eda: playbook document + event coordinator, single-action workflow-kind dispatch #438

Closed
opened 2026-10-27 13:36:19 +00:00 by sam · 0 comments
Owner

Seventh slice of docs/prds/eda-playbook-engine.md. Builds the rich playbook document shape (trigger + ordered actions with CEL 'when') and an event coordinator that dispatches it -- the first real consumer of t2db.14's expr package. Scoped tightly to what's already safe per this doc's own gating:

  • Exactly ONE action per playbook in this slice, and it MUST be position: workflow. Reject (load failure) a playbook declaring more than one action, or an action whose position is module/channel/forge -- those remain blocked on the unresolved execution-time gaps (mid-run failure semantics, idempotency for non-workflow actions) per the 'Execution-time gaps' section. Do not relax this without Sam's sign-off -- this is the one hard boundary in this ticket, everything else is normal implementation judgment.
  • This is an ADDITIONAL loading path alongside the existing flat kind/label binding files (t2db.9/.10/.11). Do NOT modify workflow.Route(), workflow.workflowForLabels, or remove/change the existing single-file/multi-dir binding loaders. Migrating Route() onto the new mechanism is a separate, later, larger decision -- not in scope here.
  • Idempotency is free for this slice for the same reason it was free for t2db.13's first Module slice: a single workflow-kind action reaches the exact same workflow.Registry dispatch path that already carries TaskEnvelope's idempotency key. Nothing new to design here.

Design

