fix(eda): authoritative module ids and stricter action load errors

This commit is contained in:
sam committed 2026-09-22 09:41:31 +10:00
1 parent 85a671491f
commit f498f593c9
8 files changed
+361 -45

No files matched your search

+5 -2
View File
@@ -60,8 +60,11 @@ checker validates and the value the run reads have one definition.
Relaxing the boundary must not make a bad reference resolvable. The load fails,
naming the playbook and the offending action, for:
- an `id` missing where a later action references it, duplicated, or not a
stable identifier (J1, already enforced);
- an `id` missing where a later action references it, duplicated, or outside
its shape's grammar: a workflow action id keeps the shared
stable-identifier grammar (J1, already enforced), while a module action id
must be a lowercase CEL field name writable as `actions.<id>` (so a CEL
keyword such as `in`, `true`, `false`, or `null` is rejected at load);
- an `actions.<id>` read of an id no earlier action declares;
- an `actions` read that is not statically resolvable to an id (a dynamic
index, `in`, a comprehension — already enforced);
+7 -5
View File
@@ -104,16 +104,17 @@ 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` | `map(string, dyn)` | Previous actions' results, keyed by the action's `id` as declared in the playbook (`actions.<id>.result.<field>`), so a later action reads an earlier one's `Result` map regardless of position. The current action and later actions are not present. |
| `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.
`actions.<id>.result` is the `map[string]any` `Module.Invoke` already
returns (`archie-core-t2db.13`), so no result-shape change is needed for data flow;
channel/forge kinds' results are declared to the same shape.
`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.
Judgement call J1: `action` id is a required field on every action
that later actions reference; ids are validated at load (unique,
@@ -133,7 +134,8 @@ same way, at playbook load:
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 `map(string, dyn)`),
(`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
+2 -1
View File
@@ -463,7 +463,8 @@ type Config struct {
// conditions, dispatched by the event coordinator). This is DISTINCT
// from PlaybookDirs, which holds FLAT binding files (kind/label ->
// workflow name) consumed by the routing loaders. A playbook here is a
// document (one trigger, one action in this slice); a binding file there
// document (one trigger plus ordered actions: either exactly one
// workflow action or one or more module actions); a binding file there
// is a map of keys. When empty, no EDA playbook documents are loaded.
EDAPlaybookDir string `toml:"eda_playbook_dir" yaml:"eda_playbook_dir"`
// MaxRetries caps how many times a parked task is retried before
+22
View File
@@ -44,6 +44,28 @@ type DeclaredResult struct {
Type reflect.Type
}
// probeResult is the placeholder Result type used by IsCELFieldName's probe
// environment. It is a struct only so it satisfies the native type registry;
// its fields are never read.
type probeResult struct{}
// IsCELFieldName reports whether id can be written as `actions.<id>` in a CEL
// expression. It is the authoritative check the playbook loader uses for a
// module action id, replacing a regex approximation of CEL's token rules: it
// compiles a probe expression against a one-field environment declaring the
// id, so the CEL parser and checker decide. CEL keywords (`in`, `true`,
// `false`, `null`) and any other spelling with no field-selection form return
// false; a valid CEL identifier such as `Build` returns true (the loader adds
// its own lowercase policy on top).
func IsCELFieldName(id string) bool {
if id == "" {
return false
}
env := NewEnv(DeclaredResult{ID: id, Type: reflect.TypeFor[probeResult]()})
_, err := env.Compile("actions." + id)
return err == nil
}
// Env is the CEL environment for playbook expressions: the declared context
// roots and the default cost limit applied to every compiled program.
type Env struct {
+18
View File
@@ -83,6 +83,24 @@ func TestCompileDynamicActionAccessRejected(t *testing.T) {
}
}
// TestIsCELFieldName proves the authoritative module-id gate the playbook
// loader uses: a normal id is accepted, and a CEL keyword or any spelling with
// no `actions.<id>` field-selection form is rejected. `Build` is asserted
// true here to show the check reports CEL referenceability, not the loader's
// separate lowercase policy.
func TestIsCELFieldName(t *testing.T) {
for _, id := range []string{"build", "step_2", "x9", "Build"} {
if !IsCELFieldName(id) {
t.Errorf("IsCELFieldName(%q) = false, want true", id)
}
}
for _, id := range []string{"in", "true", "false", "null", "build.step", "build-step", ""} {
if IsCELFieldName(id) {
t.Errorf("IsCELFieldName(%q) = true, want false", id)
}
}
}
// TestEvalDeclaredResultRead: a declared id's result read evaluates against a
// map whose id entry wraps the Go Result struct in `{result: ...}`.
func TestEvalDeclaredResultRead(t *testing.T) {
+15 -2
View File
@@ -64,9 +64,16 @@ func TestRegisterUnknownKindIsError(t *testing.T) {
func TestKindSchema(t *testing.T) {
r := New()
if _, _, ok := r.KindSchema("log"); !ok {
argsType, resultType, ok := r.KindSchema("log")
if !ok {
t.Fatal("KindSchema(log) = not ok, want the built-in log contract")
}
if want := reflect.TypeFor[log.Args](); argsType != want {
t.Errorf("KindSchema(log) args type = %v, want %v", argsType, want)
}
if want := reflect.TypeFor[log.Result](); resultType != want {
t.Errorf("KindSchema(log) result type = %v, want %v", resultType, want)
}
if _, _, ok := r.KindSchema("notify"); ok {
t.Fatal("KindSchema(notify) = ok, want false for an unregistered kind")
}
@@ -164,9 +171,15 @@ func Run(a log.Args) log.Result {
func TestDecodeResultUnknownFieldIsError(t *testing.T) {
r := New()
if _, err := r.DecodeResult("log", map[string]any{"written": true, "bogus": "x"}); err == nil {
_, err := r.DecodeResult("log", map[string]any{"written": true, "bogus": "x"})
if err == nil {
t.Fatal("DecodeResult(unknown field) = nil, want error")
}
for _, want := range []string{"bogus", "unknown result field"} {
if !strings.Contains(err.Error(), want) {
t.Errorf("DecodeResult error = %q, want it to contain %q", err.Error(), want)
}
}
}
func TestInvokePanicRecovered(t *testing.T) {
+78 -27
View File
@@ -104,9 +104,10 @@ type Action struct {
// env is the per-action CEL environment this action's expressions were
// compiled against: the prior actions' declared ids and their kinds'
// Result types. It is also the eval receiver for When/Args. It is unset
// only for a hand-built Action (tests, pre-load composition); loaded
// actions always carry it.
// Result types. It is compile-only: expr.Env.Eval reads only the
// compiled Program (the cost limit is baked in at Compile) and never
// reads the Env receiver. It is unset only for a hand-built Action
// (tests, pre-load composition); loaded actions always carry it.
env *expr.Env
}
@@ -135,14 +136,15 @@ type rawAction struct {
// internal/plugin/host.go:21 and internal/domain/workflow/vocabulary.go:19),
// so an id has exactly one spelling and cannot smuggle whitespace or case into
// the vocabulary two processes compare. Module action ids are stricter (see
// actionIDCELPattern) because they must also be CEL field selections.
// validateModuleActionIDs) because they must also be CEL field selections.
var actionIDPattern = regexp.MustCompile(`^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`)
// actionIDCELPattern is the id shape for MODULE actions: a lowercase CEL
// identifier. `actions.<id>` is CEL field selection, and a `.` or `-` in an id
// has no field-selection spelling, so a dotted/dashed id would load yet could
// never be referenced.
var actionIDCELPattern = regexp.MustCompile(`^[a-z][a-z0-9_]*$`)
// Module action ids are stricter than workflow ids because they must also be
// readable as `actions.<id>` in CEL field selection. The authoritative check
// is expr.IsCELFieldName (which compiles the probe), plus a lowercase policy:
// the id must be a lowercase CEL field name, so `Build` -- a valid CEL
// identifier -- is rejected for its case, while a CEL keyword such as `in` is
// rejected because `actions.in` has no field-selection spelling.
// validateActionIDs enforces the WORKFLOW id shape and uniqueness. An absent
// id is fine (ids are optional); a declared id must match the
@@ -167,9 +169,9 @@ func validateActionIDs(actions []rawAction) error {
}
// validateModuleActionIDs enforces the MODULE id shape and uniqueness. A
// module id must be a CEL identifier (not the looser workflow
// stable-identifier grammar) and may not repeat; the error names the
// playbook and the offending id.
// module id must be a lowercase CEL field name writable as `actions.<id>`
// (stricter than the workflow stable-identifier grammar) and may not repeat;
// the error names the playbook, the action index, and the offending id.
func validateModuleActionIDs(path string, actions []rawAction) error {
seen := make(map[string]struct{}, len(actions))
for i, a := range actions {
@@ -177,8 +179,8 @@ func validateModuleActionIDs(path string, actions []rawAction) error {
if id == "" {
continue
}
if !actionIDCELPattern.MatchString(id) {
return fmt.Errorf("playbook %s: action %d id %q is not a valid CEL identifier (want %s)", path, i+1, id, actionIDCELPattern.String())
if id != strings.ToLower(id) || !expr.IsCELFieldName(id) {
return fmt.Errorf("playbook %s: action %d id %q must be a lowercase CEL field name writable as actions.%s", path, i+1, id, id)
}
if _, dup := seen[id]; dup {
return fmt.Errorf("playbook %s: duplicate action id %q", path, id)
@@ -296,6 +298,9 @@ func compileActions(path string, raw []rawAction, schemas KindSchemas) ([]Action
return nil, fmt.Errorf("playbook %s: action %d position %q is not supported (want %q or %q)", path, i+1, pos, "workflow", "module")
}
a.Position = pos
if err := validateActionShapeField(path, i, pos, a); err != nil {
return nil, err
}
if pos == "workflow" {
workflows++
} else {
@@ -316,6 +321,25 @@ func compileActions(path string, raw []rawAction, schemas KindSchemas) ([]Action
}
}
// validateActionShapeField rejects a field from the other shape being present
// on an action: a workflow action must not declare kind (module-only), and a
// module action must not declare workflow (workflow-only). yaml.Unmarshal
// accepts both keys, so this is where a silently-ignored foreign key becomes
// a reported load failure naming the playbook and the action index.
func validateActionShapeField(path string, i int, pos string, a *rawAction) error {
switch pos {
case "workflow":
if strings.TrimSpace(a.Kind) != "" {
return fmt.Errorf("playbook %s: action %d is a workflow action and must not declare kind", path, i+1)
}
case "module":
if strings.TrimSpace(a.Workflow) != "" {
return fmt.Errorf("playbook %s: action %d is a module action and must not declare workflow", path, i+1)
}
}
return nil
}
// compileWorkflowActions builds the single-action workflow playbook shape.
// The env has no prior result ids, so a workflow `when` or `args` value that
// reads `actions.<id>` fails at compile -- the unchanged workflow behaviour.
@@ -342,7 +366,7 @@ func compileWorkflowActions(path string, raw []rawAction) ([]Action, error) {
}
action.When = prg
}
args, err := compileArgs(path, "", a.Args, env, nil)
args, err := compileArgs(path, "", "", a.Args, env, nil)
if err != nil {
return nil, err
}
@@ -360,14 +384,16 @@ func compileModuleActions(path string, raw []rawAction, schemas KindSchemas) ([]
}
actions := make([]Action, 0, len(raw))
var declared []expr.DeclaredResult
for _, a := range raw {
for i := range raw {
a := &raw[i]
label := actionLabel(i, a.ID)
kind := strings.TrimSpace(a.Kind)
if kind == "" {
return nil, fmt.Errorf("playbook %s: module-kind action must name a kind", path)
return nil, fmt.Errorf("playbook %s: %s must name a kind", path, label)
}
argsType, resultType, ok := schemas.KindSchema(kind)
if !ok {
return nil, fmt.Errorf("playbook %s: unknown module kind %q", path, kind)
return nil, fmt.Errorf("playbook %s: %s has unknown module kind %q", path, label, kind)
}
env := expr.NewEnv(declared...)
@@ -378,13 +404,13 @@ func compileModuleActions(path string, raw []rawAction, schemas KindSchemas) ([]
env: env,
}
if strings.TrimSpace(a.When) != "" {
prg, err := compileExpr(path, "when condition", a.When, env)
prg, err := compileExpr(path, label+" when condition", a.When, env)
if err != nil {
return nil, err
}
action.When = prg
}
args, err := compileArgs(path, kind, a.Args, env, argsType)
args, err := compileArgs(path, label, kind, a.Args, env, argsType)
if err != nil {
return nil, err
}
@@ -398,20 +424,41 @@ func compileModuleActions(path string, raw []rawAction, schemas KindSchemas) ([]
return actions, nil
}
// actionLabel renders the 1-based action location used in module-action load
// errors, including the declared id when present so an operator can find the
// offending action by either index or id.
func actionLabel(i int, id string) string {
id = strings.TrimSpace(id)
if id == "" {
return fmt.Sprintf("action %d", i+1)
}
return fmt.Sprintf("action %d (id %q)", i+1, id)
}
// argsLabel prefixes an args-key location with the action label when one is
// supplied; workflow actions pass an empty label and keep the bare
// `args["key"]` spelling.
func argsLabel(label, key string) string {
if label == "" {
return fmt.Sprintf("args[%q]", key)
}
return fmt.Sprintf("%s args[%q]", label, key)
}
// 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
// context read is written as CEL. When argsSchema is non-nil (a module kind's
// Args struct) every key must name one of its fields; workflow actions pass
// nil and keep free-form args. Each program goes through the same
// compile/reference validation as `when`, with the field label naming the
// offending args key.
func compileArgs(path, kind string, raw map[string]string, env *expr.Env, argsSchema reflect.Type) (map[string]*expr.Program, error) {
// compile/reference validation as `when`, with label naming the offending
// action and the args key naming the offending field.
func compileArgs(path, label, kind string, raw map[string]string, env *expr.Env, argsSchema reflect.Type) (map[string]*expr.Program, error) {
if len(raw) == 0 {
return nil, nil
}
if argsSchema != nil {
if err := validateArgsKeys(path, kind, argsSchema, raw); err != nil {
if err := validateArgsKeys(path, label, kind, argsSchema, raw); err != nil {
return nil, err
}
}
@@ -422,7 +469,7 @@ func compileArgs(path, kind string, raw map[string]string, env *expr.Env, argsSc
sort.Strings(keys)
args := make(map[string]*expr.Program, len(raw))
for _, key := range keys {
prg, err := compileExpr(path, fmt.Sprintf("args[%q]", key), raw[key], env)
prg, err := compileExpr(path, argsLabel(label, key), raw[key], env)
if err != nil {
return nil, err
}
@@ -437,7 +484,7 @@ func compileArgs(path, kind string, raw map[string]string, env *expr.Env, argsSc
// YAML spelling (Message -> message), and the YAML key is compared verbatim:
// the decoder also matches literal lower-case keys, so `Message` is rejected
// here rather than loading and then failing at dispatch.
func validateArgsKeys(path, kind string, argsSchema reflect.Type, raw map[string]string) error {
func validateArgsKeys(path, label, kind string, argsSchema reflect.Type, raw map[string]string) error {
t := argsSchema
if t.Kind() == reflect.Pointer {
t = t.Elem()
@@ -451,9 +498,13 @@ func validateArgsKeys(path, kind string, argsSchema reflect.Type, raw map[string
keys = append(keys, key)
}
sort.Strings(keys)
loc := kind + " kind"
if label != "" {
loc = label + " " + loc
}
for _, key := range keys {
if _, ok := fields[key]; !ok {
return fmt.Errorf("playbook %s: %s kind args[%q] is not a declared Args field", path, kind, key)
return fmt.Errorf("playbook %s: %s args[%q] is not a declared Args field", path, loc, key)
}
}
return nil
+214 -8
View File
@@ -699,7 +699,7 @@ func TestCompileArgsReportsFirstKeyDeterministically(t *testing.T) {
"a.bad": "event.missing ==",
}
for range 64 {
_, err := compileArgs("pb.yaml", "", raw, env, nil)
_, err := compileArgs("pb.yaml", "", "", raw, env, nil)
if err == nil {
t.Fatal("compileArgs = nil, want error")
}
@@ -725,7 +725,7 @@ func TestValidateArgsKeysReportsFirstKeyDeterministically(t *testing.T) {
"a.bad": "x",
}
for range 64 {
err := validateArgsKeys("pb.yaml", "log", argsType, raw)
err := validateArgsKeys("pb.yaml", "", "log", argsType, raw)
if err == nil {
t.Fatal("validateArgsKeys = nil, want error")
}
@@ -877,6 +877,210 @@ actions:
}
}
// TestLoadActionPlaybookArgsValueReadsPriorResult: the approved doc's own
// example reads a prior action's result inside a later action's args VALUE
// (not only inside `when`). That spelling must compile and load through the
// real loader.
func TestLoadActionPlaybookArgsValueReadsPriorResult(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "pb.yaml", `
trigger:
kind: bug
actions:
- id: build
position: module
kind: log
args:
message: '"build started"'
- id: done
position: module
kind: log
args:
message: '"done: " + string(actions.build.result.written)'
`)
store, err := Load(dir, testSchemas(t))
if err != nil {
t.Fatalf("Load(args value reading a prior result): %v", err)
}
if got := len(store.Playbooks); got != 1 {
t.Fatalf("loaded %d playbooks, want 1", got)
}
if store.Playbooks[0].Actions[1].Args["message"] == nil {
t.Fatal("second action args[message] = nil, want the compiled prior-result read")
}
}
// TestLoadRejectsShapeForeignFields: a shape-foreign field is a reject-at-load
// error naming the playbook and the action index, not a silently dropped key.
func TestLoadRejectsShapeForeignFields(t *testing.T) {
tests := []struct {
name string
doc string
want []string
}{
{
name: "module action carrying workflow",
doc: `
trigger:
kind: bug
actions:
- position: module
kind: log
workflow: tdd
args:
message: '"hello"'
`,
want: []string{"pb.yaml", "action 1", "workflow"},
},
{
name: "workflow action carrying kind",
doc: `
trigger:
kind: bug
actions:
- position: workflow
workflow: tdd
kind: log
`,
want: []string{"pb.yaml", "action 1", "kind"},
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "pb.yaml", tc.doc)
_, err := Load(dir, testSchemas(t))
if err == nil {
t.Fatal("Load = nil, want load failure")
}
for _, want := range tc.want {
if !strings.Contains(err.Error(), want) {
t.Errorf("Load error = %q, want it to contain %q", err.Error(), want)
}
}
})
}
}
// TestLoadModuleActionErrorsNameActionLocation: module-action load failures
// name the 1-based index and the declared id (when present) of the offending
// action, not just the field label, so an operator can locate the action.
func TestLoadModuleActionErrorsNameActionLocation(t *testing.T) {
tests := []struct {
name string
doc string
want []string
}{
{
name: "when compile error",
doc: `
trigger:
kind: bug
actions:
- id: build
position: module
kind: log
args:
message: '"build"'
- id: done
position: module
kind: log
args:
message: '"done"'
when: event.label ==
`,
want: []string{"pb.yaml", "action 2", "done", "when condition"},
},
{
name: "args value compile error",
doc: `
trigger:
kind: bug
actions:
- id: build
position: module
kind: log
args:
message: '"build"'
- id: done
position: module
kind: log
args:
message: 'foo.bar == 1'
`,
want: []string{"pb.yaml", "action 2", "done", `args["message"]`},
},
{
name: "unknown kind",
doc: `
trigger:
kind: bug
actions:
- id: build
position: module
kind: log
args:
message: '"build"'
- id: done
position: module
kind: notify
`,
want: []string{"pb.yaml", "action 2", "done", "notify"},
},
{
name: "missing kind",
doc: `
trigger:
kind: bug
actions:
- id: build
position: module
kind: log
args:
message: '"build"'
- id: done
position: module
`,
want: []string{"pb.yaml", "action 2", "done"},
},
{
name: "unknown arg key",
doc: `
trigger:
kind: bug
actions:
- id: build
position: module
kind: log
args:
message: '"build"'
- id: done
position: module
kind: log
args:
message: '"done"'
bogus: '"x"'
`,
want: []string{"pb.yaml", "action 2", "done", "bogus"},
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "pb.yaml", tc.doc)
_, err := Load(dir, testSchemas(t))
if err == nil {
t.Fatal("Load = nil, want load failure")
}
for _, want := range tc.want {
if !strings.Contains(err.Error(), want) {
t.Errorf("Load error = %q, want it to contain %q", err.Error(), want)
}
}
})
}
}
// TestLoadActionPlaybookForwardReferenceFails: an action may not read a later
// action's id -- the env only declares PRIOR actions' ids, so the forward read
// is an undefined field at compile.
@@ -1063,20 +1267,22 @@ actions:
}
}
// TestLoadActionPlaybookRejectsNonCELID: a module action id must be a CEL
// identifier, so a dotted/dashed id (legal for a workflow id) loads nowhere.
// TestLoadActionPlaybookRejectsNonCELID: a module action id must be a
// lowercase CEL field name writable as `actions.<id>`, so a dotted/dashed id
// (legal for a workflow id), an uppercase id, or a CEL keyword all fail the
// load naming the id.
func TestLoadActionPlaybookRejectsNonCELID(t *testing.T) {
for _, id := range []string{"build.step", "build-step", "Build"} {
for _, id := range []string{"build.step", "build-step", "Build", "in", "true", "false", "null"} {
t.Run(id, func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "pb.yaml", "\ntrigger:\n kind: bug\nactions:\n - id: "+id+"\n position: module\n kind: log\n args:\n message: '\"hello\"'\n")
writeFile(t, dir, "pb.yaml", "\ntrigger:\n kind: bug\nactions:\n - id: '"+id+"'\n position: module\n kind: log\n args:\n message: '\"hello\"'\n")
_, err := Load(dir, testSchemas(t))
if err == nil {
t.Fatalf("Load(id %q) = nil, want load failure", id)
}
for _, want := range []string{"pb.yaml", id} {
for _, want := range []string{"pb.yaml", id, "lowercase CEL field name"} {
if !strings.Contains(err.Error(), want) {
t.Errorf("Load error = %q, want it to name %q", err.Error(), want)
t.Errorf("Load error = %q, want it to contain %q", err.Error(), want)
}
}
})