docs(prds): execution tree and enforced state machine
This commit is contained in:
1 parent
6401fbdfa9
commit
47fcbbea46
4 files changed
+179
-4
No files matched your search
@@ -310,7 +310,8 @@ implemented in different packages:
|
||||
## Current workflow-feature hazards
|
||||
|
||||
- There is no enforced WorkflowExecution state machine. `Store.Transition`
|
||||
ignores the supplied `from` state when updating the row.
|
||||
guards on the supplied `from` state but accepts any `from` to `to` pair. See
|
||||
`docs/prds/execution-tree-state-machine.md`.
|
||||
- State update and transition-history insertion are separate operations, so
|
||||
state and audit can diverge.
|
||||
- Callers frequently discard persistence and transition errors.
|
||||
|
||||
@@ -410,7 +410,8 @@ The migration must decide:
|
||||
|
||||
- Workflow definition and version persistence;
|
||||
- the smallest accepted-work-request contract consumed from Work Intake;
|
||||
- the enforced WorkflowExecution state machine;
|
||||
- the enforced WorkflowExecution state machine (proposed in
|
||||
`docs/prds/execution-tree-state-machine.md`);
|
||||
- atomic state and domain-event persistence;
|
||||
- migration of existing task rows and transition history;
|
||||
- disposition of current skill, Yaegi, and stage-plugin implementations;
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
"url": "/dev/architecture/agent-system/",
|
||||
"title": "Agent System",
|
||||
"section": "Architecture",
|
||||
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
|
||||
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/bindings/",
|
||||
@@ -64,7 +64,7 @@
|
||||
"url": "/dev/architecture/migration-decisions/",
|
||||
"title": "Architecture Migration Decisions",
|
||||
"section": "Architecture",
|
||||
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
|
||||
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/observability/",
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
# Execution tree and enforced state machine
|
||||
|
||||
**Status:** Draft
|
||||
**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);
|
||||
settles the "enforced WorkflowExecution state machine" item in
|
||||
`docs/architecture/migration-decisions.md` section 4.
|
||||
**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),
|
||||
`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).
|
||||
|
||||
## Decision
|
||||
|
||||
A WorkflowExecution becomes the root of a tree of StepExecutions. Every stage
|
||||
run, and every agent call a stage makes, is its own durable record with a
|
||||
parent, an attempt, a status and an outcome. Both levels move only through a
|
||||
declared transition table, enforced by the State Store in the same transaction
|
||||
that writes the audit row and the domain event.
|
||||
|
||||
## Problem
|
||||
|
||||
- A run is one `tasks` row. The only per-step record is the mutable `stage`
|
||||
column, overwritten as `workflow.Run` advances, plus observability events.
|
||||
A failed attempt cannot say which step failed or what its children did
|
||||
without replaying the event stream.
|
||||
- `Store.Transition` guards on the expected `from` status, but any `from` to
|
||||
any `to` is accepted. A `queued` to `merged` write succeeds.
|
||||
- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says
|
||||
which work was in flight, so an agent call that outlives its stage (a
|
||||
reviewer, a container) is invisible to the store.
|
||||
- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits
|
||||
`KindStageStart` separately. State and events can diverge.
|
||||
|
||||
## Model
|
||||
|
||||
```text
|
||||
WorkflowExecution (tasks row, id E)
|
||||
└── attempt N
|
||||
├── StepExecution stage "plan" depth 0
|
||||
├── StepExecution stage "implement" depth 0
|
||||
│ └── StepExecution agent "implement" depth 1
|
||||
└── StepExecution stage "review" depth 0
|
||||
├── StepExecution agent "review:1" depth 1
|
||||
└── StepExecution agent "review:2" depth 1
|
||||
```
|
||||
|
||||
- A StepExecution belongs to exactly one WorkflowExecution and one attempt.
|
||||
`parent_id` is null for a stage and names the enclosing StepExecution
|
||||
otherwise. Depth is derived from the parent, never supplied by the caller.
|
||||
- `kind` is `stage` or `agent`. A new kind needs a named consumer before it is
|
||||
added.
|
||||
- A retry starts a new attempt. Earlier attempts' StepExecutions are never
|
||||
rewritten.
|
||||
|
||||
## Transition tables
|
||||
|
||||
WorkflowExecution statuses are the existing `taskstate` constants, persisted
|
||||
strings unchanged. `taskstate` gains the one table every writer checks:
|
||||
|
||||
| From | To |
|
||||
| --------------- | ---------------------------------------------------------- |
|
||||
| `queued` | `running`, `closed_wont_do` |
|
||||
| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |
|
||||
| `waiting_human` | `queued` (approve), `closed_wont_do` |
|
||||
| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |
|
||||
| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |
|
||||
| terminal | none |
|
||||
|
||||
StepExecution statuses:
|
||||
|
||||
| From | To |
|
||||
| --------- | ------------------------------------------------------ |
|
||||
| `pending` | `running`, `cancelled` |
|
||||
| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |
|
||||
| terminal | none |
|
||||
|
||||
`interrupted` means the process running the step died or shut down. It is
|
||||
distinct from `cancelled`, which an operator or a parent asked for, and from
|
||||
`failed`, which the step reported.
|
||||
|
||||
A StepExecution cannot reach `running` while its WorkflowExecution is not
|
||||
`running`, and cannot start under a terminal parent.
|
||||
|
||||
## Enforcement
|
||||
|
||||
- The table lives in `taskstate` (no dependencies), so the store, daemon and
|
||||
gateway share one copy.
|
||||
- The State Store rejects an illegal transition with a new sentinel,
|
||||
`ErrIllegalTransition`, carried across the wire through `mapError` like
|
||||
`ErrStaleTransition`. A stale `from` stays `ErrStaleTransition`.
|
||||
- Each transition is one transaction: guarded row update, audit row, domain
|
||||
event row. The events table is written by the store, not emitted beside it.
|
||||
`KindStageStart` and `KindStageFinish` are produced by the step transition.
|
||||
- `workflow.Run` stops discarding persistence errors. A failed step write
|
||||
parks the execution; the step does not run unrecorded.
|
||||
|
||||
## Cancellation
|
||||
|
||||
Stopping a run is one store call, `CancelExecution(E, reason)`. In one
|
||||
transaction it moves every non-terminal StepExecution of the current attempt
|
||||
to `cancelled` and the WorkflowExecution to `closed_wont_do` or `parked`,
|
||||
whichever the operator action names. The daemon then cancels the in-memory
|
||||
context. A worker whose step write returns `ErrStaleTransition` because its
|
||||
step is already `cancelled` stops without writing further.
|
||||
|
||||
The store is the record of cancellation. The context cancel is the delivery
|
||||
mechanism, so a lost cancel still leaves the store correct and the worker's
|
||||
next write fails.
|
||||
|
||||
## Crash recovery
|
||||
|
||||
`RecoverStale` moves every `running` StepExecution of an interrupted
|
||||
execution to `interrupted` in the same transaction that requeues the
|
||||
execution. The next attempt starts with fresh steps.
|
||||
|
||||
## Wire contract
|
||||
|
||||
New State Store RPCs, each with a matching Go method on a narrow consumer
|
||||
facade:
|
||||
|
||||
- `StartStep(execution, attempt, parent, kind, name) -> step id`
|
||||
- `FinishStep(step, from, to, detail, tokens_used)`
|
||||
- `CancelExecution(execution, reason, to)`
|
||||
- `ListSteps(execution, attempt)`
|
||||
|
||||
`TaskGrants.UnaryInterceptor` authorises a task-scoped token for `StartStep`
|
||||
and `FinishStep` on its own execution only. The container records its own
|
||||
agent calls. `CancelExecution` and `ListSteps` require the administrative
|
||||
token.
|
||||
|
||||
## Storage
|
||||
|
||||
One new table, `step_executions`: `id`, `execution_id`, `attempt`,
|
||||
`parent_id`, `depth`, `kind`, `name`, `status`, `detail`, `tokens_used`,
|
||||
`started_at`, `finished_at`. Indexed on `(execution_id, attempt, id)`.
|
||||
Existing rows gain no backfilled steps. Their history stays in `transitions`
|
||||
and `events`.
|
||||
|
||||
`tasks.stage` is written from the step transition while any reader still uses
|
||||
it, then dropped once the dashboard reads `ListSteps`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Running sibling steps in parallel. The tree records concurrency; changing
|
||||
the stage runner is separate work.
|
||||
- Cost in currency. `tokens_used` per step is the only usage field.
|
||||
- Workflow definition versioning and the `tasks` to `workflow_executions`
|
||||
rename.
|
||||
- A harness contract for swappable coding agents.
|
||||
|
||||
## Plan
|
||||
|
||||
1. `taskstate` transition tables with table-driven tests covering every
|
||||
legal and a sample of illegal pairs.
|
||||
2. `ErrIllegalTransition` enforced in the Postgres store and mapped over the
|
||||
wire.
|
||||
3. `step_executions` migration, `StartStep`/`FinishStep`, grant rules;
|
||||
`workflow.Run` records stages; events written in the transition
|
||||
transaction.
|
||||
4. Agent-call children recorded from the agent runtime.
|
||||
5. `CancelExecution`; daemon stop and chat/dashboard actions route through it.
|
||||
6. `RecoverStale` interrupts running steps.
|
||||
7. Dashboard run detail reads `ListSteps`; `tasks.stage` dropped.
|
||||
|
||||
## Verification
|
||||
|
||||
- An illegal WorkflowExecution or StepExecution transition returns
|
||||
`ErrIllegalTransition` over gRPC, and `errors.Is` matches on the client.
|
||||
- Killing the daemon mid-stage, then restarting, leaves that stage
|
||||
`interrupted` and the execution `queued` with a new attempt.
|
||||
- Stopping a run during review leaves every review child `cancelled`, and a
|
||||
late `FinishStep` from the container returns `ErrStaleTransition`.
|
||||
- A task-scoped token cannot `StartStep` on another execution.
|
||||
- For every step transition there is exactly one event row, written in the
|
||||
same transaction.
|
||||
Reference in new issue
Block a user