diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 63d2da19a..10399892a 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -91,7 +91,7 @@ {"_type":"issue","id":"archie-core-g7tm","title":"telegram: finalize the reply through a live context, matching the error branch","description":"The success path calls live.finalize(turnCtx, reply) with the raw cancellable turn context (telegram.go:582), while the error branch two lines above deliberately uses context.WithoutCancel(turnCtx). If /stop lands during finalize, the rich edit, the plain-text retry, and the split-send fallback all abort with context.Canceled (go-telegram/bot builds requests with NewRequestWithContext), so the authoritative reply is never delivered and the live message keeps the ▌ cursor forever. The reply is persisted to the ledger, so the loss is delivery-level — but the user sees a frozen half-answer.\n\nFailure: a long tool-using turn is /stop-ped as it completes; turnCtx is cancelled mid-finalize; every send fails on the dead context; the chat shows the last live frame with a blinking cursor and no final answer.\n\nFound by code-review of PR #476 (feat/467, merged 98e8dda).","design":"live.finalize(context.WithoutCancel(turnCtx), reply) — the one-liner the error branch already uses. Consider making finalize take a live context internally rather than trusting each caller to remember.","acceptance_criteria":"A /stop landing mid-finalize still delivers the authoritative reply and drops the cursor; a test covers the cancellable-context finalize path.","status":"closed","priority":1,"issue_type":"bug","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-14T14:43:08Z","created_by":"Sam Catlow","updated_at":"2026-08-14T15:07:36Z","started_at":"2026-08-14T14:53:28Z","closed_at":"2026-08-14T15:03:28Z","close_reason":"Fixed in internal/channels/telegram/live.go and telegram.go: finalize/abandon strip context cancellation before sending (mirroring each other), ToolCall escapes Markdown metacharacters via bot.EscapeMarkdown, splitLongMessage splits on rune boundaries. All new/changed tests verified red-then-green; task check clean; adversarial review pass found no blocking issues.","external_ref":"https://github.com/samcharles93/archie-core/issues/484","labels":["code-review","streaming","telegram"],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-tb3a","title":"Fix streaming review blockers for inline tool calls","description":"Resolve the four evidence-gated findings in merged inline tool-call streaming: preserve the authoritative Telegram reply when final edits fail; keep Telegram network I/O off the model FullStream consumer and cancellable; correlate tool inputs with results and render a bounded redacted parameter summary; snapshot show_tool_calls per live reply to avoid reload races. Add regression tests for every path and run task check plus lint/race validation.","acceptance_criteria":"Regression tests fail on the merged implementation and pass after the fix. Final edit failure falls back to normal split delivery. Delta and ToolCall callbacks do not wait on Telegram HTTP and stop cancels in-flight rendering. Completed tool events include bounded redacted parameters correlated by tool-call ID. Reload cannot race an in-flight reply's show_tool_calls setting. task check passes, golangci-lint reports no new findings, and focused race tests pass.","notes":"Implemented in worktree /tmp/archie-core-tb3a on branch fix/archie-core-tb3a. Added cancellable async Telegram rendering, final edit failure fallback through normal split delivery, call-ID-correlated bounded conservative parameter summaries, atomic per-reply show_tool_calls snapshots, SSE/UI parameter rendering, rebuilt ui/dist, and regression tests. Validation: GOFLAGS=-buildvcs=false task check passed; golangci-lint --new-from-rev=HEAD ./... reported 0 issues; focused race suite passed; fresh adversarial reviewer reported PASS with zero findings. Plain task check is blocked in linked worktrees by Go VCS stamping exit 128, hence buildvcs override.\n2026-08-24 reconciliation: the close reason's 'worktree left uncommitted' is stale. The work did land on main via ba33527 (Merge pull request #477 from samcharles93/fix/archie-core-tb3a); verified on main: gateway/stream.go sensitiveParameterKey+redactToolParameters, telegram/live.go per-reply showToolCalls snapshot, webui/api_chat.go gating. The /tmp/archie-core-tb3a worktree and its branch are gone, as expected.\n","status":"closed","priority":1,"issue_type":"bug","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-13T18:05:35Z","created_by":"Sam Catlow","updated_at":"2026-08-24T07:29:09Z","started_at":"2026-08-13T18:05:39Z","closed_at":"2026-08-13T18:35:26Z","close_reason":"Completed and independently reviewed; worktree left uncommitted per conservative repository policy.","external_ref":"https://github.com/samcharles93/archie-core/issues/485","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-dzx","title":"Remove duplicate archie-agent safe.directory setup","description":"## Problem\\ncmd/archie-agent/main.go configures git safe.directory inline and then calls markWorktreeSafe, so startup writes the same global git configuration twice.\\n\\n## Scope\\nKeep markWorktreeSafe as the single tested production path and remove the older inline exec.Command block/import. Add regression coverage proving startup wiring has exactly one authoritative safe-directory call.\\n\\n## Acceptance\\n- archie-agent startup invokes markWorktreeSafe exactly once\\n- no second inline safe.directory command remains in main.go\\n- cmd/archie-agent tests and repository quality gate pass","acceptance_criteria":"Single tested safe.directory setup path remains; duplicate inline command is removed; tests and task check pass","notes":"Red proof: TestMainConfiguresWorktreeSafetyOnce failed with 2 setup paths before implementation. Green proof: go test/vet/build ./cmd/archie-agent/... passed; golangci-lint --new-from-rev=HEAD reported 0 issues. Fresh adversarial review found no blockers. Full task check was not run because the working tree contains unrelated in-progress changes and task check rewrites files; scoped package gate used per repository protocol.","status":"closed","priority":1,"issue_type":"bug","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-08-13T16:10:09Z","created_by":"Sam Catlow","updated_at":"2026-08-13T16:13:48Z","started_at":"2026-08-13T16:10:24Z","closed_at":"2026-08-13T16:13:48Z","close_reason":"Removed duplicate inline safe.directory setup; markWorktreeSafe is now the single tested production path","external_ref":"https://github.com/samcharles93/archie-core/issues/470","dependency_count":0,"dependent_count":0,"comment_count":0} -{"_type":"issue","id":"archie-core-t2db.12","title":"workflow: standalone playbook lint/LSP tool (gopls-shaped)","description":"Fourth slice of docs/prds/eda-playbook-engine.md. The design doc's collision handling has two layers: a linter for pre-merge, same-tree collisions, and the runtime detect-log-report path for cross-source collisions only visible at daemon startup (t2db.9/.10/.11). Only the runtime path exists so far.\n\nCorrected 2026-09-03 (Sam): not a Taskfile target wrapping existing functions -- a small standalone CLI binary shaped like gopls: one tool, multiple invocation modes. A one-shot 'lint' mode ships in this ticket; the design doc's LSP requirement (author-time hover/completion/inline errors) is a later mode of the SAME binary, not a separate tool, so the two can never validate a playbook YAML differently -- one schema source, one binary, two entrypoints into it (matches gopls's own check-vs-serve split).\n\nDepends on archie-core-t2db.11 (multiple playbook directories) landing first, since a linter checking one directory in isolation can't demonstrate the cross-directory case the doc cares about -- though it should also catch within-a-single-directory duplicates, which is the more common real case.","design":"New cmd/\u003cname\u003e binary (e.g. cmd/archie-playbooks), per organisation.md's cmd/ rule: CLI flag parsing and entry-point routing only, no domain wiring in cmd/ itself. Actual validation logic stays in internal/domain/workflow (reuse LoadKindWorkflowsYAML/LoadLabelWorkflowsYAML/t2db.11's directory merge directly -- no second, parallel validation path). This ticket implements only the lint subcommand/mode; structure the binary's command dispatch so an 'lsp'/'serve' subcommand can be added later without restructuring (e.g. a small subcommand table from the start, even with one entry), matching gopls's shape rather than assuming a single-purpose CLI that gets bolted onto later.","acceptance_criteria":"A new cmd/ binary exists with a lint subcommand/mode that runs against one or more playbook directories and exits non-zero with a clear message when two files bind the same label/kind; exits 0 cleanly on a valid set. Reuses existing loader/merge logic directly -- no duplicated validation rules. Binary's command structure has an explicit seam for adding an LSP/serve mode later (does not need to be built yet). Documented (README or Taskfile.yml comment) so it's discoverable. task check passes.","status":"open","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-09-02T16:56:44Z","created_by":"Sam Catlow","updated_at":"2026-09-02T16:58:38Z","dependencies":[{"issue_id":"archie-core-t2db.12","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-09-02T16:56:44Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"archie-core-t2db.12","title":"workflow: standalone playbook lint/LSP tool (gopls-shaped)","description":"Fourth slice of docs/prds/eda-playbook-engine.md. The design doc's collision handling has two layers: a linter for pre-merge, same-tree collisions, and the runtime detect-log-report path for cross-source collisions only visible at daemon startup (t2db.9/.10/.11). Only the runtime path exists so far.\n\nCorrected 2026-09-03 (Sam): not a Taskfile target wrapping existing functions -- a small standalone CLI binary shaped like gopls: one tool, multiple invocation modes. A one-shot 'lint' mode ships in this ticket; the design doc's LSP requirement (author-time hover/completion/inline errors) is a later mode of the SAME binary, not a separate tool, so the two can never validate a playbook YAML differently -- one schema source, one binary, two entrypoints into it (matches gopls's own check-vs-serve split).\n\nDepends on archie-core-t2db.11 (multiple playbook directories) landing first, since a linter checking one directory in isolation can't demonstrate the cross-directory case the doc cares about -- though it should also catch within-a-single-directory duplicates, which is the more common real case.","design":"New cmd/\u003cname\u003e binary (e.g. cmd/archie-playbooks), per organisation.md's cmd/ rule: CLI flag parsing and entry-point routing only, no domain wiring in cmd/ itself. Actual validation logic stays in internal/domain/workflow (reuse LoadKindWorkflowsYAML/LoadLabelWorkflowsYAML/t2db.11's directory merge directly -- no second, parallel validation path). This ticket implements only the lint subcommand/mode; structure the binary's command dispatch so an 'lsp'/'serve' subcommand can be added later without restructuring (e.g. a small subcommand table from the start, even with one entry), matching gopls's shape rather than assuming a single-purpose CLI that gets bolted onto later.","acceptance_criteria":"A new cmd/ binary exists with a lint subcommand/mode that runs against one or more playbook directories and exits non-zero with a clear message when two files bind the same label/kind; exits 0 cleanly on a valid set. Reuses existing loader/merge logic directly -- no duplicated validation rules. Binary's command structure has an explicit seam for adding an LSP/serve mode later (does not need to be built yet). Documented (README or Taskfile.yml comment) so it's discoverable. task check passes.","status":"closed","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-09-02T16:56:44Z","created_by":"Sam Catlow","updated_at":"2026-09-02T17:07:39Z","closed_at":"2026-09-02T17:07:39Z","close_reason":"Implemented and gate-verified as 2c7c79e (pushed to main). cmd/archie-playbooks lint mode reuses daemon loaders; file-granular positions documented as known limitation.","dependencies":[{"issue_id":"archie-core-t2db.12","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-09-02T16:56:44Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-t2db.11","title":"workflow: generalize routing/label files to multiple playbook directories","description":"Third slice of docs/prds/eda-playbook-engine.md, completing open question #2. Generalizes the single-file workflow_routing_file / workflow_labels_file config fields (t2db.9, t2db.10) into a LIST of configured playbook directories, loaded at daemon startup alongside the existing single-file fields for backward compatibility. This is what makes the design doc's collision-handling rule (drop + log + report to caller, no auto-arbitration) load-bearing: a single file has nothing to collide with, so the rule has never actually been exercised in production code yet.\n\nCorrected 2026-09-03 (Sam): must be a list of directories, not one directory -- a single playbook_dir field would contradict supporting multiple independently-maintained playbook sources, which the PRD's own Dedup section already assumes ('independently-sourced playbook directories collide'). Scope directories by the existing Repo (owner/name) concept already in Config.Repos, NOT by org/tenant -- org-keying would require an auth/identity model archie does not have yet. That is a separate, later decision, not something to half-build here.","design":"Follow the existing once-at-startup lifecycle (SetKindWorkflows/SetLabelWorkflows pattern) rather than inventing new state management. Config gains a list field (e.g. PlaybookDirs []string, or a PlaybookDir field on the existing Repo struct if directories should tie to a specific configured repo rather than being globally pooled -- decide based on whether playbooks are meant to be repo-scoped or operator-global). A loader reads every *.yaml file across all configured directories, applying the same per-file validation LoadLabelWorkflowsYAML already does, then merges bindings across all sources -- a binding for the same label/kind declared by two different sources is the collision case: drop both, log which sources/label collided, return the error to the caller (do not start the daemon on a routing collision). Single-file fields (workflow_routing_file, workflow_labels_file) remain supported unchanged as an additional, independent input alongside the directory list, not replaced by it.","acceptance_criteria":"Config supports a LIST of playbook directories (not a single path), empty/unset by default (no behavior change for existing configs). Loading two directories with a colliding label binding is a reported load failure, not a silent pick-one. Loading multiple non-colliding directories merges cleanly and Route() honours the merged bindings. Existing workflow_routing_file/workflow_labels_file continue to work unchanged when no directories are configured. Org/tenant scoping is explicitly out of scope and not attempted. task check passes.","status":"closed","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-09-02T16:50:18Z","created_by":"Sam Catlow","updated_at":"2026-09-02T16:57:50Z","closed_at":"2026-09-02T16:57:50Z","close_reason":"Implemented and gate-verified as 3e7fe00 (pushed to main). PlaybookDirs is a list per ticket correction; cross-source collision rule exercised by new load path.","dependencies":[{"issue_id":"archie-core-t2db.11","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-09-02T16:50:18Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-t2db.10","title":"feat(workflow): route arbitrary forge labels to workflows via playbook YAML","description":"Second slice of docs/prds/eda-playbook-engine.md, complementing the kind-\u003eworkflow layer (WorkflowRoutingFile): the label vocabulary itself becomes playbook data. A label outside the closed bug/feature/bootstrap kind set (e.g. security) dispatches to a registered workflow from an optional WorkflowLabelsFile, instead of falling through to triage.\n\n- LabelWorkflows + LoadLabelWorkflowsYAML/SetLabelWorkflows in internal/domain/workflow/routing.go, mirroring the kind layer's once-at-startup lifecycle. The closed Kind/NATS-subject set is untouched; the map only extends binding authority for labels the kind layer does not own.\n- Collision rule per design doc: a label owned by the kind set, an empty label, an empty workflow name, or a duplicate binding is a reported load failure (dropped, logged, error returned to the caller) -- the schema defines what is accepted; nothing is silently arbitrated by schema/version.\n- Route() precedence: explicit t.Workflow -\u003e arbitrary-label binding -\u003e kind binding -\u003e triage -\u003e implement -\u003e default.\n- Config: WorkflowLabelsFile (workflow_labels_file), wired at boot alongside WorkflowRoutingFile; documented in config.example.toml.\n- PRD: records this slice's decisions (single-file shape, collision rule, precedence) so later slices stay anchored.\n\nCommitted as 93a5f3a and pushed to main.","design":"Follows the EDA playbook engine design doc (docs/prds/eda-playbook-engine.md). Open question 2 (config field shape) partially resolved: single file (workflow_labels_file) mirroring WorkflowRoutingFile and SkillsDir's single-path precedent; a directory remains open and larger. Data-flow/condition syntax (Q1), mid-run failure semantics and idempotency (design gaps 1-2) are explicitly out of this slice's scope per the PRD phasing -- they land with Module/Channel/Forge action kinds.","acceptance_criteria":"1. An issue labelled with an arbitrary label (not bug/feature/bootstrap) routes to the workflow bound in workflow_labels_file.\n2. No workflow_labels_file configured: kind-only routing unchanged (backward compatible).\n3. Colliding/empty/kind-owned labels in the file produce a reported load error, not silent arbitration.\n4. Route() precedence: explicit t.Workflow \u003e arbitrary-label binding \u003e kind binding \u003e triage \u003e implement \u003e default.\n5. task check is green; tests cover dispatch, collision, empties, nil-restore, and precedence.","status":"closed","priority":2,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-09-02T16:45:33Z","created_by":"Sam Catlow","updated_at":"2026-09-02T16:46:28Z","closed_at":"2026-09-02T16:46:14Z","close_reason":"Implemented and gate-verified as 93a5f3a (pushed to main).","external_ref":"https://github.com/samcharles93/archie-core/issues/701","dependencies":[{"issue_id":"archie-core-t2db.10","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-09-02T16:45:33Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-t2db.9","title":"workflow: make kind-to-workflow routing YAML-overridable","description":"First slice of the EDA playbook engine (docs/prds/eda-playbook-engine.md): make workflow/routing.go's kindWorkflows map overridable from an optional YAML file, so which workflow runs for an intake Kind is data instead of a Go literal. labelKinds/NATS subjects are explicitly out of scope for this slice (closed subject-per-kind question deferred).","acceptance_criteria":"Route() accepts an optional KindWorkflows override; a YAML file with the same shape as the built-in map overrides it; absent file/nil override falls back to today's hardcoded defaults unchanged; config gains an optional path field; task check passes.","status":"closed","priority":2,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-09-02T16:32:45Z","created_by":"Sam Catlow","updated_at":"2026-09-02T16:46:28Z","started_at":"2026-09-02T16:32:50Z","closed_at":"2026-09-02T16:35:44Z","close_reason":"kindWorkflows YAML override shipped, task check green","external_ref":"https://github.com/samcharles93/archie-core/issues/702","dependencies":[{"issue_id":"archie-core-t2db.9","depends_on_id":"archie-core-t2db","type":"parent-child","created_at":"2026-09-02T16:32:45Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/docs/prds/eda-playbook-engine.md b/docs/prds/eda-playbook-engine.md index c664def6c..0cd5bf1c6 100644 --- a/docs/prds/eda-playbook-engine.md +++ b/docs/prds/eda-playbook-engine.md @@ -83,7 +83,9 @@ access. Concretely: Yaegi-evaluated implementation of a generated interface (args in, typed result out) for one declared action kind (e.g. `image-gen`, `notify`, `open-pr-comment`). This is the position that makes actions "not - restricted to code-generation." + restricted to code-generation." Full design (schema-per-kind, the + registry shape, the trust boundary, the recommended first slice): + `docs/prds/module-position.md`. - **Channel** -- already exists as `channels.Channel` (telegram, email, webhook). A playbook action of kind `channel` sends through a named, already-registered channel. No new mechanism; this document just makes it diff --git a/docs/prds/module-position.md b/docs/prds/module-position.md new file mode 100644 index 000000000..982118bcc --- /dev/null +++ b/docs/prds/module-position.md @@ -0,0 +1,203 @@ +# Module position -- design + +**Status:** Draft, awaiting sign-off (not yet in `docs/architecture/`) +**Date:** 2026-09-03 +**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db` + +## Problem + +`eda-playbook-engine.md` names four logic positions a playbook action can +target: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`) +and the standalone lint tool (`t2db.12`) are shipped. Module -- the +position that makes an action "not restricted to code-generation" -- has +not started, because it needs a schema-generation mechanism the parent +doc deliberately deferred: "This document does not attempt to design the +full generator today." This is that design. + +## Do not invent a new mechanism -- generalize the one already shipped three times + +Yaegi-interpreted extension code with a fixed, resolved-by-name exported +function already exists in this codebase for three surfaces, and all three +follow the identical shape: + +| Surface | Fixed signature | Export path | Symbol table | +|---|---|---|---| +| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `"gate.Check"` | `gateextract.Symbols` | +| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` | +| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `"main.Run"` | none (stdlib only) | + +Each is: read a `.go` file -> `yaegiutil.New` with that surface's symbol +table -> `yaegiutil.Resolve[T](i, src, exportPath)` -> call the resolved +function wrapped in `yaegiutil.Safe` for panic recovery. **Module is a +fourth instance of this same shape**, parameterized by action kind instead +of hardcoded to one fixed signature. No new interpreter construction, no +new panic-recovery mechanism, no new symbol-table generation tool -- +`go generate ... yaegi extract` is already how `wfextract`/`gateextract` +are produced today (see their `//go:generate` directives), and Module +schema generation reuses that exact command. + +## No generic `Module` interface -- one typed contract per action kind + +The plugin engine rule's invariant 1 requires "real capability-specific +operations," and invariant 5 forbids adding capability methods to a +generic interface. A single `Module` interface with `Run(args any) (any, +error)` would be exactly the untyped hook the rule (and +`event-sources-and-reactions.md`'s rejection of a generic `Source` +interface) exists to prevent -- restating the mistake the whole EDA +document was written to move away from (`wfextract`'s hardcoded +`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per- +case system already looks like in this repo). + +Instead, **each action kind is its own tiny package with its own +generated contract**, exactly like `gate.GateContext`/`gate.Finding` are +one hand-written Go file that `gateextract` turns into a Yaegi symbol +table: + +```go +// internal/domain/eda/module/notify/types.go (hand-written, the schema source) +package notify + +// SchemaVersion is independent of a playbook's own workflow_version, per +// eda-playbook-engine.md's schema-versioning point. +const SchemaVersion = 1 + +type Args struct { + Channel string + Message string +} + +type Result struct { + Delivered bool +} + +//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify +``` + +A Yaegi module implementing this kind exports a fixed function name +against these generated types, resolved the same way `gate.Check` is: + +```go +// operator's notify.go, interpreted at load +package notify + +func Run(a notify.Args) notify.Result { ... } +``` + +`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols` +is its generated Yaegi bridge; the operator's file is the implementation. +This is the same three-way split `internal/gate` / `gateextract` / +`.archie/gate.go` already has. + +## The registry: `ModuleRegistry`, keyed by kind, not a service locator + +Per invariant 2 (owning family manager) and invariant 4 (narrow host +access): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind +name (`"notify"`, `"image-gen"`) to a resolved, type-erased invoker -- +the same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols` +already uses to bridge Yaegi and Go, not a new pattern and not exposed as +the plugin's contract with the daemon (the plugin still writes and is +checked against a fully typed `func(Args) Result`; the registry's +internal storage is the only place erasure appears, exactly as it already +does inside `wfextract`). + +```go +type ModuleRegistry struct { + // kind -> (validate args against generated schema, invoke, marshal result) +} + +func (r *ModuleRegistry) Register(kind string, dir string) error // discovers .go, resolves against that kind's generated symbols +func (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]any, error) +``` + +`Invoke` decodes `rawArgs` into that kind's generated `Args` struct before +calling the interpreted function -- a shape mismatch is a reported load/ +dispatch failure per the design doc's "schema defines the accepted +message" rule, not a silent zero-value fill. This mirrors `plugin.Registry` +(`internal/plugin/plugin.go`)'s `Register`/dispatch split, scoped to one +capability family instead of generic daemon plugins. + +Lifecycle (invariant 3): stateless invocation is the default -- explicit +no-op start/health/stop, matching "Stateless providers may make these +operations explicit no-ops." A future Module kind that owns a resource +(e.g. a persistent connection) can add optional lifecycle methods later, +the same way `internal/memory.MemoryProvider`'s optional capability +contracts (system-prompt contributions, prefetch, shutdown) layer onto a +minimal required set without forcing every provider to implement them. + +## Trust boundary (closes `eda-playbook-engine.md` open question 3) + +Invariant 6 draws the line: operator-trusted in-process code vs. +repository-supplied code that must run in a container. Module code is +**operator-installed, in-process, daemon-privileged** -- the same trust +tier as `PluginDir` (daemon plugins) and `SecretEngineDir` (secret engine +plugins) already occupy, both Yaegi-interpreted and already running +in-process today. It is **not** repository-supplied code from a task +(that stays containerized, unchanged). A Module directory is therefore a +new config field the operator points at their own trusted directory, +mirroring `PluginDir`'s shape exactly -- not something a forge webhook or +an untrusted playbook source can populate. + +## Playbook YAML shape for a Module action + +```yaml +actions: + - position: module + kind: notify + args: + channel: telegram + message: "build finished" +``` + +`args` is validated against `notify.Args` (via the registry's decode +step) before invocation -- an unknown or missing required field is the +same "dropped and reported to the caller" failure the routing layer +already applies to unrecognised kinds/labels, not a new error philosophy. + +## Interaction with the unresolved execution-time gaps + +`eda-playbook-engine.md`'s "Execution-time gaps" section already gates +this: mid-run failure semantics and idempotency keying "must be resolved +before Channel/Forge actions or multi-action playbooks ship." Module is +where those gaps stop being theoretical -- a `notify` action has a real +side effect. Concretely: + +- A **first Module kind should be side-effect-free** (e.g. a `log`/`echo` + kind that only writes to the daemon's own log) so the schema-gen -> + registry -> playbook-dispatch mechanism can be proven end to end without + yet needing an idempotency answer. +- **Any Module kind with a real external side effect (`notify`, + `image-gen`, forge writes) is blocked on resolving those two gaps + first** -- this document does not relitigate or resolve them, it + inherits the existing gate. + +## Recommended first slice + +1. `internal/domain/eda/module` package: `ModuleRegistry`, the + discover/resolve/invoke mechanics, generalizing `gateeval`'s pattern. +2. One proof-of-concept kind, side-effect-free (`log`), with its schema + source + generated extract file, to prove schema -> `go:generate` -> + Yaegi load -> registry -> playbook dispatch end to end. +3. Config field for the Module directory (`ModuleDir`, mirroring + `PluginDir`), wired at daemon startup alongside the existing + `PlaybookDirs` loading. +4. Do **not** implement `notify` or any side-effecting kind in this slice + -- that is explicitly gated on the execution-time gaps above. + +## Open questions + +1. **Discovery convention.** Does a Module kind's implementation file need + to declare its kind name explicitly (frontmatter-style, like a skill's + `metadata.archie.workflow`) or is the kind inferred from directory/file + naming (`module/notify/impl.go` implies kind `notify`)? Follow the + skill catalog's existing declared-metadata convention unless there's a + reason not to -- not decided here. +2. **Where schema source files live.** This doc assumes + `internal/domain/eda/module//types.go` per kind, but the exact + package layout (one package per kind vs. one package with per-kind + subtypes) should be confirmed against `organisation.md`'s file-layout + rule before the first slice starts. +3. **Result surfacing.** A Module's `Result` needs to reach later actions + in the same playbook once data-flow (parent doc's open question 1) is + designed -- this doc does not attempt that, but the `map[string]any` + result shape above should stay compatible with whatever that + mechanism turns out to be.