Playbooks can trigger on an event type #152
Notifications
Due Date
No due date set.
Blocks
Reference: sam/archie#152
Reference in new issue
Block a user
Goal
A playbook can name a captured event type as its trigger; a matching capture runs its actions through the idempotency ledger.
Evidence
Trigger has only kind and labels (internal/domain/eda/playbook/playbook.go:103-106); playbooks run only at task pin (daemon.go:1853).
Rules
Read CLAUDE.md. Do only what the Goal and Stop when need. File anything else you notice as a bead; do not fix it. Run
task checkonce at the end; if it fails twice on the same problem, comment on this bead and stop.Stop when
Then commit (Conventional Commits, scoped by package),
bd closethis bead and stop.Imported from beads
archie-core-bdb5.6· GitHub #1312 · type feature · priority P2 · created 2026-10-05archie's PRD is ready -- awaiting your go/no-go.
PRD — Playbooks can trigger on an event type (#152)
Problem
An EDA playbook's trigger can only describe a task:
TriggerholdsKind workintake.KindandLabels []stringand nothing else (internal/domain/eda/playbook/playbook.go:66-75), and the only required-field check is "kind or labels" (:238-240). Playbooks are therefore consulted in exactly one place — the workflow pin path:runActionPlaybooksfrompinDefinition(internal/daemon/daemon.go:2266,:2332-2342) andresolveWorkflowID(:2346-2362).Store.Dispatchdeliberately skips action playbooks (playbook.go:588-590), so a capture can never reach a playbook no matter what it contains.Two things already exist and are unused for this input:
when/args, typed module actions, and theplaybook_dispatchesledger keyed(playbook_id, playbook_version, event_id, action_id)with a unique index (migrations/0002_edastore.sql:84-92), wired into production atinternal/app/archied/bootstrap.go:674.CaptureStore.ListCaptures(storecontract/capture.go:11-14), org-scoped SQL (queries/edastore.sql:10-15), implemented bystaterpc.Client.ListCaptures(staterpc/captures.go:131-147), plusClient.ListEventTypes(staterpc/eventtypes.go:139-145) to turn a capture's event-type ID into(source, name).So the gap is one trigger field, one save-time check, and one dispatch pass — not new machinery.
Why the pass cannot reuse the binding read.
ListUndispatchedCapturesonly lists captures that an armed binding's mapping matches (queries/edastore.sql:17-31) anddispatchOrgBindingsreturns before listing when no binding is enabled (daemon.go:611-632). A capture nobody has bound is invisible to the daemon, which is precisely the capture a playbook trigger should see.Proposed solution
1. Trigger field, validated on save
TriggergainsEvent *EventType(new value typeEventType{Source, Name string}), decoded fromrawTrigger(playbook.go:110-114). The pair is optional; absent keeps today's behaviour exactly.compileOne(playbook.go:222-250), which is the one compiler behind both save-time validation (playbooksDefinition().Validate→CompilePlaybooks,controlplanestore/playbooks.go:30-44) and the daemon's live load (LivePlaybooks.current,playbooks_client.go:96). New rejections, each naming the playbook and the field:trigger.eventwith an emptysourceorname;trigger.eventtogether withkindorlabels(a capture has neither, so the combination can never match one thing);trigger.eventon a playbook with a workflow action — a workflow playbook is selected only at pin, where there is no capture, so it would load, show up, and never fire;2. Matching
Match(playbook.go:533-557) gains an explicit event branch: withTrigger.Eventset, it compares the input'sEventType{Source, Name}and nothing else.DispatchInput.TaskIDis renamedEventID(documented as "the ledger's event key: a task's idempotency key at pin, a capture's id on the capture path"; usages:coordinator.go:24-31,daemon.playbookInputatdaemon.go:2370-2388).DispatchInputgainsEventType *EventType.The event branch is what stops an event-triggered playbook firing at every task pin: task inputs carry no
EventType, so the branch returns false. In the other direction no guard is needed — a capture input carries no labels and no kind, so akind/labelstrigger cannot match it, and a trigger with neither is already rejected at load.3. Capture dispatch path
A new pass beside the binding pass, at the same three call sites (
daemon.go:378,:405,:478):captureInputsetsEventID = c.ID,EventType = {t.Source, t.Name}, and a CELeventmap ofsource,event_type(name),delivery,received_at. No body (see Non-goals).capturePlaybookLimitis a new const (proposal: 20), deliberately smaller thanbindingDispatchBatchLimitbecause the whole window is re-read every pass.Daemon gains two fields, both already implemented by the
staterpc.Clientthe daemon holds:Captures storecontract.CaptureStoreandEventTypes interface{ ListEventTypes(context.Context) ([]eventtype.EventType, error) }, assigned inbuildDaemonwith the same assert-and-assign pattern asBindings/BindingDispatcher(bootstrap.go:645-672) — ~8 lines. Suggested cleanup: extract the principal-per-org iteration indispatchBindings(daemon.go:568-604) into one helper both passes call, so the two cannot drift.Fire-and-forget in the same sense as today:
Runjoins errors, the pass logs and moves on, no task is failed, the loop is never aborted.Semantics this buys, stated plainly
log, so the effect is a second log line. Before the first side-effecting kind ships this must be closed — either a store-side undispatched-capture read (proto + sqlc anti-join, follow-up bead) or a load-time cutoff (fire only on captures received after this version was compiled).Files and components affected
internal/domain/eda/playbook/playbook.goTrigger.Event,EventTypetype, raw decode, load validation,Matchbranch,DispatchInput.EventType,TaskID→EventIDinternal/domain/eda/playbook/coordinator.goEventIDfield renameinternal/domain/eda/playbook/run.goRunnow has two callers);Store.HasEventTriggers()internal/infrastructure/controlplanestore/playbooks_client.goHasEventTriggersdelegateinternal/daemon/daemon.godispatchCapturePlaybooks,dispatchOrgCapturePlaybooks,captureInput, 3 call sites, optional org-iteration helperinternal/app/archied/bootstrap.goCaptures,EventTypesinternal/domain/eda/playbook/playbook_test.go(new)internal/daemon/capture_playbook_test.go(new)WORKFLOWS.md(the playbook bullet,:327-328)source+namenaming, redacted-payload note, window caveatCHANGELOG.md[Unreleased]under archiedtask newsmust then be re-run ornews:checkfailsNo proto, sqlc, store-contract, RPC, config field, UI or migration change. The playbook editor is a YAML textarea (
ui/src/settings/PlaybooksPage.vue) and the canvas lists only workflow playbooks (ui/src/workflows/workflow-triggers.ts:96-105), so neither needs touching.Acceptance criteria
event: {source: S, name: N}with module actions saves through the control plane (Command{command:"replace"}and"validate"both succeed).event.source; emptyevent.name;eventcombined withkindorlabels;eventon a workflow-action playbook; a trigger with no kind, labels or event.Sidentified asN, within one daemon pass (≤1 s in the drain loop, ≤poll_intervalotherwise) the playbook's actions run in order, oneplaybook_dispatchesrow per action exists withevent_id= the capture id, and thelogkind writes one daemon log line.ErrAlreadyDispatched), logs nothing new, and surfaces no error.event_type = '', or one that is neither authenticated norunsigned(CapturedEvent.Dispatchable()), fires nothing.kind/labelsplaybook behaves exactly as before at pin; the existing binding-dispatch tests still pass.task checkpasses once, on the finished tree.Explicit non-goals
event.body). Redacted bodies, payload size and "unauthenticated input inside expressions" need their own decision; follow-up bead.Definition.Validate/Decodetake nocontext.Contextand no org (controlplanestore/registry.go:56-84), and the same validator runs over every org's stored value at startup (registry.go:294-310) and over seeds — a check against live event types there would fail a stored playbook once its type is deleted and make the resource unrepairable. Precedent:binding.Validateis shape-only and workflow existence is checked elsewhere (domain/binding/binding.go:64-68). The cost is that a typo is a silent non-trigger.logremains the only registered kind (module/module.go:30-36), so the observable effect of this feature today is a log line plus ledger rows.Store.Dispatch(workflow selection) stays pin-only; workflow playbooks may not carry an event trigger.Diff size
~350–400 lines including tests: ~180 shipped Go, ~6 docs, ~150 in two new test files; plus the optional ~25-line org-iteration extraction (moved, not added). No generated files change.
Risks and operator decisions
event: {source, name}(recommended) vs the event-type ID.(source, name)is unique instance-wide (migrations/0007_event_types.sql:22, unchanged by later migrations); the ID is an opaque UUID and playbooks are hand-written YAML. Renaming an event type silently stops matching.Dispatchable()(daemon.go:750-800,storecontract/capture.go:74-76); module actions have no gate. Recommended: fire only whenc.Dispatchable()and the event type is non-empty, with the reason in a code comment — because this is an unauthenticated-input → in-process-action path once a side-effecting kind exists.Validateto take a ctx and anEventTypeStoreinjected into the control plane, ~40 lines across 16 definitions).StreamPlaybookCaptureswith aplaybook_dispatchesanti-join now (exactly-once over the backlog, but proto + sqlc + contract + generated churn). Recommend the cheap path now and file the anti-join as a blocking bead for the first side-effecting module kind.WORKFLOWS.md:327-328must say which to use when.What I verified / did not
Verified by reading the tree: every file, line and behaviour cited above, including that
ListCapturesandListEventTypesare already onstaterpc.Clientand org-scoped, thatplaybook_dispatcheshas no org column and a per-version unique key, thatlogis the only module kind, and that the three dispatch call sites are the only ones. The working tree is already on branchfeat/152-playbooks-can-trigger-on-an-event-typewith no commits for it.Not verified: I could not run
task check,go test,bdortea, so the diff estimate is a reading of the code, not a measurement; and I could not read the parent epic's other beads, so sequencing against it is unknown.Decide in chat or on the dashboard.
Closed: goes against the product plan in epic #1977. Playbooks are being removed; triggers replace bindings, mappings, issue routing and playbooks (#1978).