Files
archie/docs/prds/ui-service-boundary.md
T
sam ff00de9519 docs(eda): split the expression decision out and cut the playbook PRD to its design
The playbook engine PRD had grown to 972 lines against CLAUDE.md's one-page
bar, because four documents were living in it.

The expression decision was the worst of it: an H2 nested inside a numbered
list item, 270 lines with twelve H3s and its own Status and Date fields. That
broke the outline and gave the document a second, non-canonical status. It is
now docs/prds/playbook-expression-syntax.md, named flat and linked by a Parent
field the way module-position.md already relates to this epic. The parent
keeps the decision and a pointer.

Repetition, against the state-each-fact-once rule: reject-at-load was stated
ten times, the plugin engine rule nine, producer-only seven. The producer-only
argument ran 32 lines and closed by restating itself; it is eight lines and
stated once. One heading read "confirmed non-issue (stated once)" above the
third statement of the point.

Open question 3 was closed by module-position.md and still listed here as
open. The section holding four decisions and one note is no longer called
"Open questions", and the note is a standing constraint, which is what it is.

Also removed: two list summaries written before their lists, ten dated
attributions, two progress claims, three orphan line citations, and the
undefined { Call: ... } notation.

Five findings in other PRDs came from tightening the guard, not from this
split.
2026-09-22 01:07:05 +10:00

22 KiB

UI Service boundary and configuration ownership

