diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 72253cb22..9a18dcca1 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a result, so it cannot feed `actions.\u003cid\u003e.result`.\n\n**D3 — the CEL typing mechanism.** Settled: a per-playbook environment whose\n`actions` root is an object type with one field per declared id, each field typed\nby the kind's `Result` struct. `internal/domain/eda/expr` implements it with the\ngeneric `actionResultProvider`.\n\n**D4 — `args` against the kind's `Args` schema.** Settled: keys and statically\ntyped values are checked at load; `dyn` values are checked by the module decode.\n\n**D5 — where the result map becomes the `Result` struct.** Settled:\n`ModuleRegistry` stays schema-agnostic. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the conversion site.\n\n## Verification\n\n- A two-action `module` playbook with a valid `actions.\u003cid\u003e.result.\u003cfield\u003e` read\n loads; the same read of a field the kind's `Result` does not define fails the\n load naming the field; a read of an id no earlier action declares fails; a\n dynamically indexed `actions` read fails.\n- An arg KEY the kind's `Args` schema does not define fails the load, and so\n does `message: '123'` for the `log` kind. `message: event.title` loads.\n- The one-action `workflow` playbook shape, its dispatch, and its existing\n load-time checks are unchanged.\n" + "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.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a result, so it cannot feed `actions.\u003cid\u003e.result`.\n\n**D3 — the CEL typing mechanism.** Settled: a per-playbook environment whose\n`actions` root is an object type with one field per declared id, each field typed\nby the kind's `Result` struct. `internal/domain/eda/expr` implements it with the\ngeneric `actionResultProvider`.\n\n**D4 — `args` against the kind's `Args` schema.** Settled: keys and statically\ntyped values are checked at load; `dyn` values are checked by the module decode.\n\n**D5 — where the result map becomes the `Result` struct.** Settled:\n`ModuleRegistry` stays schema-agnostic. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the conversion site. It accepts a value only\nwhen it already carries the field's declared type, and a map only when it\ncarries every declared field. A conversion changes the value's representation --\na number for a string field is the named case -- and an absent field reads as the\nzero value, so each is reported rather than becoming a quietly wrong value in a\nlater expression.\n\n## Verification\n\n- A two-action `module` playbook with a valid `actions.\u003cid\u003e.result.\u003cfield\u003e` read\n loads; the same read of a field the kind's `Result` does not define fails the\n load naming the field; a read of an id no earlier action declares fails; a\n dynamically indexed `actions` read fails.\n- An arg KEY the kind's `Args` schema does not define fails the load, and so\n does `message: '123'` for the `log` kind. `message: event.title` loads.\n- A result map missing a declared field, and one whose value is not already the\n field's type, are both reported by the decode; a value that would only be\n convertible (a number for a string field) is not accepted.\n- The one-action `workflow` playbook shape, its dispatch, and its existing\n load-time checks are unchanged.\n" }, { "url": "/dev/prds/news-and-releases/", diff --git a/docs/prds/multi-action-playbooks.md b/docs/prds/multi-action-playbooks.md index af42a8cbf..76fefaa94 100644 --- a/docs/prds/multi-action-playbooks.md +++ b/docs/prds/multi-action-playbooks.md @@ -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. diff --git a/internal/domain/eda/module/module.go b/internal/domain/eda/module/module.go index a8be6201a..e2efd131d 100644 --- a/internal/domain/eda/module/module.go +++ b/internal/domain/eda/module/module.go @@ -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..result.`). 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 } diff --git a/internal/domain/eda/module/module_test.go b/internal/domain/eda/module/module_test.go index 7c46d01c0..ac978ec6e 100644 --- a/internal/domain/eda/module/module_test.go +++ b/internal/domain/eda/module/module_test.go @@ -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") }