Workflow documents use today's step shape, references and when on the durable engine #2039

Closed
opened 2026-11-17 07:29:39 +00:00 by sam · 2 comments
Owner

Child of #2037. Plan: workflow vocabulary on the durable engine, one requirement per child.

The document becomes today's shape: id/type/settings with when and on_failure, a step-type registry with strict per-type settings, workflow-level inputs, repository, instructions, identity and profile, and {{ }} references (roots task, inputs, steps) checked at save. The five kinds become types: agent.run (inline mission, memory), connector.action, approval.wait, run.notify, workflow.sleep. Results are kept per step; any number of approval waits; actions still held at the end get settled before the run finishes. retry, switch, parallel and outputs are refused until their children land. A run of a workflow naming an identity or profile is refused at start until identity (#2017) or task runs (#2020) land. List, get and save endpoints for workflows and a step-type catalog; the editor page is the first page of #2029.

Done when: the corpus table test passes with each old document marked valid or refused for a named reason, investigate runs on fakes in the new format, and staging runs investigate after its stored documents are rewritten.

Child of #2037. Plan: workflow vocabulary on the durable engine, one requirement per child. The document becomes today's shape: `id`/`type`/`settings` with `when` and `on_failure`, a step-type registry with strict per-type settings, workflow-level `inputs`, `repository`, `instructions`, `identity` and `profile`, and `{{ }}` references (roots `task`, `inputs`, `steps`) checked at save. The five kinds become types: `agent.run` (inline mission, memory), `connector.action`, `approval.wait`, `run.notify`, `workflow.sleep`. Results are kept per step; any number of approval waits; actions still held at the end get settled before the run finishes. `retry`, `switch`, `parallel` and `outputs` are refused until their children land. A run of a workflow naming an identity or profile is refused at start until identity (#2017) or task runs (#2020) land. List, get and save endpoints for workflows and a step-type catalog; the editor page is the first page of #2029. Done when: the corpus table test passes with each old document marked valid or refused for a named reason, investigate runs on fakes in the new format, and staging runs investigate after its stored documents are rewritten.
sam added the featurecritical labels 2026-11-17 07:29:39 +00:00
sam added a new dependency 2026-11-17 07:29:45 +00:00
sam added the in-progress label 2026-11-17 07:30:03 +00:00
Author
Owner

Landed in ce70d4f3e:

  • The document now takes today's shape. inputs, repository, instructions, identity and profile are declared, and steps are id/type/settings with when and on_failure.
  • Five registry types: agent.run (inline mission, memory), connector.action, approval.wait, run.notify, workflow.sleep.
  • {{ task|inputs|steps }} references are checked at save. The run input is read as inputs.event.
  • Any number of approval steps are allowed, each asking only about what was held since the last one. Anything still held is settled before the run ends.
  • Starting a run checks its inputs, and refuses a workflow that names an identity or profile. Saving a trigger is refused when it can't start its workflow.
  • New endpoints: GET/PUT /api/workflows/{name}, GET /api/workflows and GET /api/workflow-step-types.

Verified:

  • TestCorpusChecksAsItsStepTypesLand: the six old shipped documents and the old reference rules. Each old document is refused only for types or settings that a later child or #2020/#2034 adds.
  • TestDocumentStepsRun on fakes: rendering, when, continue, the end-of-run settle, and one ask per action.
  • Each table row was mutation-checked. task check passes.

Still to do: deploy to staging and rewrite the stored bodies in place, which needs the maintainer's OK.

