docs(prds): reflow playbook-expression-syntax
This commit is contained in:
1 parent
a4d98786a1
commit
459bbcd5fc
2 files changed
+159
-183
No files matched your search
@@ -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/",
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user