Operations App
The Operations app (apps/operations) is Spectral’s internal operator surface. It is where
the Spectral operations team authors and publishes world models, triages platform health, and
collaborates with the Operations Agent on world-model-lifecycle work. It is not
customer-facing at any tier.
Audience
Section titled “Audience”The Operations app has exactly one audience: the Spectral operations team (the operations
account role — Spectral staff). Every surface in the app assumes operator context:
- Operators have unrestricted read access to world-model internals (rules, provenance chains, EvalSet corpora, World Agent memory) — posture customers never have.
- Operators are the only humans permitted to enshrine rule candidates, publish world-model versions, or retire rules.
- Operators can invoke the Operations Agent for task-oriented work and the World Agent for exploration — both kept internal, per Agent Architecture.
Customers do not see the Operations app, do not have credentials for it, and do not consume its output directly. When operator work produces a customer-facing artifact (a published WorldModelCard, a release note), the artifact reaches customers through the platform’s normal publication path — the dashboard, the API, or a customer-email delivery — not through the Operations app.
The Operations app is the surface for four distinct operator workflows:
| Workflow | Purpose |
|---|---|
| World-model authoring | Create, version, and retire world models; author rules; manage rule relationships; adjust provenance tier with audit trail. |
| Source material + candidate distillation | Ingest source documents (IRS publications, statute excerpts, regulatory guidance), anchor provenance, run LLM-guided distillation, feed candidates into the enshrinement queue. |
| Version publication | Bundle accumulated enshrined rules into a world-model version; mint EvaluationAuthorityRef; generate WorldModelCard; coordinate publication. |
| Release notes | Author the narrative and correction/restatement content that accompanies each published version (release notes are the restatement mechanism per ADR-026). |
A fifth workflow — platform operations (world-model health dashboard, enshrinement review queue, cross-world observability) — has detailed surfaces separate from this subtree’s page layout but shares the same architectural placement and boundary rules.
Dual-occupant UX principle — API / UI parity
Section titled “Dual-occupant UX principle — API / UI parity”Every workflow in the Operations app is usable by either the human operator (through the UI) or the Operations Agent (through API calls) with full parity. This is a load-bearing principle: it is what lets the Ops Agent and a human operator collaborate on the same workflow without either becoming a second-class occupant.
Parity rules:
- Every write path is an API call first. The UI is a thin client over the same HTTP API that the Ops Agent calls. There is no UI-only mutation that the agent cannot perform.
- Every read path is queryable by both. The UI’s data fetches, the agent’s tool calls, and direct API consumers all hit the same endpoints with the same auth + RBAC.
- Every state change emits an event. When the human operator approves a candidate in the UI, the agent’s subsequent read reflects the approval without the agent having observed the UI action directly. When the agent proposes a candidate, the human’s UI view updates the same way.
- The governed enshrinement pipeline is single-source. There is no “UI-only” or “agent-only” enshrinement path. Human sign-off gates every promotion, regardless of who proposed the candidate. Agents (including the Ops Agent) propose and draft; the human operator enshrines.
Dual-occupant flows are an explicit test category with coverage for every meaningful surface — see Testing.
Architectural placement — a separate deployable, not a context
Section titled “Architectural placement — a separate deployable, not a context”apps/operations is a separate deployable rather than a fourth context — it doesn’t own a
ubiquitous language, business rules, or domain data. Its vocabulary is operational UX over the
existing domains; every business rule it exercises lives in spectral.worlds or
spectral.platform; its persistence is operator-state, not domain data. The deployable
composes public APIs from worlds and platform, adds its own UI and agent-orchestration layer,
and ships as its own TanStack Start project (per
ADR-047) — its own Render service
(spectral-ops-staging / spectral-ops-production), reachable at ops.runspectral.com.
The three claims in detail:
- No new ubiquitous language. The vocabulary (operator, review queue, publication draft) is operational UX over the existing domain languages, not a new domain.
- No business rules. Every rule the Operations app exercises (enshrinement gates, candidate
validity, publication invariants) lives in
spectral.worldsorspectral.platform. - Operator-state only. Persistence is in-flight tasks, agent conversation memory, and UI-ephemeral selections — not domain data.
See Architecture for the three-context topology that the Operations app composes over.
Deployment topology
Section titled “Deployment topology”Operations runs as its own TanStack Start project deployed independently to ops.runspectral.com,
with its own auth boundary — Pattern A JWKS-local middleware (per
ADR-047 D2 and
ADR-039 D4a) validates the Supabase
JWT in-process and gates every route on the operations scope. The customer dashboard
(apps/dashboard) is a separate Vite build at app.runspectral.com; the Codex docs site is a
Cloudflare Pages deployment at codex.runspectral.com that shares the operations auth gate via a
Pages Function port of the same Pattern A check (per
ADR-047 D4 +
ADR-048 D3). The cross-subdomain session cookie is scoped at
the runspectral.com eTLD+1 so a single login session is readable from all three surfaces (per
ADR-046 D8).
Context-boundary discipline
Section titled “Context-boundary discipline”The Operations app consumes public APIs from worlds and platform. It does not import their internals.
| Allowed | Forbidden |
|---|---|
HTTP calls to apps/api routes | Direct imports from src/spectral/worlds/domain or src/spectral/worlds/application |
Subscribing to producer-owned typed event payloads in <context>.contracts.events.* (per ADR-065 D2) | Direct imports from src/spectral/platform/domain or src/spectral/platform/application |
Importing kernel substrate types from spectral.core (EventEnvelope, retry primitives, auth context, retention shape) | Cross-importing infrastructure adapters from worlds or platform |
Importing callee-owned OHS Protocols from <context>.contracts.protocols.* (per ADR-065 D3) when composing bridge tools at the framework layer | Treating <context>.contracts.* as “core types” — they are producer-owned contract surfaces, not kernel residue |
| Composing UI state over API-returned DTOs | Reaching into another context’s internal persistence |
The architecture validator enforces these rules with STRICT=True. A PR that adds
from spectral.worlds.domain.rules import Rule (or any other domain import that crosses contexts) to
apps/operations fails CI.
Why this is non-negotiable:
- Authority stays single-source. If the Operations app could import worlds internals, it could bypass the enshrinement gate. Forcing HTTP means every action passes through the context’s governed entry point.
- Operations app evolves independently. UI refactors, agent-tool changes, and UX iterations do not require rebuilds or coordinated releases of worlds or platform.
- Multi-tenant RLS stays simple. All customer-data access flows through the authenticated API path, where RLS policies are uniformly applied. The Operations app does not get a privileged bypass.
See spectral.core governance ADR-065 for the
complementary discipline on the shared-contract side.
Relationship to the other agent surfaces
Section titled “Relationship to the other agent surfaces”The Operations app hosts the Operations Agent. The World Agent
is also accessible inside the app — operators can chat with it as a read-oriented exploration
surface — but lives in spectral.worlds and is summoned through API calls, not composed into the
Ops Agent.
The full three-agent topology (Spectral Agent, World Agent, Operations Agent), their boundaries, and their interaction patterns are documented in Agent Architecture. This page covers where the Operations app hosts those agents; that page covers what the agents are.
Pages in this subtree
Section titled “Pages in this subtree”- Operations Agent — the task-oriented agent that lives in this app
- Authoring — world-model authoring surface
- Distillation — source material + candidate distillation pipeline
- Publication — version publication workflow
- Release notes — release-notes authoring