Landed in ce70d4f3e: - The document now takes today's shape. `inputs`, `repository`, `instructions`, `identity` and `profile` are declared, and steps are `id`/`type`/`settings` with `when` and `on_failure`. - Five registry types: `agent.run` (inline mission, memory), `connector.action`, `approval.wait`, `run.notify`, `workflow.sleep`. - `{{ task|inputs|steps }}` references are checked at save. The run input is read as `inputs.event`. - Any number of approval steps are allowed, each asking only about what was held since the last one. Anything still held is settled before the run ends. - Starting a run checks its inputs, and refuses a workflow that names an identity or profile. Saving a trigger is refused when it can't start its workflow. - New endpoints: `GET/PUT /api/workflows/{name}`, `GET /api/workflows` and `GET /api/workflow-step-types`. Verified: - `TestCorpusChecksAsItsStepTypesLand`: the six old shipped documents and the old reference rules. Each old document is refused only for types or settings that a later child or #2020/#2034 adds. - `TestDocumentStepsRun` on fakes: rendering, when, continue, the end-of-run settle, and one ask per action. - Each table row was mutation-checked. `task check` passes. Still to do: deploy to staging and rewrite the stored bodies in place, which needs the maintainer's OK.
Author
Owner

The local gaps are closed in 90637aa45; staging is the remaining step.

What changed:

  • A held action is settled before the run finishes when the last approval step is conditional and was skipped, and when an approval continued past its own failure. Both used to leave held actions unasked. Resume still replays the agent and the request exactly once.
  • Triggers and dry runs refuse a document that declares an identity or profile; dry runs also check required inputs, so every entry point agrees on what can start.
  • Step ids cannot contain dots: references read dots as separators, so a dotted id could never be referenced and made save and runtime disagree.
  • The shipped investigate document now has a test that holds an action, suspends while the person decides, resumes through the journal, executes the action once, asks once, and reports one approved action.

Verified through the single binary against a disposable database: the step catalog; list/get/save; field-specific 400s for an unknown type, retry, parallel, switch, outputs and a dotted id; a rejected save creates no version; an identity document saves but its trigger is refused; a startable workflow accepts a trigger. task check passes on the commit.

Staging, which this issue still needs:

  1. Before deploying, list runs that are not succeeded, failed or cancelled: select id, workflow, workflow_version, state from runs.runs where state not in ('succeeded','failed','cancelled'). A run pinned to an old-format document cannot resume under the new parser, so let those finish on the current binary first.
  2. On deploy, the starter install publishes the new investigate as a new version because its body changed. Confirm the stored latest version is the new format before starting a run.
  3. Re-save every other stored workflow through the save endpoint with its current body. An unchanged valid body keeps its version; an invalid one answers 400 with the field path and creates nothing, which is the inventory this issue wants.
  4. Run investigate from an approved staging event with a safe connector target, then confirm the run is pinned to the new version, the trail shows the held action and its approval, and the notification names the action and outcome. Close this issue on that evidence.
The local gaps are closed in 90637aa45; staging is the remaining step. What changed: - A held action is settled before the run finishes when the last approval step is conditional and was skipped, and when an approval continued past its own failure. Both used to leave held actions unasked. Resume still replays the agent and the request exactly once. - Triggers and dry runs refuse a document that declares an identity or profile; dry runs also check required inputs, so every entry point agrees on what can start. - Step ids cannot contain dots: references read dots as separators, so a dotted id could never be referenced and made save and runtime disagree. - The shipped investigate document now has a test that holds an action, suspends while the person decides, resumes through the journal, executes the action once, asks once, and reports one approved action. Verified through the single binary against a disposable database: the step catalog; list/get/save; field-specific 400s for an unknown type, retry, parallel, switch, outputs and a dotted id; a rejected save creates no version; an identity document saves but its trigger is refused; a startable workflow accepts a trigger. task check passes on the commit. Staging, which this issue still needs: 1. Before deploying, list runs that are not succeeded, failed or cancelled: select id, workflow, workflow_version, state from runs.runs where state not in ('succeeded','failed','cancelled'). A run pinned to an old-format document cannot resume under the new parser, so let those finish on the current binary first. 2. On deploy, the starter install publishes the new investigate as a new version because its body changed. Confirm the stored latest version is the new format before starting a run. 3. Re-save every other stored workflow through the save endpoint with its current body. An unchanged valid body keeps its version; an invalid one answers 400 with the field path and creates nothing, which is the inventory this issue wants. 4. Run investigate from an approved staging event with a safe connector target, then confirm the run is pinned to the new version, the trail shows the held action and its approval, and the notification names the action and outcome. Close this issue on that evidence.
sam closed this issue 2026-11-20 14:22:27 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#2039