Workflow documents carry today's vocabulary on the durable engine #2037

Open
opened 2026-11-16 10:54:54 +00:00 by sam · 1 comment
Owner

The single binary's workflow document (modules/runs/document.go) has five step kinds (agent, action, wait_for_approval, notify, sleep) and none of the properties a workflow author has today. Shipping it as the replacement would take most of what makes the platform useful. ARCHITECTURE 2.2 and section 4 already say the workflow definitions and engine are kept and moved; the implementation wrote a new, smaller vocabulary instead.

Move today's vocabulary (WORKFLOWS.md, internal/domain/workflow) onto the durable engine. The engine's part is new: leases, the step journal, unknown outcomes, waits that hold no worker. The vocabulary and step semantics are today's, renamed only where the maintainer changes a name. The new step kinds (judged connector action, wait for approval, notify, sleep) join it.

What the document lacks today, each of which must be there:

  • Workflow level: inputs and outputs with types, identity, profile, repository (required, optional, none).
  • Step level: when conditions, on_failure (park or continue), retry (attempts and backoff), parallel branches, step id for references.
  • References: task.*, inputs.*, steps.<id>.summary, steps.<id>.result.<field>, checked when the workflow is saved.
  • Agent settings: mission, a result JSON Schema, model alias, read-only, protected tests, extra rules, gate.
  • Step types: command.run, repo.prepare, repo.tooling, repo.commit, repo.open-pr, gate.diff-rules, gate.repository, forge.comment, forge.close-issue, message.send, workflow.approve, workflow.call (with inputs, outputs and wait), workflow.finish (completed, parked, waiting for approval, declined), workflow.handoff, review.pr, review.reply, review.start-round.
  • Run endings: the first step that sets an outcome ends the run; a failed step parks unless it continues; a parked run retries from a top-level step with the earlier results kept.

The lifecycle protections in #2036 are expressed through these properties, so Archie or the person writing a workflow can set them, with defaults that match today's behaviour.

Done when: every workflow in internal/domain/workflow and the starter documents parses and runs on the durable engine with the same steps, references and endings, and the new step kinds work beside them.

The single binary's workflow document (`modules/runs/document.go`) has five step kinds (agent, action, wait_for_approval, notify, sleep) and none of the properties a workflow author has today. Shipping it as the replacement would take most of what makes the platform useful. ARCHITECTURE 2.2 and section 4 already say the workflow definitions and engine are kept and moved; the implementation wrote a new, smaller vocabulary instead. Move today's vocabulary (`WORKFLOWS.md`, `internal/domain/workflow`) onto the durable engine. The engine's part is new: leases, the step journal, unknown outcomes, waits that hold no worker. The vocabulary and step semantics are today's, renamed only where the maintainer changes a name. The new step kinds (judged connector action, wait for approval, notify, sleep) join it. What the document lacks today, each of which must be there: - Workflow level: `inputs` and `outputs` with types, `identity`, `profile`, `repository` (required, optional, none). - Step level: `when` conditions, `on_failure` (park or continue), `retry` (attempts and backoff), `parallel` branches, step `id` for references. - References: `task.*`, `inputs.*`, `steps.<id>.summary`, `steps.<id>.result.<field>`, checked when the workflow is saved. - Agent settings: mission, a result JSON Schema, model alias, read-only, protected tests, extra rules, gate. - Step types: `command.run`, `repo.prepare`, `repo.tooling`, `repo.commit`, `repo.open-pr`, `gate.diff-rules`, `gate.repository`, `forge.comment`, `forge.close-issue`, `message.send`, `workflow.approve`, `workflow.call` (with inputs, outputs and wait), `workflow.finish` (completed, parked, waiting for approval, declined), `workflow.handoff`, `review.pr`, `review.reply`, `review.start-round`. - Run endings: the first step that sets an outcome ends the run; a failed step parks unless it continues; a parked run retries from a top-level step with the earlier results kept. The lifecycle protections in #2036 are expressed through these properties, so Archie or the person writing a workflow can set them, with defaults that match today's behaviour. Done when: every workflow in `internal/domain/workflow` and the starter documents parses and runs on the durable engine with the same steps, references and endings, and the new step kinds work beside them.
sam added the featurecritical labels 2026-11-16 10:54:54 +00:00
sam added a new dependency 2026-11-16 10:55:01 +00:00
sam added a new dependency 2026-11-17 07:29:50 +00:00
sam added a new dependency 2026-11-17 07:29:52 +00:00
sam added a new dependency 2026-11-17 07:29:57 +00:00
Author
Owner

Planned 2026-11-17 as seven children, in this order: #2039 format, references and when; #2040 retry; #2041 switch; #2042 run endings; #2043 agent.run settings; #2044 workflow.call/approve/handoff and message.send; #2045 parallel.

Scope split by owner: the sandbox step types (repo., command.run, gate., review.) execute when #2020 lands, forge. when #2034 does. Resume-at-step, the needs-a-person state and run-level transient retry stay with #2036.

Done-when amended: the corpus (the shipped documents, investigate, and the old package's test YAML) is a table test in which each row states whether it parses and checks, runs, or is refused for a named reason. A row moves to "runs" once the owners of all its step types have shipped. This issue closes when every type it owns runs.

Planned 2026-11-17 as seven children, in this order: #2039 format, references and when; #2040 retry; #2041 switch; #2042 run endings; #2043 agent.run settings; #2044 workflow.call/approve/handoff and message.send; #2045 parallel. Scope split by owner: the sandbox step types (repo.*, command.run, gate.*, review.*) execute when #2020 lands, forge.* when #2034 does. Resume-at-step, the needs-a-person state and run-level transient retry stay with #2036. Done-when amended: the corpus (the shipped documents, investigate, and the old package's test YAML) is a table test in which each row states whether it parses and checks, runs, or is refused for a named reason. A row moves to "runs" once the owners of all its step types have shipped. This issue closes when every type it owns runs.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#2037