merge: decide the workflow step-type vocabulary (m7oc, ze7y)

This commit is contained in:
sam committed 2026-09-30 07:56:10 +10:00
commit b2dedb579a
2 files changed
+95

No files matched your search

+10
View File
@@ -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 Line truncated
},
{
"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 skLine truncated
}
],
"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/"
}
]
}
+85
View File
@@ -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.