eda: build the playbook_dispatches idempotency ledger (unblocks side-effecting action positions) #448

Closed
opened 2026-10-27 13:36:22 +00:00 by sam · 0 comments
Owner

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:

  • proto/state/v1/state.proto: a new RPC on StateStoreService. CLAUDE.md's rule
    is absolute -- never add a Go interface method without a matching RPC.
  • internal/contracts/state/v1/: regenerate. gofumpt (standalone, not
    golangci-lint) formats generated protobuf contracts.
  • internal/infrastructure/staterpc/client.go and server.go: RecordDispatch is
    the worked example of the shape.
  • internal/infrastructure/staterpc/values.go: the new sentinel crosses via
    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.
  • internal/store: the table, the INSERT OR IGNORE write, and deletion of a
    playbook's rows with the playbook.
  • internal/domain/eda/playbook or a sibling: the domain-side consumer
    interface, shaped like storecontract.BindingDispatcher.

Two traps carried from .4.2:

  • The interface method must NOT take a *sql.Tx. RecordDispatch dropped its tx
    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.
  • staterpc.TaskGrants.UnaryInterceptor authorizes a task-scoped token for only
    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

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: - proto/state/v1/state.proto: a new RPC on StateStoreService. CLAUDE.md's rule is absolute -- never add a Go interface method without a matching RPC. - internal/contracts/state/v1/: regenerate. gofumpt (standalone, not golangci-lint) formats generated protobuf contracts. - internal/infrastructure/staterpc/client.go and server.go: RecordDispatch is the worked example of the shape. - internal/infrastructure/staterpc/values.go: the new sentinel crosses via 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. - internal/store: the table, the INSERT OR IGNORE write, and deletion of a playbook's rows with the playbook. - internal/domain/eda/playbook or a sibling: the domain-side consumer interface, shaped like storecontract.BindingDispatcher. Two traps carried from .4.2: - The interface method must NOT take a *sql.Tx. RecordDispatch dropped its tx 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. - staterpc.TaskGrants.UnaryInterceptor authorizes a task-scoped token for only 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_
sam added the mediumtask labels 2026-10-27 13:36:22 +00:00
sam self-assigned this 2026-10-27 13:36:22 +00:00
sam closed this issue 2026-10-27 13:36:22 +00:00
sam added a new dependency 2026-10-27 13:42:03 +00:00
sam added a new dependency 2026-10-27 13:42:03 +00:00
sam added a new dependency 2026-10-27 13:42:04 +00:00
sam added a new dependency 2026-10-27 13:42:04 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#448