deliveries

Sends and handoffs, UNIQUE(target, scope, idempotency)

What you'll learn

You're writing SQL that reads deliveries and need its columns, what each holds, and the DDL as the spec states it.

  • every column and its type
  • what the object holds and who writes it
  • the DDL as the spec states it

A table. Sends and handoffs, UNIQUE(target, scope, idempotency) — scope is the resolved idempotency_scope config value (ADR-044, '' = unscoped); status accepted|confirmed|contradicted|sent; variables_hash drives redeliver: on_change (ADR-045)

Columns

ColumnTypeConstraints
idTEXTPRIMARY KEY
identity_idTEXTNOT NULL
targetTEXTNOT NULL
scopeTEXTNOT NULL DEFAULT ''
idempotencyTEXTNOT NULL
run_idTEXTNOT NULL
created_atTEXTNOT NULL
statusTEXTNOT NULL DEFAULT 'accepted'
sent_atTEXT
variables_hashTEXTNOT NULL DEFAULT ''

Table constraints: UNIQUE(target, scope, idempotency).

Definition

From spec/ledger.sql, which is the machine-checkable form of SPEC.md §3:

CREATE TABLE deliveries (
  id             TEXT PRIMARY KEY,
  identity_id    TEXT NOT NULL,
  target         TEXT NOT NULL,           -- adapter id, or group:<name> for a handoff (ADR-032)
  scope          TEXT NOT NULL DEFAULT '', -- the destination's stable identifier: the idempotency_scope config value (ADR-044, ADR-062); '' = unscoped
  idempotency    TEXT NOT NULL,           -- computed key, see §8 deliver
  run_id         TEXT NOT NULL,
  created_at     TEXT NOT NULL,
  status         TEXT NOT NULL DEFAULT 'accepted',  -- accepted|confirmed|contradicted|sent (ADR-036)|unconfirmed (ADR-060: in flight at a crash; held)|settled (ADR-064: held, then found at the target by the operator)
  sent_at        TEXT,                    -- set only by attestation (ADR-036)
  variables_hash TEXT NOT NULL DEFAULT '', -- resolved variables at delivery (ADR-045); drives redeliver: on_change
  UNIQUE(target, scope, idempotency)
);

Used in

  • Top up
  • Iterate: The target, scope, and key each delivery row carries
  • Recover: The table a deliver step checks before it sends, where a held record's row says unconfirmed
  • Segment: Every delivery row, with the target and scope a slice can narrow on
  • Run on cron and events