How Spectral Works

Compile business logic into executable agent behavior. Spectral turns operational judgment into versioned world models and deterministic decision modules that agents call before they act.

A caller invokes POST /decide (or the MCP equivalent per ADR-088) naming an action and supplying request context. Spectral routes to the deployed decision module for (org, domain, action, world_model_version), evaluates that module’s rules against the context, and returns a binding { status, work_frame, decision_metadata }. The decision path is pure code execution — no LLM is invoked, no network I/O beyond the request itself, and the outcome is deterministic over the inputs.

Spectral is built around two pillars that operate as separate authorities.

The internal world-model system is the authoring authority. Spectral-built, internally curated, scoped to each customer’s domain. It produces the deterministic decision modules — rules in natural language compile via world-agent code generation and gated enshrinement to deployable artifacts. It owns: the world model (context schema, configuration, action registry), the rules and their dual provenance, the conformity gate, restatement, the World Model Card.

The customer-facing platform is the decision host. It hosts and routes decision-module execution: the decision API, the MCP surface, auth and identity resolution, the audit chain, observability, billing, and the deployment lifecycle of decision modules. The System Card lives here (deployment-scoped).

The world-model system produces deployable decision modules through world-agent code generation; the platform runs those modules at decision time.

Why Spectral decides, not executes

Spectral takes a different approach than evaluation tooling. The world model is a separate, Spectral-built artifact — not an evaluation reference, but an executable substrate. Operational rules compile to deterministic decision modules that run outside the LLM’s reasoning loop. Agents call Spectral before they act; the response is binding, deterministic, and audit-trail-grade. Other tools instrument or evaluate agents after the fact. Spectral makes the binding decision before the agent does.

The structural property the two-pillar split buys is that the world model decides independently of the customer’s agent — the agent cannot prompt past, reason around, or quietly reinterpret it. The decision module is code the agent calls; the work frame is the explicit decision the agent is expected to operate within (mode, next_action, allowed_actions, forbidden_actions, required_output, missing_evidence, next_human_owner). LLM policy decision is named as a forbidden action by construction.

Posture

Spectral is the decision boundary in the agent’s request path. Before an agent acts, the caller invokes Spectral via API or MCP; Spectral returns an authoritative decision — a work frame the agent is expected to honor. Agency stays with the customer’s agent, which consults Spectral and acts on the decision; authority and proof stay with Spectral, which decides deterministically and records the outcome. The decision path does not invoke an LLM — generated code runs against the request and produces the outcome. Spectral’s authoring path (world-agent code generation, eval validation, enshrinement) is asynchronous to the decision path; only deployed, deterministic code modules see live traffic.

How a decision happens

Every /decide invocation flows through five phases — authorization and request validation, action mapping and module load, context establishment, predicate execution per rule, aggregation and response. The phases are sequential, bounded, and uniform across all decision modules; cost variance comes from per-phase content, not from phase structure.

Decision Execution is the full phase-by-phase breakdown. The short version: the platform pillar resolves auth and captures request_time / request_id / authenticated_caller; the decision-server routes to the cached module for (org, domain, action, world_model_version); the composition root validates supplied context, runs derivations for computed attributes, evaluates each rule’s applies_when filter and main predicate in severity order, applies suppression chains, runs aggregation per the action’s mode, and constructs the response.

The composition root is deterministic codegen — not an LLM. The LLM’s job stays narrowly scoped to per-rule predicate generation at authoring time. At runtime, predicates are pure functions of typed context; they cannot do I/O, cannot mutate state, cannot read configuration directly. The runtime-safety constraint is enforced by codegen-time AST analysis per ADR-083 D2 and by the runtime app sandbox per ADR-083 D3. Configuration values that derivations or rules need (thresholds, business-hour definitions, holiday calendars) are baked into the generated predicate code at code-gen time, so a configuration change is a world-model version bump that regenerates dependent code — not a runtime read.

How a world model gets built

The authoring path is where the world-model system earns its authority. Operators draft rules in natural language alongside the world agent, which generates the predicate code, suggests inline tests, and proposes provenance citations. Two gates guard the path from draft rule to accepted catalog rule and later published module: an implementation-readiness gate that verifies the generated code matches the natural-language intent (tests pass; semantics agree), and a conformity gate that verifies the rule against the domain’s authoritative sources (statute, regulatory guidance, scholarly publication).

