diff --git a/docs/architecture/migration-decisions.md b/docs/architecture/migration-decisions.md index ff8d11ccc..0e2c699ca 100644 --- a/docs/architecture/migration-decisions.md +++ b/docs/architecture/migration-decisions.md @@ -106,6 +106,26 @@ 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`](../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 @@ -276,6 +296,18 @@ 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`](../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. + ### 7. Shared mechanics The following cross-domain mechanics require exact contracts before dependent diff --git a/docs/prds/service-decomposition.md b/docs/prds/service-decomposition.md index 61f44250b..73150b89a 100644 --- a/docs/prds/service-decomposition.md +++ b/docs/prds/service-decomposition.md @@ -9,6 +9,11 @@ `/work/artefacts/archie-core-current-state-archify.html`, `/work/artefacts/archie-core-ideal-state-archify.html` +The Phase 3 UI boundary and configuration decision is ratified in +[`ui-service-boundary.md`](ui-service-boundary.md). That focused document is +the implementation authority for `archie-core-8cda.5.2`; this parent remains +the broader service-distribution proposal. + ## Decision archie-core moves from one Go binary (`archied`) hosting every domain @@ -30,7 +35,7 @@ boundaries. | Service | Contract it owns | Existing code it replaces/wraps | |---|---|---| -| UI Service | thin client only; talks to Gateway's contract | `internal/webui` (SPA hosting stays; API surface becomes a Gateway client, not a peer with direct access) | +| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) | | Gateway Service | routing / turn / session contract | `internal/gateway` | | Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` | | Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` | @@ -80,23 +85,18 @@ either shape. established that Archie's existing domain split already does what AWX's service-decomposition post argues for -- boundaries exist. What doesn't exist is deployability: `internal/webui` is not a passive frontend today. -Verified couplings that this decomposition must eliminate: +The original webui coupling inventory has been re-baselined against the current +checkout. Two earlier couplings are already removed; the remaining UI work is +recorded in [`ui-service-boundary.md`](ui-service-boundary.md). -- Telegram's task-action execution (pause/resume) currently routes through - `internal/webui`'s own HTTP handler in-process - (`chatTaskActorAdapter.ApplyChatTaskAction`, - `internal/app/archied/main.go:224-242`, dispatching into - `internal/webui/server.go:231`'s `handleTaskAction`). Under this PRD, - Messaging Service calls Gateway Service's contract directly -- no HTTP - detour through a UI process. -- `internal/webui/api_chat.go` calls `gateway.SessionStore`, `Router`, and - `TurnHistory` directly (lines 97, 142, 198, 256, 261) instead of through - a narrow interface. Under this PRD, UI Service only ever sees Gateway - Service's `ChatContract`. -- `bootstrap.go:1239` shares the daemon's live `config.Holder` with webui - rather than passing config. Under this PRD, each service owns its own - configuration surface; nothing shares a live in-process struct across a - service boundary because there is no longer a shared process. +- Telegram task actions now call Gateway's `ChatContract` directly through + `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical. +- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct + `SessionStore`, `Router`, and `TurnHistory` access is historical. +- The live `config.Holder` alias remains: `buildDaemon` assigns + `b.web.Cfg = b.d.Cfg`. UI extraction must remove that alias and also assign + owners/contracts for the State Store, channel manager, event/log feeds, + configuration mutations, webhook capture, and other current webui routes. ## Non-goals diff --git a/docs/prds/ui-service-boundary.md b/docs/prds/ui-service-boundary.md new file mode 100644 index 000000000..9bdd395e7 --- /dev/null +++ b/docs/prds/ui-service-boundary.md @@ -0,0 +1,207 @@ +# UI Service boundary and configuration ownership + +**Status:** Ratified (rev. 1) +**Date:** 2026-09-07 +**Beads issue:** `archie-core-8cda.5.1` +**Parent:** [`service-decomposition.md`](service-decomposition.md) +**Prerequisites:** Gateway contract extraction and State Store contract ratification + +This document is the authority for Phase 3 UI Service implementation. It fixes +the process boundary, configuration ownership, client contracts, security +posture, readiness behavior, and migration evidence required by +`archie-core-8cda.5.2` and later UI extraction work. + +## Decision + +The UI Service owns the operator-facing HTTP surface and the compiled SPA. It +serves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and +actions. It does not own conversations, task state, workflow execution, +channel lifecycle, forge access, or the daemon's runtime configuration. + +The UI Service consumes two typed remote capabilities: + +- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC + contract, for chat snapshots, messages, turns, streaming, persona changes, + cancellation, and Gateway task actions. +- State Store's narrow read/write contracts through the versioned State Store + gRPC contract, for task views, events, captures, mappings, bindings, and + configuration data explicitly projected for the dashboard. + +The UI process may compose local adapters during the migration seam, but the +adapter implements the same wire-safe contract as the remote client. The +production extraction cutover removes the in-process adapter in the same +change; a dual-live UI authority is not permitted. + +## Boundary and ownership + +| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive | +|---|---|---|---| +| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles | +| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime | +| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer | +| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation | +| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers | + +Every value crossing the process boundary is a versioned DTO or scalar contract +value. `internal/webui` may retain temporary Go-side adapters while the +migration is in progress, but handlers must map Gateway/State Store values to +UI-owned response types at the HTTP edge. A constructor accepting a concrete +Gateway, State Store, daemon, or `config.Holder` is not an approved final +boundary. + +The existing UI routes remain behaviorally compatible during extraction, +including task actions, SSE event delivery, config views, chat streaming, +capture intake, mappings, bindings, update reporting, and health endpoints. +Compatibility preserves status codes, authentication requirements, redaction, +pagination/limits, event ordering, and failure degradation unless a separately +ratified contract changes them. + +The route families have these target owners. This is the required inventory for +the implementation children; a route without an owner is not eligible for +cutover. + +| Route family | Target owner consumed by UI | Migration status | +|---|---|---| +| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain | +| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains | +| `/api/logs`, `/events` | State/event and log contracts with replay cursor and backpressure rules | local bus/feed only today; contract remains to define | +| `/api/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | local adapter exists; remote UI surface remains to define | +| `/api/config` | daemon/config owner through a versioned admin contract | current app callbacks; shared holder must be removed | +| `/api/channels`, reload, curators, memory, skills, version/update | owning capability contract or an explicitly removed route | owner and failure semantics remain to define | +| `/`, `/healthz`, `/health`, `/health/detailed` | UI HTTP process; readiness consumes per-service health contracts | current HTTP behavior is the compatibility baseline | + +## Configuration ownership + +The UI Service owns only process-local settings: + +- HTTP listen address and read/header/shutdown timeouts; +- UI asset source or build mode; +- UI authentication mode and token reference; +- Gateway endpoint and credential reference; +- State Store endpoint and credential reference; +- readiness endpoint and dependency timeout policy. + +These settings are decoded into a UI-owned input DTO by the UI composition root. +The DTO contains endpoint references and secret references, never resolved +secret values or complete daemon configuration. The UI process resolves its +own credentials and builds its own clients. It does not read or mutate the +daemon's configuration file, runtime overlay, forge credentials, model catalog, +workflow routing, NATS settings, filesystem jail, or agent/container settings. + +The dashboard configuration API is a separate capability. Its secret-free, +allowlisted field projections remain governed by +[`config-schema.md`](config-schema.md). During the transition the daemon may +continue to perform validate-persist-publish for those updates through a +narrow application contract. The UI process must never implement that policy +by holding or mutating a shared `config.Holder`. + +The current daemon's `config.Holder` sharing is migration residue: `buildDaemon` +currently assigns `b.web.Cfg = b.d.Cfg`. It is removed only when the UI has a +configuration read/update contract and tests prove that the daemon and UI no +longer share a mutable holder. + +For Phase 3, configuration ownership is split deliberately. The UI process +owns its listener, browser-auth, asset, dependency-target, and readiness +settings. The daemon/application configuration owner remains authoritative for +the dashboard's `/api/config` read, validation, persistence, overlay, reload, +and audit behavior; the UI calls that owner through a narrow admin contract. +The UI does not become the writer merely because it renders the configuration +page. A future dedicated Configuration Service may replace that owner through +the same contract without changing the UI boundary. + +## Listen, authentication, and readiness + +The extracted UI follows the current web UI security posture: + +- loopback listeners may omit a dashboard token; +- non-loopback listeners require a non-empty token and fail closed when it is + absent; +- `/healthz` and `/health` are unauthenticated liveness probes; +- `/health/detailed` is authenticated and reports dependency readiness; +- capture webhooks retain their separately ratified source authentication and + rate-limit rules; they are not admitted by the dashboard token; +- Gateway and State Store credentials are service-to-service credentials, never + browser-visible dashboard tokens. + +The UI is ready only when its HTTP server is serving and each mandatory remote +contract has passed its bounded readiness check. Each dependency must expose a +versioned health result or health endpoint that the UI can consume; the UI must +not inspect another service's concrete manager, registry, or database. Optional +dashboard sections may remain degraded with the current explicit +`503`/unavailable behavior. A successful liveness response must never imply +dependency readiness. + +## Migration sequence and evidence + +The implementation must complete these gates in order: + +1. Define the UI input DTO, Gateway client surface, State Store client surface, + and UI response DTOs. Add compile-time contract assertions and mapping + tests. No handler may depend on a concrete remote implementation. +2. Make the current in-process web UI consume the same narrow adapters and + preserve the current route, auth, redaction, stream, SSE, and degradation + behavior. Add a composition test proving the selected adapter is the one + used by production wiring. +3. Remove direct `internal/gateway` session/router/runtime access from web UI + handlers. Remove direct `internal/store` implementation access, SQL access, + daemon pointers, and broad runtime callback bundles from the UI constructor. +4. Replace the shared `config.Holder` with the UI-owned configuration DTO and + narrow configuration application contract. Prove reload/update atomicity + remains owned by the configuration/application boundary. +5. Add the standalone UI process and deployment wiring. It must obtain Gateway + and State Store endpoints from its own configuration, authenticate each + client independently, start liveness/readiness endpoints, and shut down + clients and HTTP listeners in bounded order. +6. Run dual-adapter contract tests and an HTTP parity suite covering every + retained route. Test remote failures, missing credentials, malformed DTOs, + stream cancellation, stale State Store data, and readiness degradation. +7. Cut over the supported composition to the UI process. The old in-process + `webui.Run` path is deleted in the same change; no fallback or second HTTP + authority remains. + +The deletion gate is objective: `go list -deps` from the UI process shows no +daemon, SQL/store implementation, workflow, forge, channel, model, or secret +runtime package; production composition contains one UI HTTP listener; and +architecture tests reject `config.Holder`, concrete `*store.Store`, concrete +Gateway runtime types, and direct SQLite imports in the UI service. + +Rollback is a deployment composition change that points the operator at the +last validated UI binary and restores the previous endpoint configuration. It +must not restore a second writer or reintroduce shared-holder mutation. UI +state is either remote contract state or existing durable state owned by its +current service; no UI-specific database migration is introduced by this +boundary decision. + +## Current evidence and known delta + +Current code proves the following migration inputs: + +- `internal/app/archied/bootstrap.go:setupObservability` constructs + `webui.Server` and wires store, channels, events, logs, and config-related + callbacks. +- `internal/app/archied/bootstrap.go:buildDaemon` replaces the initial holder + with `b.d.Cfg`, explicitly sharing the daemon's live configuration. +- `internal/webui/api_chat.go` calls the Gateway contract but still imports + Gateway-owned request/value types; handlers must finish the DTO projection. +- `internal/webui/server.go:Handler` owns the route set, SPA fallback, health + split, capture bypass, and token wrapper. +- `internal/app/archied/state_store.go:RunStateStore` owns the task SQLite + file and serves the State Store gRPC contract; the UI must use that contract + rather than opening the file. +- `internal/app/archied/gateway.go:RunGateway` serves Gateway gRPC and owns + Gateway session persistence; the UI must use `ChatContract` rather than + Gateway internals. + +The current code therefore satisfies the upstream prerequisites but does not +yet satisfy this boundary. This document is the ratified target; the +implementation child must prove each migration gate before claiming Phase 3 +complete. + +## Non-goals and open work + +This ratification does not define a new domain model, move the dashboard's +allowlisted configuration schema, redesign Gateway or State Store RPCs, choose +Kubernetes versus local discovery, or authorize unrelated package migration. +Those decisions remain in their existing authority documents. Any new UI +capability that requires a wider Gateway or State Store surface must amend that +service's contract before implementation.