feat(eda): reject an args value whose checked CEL type cannot fill its Args field

This commit is contained in:
sam committed 2026-09-23 22:05:50 +10:00
1 parent e867760711
commit d01f7b3d3a
5 files changed
+121 -10

No files matched your search

+11 -1
View File
@@ -114,6 +114,12 @@
"section": "PRDs",
"body": "# PRD writing rules\n\nThese rules apply to every file in `docs/prds/`.\n\n- Search existing PRDs, issues, architecture records, and code first. Do not ask\n the maintainer to repeat recorded requirements.\n- A newer maintainer decision overrides an older design. Mark the old design as\n superseded instead of preserving or defending it.\n- Write plain English. Use a technical term only when the reader needs that\n exact contract or concept.\n- Use the shortest direct sentence. Write “When upgraded, existing instances\n are migrated to the database,” not a description of an importer seeding\n absent resources.\n- State each fact once. Do not repeat a heading, summarize a list before showing\n it, or restate a decision afterward.\n- Every sentence must add a decision, requirement, constraint, evidence, or\n verification step. Delete narration and explanations of obvious text.\n- Do not turn a requested outcome into extra product features. Keep inferences\n open until the maintainer or repository evidence settles them.\n- Do not create a process for a logical boundary. Add one only when it must\n deploy, scale, start, secure, or fail separately.\n- Describe working behavior, not explanatory UI around missing behavior. State\n what users can do and how success is proved.\n- Before approval, use independent read-only reviewers to check a cross-cutting\n PRD for missing behavior and exaggerated claims. Verify and synthesize their\n findings; do not copy their prose.\n- Before requesting approval, review every sentence for complexity, repetition,\n and unsupported scope.\n- Write nothing whose truth expires. No `file.go:123` citations (cite the file\n and the symbol), no progress reports on the work being designed, no dated\n status claims, and no record of how a finding was produced. A phased plan is\n durable design; which phase is finished is not. Do not refer to what this\n document used to say: the reader cannot see it. A supersede marker is fine\n when it names a file, a section or a symbol they can find. `task docs:prds`\n enforces this.\n- Every PRD carries one of three statuses, and nothing else in that field.\n `Draft` until the maintainer explicitly approves it, `Approved` once they\n have and while the work is being built, `Finalised` when the work is\n complete. A finalised PRD does not change; supersede it with a new one\n instead. A revision number belongs in `**Revision:**`, a pointer to the\n authoritative document in `**Authority:**`, and what a past revision changed\n belongs in git.\n"
},
{
"url": "/dev/prds/action-playbook-run/",
"title": "Running action playbooks",
"section": "PRDs",
"body": "# Running action playbooks\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** `docs/prds/multi-action-playbooks.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.31`\n\n## Why this exists\n\nAn action playbook loads and type-checks but never runs: `Store.Dispatch`\nskips it and the daemon logs a warning at boot (`multi-action-playbooks.md`,\nD1). This document defines when it runs, what each action does, and how the\n`playbook_dispatches` ledger gates it.\n\n## When a playbook runs\n\nThe daemon runs action playbooks at the point it pins a task's workflow\ndefinition (`Daemon.resolveWorkflowID`), using the same `DispatchInput` the\nworkflow playbooks use. The definition is pinned once per task, so the run\nhappens once per task.\n\n- Every action playbook whose trigger matches runs, in load order. A workflow\n playbook stops at the first match because it chooses one workflow; action\n playbooks choose nothing, so no match suppresses another.\n- A run never changes routing. The task is pinned by the workflow playbooks\n and bindings exactly as when no action playbook exists.\n- An action or playbook failure never parks or fails the task. It is logged\n at warning level with the playbook, the action and the task.\n- A task that already names a workflow (the approval requeue) is skipped, as\n it is for workflow playbooks.\n- Actions run synchronously in the pin path, bounded by the daemon's context.\n The only Module kind, `log`, returns immediately. A slow kind must bring its\n own timeout.\n\n## What one action does\n\nActions run in order against one evaluation context whose `actions` map\nstarts empty.\n\n1. Evaluate `when`. False or an evaluation error skips the action (J3). A\n skipped action records nothing and produces no result.\n2. Evaluate every `args` value. An evaluation error stops the playbook.\n3. Call `playbook.InvokeOnce` with the Module invoke as its function. The\n ledger row is written first. A duplicate row skips the invoke.\n4. An invoke error stops the playbook. The row stays, so the action is not\n retried: the ledger promises at most once, not at least once.\n5. On success, `ModuleRegistry.DecodeResult` converts the result, and it is\n stored as `actions.\u003cid\u003e.result` when the action declares an id.\n\nThe event id in the ledger key is `DispatchInput.TaskID`, the issue's\nidempotency key (`owner/repo/number`). An action therefore runs at most once\nper issue for each playbook version. Editing a playbook changes its version\nand lets it run again for issues it already handled.\n\nA skipped duplicate has no result. A later action that reads it sees a\nmissing field: its `when` evaluates false, or its args fail and the playbook\nstops. This only happens when the same issue is pinned twice under one\nplaybook version.\n\n## Wiring\n\n- `storecontract.PlaybookDispatcher` is lifted onto the daemon from the State\n Store client in `internal/app/archied/bootstrap.go`, the same way\n `BindingDispatcher` is.\n- The daemon's `Playbooks` dependency gains the run method. The Module\n registry is passed to the playbook store at load, so the daemon needs no\n new dependency for it.\n- With no `PlaybookDispatcher` wired, action playbooks do not run, and the\n boot warning names each one. They never run without the ledger.\n- The boot warning that action playbooks do not execute is removed when the\n ledger is wired.\n\n## Verification\n\n- A matching two-action `log` playbook runs both actions in order, and the\n second reads the first's result.\n- Pinning the same task twice under one playbook version invokes each action\n once.\n- A `when` that evaluates false skips that action and the run continues.\n- An invoke error stops the playbook. The task is still pinned to the same\n workflow it would get with no action playbook.\n- A non-matching trigger runs nothing.\n- With no ledger wired, nothing runs and the warning names the playbook.\n"
},
{
"url": "/dev/prds/adversarial-self-review/",
"title": "Adversarial self-review stage -- decision",
@@ -298,7 +304,7 @@
"url": "/dev/prds/multi-action-playbooks/",
"title": "Multi-action playbooks and typed action results",
"section": "PRDs",
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define. Arg VALUE type-checking\n is tracked as `archie-core-t2db` debt, not shipped here.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo a load failure; arg value\ntype-checking is tracked as `archie-core-t2db` debt.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a result, so it cannot feed `actions.\u0Line truncated
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
},
{
"url": "/dev/prds/news-and-releases/",
@@ -521,6 +527,10 @@
"title": "PRD writing rules",
"url": "/dev/prds/RULES/"
},
{
"title": "Running action playbooks",
"url": "/dev/prds/action-playbook-run/"
},
{
"title": "Adversarial self-review stage -- decision",
"url": "/dev/prds/adversarial-self-review/"
+11 -8
View File
@@ -75,13 +75,16 @@ naming the playbook and the offending action, for:
- 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.
- 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 a load failure; arg value
type-checking is tracked as `archie-core-t2db` debt.
kind's `Args` schema makes an arg-key typo or a wrongly typed value a load
failure.
## The environment is per playbook
@@ -110,8 +113,8 @@ yields a task, not a result, so it cannot feed `actions.<id>.result`.
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: arg KEY checking ships
now. Arg value type-checking is tracked as `archie-core-t2db` debt.
**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`
@@ -123,7 +126,7 @@ now. Arg value type-checking is tracked as `archie-core-t2db` debt.
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. Arg VALUE
type-checking is tracked as `archie-core-t2db` debt.
- 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.
+40 -1
View File
@@ -277,7 +277,7 @@ func (e *Env) Compile(src string) (*Program, error) {
return nil, err
}
ids, resolvable := actionReferences(ast)
return &Program{prg: prg, actionIDs: ids, resolvable: resolvable}, nil
return &Program{prg: prg, actionIDs: ids, resolvable: resolvable, outType: ast.OutputType()}, nil
}
// actionReferences walks the checked AST once and classifies every read of
@@ -328,6 +328,45 @@ type Program struct {
prg cel.Program
actionIDs []string
resolvable bool
outType *cel.Type
}
// Fits reports whether the program's checked output type can fill a Go value
// of type t. A dyn output fits anything: its type is known only per
// evaluation. A Go type with no CEL scalar counterpart is not checked here.
func (p *Program) Fits(t reflect.Type) bool {
if p.outType == nil || p.outType.Kind() == types.DynKind {
return true
}
want, ok := celScalar(t)
return !ok || want.IsExactType(p.outType)
}
// OutputType is the program's checked output type, for error messages.
func (p *Program) OutputType() string {
if p.outType == nil {
return "dyn"
}
return p.outType.String()
}
// celScalar maps a Go scalar kind to the CEL type an expression must produce
// to fill it.
func celScalar(t reflect.Type) (*cel.Type, bool) {
switch t.Kind() {
case reflect.String:
return cel.StringType, true
case reflect.Bool:
return cel.BoolType, true
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
return cel.IntType, true
case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
return cel.UintType, true
case reflect.Float32, reflect.Float64:
return cel.DoubleType, true
default:
return nil, false
}
}
// ActionReferences reports the action ids the expression reads from the
+26
View File
@@ -448,6 +448,27 @@ func argsLabel(label, key string) string {
return fmt.Sprintf("%s args[%q]", label, key)
}
// checkArgType refuses an args value whose checked CEL type cannot fill the
// Args field it names. A dyn value passes: the module decode checks it per
// event.
func checkArgType(path, label, kind string, argsSchema reflect.Type, key string, prg *expr.Program) error {
t := argsSchema
if t.Kind() == reflect.Pointer {
t = t.Elem()
}
for field := range t.Fields() {
if strings.ToLower(field.Name) != key || prg.Fits(field.Type) {
continue
}
loc := kind + " kind"
if label != "" {
loc = label + " " + loc
}
return fmt.Errorf("playbook %s: %s args[%q] is %s, want %s", path, loc, key, prg.OutputType(), field.Type)
}
return nil
}
// compileArgs compiles every args value as a CEL expression at load, keyed by
// arg name. J2 has no literal/expression split: the YAML scalar text IS the
// CEL source, so a string literal is quoted inside YAML and a number or
@@ -476,6 +497,11 @@ func compileArgs(path, label, kind string, raw map[string]string, env *expr.Env,
if err != nil {
return nil, err
}
if argsSchema != nil {
if err := checkArgType(path, label, kind, argsSchema, key, prg); err != nil {
return nil, err
}
}
args[key] = prg
}
return args, nil
@@ -1443,3 +1443,36 @@ func TestLoadActionPlaybookRejectsActionReferences(t *testing.T) {
})
}
}
// An args value whose static CEL type cannot fill the kind's Args field fails
// the load, naming the key. A dyn value (an event read) is accepted: its type
// is known only per event, and the module decode refuses a bad one at run.
func TestLoadArgsValueTypeAgainstArgsSchema(t *testing.T) {
tests := []struct {
name string
message string
wantErr bool
}{
{name: "string literal", message: `'"hello"'`},
{name: "string concatenation", message: `'"n=" + string(1)'`},
{name: "dyn event read", message: `event.title`},
{name: "int literal", message: `'123'`, wantErr: true},
{name: "bool expression", message: `'1 == 1'`, wantErr: true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "pb.yaml", "trigger:\n kind: bug\nactions:\n - position: module\n kind: log\n args:\n message: "+tt.message+"\n")
_, err := Load(dir, testSchemas(t))
if !tt.wantErr {
if err != nil {
t.Fatalf("Load: %v", err)
}
return
}
if err == nil || !strings.Contains(err.Error(), `args["message"]`) || !strings.Contains(err.Error(), "string") {
t.Fatalf("Load error = %v, want args[\"message\"] refused for not being a string", err)
}
})
}
}