Files
archie/docs/prds/multi-action-playbooks.md
T

6.0 KiB

Multi-action playbooks and typed action results

Status: Approved Date: 2026-09-22 Parent: docs/prds/eda-playbook-engine.md, epic archie-core-t2db Beads issue: archie-core-nx30 (unblocks archie-core-t2db.27 and archie-core-t2db.31)

Why this exists

eda-playbook-engine.md's hard boundary rejects any playbook that is not exactly one workflow action, so the parent document's data-flow, Module and Channel/Forge decisions have no loadable shape to attach to. The boundary's own stated condition is now met: both execution-time gaps are resolved (eda-playbook-engine.md, "Execution-time gaps"; the playbook_dispatches ledger). This document designs the relaxation.

A playbook is one of two shapes

  • A workflow playbook is exactly one workflow action. Unchanged: it names a workflow definition and is routed by the daemon's definition pin.
  • An action playbook is one or more module actions in order. Each action has an optional id, a kind naming a registered Module kind, args, and an optional when.

One playbook does not mix the two shapes.

trigger: { kind: bug }
actions:
  - id: build
    position: module
    kind: log
    args: { message: '"build started"' }
  - id: done
    position: module
    kind: log
    args: { message: '"done: " + string(actions.build.result.written)' }
    when: actions.build.result.written == true

The first Module kind is the side-effect-free log kind (module-position.md, "Recommended first slice"). A Module kind with an external side effect, and the Channel and Forge positions, are out of scope.

A result type is the kind's generated Result struct

Each Module kind owns a hand-written Args and Result struct (internal/domain/eda/module/log is the worked example); ModuleRegistry.Invoke returns the result as a flat map[string]any. ModuleRegistry.DecodeResult (internal/domain/eda/module) is the single site that converts that map into the kind's Result struct before a later expression reads it, so the value the checker validates and the value the run reads have one definition.

actions.<id> is typed by the kind of the action that declares <id>: { result: <KindResult> }. event stays dyn (J4, playbook-expression-syntax.md).

Reject-at-load, preserved

Relaxing the boundary must not make a bad reference resolvable. The load fails, naming the playbook and the offending action, for:

  • an id missing where a later action references it, duplicated, or outside its shape's grammar: a workflow action id keeps the shared stable-identifier grammar (J1, already enforced), while a module action id must be a lowercase CEL field name writable as actions.<id> (so a CEL keyword such as in, true, false, or null is rejected at load);
  • an actions.<id> read of an id no earlier action declares;
  • an actions read that is not statically resolvable to an id (any map index, literal or dynamic, in, a comprehension): the typed actions root is an object type, so only field selection actions.<id> resolves and the actions["id"] spelling is not accepted;
  • a result field the referenced kind's Result does not define;
  • a reference to an earlier action that produces no result;
  • an unknown position, an unknown kind, or a module action with no kind;
  • a field belonging to the other shape (kind on a workflow action, or workflow on a module action);
  • an arg KEY the kind's Args schema does not define;
  • an arg value whose checked CEL type cannot fill its Args field ('123' for a string field). A dyn value, such as an event read, passes: its type is known only per event, and the module decode refuses a bad one at run.

Declaring the kind's Result schema to CEL at load makes a result-field typo a load failure rather than a dispatch failure. Matching arg keys against the kind's Args schema makes an arg-key typo or a wrongly typed value a load failure.

The environment is per playbook

Result typing depends on the ids a playbook declares and the kind each id runs, so the CEL environment is built from one playbook's action list rather than once per Store, and expr.NewEnv takes that list: each declared id becomes a field 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. Running one is designed in docs/prds/action-playbook-run.md.

Decisions

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.

D2 — mixing positions. Settled: one shape per playbook. A workflow action yields a task, not a result, so it cannot feed actions.<id>.result.

D3 — the CEL typing mechanism. Settled: a per-playbook environment whose actions root is an object type with one field per declared id, each field typed by the kind's Result struct. internal/domain/eda/expr implements it with the generic actionResultProvider.

D4 — args against the kind's Args schema. Settled: keys and statically typed values are checked at load; dyn values are checked by the module decode.

D5 — where the result map becomes the Result struct. Settled: ModuleRegistry stays schema-agnostic. ModuleRegistry.DecodeResult (internal/domain/eda/module) is the conversion site.

Verification

  • A two-action module playbook with a valid actions.<id>.result.<field> read loads; the same read of a field the kind's Result does not define fails the load naming the field; a read of an id no earlier action declares fails; a dynamically indexed actions read fails.
  • An arg KEY the kind's Args schema does not define fails the load, and so does message: '123' for the log kind. message: event.title loads.
  • The one-action workflow playbook shape, its dispatch, and its existing load-time checks are unchanged.