Depends on archie-core-t2db.14 (expr package) -- do not start until it is closed and verified.

  1. Playbook document type (new package, likely internal/domain/eda/playbook -- confirm against organisation.md's layout rule, follow the log/logextract split precedent from t2db.13 if a generated component turns out to be needed, though this ticket is pure YAML+CEL, no Yaegi, so likely no extract package is needed here):
    • trigger: reuse existing workintake label/kind matching (do not invent a second label-matching mechanism -- workintake.SplitLabels/KindsForLabels already exist and are the one place this vocabulary lives).
    • actions: a list, validated at load to contain exactly one entry with position: workflow and a workflow registry name.
    • when: optional CEL expression string on the action, compiled via t2db.14's Compile() at load time -- a compile failure is a reported load failure (same collision-handling philosophy as t2db.9-.12), not a silently-skipped playbook.
  2. Event coordinator: loads playbook files from a configured directory (mirror the PlaybookDirs pattern from t2db.11 -- reuse its directory-scanning shape, do not reinvent), compiles every playbook's when expression at load (fail the whole load on any compile error, consistent with the existing reject-at-load rule), and at dispatch time: match trigger against an incoming task's labels/kind, evaluate when (if present) against a context of {event: <task's label/kind fields, whatever is cheaply available -- do not over-engineer the event shape beyond what a workflow-kind dispatch actually needs>, actions: {} (empty -- no prior actions exist in a single-action playbook)}, and if the condition is true (or absent), dispatch to the named workflow via the existing workflow.Registry -- call the same registry lookup Route() already uses, do not duplicate dispatch logic.
  3. Config: a directory field for these playbook documents (distinct from t2db.11's PlaybookDirs, which holds flat binding files -- naming these two similar-but-different directories clearly is important; suggest something like EDAPlaybookDir or clarify in the field doc comment exactly how it differs from PlaybookDirs so a future reader isn't confused). If you judge the distinction is confusing enough that these should share one directory with two file shapes distinguished by content, flag that as a note in the PRD rather than silently deciding it -- but implement SOMETHING reasonable rather than blocking.
  4. Bootstrap wiring: load-and-abort on failure, matching every other slice's established pattern.
  5. Do NOT wire this into production task intake (daemon.go/pollNATS/publishTask) in this ticket -- prove the coordinator end-to-end with tests that construct a task-like input directly, the same way t2db.13 proved ModuleRegistry with direct Register/Invoke calls rather than full daemon wiring. Production wiring (making a real forge-triggered task actually flow through this coordinator instead of only workflow.Route()) is explicitly a follow-up ticket -- note it as such when you close this one.

Acceptance criteria

A playbook YAML with trigger + one workflow-kind action + optional when loads successfully and dispatches to the correct registered workflow when trigger+when match. A playbook declaring 2+ actions is a reported load failure. A playbook with a non-workflow action position is a reported load failure. A when expression that compiles but evaluates false at dispatch time correctly skips dispatch (logged, not silently ignored). A when compile failure at load time is reported and the playbook is dropped (same collision-handling shape as prior slices). Existing workflow.Route()/label-binding tests (t2db.9-.12) are unaffected -- run their full test suites and confirm zero regressions. task check passes.

Close reason

Verified landed: internal/domain/eda/playbook (Store/Match/loadOne) plus boot.loadEDAPlaybooks.


Imported from beads archie-core-t2db.15 · GitHub #739 · type task · priority P2 · created 2026-09-02 · closed 2026-09-11

Seventh slice of docs/prds/eda-playbook-engine.md. Builds the rich playbook document shape (trigger + ordered actions with CEL 'when') and an event coordinator that dispatches it -- the first real consumer of t2db.14's expr package. Scoped tightly to what's already safe per this doc's own gating: - Exactly ONE action per playbook in this slice, and it MUST be position: workflow. Reject (load failure) a playbook declaring more than one action, or an action whose position is module/channel/forge -- those remain blocked on the unresolved execution-time gaps (mid-run failure semantics, idempotency for non-workflow actions) per the 'Execution-time gaps' section. Do not relax this without Sam's sign-off -- this is the one hard boundary in this ticket, everything else is normal implementation judgment. - This is an ADDITIONAL loading path alongside the existing flat kind/label binding files (t2db.9/.10/.11). Do NOT modify workflow.Route(), workflow.workflowForLabels, or remove/change the existing single-file/multi-dir binding loaders. Migrating Route() onto the new mechanism is a separate, later, larger decision -- not in scope here. - Idempotency is free for this slice for the same reason it was free for t2db.13's first Module slice: a single workflow-kind action reaches the exact same workflow.Registry dispatch path that already carries TaskEnvelope's idempotency key. Nothing new to design here. ### Design Depends on archie-core-t2db.14 (expr package) -- do not start until it is closed and verified. 1. Playbook document type (new package, likely internal/domain/eda/playbook -- confirm against organisation.md's layout rule, follow the log/logextract split precedent from t2db.13 if a generated component turns out to be needed, though this ticket is pure YAML+CEL, no Yaegi, so likely no extract package is needed here): - trigger: reuse existing workintake label/kind matching (do not invent a second label-matching mechanism -- workintake.SplitLabels/KindsForLabels already exist and are the one place this vocabulary lives). - actions: a list, validated at load to contain exactly one entry with position: workflow and a workflow registry name. - when: optional CEL expression string on the action, compiled via t2db.14's Compile() at load time -- a compile failure is a reported load failure (same collision-handling philosophy as t2db.9-.12), not a silently-skipped playbook. 2. Event coordinator: loads playbook files from a configured directory (mirror the PlaybookDirs pattern from t2db.11 -- reuse its directory-scanning shape, do not reinvent), compiles every playbook's when expression at load (fail the whole load on any compile error, consistent with the existing reject-at-load rule), and at dispatch time: match trigger against an incoming task's labels/kind, evaluate when (if present) against a context of {event: <task's label/kind fields, whatever is cheaply available -- do not over-engineer the event shape beyond what a workflow-kind dispatch actually needs>, actions: {} (empty -- no prior actions exist in a single-action playbook)}, and if the condition is true (or absent), dispatch to the named workflow via the existing workflow.Registry -- call the same registry lookup Route() already uses, do not duplicate dispatch logic. 3. Config: a directory field for these playbook documents (distinct from t2db.11's PlaybookDirs, which holds flat binding files -- naming these two similar-but-different directories clearly is important; suggest something like EDAPlaybookDir or clarify in the field doc comment exactly how it differs from PlaybookDirs so a future reader isn't confused). If you judge the distinction is confusing enough that these should share one directory with two file shapes distinguished by content, flag that as a note in the PRD rather than silently deciding it -- but implement SOMETHING reasonable rather than blocking. 4. Bootstrap wiring: load-and-abort on failure, matching every other slice's established pattern. 5. Do NOT wire this into production task intake (daemon.go/pollNATS/publishTask) in this ticket -- prove the coordinator end-to-end with tests that construct a task-like input directly, the same way t2db.13 proved ModuleRegistry with direct Register/Invoke calls rather than full daemon wiring. Production wiring (making a real forge-triggered task actually flow through this coordinator instead of only workflow.Route()) is explicitly a follow-up ticket -- note it as such when you close this one. ### Acceptance criteria A playbook YAML with trigger + one workflow-kind action + optional when loads successfully and dispatches to the correct registered workflow when trigger+when match. A playbook declaring 2+ actions is a reported load failure. A playbook with a non-workflow action position is a reported load failure. A when expression that compiles but evaluates false at dispatch time correctly skips dispatch (logged, not silently ignored). A when compile failure at load time is reported and the playbook is dropped (same collision-handling shape as prior slices). Existing workflow.Route()/label-binding tests (t2db.9-.12) are unaffected -- run their full test suites and confirm zero regressions. task check passes. ### Close reason Verified landed: internal/domain/eda/playbook (Store/Match/loadOne) plus boot.loadEDAPlaybooks. --- _Imported from beads `archie-core-t2db.15` · GitHub #739 · type task · priority P2 · created 2026-09-02 · closed 2026-09-11_
sam added the mediumtask labels 2026-10-27 13:36:19 +00:00
sam self-assigned this 2026-10-27 13:36:20 +00:00
sam closed this issue 2026-10-27 13:36:20 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#438