The world-model system owns the gates. Operators run them; enshrinement is theirs alone — neither the world agent nor any other agent can enshrine. Once both gates pass and an operator enshrines, the rule enters the working catalog. A later publish/deploy boundary builds the action module, writes it to the module store with its embedded schema, version metadata, code provenance, and signature, and makes it loadable by the decision path. Module integrity is checked at load time per ADR-080 D2 + D3 (content hash + operator-approval check) before the platform decision-server caches it for execution.

The Operations subtree covers each authoring workflow in detail: authoring, source-material ingestion and distillation, enshrinement, and publication.

The two control planes

Customers and operators each have their own control plane. Both surfaces are read by their respective audiences and never cross.

Customer side — the dashboard at app.runspectral.com is the customer’s structured view of what’s running and what decisions have been made. v0 is primarily read-only inspection: a live feed of recent decisions filterable by status, per-decision detail panels with three-source request context and rule evaluation traces, the version-scoped World Model, the action registry, and the deployment-scoped System Card. Two lightweight customer-to-operator interaction primitives layer on top: a customer can flag a decision for operator review, or mark a decision noteworthy. The dashboard does not let customers approve modules, edit rules, or override decisions — decisions are binding per ADR-077. See Customer Dashboard for v0 scope and the post-release World Agent chat affordance.

Operator side — the Operations app is the operational control plane where Spectral staff author and evolve the world-model system. Authoring, eval validation, enshrinement (every promotion is a governed human gate), and publication all happen here. The audience asymmetry is load-bearing per ADR-047: the customer-facing platform is per-(org, domain)-isolated and consumption-shaped; the operational control plane is single-tenant and authoring-shaped, running on Spectral-staff identities under an operations scope that never crosses into customer sessions. That separation is what lets the world-model system remain the authority customers cite.

How the two pillars connect

The pillars communicate through three narrow, explicit seams — the module store, the audit chain, and override-pattern signals. None of the three lets the platform reach into the world-model system’s authoring data; none lets the world-model system reach into a customer’s deployed modules.

1. The module store. When the world-model system publishes an enshrined action module, it writes the artifact to a content-addressed module store keyed by (org, domain, action, version) with a deterministic content hash. The platform decision-server fetches modules from the store at first request, verifies the content hash and operator-approval marker per ADR-080 D2 + D3, caches the loaded module, and runs it. The store is the unidirectional handoff from authoring to execution.
2. The audit chain. Every decision the platform serves writes a structured audit record (request context, matched rules, suppression chain, aggregation outcome, predicate traces, errored predicates, work frame, response) to the audit chain per ADR-076 D3. The audit chain backs the deployment-scoped System Card and is the substrate for customer-initiated review requests routing back to the operator triage queue.
3. Override-pattern signals. When a customer marks decisions noteworthy or flags decisions for operator review, the platform aggregates these as override-pattern signals that operators read alongside other evidence during evolution-loop work. The customer-reality → operator-authority feedback path is structured signal flow, not synchronous coupling.

Architecture covers the codebase topology (spectral.platform / spectral.worlds / spectral.core) that backs this. Contract Surfaces is the canonical reference for how the two pillars exchange data without coupling — producer-owned typed event payloads and callee-owned protocols rather than direct imports across contexts.

Data handling

Spectral sees only what the caller sends in the request body — the supplied context attributes the world model’s schema declares — plus what Spectral captures at request entry (request_time, request_id, the resolved authenticated_caller from the signed auth token). The customer’s runtime data stays in the customer’s system unless they include it as supplied context. The signed auth token format and the RFC 8693 act claim that carries delegation are spec’d in ADR-087. Encryption and access posture: see Security Boundaries and Access Control.

What’s next

• Operator walkthrough — an operator bootstraps the first world model from nothing through a published action module on the operational control plane.
• Decision Execution — the five-phase breakdown of every /decide invocation.
• Customer Dashboard — v0 inspection surface and post-release World Agent chat affordance.

For the technical architecture in detail, see Architecture, the World Model System subtree, and the Platform subtree.