diff --git a/docs/architecture/agent-system.md b/docs/architecture/agent-system.md index 34e39d240..5fad4b444 100644 --- a/docs/architecture/agent-system.md +++ b/docs/architecture/agent-system.md @@ -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. diff --git a/docs/architecture/migration-decisions.md b/docs/architecture/migration-decisions.md index b7fe56b45..721578097 100644 --- a/docs/architecture/migration-decisions.md +++ b/docs/architecture/migration-decisions.md @@ -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; diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 569aa3f1f..c8d7b5000 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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\nor send messages, retain information, or propose durable workflow-backed work.\nNone of these operations inherently requires a WorkflowExecution.\n\n## Agent and Workflow domain boundary\n\nAgent and Workflow are separate domains:\n\n```text\ninternal/domain/agent\ninternal/domain/workflow\n```\n\nThe Agent domain owns persistent assistants, their specialisation, instructions,\nmodel-independent continuity, capability context, and associations with identity\nand memory.\n\nThe Workflow domain owns reusable, user- or Agent-defined behaviour and every\ndurable execution of that behaviour. An Agent may invoke or define a Workflow,\nbut the Workflow is not part of the Agent aggregate and does not require a\nconversational Agent interaction to execute.\n\n## Canonical workflow model\n\nThe Workflow feature uses these canonical terms:\n\n- **Workflow**: a reusable, versioned definition of how an agent behaves and\n performs a kind of work.\n- **WorkflowExecution**: one durable execution of a specific Workflow version.\n- **WorkflowStep**: one defined operation in a Workflow.\n- **StepExecution**: the recorded execution and outcome of one WorkflowStep.\n- **Attempt**: a retry of the same WorkflowExecution, not a new execution.\n\nA Workflow MAY structure any repeatable agent behaviour, including personal\nassistance and scheduled routines. For example, a morning email review may\ncombine a schedule event, message retrieval tool, LLM classification and\nsummarisation, and delivery of the resulting rundown. Workflow is therefore not\nrestricted to forge work, source changes, or requests submitted by a user at\nexecution time.\n\nWorkflows are extensible through Workflow-owned plugins. The Workflow domain\ndefines the typed plugin registration, definition, validation, versioning, and\nexecution contracts. Users and Agents may define reusable Workflows through\nthose contracts.\n\nThe generic plugin contract remains metadata-only. It MUST NOT own Workflow\nsemantics or replace the Workflow registry with generic hooks.\n\n`Workflow` and `WorkflowExecution` are the names used in architecture, generated\nreference, configuration, commands, events, and external contracts. The\nimplementation MAY use package qualification to remain concise:\n\n```go\nworkflow.Definition\nworkflow.Execution\nworkflow.Step\nworkflow.StepExecution\n```\n\nThe unqualified name `Execution` MUST NOT be used in cross-domain contracts or\ndocumentation because it is ambiguous among workflow, tool, command, policy, and\nservice execution.\n\n## Current workflow-execution feature\n\nThe current feature takes a channel request through agent execution and a\ndurable outcome.\n\nCurrent execution state includes source-message references, owning identity,\nrepository, selected workflow and stage, agent output, branch and pull-request\nreferences, token and iteration counts, retry information, human-wait\ninformation, and failure details.\n\nThe current `store.Task` lifecycle uses:\n\n```text\nqueued -\u003e running\nrunning -\u003e waiting_human | pr_open | merged | parked | closed_wont_do\nwaiting_human -\u003e queued | closed_wont_do\nparked -\u003e queued | dead\npr_open -\u003e merged | rejected\nrunning after crash -\u003e queued\n```\n\nWorkflows select and sequence deterministic and agent-run stages. Implement,\nTDD, feasibility, and bootstrap are current Workflow definitions.\nEvery WorkflowExecution is handed wholesale over core NATS to a task-scoped\n`archie-agent` container, which owns the workflow stage loop.\n\n## Current workflow-feature placement\n\nThe behaviour is divided across technical packages:\n\n- `internal/domain/workflow` defines the current `Task` execution record and\n status strings; `internal/infrastructure/postgres` persists mutable state\n and transition history behind `internal/domain/storecontract`.\n- `internal/daemon` discovers, claims, schedules, retries, recovers, processes,\n waits for human input, and reconciles pull requests.\n- `internal/domain/workflow` routes work, executes stages, mutates tasks, applies\n outcomes, parks failures, and performs forge/worktree operations.\n- `internal/agentexec` defines and runs individual autonomous-stage protocols.\n- `internal/taskrun` hands a complete WorkflowExecution to a container worker.\n- `internal/gate` and repository configuration define execution constraints.\n- `internal/gateway` duplicates task status strings and applies task-control\n rules.\n- forge, worktree, NATS, PostgreSQL, containers, and agent runtimes are concrete\n dependencies mixed into orchestration.\n\n## Current `task` meanings and required replacements\n\nThe existing code uses `task` for unrelated concepts. Migration MUST resolve\neach meaning deliberately; a global text replacement is prohibited.\n\n| Current meaning | Representative locations | Target concept | Requirements |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. |\n| Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. |\n| Persisted `workflow.Task` row | `internal/infrastructure/postgres` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. |\n| Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. |\n| Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. |\n| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. |\n| `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. |\n| Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. |\n| NATS `TaskMessage` and `archie.task.*` | `internal/domain/workintake` (subjects, `TaskEnvelope`); `internal/infrastructure/agenttransport/nats` (transport) -- `internal/nats` no longer exists; whether this row's \"current meaning\" itself is now superseded by `TaskEnvelope` needs a closer look, not asserted here | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. |\n| `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialisation is policy, not identity derived from an incomplete task struct. |\n| `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. |\n| `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |\n| Gateway `TaskCreator` | `internal/gateway` | Accepted work request handoff | A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff. |\n| Gateway `TaskController` and `ChatTaskStatus` | `internal/gateway/tasks.go` | WorkflowExecution commands and query view | Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions. |\n| Gateway `TaskProfile` | `internal/gateway/tasks.go`, `cmd/archied` | Channel/identity execution defaults | This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features. |\n| `config.TaskConfig` and `TaskForge` | `internal/config` | Worker execution settings and channel/service references | Dissolve with `internal/config`. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain. |\n| `events.Event.TaskID`, task event timelines | `internal/events`, stores, web UI | WorkflowExecutionID and WorkflowExecution events | Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events. |\n| Web UI task lists and counts | `internal/webui`, store query APIs | WorkflowExecution read model | Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records. |\n| Task-scoped forge/store/worktree RPC | `forgerpc`, `storerpc`, `worktreerpc`, `registerTaskRPCServers` | Execution-scoped capability ports | Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden. |\n| Per-task worktree, branch, volume, and cleanup | daemon, worktree, storage, container | WorkflowExecution workspace | Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model. |\n| Task retry, dead, waiting-human, PR reconciliation | daemon, workflow, gateway | WorkflowExecution lifecycle policies | Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state. |\n| Task-run readiness and retry timeouts | daemon taskrun request loop | Worker-dispatch settings and policy | These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability. |\n\n### Terms that do not migrate\n\n- The `task` command in `Taskfile.yml` is the external Task build tool and keeps\n its name.\n- A forge may call its own records issues or tasks inside its channel adapter.\n- General prose may use “task” informally only when it clearly refers to an\n external system. Agent System contracts and generated reference MUST use the\n canonical Workflow vocabulary.\n\n## Current WorkflowExecution data inventory\n\nThis inventory is the migration ledger for data currently spread across\n`store.Task`, database-only columns, `workflow.TaskContext`, worker messages,\nand surrounding configuration. Implementation SHOULD NOT require another\nrepository-wide search to determine what existing execution data must be\npreserved or deliberately removed.\n\n| Current data | Current representation | Required target |\n| ---------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| Execution identity | `Task.ID`, `task_id`, NATS subjects, logs | Immutable WorkflowExecutionID used consistently by state, events, workers, projections, and capability calls |\n| Owning actor | `Task.Identity` string | Canonical IdentityID |\n| Source type | `Task.Source` (`forge` or `chat`) | Typed channel and SourceMessageReference; no closed source enum in WorkflowExecution |\n| Source address | `Owner`, `Repo`, `IssueNumber`; synthetic chat issue number | Channel-owned source reference with native message/thread/object identifiers; synthetic identifiers removed |\n| Requested work | `Title`, `Body`, `Labels` | Immutable execution input captured from the source request; channel-specific metadata retained in the source envelope |\n| Workflow selection | `Workflow` string | Immutable WorkflowID plus selected WorkflowVersion |\n| Lifecycle | `Status` string | Enforced WorkflowExecution state |\n| Current position | mutable `Stage` string | Derived current WorkflowStep reference plus durable StepExecution history |\n| Attempts | `Attempt`, `RetryCount` | Execution attempt history and retry-policy evidence; distinguish worker delivery retry from workflow retry |\n| Failure | `ParkReason`, transition detail, response errors | Typed failure classification, evidence, retryability, and resulting lifecycle event |\n| Human wait | `WatchCommentID`, `waiting_human` | Channel-neutral wait condition and correlation reference; forge comment IDs stay in the forge channel |\n| Workspace | `Dir`, `Branch`, worktree path, `task.json` | Execution workspace reference and independently managed workspace lifecycle |\n| Change outcome | `BuildSummary`, `BuildNoChanges`, changed files | Step outputs and final WorkflowExecution outcome |\n| Reproduction evidence | `ReproProof` | Typed TDD step evidence retained with the StepExecution and final outcome |\n| Planning output | `Plan` | Typed step output referenced by later steps rather than a special aggregate field |\n| Notes | `Notes`, appended agent notes | Ordered execution annotations with actor, source step, and timestamp |\n| Pull request | `PRNumber`, forge host/repository assumptions | Forge-channel delivery reference and reconciliation state |\n| Agent usage | `TokensUsed`, `Iterations` | StepExecution usage measurements aggregated into execution projections |\n| Decision capture | private feasibility `decision`, capture-tool output | Typed WorkflowStep output defined by that Workflow version |\n| Terminal outcome | mutable `Outcome{Status, Detail}` | Explicit WorkflowExecution outcome command/event validated by the state machine |\n| Skill context | `SkillBody`, `SkillPlugins` | Resolved Workflow version dependencies or execution inputs, with provenance |\n| Agent prompt context | `SystemPrompt`, `ExtraRules`, mission strings | Versioned WorkflowStep definition plus resolved execution context; mutable global prompt callbacks removed |\n| Gates and protection | `Gate`, `Preflight`, `Protection`, repository config | Agent System policy definitions resolved for the WorkflowExecution and enforced outside the agent |\n| Budgets | steps, tokens, wall clock, gate failures | Execution and StepExecution policy values with measured usage and evidence |\n| Tool access | capture tools, registry, guardrails, skill plugins | Resolved step capability set and policy; global registry pointers do not enter execution state |\n| Persistence timestamps | SQL `created_at` and `updated_at` | Domain timestamps and version used for optimistic concurrency and audit |\n| Transition history | SQL `transitions` and generic events | Authoritative WorkflowExecution domain events stored atomically with state |\n\n## Current runtime responsibilities to unify\n\nThe following behaviours currently act on the same WorkflowExecution but are\nimplemented in different packages:\n\n- accept a request from a channel and enforce idempotency;\n- select and version a Workflow;\n- create, queue, claim, schedule, and execute a WorkflowExecution;\n- serialise same-repository execution where policy requires it;\n- resolve identity-specific capabilities;\n- prepare, retain, recover, and clean up the workspace;\n- run deterministic and agent-backed WorkflowSteps;\n- enforce gates, budgets, protected paths, tool constraints, and result review;\n- persist state and StepExecution outputs;\n- publish authoritative lifecycle events;\n- wait for channel input and resume;\n- classify failure, retry, park, mark exhausted, cancel, or recover after crash;\n- deliver and reconcile forge changes;\n- project status, history, counts, and audit for channels and the web UI;\n- hand execution to a worker without moving domain ownership to the worker.\n\n## Current workflow-feature hazards\n\n- There is no enforced WorkflowExecution state machine. `Store.Transition`\n ignores the supplied `from` state when updating the row.\n- State update and transition-history insertion are separate operations, so\n state and audit can diverge.\n- Callers frequently discard persistence and transition errors.\n- Gateway task control duplicates lifecycle status constants by hand.\n- `workflow.TaskContext` is a mutable service bag containing complete\n configuration plus forge, store, worktree, agent, event bus, logging, memory,\n guardrails, skills, and scratch state.\n- Lifecycle changes occur in both daemon and workflow code.\n- Workflow orchestration runs inside task-scoped agent containers while the\n daemon retains lifecycle, admission, and authority-bearing RPC ownership.\n- Forge-backed and chat-created work share one record through source flags and\n synthetic issue numbers.\n- Repository labels currently select workflows and mirror task state, coupling\n domain transitions to forge presentation.\n- Failure generally becomes `parked`, but failure classification and\n retryability are not represented explicitly.\n- Generic observability events are emitted alongside state changes rather than\n being the authoritative domain events.\n\n## Existing invariants to preserve\n\n- The model never performs git operations directly.\n- Deterministic policy and gates cannot be waived by the agent.\n- TDD captures a failing reproduction before implementation and protects the\n test during the fix.\n- Every run ends in an explicit outcome; definition errors and stage errors do\n not disappear silently.\n- Crash recovery requeues interrupted work.\n- Agent execution crosses a versioned data boundary.\n- Forge, persistence, workspace, transport, container, and model runtimes remain\n replaceable infrastructure.\n- Work from the same repository is serialised by default.\n\n## Required migration\n\n- Rename the current persisted `store.Task` concept to WorkflowExecution.\n- Replace task lifecycle terminology in core commands, events, persistence,\n worker contracts, logs, and generated reference.\n- Preserve external source terminology only inside its channel adapter.\n- Replace synthetic issue numbers with explicit source-message references.\n- Associate every WorkflowExecution with an immutable Workflow identifier and\n version.\n- Record StepExecutions explicitly rather than treating one mutable `stage`\n field as complete execution history.\n- Keep Attempt as retry state within the same WorkflowExecution.\n\n## Curator isolation invariant\n\nDecided 2026-08-05\n([#435](https://github.com/samcharles93/archie-core/issues/435) epic,\n[#98](https://github.com/samcharles93/archie-core/issues/98) runtime).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Curators are peers, not dependencies.** They must never block, delay, or take\ndown chat turns, agent runs, or the daemon.\n\n1. Registry-owned goroutines, one per curator, with per-pass `recover()`,\n per-pass budgets (max steps, tokens, timeout), and a configurable maximum of\n concurrent passes (default 1) so curators cannot saturate the shared LLM\n runtime against chat.\n2. Wake events ride the in-process `events.Bus`, which is mutex fan-out with\n bounded per-subscriber buffers that **drop** on overflow\n (`internal/events/events.go`). A slow curator can never backpressure the chat\n publisher.\n3. Wake is a best-effort nudge. The trigger is a deterministic read of persisted\n primary-input state at pass time, so a dropped wake only delays a run to the\n next check-in and never corrupts trigger accounting\n ([#22](https://github.com/samcharles93/archie-core/issues/22)).\n4. The curator registry lifecycle is independent of the agent loop. Daemon\n shutdown cancels in-flight passes and waits bounded.\n\nChat turns keep their per-session lanes; agent runs keep their workflow\ngoroutines and containers. Rule of thumb: **no code path a curator executes may\never appear on a chat turn's critical path.**\n" + "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\nor send messages, retain information, or propose durable workflow-backed work.\nNone of these operations inherently requires a WorkflowExecution.\n\n## Agent and Workflow domain boundary\n\nAgent and Workflow are separate domains:\n\n```text\ninternal/domain/agent\ninternal/domain/workflow\n```\n\nThe Agent domain owns persistent assistants, their specialisation, instructions,\nmodel-independent continuity, capability context, and associations with identity\nand memory.\n\nThe Workflow domain owns reusable, user- or Agent-defined behaviour and every\ndurable execution of that behaviour. An Agent may invoke or define a Workflow,\nbut the Workflow is not part of the Agent aggregate and does not require a\nconversational Agent interaction to execute.\n\n## Canonical workflow model\n\nThe Workflow feature uses these canonical terms:\n\n- **Workflow**: a reusable, versioned definition of how an agent behaves and\n performs a kind of work.\n- **WorkflowExecution**: one durable execution of a specific Workflow version.\n- **WorkflowStep**: one defined operation in a Workflow.\n- **StepExecution**: the recorded execution and outcome of one WorkflowStep.\n- **Attempt**: a retry of the same WorkflowExecution, not a new execution.\n\nA Workflow MAY structure any repeatable agent behaviour, including personal\nassistance and scheduled routines. For example, a morning email review may\ncombine a schedule event, message retrieval tool, LLM classification and\nsummarisation, and delivery of the resulting rundown. Workflow is therefore not\nrestricted to forge work, source changes, or requests submitted by a user at\nexecution time.\n\nWorkflows are extensible through Workflow-owned plugins. The Workflow domain\ndefines the typed plugin registration, definition, validation, versioning, and\nexecution contracts. Users and Agents may define reusable Workflows through\nthose contracts.\n\nThe generic plugin contract remains metadata-only. It MUST NOT own Workflow\nsemantics or replace the Workflow registry with generic hooks.\n\n`Workflow` and `WorkflowExecution` are the names used in architecture, generated\nreference, configuration, commands, events, and external contracts. The\nimplementation MAY use package qualification to remain concise:\n\n```go\nworkflow.Definition\nworkflow.Execution\nworkflow.Step\nworkflow.StepExecution\n```\n\nThe unqualified name `Execution` MUST NOT be used in cross-domain contracts or\ndocumentation because it is ambiguous among workflow, tool, command, policy, and\nservice execution.\n\n## Current workflow-execution feature\n\nThe current feature takes a channel request through agent execution and a\ndurable outcome.\n\nCurrent execution state includes source-message references, owning identity,\nrepository, selected workflow and stage, agent output, branch and pull-request\nreferences, token and iteration counts, retry information, human-wait\ninformation, and failure details.\n\nThe current `store.Task` lifecycle uses:\n\n```text\nqueued -\u003e running\nrunning -\u003e waiting_human | pr_open | merged | parked | closed_wont_do\nwaiting_human -\u003e queued | closed_wont_do\nparked -\u003e queued | dead\npr_open -\u003e merged | rejected\nrunning after crash -\u003e queued\n```\n\nWorkflows select and sequence deterministic and agent-run stages. Implement,\nTDD, feasibility, and bootstrap are current Workflow definitions.\nEvery WorkflowExecution is handed wholesale over core NATS to a task-scoped\n`archie-agent` container, which owns the workflow stage loop.\n\n## Current workflow-feature placement\n\nThe behaviour is divided across technical packages:\n\n- `internal/domain/workflow` defines the current `Task` execution record and\n status strings; `internal/infrastructure/postgres` persists mutable state\n and transition history behind `internal/domain/storecontract`.\n- `internal/daemon` discovers, claims, schedules, retries, recovers, processes,\n waits for human input, and reconciles pull requests.\n- `internal/domain/workflow` routes work, executes stages, mutates tasks, applies\n outcomes, parks failures, and performs forge/worktree operations.\n- `internal/agentexec` defines and runs individual autonomous-stage protocols.\n- `internal/taskrun` hands a complete WorkflowExecution to a container worker.\n- `internal/gate` and repository configuration define execution constraints.\n- `internal/gateway` duplicates task status strings and applies task-control\n rules.\n- forge, worktree, NATS, PostgreSQL, containers, and agent runtimes are concrete\n dependencies mixed into orchestration.\n\n## Current `task` meanings and required replacements\n\nThe existing code uses `task` for unrelated concepts. Migration MUST resolve\neach meaning deliberately; a global text replacement is prohibited.\n\n| Current meaning | Representative locations | Target concept | Requirements |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. |\n| Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. |\n| Persisted `workflow.Task` row | `internal/infrastructure/postgres` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. |\n| Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. |\n| Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. |\n| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. |\n| `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. |\n| Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. |\n| NATS `TaskMessage` and `archie.task.*` | `internal/domain/workintake` (subjects, `TaskEnvelope`); `internal/infrastructure/agenttransport/nats` (transport) -- `internal/nats` no longer exists; whether this row's \"current meaning\" itself is now superseded by `TaskEnvelope` needs a closer look, not asserted here | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. |\n| `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialisation is policy, not identity derived from an incomplete task struct. |\n| `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. |\n| `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |\n| Gateway `TaskCreator` | `internal/gateway` | Accepted work request handoff | A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff. |\n| Gateway `TaskController` and `ChatTaskStatus` | `internal/gateway/tasks.go` | WorkflowExecution commands and query view | Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions. |\n| Gateway `TaskProfile` | `internal/gateway/tasks.go`, `cmd/archied` | Channel/identity execution defaults | This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features. |\n| `config.TaskConfig` and `TaskForge` | `internal/config` | Worker execution settings and channel/service references | Dissolve with `internal/config`. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain. |\n| `events.Event.TaskID`, task event timelines | `internal/events`, stores, web UI | WorkflowExecutionID and WorkflowExecution events | Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events. |\n| Web UI task lists and counts | `internal/webui`, store query APIs | WorkflowExecution read model | Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records. |\n| Task-scoped forge/store/worktree RPC | `forgerpc`, `storerpc`, `worktreerpc`, `registerTaskRPCServers` | Execution-scoped capability ports | Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden. |\n| Per-task worktree, branch, volume, and cleanup | daemon, worktree, storage, container | WorkflowExecution workspace | Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model. |\n| Task retry, dead, waiting-human, PR reconciliation | daemon, workflow, gateway | WorkflowExecution lifecycle policies | Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state. |\n| Task-run readiness and retry timeouts | daemon taskrun request loop | Worker-dispatch settings and policy | These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability. |\n\n### Terms that do not migrate\n\n- The `task` command in `Taskfile.yml` is the external Task build tool and keeps\n its name.\n- A forge may call its own records issues or tasks inside its channel adapter.\n- General prose may use “task” informally only when it clearly refers to an\n external system. Agent System contracts and generated reference MUST use the\n canonical Workflow vocabulary.\n\n## Current WorkflowExecution data inventory\n\nThis inventory is the migration ledger for data currently spread across\n`store.Task`, database-only columns, `workflow.TaskContext`, worker messages,\nand surrounding configuration. Implementation SHOULD NOT require another\nrepository-wide search to determine what existing execution data must be\npreserved or deliberately removed.\n\n| Current data | Current representation | Required target |\n| ---------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| Execution identity | `Task.ID`, `task_id`, NATS subjects, logs | Immutable WorkflowExecutionID used consistently by state, events, workers, projections, and capability calls |\n| Owning actor | `Task.Identity` string | Canonical IdentityID |\n| Source type | `Task.Source` (`forge` or `chat`) | Typed channel and SourceMessageReference; no closed source enum in WorkflowExecution |\n| Source address | `Owner`, `Repo`, `IssueNumber`; synthetic chat issue number | Channel-owned source reference with native message/thread/object identifiers; synthetic identifiers removed |\n| Requested work | `Title`, `Body`, `Labels` | Immutable execution input captured from the source request; channel-specific metadata retained in the source envelope |\n| Workflow selection | `Workflow` string | Immutable WorkflowID plus selected WorkflowVersion |\n| Lifecycle | `Status` string | Enforced WorkflowExecution state |\n| Current position | mutable `Stage` string | Derived current WorkflowStep reference plus durable StepExecution history |\n| Attempts | `Attempt`, `RetryCount` | Execution attempt history and retry-policy evidence; distinguish worker delivery retry from workflow retry |\n| Failure | `ParkReason`, transition detail, response errors | Typed failure classification, evidence, retryability, and resulting lifecycle event |\n| Human wait | `WatchCommentID`, `waiting_human` | Channel-neutral wait condition and correlation reference; forge comment IDs stay in the forge channel |\n| Workspace | `Dir`, `Branch`, worktree path, `task.json` | Execution workspace reference and independently managed workspace lifecycle |\n| Change outcome | `BuildSummary`, `BuildNoChanges`, changed files | Step outputs and final WorkflowExecution outcome |\n| Reproduction evidence | `ReproProof` | Typed TDD step evidence retained with the StepExecution and final outcome |\n| Planning output | `Plan` | Typed step output referenced by later steps rather than a special aggregate field |\n| Notes | `Notes`, appended agent notes | Ordered execution annotations with actor, source step, and timestamp |\n| Pull request | `PRNumber`, forge host/repository assumptions | Forge-channel delivery reference and reconciliation state |\n| Agent usage | `TokensUsed`, `Iterations` | StepExecution usage measurements aggregated into execution projections |\n| Decision capture | private feasibility `decision`, capture-tool output | Typed WorkflowStep output defined by that Workflow version |\n| Terminal outcome | mutable `Outcome{Status, Detail}` | Explicit WorkflowExecution outcome command/event validated by the state machine |\n| Skill context | `SkillBody`, `SkillPlugins` | Resolved Workflow version dependencies or execution inputs, with provenance |\n| Agent prompt context | `SystemPrompt`, `ExtraRules`, mission strings | Versioned WorkflowStep definition plus resolved execution context; mutable global prompt callbacks removed |\n| Gates and protection | `Gate`, `Preflight`, `Protection`, repository config | Agent System policy definitions resolved for the WorkflowExecution and enforced outside the agent |\n| Budgets | steps, tokens, wall clock, gate failures | Execution and StepExecution policy values with measured usage and evidence |\n| Tool access | capture tools, registry, guardrails, skill plugins | Resolved step capability set and policy; global registry pointers do not enter execution state |\n| Persistence timestamps | SQL `created_at` and `updated_at` | Domain timestamps and version used for optimistic concurrency and audit |\n| Transition history | SQL `transitions` and generic events | Authoritative WorkflowExecution domain events stored atomically with state |\n\n## Current runtime responsibilities to unify\n\nThe following behaviours currently act on the same WorkflowExecution but are\nimplemented in different packages:\n\n- accept a request from a channel and enforce idempotency;\n- select and version a Workflow;\n- create, queue, claim, schedule, and execute a WorkflowExecution;\n- serialise same-repository execution where policy requires it;\n- resolve identity-specific capabilities;\n- prepare, retain, recover, and clean up the workspace;\n- run deterministic and agent-backed WorkflowSteps;\n- enforce gates, budgets, protected paths, tool constraints, and result review;\n- persist state and StepExecution outputs;\n- publish authoritative lifecycle events;\n- wait for channel input and resume;\n- classify failure, retry, park, mark exhausted, cancel, or recover after crash;\n- deliver and reconcile forge changes;\n- project status, history, counts, and audit for channels and the web UI;\n- hand execution to a worker without moving domain ownership to the worker.\n\n## Current workflow-feature hazards\n\n- There is no enforced WorkflowExecution state machine. `Store.Transition`\n guards on the supplied `from` state but accepts any `from` to `to` pair. See\n `docs/prds/execution-tree-state-machine.md`.\n- State update and transition-history insertion are separate operations, so\n state and audit can diverge.\n- Callers frequently discard persistence and transition errors.\n- Gateway task control duplicates lifecycle status constants by hand.\n- `workflow.TaskContext` is a mutable service bag containing complete\n configuration plus forge, store, worktree, agent, event bus, logging, memory,\n guardrails, skills, and scratch state.\n- Lifecycle changes occur in both daemon and workflow code.\n- Workflow orchestration runs inside task-scoped agent containers while the\n daemon retains lifecycle, admission, and authority-bearing RPC ownership.\n- Forge-backed and chat-created work share one record through source flags and\n synthetic issue numbers.\n- Repository labels currently select workflows and mirror task state, coupling\n domain transitions to forge presentation.\n- Failure generally becomes `parked`, but failure classification and\n retryability are not represented explicitly.\n- Generic observability events are emitted alongside state changes rather than\n being the authoritative domain events.\n\n## Existing invariants to preserve\n\n- The model never performs git operations directly.\n- Deterministic policy and gates cannot be waived by the agent.\n- TDD captures a failing reproduction before implementation and protects the\n test during the fix.\n- Every run ends in an explicit outcome; definition errors and stage errors do\n not disappear silently.\n- Crash recovery requeues interrupted work.\n- Agent execution crosses a versioned data boundary.\n- Forge, persistence, workspace, transport, container, and model runtimes remain\n replaceable infrastructure.\n- Work from the same repository is serialised by default.\n\n## Required migration\n\n- Rename the current persisted `store.Task` concept to WorkflowExecution.\n- Replace task lifecycle terminology in core commands, events, persistence,\n worker contracts, logs, and generated reference.\n- Preserve external source terminology only inside its channel adapter.\n- Replace synthetic issue numbers with explicit source-message references.\n- Associate every WorkflowExecution with an immutable Workflow identifier and\n version.\n- Record StepExecutions explicitly rather than treating one mutable `stage`\n field as complete execution history.\n- Keep Attempt as retry state within the same WorkflowExecution.\n\n## Curator isolation invariant\n\nDecided 2026-08-05\n([#435](https://github.com/samcharles93/archie-core/issues/435) epic,\n[#98](https://github.com/samcharles93/archie-core/issues/98) runtime).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Curators are peers, not dependencies.** They must never block, delay, or take\ndown chat turns, agent runs, or the daemon.\n\n1. Registry-owned goroutines, one per curator, with per-pass `recover()`,\n per-pass budgets (max steps, tokens, timeout), and a configurable maximum of\n concurrent passes (default 1) so curators cannot saturate the shared LLM\n runtime against chat.\n2. Wake events ride the in-process `events.Bus`, which is mutex fan-out with\n bounded per-subscriber buffers that **drop** on overflow\n (`internal/events/events.go`). A slow curator can never backpressure the chat\n publisher.\n3. Wake is a best-effort nudge. The trigger is a deterministic read of persisted\n primary-input state at pass time, so a dropped wake only delays a run to the\n next check-in and never corrupts trigger accounting\n ([#22](https://github.com/samcharles93/archie-core/issues/22)).\n4. The curator registry lifecycle is independent of the agent loop. Daemon\n shutdown cancels in-flight passes and waits bounded.\n\nChat turns keep their per-session lanes; agent runs keep their workflow\ngoroutines and containers. Rule of thumb: **no code path a curator executes may\never appear on a chat turn's critical path.**\n" }, { "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\nauthentication, UI response projection, configuration reads and mutations,\ntask/control APIs, and direct adapters to State Store, channel, event/log,\nmemory, curator, workflow, forge, and Gateway runtime values. The target owner\nis a standalone UI application process; `internal/webui` remains its HTTP\ntransport adapter, while Gateway, State Store, configuration, Work Intake,\nMessaging, and other capability owners expose the contracts behind those\nroutes. The migration preserves retained route schemas, auth/CSRF behaviour,\ntask/capture/mapping/binding/session continuity, SSE replay semantics, and\ncommitted generated SPA assets. Prerequisites are the ratified UI boundary,\nroute-owner inventory, narrow remote adapters, configuration/auth/readiness\ncontracts, and process/conformance tests. Remove the shared live\n`config.Holder`, direct event/log bus, daemon stopper, forge client, channel\nmanager, capability registries, composite store access, and in-process UI\nlistener only after the focused criteria in\n[`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/) pass in\nproduction composition. The old construction and listener are deleted in the\nsame cutover change; no second UI authority remains.\n\n### 2. Session and Messaging migration\n\nThe existing session implementation is the migration baseline. The migration must\ndecide:\n\n- which session and message components are retained or adapted;\n- how Agent, user, channel, Conversation, and branch ownership are added;\n- how Archie's parallel gateway session implementation is replaced;\n- how canonical Messages become immutable persisted records;\n- how existing sessions and messages are migrated;\n- how outbound delivery, retry, acknowledgement, deduplication, and failure\n semantics are represented;\n- how current Telegram, email, webhook, forge, and Jira integrations migrate to\n Messaging infrastructure adapters.\n\nThe following are already decided and MUST NOT be reopened without contradictory\nimplementation evidence:\n\n- the composite Conversation identity;\n- immutable MessageIDs;\n- typed tool-call and tool-result messages;\n- exact branch lineage through ParentConversationID and ForkMessageID;\n- parent and child transcript isolation;\n- normal scoped-memory behaviour regardless of the originating Conversation;\n- Messaging and Work Intake ownership.\n\n**Decision (2026-08-31), resolving the open questions above:**\n\n`internal/gateway/` is the \"parallel gateway session implementation\" this\nsection names. It is retained as-is for now — a big-bang rewrite of live\nsession/compression/approval/branch logic across Telegram, web UI, email, and\nwebhook channels in one change is exactly the \"convoluted to satisfy edge\ncases\" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would\nrisk silent behavioural regressions in the one path every user-facing message\ntravels through.\n\nInstead, `internal/domain/messaging/` is materialised now with the pieces\nthat are already decided and don't require touching gateway: the canonical\n`Message` and `Conversation` types (composite Conversation identity, immutable\n`MessageID`, typed tool-call/tool-result message variants, branch lineage via\n`ParentConversationID`/`ForkMessageID`). These are pure domain types with no\ngateway dependency — a new package, not a rewrite of an existing one.\n\nMigrating `internal/gateway/`'s session, compression, approval, and branch\nlogic onto these types is real, cross-channel-risk work and is **not** done in\nthis pass. It is tracked as separate, appropriately-scoped bd issues (see\n`bd list --label messaging-migration`), sequenced channel-by-channel so each\nlands with its own behavioural verification instead of one large diff no one\ncan safely review.\n\n**Amended 2026-09-15.** `internal/infrastructure/gatewayrpc.StoreClient` is the\nadapter this migration will need: it implements `messaging.SessionStore` over\nthe chat service's session-store RPCs and is proven by\n`TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired.\nProduction `archied` dials the standalone gateway for `ChatContract` only\n(`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a\n`*StoreClient`), and the Gateway's session store is PostgreSQL via\n`gateway.NewPostgresSessionStore`. The test comment that says it mirrors production\ndescribes the target, not today's tree. Kept rather than deleted because the\nmigration it serves is deferred by this very section, and re-deriving a tested\nwire adapter once that lands is pure cost.\n\n**Phase 4 Messaging Service extraction (2026-09-19, `archie-core-8cda.6.1`).**\nThe process boundary for external channels (Telegram, email, webhook) is ratified\nin [`docs/prds/messaging-service-boundary.md`](/dev/prds/messaging-service-boundary/).\nMessaging is extracted into `cmd/archie-messaging` / `internal/app/archiemessaging`,\ncalling Gateway's `messaging.ChatContract` exclusively over gRPC. Channel frontends\nhold no direct database handles, daemon state, or model runtimes.\n\n**Telegram operator surface after extraction (2026-09-19, `archie-core-8cda.6.6`).**\n`setupTelegramGateway` wired eight `telegram.Gateway` seams the daemon could\nsatisfy from its own process. Each is resolved by where the fact it needs is\nactually owned, not by where it used to be built:\n\n| Seam | Resolution |\n| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |\n| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |\n| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |\n| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |\n| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |\n| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |\n| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |\n| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported \"not configured\" before the extraction and still do. |\n\nThe Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and\n`[health]` in addition to the PRD's `[chat.*]` / `[services.gateway]` list.\n`[health]` is the daemon's health URL, which `releaseupdate.CommandInstaller`\npolls from outside to confirm an update came back up; the rest of the PRD's\nprohibition list is untouched.\n\n**Phase 4 messaging severance: what must move, and the decision the PRD does\nnot cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot\npass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the\ncheck that section specifies -- `go list -deps ./cmd/archie-messaging` links\nzero banned runtime packages -- reported four at the time (the task store was\nthen `internal/store` over `modernc.org/sqlite`; the gate now bans\n`modernc.org/sqlite`, `github.com/jackc/pgx` and\n`internal/infrastructure/postgres` in its place):\n\n| banned package | PRD category |\n| -------------------------- | -------------------------------------------------------- |\n| `modernc.org/sqlite` | State Store |\n| `internal/store` | State Store |\n| `internal/domain/workflow` | Workflow engine |\n| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |\n\nAll four arrive through one import: `internal/app/archiemessaging/run.go`\nimports `internal/app/controlplane`, whose own dependency set is exactly those\nfour. The Messaging Service uses three symbols from that package\n(`NewRPCClient`, `RuntimeChatConfig`, `ChannelSettingsKind`); the package also\ncarries the store-backed `ResourceStore` server, the `Definition` registry and\nthe workflow step vocabulary. Sever the package. Amending the gate to tolerate\n`modernc.org/sqlite` and `internal/store` is rejected: a boundary you whitelist\naround is no longer a boundary.\n\n**What moves.**\n\n- Every kind constant. They are strings with no dependency, and the client names\n them.\n- The channel-settings vocabulary and its decode: `channelSettings`,\n `telegramSettings`, `webhookChannelSettings`, `emailSettings`,\n `rateLimitSettings`, `channelDuration`, and `decodeRenamingLegacyKeys`.\n- The generic client: `Client`, `NewRPCClient`, `RuntimeConfig` with\n `runtimeConfigFrom`, `runtimeChatConfigFrom`, the other `runtime*From`\n projections, and the `resourceReader` interface.\n- The persona watch (`WatchPersonas`, `AppliedPersonas`), which needs only\n `internal/domain/agent`.\n- `executionSettingsDocument`, the document alone.\n\n**What stays, and why.**\n\n- The store-backed server: `Server`, `NewServer`, `ResourceStore`,\n `ImportConfig`, `SeedSkip`, the `Definition` registry, and every other kind's\n seed, validator and `Normalize` hook.\n- `WorkflowDefinitionsClient` and `stepRegistry`, which decode through\n `internal/domain/workflow`.\n- `WatchWorkflowExecutionSettings` and `decodeSettings`: `decodeSettings`\n returns and validates `workflow.ExecutionSettings`, so any package holding it\n links the workflow domain and therefore `internal/agentexec`. This is why the\n client cannot move as one package -- see open question 2.\n- The schedules document, whose type is `scheduling.JobSpec` in\n `internal/domain/scheduling` -- the vocabulary moved there when the legacy\n file-backed cronstore was deleted, which is also what satisfies the rule\n that a domain vocabulary package may not import infrastructure.\n- The schema derivation, which describes the documents the server advertises.\n\n**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,\n`internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the\nchannel-settings document and its decode) and the client\n(`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the\nwire sentinels and `ClientError`). A second `internal/domain/controlplane` package\nfor the vocabulary was planned and then measured out of the design: the vocabulary\nhas exactly one consumer, the client that projects it, and the store-backed side\nreads the same definitions through type aliases rather than a copy -- so a separate\ndomain package would have been a package with one consumer and a second name for\none thing. What made that safe is a measurement, not a preference:\n`internal/app/controlplane` was the ONLY direct import of the Messaging Service\nthat dragged a banned runtime (`gatewayrpc`, `staterpc`, `applystatus`, `messaging`,\n`configuration`, `readiness` and `health` were all clean), so severing that one\ndependency is sufficient, and the severance needed no third package. Promoting the\nvocabulary to a domain package stays open for the day a second consumer appears.\n\n**Settled by the implementation.** Two of the four open questions this decision\noriginally left are answered, in both cases by measuring rather than by preference:\n\n- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and\n `WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now\n _embeds_ the new one, so the daemon's validated watch is still defined once and\n the read path still has one implementation -- which is what the second package\n was for -- with one fewer package to keep in step.\n- The schedules and workflow documents stayed put, and\n `internal/domain/workflow/task` is linked deliberately: it carries the Task\n status and view vocabulary, its own dependency set holds none of the banned\n runtimes, and `cmd/archie-messaging/architecture_test.go` carries it as an\n exception checked in both directions (the same entry, for the same reason, as\n `cmd/archie-ui/architecture_test.go`).\n\n**Still open.**\n\n1. Does the server also leave `internal/app/`? `organisation.md` reserves\n `internal/app/` for wiring and composition, and a store-backed gRPC server is\n infrastructure -- but the gate does not require the move, and it would multiply\n the diff across archied's wiring and the State Store binary. Tracked as\n `archie-core-8f4n`.\n2. Does `internal/domain/workflow`'s contract/engine split happen, and when? A\n contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only\n because `agent.go` sits beside it. Independent of this severance, tracked as\n `archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.\n3. Does the vocabulary move to a domain package when a second consumer appears?\n\n**Both consumers keep compiling.** archied imports the new vocabulary for the\nkinds it names and the new client package for `RuntimeConfig` and the persona\nwatch, and keeps `internal/app/controlplane` for the server, the registry,\n`ErrVersionConflict` and the workflow-aware pieces. The State Store binary\ncontinues to call `NewServer` and `ResourceStore` unchanged. The Messaging\nService then imports only `internal/infrastructure/controlplanerpc`,\n`gatewayrpc` and `staterpc`, so `go list -deps ./cmd/archie-messaging` loses all\nfour banned packages and the gate can land green.\n\n**Channel state to the dashboard: one administrative surface, following the\nconfig-snapshot precedent (2026-09-22, `archie-core-8cda.6.8`).** The Messaging\nService now records its channels' lifecycle -- `internal/channels/status.Manager`,\none entry per composed channel, written by each channel's own report through\n`channels.Lifecycle` -- and nothing reads that across a process boundary.\n`/api/channels` answers with nothing because `webui.Server.Channels` has no\nproduction source, and POST `/api/channels/{id}/reload` answers 501 for the same\nreason. The carrier is the State Store, and the shape is the one\n`archie-core-ymut` already established for config snapshots\n(`docs/prds/state-store-contract.md`, \"the one surface whose writer is the daemon\nand whose reader is the UI process\"): a pair of administrative RPCs, deny-by-default\nunder `authorizesTaskScopedCall`, so a task-scoped grant reaches neither.\n\nWhat that decides, so the implementation need not invent it:\n\n- A channel's state is **runtime** state, not a settings document. It does not\n belong in the `ControlPlaneService` resource kinds, which are validated,\n versioned documents seeded from config; a channel that is failed is not a\n document anybody edits.\n- The reader is the UI process, which already dials the State Store and pumps its\n cursor, so the surface needs no new transport in either direction.\n- Adding the pair changes the contract's RPC count, so\n `docs/prds/state-store-contract.md`'s grouped table gains a group in the same\n change that adds the RPCs -- the table is the contract's own index, and a\n surface it does not list is a surface nobody finds.\n\n**Reload gets its own surface, with its own lifetime (decided 2026-09-22).** Reload\nruns the other way -- the UI asks the service to reload a channel -- and the two\ncandidates were a request surface the service observes and clears, or a field on\nthe status surface the service watches. It is the first. The reasoning, recorded\nbecause it would look arbitrary later:\n\n- A request queue and a status report do not share a lifetime, so they should not\n share a surface. A pending request is transient and has an outcome; a channel's\n state is durable and has a current value.\n- A \"please reload\" field on the status resource makes READING status capable of\n RETRIGGERING an action, and makes a transient request indistinguishable from\n state the moment anything polls it.\n- It would also invert the writer/reader relationship the precedent establishes:\n the service would have to clear a field on an object whose whole contract is\n that the service reports it.\n\nSo the status surface stays writer-is-service, and the request carrier is its own\nobject with its own states.\n\n`archie-core-8cda.6.9`'s component self-report is the **same shape**: a process\nreporting something about itself for the UI to read. Whether it shares this\nsurface or gets its own is a decision for `6.9`, and the one outcome to avoid is\ntwo homes for \"what a component reports about itself\".\n\n### 3. Identity data migration\n\nThe migration must define:\n\n- the durable identity schema and repository implementation;\n- bootstrap of the permanent system identity;\n- stable IdentityIDs for existing configured Agents;\n- migration from configured identity names, empty-string ownership, and bot\n usernames;\n- preservation of historical attribution;\n- identity-aware uniqueness and transport deduplication;\n- correction of container and RPC capability resolution so execution uses the\n owning identity's bindings;\n- removal of identity-string equality from access-control behaviour.\n\nExact schema and method signatures are implementation decisions. The approved\nIdentity lifecycle and attribution semantics are fixed migration constraints.\n\n### 4. Workflow migration\n\nThe current implementation must be transformed deliberately:\n\n```text\nstore.Task -\u003e WorkflowExecution\nmutable Stage -\u003e StepExecution history\nRetryCount / Attempt -\u003e Attempt records\nworkflow.Registry -\u003e versioned Workflow definitions\ncurrent stages -\u003e WorkflowStep definitions or Workflow plugins\n```\n\nThe migration must decide:\n\n- Workflow definition and version persistence;\n- the smallest accepted-work-request contract consumed from Work Intake;\n- the enforced WorkflowExecution state machine;\n- atomic state and domain-event persistence;\n- migration of existing task rows and transition history;\n- disposition of current skill, Yaegi, and stage-plugin implementations;\n- the versioned worker-handoff contract;\n- scheduler, claim, retry, crash-recovery, and waiting-human cutover.\n\nWorkflow remains a separate domain from Agent. A user or Agent may define or\ninvoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.\n\n### 5. Memory placement and storage\n\nThe four required scopes are fixed:\n\n- global shared;\n- Agent-wide;\n- user-wide;\n- Agent-user relationship.\n\nA focused review of `internal/memory`, its providers, consumers, persistence,\nand tests had these decisions:\n\n- `internal/domain/memory` versus ownership within the Agent domain — settled\n (2026-09-02, below);\n- the authoritative memory record and revision model — settled by the PRD\n (2026-09-16, below);\n- provider and infrastructure boundaries — settled by the PRD (2026-09-16,\n below);\n- retrieval and access enforcement — settled by the PRD (2026-09-16, below);\n ranked retrieval remains open (below);\n- migration of existing memory data — open: existing data is not migrated;\n- provenance representation — settled by the PRD (2026-09-16, below).\n\nConversation branches do not create another memory scope. A memory action has\nthe same scoped effect regardless of which Conversation originated it.\n\n**`internal/domain/memory` ownership — DECIDED (2026-09-02).** The typed\nengine family lives at `internal/domain/memory`\n(archie-core-1786637490069-11-e245c170), mirroring `internal/domain/curator`'s\ncontract/registrar/registry split. Not owned within the Agent domain: memory\nis consumed by more than agent turns (curators, per archie-core-1786637499636)\nand the plugin engine rule requires its own family, not a capability bolted\nonto another domain's contract.\n\n**Authoritative record and revision model for the builtin engine — DECIDED\n(2026-09-02),** scoped to unblock archie-core-1786637499480 (ship the\nfile-writing store as the default engine). This decides only the builtin\nengine's mapping onto the new `Record{ID}`/`Forget(id)` contract, not the\nmemory model in general or a future non-file engine's model:\n\n- `internal/memory/builtin.Store` is unchanged. It has no concept of a\n stable per-block ID — blocks are addressed by content substring — and nothing\n in this decision requires changing that; existing `internal/memory` tests\n keep passing unmodified, per that issue's acceptance criteria.\n- A new infrastructure adapter (`internal/infrastructure/memory`, per\n `organisation.md`'s \"infrastructure implements domain contracts\" rule — not\n under `internal/domain/memory`, which stays contract-only) wraps one\n `builtin.Store` per identity.\n- **Identity → directory:** `hex(sha256(identity))`, not the identity string\n itself. Closes the path-traversal question without an allowlist regex, and\n sidesteps collisions from identities that differ only in characters a\n filesystem treats as equivalent.\n- **Record ID:** assigned once at `Write`, independent of content, so a later\n edit elsewhere in the file can never orphan a `Forget`. Realised as a\n leading marker line (`\u003c!--mem:\u003culid\u003e--\u003e`) on the block `builtin.Store.Add`\n writes; `Query`/`List` strip it back out of `Record.Content` before\n returning, and `Forget(id)` locates the block by that unique marker via the\n store's existing substring-based `Remove`. The marker is a pragmatic,\n reversible choice — plain-text records stay human-readable and\n human-editable, at the cost of one marker line an operator editing the file\n by hand should leave alone. Revisit if/when provenance representation\n (still open, below) settles on something richer.\n- **Kind → section:** `Observation.Kind` (default `\"general\"` when empty) is\n the section name, reusing `builtin.ValidateSectionName` — so an\n invalid `Kind` fails `Write` with the same validation error `memory_edit`\n already returns for an invalid section today, not a new error shape.\n\n**Memory engine: scopes, CRUD with retained revisions, and store placement —\nDECIDED (2026-09-16).** Supersedes the 2026-09-02 \"Authoritative record and\nrevision model for the builtin engine\" entry above, whose `\u003c!--mem:\u003culid\u003e--\u003e`\nlive marker cannot carry provenance. Authority:\n[`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\n(Approved); the contract is `internal/domain/memory/contract.go`. This register\nsupersedes; it does not erase.\n\n- **Four typed scopes, caller-named.** `internal/domain/memory` is addressed by\n `Scope{Kind, Agent, User}` over `global`, `agent`, `user` and `agent-user`,\n with `Validate` rejecting a component present where it is not required. A\n caller names the read and write sets (`Subject.Scopes()` /\n `WritableScopes()`; global is never model-writable) and the engine applies no\n policy of its own: **access control is naming a scope, and nothing else.** An\n engine that enforced policy would need to know about channels, sessions and\n bindings, and every backend would reimplement it. `Scope.Key()` length-prefixes\n each component, so two scopes can never share a key even when an opaque\n channel-native id embeds the separator.\n- **The caller resolves identity; the engine never does.** Resolution happens in\n the gateway turn path, where the native sender id and the session are both in\n hand, and is supplied per channel by the composition. A webhook's sender id is\n a route path, not a person, and treating it as one would give a URL an\n identity. An absent user id yields global and agent scopes only: \"show none of\n it\", never a wider fallback.\n- **CRUD supersedes, never overwrites.** `Store` is `Create`/`Get`/`Query`/\n `List`/`Update`/`Forget`/`Revisions` over the four scopes. `Update` appends the\n superseded state to the scope's `HISTORY.md` before replacing the live block;\n `Update.Expected` names the revision being replaced and returns\n `ErrStaleRevision` on mismatch, making a lost update between two processes\n sharing one scope file detectable. `Forget` records a deleted revision before\n removing the live block, so a record's provenance outlives its content; `Get`\n and `Forget` take a scope, because an id alone does not locate one.\n- **Provenance representation.** The live marker becomes JSON, since a\n `\u003c!--mem:\u003culid\u003e--\u003e` line cannot carry provenance, and `Record` retains the\n provenance `agent-system.md` requires — scope, author, originating user,\n source, and revision history. `Metadata` is dropped: it never round-tripped.\n- **Store and scanner placement.** The markdown store relocates to\n `internal/infrastructure/memory/builtin`, its correct home under\n `organisation.md`'s \"a package owns its on-disk format end-to-end\". The content\n scanner moves into `internal/domain/memory` and is applied in `Create` and\n `Update` — the single choke point every producer crosses, so curator-extracted\n content is covered too.\n\n**Open in this section.** Ranked retrieval is deferred: `Query.Text` stays in\nthe contract, unused by the prompt path. Existing memory data is not migrated:\n`\u003cworkDir\u003e/memory` and `\u003cworkDir\u003e/memory-engine` are left on disk, unreferenced.\nThe PRD leaves these undetermined and they remain open here: group-chat\nextraction, where the curator fails closed on mixed-sender sessions; two\nprocesses (`archied` and `archie-gateway`) holding one scope file, where\n`Update.Expected` detects but does not prevent a lost block; unbounded\n`HISTORY.md` with no compaction policy; whether the per-scope size bound is\nright; and whether the dashboard should carry a user identity.\n\n### 6. Runtime and process boundaries — DECIDED\n\n`archied` is the native resident orchestration and interactive-chat process.\nEvery autonomous repository workflow crosses one full-task core-NATS handoff\ninto a task-scoped `archie-agent` container. Embedded versus external NATS\nchanges broker deployment only; it never selects an executor. The former host\nin-process runner, per-stage NATS protocol, and subprocess runner are removed.\n\nForge, store, and worktree authority remains in `archied` and is exposed to the\ntask container through scoped RPC services. The worker runs the workflow and\nits worker-local ai-sdk loop; it does not receive forge credentials or direct\nstore access. See `docs/prds/embedded-nats.md`.\n\n**UI Service boundary — RATIFIED (2026-09-07).** Phase 3 has a focused\nauthority record in [`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\nThe UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and\nits own endpoint/credential/readiness settings. It consumes Gateway and State\nStore contracts and does not receive `config.Holder`, daemon pointers, SQL or\nstore implementations, workflow registries, forge/channel/model runtimes, or\nresolved secrets. The current `internal/webui` implementation remains inside\n`archied` until the ratified migration gates prove route parity, adapter\nselection, failure/readiness behaviour, and deletion of the shared-holder and\ndirect-access paths. The extraction cutover removes the in-process UI\nlistener in the same change; there is no dual-live UI authority.\n\n**Dashboard live event delivery — DECIDED (2026-09-09, `archie-core-za9f`).**\nThe extracted UI receives live activity by polling the State Store's existing\n`EventsSince` cursor, not by a new push-subscription RPC. No proto change, no\ncontract amendment beyond this record.\n\nThe UI process runs one event pump. It primes its watermark by paging\n`EventsSince` to the end at startup without delivering, then polls\n`EventsSince(watermark, limit)` on an interval and hands each new event to\n`webui.Server.Broadcast`, exactly where `internal/app/archied/main.go`'s\n`persistAndBroadcastEvents` hands events to it today. One pump serves every\nconnected browser, so cost is one indexed query per interval regardless of\nviewer count, and `Broadcast` is a no-op when nobody is watching.\n\nThree properties make the cursor sufficient, and a push hub unnecessary:\n\n- **The cursor cannot skip.** `internal/infrastructure/postgres` takes an\n advisory event-append lock around each insert (`TestEventInsertsCommitInIDOrder`),\n so a row's `id` is assigned in commit order. There is no window in which a lower id becomes visible after a\n higher one, which is the failure mode that normally rules out polling an\n autoincrement cursor. SSE catch-up already depends on this same property.\n- **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each\n broadcast event as a signal to fill the persisted gap ahead of it via\n `catchUp`, then delivers the event only if catch-up did not already cover\n it, deduplicating on the `since` watermark. Substituting a poller for the\n in-process bus therefore changes no SSE semantics, and needs no change to\n `internal/webui/sse.go`. It also means a broadcast dropped to a stalled\n client self-heals on the next one.\n- **The table is the only complete fan-out point.** Events reach the store\n through several paths that never touch the daemon's bus, including the\n audit event `store.ArchiveTask` writes inside its transaction\n (`internal/infrastructure/postgres/store.go`) and the binding-dispatch failure\n `internal/daemon/daemon.go` inserts directly. A push hub would have to be\n hooked at every write site and at post-commit, and would silently miss any\n site added later that forgets to notify. Reading the table misses nothing.\n\nThe cost is one poll interval of latency on the activity feed, default 1s and\noperator-tunable. That is accepted: the feed reports task lifecycle history,\nand an operator action already gets its own synchronous HTTP response.\n\nThis resolves the `/events` row of the route-owner inventory in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). `/api/logs` and\n`/api/logs/stream` are not resolved by it, they read the daemon's in-process\ndiagnostic feed and remain host-local (see `archie-core-8cda.5.4`).\n\nRevisit only if sub-second feed latency becomes a requirement, or if a second\nconsumer needs the same stream, at which point the fan-out belongs in the State\nStore process behind a `SubscribeEvents` RPC and this record is superseded.\n\n**Dashboard configuration page — DECIDED (2026-09-09, `archie-core-ymut`).**\nThe configuration page becomes read-only in the UI process for Phase 3. Reads\ncross the boundary as a published snapshot; writes are descoped, not\ncontracted. This amends the ratified boundary, which assumed a single admin\ncontract carrying both.\n\n**Reads.** `webui.ConfigView` is already the whole answer. It is a UI-owned,\nsecret-free value projection built in `handleConfig`: `ProviderView` carries\nthe API key's environment variable name and a `Configured` boolean, never a\nvalue, and `RepoView` is repository metadata only. It is already the exact\nshape the browser receives. So the daemon publishes that projection, plus\nprovenance, reload status and the overridden-key list, as a snapshot the UI\nreads; nothing new has to be designed, only moved. Two State Store RPCs carry\nit, a `PutConfigSnapshot` restricted to the administrative token and a\n`GetConfigSnapshot` the UI calls. The daemon republishes on boot and after\neach successful reload, which is precisely when the projection changes.\n\nThe State Store is the right holder because a published configuration snapshot\nis shared state, it is already dialled by the UI, and it costs no new listener,\nport, token or interceptor. The alternative, a config admin service on\n`archied`, would make the daemon a gRPC server for the first time. Today it is\npurely a client of Gateway and State Store; `grpc.NewServer` appears only in\n`RunGateway` and `RunStateStore`, which are the standalone binaries' entry\npoints, not the daemon's.\n\n**Writes.** `PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}` answer 503 in the UI process, and the\nSPA hides those controls rather than offering a button that fails. Editing is\n`config.toml` plus reload, which is already the only path for every setting\noutside the runtime-tunable allowlist.\n\nThis is a deliberate feature reduction and worth naming as one. The write path\nis not hard because of the transport; it is hard because the policy is\ndaemon-local and stays that way: `installUpdateConfigHandler` denies\nnon-runtime-tunable keys, applies a dotted overlay to a clone of the published\nconfig, validates the materialised result, writes overlay rows, and rebuilds\nprovenance. Contracting that means either moving the policy, which the\nboundary forbids, or exposing it verbatim as remote procedure calls, which\nbuilds a Configuration Service inside a migration bead. Neither is work this\nphase should be doing to keep one page's buttons alive.\n\nRevisit when dashboard configuration editing is picked up as a feature in its\nown right (`archie-core-1786637498420-327`, still open). At that point it gets\nan admin contract designed as a feature, and the Configuration Service this\ndocument already anticipates is its natural owner. Until then the UI renders\nconfiguration and does not write it, which is what the boundary always said\nabout ownership even when it assumed a wider contract.\n\nAmended 2026-09-11. This descope is a deferral, not a decision that the\ndashboard should be read-only. Name it that way in review: the daemon-side\npolicy was built and tested, then deleted by the cutover (`e037b95` removed\n`internal/app/archied/config_update.go` and its tests), so reviving it is\nrecoverable work, not a rewrite. `archie-core-j28m` carries the remaining\nquestion -- which process serves the policy and what transport carries the\nwrite -- and blocks the feature bead. The handlers, their error sentinels and\nthe `UpdateConfig`/`ResetConfig`/`UpdateRepoField` seams on `webui.Server` are\nkept deliberately for it; `ConfigView.Editable` follows whichever process holds\n`UpdateConfig`, so wiring that one field makes the page editable\n(`archie-core-ml30`).\n\nImplementation belongs to `archie-core-8cda.5.4`, the cutover that removes the\ndaemon's own dashboard. Nothing here is built yet.\n\n**Superseded 2026-09-21 by the runtime control plane.** The open question this\ndescope left -- which process serves the policy and what transport carries the\nwrite -- was answered by `docs/prds/runtime-control-plane.md`: neither a daemon\nadmin service nor a revival of the daemon-local policy. `ControlPlaneService` on\nthe State Store's existing gRPC server owns every database-backed setting, and\neach feature validates its own resource, so there is no daemon-local policy left\nto contract. `archie-core-j28m` is closed.\n\nConsequently the three write seams described above no longer exist.\n`PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}`, the `UpdateConfig`/`ResetConfig`/\n`UpdateRepoField` fields on `webui.Server`, and `ConfigView.Editable` were\ndeleted in `31622ec5` along with the runtime overlay store they wrote to.\n`GET /api/config` remains a read of the published projection, as this decision\nalways intended.\n\n### 7. Shared mechanics\n\nThe following cross-domain mechanics require exact contracts before dependent\npackages migrate:\n\n- event-bus delivery and failure semantics;\n- policy evaluation API, composition, and precedence;\n- configuration candidate preparation, health validation, atomic promotion,\n observation, and rollback;\n- service-specific health, bounded remediation, isolation, and escalation;\n- changelog association and grouping.\n\nThese shared mechanisms do not acquire ownership of domain meaning. Domains\ncontinue to own their commands, events, policies, settings, and consequences.\n\nThe Go documentation generator, its output placement, and drift checking are\ndefined in `generated-documentation.md`. The external Astro website consumes\nthe committed documentation and release JSON artifacts and serves them under\n`offloaded.dev/docs/`. This repository owns the source and artifact checks; the\nwebsite repository owns rendering and deployment. The generators and\nArchie's normalised documentation model remain migration work rather than open\nproduct architecture.\n\n**Amended 2026-09-15.** `internal/infrastructure/servicediscovery/nats`\nimplements the `servicediscovery.ServiceRegistry` contract (Connect, Register,\nResolve, Watch) over NATS KV and is fully tested, but no production code\nconstructs it and no config surface exposes it. This is a deliberate deferral,\nnot an oversight: service-to-service addressing belongs to the runtime and\nprocess boundary work in section 6, which currently pins container addressing\nby injecting the daemon's startup NATS URL rather than resolving through a\nregistry. The scaffold is kept for that work; re-derive it only if the\naddressing model changes.\n\n### 8. Cutover sequence\n\nThe final migration plan must order:\n\n- compatibility adapters;\n- schema migrations and data backfills;\n- any required dual-read or transitional paths;\n- domain-by-domain package replacement;\n- production wiring changes;\n- legacy package removal;\n- architecture tests preventing dependency regression;\n- focused, integration, race, and full quality gates.\n\nEach legacy package requires objective removal criteria. No compatibility path\nmay become an indefinite second implementation.\n\n## Completion criteria\n\nMigration design is complete when:\n\n- every current package has one approved owner and destination;\n- every mutable record has one authoritative owner and migration path;\n- all external and cross-process contracts have versioned owners;\n- existing behaviour and data have explicit parity requirements;\n- process boundaries have evidence-backed justification;\n- the cutover order preserves a working application;\n- legacy deletion criteria and deterministic architecture tests are defined;\n- no unresolved decision requires an implementer to invent domain semantics.\n\nExact Go APIs, SQL statements, and mechanical refactoring steps MAY be finalized\nduring implementation when they do not change these semantics.\n\n## Recorded migration position (2026-07-29)\n\nRecovered 2026-08-09 from the pre-migration issue tracker. This section records\ndecisions the maintainer approved that the repository did not otherwise capture.\n\n**Completed:** `internal/infrastructure/eventbus/nats` (rebuilt, not relocated);\n`internal/infrastructure/configuration` (loading moved out of `internal/config`,\nwhich is now types-only and does no I/O); `internal/eventbus` (broker-neutral\ncontract); `internal/domain/workintake` (the first `internal/domain/` package,\nowning `TaskEnvelope`, the routing `Kind`, the label vocabulary, and task\nsubjects).\n\n**DECISION — private input DTO deferred (approved).**\n`configuration.Document.Config` is still `internal/config.Config` rather than the\nprivate per-domain input DTO this document mandates. Building an ~800-line\nparallel type tree while every consumer still reads `config.Config` would mean\ntwo shapes kept in sync by hand, with no consumer for the new one. It is named as\na field so the compromise is visible at each use site, with the deletion\ncondition recorded in that package's `doc.go`. Do this **with** the\n`internal/config` dissolution, not ahead of it.\n\n**Agreed next: `internal/app/{archied,agentworker}`.** `run()` in\n`cmd/archied/main.go` is ~460 lines, against `organisation.md`'s rule that\n`cmd/*` must not contain substantive wiring or act as a service locator. It is\nalso the last non-infrastructure holder of the NATS SDK, and it is where the\nconfig DTO translation will land, so it unblocks the dissolution above.\n\n**Method constraint.** Do not write a separate recorded package-review document\nper area when the decisions are already dictated by\n`dependencies-and-contracts.md`. That is the ceremony pattern this project\ndeliberately avoids.\n\n## OPEN — `[chat.*]` config section naming\n\n`configuration.md:160` already states the position: `ChatConfig` holds \"separate\nchannel instance settings... there is no chat-wide settings owner\". The config\nsection name has not followed, so a settings block named for a product surface\nowns what the architecture calls channel state.\n\nTwo candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The\nsecond reads as a domain path, and no config section in this repo is currently\nnamed after a domain package, so adopting it sets a precedent for every other\nsection rather than fixing one name.\n\nBlocked on a maintainer decision, not on evidence. This is a rename with an\noperator-visible TOML break, so it should land with the `internal/config`\ndissolution recorded above rather than on its own.\n" + "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\nauthentication, UI response projection, configuration reads and mutations,\ntask/control APIs, and direct adapters to State Store, channel, event/log,\nmemory, curator, workflow, forge, and Gateway runtime values. The target owner\nis a standalone UI application process; `internal/webui` remains its HTTP\ntransport adapter, while Gateway, State Store, configuration, Work Intake,\nMessaging, and other capability owners expose the contracts behind those\nroutes. The migration preserves retained route schemas, auth/CSRF behaviour,\ntask/capture/mapping/binding/session continuity, SSE replay semantics, and\ncommitted generated SPA assets. Prerequisites are the ratified UI boundary,\nroute-owner inventory, narrow remote adapters, configuration/auth/readiness\ncontracts, and process/conformance tests. Remove the shared live\n`config.Holder`, direct event/log bus, daemon stopper, forge client, channel\nmanager, capability registries, composite store access, and in-process UI\nlistener only after the focused criteria in\n[`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/) pass in\nproduction composition. The old construction and listener are deleted in the\nsame cutover change; no second UI authority remains.\n\n### 2. Session and Messaging migration\n\nThe existing session implementation is the migration baseline. The migration must\ndecide:\n\n- which session and message components are retained or adapted;\n- how Agent, user, channel, Conversation, and branch ownership are added;\n- how Archie's parallel gateway session implementation is replaced;\n- how canonical Messages become immutable persisted records;\n- how existing sessions and messages are migrated;\n- how outbound delivery, retry, acknowledgement, deduplication, and failure\n semantics are represented;\n- how current Telegram, email, webhook, forge, and Jira integrations migrate to\n Messaging infrastructure adapters.\n\nThe following are already decided and MUST NOT be reopened without contradictory\nimplementation evidence:\n\n- the composite Conversation identity;\n- immutable MessageIDs;\n- typed tool-call and tool-result messages;\n- exact branch lineage through ParentConversationID and ForkMessageID;\n- parent and child transcript isolation;\n- normal scoped-memory behaviour regardless of the originating Conversation;\n- Messaging and Work Intake ownership.\n\n**Decision (2026-08-31), resolving the open questions above:**\n\n`internal/gateway/` is the \"parallel gateway session implementation\" this\nsection names. It is retained as-is for now — a big-bang rewrite of live\nsession/compression/approval/branch logic across Telegram, web UI, email, and\nwebhook channels in one change is exactly the \"convoluted to satisfy edge\ncases\" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would\nrisk silent behavioural regressions in the one path every user-facing message\ntravels through.\n\nInstead, `internal/domain/messaging/` is materialised now with the pieces\nthat are already decided and don't require touching gateway: the canonical\n`Message` and `Conversation` types (composite Conversation identity, immutable\n`MessageID`, typed tool-call/tool-result message variants, branch lineage via\n`ParentConversationID`/`ForkMessageID`). These are pure domain types with no\ngateway dependency — a new package, not a rewrite of an existing one.\n\nMigrating `internal/gateway/`'s session, compression, approval, and branch\nlogic onto these types is real, cross-channel-risk work and is **not** done in\nthis pass. It is tracked as separate, appropriately-scoped bd issues (see\n`bd list --label messaging-migration`), sequenced channel-by-channel so each\nlands with its own behavioural verification instead of one large diff no one\ncan safely review.\n\n**Amended 2026-09-15.** `internal/infrastructure/gatewayrpc.StoreClient` is the\nadapter this migration will need: it implements `messaging.SessionStore` over\nthe chat service's session-store RPCs and is proven by\n`TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired.\nProduction `archied` dials the standalone gateway for `ChatContract` only\n(`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a\n`*StoreClient`), and the Gateway's session store is PostgreSQL via\n`gateway.NewPostgresSessionStore`. The test comment that says it mirrors production\ndescribes the target, not today's tree. Kept rather than deleted because the\nmigration it serves is deferred by this very section, and re-deriving a tested\nwire adapter once that lands is pure cost.\n\n**Phase 4 Messaging Service extraction (2026-09-19, `archie-core-8cda.6.1`).**\nThe process boundary for external channels (Telegram, email, webhook) is ratified\nin [`docs/prds/messaging-service-boundary.md`](/dev/prds/messaging-service-boundary/).\nMessaging is extracted into `cmd/archie-messaging` / `internal/app/archiemessaging`,\ncalling Gateway's `messaging.ChatContract` exclusively over gRPC. Channel frontends\nhold no direct database handles, daemon state, or model runtimes.\n\n**Telegram operator surface after extraction (2026-09-19, `archie-core-8cda.6.6`).**\n`setupTelegramGateway` wired eight `telegram.Gateway` seams the daemon could\nsatisfy from its own process. Each is resolved by where the fact it needs is\nactually owned, not by where it used to be built:\n\n| Seam | Resolution |\n| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |\n| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |\n| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |\n| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |\n| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |\n| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |\n| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |\n| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported \"not configured\" before the extraction and still do. |\n\nThe Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and\n`[health]` in addition to the PRD's `[chat.*]` / `[services.gateway]` list.\n`[health]` is the daemon's health URL, which `releaseupdate.CommandInstaller`\npolls from outside to confirm an update came back up; the rest of the PRD's\nprohibition list is untouched.\n\n**Phase 4 messaging severance: what must move, and the decision the PRD does\nnot cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot\npass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the\ncheck that section specifies -- `go list -deps ./cmd/archie-messaging` links\nzero banned runtime packages -- reported four at the time (the task store was\nthen `internal/store` over `modernc.org/sqlite`; the gate now bans\n`modernc.org/sqlite`, `github.com/jackc/pgx` and\n`internal/infrastructure/postgres` in its place):\n\n| banned package | PRD category |\n| -------------------------- | -------------------------------------------------------- |\n| `modernc.org/sqlite` | State Store |\n| `internal/store` | State Store |\n| `internal/domain/workflow` | Workflow engine |\n| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |\n\nAll four arrive through one import: `internal/app/archiemessaging/run.go`\nimports `internal/app/controlplane`, whose own dependency set is exactly those\nfour. The Messaging Service uses three symbols from that package\n(`NewRPCClient`, `RuntimeChatConfig`, `ChannelSettingsKind`); the package also\ncarries the store-backed `ResourceStore` server, the `Definition` registry and\nthe workflow step vocabulary. Sever the package. Amending the gate to tolerate\n`modernc.org/sqlite` and `internal/store` is rejected: a boundary you whitelist\naround is no longer a boundary.\n\n**What moves.**\n\n- Every kind constant. They are strings with no dependency, and the client names\n them.\n- The channel-settings vocabulary and its decode: `channelSettings`,\n `telegramSettings`, `webhookChannelSettings`, `emailSettings`,\n `rateLimitSettings`, `channelDuration`, and `decodeRenamingLegacyKeys`.\n- The generic client: `Client`, `NewRPCClient`, `RuntimeConfig` with\n `runtimeConfigFrom`, `runtimeChatConfigFrom`, the other `runtime*From`\n projections, and the `resourceReader` interface.\n- The persona watch (`WatchPersonas`, `AppliedPersonas`), which needs only\n `internal/domain/agent`.\n- `executionSettingsDocument`, the document alone.\n\n**What stays, and why.**\n\n- The store-backed server: `Server`, `NewServer`, `ResourceStore`,\n `ImportConfig`, `SeedSkip`, the `Definition` registry, and every other kind's\n seed, validator and `Normalize` hook.\n- `WorkflowDefinitionsClient` and `stepRegistry`, which decode through\n `internal/domain/workflow`.\n- `WatchWorkflowExecutionSettings` and `decodeSettings`: `decodeSettings`\n returns and validates `workflow.ExecutionSettings`, so any package holding it\n links the workflow domain and therefore `internal/agentexec`. This is why the\n client cannot move as one package -- see open question 2.\n- The schedules document, whose type is `scheduling.JobSpec` in\n `internal/domain/scheduling` -- the vocabulary moved there when the legacy\n file-backed cronstore was deleted, which is also what satisfies the rule\n that a domain vocabulary package may not import infrastructure.\n- The schema derivation, which describes the documents the server advertises.\n\n**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,\n`internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the\nchannel-settings document and its decode) and the client\n(`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the\nwire sentinels and `ClientError`). A second `internal/domain/controlplane` package\nfor the vocabulary was planned and then measured out of the design: the vocabulary\nhas exactly one consumer, the client that projects it, and the store-backed side\nreads the same definitions through type aliases rather than a copy -- so a separate\ndomain package would have been a package with one consumer and a second name for\none thing. What made that safe is a measurement, not a preference:\n`internal/app/controlplane` was the ONLY direct import of the Messaging Service\nthat dragged a banned runtime (`gatewayrpc`, `staterpc`, `applystatus`, `messaging`,\n`configuration`, `readiness` and `health` were all clean), so severing that one\ndependency is sufficient, and the severance needed no third package. Promoting the\nvocabulary to a domain package stays open for the day a second consumer appears.\n\n**Settled by the implementation.** Two of the four open questions this decision\noriginally left are answered, in both cases by measuring rather than by preference:\n\n- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and\n `WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now\n _embeds_ the new one, so the daemon's validated watch is still defined once and\n the read path still has one implementation -- which is what the second package\n was for -- with one fewer package to keep in step.\n- The schedules and workflow documents stayed put, and\n `internal/domain/workflow/task` is linked deliberately: it carries the Task\n status and view vocabulary, its own dependency set holds none of the banned\n runtimes, and `cmd/archie-messaging/architecture_test.go` carries it as an\n exception checked in both directions (the same entry, for the same reason, as\n `cmd/archie-ui/architecture_test.go`).\n\n**Still open.**\n\n1. Does the server also leave `internal/app/`? `organisation.md` reserves\n `internal/app/` for wiring and composition, and a store-backed gRPC server is\n infrastructure -- but the gate does not require the move, and it would multiply\n the diff across archied's wiring and the State Store binary. Tracked as\n `archie-core-8f4n`.\n2. Does `internal/domain/workflow`'s contract/engine split happen, and when? A\n contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only\n because `agent.go` sits beside it. Independent of this severance, tracked as\n `archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.\n3. Does the vocabulary move to a domain package when a second consumer appears?\n\n**Both consumers keep compiling.** archied imports the new vocabulary for the\nkinds it names and the new client package for `RuntimeConfig` and the persona\nwatch, and keeps `internal/app/controlplane` for the server, the registry,\n`ErrVersionConflict` and the workflow-aware pieces. The State Store binary\ncontinues to call `NewServer` and `ResourceStore` unchanged. The Messaging\nService then imports only `internal/infrastructure/controlplanerpc`,\n`gatewayrpc` and `staterpc`, so `go list -deps ./cmd/archie-messaging` loses all\nfour banned packages and the gate can land green.\n\n**Channel state to the dashboard: one administrative surface, following the\nconfig-snapshot precedent (2026-09-22, `archie-core-8cda.6.8`).** The Messaging\nService now records its channels' lifecycle -- `internal/channels/status.Manager`,\none entry per composed channel, written by each channel's own report through\n`channels.Lifecycle` -- and nothing reads that across a process boundary.\n`/api/channels` answers with nothing because `webui.Server.Channels` has no\nproduction source, and POST `/api/channels/{id}/reload` answers 501 for the same\nreason. The carrier is the State Store, and the shape is the one\n`archie-core-ymut` already established for config snapshots\n(`docs/prds/state-store-contract.md`, \"the one surface whose writer is the daemon\nand whose reader is the UI process\"): a pair of administrative RPCs, deny-by-default\nunder `authorizesTaskScopedCall`, so a task-scoped grant reaches neither.\n\nWhat that decides, so the implementation need not invent it:\n\n- A channel's state is **runtime** state, not a settings document. It does not\n belong in the `ControlPlaneService` resource kinds, which are validated,\n versioned documents seeded from config; a channel that is failed is not a\n document anybody edits.\n- The reader is the UI process, which already dials the State Store and pumps its\n cursor, so the surface needs no new transport in either direction.\n- Adding the pair changes the contract's RPC count, so\n `docs/prds/state-store-contract.md`'s grouped table gains a group in the same\n change that adds the RPCs -- the table is the contract's own index, and a\n surface it does not list is a surface nobody finds.\n\n**Reload gets its own surface, with its own lifetime (decided 2026-09-22).** Reload\nruns the other way -- the UI asks the service to reload a channel -- and the two\ncandidates were a request surface the service observes and clears, or a field on\nthe status surface the service watches. It is the first. The reasoning, recorded\nbecause it would look arbitrary later:\n\n- A request queue and a status report do not share a lifetime, so they should not\n share a surface. A pending request is transient and has an outcome; a channel's\n state is durable and has a current value.\n- A \"please reload\" field on the status resource makes READING status capable of\n RETRIGGERING an action, and makes a transient request indistinguishable from\n state the moment anything polls it.\n- It would also invert the writer/reader relationship the precedent establishes:\n the service would have to clear a field on an object whose whole contract is\n that the service reports it.\n\nSo the status surface stays writer-is-service, and the request carrier is its own\nobject with its own states.\n\n`archie-core-8cda.6.9`'s component self-report is the **same shape**: a process\nreporting something about itself for the UI to read. Whether it shares this\nsurface or gets its own is a decision for `6.9`, and the one outcome to avoid is\ntwo homes for \"what a component reports about itself\".\n\n### 3. Identity data migration\n\nThe migration must define:\n\n- the durable identity schema and repository implementation;\n- bootstrap of the permanent system identity;\n- stable IdentityIDs for existing configured Agents;\n- migration from configured identity names, empty-string ownership, and bot\n usernames;\n- preservation of historical attribution;\n- identity-aware uniqueness and transport deduplication;\n- correction of container and RPC capability resolution so execution uses the\n owning identity's bindings;\n- removal of identity-string equality from access-control behaviour.\n\nExact schema and method signatures are implementation decisions. The approved\nIdentity lifecycle and attribution semantics are fixed migration constraints.\n\n### 4. Workflow migration\n\nThe current implementation must be transformed deliberately:\n\n```text\nstore.Task -\u003e WorkflowExecution\nmutable Stage -\u003e StepExecution history\nRetryCount / Attempt -\u003e Attempt records\nworkflow.Registry -\u003e versioned Workflow definitions\ncurrent stages -\u003e WorkflowStep definitions or Workflow plugins\n```\n\nThe migration must decide:\n\n- Workflow definition and version persistence;\n- the smallest accepted-work-request contract consumed from Work Intake;\n- the enforced WorkflowExecution state machine (proposed in\n `docs/prds/execution-tree-state-machine.md`);\n- atomic state and domain-event persistence;\n- migration of existing task rows and transition history;\n- disposition of current skill, Yaegi, and stage-plugin implementations;\n- the versioned worker-handoff contract;\n- scheduler, claim, retry, crash-recovery, and waiting-human cutover.\n\nWorkflow remains a separate domain from Agent. A user or Agent may define or\ninvoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.\n\n### 5. Memory placement and storage\n\nThe four required scopes are fixed:\n\n- global shared;\n- Agent-wide;\n- user-wide;\n- Agent-user relationship.\n\nA focused review of `internal/memory`, its providers, consumers, persistence,\nand tests had these decisions:\n\n- `internal/domain/memory` versus ownership within the Agent domain — settled\n (2026-09-02, below);\n- the authoritative memory record and revision model — settled by the PRD\n (2026-09-16, below);\n- provider and infrastructure boundaries — settled by the PRD (2026-09-16,\n below);\n- retrieval and access enforcement — settled by the PRD (2026-09-16, below);\n ranked retrieval remains open (below);\n- migration of existing memory data — open: existing data is not migrated;\n- provenance representation — settled by the PRD (2026-09-16, below).\n\nConversation branches do not create another memory scope. A memory action has\nthe same scoped effect regardless of which Conversation originated it.\n\n**`internal/domain/memory` ownership — DECIDED (2026-09-02).** The typed\nengine family lives at `internal/domain/memory`\n(archie-core-1786637490069-11-e245c170), mirroring `internal/domain/curator`'s\ncontract/registrar/registry split. Not owned within the Agent domain: memory\nis consumed by more than agent turns (curators, per archie-core-1786637499636)\nand the plugin engine rule requires its own family, not a capability bolted\nonto another domain's contract.\n\n**Authoritative record and revision model for the builtin engine — DECIDED\n(2026-09-02),** scoped to unblock archie-core-1786637499480 (ship the\nfile-writing store as the default engine). This decides only the builtin\nengine's mapping onto the new `Record{ID}`/`Forget(id)` contract, not the\nmemory model in general or a future non-file engine's model:\n\n- `internal/memory/builtin.Store` is unchanged. It has no concept of a\n stable per-block ID — blocks are addressed by content substring — and nothing\n in this decision requires changing that; existing `internal/memory` tests\n keep passing unmodified, per that issue's acceptance criteria.\n- A new infrastructure adapter (`internal/infrastructure/memory`, per\n `organisation.md`'s \"infrastructure implements domain contracts\" rule — not\n under `internal/domain/memory`, which stays contract-only) wraps one\n `builtin.Store` per identity.\n- **Identity → directory:** `hex(sha256(identity))`, not the identity string\n itself. Closes the path-traversal question without an allowlist regex, and\n sidesteps collisions from identities that differ only in characters a\n filesystem treats as equivalent.\n- **Record ID:** assigned once at `Write`, independent of content, so a later\n edit elsewhere in the file can never orphan a `Forget`. Realised as a\n leading marker line (`\u003c!--mem:\u003culid\u003e--\u003e`) on the block `builtin.Store.Add`\n writes; `Query`/`List` strip it back out of `Record.Content` before\n returning, and `Forget(id)` locates the block by that unique marker via the\n store's existing substring-based `Remove`. The marker is a pragmatic,\n reversible choice — plain-text records stay human-readable and\n human-editable, at the cost of one marker line an operator editing the file\n by hand should leave alone. Revisit if/when provenance representation\n (still open, below) settles on something richer.\n- **Kind → section:** `Observation.Kind` (default `\"general\"` when empty) is\n the section name, reusing `builtin.ValidateSectionName` — so an\n invalid `Kind` fails `Write` with the same validation error `memory_edit`\n already returns for an invalid section today, not a new error shape.\n\n**Memory engine: scopes, CRUD with retained revisions, and store placement —\nDECIDED (2026-09-16).** Supersedes the 2026-09-02 \"Authoritative record and\nrevision model for the builtin engine\" entry above, whose `\u003c!--mem:\u003culid\u003e--\u003e`\nlive marker cannot carry provenance. Authority:\n[`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\n(Approved); the contract is `internal/domain/memory/contract.go`. This register\nsupersedes; it does not erase.\n\n- **Four typed scopes, caller-named.** `internal/domain/memory` is addressed by\n `Scope{Kind, Agent, User}` over `global`, `agent`, `user` and `agent-user`,\n with `Validate` rejecting a component present where it is not required. A\n caller names the read and write sets (`Subject.Scopes()` /\n `WritableScopes()`; global is never model-writable) and the engine applies no\n policy of its own: **access control is naming a scope, and nothing else.** An\n engine that enforced policy would need to know about channels, sessions and\n bindings, and every backend would reimplement it. `Scope.Key()` length-prefixes\n each component, so two scopes can never share a key even when an opaque\n channel-native id embeds the separator.\n- **The caller resolves identity; the engine never does.** Resolution happens in\n the gateway turn path, where the native sender id and the session are both in\n hand, and is supplied per channel by the composition. A webhook's sender id is\n a route path, not a person, and treating it as one would give a URL an\n identity. An absent user id yields global and agent scopes only: \"show none of\n it\", never a wider fallback.\n- **CRUD supersedes, never overwrites.** `Store` is `Create`/`Get`/`Query`/\n `List`/`Update`/`Forget`/`Revisions` over the four scopes. `Update` appends the\n superseded state to the scope's `HISTORY.md` before replacing the live block;\n `Update.Expected` names the revision being replaced and returns\n `ErrStaleRevision` on mismatch, making a lost update between two processes\n sharing one scope file detectable. `Forget` records a deleted revision before\n removing the live block, so a record's provenance outlives its content; `Get`\n and `Forget` take a scope, because an id alone does not locate one.\n- **Provenance representation.** The live marker becomes JSON, since a\n `\u003c!--mem:\u003culid\u003e--\u003e` line cannot carry provenance, and `Record` retains the\n provenance `agent-system.md` requires — scope, author, originating user,\n source, and revision history. `Metadata` is dropped: it never round-tripped.\n- **Store and scanner placement.** The markdown store relocates to\n `internal/infrastructure/memory/builtin`, its correct home under\n `organisation.md`'s \"a package owns its on-disk format end-to-end\". The content\n scanner moves into `internal/domain/memory` and is applied in `Create` and\n `Update` — the single choke point every producer crosses, so curator-extracted\n content is covered too.\n\n**Open in this section.** Ranked retrieval is deferred: `Query.Text` stays in\nthe contract, unused by the prompt path. Existing memory data is not migrated:\n`\u003cworkDir\u003e/memory` and `\u003cworkDir\u003e/memory-engine` are left on disk, unreferenced.\nThe PRD leaves these undetermined and they remain open here: group-chat\nextraction, where the curator fails closed on mixed-sender sessions; two\nprocesses (`archied` and `archie-gateway`) holding one scope file, where\n`Update.Expected` detects but does not prevent a lost block; unbounded\n`HISTORY.md` with no compaction policy; whether the per-scope size bound is\nright; and whether the dashboard should carry a user identity.\n\n### 6. Runtime and process boundaries — DECIDED\n\n`archied` is the native resident orchestration and interactive-chat process.\nEvery autonomous repository workflow crosses one full-task core-NATS handoff\ninto a task-scoped `archie-agent` container. Embedded versus external NATS\nchanges broker deployment only; it never selects an executor. The former host\nin-process runner, per-stage NATS protocol, and subprocess runner are removed.\n\nForge, store, and worktree authority remains in `archied` and is exposed to the\ntask container through scoped RPC services. The worker runs the workflow and\nits worker-local ai-sdk loop; it does not receive forge credentials or direct\nstore access. See `docs/prds/embedded-nats.md`.\n\n**UI Service boundary — RATIFIED (2026-09-07).** Phase 3 has a focused\nauthority record in [`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\nThe UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and\nits own endpoint/credential/readiness settings. It consumes Gateway and State\nStore contracts and does not receive `config.Holder`, daemon pointers, SQL or\nstore implementations, workflow registries, forge/channel/model runtimes, or\nresolved secrets. The current `internal/webui` implementation remains inside\n`archied` until the ratified migration gates prove route parity, adapter\nselection, failure/readiness behaviour, and deletion of the shared-holder and\ndirect-access paths. The extraction cutover removes the in-process UI\nlistener in the same change; there is no dual-live UI authority.\n\n**Dashboard live event delivery — DECIDED (2026-09-09, `archie-core-za9f`).**\nThe extracted UI receives live activity by polling the State Store's existing\n`EventsSince` cursor, not by a new push-subscription RPC. No proto change, no\ncontract amendment beyond this record.\n\nThe UI process runs one event pump. It primes its watermark by paging\n`EventsSince` to the end at startup without delivering, then polls\n`EventsSince(watermark, limit)` on an interval and hands each new event to\n`webui.Server.Broadcast`, exactly where `internal/app/archied/main.go`'s\n`persistAndBroadcastEvents` hands events to it today. One pump serves every\nconnected browser, so cost is one indexed query per interval regardless of\nviewer count, and `Broadcast` is a no-op when nobody is watching.\n\nThree properties make the cursor sufficient, and a push hub unnecessary:\n\n- **The cursor cannot skip.** `internal/infrastructure/postgres` takes an\n advisory event-append lock around each insert (`TestEventInsertsCommitInIDOrder`),\n so a row's `id` is assigned in commit order. There is no window in which a lower id becomes visible after a\n higher one, which is the failure mode that normally rules out polling an\n autoincrement cursor. SSE catch-up already depends on this same property.\n- **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each\n broadcast event as a signal to fill the persisted gap ahead of it via\n `catchUp`, then delivers the event only if catch-up did not already cover\n it, deduplicating on the `since` watermark. Substituting a poller for the\n in-process bus therefore changes no SSE semantics, and needs no change to\n `internal/webui/sse.go`. It also means a broadcast dropped to a stalled\n client self-heals on the next one.\n- **The table is the only complete fan-out point.** Events reach the store\n through several paths that never touch the daemon's bus, including the\n audit event `store.ArchiveTask` writes inside its transaction\n (`internal/infrastructure/postgres/store.go`) and the binding-dispatch failure\n `internal/daemon/daemon.go` inserts directly. A push hub would have to be\n hooked at every write site and at post-commit, and would silently miss any\n site added later that forgets to notify. Reading the table misses nothing.\n\nThe cost is one poll interval of latency on the activity feed, default 1s and\noperator-tunable. That is accepted: the feed reports task lifecycle history,\nand an operator action already gets its own synchronous HTTP response.\n\nThis resolves the `/events` row of the route-owner inventory in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). `/api/logs` and\n`/api/logs/stream` are not resolved by it, they read the daemon's in-process\ndiagnostic feed and remain host-local (see `archie-core-8cda.5.4`).\n\nRevisit only if sub-second feed latency becomes a requirement, or if a second\nconsumer needs the same stream, at which point the fan-out belongs in the State\nStore process behind a `SubscribeEvents` RPC and this record is superseded.\n\n**Dashboard configuration page — DECIDED (2026-09-09, `archie-core-ymut`).**\nThe configuration page becomes read-only in the UI process for Phase 3. Reads\ncross the boundary as a published snapshot; writes are descoped, not\ncontracted. This amends the ratified boundary, which assumed a single admin\ncontract carrying both.\n\n**Reads.** `webui.ConfigView` is already the whole answer. It is a UI-owned,\nsecret-free value projection built in `handleConfig`: `ProviderView` carries\nthe API key's environment variable name and a `Configured` boolean, never a\nvalue, and `RepoView` is repository metadata only. It is already the exact\nshape the browser receives. So the daemon publishes that projection, plus\nprovenance, reload status and the overridden-key list, as a snapshot the UI\nreads; nothing new has to be designed, only moved. Two State Store RPCs carry\nit, a `PutConfigSnapshot` restricted to the administrative token and a\n`GetConfigSnapshot` the UI calls. The daemon republishes on boot and after\neach successful reload, which is precisely when the projection changes.\n\nThe State Store is the right holder because a published configuration snapshot\nis shared state, it is already dialled by the UI, and it costs no new listener,\nport, token or interceptor. The alternative, a config admin service on\n`archied`, would make the daemon a gRPC server for the first time. Today it is\npurely a client of Gateway and State Store; `grpc.NewServer` appears only in\n`RunGateway` and `RunStateStore`, which are the standalone binaries' entry\npoints, not the daemon's.\n\n**Writes.** `PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}` answer 503 in the UI process, and the\nSPA hides those controls rather than offering a button that fails. Editing is\n`config.toml` plus reload, which is already the only path for every setting\noutside the runtime-tunable allowlist.\n\nThis is a deliberate feature reduction and worth naming as one. The write path\nis not hard because of the transport; it is hard because the policy is\ndaemon-local and stays that way: `installUpdateConfigHandler` denies\nnon-runtime-tunable keys, applies a dotted overlay to a clone of the published\nconfig, validates the materialised result, writes overlay rows, and rebuilds\nprovenance. Contracting that means either moving the policy, which the\nboundary forbids, or exposing it verbatim as remote procedure calls, which\nbuilds a Configuration Service inside a migration bead. Neither is work this\nphase should be doing to keep one page's buttons alive.\n\nRevisit when dashboard configuration editing is picked up as a feature in its\nown right (`archie-core-1786637498420-327`, still open). At that point it gets\nan admin contract designed as a feature, and the Configuration Service this\ndocument already anticipates is its natural owner. Until then the UI renders\nconfiguration and does not write it, which is what the boundary always said\nabout ownership even when it assumed a wider contract.\n\nAmended 2026-09-11. This descope is a deferral, not a decision that the\ndashboard should be read-only. Name it that way in review: the daemon-side\npolicy was built and tested, then deleted by the cutover (`e037b95` removed\n`internal/app/archied/config_update.go` and its tests), so reviving it is\nrecoverable work, not a rewrite. `archie-core-j28m` carries the remaining\nquestion -- which process serves the policy and what transport carries the\nwrite -- and blocks the feature bead. The handlers, their error sentinels and\nthe `UpdateConfig`/`ResetConfig`/`UpdateRepoField` seams on `webui.Server` are\nkept deliberately for it; `ConfigView.Editable` follows whichever process holds\n`UpdateConfig`, so wiring that one field makes the page editable\n(`archie-core-ml30`).\n\nImplementation belongs to `archie-core-8cda.5.4`, the cutover that removes the\ndaemon's own dashboard. Nothing here is built yet.\n\n**Superseded 2026-09-21 by the runtime control plane.** The open question this\ndescope left -- which process serves the policy and what transport carries the\nwrite -- was answered by `docs/prds/runtime-control-plane.md`: neither a daemon\nadmin service nor a revival of the daemon-local policy. `ControlPlaneService` on\nthe State Store's existing gRPC server owns every database-backed setting, and\neach feature validates its own resource, so there is no daemon-local policy left\nto contract. `archie-core-j28m` is closed.\n\nConsequently the three write seams described above no longer exist.\n`PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}`, the `UpdateConfig`/`ResetConfig`/\n`UpdateRepoField` fields on `webui.Server`, and `ConfigView.Editable` were\ndeleted in `31622ec5` along with the runtime overlay store they wrote to.\n`GET /api/config` remains a read of the published projection, as this decision\nalways intended.\n\n### 7. Shared mechanics\n\nThe following cross-domain mechanics require exact contracts before dependent\npackages migrate:\n\n- event-bus delivery and failure semantics;\n- policy evaluation API, composition, and precedence;\n- configuration candidate preparation, health validation, atomic promotion,\n observation, and rollback;\n- service-specific health, bounded remediation, isolation, and escalation;\n- changelog association and grouping.\n\nThese shared mechanisms do not acquire ownership of domain meaning. Domains\ncontinue to own their commands, events, policies, settings, and consequences.\n\nThe Go documentation generator, its output placement, and drift checking are\ndefined in `generated-documentation.md`. The external Astro website consumes\nthe committed documentation and release JSON artifacts and serves them under\n`offloaded.dev/docs/`. This repository owns the source and artifact checks; the\nwebsite repository owns rendering and deployment. The generators and\nArchie's normalised documentation model remain migration work rather than open\nproduct architecture.\n\n**Amended 2026-09-15.** `internal/infrastructure/servicediscovery/nats`\nimplements the `servicediscovery.ServiceRegistry` contract (Connect, Register,\nResolve, Watch) over NATS KV and is fully tested, but no production code\nconstructs it and no config surface exposes it. This is a deliberate deferral,\nnot an oversight: service-to-service addressing belongs to the runtime and\nprocess boundary work in section 6, which currently pins container addressing\nby injecting the daemon's startup NATS URL rather than resolving through a\nregistry. The scaffold is kept for that work; re-derive it only if the\naddressing model changes.\n\n### 8. Cutover sequence\n\nThe final migration plan must order:\n\n- compatibility adapters;\n- schema migrations and data backfills;\n- any required dual-read or transitional paths;\n- domain-by-domain package replacement;\n- production wiring changes;\n- legacy package removal;\n- architecture tests preventing dependency regression;\n- focused, integration, race, and full quality gates.\n\nEach legacy package requires objective removal criteria. No compatibility path\nmay become an indefinite second implementation.\n\n## Completion criteria\n\nMigration design is complete when:\n\n- every current package has one approved owner and destination;\n- every mutable record has one authoritative owner and migration path;\n- all external and cross-process contracts have versioned owners;\n- existing behaviour and data have explicit parity requirements;\n- process boundaries have evidence-backed justification;\n- the cutover order preserves a working application;\n- legacy deletion criteria and deterministic architecture tests are defined;\n- no unresolved decision requires an implementer to invent domain semantics.\n\nExact Go APIs, SQL statements, and mechanical refactoring steps MAY be finalized\nduring implementation when they do not change these semantics.\n\n## Recorded migration position (2026-07-29)\n\nRecovered 2026-08-09 from the pre-migration issue tracker. This section records\ndecisions the maintainer approved that the repository did not otherwise capture.\n\n**Completed:** `internal/infrastructure/eventbus/nats` (rebuilt, not relocated);\n`internal/infrastructure/configuration` (loading moved out of `internal/config`,\nwhich is now types-only and does no I/O); `internal/eventbus` (broker-neutral\ncontract); `internal/domain/workintake` (the first `internal/domain/` package,\nowning `TaskEnvelope`, the routing `Kind`, the label vocabulary, and task\nsubjects).\n\n**DECISION — private input DTO deferred (approved).**\n`configuration.Document.Config` is still `internal/config.Config` rather than the\nprivate per-domain input DTO this document mandates. Building an ~800-line\nparallel type tree while every consumer still reads `config.Config` would mean\ntwo shapes kept in sync by hand, with no consumer for the new one. It is named as\na field so the compromise is visible at each use site, with the deletion\ncondition recorded in that package's `doc.go`. Do this **with** the\n`internal/config` dissolution, not ahead of it.\n\n**Agreed next: `internal/app/{archied,agentworker}`.** `run()` in\n`cmd/archied/main.go` is ~460 lines, against `organisation.md`'s rule that\n`cmd/*` must not contain substantive wiring or act as a service locator. It is\nalso the last non-infrastructure holder of the NATS SDK, and it is where the\nconfig DTO translation will land, so it unblocks the dissolution above.\n\n**Method constraint.** Do not write a separate recorded package-review document\nper area when the decisions are already dictated by\n`dependencies-and-contracts.md`. That is the ceremony pattern this project\ndeliberately avoids.\n\n## OPEN — `[chat.*]` config section naming\n\n`configuration.md:160` already states the position: `ChatConfig` holds \"separate\nchannel instance settings... there is no chat-wide settings owner\". The config\nsection name has not followed, so a settings block named for a product surface\nowns what the architecture calls channel state.\n\nTwo candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The\nsecond reads as a domain path, and no config section in this repo is currently\nnamed after a domain package, so adopting it sets a precedent for every other\nsection rather than fixing one name.\n\nBlocked on a maintainer decision, not on evidence. This is a rename with an\noperator-visible TOML break, so it should land with the `internal/config`\ndissolution recorded above rather than on its own.\n" }, { "url": "/dev/architecture/observability/", diff --git a/docs/prds/execution-tree-state-machine.md b/docs/prds/execution-tree-state-machine.md new file mode 100644 index 000000000..e4b3cb420 --- /dev/null +++ b/docs/prds/execution-tree-state-machine.md @@ -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.