Status: Approved Revision: 1 Date: 2026-09-07 Beads issue: archie-core-8cda.5.1 Parent: 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
/events State Store EventsSince, polled by one UI-process pump feeding Server.Broadcast RESOLVED (archie-core-za9f): see migration-decisions, "Dashboard live event delivery". No new RPC; replay cursor and drop-recovery are the existing since watermark in sse.go
/api/logs, /api/logs/stream daemon diagnostic feed, host-local unresolved: logging.Feed is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see /api/tasks/* above
/api/tasks/{id}/logs, /api/tasks/{id}/logs/download State Store task-log read contract (TaskLogStore: ReadTaskLog + StreamTaskLogContent), read by the UI process from the service that owns the state directory RESOLVED (archie-core-iaqx): the UI process composes TaskLogStore from its own State Store client and serves the attempt log as JSON (found distinguishes "no log for this attempt" from "this process cannot read logs") and as a Content-Disposition attachment named task-<id>-attempt-<n>.log. The daemon's in-process registry is wired as the server-side reader in internal/app/archied/state_store.go only (staterpc.Deps.TaskLogs), so no process opens another process's log files
/api/captures, /api/mappings, /api/bindings State Store contracts, with webhook verification owned by Work Intake/Messaging RESOLVED (cutover, archie-core-8cda.5.4): the UI process composes CaptureStore/MappingStore/BindingStore and mounts the captureintake.Receiver from its own State Store client; the daemon's binding-dispatch loop keeps consuming captures from the same store
/api/config (read) daemon-published ConfigView snapshot, read over the State Store contract RESOLVED (archie-core-ymut): see migration-decisions, "Dashboard configuration page"
/api/config (write), /api/config/reset, /api/config/repos/* a configuration write contract; the daemon stays the policy owner DESCOPED for Phase 3 (archie-core-ymut), NOT abandoned: 503 in the UI process, SPA hides the controls, editing is config.toml plus reload. Dashboard editing is a tracked feature (archie-core-1786637498420-327) and its transport is archie-core-j28m; the handlers and their func-field seams on webui.Server are kept for it
/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. 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 daemon's config.Holder sharing was migration residue: buildDaemon assigned b.web.Cfg = b.d.Cfg. Removed by archie-core-ml30 -- the field no longer exists, and boot owns the single Holder the daemon reads through.

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 does not become the writer merely because it renders the configuration page.

Amended 2026-09-11 by archie-core-ml30: the daemon's config.Holder sharing is gone. webui.Server has no holder field, so the sharing this paragraph describes cannot be reintroduced by wiring; the daemon owns one Holder and publishes a rendered projection.

There is no single narrow admin contract carrying both the read and the write (archie-core-ymut). The read crosses as a daemon-published ConfigView snapshot over the State Store contract, and the write is descoped for Phase 3 rather than contracted, on the reasoning recorded in migration-decisions under "Dashboard configuration page". A future dedicated Configuration Service is the natural owner of a write contract, and designing one is that feature's work, not this migration's.

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.

Phase 3 gates

Every gate below is proven by test, not by inspection:

Gate Evidence
Deletion cmd/archie-ui/architecture_test.go re-runs go list -deps on every task check and fails on any banned package, checked in both directions against its two exceptions
Composition internal/app/archieui/TestComposeUIServerHoldsNoDaemonState fails on a concrete *store.Store or a Gateway that is not the gRPC client. The holder clause it also carried is enforced by the type: webui.Server has no config.Holder field (archie-core-ml30)
End-to-end cmd/archie-ui/main_test.go builds the binary and drives it over HTTP against a live Gateway and State Store
No dual authority The dashboard HTTP listener is internal/app/archieui/run.go only; the daemon's two http.Servers are its own health endpoint and the forge webhook receiver

Acceptance criterion 1 was amended at the close of Phase 3 to name the UI process rather than the internal/webui package, because the daemon still held a holder inside its own process to render the published ConfigView snapshot. archie-core-ml30 removed that residue, so the criterion holds in its original form again: internal/webui receives no holder in any process.

Deletion gate: SATISFIED (archie-core-8cda.5.6, rev. 2)

The objective gate now holds. go list -deps ./cmd/archie-ui links zero banned packages: no modernc.org/sqlite, no internal/store, internal/gateway, internal/channels, internal/memory, internal/secret, internal/agentexec, internal/tools, internal/skill, internal/yaegiutil, internal/domain/curator, or the workflow engine (internal/domain/workflow). How the runtime handles were severed, each at the producer:

  • Store contracts moved to internal/domain/storecontract (producer-owned read contracts, state-store-contract rev. 2d); internal/store keeps aliases.
  • Chat contracts moved to internal/domain/messaging; internal/gateway keeps aliases. The UI process holds ChatContract, SessionStore, turn and stream types without linking the gateway runtime or its SQLite session store.
  • Webui-owned views replaced concrete runtime handles on webui.Server: channel lifecycle via internal/channels/status, memory via a MemoryStatus interface, curators via a CuratorStatus interface, and the skill catalogue via a SkillCatalog interface — each supplied by a daemon-side adapter at bootstrap, each degrading to an empty page when unwired.
  • config.SecretRef moved into internal/config (it is config vocabulary); internal/secret keeps an alias and resolves through Registry.Resolve.
  • Task vocabulary (Task, Store, Definition, status constants) split into internal/domain/workflow/task; the pipeline engine stays in package workflow, which keeps aliases. The UI process links the vocabulary only.

The gate is enforced, not just measured. cmd/archie-ui/architecture_test.go re-runs go list -deps on every task check and fails on any package in a banned category, so a single reference to a type sitting beside a runtime cannot quietly relink it. Its exception list (internal/channels/status, internal/domain/workflow/task) is checked in both directions: an exception the UI stops needing is reported, so the allowlist cannot decay into an open prefix. internal/app/archieui's TestComposeUIServerHoldsNoDaemonState covers the composition clauses, failing on a non-nil config.Holder, a concrete *store.Store, or a Gateway that is not the gRPC client.

One piece of residue remained visible at the close of Phase 3: webui.Server still declared Cfg *config.Holder, because the daemon kept a webui.Server as the renderer that built the published ConfigView snapshot. That cleanup landed as archie-core-ml30. webui.Server no longer has a configuration holder, provenance store, reload-status callback or override-listing callback: the projection is built by webui.BuildConfigView, a pure function the configuration owner calls, and the daemon assembles its input from its own state (boot.configViewInput). Readiness reads the daemon's own Holder, channel manager and chat contract, and the health registry it produces is a daemon field rather than a field on a server the daemon never serves.

ConfigView.Editable moved with it. It describes the rendering process's own write path, so handleConfig sets it from Server.UpdateConfig rather than any process baking it into the document. A future configuration write contract (archie-core-j28m) makes the page editable by wiring that one field.

Real-process evidence (archie-core-8cda.5.6)

cmd/archie-ui/main_test.go builds the binary and runs it against a State Store and a Gateway on loopback gRPC, then drives it over HTTP: liveness without a token, 401 for an API request without one, the ?t= exchange into an HttpOnly cookie, task rows with their forge links, the embedded SPA and its assets, a chat stream relayed frame by frame from the Gateway, an operator task action crossing to the Gateway (and refused without the CSRF header), capture intake accepted unauthenticated, the ratified degradations, readiness dropping when the State Store dies while liveness holds, and a clean SIGTERM.

Two dashboard values degraded here because the published projection did not carry them: chat.show_tool_calls (the chat page never expanded tool calls) and the /api/setup checklist (the panel was omitted rather than rendered). Both are closed by archie-core-ml30: ConfigView gained a chat section carrying show_tool_calls, the operator name, and whether any chat channel is configured, and both surfaces now read the projection rather than a live holder. The end-to-end suite drives the real binary and streams a turn, so the show_tool_calls assertion is made on the frames a browser receives.

The checklist stays. The question raised when it was republished -- is a read-only setup report wanted in a process that cannot apply the setup it reports? -- resolves in favour of keeping it, because the panel never promised to apply anything. It renders each step as a title, a detail and a done mark with no control behind it, so it answers "what is this deployment missing?" rather than "fix it here", and the page that CAN act on it (the Configuration page) is where an operator goes next, in the daemon's own words. Removing it would delete the one surface that distinguishes a fresh deployment from a finished one for no gain, since the values it reads already cross the boundary in ConfigView and the read path costs the daemon nothing. The write path remains descoped (see /api/config (write) in the route table): the checklist reports configuration, it does not change it.

archie-core-ml30 published the channel flag from two of the three chat front-ends, so an email-only deployment read as configured on /api/channels and unconfigured on the checklist at the same time (GitHub #821). Both now derive from config.ChatConfig.FrontEnds, the single definition of a configured front-end, and a test pins the two surfaces to the same answer.

A third value degraded for the same reason and is closed by archie-core-pv6t: in a deployment configuring [[identities]] the projection carried the default identity's forge alone, so task rows withheld their links rather than pointing every row at the wrong forge. ConfigView now also publishes each identity's forge coordinates and the repositories it owns (identities), which is what resolving a task to its owning forge needs — coordinates and repository names only, never a token. The end-to-end suite drives the real binary against a multi-identity projection and asserts each row's issue link is built from the forge that owns it.

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.