Ship a side-effecting playbook module #153
Notifications
Due Date
No due date set.
Blocks
Reference: sam/archie#153
Reference in new issue
Block a user
Goal
At least one module kind (notify a channel, or comment on the forge) runs end to end from a playbook with a visible result.
Evidence
internal/domain/eda/module/ contains only log.
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.7· GitHub #1310 · type feature · priority P2 · created 2026-10-05archie's PRD is ready -- awaiting your go/no-go.
PRD — Ship a side-effecting playbook module (
kind: notify)Read-only mission: nothing was built and no gate was run. Every claim below was read out of the tree; line numbers are from this checkout.
1. Problem
Action playbooks are fully wired but can only do something that has no effect.
internal/domain/eda/module/module.goregisters exactly one kind,log(side-effect free), sointernal/domain/eda/module/"contains only log" as the issue says. Everything around it is finished:internal/domain/eda/playbook/playbook.gocompiles aposition: moduleaction list, typesactions.<id>by each kind'sResult, andinternal/infrastructure/controlplanestore/playbooks.go:39validates a savededa-playbooksdocument through the sameCompile.internal/domain/eda/playbook/run.go+coordinator.gorun the actions in order, gated once per(playbook, version, event, action)byInvokeOnceagainstplaybook_dispatches(internal/infrastructure/postgres/migrations/0002_edastore.sql:84).internal/daemon/daemon.go:2266callsrunActionPlaybooksfrompinDefinition, andplaybookInput(daemon.go:2370) suppliesevent.{kind,labels,owner,repo,number,title,body,source}.messagingrpc.Client.Deliver(ctx, org, channel, chatID, text)(dialled atinternal/app/archied/bootstrap.go:506, already exposed as a 4-arg interface atinternal/app/archied/outcome_post.go:29) andforge.IssueForge.Comment(daemon.go:2658forgeFor).playbooks_client.go,ui/src/settings/PlaybooksPage.vue).So the product's accepted promise — "a trigger notifies someone" — is expressible and validated but does nothing.
CHANGELOG.md:1157still says "Action playbooks load but do not run yet."The one real constraint. The registry is built in infrastructure, not the daemon's composition root:
playbooks.go:58doesplaybook.Compile(docs, module.New(log)), and that one function serves both the running daemon and the State Store's validation (playbooksDefinition().Validate,encodePlaybooks). An invoke with an effect therefore needs a dependency that validation must not need — otherwise the State Store would have to dial the Messaging Service to save a playbook. This PRD's plumbing is exactly that separation.Verification constraint the reviewer must see. Action playbooks only run for a task that names no workflow (
daemon.go:2336), and only issue intake creates such a task (EnqueueIssuewrites noworkflow). The default stacks cannot demonstrate the stop-when:deployments/dev.tomlhas no messaging service entry and no channel,e2e/seed.shhas no channel or forge, and channels are extensions, not built-ins. A Go-level test with a fake deliverer proves the seam, not the stop-when.2. Proposed solution
One new kind,
notify, sending text to a messaging channel the task's organisation owns.Args reuse the
message.sendstep's vocabulary (WORKFLOWS.md:229), so a playbook author learns one set of names:notify.Args{Channel, ChatID, Text string}(all required),notify.Result{Delivered bool, Channel, ChatID string}.Org comes from ctx, never from an arg.
runActionPlaybooksruns insidepinDefinition, afterworkflowContexthas put the task's org on the context (daemon.go:2236), soorg.OrgFromContext(ctx)is the task's org. Anorgarg would let an operator-authored playbook address another org's channel; the messaging service already refuses a cross-org channel (internal/app/archiemessaging/compose.go:286,ErrNoChannel).Effects are optional on the registry.
module.New(log)keeps every kind's schema, so validation and package projection still accept anotifyplaybook without any dependency. A newmodule.Effects{Notify Notifier}—Notifierbeing the sameDeliver(ctx, org, channel, chatID, text) errorshape*messagingrpc.Clientalready has, so there is no adapter — supplies the run side.invokereturns a named error (module notify: no messaging service configured) when the effect is absent, which the daemon already turns into a warn (daemon.go:2339).controlplanestore.CompilePlaybooks(c, log)keeps its signature and builds a schema-only registry (both validation call sites unchanged).NewLivePlaybooks(client, log, modules playbook.Modules)gains the run-side registry, used atplaybooks_client.go:96;bootstrap.livePlaybooks()(bootstrap.go:846) builds it fromb.messaging, with the same nil check as the existing deliver closure at bootstrap.go:546."Result shows in the run" = a line in the task's log. There is no persisted per-action outcome (
playbook_dispatcheshas no outcome column) and no dashboard view of playbook actions, so the cheapest honest surface is the task's own log, which the task page already renders generically:component=playbook, e.g.playbook notify: delivered to telegram chat 12345);Daemon.runActionPlaybookspasses a task-scoped logger instead ofd.Log, via a nil-safe(*logging.TaskRegistry).Logger(taskID int64) *slog.Logger(~12 lines) that returns the open sink's logger;defer d.openTaskLog(task)()moves aboved.adoptWorkflowIdentity(ctx, task)inprocess()— today the playbook runs at daemon.go:1686, before the sink is opened at 1692, so a per-action line would otherwise be dropped. This is a one-line move and a side benefit: park reasons from a failed identity adoption (whichrecordParkalready writes, but into no open sink) now land in the task log too.Rejected alternatives, with reasons: a forge-comment kind (
Invoke(ctx, kind, args)carries no task, soforgeFor(task)'s per-connection resolution — "never falls back to the root forge" — cannot be honoured without widening the playbook domain seam); a stored per-action record (migration + proto + UI, a second change); a new event kind plus aui/src/tasks/timeline-event.tscase (plausible, but the action precedes the run, so the log is where an operator looks).Failure tolerance, stated rather than fixed:
InvokeOncewrites the ledger row before invoking, so a failed delivery is never retried for that event — the daemon warns, the task log records the error, the task proceeds.ErrNoChannel(messaging: no such channel, retrying cannot succeed) andErrUnavailable(messaging: channel unavailable, retrying could) are therefore both terminal for that action. Changing that is at-least-once semantics and belongs to a separate change.3. Files and components affected
internal/domain/eda/module/notify/notify.goArgs,Result,SchemaVersion, docinternal/domain/eda/module/module.goNotifier+Effects;EffectsonModuleRegistry;runNotify; strict notify-args decode;New(log, effects)internal/logging/registry.goLogger(taskID) *slog.Logger, nil when no sink is openinternal/daemon/daemon.goopenTaskLogdefer aboveadoptWorkflowIdentity; task-scoped logger inrunActionPlaybooksinternal/infrastructure/controlplanestore/playbooks.gointernal/infrastructure/controlplanestore/playbooks_client.gointernal/app/archied/bootstrap.gomodule.Effects{Notify: …}fromb.messaging, pass toNewLivePlaybooksWORKFLOWS.mdposition/kind/when/args/actions.<id>,notifyandlogarg+result tables; fix the one-line stub at :327CHANGELOG.md[Unreleased]→### archiedentry (news:checkskips Unreleased —tools/newsgen/changelog.go:50)internal/domain/eda/module/module_test.gonotifywith a fake notifier — the one thing that catches an arg-name or result-field drift in a package with zero tests todayNet: ~155–190 lines of product code and docs, ~250 with the test. Above AGENTS.md's ~100-line checkpoint, which is why this PRD exists; it adds no RPC, process, binary, table, proto or config field.
4. Acceptance criteria
position: module, kind: notifysaves through the control plane (dashboard/org/playbooks, package projection) and loads in the daemon; an unknown kind, an undeclared args key, a wrong-typed arg, or anotifyaction with nochannel/chat_id/textis a load failure naming the playbook, action and key.(playbook, version, event, action): the message arrives in the named chat, and a second delivery of the same event delivers nothing (ledger).component=playbook, naming the channel and chat; it is visible on the task page.when: falseskips the action: no delivery, no log line, no ledger row consumed.notifyaction'sResultis decodable, so a later action can readactions.ping.result.delivered.WORKFLOWS.mdand the[Unreleased]changelog entry describe the kind;task checkpasses once at the end.notifyruns from a real trigger with the result visible (see §5).5. Verification: what can be proven, and what needs the operator
Provable in-tree: the compile/validate path (fake
Modules), the invoke path (fake notifier), and the ledger's at-most-once behaviour.internal/domain/edahas no tests at all today, so this would be its first.Not provable in-tree: "runs from a real trigger and its result shows in the run". The only trigger reaching action playbooks is a task with no workflow — an issue discovered by the forge poll in a managed repo (
daemon.go:1382pollNATS→EnqueueIssue), or an equivalent envelope published on the task stream. The default stacks have no forge and no channel, and a channel is an installed extension. So the stop-when needs one of:6. Decisions for you
notify, or a forge comment? Recommendnotify. The messaging path already takes exactly(org, channel, chatID, text)and*messagingrpc.Clientsatisfies it unchanged; the org is on the context at that point. A forge comment needs the task threaded intoModules.Invoke, becauseforgeFor(task)resolves per connection and must not silently fall back to the root forge (daemon.go:2658–2669) — a bigger change to a domain seam and a security-relevant one.7. Explicit non-goals
playbook_dispatchesoutcome column, no proto change, no dashboard action history.ui/change.cmd/archiedhassetup, update, release, status, prbenchonly, soCHANGELOG.md:876'sarchie-playbooks lint -eda-dirno longer exists).8. Follow-ups to file as beads, not fix here
InvokeOncerecords first); decide whether record-then-retry is acceptable, which needs an outcome column.CHANGELOG.md:1157and:876are stale about playbooks running and about thearchie-playbooksCLI.internal/domain/edahas no tests; the module contract is uncovered.WORKFLOWS.mdcurrently documents no playbook document shape at all (only the one-line stub at :327) — in scope here as "documented", but say if you want it split out.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).