From 38ddfbb00111c8d5fb08c99ef89d0a3ec238890d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 09:51:40 +1000 Subject: [PATCH] docs(eda): record the shipped action-playbook rules and stale claims --- config.example.toml | 2 +- docs/prds/multi-action-playbooks.md | 13 ++++++++----- docs/prds/playbook-expression-syntax.md | 9 +++++---- internal/domain/eda/expr/expr.go | 7 ++++--- 4 files changed, 18 insertions(+), 13 deletions(-) diff --git a/config.example.toml b/config.example.toml index e7b9c8474..49506a1a7 100644 --- a/config.example.toml +++ b/config.example.toml @@ -21,7 +21,7 @@ # workflow_routing_file = "~/.local/share/archie/workflow-routing.yaml" # kind->workflow rebinding (bug/feature/bootstrap) # workflow_labels_file = "~/.local/share/archie/workflow-labels.yaml" # arbitrary forge label -> workflow (EDA playbook slice 2) # playbook_dirs = ["~/.local/share/archie/workflows"] # list of dirs of *.yaml binding files, merged with the two above (slice 3); a key bound twice across sources is a load failure -# eda_playbook_dir = "~/.local/share/archie/eda-playbooks" # rich EDA playbook documents (trigger + CEL gated single workflow action); a matching one decides the task's workflow ahead of the three binding sources above; distinct from playbook_dirs +# eda_playbook_dir = "~/.local/share/archie/eda-playbooks" # rich EDA playbook documents (one trigger; either a CEL-gated workflow action or a list of module actions); a matching workflow playbook decides the task's workflow ahead of the three binding sources above; distinct from playbook_dirs poll_interval = "60s" label = "archie" diff --git a/docs/prds/multi-action-playbooks.md b/docs/prds/multi-action-playbooks.md index b5e4efad1..14ad05424 100644 --- a/docs/prds/multi-action-playbooks.md +++ b/docs/prds/multi-action-playbooks.md @@ -66,11 +66,15 @@ naming the playbook and the offending action, for: must be a lowercase CEL field name writable as `actions.` (so a CEL keyword such as `in`, `true`, `false`, or `null` is rejected at load); - an `actions.` read of an id no earlier action declares; -- an `actions` read that is not statically resolvable to an id (a dynamic - index, `in`, a comprehension — already enforced); +- 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.` 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. Arg VALUE type-checking is tracked as `archie-core-t2db` debt, not shipped here. @@ -83,9 +87,8 @@ type-checking is tracked as `archie-core-t2db` debt. 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`. `expr.NewEnv()` declares `actions` as `map(string, dyn)` and takes no -parameters, so its signature changes to accept the declared ids and their result -types. +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 diff --git a/docs/prds/playbook-expression-syntax.md b/docs/prds/playbook-expression-syntax.md index 92f0b9d86..26664a45b 100644 --- a/docs/prds/playbook-expression-syntax.md +++ b/docs/prds/playbook-expression-syntax.md @@ -29,16 +29,17 @@ linear evaluation when macros are bounded, cost-limited). ```yaml actions: - - position: module + - id: build + position: module kind: log args: message: '"build finished"' # literal when: 'event.label == "bugfix"' # gate on event field - position: module - kind: notify + kind: log args: - message: '"priority " + string(event.priority)' - when: 'actions.notify.result.delivered == true' + message: '"done: " + string(actions.build.result.written)' + when: 'actions.build.result.written == true' ``` ## Trust boundary of the expression diff --git a/internal/domain/eda/expr/expr.go b/internal/domain/eda/expr/expr.go index 8ce28dc2b..eaf1fef93 100644 --- a/internal/domain/eda/expr/expr.go +++ b/internal/domain/eda/expr/expr.go @@ -8,9 +8,10 @@ // every program. `actions` is not a global map: its shape depends on the ids // one playbook declares and the kind each id runs, so NewEnv takes the // declared ids and their Go Result struct types and builds a per-playbook -// object type (multi-action-playbooks.md, D3). The same compile path serves -// the playbook loader (reject-at-load) and the lint tool, so author-time -// diagnostics and runtime evaluation cannot disagree. +// object type (multi-action-playbooks.md, D3). The playbook loader compiles +// every `when` and `args` value here, so load-time rejection and runtime +// evaluation cannot disagree; the standalone lint command covers the flat +// kind/label binding files, not rich EDA playbook documents. // // CEL is non-Turing-complete, side-effect-free, and panic-free by design (no // recover() wrapper is needed; verified in the t2db.14 acceptance tests