From 49b6f708da397fd35f4dac0cce3b0fffa8e71c84 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 04:35:43 +1000 Subject: [PATCH] fix(eda): wire playbook dispatch ledger and validate its key --- CLAUDE.md | 2 +- docs/prds/state-store-contract.md | 5 +- internal/app/archied/state_store.go | 3 ++ internal/app/archied/state_store_test.go | 29 +++++++++++ internal/domain/eda/playbook/coordinator.go | 17 +++++-- .../domain/eda/playbook/coordinator_test.go | 48 +++++++++++++------ internal/domain/eda/playbook/playbook.go | 7 ++- .../domain/storecontract/storecontract.go | 8 ++-- .../staterpc/conformance_test.go | 6 +++ internal/store/playbook_dispatches_test.go | 26 ++++++++++ 10 files changed, 127 insertions(+), 24 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5255e6be1..a0e16e8c1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -207,7 +207,7 @@ structures found in legacy packages. changing this package or its callers. - The proto (`proto/state/v1/state.proto`, service `StateStoreService`, package `statev1` in `internal/contracts/state/v1/`) is one gRPC service - fronting every ratified store contract (48 RPCs, including grant management + fronting every ratified store contract (59 RPCs, including grant management and deprecated compatibility RPCs); the Go consumer facades stay narrow (`workflow.Store`, `store.TaskStore`, etc., all ≤8 methods except the `TaskStore` composite) via `staterpc.Client`'s multiple `var _` diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index 2ea729d8f..2a6688fc6 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -253,12 +253,13 @@ Methods are named after the store methods so the mapping is unambiguous. `workfl | Mapping | `InsertMapping`, `GetMapping`, `ListMappings`, `UpdateMapping`, `DeleteMapping` | | Binding | `InsertBinding`, `GetBinding`, `ListBindings`, `UpdateBinding`, `DeleteBinding`, `ApproveBinding` | | Dispatch | `ArmedBindingsForSource`, `RecordDispatch`, `ListUndispatchedCaptures` | +| Playbook | `RecordPlaybookDispatch`, `DeletePlaybookDispatches` | | BindingTaskCreator | `EnqueueBindingTask` | | Config snapshot | `PutConfigSnapshot`, `GetConfigSnapshot` | | Apply status | `PutApplyStatus`, `ListApplyStatus` | | Task log | `ReadTaskLog`, `StreamTaskLogContent` | -That is **47 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped). +That is **49 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped). `Close()` is **excluded** from the wire (it is server lifecycle, not a client call) — see §11. The config-snapshot pair was added by `archie-core-ymut` (see @@ -664,7 +665,7 @@ an explicit operator decision. (`workflow.Store` + `workflow.Task`/`Status`/`Source`, per dependency rules #2 and #7); daemon/webui store surfaces stay **producer-owned** in `internal/store`. `store.WorkflowStore` is superseded by `workflow.Store`. -- **One `StateStore` gRPC service** (47 contract RPCs, grouped by contract) + narrow Go consumer facades +- **One `StateStore` gRPC service** (49 contract RPCs, grouped by contract) + narrow Go consumer facades (≤8) on `staterpc.Client` — mirrors the single-`ChatService` precedent. - **Domain type relocation** (`Task`/`Status`/`Source` → `internal/domain/workflow`) is a Phase 2 prerequisite, pulled forward from migration-decisions §4 (minimal bound, diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 87808ff1b..c206353e8 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -350,6 +350,9 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps { if bd, ok := b.st.(storecontract.BindingDispatcher); ok { deps.BindingDispatcher = bd } + if pd, ok := b.st.(storecontract.PlaybookDispatcher); ok { + deps.PlaybookDispatcher = pd + } if btc, ok := b.st.(storecontract.BindingTaskCreator); ok { deps.BindingTaskCreator = btc } diff --git a/internal/app/archied/state_store_test.go b/internal/app/archied/state_store_test.go index be8e9d9b6..0d27bcbc7 100644 --- a/internal/app/archied/state_store_test.go +++ b/internal/app/archied/state_store_test.go @@ -129,6 +129,35 @@ func TestStateStoreDepsServeTaskLogs(t *testing.T) { } } +// TestStateStoreDepsServePlaybookDispatcher proves the standalone State Store +// process fronts the playbook dispatch ledger: the two playbook RPCs answer +// codes.Unavailable for every call unless stateStoreDeps lifts the opened +// *store.Store's PlaybookDispatcher surface onto Deps. This is the only +// production server for that surface, so without this wiring the idempotency +// ledger is unreachable. +func TestStateStoreDepsServePlaybookDispatcher(t *testing.T) { + st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.sqlite")) + if err != nil { + t.Fatalf("open temp store: %v", err) + } + defer st.Close() + + b := newBootstrap() + b.st = st + deps := b.stateStoreDeps(&staterpc.TaskGrants{}) + if deps.PlaybookDispatcher == nil { + t.Fatal("stateStoreDeps leaves PlaybookDispatcher nil; the standalone State Store is the only production server for the playbook dispatch ledger") + } + if deps.PlaybookDispatcher != storecontract.PlaybookDispatcher(st) { + t.Fatalf("PlaybookDispatcher = %T, want the opened *store.Store", deps.PlaybookDispatcher) + } + // A boot without a store must not fabricate one: nil keeps the RPCs honest + // as unavailable rather than depending on a nil receiver. + if plain := (&boot{}).stateStoreDeps(&staterpc.TaskGrants{}); plain.PlaybookDispatcher != nil { + t.Errorf("PlaybookDispatcher = %T with no store on the boot, want nil so the RPCs report unavailability", plain.PlaybookDispatcher) + } +} + // TestStateStoreDataSurvivesRestart is the .4.7 restart/recovery check: a // task written by one archie-state-store process must still be there for a // fresh process opening the same archie.db path, proving b.openStateStore diff --git a/internal/domain/eda/playbook/coordinator.go b/internal/domain/eda/playbook/coordinator.go index 448d7c0b9..8d1ed78e9 100644 --- a/internal/domain/eda/playbook/coordinator.go +++ b/internal/domain/eda/playbook/coordinator.go @@ -3,7 +3,9 @@ package playbook import ( "context" "errors" + "fmt" "log/slog" + "strconv" "github.com/samcharles93/archie-core/internal/domain/storecontract" ) @@ -14,12 +16,21 @@ import ( // structural key) skips without repeating a non-revocable side effect // (docs/prds/eda-playbook-engine.md gap 2). The structural key is computed // from Decision.PlaybookID, Decision.Version, input.TaskID (the event_id) and -// Decision.ActionID, falling back to the 1-based action position ("1") when -// the action declares no id -- it is never a CEL expression. +// Decision.ActionID; when the action declares no id the 1-based +// Decision.ActionPosition is used instead -- it is never a CEL expression. A +// key with an empty component (or no fallback position) is rejected before +// the ledger write rather than recorded as a degenerate row that collapses +// distinct events onto one key. func InvokeOnce(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, decision Decision, input DispatchInput, fn func(context.Context) error) error { + if decision.ActionID == "" && decision.ActionPosition < 1 { + return fmt.Errorf("playbook action has no id and no 1-based position (playbook_id=%q)", decision.PlaybookID) + } actionID := decision.ActionID if actionID == "" { - actionID = "1" + actionID = strconv.Itoa(decision.ActionPosition) + } + if decision.PlaybookID == "" || decision.Version == "" || input.TaskID == "" || actionID == "" { + return fmt.Errorf("playbook dispatch key has an empty component (playbook_id=%q, version=%q, event_id=%q, action_id=%q)", decision.PlaybookID, decision.Version, input.TaskID, actionID) } err := ledger.RecordPlaybookDispatch(ctx, decision.PlaybookID, decision.Version, input.TaskID, actionID) if err != nil { diff --git a/internal/domain/eda/playbook/coordinator_test.go b/internal/domain/eda/playbook/coordinator_test.go index b79f08682..18cb91c73 100644 --- a/internal/domain/eda/playbook/coordinator_test.go +++ b/internal/domain/eda/playbook/coordinator_test.go @@ -37,14 +37,6 @@ func (f *fakePlaybookLedger) DeletePlaybookDispatches(ctx context.Context, playb return nil } -func discardLogger() *slog.Logger { - return slog.New(slog.NewTextHandler(&testDiscardWriter{}, nil)) -} - -type testDiscardWriter struct{} - -func (testDiscardWriter) Write(p []byte) (int, error) { return len(p), nil } - func TestInvokeOnceSkipsRedeliveredAction(t *testing.T) { ledger := &fakePlaybookLedger{} decision := Decision{PlaybookID: "pb.yaml", Version: "v1", Workflow: "notify", ActionID: "notify"} @@ -52,10 +44,11 @@ func TestInvokeOnceSkipsRedeliveredAction(t *testing.T) { calls := 0 action := func(ctx context.Context) error { calls++; return nil } - if err := InvokeOnce(t.Context(), ledger, discardLogger(), decision, input, action); err != nil { + log := slog.New(slog.DiscardHandler) + if err := InvokeOnce(t.Context(), ledger, log, decision, input, action); err != nil { t.Fatalf("first InvokeOnce: %v", err) } - if err := InvokeOnce(t.Context(), ledger, discardLogger(), decision, input, action); err != nil { + if err := InvokeOnce(t.Context(), ledger, log, decision, input, action); err != nil { t.Fatalf("second InvokeOnce: %v", err) } if calls != 1 { @@ -63,20 +56,47 @@ func TestInvokeOnceSkipsRedeliveredAction(t *testing.T) { } } -func TestInvokeOnceFallsBackToActionPosition(t *testing.T) { +func TestInvokeOnceNilLoggerOnRedelivery(t *testing.T) { ledger := &fakePlaybookLedger{} - decision := Decision{PlaybookID: "pb.yaml", Version: "v1", Workflow: "notify"} + decision := Decision{PlaybookID: "pb.yaml", Version: "v1", Workflow: "notify", ActionID: "notify"} input := DispatchInput{TaskID: "archie:acme/widget/7"} - if err := InvokeOnce(t.Context(), ledger, discardLogger(), decision, input, func(ctx context.Context) error { return nil }); err != nil { + if err := InvokeOnce(t.Context(), ledger, nil, decision, input, func(ctx context.Context) error { return nil }); err != nil { + t.Fatalf("first InvokeOnce: %v", err) + } + if err := InvokeOnce(t.Context(), ledger, nil, decision, input, func(ctx context.Context) error { return nil }); err != nil { + t.Fatalf("redelivered InvokeOnce with nil logger: %v", err) + } +} + +func TestInvokeOnceFallsBackToActionPosition(t *testing.T) { + ledger := &fakePlaybookLedger{} + decision := Decision{PlaybookID: "pb.yaml", Version: "v1", Workflow: "notify", ActionPosition: 2} + input := DispatchInput{TaskID: "archie:acme/widget/7"} + + if err := InvokeOnce(t.Context(), ledger, slog.New(slog.DiscardHandler), decision, input, func(ctx context.Context) error { return nil }); err != nil { t.Fatalf("InvokeOnce: %v", err) } if len(ledger.records) != 1 { t.Fatalf("ledger records = %d, want 1", len(ledger.records)) } got := ledger.records[0] - want := playbookRecord{playbookID: "pb.yaml", playbookVersion: "v1", eventID: "archie:acme/widget/7", actionID: "1"} + want := playbookRecord{playbookID: "pb.yaml", playbookVersion: "v1", eventID: "archie:acme/widget/7", actionID: "2"} if got != want { t.Fatalf("ledger record = %+v, want %+v (an action without an id keys on its 1-based position)", got, want) } } + +func TestInvokeOnceRejectsEmptyKeyComponent(t *testing.T) { + ledger := &fakePlaybookLedger{} + decision := Decision{PlaybookID: "pb.yaml", Version: "v1", Workflow: "notify", ActionID: "notify"} + input := DispatchInput{TaskID: ""} + + err := InvokeOnce(t.Context(), ledger, slog.New(slog.DiscardHandler), decision, input, func(ctx context.Context) error { return nil }) + if err == nil { + t.Fatal("InvokeOnce with empty event_id should error before recording") + } + if len(ledger.records) != 0 { + t.Fatalf("ledger records = %d, want 0 (validation must precede the ledger write)", len(ledger.records)) + } +} diff --git a/internal/domain/eda/playbook/playbook.go b/internal/domain/eda/playbook/playbook.go index 7f593e113..15a7a4287 100644 --- a/internal/domain/eda/playbook/playbook.go +++ b/internal/domain/eda/playbook/playbook.go @@ -349,6 +349,11 @@ type Decision struct { // declares none. It is the `actions.` key later actions (and the // dispatch ledger) read this action under. ActionID string + // ActionPosition is the 1-based index of the dispatched action in the + // playbook's actions list. It is the idempotency-key fallback when + // ActionID is empty (docs/prds/eda-playbook-engine.md, "Idempotency at + // execution time"). + ActionPosition int } // Dispatch returns the workflow name the first matching playbook selects for @@ -390,7 +395,7 @@ func (s *Store) Dispatch(input DispatchInput) (Decision, bool) { continue } } - return Decision{PlaybookID: pb.ID, Version: pb.Version, Workflow: a.Workflow, ActionID: a.ID}, true + return Decision{PlaybookID: pb.ID, Version: pb.Version, Workflow: a.Workflow, ActionID: a.ID, ActionPosition: 1}, true } return Decision{}, false } diff --git a/internal/domain/storecontract/storecontract.go b/internal/domain/storecontract/storecontract.go index ee7136f3d..083069fd3 100644 --- a/internal/domain/storecontract/storecontract.go +++ b/internal/domain/storecontract/storecontract.go @@ -179,9 +179,11 @@ type BindingTaskCreator interface { // BEFORE the action's side effect fires -- the deliberate reverse of // BindingDispatcher.RecordDispatch -- so a duplicate returns // ErrAlreadyDispatched and the caller skips the invoke rather than repeating -// a non-revocable side effect. DeletePlaybookDispatches frees one playbook's -// rows when the playbook is removed. There is deliberately no *sql.Tx: any -// transaction stays server-side inside internal/store. +// a non-revocable side effect. DeletePlaybookDispatches deletes one +// playbook's ledger rows and is the reclamation primitive for when a playbook +// is removed from the configured directory -- a removal path that does not +// exist yet and is tracked by archie-core-t2db.30. There is deliberately no +// *sql.Tx: any transaction stays server-side inside internal/store. type PlaybookDispatcher interface { RecordPlaybookDispatch(ctx context.Context, playbookID, playbookVersion, eventID, actionID string) error DeletePlaybookDispatches(ctx context.Context, playbookID string) error diff --git a/internal/infrastructure/staterpc/conformance_test.go b/internal/infrastructure/staterpc/conformance_test.go index 7e9913ac7..c0f834df7 100644 --- a/internal/infrastructure/staterpc/conformance_test.go +++ b/internal/infrastructure/staterpc/conformance_test.go @@ -350,6 +350,12 @@ func TestStateStoreConformance(t *testing.T) { if err := pc.RecordPlaybookDispatch(ctx, "pb.yaml", "v1", "archie:acme/widget/7", "notify"); err != nil { t.Fatalf("RecordPlaybookDispatch: %v", err) } + // A distinct event_id is a distinct row: the client -> proto -> + // server mapping must carry event_id rather than collapse it into + // the first tuple's key. + if err := pc.RecordPlaybookDispatch(ctx, "pb.yaml", "v1", "archie:acme/widget/8", "notify"); err != nil { + t.Fatalf("RecordPlaybookDispatch (distinct event_id) = %v, want success", err) + } err = pc.RecordPlaybookDispatch(ctx, "pb.yaml", "v1", "archie:acme/widget/7", "notify") if !errors.Is(err, store.ErrAlreadyDispatched) { t.Fatalf("RecordPlaybookDispatch dup = %v, want ErrAlreadyDispatched", err) diff --git a/internal/store/playbook_dispatches_test.go b/internal/store/playbook_dispatches_test.go index 0c7ffedfa..75b85bc41 100644 --- a/internal/store/playbook_dispatches_test.go +++ b/internal/store/playbook_dispatches_test.go @@ -17,6 +17,32 @@ func TestRecordPlaybookDispatchIsIdempotent(t *testing.T) { } } +func TestRecordPlaybookDispatchKeyIsAllFourComponents(t *testing.T) { + s := openTest(t) + ctx := t.Context() + + if err := s.RecordPlaybookDispatch(ctx, "pb", "v1", "e1", "notify"); err != nil { + t.Fatalf("record (pb, v1, e1, notify): %v", err) + } + // Every component of the PRIMARY KEY distinguishes a row: a mutant key + // missing any one of the four would collapse distinct dispatches here. + if err := s.RecordPlaybookDispatch(ctx, "pb", "v1", "e1", "build"); err != nil { + t.Fatalf("record (pb, v1, e1, build) = %v, want success (action_id is a key component)", err) + } + if err := s.RecordPlaybookDispatch(ctx, "pb", "v1", "e2", "notify"); err != nil { + t.Fatalf("record (pb, v1, e2, notify) = %v, want success (event_id is a key component)", err) + } + if err := s.RecordPlaybookDispatch(ctx, "pb", "v2", "e1", "notify"); err != nil { + t.Fatalf("record (pb, v2, e1, notify) = %v, want success (playbook_version is a key component)", err) + } + if err := s.RecordPlaybookDispatch(ctx, "pb2", "v1", "e1", "notify"); err != nil { + t.Fatalf("record (pb2, v1, e1, notify) = %v, want success (playbook_id is a key component)", err) + } + if err := s.RecordPlaybookDispatch(ctx, "pb", "v1", "e1", "notify"); !errors.Is(err, ErrAlreadyDispatched) { + t.Fatalf("re-record (pb, v1, e1, notify) = %v, want ErrAlreadyDispatched", err) + } +} + func TestDeletePlaybookDispatchesRemovesOnlyThatPlaybook(t *testing.T) { s := openTest(t) ctx := t.Context()