feat(eda): run action playbooks at pin time through the at-most-once dispatch ledger

This commit is contained in:
sam committed 2026-09-23 22:00:52 +10:00
1 parent 6046948ff0
commit 2bc4b8db32
11 files changed
+517 -95

No files matched your search

+1 -1
View File
@@ -298,7 +298,7 @@
"url": "/dev/prds/multi-action-playbooks/",
"title": "Multi-action playbooks and typed action results",
"section": "PRDs",
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define. Arg VALUE type-checking\n is tracked as `archie-core-t2db` debt, not shipped here.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo a load failure; arg value\ntype-checking is tracked as `archie-core-t2db` debt.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check. It\ndoes not invoke a Module kind. Invocation, the `playbook_dispatches` gate, and\nstop-on-first-failure across actions are `archie-core-t2db.31`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Settled: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a rLine truncated
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define. Arg VALUE type-checking\n is tracked as `archie-core-t2db` debt, not shipped here.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo a load failure; arg value\ntype-checking is tracked as `archie-core-t2db` debt.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a result, so it cannot feed `actions.\u0Line truncated
},
{
"url": "/dev/prds/news-and-releases/",
+83
View File
@@ -0,0 +1,83 @@
# Running action playbooks
**Status:** Approved
**Date:** 2026-09-23
**Parent:** `docs/prds/multi-action-playbooks.md`, epic `archie-core-t2db`
**Beads issue:** `archie-core-t2db.31`
## Why this exists
An action playbook loads and type-checks but never runs: `Store.Dispatch`
skips it and the daemon logs a warning at boot (`multi-action-playbooks.md`,
D1). This document defines when it runs, what each action does, and how the
`playbook_dispatches` ledger gates it.
## When a playbook runs
The daemon runs action playbooks at the point it pins a task's workflow
definition (`Daemon.resolveWorkflowID`), using the same `DispatchInput` the
workflow playbooks use. The definition is pinned once per task, so the run
happens once per task.
- Every action playbook whose trigger matches runs, in load order. A workflow
playbook stops at the first match because it chooses one workflow; action
playbooks choose nothing, so no match suppresses another.
- A run never changes routing. The task is pinned by the workflow playbooks
and bindings exactly as when no action playbook exists.
- An action or playbook failure never parks or fails the task. It is logged
at warning level with the playbook, the action and the task.
- A task that already names a workflow (the approval requeue) is skipped, as
it is for workflow playbooks.
- Actions run synchronously in the pin path, bounded by the daemon's context.
The only Module kind, `log`, returns immediately. A slow kind must bring its
own timeout.
## What one action does
Actions run in order against one evaluation context whose `actions` map
starts empty.
1. Evaluate `when`. False or an evaluation error skips the action (J3). A
skipped action records nothing and produces no result.
2. Evaluate every `args` value. An evaluation error stops the playbook.
3. Call `playbook.InvokeOnce` with the Module invoke as its function. The
ledger row is written first. A duplicate row skips the invoke.
4. An invoke error stops the playbook. The row stays, so the action is not
retried: the ledger promises at most once, not at least once.
5. On success, `ModuleRegistry.DecodeResult` converts the result, and it is
stored as `actions.<id>.result` when the action declares an id.
The event id in the ledger key is `DispatchInput.TaskID`, the issue's
idempotency key (`owner/repo/number`). An action therefore runs at most once
per issue for each playbook version. Editing a playbook changes its version
and lets it run again for issues it already handled.
A skipped duplicate has no result. A later action that reads it sees a
missing field: its `when` evaluates false, or its args fail and the playbook
stops. This only happens when the same issue is pinned twice under one
playbook version.
## Wiring
- `storecontract.PlaybookDispatcher` is lifted onto the daemon from the State
Store client in `internal/app/archied/bootstrap.go`, the same way
`BindingDispatcher` is.
- The daemon's `Playbooks` dependency gains the run method. The Module
registry is passed to the playbook store at load, so the daemon needs no
new dependency for it.
- With no `PlaybookDispatcher` wired, action playbooks do not run, and the
boot warning names each one. They never run without the ledger.
- The boot warning that action playbooks do not execute is removed when the
ledger is wired.
## Verification
- A matching two-action `log` playbook runs both actions in order, and the
second reads the first's result.
- Pinning the same task twice under one playbook version invokes each action
once.
- A `when` that evaluates false skips that action and the run continues.
- An invoke error stops the playbook. The task is still pinned to the same
workflow it would get with no action playbook.
- A non-matching trigger runs nothing.
- With no ledger wired, nothing runs and the warning names the playbook.
+4 -4
View File
@@ -92,13 +92,13 @@ of the `actions` object typed by its kind's `Result`.
## Running an action playbook is out of scope
This document makes an action playbook load and its references type-check. It
does not invoke a Module kind. Invocation, the `playbook_dispatches` gate, and
stop-on-first-failure across actions are `archie-core-t2db.31`.
This document makes an action playbook load and its references type-check.
Running one is designed in `docs/prds/action-playbook-run.md`.
## Decisions
**D1 — dispatch before `t2db.31`.** Settled: an action playbook loads and
**D1 — dispatch before `t2db.31`.** Superseded by
`docs/prds/action-playbook-run.md`. Was: an action playbook loads and
validates but is not routed; the definition-pin dispatch reports no match for it,
and the daemon logs a visible warning naming it.
+18 -8
View File
@@ -774,9 +774,8 @@ func (b *boot) loadModules(cfg config.Config, log *slog.Logger) error {
// rule -- any malformed playbook, mixed/unsupported action shape, unknown
// module kind, when compile failure, or args key failure aborts startup,
// matching the routing-file load pattern (not degrade-and-skip). A nonexistent
// dir is an empty store. Action playbooks load and type-check but have no run
// path yet (t2db.31), so each one is logged as a visible warning here rather
// than routed by the definition pin.
// dir is an empty store. Action playbooks run through the daemon once
// buildDaemon wires the dispatch ledger (docs/prds/action-playbook-run.md).
func (b *boot) loadEDAPlaybooks(cfg config.Config, log *slog.Logger) error {
var err error
b.playbooks, err = playbook.Load(cfg.EDAPlaybookDir, b.modules)
@@ -784,11 +783,6 @@ func (b *boot) loadEDAPlaybooks(cfg config.Config, log *slog.Logger) error {
log.Error("eda playbook load failed", "dir", cfg.EDAPlaybookDir, "err", err)
return err
}
for _, pb := range b.playbooks.Playbooks {
if pb.IsActionPlaybook() {
log.Warn("eda action playbook loaded: action playbooks do not execute yet", "playbook", pb.ID)
}
}
log.Info("eda playbooks loaded", "dir", cfg.EDAPlaybookDir, "playbooks", len(b.playbooks.Playbooks))
return nil
}
@@ -1326,9 +1320,25 @@ func (b *boot) buildDaemon() {
if btc, ok := b.stateStore.(storecontract.BindingTaskCreator); ok {
b.d.BindingTaskCreator = btc
}
b.d.PlaybookLedger = playbookLedger(b.stateStore, b.playbooks, b.log)
b.setupForgeWebhook()
}
// playbookLedger returns source's dispatch ledger, or nil with a warning
// naming each action playbook that therefore will not run: an action playbook
// never fires without its at-most-once gate.
func playbookLedger(source any, playbooks *playbook.Store, log *slog.Logger) storecontract.PlaybookDispatcher {
if pd, ok := source.(storecontract.PlaybookDispatcher); ok {
return pd
}
for _, pb := range playbooks.Playbooks {
if pb.IsActionPlaybook() {
log.Warn("eda action playbook will not run: no dispatch ledger is wired", "playbook", pb.ID)
}
}
return nil
}
// setupForgeWebhook starts the forge webhook receiver when intake is "webhook"
// or "both". It decodes GitHub issue events into task envelopes and publishes
// them through the same path the poller uses, so a labelled or assigned issue
+50 -55
View File
@@ -2,6 +2,7 @@ package archied
import (
"bytes"
"context"
"log/slog"
"os"
"path/filepath"
@@ -10,71 +11,65 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
"github.com/samcharles93/archie-core/internal/domain/eda/playbook"
)
// TestLoadEDAPlaybooksWarnsOnActionPlaybook pins the D1 visible warning: an
// action playbook loads and validates but has no run path yet, so the daemon
// logs a warning (not debug) naming it and stating plainly that action
// playbooks do not execute yet -- rather than silently loading a playbook that
// can never be routed.
func TestLoadEDAPlaybooksWarnsOnActionPlaybook(t *testing.T) {
type stubPlaybookLedger struct{}
func (stubPlaybookLedger) RecordPlaybookDispatch(context.Context, string, string, string, string) error {
return nil
}
func (stubPlaybookLedger) DeletePlaybookDispatches(context.Context, string) error { return nil }
func loadBootPlaybooks(t *testing.T, document string) *playbook.Store {
t.Helper()
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "pb.yaml"), []byte(`trigger:
if err := os.WriteFile(filepath.Join(dir, "pb.yaml"), []byte(document), 0o600); err != nil {
t.Fatal(err)
}
b := &boot{cfg: config.Config{EDAPlaybookDir: dir}, modules: module.New()}
if err := b.loadEDAPlaybooks(b.cfg, slog.New(slog.DiscardHandler)); err != nil {
t.Fatalf("loadEDAPlaybooks: %v", err)
}
return b.playbooks
}
const actionPlaybookDoc = `trigger:
kind: bug
actions:
- position: module
kind: log
args:
message: '"build started"'
`), 0o600); err != nil {
t.Fatal(err)
}
`
var buf bytes.Buffer
log := slog.New(slog.NewTextHandler(&buf, nil))
b := &boot{cfg: config.Config{EDAPlaybookDir: dir}, modules: module.New()}
if err := b.loadEDAPlaybooks(b.cfg, log); err != nil {
t.Fatalf("loadEDAPlaybooks: %v", err)
// An action playbook never runs without the dispatch ledger, and the
// operator is told which ones are inert rather than finding out by silence.
func TestPlaybookLedger(t *testing.T) {
tests := []struct {
name string
source any
document string
wantLedger bool
wantWarn bool
}{
{name: "ledger wired", source: stubPlaybookLedger{}, document: actionPlaybookDoc, wantLedger: true},
{name: "no ledger warns per action playbook", source: struct{}{}, document: actionPlaybookDoc, wantWarn: true},
{name: "no ledger, workflow playbook only", source: struct{}{}, document: "trigger:\n kind: bug\nactions:\n - position: workflow\n workflow: tdd\n"},
}
out := buf.String()
if !strings.Contains(out, "pb.yaml") {
t.Errorf("warning output does not name the action playbook: %q", out)
}
if !strings.Contains(out, "do not execute yet") {
t.Errorf("warning output does not state action playbooks do not execute yet: %q", out)
}
if strings.Contains(out, "level=DEBUG") {
t.Errorf("warning output was logged at debug, want a visible warning: %q", out)
}
}
// TestLoadEDAPlaybooksNoWarningOnWorkflowPlaybook is the inverse of the D1
// warning: a workflow playbook uses the same two-shape predicate but must not
// be logged as a non-routing action playbook.
func TestLoadEDAPlaybooksNoWarningOnWorkflowPlaybook(t *testing.T) {
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "pb.yaml"), []byte(`trigger:
kind: bug
actions:
- position: workflow
workflow: tdd
`), 0o600); err != nil {
t.Fatal(err)
}
var buf bytes.Buffer
log := slog.New(slog.NewTextHandler(&buf, nil))
b := &boot{cfg: config.Config{EDAPlaybookDir: dir}, modules: module.New()}
if err := b.loadEDAPlaybooks(b.cfg, log); err != nil {
t.Fatalf("loadEDAPlaybooks: %v", err)
}
out := buf.String()
if strings.Contains(out, "do not execute yet") {
t.Errorf("workflow playbook was warned as an action playbook: %q", out)
}
if strings.Contains(out, "level=WARN") {
t.Errorf("workflow playbook produced a warning: %q", out)
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
var buf bytes.Buffer
got := playbookLedger(tt.source, loadBootPlaybooks(t, tt.document), slog.New(slog.NewTextHandler(&buf, nil)))
if (got != nil) != tt.wantLedger {
t.Fatalf("ledger = %v, want wired=%v", got, tt.wantLedger)
}
out := buf.String()
warned := strings.Contains(out, "level=WARN") && strings.Contains(out, "pb.yaml") && strings.Contains(out, "will not run")
if warned != tt.wantWarn {
t.Fatalf("warning output = %q, want warned=%v", out, tt.wantWarn)
}
})
}
}
+19
View File
@@ -220,7 +220,11 @@ type Daemon struct {
// and routing is exactly the binding behaviour.
Playbooks interface {
Dispatch(playbook.DispatchInput) (playbook.Decision, bool)
Run(context.Context, storecontract.PlaybookDispatcher, *slog.Logger, playbook.DispatchInput) error
}
// PlaybookLedger is the at-most-once gate action playbooks run through.
// Nil means action playbooks do not run: they never fire unguarded.
PlaybookLedger storecontract.PlaybookDispatcher
// WorkflowDefinitions supplies the active database definitions. A task is
// pinned once before dispatch; retries reuse the task's stored YAML.
@@ -1552,6 +1556,7 @@ func (d *Daemon) pinWorkflowDefinition(ctx context.Context, task *workflow.Task)
}
return nil
}
d.runActionPlaybooks(ctx, task)
if d.WorkflowDefinitions == nil {
return d.pinWorkflowFromCollection(ctx, task, workflow.ShippedDefinitions(), 0)
}
@@ -1562,6 +1567,20 @@ func (d *Daemon) pinWorkflowDefinition(ctx context.Context, task *workflow.Task)
return d.pinWorkflowFromCollection(ctx, task, collection, version)
}
// runActionPlaybooks runs the action playbooks matching a task that is about
// to be pinned, which happens once per task (docs/prds/action-playbook-run.md).
// A run never affects routing and its failure never fails the task. A task
// that already names a workflow is the approval requeue and is skipped, as
// it is for workflow playbooks.
func (d *Daemon) runActionPlaybooks(ctx context.Context, task *workflow.Task) {
if d.Playbooks == nil || d.PlaybookLedger == nil || task.Workflow != "" {
return
}
if err := d.Playbooks.Run(ctx, d.PlaybookLedger, d.Log, playbookInput(task)); err != nil {
d.Log.Warn("action playbook run failed", "task", task.ID, "err", err)
}
}
// resolveWorkflowID picks the definition id to pin. A playbook whose trigger
// matches the task decides, ahead of the kind/label bindings; anything else
// falls through to workflow.ResolveWorkflowID unchanged.
+80
View File
@@ -0,0 +1,80 @@
package daemon
import (
"context"
"errors"
"log/slog"
"testing"
"github.com/samcharles93/archie-core/internal/domain/eda/playbook"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/store"
)
// runRecorder is a playbook set that matches no workflow playbook and records
// each action-playbook run, failing it when err is set.
type runRecorder struct {
runs []playbook.DispatchInput
err error
}
func (r *runRecorder) Dispatch(playbook.DispatchInput) (playbook.Decision, bool) {
return playbook.Decision{}, false
}
func (r *runRecorder) Run(_ context.Context, _ storecontract.PlaybookDispatcher, _ *slog.Logger, input playbook.DispatchInput) error {
r.runs = append(r.runs, input)
return r.err
}
type nopPlaybookLedger struct{}
func (nopPlaybookLedger) RecordPlaybookDispatch(context.Context, string, string, string, string) error {
return nil
}
func (nopPlaybookLedger) DeletePlaybookDispatches(context.Context, string) error { return nil }
func TestPinWorkflowDefinitionRunsActionPlaybooks(t *testing.T) {
tests := []struct {
name string
ledger storecontract.PlaybookDispatcher
workflow string
runErr error
wantRuns int
}{
{name: "runs once with a ledger", ledger: nopPlaybookLedger{}, wantRuns: 1},
{name: "a failed run leaves routing alone", ledger: nopPlaybookLedger{}, runErr: errors.New("boom"), wantRuns: 1},
{name: "never runs without a ledger", wantRuns: 0},
{name: "skips a task that already names a workflow", ledger: nopPlaybookLedger{}, workflow: "tdd", wantRuns: 0},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
resources := store.OpenTest(t)
defer resources.Close()
task := forgeTask(t, resources, "bug")
task.Workflow = tt.workflow
recorder := &runRecorder{err: tt.runErr}
d := &Daemon{
Store: resources,
WorkflowDefinitions: routableDefinitions(),
Log: slog.New(slog.DiscardHandler),
Playbooks: recorder,
PlaybookLedger: tt.ledger,
}
if err := d.pinWorkflowDefinition(t.Context(), task); err != nil {
t.Fatal(err)
}
// A second pin reuses the stored definition and must not run again.
if err := d.pinWorkflowDefinition(t.Context(), task); err != nil {
t.Fatal(err)
}
if len(recorder.runs) != tt.wantRuns {
t.Fatalf("runs = %d, want %d", len(recorder.runs), tt.wantRuns)
}
if task.Workflow != "tdd" {
t.Fatalf("pinned workflow = %q, want tdd (the kind binding, untouched by the run)", task.Workflow)
}
})
}
}
+46 -26
View File
@@ -7,8 +7,8 @@
// - a workflow playbook is exactly one `workflow` action, unchanged from
// the original boundary, and is routed by the daemon's definition pin;
// - an action playbook is one or more `module` actions in order, each with
// a registered `kind`, `args`, and an optional `when`/`id`. It loads and
// type-checks now but has no run path yet (t2db.31).
// a registered `kind`, `args`, and an optional `when`/`id`. Store.Run
// executes it (docs/prds/action-playbook-run.md).
//
// The two shapes never mix in one playbook. This is an ADDITIONAL routing
// source alongside the flat kind/label binding files (t2db.9/.10/.11): the
@@ -18,6 +18,7 @@
package playbook
import (
"context"
"crypto/sha256"
"fmt"
"os"
@@ -43,9 +44,19 @@ type KindSchemas interface {
KindSchema(kind string) (args, result reflect.Type, ok bool)
}
// Modules is the module source an action playbook loads and runs against:
// the kinds' schemas, the invoke, and the result decode. *module.ModuleRegistry
// satisfies it.
type Modules interface {
KindSchemas
Invoke(ctx context.Context, kind string, args map[string]any) (map[string]any, error)
DecodeResult(kind string, raw map[string]any) (any, error)
}
// Store is the loaded set of playbooks, validated and compiled at load time.
type Store struct {
Playbooks []*Playbook
modules Modules
}
// Playbook is one trigger+actions document.
@@ -190,10 +201,10 @@ func validateModuleActionIDs(path string, actions []rawAction) error {
// compile error, an args key error -- fails the whole load: the reject-at-load
// philosophy of the parent design doc. A missing directory is an empty store
// (matching the flat binding loaders' convention).
func Load(dir string, schemas KindSchemas) (*Store, error) {
func Load(dir string, modules Modules) (*Store, error) {
entries, err := os.ReadDir(dir)
if os.IsNotExist(err) {
return &Store{}, nil
return &Store{modules: modules}, nil
}
if err != nil {
return nil, fmt.Errorf("read playbook dir %s: %w", dir, err)
@@ -210,10 +221,10 @@ func Load(dir string, schemas KindSchemas) (*Store, error) {
}
sort.Strings(names)
store := &Store{}
store := &Store{modules: modules}
for _, name := range names {
path := filepath.Join(dir, name)
pb, err := loadOne(dir, path, schemas)
pb, err := loadOne(dir, path, modules)
if err != nil {
return nil, err
}
@@ -549,8 +560,8 @@ type DispatchInput struct {
// IsActionPlaybook reports whether pb is an action playbook (one or more
// module actions), as opposed to a workflow playbook (exactly one workflow
// action). It is the single two-shape predicate shared by Dispatch (which
// skips action playbooks) and the daemon's D1 load warning (which logs them),
// so the two can never disagree.
// routes only workflow playbooks) and Run (which executes only action
// playbooks), so the two can never disagree.
func (pb *Playbook) IsActionPlaybook() bool {
return len(pb.Actions) != 1 || pb.Actions[0].Position != "workflow"
}
@@ -604,9 +615,8 @@ type Decision struct {
// Dispatch returns the workflow name the first matching workflow playbook
// selects for the input, and whether any playbook matched. Action playbooks
// are loaded and validated but not routed (multi-action-playbooks.md, D1), so
// this considers workflow playbooks only: an action playbook cannot hijack the
// definition pin before its run path exists (t2db.31). No match means trigger
// choose no workflow, so they are skipped here and executed by Run. No match
// means trigger
// mismatch or a when condition evaluating false, and the caller keeps its own
// routing.
//
@@ -635,16 +645,8 @@ func (s *Store) Dispatch(input DispatchInput) (Decision, bool) {
continue
}
a := pb.Actions[0]
if a.When != nil {
val, err := a.env.Eval(a.When, ctx)
if err != nil {
// J3: evaluation error -> false (skip), caller logs.
continue
}
b, ok := val.(bool)
if !ok || !b {
continue
}
if !a.whenHolds(ctx) {
continue
}
return Decision{PlaybookID: pb.ID, Version: pb.Version, Workflow: a.Workflow, ActionID: a.ID, ActionPosition: 1}, true
}
@@ -662,9 +664,8 @@ func evalContext(input DispatchInput) expr.Context {
}
// EvalArgs evaluates a compiled action's args against the dispatch context,
// returning the resulting name->value map. No shipped position consumes args
// yet; the consumer arrives with the first side-effecting position (t2db.31).
// An action declaring no args evaluates to an empty map, nil-program entries
// returning the resulting name->value map. Run evaluates args the same way
// against a context that also carries earlier actions' results. An action declaring no args evaluates to an empty map, nil-program entries
// are skipped, and the first evaluation error is returned. Nil-receiver-safe
// for the pre-load composition phase.
//
@@ -673,10 +674,29 @@ func evalContext(input DispatchInput) expr.Context {
// meaningful substitute and is returned to the caller to abort the dispatch.
// Ratifying that rule against a real consumer is tracked by archie-core-1h05.
func (s *Store) EvalArgs(a Action, input DispatchInput) (map[string]any, error) {
if s == nil || len(a.Args) == 0 {
if s == nil {
return map[string]any{}, nil
}
ctx := evalContext(input)
return a.evalArgs(evalContext(input))
}
// whenHolds reports whether the action's `when` is absent or evaluates to
// true. An evaluation error is false (J3: skip, caller logs).
func (a Action) whenHolds(ctx expr.Context) bool {
if a.When == nil {
return true
}
val, err := a.env.Eval(a.When, ctx)
if err != nil {
return false
}
b, ok := val.(bool)
return ok && b
}
// evalArgs evaluates the action's args against ctx in key order, returning
// the first evaluation error.
func (a Action) evalArgs(ctx expr.Context) (map[string]any, error) {
out := make(map[string]any, len(a.Args))
keys := make([]string, 0, len(a.Args))
for key := range a.Args {
@@ -30,7 +30,7 @@ func writeFile(t *testing.T, dir, name, content string) string {
// tests: *module.ModuleRegistry satisfies playbook.KindSchemas. It consults
// the built-in kind registry, so no module file needs to be installed for the
// schema lookup to work.
func testSchemas(t *testing.T) KindSchemas {
func testSchemas(t *testing.T) Modules {
t.Helper()
return module.New()
}
+72
View File
@@ -0,0 +1,72 @@
package playbook
import (
"context"
"errors"
"fmt"
"log/slog"
"strconv"
"github.com/samcharles93/archie-core/internal/domain/eda/expr"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
)
// Run executes every action playbook whose trigger matches input, in load
// order (docs/prds/action-playbook-run.md). Each action goes through
// InvokeOnce, so it fires at most once per (playbook, version, event,
// action). A failure stops only its own playbook; the rest still run, and
// the failures are returned joined, each naming its playbook and action.
func (s *Store) Run(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, input DispatchInput) error {
if s == nil {
return nil
}
var errs []error
for _, pb := range s.Playbooks {
if !pb.IsActionPlaybook() || !pb.Match(input) {
continue
}
if err := s.runPlaybook(ctx, ledger, log, pb, input); err != nil {
errs = append(errs, fmt.Errorf("playbook %s: %w", pb.ID, err))
}
}
return errors.Join(errs...)
}
// runPlaybook runs one playbook's actions in order against one evaluation
// context, so a later action reads an earlier one's result.
func (s *Store) runPlaybook(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, pb *Playbook, input DispatchInput) error {
evalCtx := expr.Context{Event: input.Event, Actions: map[string]map[string]any{}}
for i, a := range pb.Actions {
label := a.ID
if label == "" {
label = "#" + strconv.Itoa(i+1)
}
if !a.whenHolds(evalCtx) {
continue
}
args, err := a.evalArgs(evalCtx)
if err != nil {
return fmt.Errorf("action %s: %w", label, err)
}
var raw map[string]any
decision := Decision{PlaybookID: pb.ID, Version: pb.Version, ActionID: a.ID, ActionPosition: i + 1}
invoked := false
err = InvokeOnce(ctx, ledger, log, decision, input, func(ctx context.Context) error {
invoked = true
raw, err = s.modules.Invoke(ctx, a.Kind, args)
return err
})
if err != nil {
return fmt.Errorf("action %s: %w", label, err)
}
if !invoked || a.ID == "" {
continue
}
result, err := s.modules.DecodeResult(a.Kind, raw)
if err != nil {
return fmt.Errorf("action %s: %w", label, err)
}
evalCtx.Actions[a.ID] = map[string]any{"result": result}
}
return nil
}
+143
View File
@@ -0,0 +1,143 @@
package playbook
import (
"context"
"errors"
"log/slog"
"slices"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
)
// recordingModules is the real kind-schema source with a fake invoker: it
// records each log message and fails any message listed in fail.
type recordingModules struct {
*module.ModuleRegistry
messages []string
fail map[string]bool
}
func (m *recordingModules) Invoke(_ context.Context, kind string, args map[string]any) (map[string]any, error) {
msg, _ := args["message"].(string)
m.messages = append(m.messages, msg)
if m.fail[msg] {
return nil, errors.New("invoke failed")
}
return map[string]any{"written": true, "level": "info"}, nil
}
func loadRunStore(t *testing.T, mods *recordingModules, document string) *Store {
t.Helper()
dir := t.TempDir()
writeFile(t, dir, "pb.yaml", document)
store, err := Load(dir, mods)
if err != nil {
t.Fatalf("Load: %v", err)
}
return store
}
const twoLogActions = `
trigger:
kind: bug
actions:
- id: first
position: module
kind: log
args: { message: '"first"' }
- id: second
position: module
kind: log
args: { message: '"second saw " + string(actions.first.result.written)' }
`
func bugInput() DispatchInput {
return DispatchInput{Labels: []string{"bug"}, Kind: "bug", TaskID: "acme/widget#7", Event: map[string]any{}}
}
func TestRunExecutesActionsInOrderAndFeedsResults(t *testing.T) {
mods := &recordingModules{ModuleRegistry: module.New()}
store := loadRunStore(t, mods, twoLogActions)
if err := store.Run(t.Context(), &fakePlaybookLedger{}, slog.New(slog.DiscardHandler), bugInput()); err != nil {
t.Fatalf("Run: %v", err)
}
if want := []string{"first", "second saw true"}; !slices.Equal(mods.messages, want) {
t.Fatalf("invoked messages = %q, want %q", mods.messages, want)
}
}
func TestRunInvokesEachActionOncePerEvent(t *testing.T) {
mods := &recordingModules{ModuleRegistry: module.New()}
store := loadRunStore(t, mods, twoLogActions)
ledger := &fakePlaybookLedger{}
log := slog.New(slog.DiscardHandler)
if err := store.Run(t.Context(), ledger, log, bugInput()); err != nil {
t.Fatalf("Run: %v", err)
}
// The repeat skips "first" as a duplicate, so it has no result and
// "second" cannot evaluate its args: the playbook stops there
// (action-playbook-run.md). Neither action is invoked again.
_ = store.Run(t.Context(), ledger, log, bugInput())
if len(mods.messages) != 2 {
t.Fatalf("invoked messages = %q, want each action once", mods.messages)
}
}
func TestRunSkipsAnActionWhoseWhenIsFalse(t *testing.T) {
mods := &recordingModules{ModuleRegistry: module.New()}
store := loadRunStore(t, mods, `
trigger:
kind: bug
actions:
- position: module
kind: log
when: 'event.kind == "feature"'
args: { message: '"skipped"' }
- position: module
kind: log
args: { message: '"ran"' }
`)
if err := store.Run(t.Context(), &fakePlaybookLedger{}, slog.New(slog.DiscardHandler), DispatchInput{
Labels: []string{"bug"}, Kind: "bug", TaskID: "acme/widget#7", Event: map[string]any{"kind": "bug"},
}); err != nil {
t.Fatalf("Run: %v", err)
}
if want := []string{"ran"}; !slices.Equal(mods.messages, want) {
t.Fatalf("invoked messages = %q, want %q", mods.messages, want)
}
}
func TestRunStopsThePlaybookOnAnInvokeError(t *testing.T) {
mods := &recordingModules{ModuleRegistry: module.New(), fail: map[string]bool{"first": true}}
store := loadRunStore(t, mods, twoLogActions)
err := store.Run(t.Context(), &fakePlaybookLedger{}, slog.New(slog.DiscardHandler), bugInput())
if err == nil || !strings.Contains(err.Error(), "pb.yaml") || !strings.Contains(err.Error(), "first") {
t.Fatalf("Run error = %v, want one naming the playbook and the action", err)
}
if want := []string{"first"}; !slices.Equal(mods.messages, want) {
t.Fatalf("invoked messages = %q, want the run stopped at %q", mods.messages, want)
}
}
func TestRunIgnoresNonMatchingAndWorkflowPlaybooks(t *testing.T) {
mods := &recordingModules{ModuleRegistry: module.New()}
store := loadRunStore(t, mods, twoLogActions)
input := bugInput()
input.Labels, input.Kind = []string{"feature"}, "feature"
if err := store.Run(t.Context(), &fakePlaybookLedger{}, slog.New(slog.DiscardHandler), input); err != nil {
t.Fatalf("Run: %v", err)
}
workflowStore := loadRunStore(t, mods, "trigger:\n kind: bug\nactions:\n - position: workflow\n workflow: tdd\n")
if err := workflowStore.Run(t.Context(), &fakePlaybookLedger{}, slog.New(slog.DiscardHandler), bugInput()); err != nil {
t.Fatalf("Run: %v", err)
}
if len(mods.messages) != 0 {
t.Fatalf("invoked messages = %q, want none", mods.messages)
}
}