Glossary
A reference for terms used across the Codex, ADRs, and source code. Where a concept has a canonical Codex page, the entry links there; this glossary is a fast lookup, not a substitute for the design pages.
If a term is missing here, it is either inline-defined where used or doctrinally subsumed by an entry below — open an issue if you hit something that should be added.
ACL pattern
Section titled “ACL pattern”Anti-Corruption Layer. The consumer-side translation step that converts a producer’s typed event payload into a local model the consumer reasons over. Applied at every event consumer between contexts to prevent producer types from leaking into consumer code. See Contract Surfaces.
Action
Section titled “Action”The unit of decision-time routing within a domain. A caller’s request names the action it is
about to take (wire_transfer.release, vendor.onboard); Spectral routes to the deployed
action module for (org, domain, action) and evaluates that action’s rules
against the context. A rule associates to one or more actions through the many-to-many
action–rule registry (per ADR-104). See
Primitives — Action.
Action module
Section titled “Action module”The deployable artifact per (org, domain, action, world_model_version). Bundles composition
root, embedded context-schema subset, rule files, and manifest. See
Primitives — Action module.
Action registry
Section titled “Action registry”The set of registered actions in a world-model version. Each entry holds the action’s rules directly and optionally an aggregation mode. See Primitives — Action registry.
Aggregation mode
Section titled “Aggregation mode”The action-level metadata controlling how an action’s rules combine into a decision outcome.
Today only winner_takes_all is implemented; vote_of_n and weighted_sum_threshold are
reserved-but-shaped. T1 rules are an unconditional hard-floor override
regardless of mode.
apps/workers
Section titled “apps/workers”The framework-layer composition seam where the World Agent runs its LangGraph orchestrator. Tool dependencies that cross between contexts wire via DI here; the agent’s own code stays inside a single context. See Architecture.
applies_when
Section titled “applies_when”An optional context-only predicate on a rule that gates whether the rule participates in matching for a given request. Used for conditional activation and multi-stage classification; DRYs gating logic that would otherwise duplicate across rule predicates. See Primitives — Rule.
authenticated_caller
Section titled “authenticated_caller”The system_generated context attribute Spectral resolves at request entry from the signed
auth token. Carries principal, acting_for (from the RFC 8693 act claim), and roles.
Caller cannot forge; auth shape per ADR-087.
Authority
Section titled “Authority”The externally-grounded source of truth a world model claims to mirror (statute, regulatory guidance, scholarly publication). Authority is structural, not organizational — what makes a world model trusted is methodological disclosure, not a stamp.
Audit chain
Section titled “Audit chain”The deployment-scoped record of every decision served per ADR-076 D3. Each entry captures the full decision trace and backs the System Card. See Primitives — Audit chain.
Bilateral contract test
Section titled “Bilateral contract test”A paired test in tests/contracts/ that imports both the producer’s typed event payload and
the consumer’s local model and pins the wire shape via a round-trip check plus a syrupy
snapshot. The only directory exempt from inter-context import discipline. See
Contract Surfaces.
Bridge tool
Section titled “Bridge tool”A framework-layer tool authored under apps/* that wraps a callee context’s
OHS Protocol and wires it into a caller agent’s tool list via DI in
apps/workers. See Architecture.
Canonical input ontology
Section titled “Canonical input ontology”An action’s persisted, authoritative input contract — one entry per real quantity (name, type,
required, enum values, description, provenance). It is what /actions publishes and deploy
sources input_schema.json from; the union of the deploying rules’ declared inputs is kept only as
a drift check, never a fallback source. Established at publish by vocabulary reconciliation,
which converges divergent rule input names onto one canonical name per quantity. Snapshotted into
the World Model Card so a published version’s input contract is frozen with its
action set. See Primitives — Canonical input ontology
and ADR-107.
Composition root
Section titled “Composition root”The deterministic codegen entry-point per action module. Validates supplied context against
the embedded schema, runs derivations for computed attributes, evaluates each rule’s
applies_when and main predicate in severity order, applies suppression chains, runs
aggregation, and constructs the work frame. Not an LLM; pure deterministic code.
Configuration block
Section titled “Configuration block”The stable per-world-model-version values that derivations and rule code-generation consume. Used by derivations at composition-root entry; baked into predicate code at code-gen time. Not exposed to predicates at runtime — predicates see only typed context. A configuration change is a version bump that regenerates dependent rule code.
Conformity gate
Section titled “Conformity gate”The acceptance check at enshrinement: a rule candidate is enshrined only if it conforms to the world model’s structural and authoritative invariants. Paired with the implementation-readiness gate.
ContentClass
Section titled “ContentClass”The data-classification taxonomy on every LLM call: PLATFORM (customer content),
OPERATIONS (Spectral-operated reasoning), or SYNTHETIC (test-agent-generated content).
Drives payload-stripping discipline at the OTel Collector. See
Observability Stack.
Context schema
Section titled “Context schema”The typed declaration of every attribute a domain’s decisions consume, with each attribute
carrying a source (supplied / system_generated / computed). The authoritative input
contract for /decide calls in this domain. See
Primitives — Context schema.
Control plane
Section titled “Control plane”One of Spectral’s two operator surfaces: the customer-facing Customer Dashboard and the internal-only Operations app, each with its own audience and authority direction. See How Spectral Works.
context
Section titled “context”One of the three code boundaries enforced by the architecture validator: spectral.core
(substrate), spectral.worlds (world-modeling domain), spectral.platform (customer-facing
platform). worlds and platform do not import each other; both depend on core. In
steady-state docs we refer to contexts by name (worlds, platform, core); “context”
appears as an architectural noun only when introducing the three or in doctrine discussion.
See Architecture and
ADR-031.
Decision
Section titled “Decision”The outcome of a single /decide invocation: { status, work_frame, decision_metadata }
returned to the caller plus a structured record written to the audit chain. Deterministic
over (world_model_version, supplied_context, system_generated_at_entry). See
Primitives — Decision.
Decision API
Section titled “Decision API”The HTTP surface at POST /decide per ADR-077
D1 and its MCP equivalent per ADR-088. Action
discoverability is exposed via OpenAPI per ADR-089.
Decision-server
Section titled “Decision-server”The platform pillar’s runtime: api-pod replicas (per ADR-076 D1) that handle the decision API surface, load and cache action modules from the module store, and execute them. Execution-layer safety contract in ADR-083.
Deployment generation
Section titled “Deployment generation”The integer stamp on every outbox row and NOTIFY message that gates which worker generation
processes which event. Allocated atomically per deploy via
INSERT INTO core.deployments RETURNING generation and exposed as SPECTRAL_GENERATION to
each service. See Deployment topology.
Domain
Section titled “Domain”The action-grouping container inside an org per ADR-086
D2 — a coherent subject area whose actions share context vocabulary, configuration, and an
authoring authority. Each domain has its own world-model version chain, its own action
registry, its own deployed action modules, and its own System Card. Tenancy enforcement keys
on domain_id per ADR-086 D6. Customer-facing roles (admin / contributor / observer) are
domain-scoped per ADR-086 D5.
EventEnvelope
Section titled “EventEnvelope”The substrate envelope from spectral.core.events.envelope that wraps every published event
with metadata (id, occurred_at, generation, correlation). Distinct from the producer-typed
Published Payload it carries. See
Event Substrate.
GREEN / GREEN-SKIP / YELLOW / RED
Section titled “GREEN / GREEN-SKIP / YELLOW / RED”The four-state status taxonomy of a decision. GREEN — execute. GREEN-SKIP — skip
allowed (audit-visible no-op). YELLOW — review path (gather evidence, prepare review
packet, route to human owner). RED — block. See
Decision Execution / Status taxonomy
for the full four-state breakdown with agent behavior per status.
Implementation-readiness gate
Section titled “Implementation-readiness gate”One of the two gates between draft and enshrined rule. Enforced at publish (per
ADR-108): verifies the generated
predicate code is behaviorally complete against an independent behavioral spec — discriminating
tests materialized from the rule’s natural-language text and generated-to-pass — with a
dead-input gate, declared == read codegen binding, and captured code provenance. Paired with
the conformity gate.
JWKS-local validation
Section titled “JWKS-local validation”JWT verification done in-process against the Supabase JWKS endpoint — signature, expiry, audience, and issuer checks — paired with a mirror-based revocation check. The default auth posture across FastAPI services and frontend Pages Functions. See Access Control.
Module store
Section titled “Module store”The content-addressed store keyed by (org, domain, action, version) that holds enshrined
action modules. The decision-server fetches modules from the store on first request, verifies
the content hash and operator-approval marker per ADR-080
D2 + D3, caches the loaded module, and runs it on subsequent requests. The store is the
unidirectional handoff from the worlds-side authoring path to the platform-side execution
path.
OHS Protocol
Section titled “OHS Protocol”Open-Host Service Protocol. The callee-owned typed Protocol in <context>.contracts.protocols.*
that defines what a callee context publishes to other contexts as a callable interface.
Implementations live in the callee’s application layer; bridge tools wire these into caller
agents via DI in apps/workers. See
ADR-065 D3.
Operations app
Section titled “Operations app”The internal-only operator console at apps/operations, served from ops.runspectral.com,
where Spectral staff author, distill, and publish the world models that produce the deployed
action modules. Distinct from the Operations team (the audience). See
Operations App.
Operations team
Section titled “Operations team”The Spectral-staff audience role for the Operations app — the humans who author rules, enshrine them, and publish world-model versions. Distinct from the Operations app (the surface).
The customer-identity boundary at the top of the tenancy hierarchy per ADR-086
D1. Owns billing identity, owner-level access, and the set of domains a customer operates.
Tokens, billing, and operator-level roles (owner / operations) key on org_id.
Override-pattern signal
Section titled “Override-pattern signal”A platform-side signal aggregating customer-initiated review-requests and noteworthy marks from the Customer Dashboard. Operators read these signals alongside other evidence during evolution-loop work. The customer-reality → operator-authority feedback path; structured signal flow, not synchronous coupling.
Pattern A
Section titled “Pattern A”The TanStack Start auth posture for staff frontends: server-side session, scope checks against
OPERATIONS_SCOPES, and JWKS-local validation of the Supabase JWT.
Used by apps/operations and the docs-codex Pages Function. See Frontend Architecture.
Predicate
Section titled “Predicate”The pure deterministic function inside a rule. Takes a typed DecisionContext, returns
{ matched: bool, reason?: string, trace?: object }. No I/O, no mutation, no nondeterminism.
Runtime-safety constraints enforced by codegen-time AST analysis per ADR-083
D2 and by the runtime app sandbox per ADR-083 D3.
Problem Space
Section titled “Problem Space”A sub-area inside a domain (e.g., dependents, filing status, deductions inside US tax prep). Operators decompose a domain into problem spaces during world-model authoring. See Problem Spaces.
Provenance — two-dimensional
Section titled “Provenance — two-dimensional”The provenance shape on every rule: an authoritative source dimension (statute, regulatory guidance, scholarly publication — preserved across restatement) and a code dimension (the generated predicate’s lineage to the natural-language rule it was generated from — regenerated when the natural-language form or configuration dependencies change).
Provenance Tier
Section titled “Provenance Tier”The source-strength taxonomy on every world-model rule. Six tiers, strongest to weakest:
Authoritative (canonical sources like statute and regulatory publication), Curated
(operator-validated derivations), Distilled (LLM-derived from authoritative sources with
operator review), Researched (research-backed but weaker than distilled authority), Observed
(signals from production decisions), and Assistant-drafted (assistant proposal awaiting stronger
source grounding). The claim that holds uniformly across tiers is “established and governed before
evaluating your system” — not “derived independently of AI.”
Published Payload
Section titled “Published Payload”The producer-owned typed event payload module in <context>.contracts.events.*. Sole source
of truth for the wire shape of an event between contexts; auto-generates Codex documentation
and is consumed via consumer-side ACL. See
ADR-065 D2.
PurposeKey
Section titled “PurposeKey”An enum identifying the purpose of an LLM call (code_generation, applies_when_generation,
distillation, reasoning, world_agent, etc.). Drives quota accounting and content-class
resolution at the composition root. See LLM Platform.
Records vs memory
Section titled “Records vs memory”The doctrine that canonical activity records (audit-chain entries, override-pattern signals, distillation runs) are produced by system functions; agent memory holds the agent’s reasoning about those records. Records hold what the system did; memory holds how the agent reasoned about it. See Memory System.
Restatement
Section titled “Restatement”The mechanism by which world-model versions name what changed and why between versions, per ADR-026. Extended to three categories: configuration restatement, rule restatement, action restatement. Carries the authoritative-provenance dimension forward across version transitions.
A single enshrined claim within a world model, assigned to the action(s) it serves. Carries metadata
(id, tier, outcome, description, category, suppresses, dual provenance), an
optional applies_when filter, a pure deterministic predicate, typed declared inputs
(declared == read), and a behavioral spec with materialized tests the predicate must pass.
Lifecycle: candidate → enshrined → retired; enshrined means accepted into the catalog, while
publish/deploy decide which enshrined rules are exposed to callers. See
Primitives — Rule and
World Model.
Rule Candidate
Section titled “Rule Candidate”A proposed rule under review, not yet enshrined. Surfaced via the Evolution Loop from operator authoring, distillation runs, and override-pattern signals. See Evolution Loop.
Status
Section titled “Status”The audit-grade headline of a decision — one of GREEN / GREEN-SKIP / YELLOW / RED. One of four values, easy to scan in volume; bound by the work frame for the richer behavior contract.
System Card
Section titled “System Card”The deployment-scoped operational record per ADR-082
D3: per-(org, domain) totals, p50/p95/p99 latency, four-state status distribution,
methodology disclosure, version history. The customer-facing view of operational health,
surfaced through the Customer Dashboard.
T1 / T2 / T3 memory (interaction / session / persistent)
Section titled “T1 / T2 / T3 memory (interaction / session / persistent)”The three-tier agent memory model. T1 = interaction-scoped (single LLM turn); T2 = session-scoped (single conversation or operator session); T3 = persistent (across sessions; anchored to the agent’s scope tuple per ADR-058). See Memory System. Not to be confused with T1 / T2 / T3 rule tier.
T1 / T2 / T3 rule tier
Section titled “T1 / T2 / T3 rule tier”The severity classification of rules within an action. T1 — unconditional hard-floor override (any T1 match wins outright). T2 — standard rules; combine according to aggregation mode. T3 — soft signal; combine according to aggregation mode. The T1-unsuppressible property is preserved across all current and reserved aggregation modes.
ToolError taxonomy
Section titled “ToolError taxonomy”The four-class agent-tool error model — ToolUserError, ToolPolicyError,
ToolTransientError, ToolTerminalError — that surfaces tool failures to the LLM rather
than retry middleware, letting the model decide retry / modify / surface / abandon. See
Agent Tool Invocation.
Vocabulary reconciliation
Section titled “Vocabulary reconciliation”The publish-boundary phase that converges an action’s rules’ divergent input names onto its
canonical input ontology — so two rules naming one real quantity
differently (rule A gross_income, rule B total_income) resolve to a single published input
rather than two. It runs holistically per declared action over the action’s assigned enshrined
rules, before the deterministic mint: an LLM proposes the canonical names and a per-rule rename map
only (the one irreducible semantic judgment); types, required, enum values, and provenance are
derived deterministically under that map. Deterministic realignment then rewrites each impacted
rule’s predicate, applies_when, declared inputs, and behavioral spec together, re-gated by the
rule’s behavioral suite (the consistency gate). The naming call is cassette-pinned and memoized — a
steady-state republish makes no LLM call. A name any published version exposed is conserved (the
freeze boundary is the published input, not the enshrined rule); low-confidence merges, would-be
published-input rewrites, and multi-action collisions fail loud as a surfaced, operator-arbitrated
rename preview before anything is applied. See Publication
and ADR-107.
Work frame
Section titled “Work frame”The structured contract returned alongside decision status, bounding the agent’s behavior
after receipt. Fields: mode, next_action, allowed_actions, forbidden_actions,
required_output, missing_evidence, next_human_owner. Names explicit anti-patterns by
construction (llm_policy_decision: false; forbidden_actions includes "reinterpret_policy"
and "override_spectral"). See Primitives — Work frame.
World Agent
Section titled “World Agent”The internal-only LLM agent in spectral.worlds. Owns the world-model authoring path:
generates predicate code from natural-language rules, materializes tests from a behavioral spec
extracted independently of the predicate, proposes provenance citations, runs the
implementation-readiness gate. Per ADR-081
D5 the World Agent also serves a post-release customer-facing role: an
explain-this-decision chat affordance keyed to the customer’s (org_id, domain_id) world.
The World Agent never enshrines — enshrinement is the operator’s gate.
World Model
Section titled “World Model”The Spectral-managed authoring authority for a domain, scoped to (org_id, domain_id) and
versioned. Each version declares a context schema, a
configuration block, and an action registry. The
unit of authority per ADR-026. See
World Model.
World Model version
Section titled “World Model version”An immutable snapshot of a world model. Versions are the unit of authority — decisions are
deterministic over (world_model_version, supplied_context, system_generated_at_entry).
Prior versions remain queryable indefinitely; the active version is the routing default for a
domain, with optional per-request world_model_version pinning per ADR-077 D2.
WorldModelCard
Section titled “WorldModelCard”The version-scoped methodology disclosure published with each world-model version per ADR-082 D2: scope, sources, decision log, authority basis, two-dimensional provenance summary. Operator-authored, not auto-generated. See System Card.