eda: build the playbook_dispatches idempotency ledger (unblocks side-effecting action positions) #448
Notifications
Due Date
No due date set.
Blocks
Depends on
Reference: sam/archie#448
Reference in new issue
Block a user
Found while wiring the coordinator into production intake (t2db.23).
The workflow position is now wired: a matching playbook decides a real task's
workflow at the daemon's definition pin. It inherits idempotency for free via
TaskEnvelope, so it needed no ledger.
Module/Channel/Forge positions do not. They are still rejected at load (the
t2db.15 hard boundary), and the gap-2 resolution that unblocks them
(docs/prds/eda-playbook-engine.md, "Idempotency at execution time") is
design-only: the playbook_dispatches table does not exist. Until it does,
module.ModuleRegistry.Invoke has no production caller and every reachability
audit will keep reporting it as dead code -- the same way Store.Dispatch was
reported twice before t2db.23.
Scope: the table, the domain-side dispatcher interface (same shape as
store.BindingDispatcher), INSERT OR IGNORE + ErrAlreadyDispatched sentinel,
rows deleted with their playbook, and the coordinator writing a record
immediately before an action's side effect. The decision text names the exact
files to copy the conventions from; do not redesign it.
Decision inputs already settled: per-action-per-event granularity, no
time-based expiry, skip-and-continue on redelivery, and the
(playbook_id, playbook_version, event_id, action_id) key. Playbook.ID/Version
(t2db.21) and DispatchInput.TaskID already exist, and Store.Dispatch now
returns them on its Decision.
Design
CROSS-PROCESS REALITY (missing from the original brief; verified 2026-09-21
against the tree). The State Store is a standalone process that exclusively
owns the task DB. The playbook coordinator runs in archied. So this ledger is
NOT a local store method: every part of binding_dispatches it copies is
already a full gRPC round trip, and the new one must be too.
Sites, all of which binding_dispatches already occupies:
is absolute -- never add a Go interface method without a matching RPC.
golangci-lint) formats generated protobuf contracts.
the worked example of the shape.
mapError/unmapError, matched on (code, EXACT canonical message).
ErrAlreadyDispatched does this at values.go's two switch arms. Changing a
canonical message string breaks errors.Is on the client with no visible
behaviour change, so treat the message constant as wire contract.
playbook's rows with the playbook.
interface, shaped like storecontract.BindingDispatcher.
Two traps carried from .4.2:
parameter precisely because it cannot cross a gRPC boundary; production
always passed nil. Deleting a playbook's rows transactionally is fine, but
that transaction stays server-side inside internal/store.
Update/Transition/InsertEvent. A new RPC therefore requires the
administrative token, which the daemon holds. Do not wire it to a
task-scoped path.
SCOPED GATE COMMAND
go test ./internal/store/... ./internal/infrastructure/staterpc/...
./internal/domain/eda/... -count=1
&& go vet ./internal/store/... ./internal/infrastructure/staterpc/... ./internal/domain/eda/...
Proto changes also shift generated assets, which are LAW: include the
regenerated contracts in the same commit.
OVERLAP: touches internal/domain/eda/playbook, as does .25. Do not run both in
one wave without deciding who owns that package's loader.
Acceptance criteria
A playbook_dispatches ledger exists in internal/store behind a domain-side interface, the coordinator records an action before invoking it, a redelivered event skips the recorded action without an error, and the rows are deleted with their playbook. No action position is unblocked by this ticket alone.
Close reason
Shipped. playbook_dispatches ledger complete end-to-end: proto RPCs RecordPlaybookDispatch + DeletePlaybookDispatches, storecontract.PlaybookDispatcher (no sql.Tx; reuses ErrAlreadyDispatched, values.go untouched), postgres edastore implementation, staterpc client/server, and coordinator.go InvokeOnce (structural key from Decision, action-position fallback). Verified: go test ./internal/domain/eda/... (TestInvokeOnce all pass) and the staterpc/postgres conformance suites. The production call site arrived with .31 (run.go).
Imported from beads
archie-core-t2db.24· GitHub #1137 · type task · priority P2 · created 2026-09-21 · closed 2026-09-29