Consume operator cassette operations instead of counts #106

Merged

padreug merged 2 commits from feat/cassette-ops-consumer into dev

2026-09-23 21:31:08 +00:00

padreug commented

2026-09-23 21:15:22 +00:00

Owner

Phase 3 machine side: the ATM owns its bay counts and applies operator operations instead of counts.

Schema v13 adds cassette_ops, the dedup ledger. A delta applied twice is wrong and addressable events are re-delivered on every reconnect, so the operator mints an id per op and this table records what was applied. That retires the created_at watermark on this path: it was the only replay defence under absolute counts, but it drops an out-of-order event whole, where per-op ids let the unseen ops through and no-op the rest.

A window applies oldest-first by at, ties broken by id, in one transaction with the count mutation. A recount then a refill is not the same as the reverse.

A malformed op, or one naming a bay this machine does not have, is neither applied nor recorded. It stays pending on the operator's dashboard, which is the honest outcome.

The state document gains applied_ops, seq and schema_version. applied_ops is the acknowledgement leg: echoing ids back is the only way the operator can tell an op that landed from one merely sent.

ADR-004's status section is updated and decision 4a is marked superseded.

Merge AFTER aiolabs/spirekeeper#46 is deployed to ariege. Strict cutover, no compatibility code.

135 machine tests and 38 state-machine tests pass, full build clean.

Phase 3 machine side: the ATM owns its bay counts and applies operator operations instead of counts. Schema v13 adds `cassette_ops`, the dedup ledger. A delta applied twice is wrong and addressable events are re-delivered on every reconnect, so the operator mints an id per op and this table records what was applied. That retires the `created_at` watermark on this path: it was the only replay defence under absolute counts, but it drops an out-of-order event whole, where per-op ids let the unseen ops through and no-op the rest. A window applies oldest-first by `at`, ties broken by id, in one transaction with the count mutation. A recount then a refill is not the same as the reverse. A malformed op, or one naming a bay this machine does not have, is neither applied nor recorded. It stays pending on the operator's dashboard, which is the honest outcome. The state document gains `applied_ops`, `seq` and `schema_version`. `applied_ops` is the acknowledgement leg: echoing ids back is the only way the operator can tell an op that landed from one merely sent. ADR-004's status section is updated and decision 4a is marked superseded. Merge AFTER aiolabs/spirekeeper#46 is deployed to ariege. Strict cutover, no compatibility code. 135 machine tests and 38 state-machine tests pass, full build clean.

padreug added 2 commits

2026-09-23 21:15:22 +00:00

feat(cassettes): consume operator operations instead of counts c889f7f0df

The machine now owns its bay counts outright. The operator publishes what
it did — a refill in notes added, an empty, a recount, a denomination
change — and this process applies it to the total it already holds.

Both sides used to write the same value over a transport that never tells
a writer it lost. Addressable events order by created_at at second
granularity with ties broken on event id, and a relay returns OK for an
event it then discards, so a dashboard form loaded before a dispense
silently discarded that dispense and neither side could detect it. A
value with one writer cannot be clobbered.

Schema v13 adds cassette_ops, the dedup ledger. A delta applied twice is
wrong and addressable events are re-delivered on every reconnect, so the
operator mints an id per operation and this table records the ones
applied. That also retires the created_at watermark on this path: it was
the only replay defence under absolute counts, but it drops an
out-of-order event whole, operations included, where per-op ids let the
unseen ones through and no-op the rest.

A window is applied oldest-first by `at`, ties broken by id, in one
transaction with the count mutation. A recount then a refill is not the
same as the reverse, and a crash mid-apply must roll back to a coherent
count rather than a partial one.

A malformed op or one naming a bay this machine does not have is neither
applied nor recorded, so it stays pending on the operator's dashboard.
That is the honest outcome. Recording it as applied would stop the noise
by telling the operator their refill landed.

The state document gains applied_ops, seq and schema_version. applied_ops
is the acknowledgement leg — echoing the ids back is the only way the
operator can tell an operation that landed from one merely sent. seq is
bumped on every local count change from any cause, so a reader can reject
a regression without trusting either clock.

docs(adr): record that the operations wire shipped 65f5f982ec

Decisions 1 through 4 are built on both sides, so the status section says
what landed rather than what is planned, and decision 4a is marked
superseded.

4a is kept rather than deleted. It is the calibration for what a warning
dialog is worth: it depended on an operator reading it at the end of a
refill round, and it could not help at all when the stale value was
already in the form. The dialog and the endpoint behind it are both gone
now, which is a stronger guarantee than any wording could be.

Also records the one gap left open on purpose. An operation recorded
while the relay is unreachable waits for the operator's next action,
because only an operator action triggers a publish.

padreug referenced this pull request from aiolabs/spirekeeper

2026-09-23 21:15:33 +00:00

Publish cassette operations instead of counts #46

padreug referenced this pull request from a commit

2026-09-23 21:18:19 +00:00

spirekeeper v0.1.6 — cassette operations replace cassette counts

padreug merged commit 8d2509b092 into dev

2026-09-23 21:31:08 +00:00

padreug deleted branch feat/cassette-ops-consumer

2026-09-23 21:31:08 +00:00

padreug referenced this pull request from a commit

2026-09-23 21:31:08 +00:00