133 lines
6.0 KiB
Markdown
133 lines
6.0 KiB
Markdown
# 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.
|
|
|
|
```yaml
|
|
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.
|