Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/demos/outbox-disposition.log
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Script started on 2026-11-13 14:10:21-05:00 [COMMAND="python3 scripts/demo-outbox-disposition.py" <not executed on terminal>]
Synthetic fixture: same old firing; deliver_pending at t=10; fresh control at t=20. base
{"mode": "base", "obsolete_attempts": 1, "obsolete_received": true, "sent": ["old-event", "fresh-event"], "fresh_control_received": true}
Synthetic fixture: same old firing; deliver_pending at t=10; fresh control at t=20. expired
{"mode": "expired", "obsolete_attempts": 0, "obsolete_received": false, "sent": ["fresh-event"], "fresh_control_received": true}

Script done on 2026-11-13 14:10:21-05:00 [COMMAND_EXIT_CODE="0"]
28 changes: 28 additions & 0 deletions docs/demos/outbox-disposition.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Outbox expiry demonstration

This terminal recording uses disposable synthetic SQLite state and the real
`deliver_pending` implementation. An obsolete firing delivers on base
`64e484528d1b7f6955dbdff01e9d4e2c2a367464`; after its explicit disposition on
implementation `7650ae4`, it remains undelivered with zero attempts. A fresh event
still delivers on both revisions. No sink network, deployment or private state
participates; the sink is an in-process receipt fixture.

[Readable transcript](outbox-disposition.log) and
[timing file](outbox-disposition.timing) are retained with this source as a small
review artifact. Replay after downloading both files:

```sh
scriptreplay --log-out outbox-disposition.log --log-timing outbox-disposition.timing
```

Playback was verified with util-linux `scriptreplay`; no inline video embed is
claimed. Reproduce from the implementation checkout, with a separate export of
the exact base:

```sh
DEMO_BASE_SOURCE=/path/to/base python3 scripts/demo-outbox-disposition.py
```

Later commits adding this recording and caption do not change the demonstrated
implementation. This source fixture demonstrates delivery behavior, not installed
acceptance or representative backlog rehearsal.
4 changes: 4 additions & 0 deletions docs/demos/outbox-disposition.timing
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
0.017207 90
0.171376 139
0.018143 93
0.134688 130
59 changes: 59 additions & 0 deletions docs/outbox-disposition.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Expire retained firings without delivery

`chaski-outbox-disposition` (also `python emitter.py`) supports an explicit,
reviewed, append-only `expired-not-delivered` disposition. Original outbox rows,
payloads, attempts, receiver bindings, delivery timestamps and cursors remain
unchanged. A disposition is not a receiver receipt or acknowledgement. Recoveries
require separate adjudication and cannot use this command.

Create a private plan from an existing database with `plan --db INBOX --plan PLAN
--emitter LABEL --created-before UNIX_SECONDS --expected-count COUNT --reason
REASON --ruling-ref REFERENCE`. This opens SQLite read-only and holds a consistent
read transaction. The plan records every exact event ID and full-row hash, scope,
cutoff, count, reason, ruling reference and source UTC. It contains no event
payloads, but its identities may still be private. The command writes an exclusive
0600 plan file and prints its SHA256. Review that exact file and hash through the
normal deployment process; a free-text ruling reference does not authenticate or
authorize the caller.

Only after the consumer is quiesced and the deployment's hold-release admission
is recorded, run `apply --db INBOX --cursor CURSOR --plan PLAN
--expected-plan-sha256 HASH`. This takes the same exclusive cursor/inbox lease as
the consumer and appends in one SQLite transaction. Every selected row must still
be undelivered, never attempted, unbound and not recovery-queued; the exact scoped
population and every full-row hash must match. Changes, duplicates, foreign scope,
recovery payloads and conflicting prior decisions refuse the whole append.
Replaying the identical plan is idempotent. No sink or network call occurs.

New plans select only work without a prior disposition, so later cohorts can be
expired without selecting the originals retained by an earlier plan. Validation
includes receipts belonging to the exact plan being replayed; receipts from
other plans remain excluded. Both original plans can be replayed without changing
their receipts, while a changed decision for an already-disposed identity still
refuses. Newly eligible rows outside the reviewed population still refuse apply.

`list --db INBOX` lists retained receipts (up to 10,000; a larger population
refuses). `verify --db INBOX` checks original row hashes and eligibility read-only.
Startup verifies the same contract; missing or changed originals refuse startup.
The runtime fences by event identity even if a row drifts after startup, so a
changed fingerprint never silently releases it. Delivery, receiver setup,
receiver binding, write-budget scheduling, wakeups, renewal and recovery selection
honor this fence. Pending/oldest-pending metrics exclude disposed rows;
`chaski_emitter_outbox_disposed_total` reports them separately. Delivered metrics
continue to count only actual delivery receipts. Supported key migration refuses
to rename an identity with a disposition.

## Rollback and custody

An older consumer that does not understand this ledger can send retained rows
again. Neither installing the ledger alone nor restoring such a binary is a safe
rollback. Keep the delivery hold asserted while preparing the ledger and moving
to the expiry-aware consumer. Before releasing the hold, rehearse the same source
revision and name either an expiry-aware rollback target or the explicit operation
that re-asserts the hold before any older consumer starts. The CLI's lease prevents
an overlapping cooperating consumer; it cannot confer this operational admission
or control a legacy process that ignores custody.

Never erase originals, mark them delivered, reset a cursor, forge a historical
receiver binding, or disable the ledger to manufacture a clean queue. New events
outside the exact plan retain the normal delivery contract.
Loading
Loading