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.
338 lines
22 KiB
Markdown
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.
|