docs(prds): reflow playbook-expression-syntax
deploy / gate (push) Failing after 5m32s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped

This commit is contained in:
sam committed 2026-09-25 02:00:16 +10:00
1 parent a4d98786a1
commit 459bbcd5fc
2 files changed
+159 -183

No files matched your search

+1 -1
View File
@@ -400,7 +400,7 @@
"url": "/dev/prds/playbook-expression-syntax/",
"title": "Playbook data-flow and condition syntax",
"section": "PRDs",
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a\ncondition deciding whether the action runs; (b) a later action's `args`\nvalues referencing an earlier action's `Result` and the triggering\nevent's fields. Both are **CEL expressions**, evaluated against one\nevaluation context. There is no separate interpolation syntax: CEL\nreads nested maps and fields natively, so `args` values that need data\nare written as CEL, and only plain literal args remain plain YAML\nscalars.\n\nBoth halves are read-only: expressions may read context values and\ncompute a result from them, never mutate, never call host functions,\nnever perform I/O. CEL enforces this structurally (no side effects,\nlinear evaluation when macros are bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged**\n-- the same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir`\n(module-position.md's trust-boundary section): loaded from a configured\ndirectory at startup, never from a webhook body or task worktree. The\nschema-by-example flow uses live events to _design against_; the saved\nplaybook is operator-authored file content in an operator-configured\nlocation.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not\n attacker input; no sandboxing against a hostile expression string is\n required. If a future playbook source is less trusted (auto-generated\n bindings from unauthenticated captures), that is the playbook-file\n trust tier moving -- the loader's acceptance check is the right\n place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook\n body, prior results through the same pipeline). Robustness against\n hostile data is required: no panic on wrong-typed/missing fields,\n no unbounded cost on deep/cyclic maps, bounded evaluation time. CEL\n provides this structurally (cost limits, linear non-Turing-complete\n evaluation, error values instead of panics -- verified in the\n vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go\n(`.archie/gate.go`) as the repo's conditional-logic precedent. That is\nthe wrong precedent for playbook conditions because this document's\npremise is: **YAML is pure orchestration data; Yaegi is where\nimperative logic lives** (Problem section; module-position.md's\n\"no generic hook\" section). Yaegi snippets in YAML would move\nimperative logic into the data layer -- the inversion this design\nexists to prevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data,\nnot programs**. CEL is non-Turing-complete and side-effect-free, so it\ncannot become a program; a condition that needs real logic gets a\nModule kind (Yaegi), referenced by the action, not a stronger\nexpression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an\n`any` payload; it exists to keep static implementation contracts\ntyped. Evaluating CEL against runtime `map[string]any` is **not the\nsame problem**: the rule concerns _implementation contracts_ (static\noperations a capability family exposes), not _runtime data values_\n(legitimately dynamic -- an event payload's shape is unknown until it\narrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the\nplaybook engine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch\ntime:\n\n| Name | Type | Source Line truncated
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source Line truncated
},
{
"url": "/dev/prds/pr-review-remediation/",
+158 -182
View File
@@ -13,19 +13,18 @@ mechanism covers both an action's `when` condition and its `args` values.
## The requirement, stated directly
A playbook action is gated and parametrised by runtime data: (a) a
condition deciding whether the action runs; (b) a later action's `args`
values referencing an earlier action's `Result` and the triggering
event's fields. Both are **CEL expressions**, evaluated against one
evaluation context. There is no separate interpolation syntax: CEL
reads nested maps and fields natively, so `args` values that need data
are written as CEL, and only plain literal args remain plain YAML
scalars.
A playbook action is gated and parametrised by runtime data: (a) a condition
deciding whether the action runs; (b) a later action's `args` values referencing
an earlier action's `Result` and the triggering event's fields. Both are **CEL
expressions**, evaluated against one evaluation context. There is no separate
interpolation syntax: CEL reads nested maps and fields natively, so `args`
values that need data are written as CEL, and only plain literal args remain
plain YAML scalars.
Both halves are read-only: expressions may read context values and
compute a result from them, never mutate, never call host functions,
never perform I/O. CEL enforces this structurally (no side effects,
linear evaluation when macros are bounded, cost-limited).
Both halves are read-only: expressions may read context values and compute a
result from them, never mutate, never call host functions, never perform I/O.
CEL enforces this structurally (no side effects, linear evaluation when macros
are bounded, cost-limited).
```yaml
actions:
@@ -44,112 +43,101 @@ actions:
## Trust boundary of the expression
A playbook YAML is **operator-installed, in-process, daemon-privileged**
-- the same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir`
(module-position.md's trust-boundary section): loaded from a configured
directory at startup, never from a webhook body or task worktree. The
schema-by-example flow uses live events to _design against_; the saved
playbook is operator-authored file content in an operator-configured
location.
A playbook YAML is **operator-installed, in-process, daemon-privileged** -- the
same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's
trust-boundary section): loaded from a configured directory at startup, never
from a webhook body or task worktree. The schema-by-example flow uses live
events to _design against_; the saved playbook is operator-authored file content
in an operator-configured location.
Two consequences:
1. The expression string is **trusted**. Operator-authored config, not
attacker input; no sandboxing against a hostile expression string is
required. If a future playbook source is less trusted (auto-generated
bindings from unauthenticated captures), that is the playbook-file
trust tier moving -- the loader's acceptance check is the right
place, not the evaluator.
2. The **data the expression reads is NOT trusted** (decoded webhook
body, prior results through the same pipeline). Robustness against
hostile data is required: no panic on wrong-typed/missing fields,
no unbounded cost on deep/cyclic maps, bounded evaluation time. CEL
provides this structurally (cost limits, linear non-Turing-complete
evaluation, error values instead of panics -- verified in the
vetting record below).
1. The expression string is **trusted**. Operator-authored config, not attacker
input; no sandboxing against a hostile expression string is required. If a
future playbook source is less trusted (auto-generated bindings from
unauthenticated captures), that is the playbook-file trust tier moving -- the
loader's acceptance check is the right place, not the evaluator.
2. The **data the expression reads is NOT trusted** (decoded webhook body, prior
results through the same pipeline). Robustness against hostile data is
required: no panic on wrong-typed/missing fields, no unbounded cost on
deep/cyclic maps, bounded evaluation time. CEL provides this structurally
(cost limits, linear non-Turing-complete evaluation, error values instead of
panics -- verified in the vetting record below).
## The gate precedent is deliberately NOT copied
`internal/gate/gateeval` evaluates arbitrary interpreted Go
(`.archie/gate.go`) as the repo's conditional-logic precedent. That is
the wrong precedent for playbook conditions because this document's
premise is: **YAML is pure orchestration data; Yaegi is where
imperative logic lives** (Problem section; module-position.md's
"no generic hook" section). Yaegi snippets in YAML would move
imperative logic into the data layer -- the inversion this design
exists to prevent -- and make playbooks un-lintable.
`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)
as the repo's conditional-logic precedent. That is the wrong precedent for
playbook conditions because this document's premise is: **YAML is pure
orchestration data; Yaegi is where imperative logic lives** (Problem section;
module-position.md's "no generic hook" section). Yaegi snippets in YAML would
move imperative logic into the data layer -- the inversion this design exists to
prevent -- and make playbooks un-lintable.
The line: conditions are **declarative predicates over runtime data,
not programs**. CEL is non-Turing-complete and side-effect-free, so it
cannot become a program; a condition that needs real logic gets a
Module kind (Yaegi), referenced by the action, not a stronger
expression body.
The line: conditions are **declarative predicates over runtime data, not
programs**. CEL is non-Turing-complete and side-effect-free, so it cannot become
a program; a condition that needs real logic gets a Module kind (Yaegi),
referenced by the action, not a stronger expression body.
## Plugin-engine-rule interaction
The plugin engine rule forbids a generic `Module` interface with an
`any` payload; it exists to keep static implementation contracts
typed. Evaluating CEL against runtime `map[string]any` is **not the
same problem**: the rule concerns _implementation contracts_ (static
operations a capability family exposes), not _runtime data values_
(legitimately dynamic -- an event payload's shape is unknown until it
arrives). The Module contract stays fully typed (generated
`Args`/`Result` schemas); CEL is a read-only data reader under the
playbook engine family, not a new capability contract. Stated once.
The plugin engine rule forbids a generic `Module` interface with an `any`
payload; it exists to keep static implementation contracts typed. Evaluating CEL
against runtime `map[string]any` is **not the same problem**: the rule concerns
_implementation contracts_ (static operations a capability family exposes), not
_runtime data values_ (legitimately dynamic -- an event payload's shape is
unknown until it arrives). The Module contract stays fully typed (generated
`Args`/`Result` schemas); CEL is a read-only data reader under the playbook
engine family, not a new capability contract. Stated once.
## Minimum viable evaluation context (what expressions see)
One flat context, namespaced from the playbook run, built at dispatch
time:
One flat context, namespaced from the playbook run, built at dispatch time:
| Name | Type | Source |
| --------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event` | `map(string, dyn)` | The triggering event's decoded payload (webhook body / forge issue / schedule tick). Field access via `event.<field>`, map access via `event["field"]`, presence via `has(event.<field>)`. |
| `actions` | per-playbook object type | Previous actions' results, one field per declared action `id` (`actions.<id>`), each field typed `{ result: <KindResult> }` so a later action reads an earlier one's `Result` struct (`actions.<id>.result.<field>`) with field-level checking. The current action and later actions are not present. |
Expressions may also read literal-only state (numbers, strings,
booleans) directly. CEL's `has()` macro covers the missing-key case
(`has(event.labels)` -> bool), which replaces any bespoke `has`/
`contains` operator.
Expressions may also read literal-only state (numbers, strings, booleans)
directly. CEL's `has()` macro covers the missing-key case (`has(event.labels)`
-> bool), which replaces any bespoke `has`/ `contains` operator.
`actions.<id>.result` is the kind's hand-written `Result` struct:
`ModuleRegistry.DecodeResult` converts `Module.Invoke`'s flat
`map[string]any` (`archie-core-t2db.13`) back into that struct before a later
expression reads it, so the checker and the run read the same typed value.
`ModuleRegistry.DecodeResult` converts `Module.Invoke`'s flat `map[string]any`
(`archie-core-t2db.13`) back into that struct before a later expression reads
it, so the checker and the run read the same typed value.
Judgement call J1: `action` id is a required field on every action
that later actions reference; ids are validated at load (unique,
stable-identifier-shaped), and a `when`/`args` expression referencing
an unknown `actions.<id>` is a **load failure**, not a runtime miss --
the same reject-at-load rule as collisions (see below).
Judgement call J1: `action` id is a required field on every action that later
actions reference; ids are validated at load (unique, stable-identifier-shaped),
and a `when`/`args` expression referencing an unknown `actions.<id>` is a **load
failure**, not a runtime miss -- the same reject-at-load rule as collisions (see
below).
## Load-time validation (consistent with the collision rule)
The collision-handling rule is: schema defines the accepted message;
anything outside it is rejected at load, logged plainly, reported to
the caller -- never deferred to runtime. Expressions are validated the
same way, at playbook load:
The collision-handling rule is: schema defines the accepted message; anything
outside it is rejected at load, logged plainly, reported to the caller -- never
deferred to runtime. Expressions are validated the same way, at playbook load:
- **Syntax**: every `when` and every CEL-typed `args` value is parsed
and checked by CEL's checker when the playbook is loaded. A syntax
or type error is a reported load failure (the playbook is dropped and
the error goes to the caller), not a runtime surprise.
- **Context conformance**: with the context declared to CEL
(`event` as `map(string, dyn)`, `actions` as a per-playbook object type
with one typed field per declared id),
unknown top-level identifiers are rejected at compile time.
Field-level typing inside `dyn` values is deferred to runtime by
CEL's design (verified: `data.items.lenght` with `data` dyn compiles
clean and errors at eval) -- so the loader declares as much type as
the schema provides (the action kinds' generated `Result` structs
become CEL type declarations at load, giving field-level rejection
for result reads), and `event` stays `dyn` because its shape is
unknown by design (schema-by-example).
- **Syntax**: every `when` and every CEL-typed `args` value is parsed and
checked by CEL's checker when the playbook is loaded. A syntax or type error
is a reported load failure (the playbook is dropped and the error goes to the
caller), not a runtime surprise.
- **Context conformance**: with the context declared to CEL (`event` as
`map(string, dyn)`, `actions` as a per-playbook object type with one typed
field per declared id), unknown top-level identifiers are rejected at compile
time. Field-level typing inside `dyn` values is deferred to runtime by CEL's
design (verified: `data.items.lenght` with `data` dyn compiles clean and
errors at eval) -- so the loader declares as much type as the schema provides
(the action kinds' generated `Result` structs become CEL type declarations at
load, giving field-level rejection for result reads), and `event` stays `dyn`
because its shape is unknown by design (schema-by-example).
- **Names**: unknown `actions.<id>` references and unknown roots are
compile-time/lint-visible errors (J1).
This means the lint tool and the daemon share one checker
-- same single-source argument as the playbook loaders.
This means the lint tool and the daemon share one checker -- same single-source
argument as the playbook loaders.
## Candidate comparison
@@ -165,112 +153,100 @@ This means the lint tool and the daemon share one checker
Source reviewed at HEAD:
- **Repo hygiene**: clean. No binaries/media in tree (the only
non-source artifacts are expected generated protobuf files); 16-line
`.gitignore`.
- **Hard-boundary correctness**: the place correctness is hard for an
expression evaluator is bounding evaluation and surviving hostile
input. Dedicated regression tests exist and pass at HEAD:
`TestCostLimit`, `TestCostTracking*`, `TestParserRecursionLimit`,
and a large conformance suite. Verified by execution: evaluation
against a 2000-deep nested map under `CostLimit` completes in ~10
microseconds and returns an error value for a missing key -- no
panic, no unbounded walk.
- **Dependency footprint**: antlr (parser), protobuf + genproto (CEL's
type model), `cel.dev/expr` (CEL spec types), yaml.v3. All
mainstream, canonical, vendored widely by Google-adjacent projects.
No runtime-impure third-party code; the REPL-only deps (readline,
tview, tcell) are not in the library import graph.
- **Security record**: no advisories on record for `cel.dev/cel-go`
(GitHub Advisory Database).
- **Module path**: migrated to `cel.dev/cel-go` (v0.32.0 is current);
the old `github.com/google/cel-go` path is the pre-migration identity.
Pin `cel.dev/cel-go`.
- **Binary size cost**: +13.0MB is the largest of the candidates
(measured: baseline 2.34MB -> 15.25MB with CEL). Accepted because:
the daemon already embeds a large Yaegi runtime; CEL's type model is
the load-bearing win (compile-time rejection of result-path typos,
matching the reject-at-load rule); and the alternative bespoke
grammar would re-implement CEL's checker to get the same guarantee.
Flagged for sign-off: if 13MB is unacceptable for a specific
deployment target, the fallback is a bespoke grammar with a
- **Repo hygiene**: clean. No binaries/media in tree (the only non-source
artifacts are expected generated protobuf files); 16-line `.gitignore`.
- **Hard-boundary correctness**: the place correctness is hard for an expression
evaluator is bounding evaluation and surviving hostile input. Dedicated
regression tests exist and pass at HEAD: `TestCostLimit`, `TestCostTracking*`,
`TestParserRecursionLimit`, and a large conformance suite. Verified by
execution: evaluation against a 2000-deep nested map under `CostLimit`
completes in ~10 microseconds and returns an error value for a missing key --
no panic, no unbounded walk.
- **Dependency footprint**: antlr (parser), protobuf + genproto (CEL's type
model), `cel.dev/expr` (CEL spec types), yaml.v3. All mainstream, canonical,
vendored widely by Google-adjacent projects. No runtime-impure third-party
code; the REPL-only deps (readline, tview, tcell) are not in the library
import graph.
- **Security record**: no advisories on record for `cel.dev/cel-go` (GitHub
Advisory Database).
- **Module path**: migrated to `cel.dev/cel-go` (v0.32.0 is current); the old
`cel.dev/cel-go/cel` path is the pre-migration identity. Pin `cel.dev/cel-go`.
- **Binary size cost**: +13.0MB is the largest of the candidates (measured:
baseline 2.34MB -> 15.25MB with CEL). Accepted because: the daemon already
embeds a large Yaegi runtime; CEL's type model is the load-bearing win
(compile-time rejection of result-path typos, matching the reject-at-load
rule); and the alternative bespoke grammar would re-implement CEL's checker to
get the same guarantee. Flagged for sign-off: if 13MB is unacceptable for a
specific deployment target, the fallback is a bespoke grammar with a
re-implemented subset of this checker -- a strictly worse trade.
## Why bespoke was not sufficient
A bespoke grammar for the shipped cases (path read + comparison + bool
composition) is small, but the load-time-validation requirement makes
the comparison: the reject-at-load rule requires _field-level_ static
checking of result paths against generated `Result` schemas, which is
CEL's type-checker's job. Re-implementing that on a hand-rolled
grammar means re-implementing a type system -- more code than the
grammar itself, with worse diagnostics, no conformance suite, and no
community surface for future expression needs (even declarative ones).
The bespoke option only wins on binary size, and the size cost of CEL
is measured and bounded.
composition) is small, but the load-time-validation requirement makes the
comparison: the reject-at-load rule requires _field-level_ static checking of
result paths against generated `Result` schemas, which is CEL's type-checker's
job. Re-implementing that on a hand-rolled grammar means re-implementing a type
system -- more code than the grammar itself, with worse diagnostics, no
conformance suite, and no community surface for future expression needs (even
declarative ones). The bespoke option only wins on binary size, and the size
cost of CEL is measured and bounded.
## Judgement calls (flagged for sign-off)
- **J1 -- `id` required on referenced actions, unknown id = load
failure.** Matches the reject-at-load rule. Alternative considered: an alternative
is positional `actions[0]` access, which breaks on reorder; named is
the operator-friendlier shape.
- **J2 -- every `args` value is evaluated as a CEL expression.** No
split between "literal args" and "expression args": a plain string
value is a CEL string literal, a number is a CEL number literal, and
any value that reads context data is written in CEL. One mechanism,
no interpolation marker, no second syntax to learn. Alternative considered: cEL
string literals must be quoted inside YAML (e.g. `message:
'"build finished"'`), which is slightly noisy for mostly-literal
args; accepted for uniformity -- the linter catches quoting mistakes
at load.
- **J3 -- condition failure semantics.** A condition that errors at
runtime (missing/wrong-typed field) evaluates to **false**: the
action is skipped, logged, run continues. This is the simplest
candidate consistent with gap 1's bias against clever recovery;
gap 1 (`archie-core-t2db.18`) commits
stop-on-first-failure, so per-action control is not coming and J3
stands. Alternative considered: cEL separates
false from error; we treat evaluation error as false + log.
- **J4 -- `event` stays `dyn` (schema-by-example).** Load-time we
cannot know event field types; declaring them typed would reject
valid plays. Result reads get field-level checking via generated
schema declarations. Alternative considered: when schema-by-example ships, tighten
event field declarations from captured samples.
- **J5 -- cost limit default.** A `CostLimit` at load time (e.g.
100,000) is applied to every expression; the linter and daemon use
the same value so they agree. Alternative considered: exact number is a constant to
tune at first use.
- **J1 -- `id` required on referenced actions, unknown id = load failure.**
Matches the reject-at-load rule. Alternative considered: an alternative is
positional `actions[0]` access, which breaks on reorder; named is the
operator-friendlier shape.
- **J2 -- every `args` value is evaluated as a CEL expression.** No split
between "literal args" and "expression args": a plain string value is a CEL
string literal, a number is a CEL number literal, and any value that reads
context data is written in CEL. One mechanism, no interpolation marker, no
second syntax to learn. Alternative considered: cEL string literals must be
quoted inside YAML (e.g. `message: '"build finished"'`), which is slightly
noisy for mostly-literal args; accepted for uniformity -- the linter catches
quoting mistakes at load.
- **J3 -- condition failure semantics.** A condition that errors at runtime
(missing/wrong-typed field) evaluates to **false**: the action is skipped,
logged, run continues. This is the simplest candidate consistent with gap 1's
bias against clever recovery; gap 1 (`archie-core-t2db.18`) commits
stop-on-first-failure, so per-action control is not coming and J3 stands.
Alternative considered: cEL separates false from error; we treat evaluation
error as false + log.
- **J4 -- `event` stays `dyn` (schema-by-example).** Load-time we cannot know
event field types; declaring them typed would reject valid plays. Result reads
get field-level checking via generated schema declarations. Alternative
considered: when schema-by-example ships, tighten event field declarations
from captured samples.
- **J5 -- cost limit default.** A `CostLimit` at load time (e.g. 100,000) is
applied to every expression; the linter and daemon use the same value so they
agree. Alternative considered: exact number is a constant to tune at first
use.
## Interaction with the execution-time gaps
This resolution does not resolve the execution-time gaps (both are
resolved separately: gap 1 by `archie-core-t2db.18`, gap 2 by the
gap-2 decision). Conditions make gap 1
concrete (condition-failure vs. action-failure semantics, J3) and
CEL's read-only result access makes gap 2's keying derivation
readable (an idempotency key expression can read event fields) -- both
flagged as the gaps' first real exercise. Gap 2's exercise is
subsequently solved by that decision: the
answer is a fixed structural derivation, and idempotency keys are
deliberately NOT CEL expressions (see the "No CEL in the key"
passage).
This resolution does not resolve the execution-time gaps (both are resolved
separately: gap 1 by `archie-core-t2db.18`, gap 2 by the gap-2 decision).
Conditions make gap 1 concrete (condition-failure vs. action-failure semantics,
J3) and CEL's read-only result access makes gap 2's keying derivation readable
(an idempotency key expression can read event fields) -- both flagged as the
gaps' first real exercise. Gap 2's exercise is subsequently solved by that
decision: the answer is a fixed structural derivation, and idempotency keys are
deliberately NOT CEL expressions (see the "No CEL in the key" passage).
## Implementation placement (for the follow-up slice)
- New `internal/domain/eda/expr` package: builds the CEL environment
(context declarations, generated `Result` schema types as CEL type
declarations, cost limit), compiles/validates playbook expressions
at load, evaluates them at dispatch. Domain layer; no infrastructure
imports; owned by the playbook engine family. One new dependency:
`cel.dev/cel-go` (pinned), `go.mod` otherwise unchanged.
- Consumption: the playbook event coordinator (open question 4's
loader) evaluates `when` before dispatch and
evaluates `args` values before `Module.Invoke`; the lint tool
(`archie-core-t2db.12`) shares the same compile/validate path for author-time
diagnostics.
- New `internal/domain/eda/expr` package: builds the CEL environment (context
declarations, generated `Result` schema types as CEL type declarations, cost
limit), compiles/validates playbook expressions at load, evaluates them at
dispatch. Domain layer; no infrastructure imports; owned by the playbook
engine family. One new dependency: `cel.dev/cel-go` (pinned), `go.mod`
otherwise unchanged.
- Consumption: the playbook event coordinator (open question 4's loader)
evaluates `when` before dispatch and evaluates `args` values before
`Module.Invoke`; the lint tool (`archie-core-t2db.12`) shares the same
compile/validate path for author-time diagnostics.
- Schema integration: action kinds' generated `Result`/`Args` structs
(`archie-core-t2db.13`'s `logextract` pattern) are declared to CEL at load so
`actions.<id>.result.<field>` type-checks; `args` expressions
type-check against the target kind's `Args` schema before the
playbook is accepted.
`actions.<id>.result.<field>` type-checks; `args` expressions type-check
against the target kind's `Args` schema before the playbook is accepted.