step_events

per-record trail

What you'll learn

You're writing SQL that reads step_events 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. per-record trail: claimed|done|failed|skipped_cache|dry_run|simulated, detail JSON.

Columns

ColumnTypeConstraints
idTEXTPRIMARY KEY
run_idTEXTNOT NULL
step_idTEXTNOT NULL
identity_idTEXT
eventTEXTNOT NULL
detailTEXT
created_atTEXTNOT NULL

Definition

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

CREATE TABLE step_events (
  id          TEXT PRIMARY KEY,           -- ULID
  run_id      TEXT NOT NULL,
  step_id     TEXT NOT NULL,
  identity_id TEXT,                       -- null for step-level events
  event       TEXT NOT NULL,              -- claimed|dispatched (ADR-060: a deliver's send is about to leave)|done|failed|skipped_cache|gated (ADR-064: held back by when: or a membership gate)|settled (ADR-064: a held delivery the operator found at the target)|pending|collected (ADR-038)|answered (ADR-049: a participant's answer awaiting collection)
  detail      TEXT,                       -- JSON
  created_at  TEXT NOT NULL
);

Used in

  • Report: One row per record per step event, which the receipt's counts are
  • Top up
  • Iterate: The events and details the reuse queries read, including the judgment signature
  • Traverse a relation: Where the traversed and coalesced events for each child are logged