diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 06b516d5c..311487502 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -557,6 +557,12 @@ "title": "Workflows calling workflows", "section": "PRDs", "body": "# Workflows calling workflows\n\n**Status:** Draft\n**Date:** 2026-09-26\n**Bead:** `archie-core-t2db.41`\n**Extends:** `docs/prds/event-automation.md` (workflow/binding/profile model), `docs/prds/state-store-contract.md` (two new RPCs), `docs/prds/execution-tree-state-machine.md` (call kind)\n\n## The call, end to end\n\n```\ncaller run (in agent container)\n workflow.call step ──StartCall──▶ State Store EnqueueCallTask(caller, workflow, inputs)\n │ callee task row: org/identity/owner/repo\n │ derived from the caller row server-side\n ▼\n callee task (queued, org of the caller)\n │ daemon claims, pins the callee's OWN\n │ definition → its OWN agent profile\n ▼\n callee run (its own container, own tree)\n wait: true ──poll──▶ State Store WorkflowCallStatus(caller, callee)\n wait: false ──continue\n```\n\nA `workflow.call` step starts the callee as a first-class task and, with\n`wait: true`, waits for its terminal state. The callee is never run \"inside\"\nthe caller: it gets its own task row, its own pinned definition, its own\nprofile, its own container, and its own outcome on its own run\n(`execution-tree-state-machine.md`).\n\n## Save-time checks (the collection is the authority)\n\nAll semantic checks run in `workflow.ValidateDefinitionCollection`, the gate\nevery save and load of the `workflow-definitions` resource passes through.\nA single-definition parse cannot see callees, so it validates shape only.\n\n- **Callee exists.** A call to a workflow outside the collection is refused.\n- **Inputs checked.** A call value is a literal or a reference\n (`inputs.\u003cname\u003e`) to the calling workflow's declared input. References must\n name a declared input; the resolved type must satisfy the callee's declared\n type; unknown callee inputs are refused; a required callee input must be\n assigned.\n- **Self-calls refused.** The call graph over the collection is walked from\n every workflow; a workflow that reaches itself, directly or through other\n workflows, is refused with the cycle path. (Cycles can otherwise deadlock:\n `wait: true` callers hold their containers.)\n- **Repository.** `workflow.call` needs no repository, so it is legal in a\n `repository: none` workflow: the callee inherits the caller's task record\n (owner/repo/identity/org), and the callee's own `repository` mode decides\n whether its run clones.\n- **Org enablement** (bead `archie-core-t2db.42`): the single\n instance-wide collection the current model serves is what \"enabled for\n the caller's org\" resolves against — an undefined callee parks. The\n callee's org is derived from the caller's row, so a callee is never\n visible outside its caller's org. The per-org enable/disable catalogue\n lands with `archie-core-t2db.42` and becomes the one source of this\n predicate.\n\n## Runtime\n\n**Depth limit.** `workflow.MaxCallDepth` (5). The calling stage refuses a call\nthat would exceed it; the store re-checks on insert (callee depth = caller\ndepth + 1), so no path can enqueue past the limit.\n\n**Starting the callee.** The caller runs inside a container whose task-scoped\nState Store grant authorizes only `Update`/`Transition`/`InsertEvent` on its\nown task — it can neither enqueue a task nor read another one. One new\ncontract RPC starts the callee:\n\n- `EnqueueCallTask(caller_task_id, workflow, inputs_json) → task`\n — the store reads the caller row, refuses a caller that is not `running`,\n refuses past the depth limit, and inserts the callee row deriving org,\n workspace, identity, owner, repo and a fresh synthetic issue number from\n the caller (the same org COALESCE `EnqueueIssue`/`InsertChatTask` use). The\n callee row carries `call_parent_task_id` and `call_depth`.\n\n**Waiting on the callee.** One new read RPC returns a call's callee:\n\n- `WorkflowCallStatus(caller_task_id, call_task_id) → (status, detail)` — the\n handler verifies `call_parent_task_id` matches, so a caller reads only its\n own callees, and returns the callee's status plus its latest transition\n detail (the callee's summary — the wait:true \"outputs\" until a structured\n outputs model lands).\n\nBoth RPCs are admitted to task-scoped grants on `caller_task_id == granted\ntask ID` (`authorizesTaskScopedCall` gains two request-shape cases). This is\nthe one sanctioned widening of a task grant: the callee is the caller's child,\nand starting it is the mechanism by which one event becomes several runs. The\nwidenings stay request-shape checks; the parent-child authorization is a\nhandler-side row check, so the interceptor never reads the database.\n\n**Schema.** `tasks` gains `call_parent_task_id` (bigint, default 0) and\n`call_depth` (int, default 0); both cross the wire on the `Task` message.\nColumns default so existing writers and rows read as depth-0 root runs.\n\n**The engine capability.** The workflow domain owns a consumer facade,\n`task.Caller` (2 methods), carried by `*staterpc.Client` and wired into\n`TaskContext.Calls` by the agent worker's composition root — the same shape\nas `workflow.Store`. A runner with no `Calls` capability fails a\n`workflow.call` step with a named error rather than pretending.\n\n**Semantics.**\n\n- `wait: false` — start, record a durable `workflow_call_started` event, and\n continue. The callee's outcome is reported on its own run.\n- `wait: true` — start, then poll `WorkflowCallStatus` (2 s, bounded by the\n task's wall clock) until the callee is terminal. `completed`, `pr_open` and\n `merged` succeed the step; `parked`, `failed`, `rejected`, `dead` and\n `closed_wont_do` fail it with the callee's detail in the error. A durable\n `workflow_call_finished` event carries the terminal status and detail.\n- The caller's own stage/attempt accounting is unchanged: the call is one\n stage that took as long as its callee.\n- A callee inherits the caller's task record but is otherwise independent:\n retry, park and cancel of the callee never rewrite the caller. Cancelling a\n caller cancels its callees through the operator action on each\n (`execution-tree-state-machine.md` \"Cancellation\"); until the tree state\n machine lands, a caller cancelled while waiting fails its stage and leaves\n the callee running — the same semantics as `wait: false`.\n\n## What is deliberately not here\n\n- **Declared outputs.** `wait: true` receives the callee's terminal detail,\n not structured outputs; the outputs model is its own bead.\n- **The StepExecution tree.** The `call` kind is designed for in\n `execution-tree-state-machine.md`; this design lands the behaviour without\n the per-step records.\n- **Per-org enablement** — bead `archie-core-t2db.42`'s catalogue is the\n source once it exists." + }, + { + "url": "/dev/prds/workflow-step-vocabulary/", + "title": "Workflow step vocabulary: what a step type is and how binaries agree on it", + "section": "PRDs", + "body": "# Workflow step vocabulary: what a step type is and how binaries agree on it\n\n**Status:** Approved\n**Date:** 2026-09-29\n**Beads:** `archie-core-m7oc` (agreement between separately deployed binaries), `archie-core-ze7y` (the deleted `.archie/stages/*.go` equivalent)\n**Extends:** `docs/architecture/plugins-and-extensions.md` (plugin engine rule), `docs/prds/event-automation.md` (the workflow model step types serve)\n\n**Authority:** `docs/architecture/plugins-and-extensions.md` — the workflow step vocabulary is a Workflow capability family, and its extension point follows the plugin engine rule.\n\n## Decision\n\nA workflow step type is a named Go factory: the word a YAML workflow writes in\na step's `type` field, plus the factory that builds its stage. The name is a\nstable identifier; the identity also declares what plugin family claims it,\nso a contribution that shadows a shipped stage is refused instead of\noverriding it.\n\nThe Workflow domain owns the typed family contract — `StepTypeProvider` for a\ncontribution and `Manager` as the owning registry. A provider contributes a\nwhole set of step types under its own stable-identifier name; the manager\nvalidates the entire contribution before applying any of it (named provider,\nwell-formed step-type names, non-nil factories, no step type claimed twice,\nno claim on a name another provider holds) and applies it atomically. The\ngeneric `plugin.Plugin` contract stays metadata-only.\n\nThe vocabulary is a compiled-in, closed set. `internal/infrastructure/workflowsteps`\nis the one place a step type is bundled into any binary that resolves one: the\nshipped workflow stages, the repository-hook replacements (`workflow.diff-rules`)\nand the repository-free event steps each arrive as one provider, and adding a\nstep type means adding a provider to that set. Interpreted plugin sources\ncannot contribute step types: the Yaegi plugin host satisfies only the\nmetadata contract, and no bridge to `StepFactory` exists.\n\nEvery binary that resolves a step type builds its manager from that same\nprovider set at its composition root, before its first resolution, and\ninjects the manager everywhere it resolves definitions. Agreement is per\nbuild: the State Store, the daemon's workflow-definitions client and the agent\nworker built from the same source register identical vocabularies by\nconstruction; binaries built from different sources can disagree, and only a\nmatching deploy fixes that.\n\nAn unknown step type is refused twice, and never degraded. The validator\n`ParseDefinition` refuses a definition naming an unregistered type at save\ntime, on the validating side the composition root built (the State Store's\nworkflow-definitions resource validates there before anything is stored). The\ncompiler refuses the same definition at run, so a binary handed a definition\nwritten against a vocabulary it does not have fails that run loudly instead of\nsilently skipping steps. Both checks live in the Workflow domain against the\ninjected manager, which is why no binary can opt out of the check by\nsubstituting its own registry.\n\n## Relationship between the questions\n\n`archie-core-ze7y` is the same question seen from the deleted\nrepository-authored stages: those `.archie/stages/*.go` files held arbitrary\nstages, and their gate half landed as `workflow.diff-rules` settings rather\nthan interpreted Go. Their stage half has no replacement and does not get one\nthat approximates it: no interpreted-Go stage type is built, and no command\nstep type is created by this decision to stand in for them. The refusal of\n`.archie/stages/*.go` stays until the maintainer's trust decision\n(`archie-core-ndm8`) says otherwise.\n\nIf that decision ever allows a command step type, it arrives as a provider in\nthe compiled-in set under the rules above — a new contributor of exactly one\nstep type at a named provider. It is not a plugin contribution mechanism, and\nit does not change any answer in this document.\n\n## Rejected alternatives\n\n- **A vocabulary version or hash on the wire.** The executing side already\n refuses an unknown step type at its first compile, which is the mismatch\n detector, and it fails closed. A wire field would only narrow the\n deploy-skew window that a matching deploy closes, at the cost of a new\n contract field.\n- **A Yaegi-plugin-to-`StepFactory` bridge.** It would run repository-supplied\n interpreted code inside the daemon's process with daemon privileges. The\n trust boundary invariant requires repository-authored code to run in the\n task container, not in an interpreter embeddable into any binary.\n- **A package-level process-global registrar.** Global mutable registry state\n is unreadable at the composition root, collides with itself when one\n process builds the vocabulary twice, and is what made the first attempt at\n this question worse instead of better.\n- **Degrading on an unknown step type.** A run that skips steps it cannot\n compile would finish green while silently dropping the behaviour the\n definition asked for; refusal at save and at run is the only honest option." } ], "nav": [ @@ -938,6 +944,10 @@ { "title": "Workflows calling workflows", "url": "/dev/prds/workflow-calls/" + }, + { + "title": "Workflow step vocabulary: what a step type is and how binaries agree on it", + "url": "/dev/prds/workflow-step-vocabulary/" } ] } diff --git a/docs/prds/workflow-step-vocabulary.md b/docs/prds/workflow-step-vocabulary.md new file mode 100644 index 000000000..233f89776 --- /dev/null +++ b/docs/prds/workflow-step-vocabulary.md @@ -0,0 +1,85 @@ +# Workflow step vocabulary: what a step type is and how binaries agree on it + +**Status:** Approved +**Date:** 2026-09-29 +**Beads:** `archie-core-m7oc` (agreement between separately deployed binaries), `archie-core-ze7y` (the deleted `.archie/stages/*.go` equivalent) +**Extends:** `docs/architecture/plugins-and-extensions.md` (plugin engine rule), `docs/prds/event-automation.md` (the workflow model step types serve) + +**Authority:** `docs/architecture/plugins-and-extensions.md` — the workflow step vocabulary is a Workflow capability family, and its extension point follows the plugin engine rule. + +## Decision + +A workflow step type is a named Go factory: the word a YAML workflow writes in +a step's `type` field, plus the factory that builds its stage. The name is a +stable identifier; the identity also declares what plugin family claims it, +so a contribution that shadows a shipped stage is refused instead of +overriding it. + +The Workflow domain owns the typed family contract — `StepTypeProvider` for a +contribution and `Manager` as the owning registry. A provider contributes a +whole set of step types under its own stable-identifier name; the manager +validates the entire contribution before applying any of it (named provider, +well-formed step-type names, non-nil factories, no step type claimed twice, +no claim on a name another provider holds) and applies it atomically. The +generic `plugin.Plugin` contract stays metadata-only. + +The vocabulary is a compiled-in, closed set. `internal/infrastructure/workflowsteps` +is the one place a step type is bundled into any binary that resolves one: the +shipped workflow stages, the repository-hook replacements (`workflow.diff-rules`) +and the repository-free event steps each arrive as one provider, and adding a +step type means adding a provider to that set. Interpreted plugin sources +cannot contribute step types: the Yaegi plugin host satisfies only the +metadata contract, and no bridge to `StepFactory` exists. + +Every binary that resolves a step type builds its manager from that same +provider set at its composition root, before its first resolution, and +injects the manager everywhere it resolves definitions. Agreement is per +build: the State Store, the daemon's workflow-definitions client and the agent +worker built from the same source register identical vocabularies by +construction; binaries built from different sources can disagree, and only a +matching deploy fixes that. + +An unknown step type is refused twice, and never degraded. The validator +`ParseDefinition` refuses a definition naming an unregistered type at save +time, on the validating side the composition root built (the State Store's +workflow-definitions resource validates there before anything is stored). The +compiler refuses the same definition at run, so a binary handed a definition +written against a vocabulary it does not have fails that run loudly instead of +silently skipping steps. Both checks live in the Workflow domain against the +injected manager, which is why no binary can opt out of the check by +substituting its own registry. + +## Relationship between the questions + +`archie-core-ze7y` is the same question seen from the deleted +repository-authored stages: those `.archie/stages/*.go` files held arbitrary +stages, and their gate half landed as `workflow.diff-rules` settings rather +than interpreted Go. Their stage half has no replacement and does not get one +that approximates it: no interpreted-Go stage type is built, and no command +step type is created by this decision to stand in for them. The refusal of +`.archie/stages/*.go` stays until the maintainer's trust decision +(`archie-core-ndm8`) says otherwise. + +If that decision ever allows a command step type, it arrives as a provider in +the compiled-in set under the rules above — a new contributor of exactly one +step type at a named provider. It is not a plugin contribution mechanism, and +it does not change any answer in this document. + +## Rejected alternatives + +- **A vocabulary version or hash on the wire.** The executing side already + refuses an unknown step type at its first compile, which is the mismatch + detector, and it fails closed. A wire field would only narrow the + deploy-skew window that a matching deploy closes, at the cost of a new + contract field. +- **A Yaegi-plugin-to-`StepFactory` bridge.** It would run repository-supplied + interpreted code inside the daemon's process with daemon privileges. The + trust boundary invariant requires repository-authored code to run in the + task container, not in an interpreter embeddable into any binary. +- **A package-level process-global registrar.** Global mutable registry state + is unreadable at the composition root, collides with itself when one + process builds the vocabulary twice, and is what made the first attempt at + this question worse instead of better. +- **Degrading on an unknown step type.** A run that skips steps it cannot + compile would finish green while silently dropping the behaviour the + definition asked for; refusal at save and at run is the only honest option. \ No newline at end of file