* feat(workflow): post line-anchored review comments with suggested fixes Bead archie-core-q9au (docs/prds/inline-review.md). A review's findings reached the operator only as a flat list in the PR body, so the author had to map every finding back to its line by hand and apply mechanical fixes by hand. Now the line-anchored findings are also posted as inline review comments, carrying a one-click suggestion when the reviewer could state the fix. Domain (internal/domain/workflow): - ReviewFinding gains Suggestion; Validate rejects one on anything but a confirmed finding, so the agent's record_finding call is refused with something it can act on. Validate splits into validateAnchor / validateClassification / validateDisposition, which also brings it back under the cyclop limit the gate enforces. - StagePostReviewComments runs after StageOpenPR in the implement workflow. It posts only line-anchored findings (Line > 0); a whole-file finding has no line to attach to and stays in the body list, which remains the complete record. It is best-effort: the PR is open and the body already lists every finding, so a failed comment is logged, never a park -- the same reasoning as OpenPR's existing best-effort LinkBranch call. - The suggestion fence is gated on Verdict == confirmed where the fence is written, because it is a one-click apply: a wrong suggestion breaks the code and the author has to notice. Forge (internal/forge): ReviewCommentWriter + GitHub/Gitea implementations, type-asserted like PullRequestReader so a forge that cannot is skipped rather than faked (NoopForge is pinned as not satisfying it). GitHub loops one CreateComment per comment and joins the failures, so one refused anchor cannot drop the rest; Gitea carries them on a single COMMENT-state review. Two deliberate departures from the PRD's sketch, both recorded in it: - The interface is batch (CreateReviewComments), not one call per comment: Gitea's only inline shape is one submitted review, and the set then crosses NATS once instead of once per finding. - The head SHA is resolved inside each forge implementation rather than by the caller. The stage runs in archie-agent, which holds no forge credentials and has no PullRequestReader; the daemon-side forgerpc handler is the only place that does. Transport (internal/forgerpc): workflow.Forger gains the method, so the agent reaches the daemon over the new create_review_comments subject; the server type-asserts the writer and answers an incapable forge with an error the stage logs. This is the one proxied method whose absence on an image skew does not park a task. The reviewer prompt and record_finding schema ask for a suggestion on a confirmed, mechanically fixable defect only. Regenerating the wfextract symbol table -- the documented way a new exported workflow symbol reaches interpreted stage plugins -- also picked up symbols that were missing from the committed table (the Status* and Source* constants, ReviewCheck, Store, Task, and the _Store wrapper). Nil-guards were re-applied to every wrapper afterwards, as that file's header requires. Evidence: task check exit 0 (incl. 229 UI tests). Three mutations of the new stage logic each fail a test that names the behaviour -- dropping the confirmed-only gate, dropping the Line > 0 filter, and letting a posting failure escape -- so the tests discriminate rather than passing vacuously. * fix(build): drop the Dockerfile pin assertion The guard fetched golangci-lint's go.mod at image build time to fail the build when GOLANGCI_LINT_VERSION and GOFUMPT_VERSION disagreed. It only ever tripped on self-inflicted pin drift, but it added a network fetch and a new failure mode to the release build, which is not where that belongs. The pins stay correct (golangci-lint 2.13.2, whose vendored gofumpt v0.11.0 equals GOFUMPT_VERSION) and the comment above them still states the invariant, so the reasoning survives without the build-time machinery. The pin change itself reaches the agent image through the normal release path: CI rebuilds and pushes archie-agent on an archie/vX.Y.Z release, and a gateway-only release deliberately does not. * feat(workflow): add the remediate workflow for PR review remediation Implements step 5 of docs/prds/pr-review-remediation.md: a remediate workflow that resumes the task's existing worktree onto its PR branch (worktree.Manager.Resume, not Prepare's refresh), runs a builder agent against the review's actionable comments, commits and pushes to the same branch, and replies via the forge's ReplyToReview. Task.RetryCount doubles as the remediation round counter, capped by the repo's max_retries; the round-cap stage parks the task and posts one comment when it's hit. Task gains a ReviewPayload field (JSON-encoded review unit) with full store/proto/staterpc plumbing. workflow.Forger gains Comment and ReplyToReview, proxied to archie-agent via a new forgerpc RPC. Resume and its Dir lookup are added as an unexported optional Trees capability rather than widening the exported interface, which is already at golangci-lint's interfacebloat cap and is projected into wfextract's Yaegi symbol table for repository-authored stage plugins. The daemon-side reaction consumer that dispatches into this workflow (subscribing ARCHIE_REACTIONS, grouping comments by review, enforcing per-task serialization) is tracked separately in archie-core-8li9.4. * feat(messaging): extract standalone messaging service binary and process composition * feat(messaging): adapt channel frontends to consume Gateway ChatContract * feat(messaging): remove in-process channels and Router from daemon bootstrap Telegram, email and webhook now run only in the Messaging Service, which reaches this process through the Gateway's ChatContract. The daemon builds no channel and no gateway.Router, so the wiring that existed only to serve them goes with it: setupGateways, setupEmailGateway, setupWebhookGateway, setupTelegramGateway, buildTelegramRouter, makeTelegramReload and the release-announcement path helper. The seams those paths owned move to where they can still be honoured: - Channel ValidateConfig runs in archiemessaging.compose, which now returns an error, so a configured-but-invalid front-end fails the service rather than being dropped silently. - The inbound rate limiter moves to the Gateway process, which owns the only Router and therefore the only place a per-sender budget applies to every channel's turns. - The daemon's gateway readiness probe becomes a ContractProbe against the Gateway. It cannot observe a channel lifecycle it no longer runs, and a channel-count probe would have reported every daemon degraded. - telegramSetup is now chatSetup (in chat_setup.go), trimmed to the fields a chat turn runner actually reads. Telegram operator features that were wired only in the daemon (/update, release announcements, version reporting, SIGHUP reload) are not yet wired in the Messaging Service: archie-core-8cda.6.6. Channel lifecycle reporting: archie-core-8cda.6.8. The Gateway process builds no worktree manager, so review_pr is unadvertised on every channel: archie-core-8cda.6.7. * feat(messaging): re-wire the Telegram operator surface in the Messaging Service setupTelegramGateway satisfied eight telegram.Gateway seams from the daemon's own process. Each is resolved by where the fact it needs is owned, not by where it used to be built; the decision table is in docs/architecture/migration-decisions.md. Wired here: /update (built from this service's own [chat.telegram] check and install commands), the update-report relay (same sha256(bot_user)[:8] path the daemon wrote, so a pending report is found rather than written afresh), show_tool_calls, and /restart's config reload, which re-resolves the token and allowlist from this service's own file and refuses a reload that resolves to an empty token. /version is sourced from the Gateway: ChatSnapshot gains a Version field carrying the Gateway's rendered build block, read per call and bounded by the dependency timeout. cmd/archie-messaging deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. RunningVersions and ReleaseAnnouncements stay nil. Both need a component's real running version, and the only versions this process can obtain are a different binary's stamps -- reporting them would manufacture exactly the false success the update check exists to catch, and the announcer without parseable versions is a no-op that reads as configured. archie-core-8cda.6.9 carries the contract that unblocks them. Dangerous stays nil: no composition has ever supplied a command authority. Enrich is dropped from the update service: componentInstallTypeEnricher read [nats], which this service must not decode, so the check command's own reported install type stands. * fix(workflow): guard inline review comments against head drift Two findings from the review of q9au. A comment's line numbers describe exactly one revision of the branch, but the forge resolved the pull request's head at posting time -- after the review had already read the worktree. A push in that window (a collaborator, a retry) meant the findings were anchored to whatever now occupied those lines, mislabelling instead of failing. The revision the review measured now travels with the comment set: OpenPR records it from the same worktree read it already performs (TaskContext.ReviewedHeadSHA), StagePostReviewComments threads it through Forger to forgerpc, and the forge refuses the whole set once the head it reads has moved off it -- which the best-effort stage logs, the PR body remaining the record. An unmeasured revision posts unverified rather than dropping every finding, so a worktree that cannot report one degrades instead of regressing. Suggestion was documented single-line only, because GitHub applies a suggestion fence up to its first line and a multi-line replacement would silently corrupt the file. Only the verdict was validated, so a multi-line suggestion reached the renderer and posted as that truncated fence. Validate now rejects an embedded newline, which makes record_finding refuse it with feedback the model can act on instead of the reviewer discovering the corruption later.
35 KiB
Architecture Migration Decisions
Status: Active migration inventory
Date: 2026-07-28
Tracking issue: #73
Purpose
This document records what remains to be decided before Archie's current implementation can be migrated into the approved domain-oriented structure.
The product and core domain model are not being redesigned. Existing Archie behaviour and the existing session implementation are the migration baseline. Remaining decisions MUST be grounded in current packages, consumers, tests, persistence, and runtime wiring.
Confirmed domain packages
internal/domain/
identity/ (approved, not yet materialised as a package)
agent/ (approved, not yet materialised as a package)
workflow/
messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)
workintake/
plugin/ (approved, not yet materialised as a package)
curator/
mapping/
scheduling/
identityowns persistent actors, lifecycle, ownership, attribution, and audit identity.agentowns persistent assistants, specialisation, instructions, model-independent continuity, capability context, and associations with identity and memory.workflowis a separate domain. It owns reusable, versioned Workflow definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts, outcomes, and typed Workflow plugin contracts.messagingowns canonical Messages, Conversations, branches, channel and source correlation, replies, acknowledgements, delivery attempts, events, and projections.workintakeowns admission, validation, deterministic routing, and accepted work requests for the optional transition into durable workflow-backed execution.pluginowns generic plugin identity, discovery, compatibility, and lifecycle mechanics. It remains metadata-only; capability semantics and typed registration belong to the owning domain.curatorowns the curator engine family: long-running agent loops that reason over memory and perform maintenance tasks on a declared shape (check-in interval, tool set, attached memory engine). See epic archie-core-yp9.mappingowns the payload field-mapping vocabulary: binding named fields to JSON paths inside a captured webhook payload, and detecting drift. Seedocs/prds/payload-field-mapping.md.schedulingowns the ticker engine: deciding when a scheduled job runs and with what concurrency. It declaresJobSource/Runnercontracts and owns no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.
Reconciliation (2026-08-31): curator, mapping, and scheduling existed
in the tree without being added to this list when their epics landed. They are
confirmed as legitimate, narrowly-scoped domains under the same rules as the
original six — each owns one capability family, declares typed contracts, and
has no cross-domain reach. This list was out of date, not the tree.
Conversely, identity, agent, messaging, and plugin are approved target
domains that do not yet exist as packages. Their behaviour currently lives in
pre-migration packages (see "Complete package destination map" below for the
full inventory). Do not create empty stub packages for them ahead of an
actual migration PR — an unused stub is dead code and gives no test coverage.
Each materialises when its corresponding migration decision below is resolved
and implemented in the same change.
Memory's final package placement remains undecided pending focused review of the existing implementation.
The following are approved shared or composition packages, not domains:
internal/eventbus/
internal/policy/
internal/infrastructure/
internal/app/archied/
internal/app/agentworker/
Remaining migration decisions
1. Complete package destination map
Every current package MUST receive one explicit disposition:
- move into a confirmed domain;
- move under infrastructure as an implementation of a domain-owned contract;
- move into application composition;
- merge with an identified duplicate;
- remain as an approved shared application contract;
- move to a plugin, extra, deployment, example, or generated artifact;
- be deleted after its replacement is proven.
The largest unreviewed areas include memory, tools and capabilities, workspace and worktree behaviour, gates, storage, events, web UI, containers, RPC packages, release management, and scheduling.
The destination matrix MUST name the behaviour owner, target path, dependencies to remove, state and contracts to preserve, migration prerequisites, and deletion criteria.
internal/webui / UI Service — RATIFIED Phase 3 disposition (2026-09-07).
The current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator
authentication, UI response projection, configuration reads and mutations,
task/control APIs, and direct adapters to State Store, channel, event/log,
memory, curator, workflow, forge, and Gateway runtime values. The target owner
is a standalone UI application process; internal/webui remains its HTTP
transport adapter, while Gateway, State Store, configuration, Work Intake,
Messaging, and other capability owners expose the contracts behind those
routes. The migration preserves retained route schemas, auth/CSRF behavior,
task/capture/mapping/binding/session continuity, SSE replay semantics, and
committed generated SPA assets. Prerequisites are the ratified UI boundary,
route-owner inventory, narrow remote adapters, configuration/auth/readiness
contracts, and process/conformance tests. Remove the shared live
config.Holder, direct event/log bus, daemon stopper, forge client, channel
manager, capability registries, composite store access, and in-process UI
listener only after the focused criteria in
docs/prds/ui-service-boundary.md pass in
production composition. The old construction and listener are deleted in the
same cutover change; no second UI authority remains.
2. Session and Messaging migration
The existing session implementation is the migration baseline. The migration must decide:
- which session and message components are retained or adapted;
- how Agent, user, channel, Conversation, and branch ownership are added;
- how Archie's parallel gateway session implementation is replaced;
- how canonical Messages become immutable persisted records;
- how existing sessions and messages are migrated;
- how outbound delivery, retry, acknowledgement, deduplication, and failure semantics are represented;
- how current Telegram, email, webhook, forge, and Jira integrations migrate to Messaging infrastructure adapters.
The following are already decided and MUST NOT be reopened without contradictory implementation evidence:
- the composite Conversation identity;
- immutable MessageIDs;
- typed tool-call and tool-result messages;
- exact branch lineage through ParentConversationID and ForkMessageID;
- parent and child transcript isolation;
- normal scoped-memory behaviour regardless of the originating Conversation;
- Messaging and Work Intake ownership.
Decision (2026-08-31), resolving the open questions above:
internal/gateway/ is the "parallel gateway session implementation" this
section names. It is retained as-is for now — a big-bang rewrite of live
session/compression/approval/branch logic across Telegram, web UI, email, and
webhook channels in one change is exactly the "convoluted to satisfy edge
cases" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would
risk silent behavioural regressions in the one path every user-facing message
travels through.
Instead, internal/domain/messaging/ is materialised now with the pieces
that are already decided and don't require touching gateway: the canonical
Message and Conversation types (composite Conversation identity, immutable
MessageID, typed tool-call/tool-result message variants, branch lineage via
ParentConversationID/ForkMessageID). These are pure domain types with no
gateway dependency — a new package, not a rewrite of an existing one.
Migrating internal/gateway/'s session, compression, approval, and branch
logic onto these types is real, cross-channel-risk work and is not done in
this pass. It is tracked as separate, appropriately-scoped bd issues (see
bd list --label messaging-migration), sequenced channel-by-channel so each
lands with its own behavioural verification instead of one large diff no one
can safely review.
Amended 2026-09-15. internal/infrastructure/gatewayrpc.StoreClient is the
adapter this migration will need: it implements messaging.SessionStore over
the chat service's session-store RPCs and is proven by
TestStoreClientPreservesCanonicalRecords. It is deliberately unwired.
Production archied dials the standalone gateway for ChatContract only
(composeChatContract → gatewayrpc.Dial returns a *Client, not a
*StoreClient), and the daemon's session store is in-process SQLite via
makeTelegramSessionStore. The test comment that says it mirrors production
describes the target, not today's tree. Kept rather than deleted because the
migration it serves is deferred by this very section, and re-deriving a tested
wire adapter once that lands is pure cost.
Phase 4 Messaging Service extraction (2026-09-19, archie-core-8cda.6.1).
The process boundary for external channels (Telegram, email, webhook) is ratified
in docs/prds/messaging-service-boundary.md.
Messaging is extracted into cmd/archie-messaging / internal/app/archiemessaging,
calling Gateway's messaging.ChatContract exclusively over gRPC. Channel frontends
hold no direct database handles, daemon state, or model runtimes.
Telegram operator surface after extraction (2026-09-19, archie-core-8cda.6.6).
setupTelegramGateway wired eight telegram.Gateway seams the daemon could
satisfy from its own process. Each is resolved by where the fact it needs is
actually owned, not by where it used to be built:
| Seam | Resolution |
|---|---|
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. |
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. |
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. |
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. |
SetShowToolCalls |
Projected from [chat].show_tool_calls. |
Reload |
Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |
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. |
Dangerous |
Stays nil. No daemon composition ever set it; /rollback and /stop reported "not configured" before the extraction and still do. |
The Messaging Service consequently reads work_dir, bot_user, [chat] and
[health] in addition to the PRD's [chat.*] / [services.gateway] list.
[health] is the daemon's health URL, which releaseupdate.CommandInstaller
polls from outside to confirm an update came back up; the rest of the PRD's
prohibition list is untouched.
3. Identity data migration
The migration must define:
- the durable identity schema and repository implementation;
- bootstrap of the permanent system identity;
- stable IdentityIDs for existing configured Agents;
- migration from configured identity names, empty-string ownership, and bot usernames;
- preservation of historical attribution;
- identity-aware uniqueness and transport deduplication;
- correction of container and RPC capability resolution so execution uses the owning identity's bindings;
- removal of identity-string equality from access-control behaviour.
Exact schema and method signatures are implementation decisions. The approved Identity lifecycle and attribution semantics are fixed migration constraints.
4. Workflow migration
The current implementation must be transformed deliberately:
store.Task -> WorkflowExecution
mutable Stage -> StepExecution history
RetryCount / Attempt -> Attempt records
workflow.Registry -> versioned Workflow definitions
current stages -> WorkflowStep definitions or Workflow plugins
The migration must decide:
- Workflow definition and version persistence;
- the smallest accepted-work-request contract consumed from Work Intake;
- the enforced WorkflowExecution state machine;
- atomic state and domain-event persistence;
- migration of existing task rows and transition history;
- disposition of current skill, Yaegi, and stage-plugin implementations;
- the versioned worker-handoff contract;
- scheduler, claim, retry, crash-recovery, and waiting-human cutover.
Workflow remains a separate domain from Agent. A user or Agent may define or invoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.
5. Memory placement and storage
The four required scopes are fixed:
- global shared;
- Agent-wide;
- user-wide;
- Agent-user relationship.
A focused review of internal/memory, its providers, consumers, persistence,
and tests had these decisions:
internal/domain/memoryversus ownership within the Agent domain — settled (2026-09-02, below);- the authoritative memory record and revision model — settled by the PRD (2026-09-16, below);
- provider and infrastructure boundaries — settled by the PRD (2026-09-16, below);
- retrieval and access enforcement — settled by the PRD (2026-09-16, below); ranked retrieval remains open (below);
- migration of existing memory data — open: existing data is not migrated;
- provenance representation — settled by the PRD (2026-09-16, below).
Conversation branches do not create another memory scope. A memory action has the same scoped effect regardless of which Conversation originated it.
internal/domain/memory ownership — DECIDED (2026-09-02). The typed
engine family lives at internal/domain/memory
(archie-core-1786637490069-11-e245c170), mirroring internal/domain/curator's
contract/registrar/registry split. Not owned within the Agent domain: memory
is consumed by more than agent turns (curators, per archie-core-1786637499636)
and the plugin engine rule requires its own family, not a capability bolted
onto another domain's contract.
Authoritative record and revision model for the builtin engine — DECIDED
(2026-09-02), scoped to unblock archie-core-1786637499480 (ship the
file-writing store as the default engine). This decides only the builtin
engine's mapping onto the new Record{ID}/Forget(id) contract, not the
memory model in general or a future non-file engine's model:
internal/memory/builtin.Storeis unchanged. It has no concept of a stable per-block ID — blocks are addressed by content substring — and nothing in this decision requires changing that; existinginternal/memorytests keep passing unmodified, per that issue's acceptance criteria.- A new infrastructure adapter (
internal/infrastructure/memory, perorganisation.md's "infrastructure implements domain contracts" rule — not underinternal/domain/memory, which stays contract-only) wraps onebuiltin.Storeper identity. - Identity → directory:
hex(sha256(identity)), not the identity string itself. Closes the path-traversal question without an allowlist regex, and sidesteps collisions from identities that differ only in characters a filesystem treats as equivalent. - Record ID: assigned once at
Write, independent of content, so a later edit elsewhere in the file can never orphan aForget. Realized as a leading marker line (<!--mem:<ulid>-->) on the blockbuiltin.Store.Addwrites;Query/Liststrip it back out ofRecord.Contentbefore returning, andForget(id)locates the block by that unique marker via the store's existing substring-basedRemove. The marker is a pragmatic, reversible choice — plain-text records stay human-readable and human-editable, at the cost of one marker line an operator editing the file by hand should leave alone. Revisit if/when provenance representation (still open, below) settles on something richer. - Kind → section:
Observation.Kind(default"general"when empty) is the section name, reusingbuiltin.ValidateSectionName— so an invalidKindfailsWritewith the same validation errormemory_editalready returns for an invalid section today, not a new error shape.
Memory engine: scopes, CRUD with retained revisions, and store placement —
DECIDED (2026-09-16). Supersedes the 2026-09-02 "Authoritative record and
revision model for the builtin engine" entry above, whose <!--mem:<ulid>-->
live marker cannot carry provenance. Authority:
docs/prds/memory-engine-unification.md
(Approved); the contract is internal/domain/memory/contract.go. This register
supersedes; it does not erase.
- Four typed scopes, caller-named.
internal/domain/memoryis addressed byScope{Kind, Agent, User}overglobal,agent,userandagent-user, withValidaterejecting a component present where it is not required. A caller names the read and write sets (Subject.Scopes()/WritableScopes(); global is never model-writable) and the engine applies no policy of its own: access control is naming a scope, and nothing else. An engine that enforced policy would need to know about channels, sessions and bindings, and every backend would reimplement it.Scope.Key()length-prefixes each component, so two scopes can never share a key even when an opaque channel-native id embeds the separator. - The caller resolves identity; the engine never does. Resolution happens in the gateway turn path, where the native sender id and the session are both in hand, and is supplied per channel by the composition. A webhook's sender id is a route path, not a person, and treating it as one would give a URL an identity. An absent user id yields global and agent scopes only: "show none of it", never a wider fallback.
- CRUD supersedes, never overwrites.
StoreisCreate/Get/Query/List/Update/Forget/Revisionsover the four scopes.Updateappends the superseded state to the scope'sHISTORY.mdbefore replacing the live block;Update.Expectednames the revision being replaced and returnsErrStaleRevisionon mismatch, making a lost update between two processes sharing one scope file detectable.Forgetrecords a deleted revision before removing the live block, so a record's provenance outlives its content;GetandForgettake a scope, because an id alone does not locate one. - Provenance representation. The live marker becomes JSON, since a
<!--mem:<ulid>-->line cannot carry provenance, andRecordretains the provenanceagent-system.mdrequires — scope, author, originating user, source, and revision history.Metadatais dropped: it never round-tripped. - Store and scanner placement. The markdown store relocates to
internal/infrastructure/memory/builtin, its correct home underorganisation.md's "a package owns its on-disk format end-to-end". The content scanner moves intointernal/domain/memoryand is applied inCreateandUpdate— the single choke point every producer crosses, so curator-extracted content is covered too.
Open in this section. Ranked retrieval is deferred: Query.Text stays in
the contract, unused by the prompt path. Existing memory data is not migrated:
<workDir>/memory and <workDir>/memory-engine are left on disk, unreferenced.
The PRD leaves these undetermined and they remain open here: group-chat
extraction, where the curator fails closed on mixed-sender sessions; two
processes (archied and archie-gateway) holding one scope file, where
Update.Expected detects but does not prevent a lost block; unbounded
HISTORY.md with no compaction policy; whether the per-scope size bound is
right; and whether the dashboard should carry a user identity.
6. Runtime and process boundaries — DECIDED
archied is the native resident orchestration and interactive-chat process.
Every autonomous repository workflow crosses one full-task core-NATS handoff
into a task-scoped archie-agent container. Embedded versus external NATS
changes broker deployment only; it never selects an executor. The former host
in-process runner, per-stage NATS protocol, and subprocess runner are removed.
Forge, store, and worktree authority remains in archied and is exposed to the
task container through scoped RPC services. The worker runs the workflow and
its worker-local ai-sdk loop; it does not receive forge credentials or direct
store access. See docs/prds/embedded-nats.md.
UI Service boundary — RATIFIED (2026-09-07). Phase 3 has a focused
authority record in docs/prds/ui-service-boundary.md.
The UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and
its own endpoint/credential/readiness settings. It consumes Gateway and State
Store contracts and does not receive config.Holder, daemon pointers, SQL or
store implementations, workflow registries, forge/channel/model runtimes, or
resolved secrets. The current internal/webui implementation remains inside
archied until the ratified migration gates prove route parity, adapter
selection, failure/readiness behavior, and deletion of the shared-holder and
direct-access paths. The extraction cutover removes the in-process UI
listener in the same change; there is no dual-live UI authority.
Dashboard live event delivery — DECIDED (2026-09-09, archie-core-za9f).
The extracted UI receives live activity by polling the State Store's existing
EventsSince cursor, not by a new push-subscription RPC. No proto change, no
contract amendment beyond this record.
The UI process runs one event pump. It primes its watermark by paging
EventsSince to the end at startup without delivering, then polls
EventsSince(watermark, limit) on an interval and hands each new event to
webui.Server.Broadcast, exactly where internal/app/archied/main.go's
persistAndBroadcastEvents hands events to it today. One pump serves every
connected browser, so cost is one indexed query per interval regardless of
viewer count, and Broadcast is a no-op when nobody is watching.
Three properties make the cursor sufficient, and a push hub unnecessary:
- The cursor cannot skip.
internal/store/store.goopens the database withSetMaxOpenConns(1), so writes serialise and a row'sidis assigned in commit order. There is no window in which a lower id becomes visible after a higher one, which is the failure mode that normally rules out polling an autoincrement cursor. SSE catch-up already depends on this same property. - A broadcast is a wakeup, not the payload.
sseStream.draintreats each broadcast event as a signal to fill the persisted gap ahead of it viacatchUp, then delivers the event only if catch-up did not already cover it, deduplicating on thesincewatermark. Substituting a poller for the in-process bus therefore changes no SSE semantics, and needs no change tointernal/webui/sse.go. It also means a broadcast dropped to a stalled client self-heals on the next one. - The table is the only complete fan-out point. Events reach the store
through several paths that never touch the daemon's bus, including the
audit event
store.ArchiveTaskwrites inside its transaction (internal/store/store.go) and the binding-dispatch failureinternal/daemon/daemon.goinserts directly. A push hub would have to be hooked at every write site and at post-commit, and would silently miss any site added later that forgets to notify. Reading the table misses nothing.
The cost is one poll interval of latency on the activity feed, default 1s and operator-tunable. That is accepted: the feed reports task lifecycle history, and an operator action already gets its own synchronous HTTP response.
This resolves the /events row of the route-owner inventory in
ui-service-boundary.md. /api/logs and
/api/logs/stream are not resolved by it, they read the daemon's in-process
diagnostic feed and remain host-local (see archie-core-8cda.5.4).
Revisit only if sub-second feed latency becomes a requirement, or if a second
consumer needs the same stream, at which point the fan-out belongs in the State
Store process behind a SubscribeEvents RPC and this record is superseded.
Dashboard configuration page — DECIDED (2026-09-09, archie-core-ymut).
The configuration page becomes read-only in the UI process for Phase 3. Reads
cross the boundary as a published snapshot; writes are descoped, not
contracted. This amends the ratified boundary, which assumed a single admin
contract carrying both.
Reads. webui.ConfigView is already the whole answer. It is a UI-owned,
secret-free value projection built in handleConfig: ProviderView carries
the API key's environment variable name and a Configured boolean, never a
value, and RepoView is repository metadata only. It is already the exact
shape the browser receives. So the daemon publishes that projection, plus
provenance, reload status and the overridden-key list, as a snapshot the UI
reads; nothing new has to be designed, only moved. Two State Store RPCs carry
it, a PutConfigSnapshot restricted to the administrative token and a
GetConfigSnapshot the UI calls. The daemon republishes on boot and after
each successful reload, which is precisely when the projection changes.
The State Store is the right holder because a published configuration snapshot
is shared state, it is already dialled by the UI, and it costs no new listener,
port, token or interceptor. The alternative, a config admin service on
archied, would make the daemon a gRPC server for the first time. Today it is
purely a client of Gateway and State Store; grpc.NewServer appears only in
RunGateway and RunStateStore, which are the standalone binaries' entry
points, not the daemon's.
Writes. PATCH /api/config, POST /api/config/reset and
PATCH /api/config/repos/{owner}/{name} answer 503 in the UI process, and the
SPA hides those controls rather than offering a button that fails. Editing is
config.toml plus reload, which is already the only path for every setting
outside the runtime-tunable allowlist.
This is a deliberate feature reduction and worth naming as one. The write path
is not hard because of the transport; it is hard because the policy is
daemon-local and stays that way: installUpdateConfigHandler denies
non-runtime-tunable keys, applies a dotted overlay to a clone of the published
config, validates the materialised result, writes overlay rows, and rebuilds
provenance. Contracting that means either moving the policy, which the
boundary forbids, or exposing it verbatim as remote procedure calls, which
builds a Configuration Service inside a migration bead. Neither is work this
phase should be doing to keep one page's buttons alive.
Revisit when dashboard configuration editing is picked up as a feature in its
own right (archie-core-1786637498420-327, still open). At that point it gets
an admin contract designed as a feature, and the Configuration Service this
document already anticipates is its natural owner. Until then the UI renders
configuration and does not write it, which is what the boundary always said
about ownership even when it assumed a wider contract.
Amended 2026-09-11. This descope is a deferral, not a decision that the
dashboard should be read-only. Name it that way in review: the daemon-side
policy was built and tested, then deleted by the cutover (e037b95 removed
internal/app/archied/config_update.go and its tests), so reviving it is
recoverable work, not a rewrite. archie-core-j28m carries the remaining
question -- which process serves the policy and what transport carries the
write -- and blocks the feature bead. The handlers, their error sentinels and
the UpdateConfig/ResetConfig/UpdateRepoField seams on webui.Server are
kept deliberately for it; ConfigView.Editable follows whichever process holds
UpdateConfig, so wiring that one field makes the page editable
(archie-core-ml30).
Implementation belongs to archie-core-8cda.5.4, the cutover that removes the
daemon's own dashboard. Nothing here is built yet.
7. Shared mechanics
The following cross-domain mechanics require exact contracts before dependent packages migrate:
- event-bus delivery and failure semantics;
- policy evaluation API, composition, and precedence;
- configuration candidate preparation, health validation, atomic promotion, observation, and rollback;
- service-specific health, bounded remediation, isolation, and escalation;
- changelog association and grouping.
These shared mechanisms do not acquire ownership of domain meaning. Domains continue to own their commands, events, policies, settings, and consequences.
The Go documentation generator, its output placement, and drift checking are
defined in generated-documentation.md. The VitePress site and its Pages
deployment were removed on 2026-09-12 as an unnecessary build step; docs/ is
repository documentation only. The rendering and publishing surface is an open
decision, and so are the renderer's page templates and any developer commands
or CI sequence that would accompany one. Adapting the generator and implementing
Archie's normalized documentation model remain migration work rather than open
product architecture.
Amended 2026-09-15. internal/infrastructure/servicediscovery/nats
implements the servicediscovery.ServiceRegistry contract (Connect, Register,
Resolve, Watch) over NATS KV and is fully tested, but no production code
constructs it and no config surface exposes it. This is a deliberate deferral,
not an oversight: service-to-service addressing belongs to the runtime and
process boundary work in section 6, which currently pins container addressing
by injecting the daemon's startup NATS URL rather than resolving through a
registry. The scaffold is kept for that work; re-derive it only if the
addressing model changes.
8. Cutover sequence
The final migration plan must order:
- compatibility adapters;
- schema migrations and data backfills;
- any required dual-read or transitional paths;
- domain-by-domain package replacement;
- production wiring changes;
- legacy package removal;
- architecture tests preventing dependency regression;
- focused, integration, race, and full quality gates.
Each legacy package requires objective removal criteria. No compatibility path may become an indefinite second implementation.
Completion criteria
Migration design is complete when:
- every current package has one approved owner and destination;
- every mutable record has one authoritative owner and migration path;
- all external and cross-process contracts have versioned owners;
- existing behaviour and data have explicit parity requirements;
- process boundaries have evidence-backed justification;
- the cutover order preserves a working application;
- legacy deletion criteria and deterministic architecture tests are defined;
- no unresolved decision requires an implementer to invent domain semantics.
Exact Go APIs, SQL statements, and mechanical refactoring steps MAY be finalized during implementation when they do not change these semantics.
Recorded migration position (2026-07-29)
Recovered 2026-08-09 from the pre-migration issue tracker. This section records decisions the maintainer approved that the repository did not otherwise capture.
Completed: internal/infrastructure/eventbus/nats (rebuilt, not relocated);
internal/infrastructure/configuration (loading moved out of internal/config,
which is now types-only and does no I/O); internal/eventbus (broker-neutral
contract); internal/domain/workintake (the first internal/domain/ package,
owning TaskEnvelope, the routing Kind, the label vocabulary, and task
subjects).
DECISION — private input DTO deferred (approved).
configuration.Document.Config is still internal/config.Config rather than the
private per-domain input DTO this document mandates. Building an ~800-line
parallel type tree while every consumer still reads config.Config would mean
two shapes kept in sync by hand, with no consumer for the new one. It is named as
a field so the compromise is visible at each use site, with the deletion
condition recorded in that package's doc.go. Do this with the
internal/config dissolution, not ahead of it.
Agreed next: internal/app/{archied,agentworker}. run() in
cmd/archied/main.go is ~460 lines, against organisation.md's rule that
cmd/* must not contain substantive wiring or act as a service locator. It is
also the last non-infrastructure holder of the NATS SDK, and it is where the
config DTO translation will land, so it unblocks the dissolution above.
Method constraint. Do not write a separate recorded package-review document
per area when the decisions are already dictated by
dependencies-and-contracts.md. That is the ceremony pattern this project
deliberately avoids.
OPEN — [chat.*] config section naming
configuration.md:160 already states the position: ChatConfig holds "separate
channel instance settings... there is no chat-wide settings owner". The config
section name has not followed, so a settings block named for a product surface
owns what the architecture calls channel state.
Two candidates, neither settled: [channel.*] and [messaging.channel.*]. The
second reads as a domain path, and no config section in this repo is currently
named after a domain package, so adopting it sets a precedent for every other
section rather than fixing one name.
Blocked on a maintainer decision, not on evidence. This is a rename with an
operator-visible TOML break, so it should land with the internal/config
dissolution recorded above rather than on its own.