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
runs 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
org role — Spectral staff). Every surface in the app assumes operator context:
- Operators have unrestricted read access to world-model internals (context schema, configuration block, action registry, rules, provenance chains, generated predicate code, 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 World Agent for authoring + exploration — 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 context schema + configuration block + action registry; author rules with the World Agent generating predicate code; adjust provenance with audit trail. |
| Source material + candidate distillation | Ingest source documents (statute, regulatory guidance, scholarly publication), anchor provenance, run LLM-guided distillation, feed candidates through both gates and into the enshrinement queue. |
| Version publication | Bundle accumulated enshrinements into a world-model version; mint per-action action modules into the module store per ADR-080; generate the World Model Card; coordinate publication. |
| Release notes | Author the narrative and three-category restatement content (configuration / rule / action) that accompanies each published version. Release notes are the restatement mechanism per ADR-026. |
A fifth workflow — platform operations (System Card review, the review queue, override-pattern signal triage, cross-domain observability) — has detailed surfaces separate from this subtree’s page layout but shares the same architectural placement and boundary rules.
The app’s shell is a persistent left rail with three global destinations — Workbench
(the home orientation surface), Rulesets, and Review queue — plus a topbar with the
breadcrumb and search. Opening a ruleset lands in its workspace, a five-tab surface in
workflow order: Rules · Sources · Review · Publish · Feedback (source-material extraction
folds into Sources; version history folds into Publish). The World Agent
is not a tab — it is a global dock, a right-side slide-over summoned with ⌘J (or the
topbar button) and a ⌘K command palette, overlaying whatever surface the operator is on.
API / UI parity principle
Section titled “API / UI parity principle”Every workflow in the Operations app is API-first: the UI is a thin client over the same HTTP API that any other consumer would call. This is a load-bearing principle — it keeps the API the single governed entry point, keeps workflows testable through the API independent of the UI, and leaves room for direct API consumers without a privileged UI-only path.
Parity rules:
- Every write path is an API call first. The UI is a thin client over the HTTP API. There is no UI-only mutation that a direct API consumer cannot perform.
- Every read path is queryable through the API. The UI’s data fetches and direct API consumers all hit the same endpoints with the same auth + RBAC.
- Every state change emits an event. When the operator approves a candidate, downstream readers reflect the approval through the event substrate without observing the UI action directly.
- The governed enshrinement pipeline is single-source. There is no “UI-only” enshrinement path. Human sign-off gates every promotion, regardless of where the candidate originated.
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 separately-deployable
surface, 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 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-052 D4). 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. Composing public APIs is the same discipline the UI follows as an API client.
| 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 |
| 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 agent surfaces
Section titled “Relationship to the agent surfaces”The World Agent is accessible inside the
Operations app — operators reach it through the global dock as a code-generation and
exploration surface — but lives in spectral.worlds and is summoned through API calls.
The full agent topology (the World Agent plus test-agent reference implementations), its boundaries, and its interaction patterns are documented in Agent Architecture. This page covers where the Operations app surfaces the World Agent; that page covers what the agent is.
Pages in this subtree
Section titled “Pages in this subtree”- Authoring — world-model authoring surface
- Distillation — source material + candidate distillation pipeline
- Publication — version publication workflow
- Release notes — release-notes authoring