Files
archie/docs/prds/ui-service-boundary.md
T
sam ac7ffe343a 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

338 lines
22 KiB
Markdown

# 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`](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`](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.Server`s 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.