fix(eda): reject a result map missing a field or needing a conversion
DecodeResult accepted any value reflect could convert, so a number for a string field silently became the rune string (42 became "*"), and a declared field absent from the map read as its zero value. Both are now reported: a value is accepted only at the field's declared type, and every declared field must be present. That is the boundary the typed CEL environment promises, and it is live now that the action runner decodes every result into actions.<id>.result before a later expression reads it. D5 in docs/prds/multi-action-playbooks.md records the rule.
This commit is contained in:
4 files changed
+112
-22
No files matched your search
@@ -376,7 +376,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;\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
|
||||
"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/",
|
||||
|
||||
@@ -118,7 +118,12 @@ typed values are checked at load; `dyn` values are checked by the module decode.
|
||||
|
||||
**D5 — where the result map becomes the `Result` struct.** Settled:
|
||||
`ModuleRegistry` stays schema-agnostic. `ModuleRegistry.DecodeResult`
|
||||
(`internal/domain/eda/module`) is the conversion site.
|
||||
(`internal/domain/eda/module`) is the conversion site. It accepts a value only
|
||||
when it already carries the field's declared type, and a map only when it
|
||||
carries every declared field. A conversion changes the value's representation --
|
||||
a number for a string field is the named case -- and an absent field reads as the
|
||||
zero value, so each is reported rather than becoming a quietly wrong value in a
|
||||
later expression.
|
||||
|
||||
## Verification
|
||||
|
||||
@@ -128,5 +133,8 @@ typed values are checked at load; `dyn` values are checked by the module decode.
|
||||
dynamically indexed `actions` read fails.
|
||||
- An arg KEY the kind's `Args` schema does not define fails the load, and so
|
||||
does `message: '123'` for the `log` kind. `message: event.title` loads.
|
||||
- A result map missing a declared field, and one whose value is not already the
|
||||
field's type, are both reported by the decode; a value that would only be
|
||||
convertible (a number for a string field) is not accepted.
|
||||
- The one-action `workflow` playbook shape, its dispatch, and its existing
|
||||
load-time checks are unchanged.
|
||||
@@ -235,7 +235,8 @@ func (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[st
|
||||
// CEL expression reads is the same Go struct the expression environment typed
|
||||
// (`actions.<id>.result.<field>`). The map is keyed by the lower-cased Go
|
||||
// field name, the same spelling expr registers as the CEL field name. An
|
||||
// unknown field or a wrong-typed value is a reported error.
|
||||
// unknown field, an absent declared field, or a value that is not already the
|
||||
// field's type is a reported error.
|
||||
func (r *ModuleRegistry) DecodeResult(kind string, raw map[string]any) (any, error) {
|
||||
k, ok := registry[kind]
|
||||
if !ok {
|
||||
@@ -246,7 +247,11 @@ func (r *ModuleRegistry) DecodeResult(kind string, raw map[string]any) (any, err
|
||||
|
||||
// decodeResultStruct marshals raw into a new value of the kind's Result
|
||||
// struct type, keyed by the lower-cased Go field name -- the same spelling
|
||||
// expr registers as the CEL field name.
|
||||
// expr registers as the CEL field name. Every declared field must be present
|
||||
// and every value must already carry that field's type: a missing field would
|
||||
// read as the zero value, and a conversion would change the value's
|
||||
// representation, so both are reported rather than becoming a quietly wrong
|
||||
// value in a later expression.
|
||||
func decodeResultStruct(kind string, t reflect.Type, raw map[string]any) (any, error) {
|
||||
if t == nil {
|
||||
return nil, fmt.Errorf("module %s: result schema is not set", kind)
|
||||
@@ -259,40 +264,55 @@ func decodeResultStruct(kind string, t reflect.Type, raw map[string]any) (any, e
|
||||
}
|
||||
|
||||
out := reflect.New(t).Elem()
|
||||
fields := make(map[string]reflect.Value, t.NumField())
|
||||
type declaredField struct {
|
||||
name string
|
||||
value reflect.Value
|
||||
}
|
||||
declared := make([]declaredField, 0, t.NumField())
|
||||
byName := make(map[string]reflect.Value, t.NumField())
|
||||
for i := 0; i < t.NumField(); i++ {
|
||||
f := t.Field(i)
|
||||
if !out.Field(i).CanSet() {
|
||||
continue
|
||||
}
|
||||
fields[strings.ToLower(f.Name)] = out.Field(i)
|
||||
name := strings.ToLower(t.Field(i).Name)
|
||||
declared = append(declared, declaredField{name: name, value: out.Field(i)})
|
||||
byName[name] = out.Field(i)
|
||||
}
|
||||
for key, val := range raw {
|
||||
fv, ok := fields[key]
|
||||
if !ok {
|
||||
|
||||
keys := make([]string, 0, len(raw))
|
||||
for key := range raw {
|
||||
keys = append(keys, key)
|
||||
}
|
||||
sort.Strings(keys)
|
||||
for _, key := range keys {
|
||||
if _, ok := byName[key]; !ok {
|
||||
return nil, fmt.Errorf("module %s: unknown result field %q", kind, key)
|
||||
}
|
||||
if err := setResultField(kind, key, fv, val); err != nil {
|
||||
}
|
||||
for _, f := range declared {
|
||||
val, ok := raw[f.name]
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("module %s: result field %q is missing, want %s", kind, f.name, f.value.Type())
|
||||
}
|
||||
if err := setResultField(kind, f.name, f.value, val); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
}
|
||||
return out.Interface(), nil
|
||||
}
|
||||
|
||||
// setResultField assigns val to fv, converting compatible Go types. A nil or
|
||||
// incompatible value is a reported error, never a silent zero-value fill.
|
||||
// setResultField assigns val to fv only when val's type is the field's type. A
|
||||
// conversion would change the value's representation -- a number silently
|
||||
// becoming a string is the named case -- so it is refused, as are a nil and a
|
||||
// wrong-typed value. Nothing here zero-fills.
|
||||
func setResultField(kind, field string, fv reflect.Value, val any) error {
|
||||
if val == nil {
|
||||
return fmt.Errorf("module %s: result.%s is nil, want %s", kind, field, fv.Type())
|
||||
}
|
||||
rv := reflect.ValueOf(val)
|
||||
if rv.Type().AssignableTo(fv.Type()) {
|
||||
fv.Set(rv)
|
||||
return nil
|
||||
if !rv.Type().AssignableTo(fv.Type()) {
|
||||
return fmt.Errorf("module %s: result.%s is %T, want %s", kind, field, val, fv.Type())
|
||||
}
|
||||
if rv.Type().ConvertibleTo(fv.Type()) {
|
||||
fv.Set(rv.Convert(fv.Type()))
|
||||
return nil
|
||||
}
|
||||
return fmt.Errorf("module %s: result.%s is %T, want %s", kind, field, val, fv.Type())
|
||||
fv.Set(rv)
|
||||
return nil
|
||||
}
|
||||
@@ -169,9 +169,71 @@ func Run(a log.Args) log.Result {
|
||||
}
|
||||
}
|
||||
|
||||
// TestDecodeResultRejectsSchemaViolations pins the strict schema boundary:
|
||||
// every declared Result field must be present, and a value is accepted only
|
||||
// when its type is the field's type. An absent field would read as the zero
|
||||
// value, and a conversion changes the value's representation -- a number
|
||||
// silently becoming a string is the named case -- so both are failures rather
|
||||
// than a quietly wrong value in a later expression.
|
||||
func TestDecodeResultRejectsSchemaViolations(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
raw map[string]any
|
||||
wants []string
|
||||
}{
|
||||
{
|
||||
name: "absent field",
|
||||
raw: map[string]any{"written": true},
|
||||
wants: []string{"log", `result field "level"`, "missing"},
|
||||
},
|
||||
{
|
||||
name: "number where a string field is declared",
|
||||
raw: map[string]any{"written": true, "level": 42},
|
||||
wants: []string{"log", "result.level", "int", "want string"},
|
||||
},
|
||||
{
|
||||
name: "string where a bool field is declared",
|
||||
raw: map[string]any{"written": "true", "level": "info"},
|
||||
wants: []string{"log", "result.written", "want bool"},
|
||||
},
|
||||
}
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
r := New()
|
||||
got, err := r.DecodeResult("log", tc.raw)
|
||||
if err == nil {
|
||||
t.Fatalf("DecodeResult(%v) = %#v, want an error", tc.raw, got)
|
||||
}
|
||||
for _, want := range tc.wants {
|
||||
if !strings.Contains(err.Error(), want) {
|
||||
t.Errorf("DecodeResult error = %q, want it to contain %q", err.Error(), want)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestDecodeResultAcceptsEveryFieldAtItsType is the other half of the strict
|
||||
// boundary: a complete map whose values already carry the schema's types
|
||||
// decodes unchanged.
|
||||
func TestDecodeResultAcceptsEveryFieldAtItsType(t *testing.T) {
|
||||
r := New()
|
||||
got, err := r.DecodeResult("log", map[string]any{"written": true, "level": "info"})
|
||||
if err != nil {
|
||||
t.Fatalf("DecodeResult: %v", err)
|
||||
}
|
||||
result, ok := got.(log.Result)
|
||||
if !ok {
|
||||
t.Fatalf("DecodeResult returned %T, want log.Result", got)
|
||||
}
|
||||
if want := (log.Result{Written: true, Level: "info"}); result != want {
|
||||
t.Fatalf("DecodeResult = %#v, want %#v", result, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDecodeResultUnknownFieldIsError(t *testing.T) {
|
||||
r := New()
|
||||
_, err := r.DecodeResult("log", map[string]any{"written": true, "bogus": "x"})
|
||||
_, err := r.DecodeResult("log", map[string]any{"written": true, "level": "info", "bogus": "x"})
|
||||
if err == nil {
|
||||
t.Fatal("DecodeResult(unknown field) = nil, want error")
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user