Reference

Domain Model

This page is the primitives view of spectral.<context>.domain.* — what the entities are, why they exist, and how they relate. For field-level shape and module paths, the code under src/spectral/<context>/domain/ is the source of truth; this page anchors the conceptual model the code embodies.

For the inter-context architecture that holds these primitives together, see Architecture and Contract Surfaces. For the worlds-side authoring model and its full evolution loop, see World Model System.

Entity relationship overview

Two FK edges deserve explicit mention because they are not aggregate-traversable. Domain ||--o{ Observation — agent-memory rows are read via ObservationRepo for compounding/retrieval/decay, never through a Domain load. Decision ||--o{ OverridePatternSignal — customer-initiated review-request and noteworthy-mark signals are read via the platform-side signal aggregator for operator triage, never through a Decision load. Treating either as traversable would couple unrelated lifecycles. The three-tier memory shape behind the Observation FK is documented in ADR-058.

Primary primitives

Org

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.

Domain

The action-grouping container 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. The customer-facing roles (admin / contributor / observer) are scoped per ADR-086 D5; tenancy enforcement keys on domain_id per ADR-086 D6.

WorldModelVersion

The unit of authority per ADR-026. Each version is an immutable snapshot of one domain’s authoring state: context schema, configuration block, action registry, and the rules under each action. Versions never retroactively change; prior versions remain queryable indefinitely.

ContextSchema

The typed declaration of every attribute a domain’s decisions can consume, with each attribute carrying a source (supplied / system_generated / computed). The schema is the authoritative input contract for /decide calls in this domain. See Primitives — Context schema.

ConfigurationBlock

Stable values per world-model version that derivations consume at composition-root entry and that rule code-generation bakes into predicates at authoring time. Not exposed to predicates at runtime; configuration changes are version bumps that regenerate dependent code.

Action

The unit of decision-time routing within a domain. Each action carries its own rules directly (no separate “rule-set” primitive) and optionally an aggregation_mode controlling how rules combine. A rule associates to one or more actions through the many-to-many action–rule registry (per ADR-104 D2); a rule assigned to no action does not deploy. Each action also carries a persisted canonical input ontology (worlds.actions.ontology) — one named, typed input per real quantity — established at publish by vocabulary reconciliation and the authority for the action’s published input schema (per ADR-107).

Rule

One enforceable expectation, assigned to the action(s) it serves. Each rule is one file inside the action’s module, exporting metadata (id, tier, outcome, description, category, suppresses, dual provenance), an optional applies_when context-only filter, a pure deterministic predicate, and inline tests. The full lifecycle (candidate → enshrined → retired) is governed by the Evolution Loop.

Provenance (two-dimensional)

Each rule carries two-dimensional provenance: an authoritative source dimension (statute, regulatory guidance, scholarly publication) and a code dimension (the generated predicate’s lineage to the natural-language rule it was generated from). The authoritative dimension carries through restatement; the code dimension is regenerated when the rule’s natural-language form or its configuration dependencies change.

ActionModule

The deployable artifact for (org, domain, action, world_model_version) produced by the authoring path and stored content-addressed in the module store. Carries composition root, embedded context-schema subset, rule files, and a manifest with module version, code provenance, embedded schema digest, and signature. Integrity is verified at load time per ADR-080 D2 + D3.

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. Every decision is deterministic over (world_model_version, supplied_context, system_generated_at_entry). Response shape per ADR-077 D3.

AuditChainEntry

The per-decision audit record persisted in the platform pillar per ADR-076 D3. Captures the full decision trace (request context, matched rules, suppression chain, aggregation outcome, predicate traces, errored predicates, work frame, response). Backs the System Card and the customer-initiated review-request flow.

SystemCard

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.

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.

Observation

The memory primitive — agent reasoning compounded across runs. Observations are append-only, anchored to the agent that produced them, and tiered (interaction / session / persistent) per ADR-058. The records-vs-memory boundary — observations are value-added reasoning about records, not records themselves — is the load-bearing invariant. See Memory System.

Operator-side workflow entities

The entities operators interact with on the Operations app during world-model authoring, distillation, publication, and release-notes work.

SourceMaterial

A registered authoritative-tier source document (statute, regulatory guidance, scholarly publication) that distillation runs against and rules cite. Operators ingest source materials into the inventory with anchored provenance metadata; the REFERENCED ⇌ ACTIVE retention transition holds rows cited by enshrined rules indefinitely. Append-only — metadata corrections produce a new row plus retire of the prior; retirement is a state transition, not a delete.

DistillationRun

An operator-submitted run of the LLM-guided distillation pipeline against selected source materials. Carries lifecycle state (status, started_at, completed_at, failure_reason_code) and the produced RuleCandidate rows. Per-source extraction state surfaces partial output and explicit errors; failures surface a coded failure_reason_code (retained on STRIP_PAYLOAD) plus free-text detail (stripped on disposal).

DistillationRunOutput

The junction row linking a DistillationRun to each RuleCandidate it produced and the SourceMaterial rows that contributed to the candidate’s extraction. End-to-end provenance trail: run → source materials → candidate.

RuleCandidate

A proposed rule under review, not yet enshrined. Surfaced from three signal sources (operator authoring, distillation runs, override-pattern signal aggregation) per Evolution Loop. Carries the proposed metadata, the World Agent’s generated predicate code (when authoring is past the implementation-readiness gate), proposed provenance citations, and the supporting evidence summary. Lifecycle: candidate → enshrined → retired; request-revision/send-back keeps it in candidate, while discard/reject retires it.

ApprovalDecision

The operator-action audit row recording an enshrinement-gate decision (approve / reject / request-revision) on a RuleCandidate. Operator-scoped (app.user_id) with no domain RLS, keyed on (candidate_id, operator_id, decided_at) with rationale captured verbatim. Records — not memory. Append-only.

WorldAuthoringAudit

The operator-action audit row for every authoring action on the worlds-side surfaces — world-model lifecycle, rule authoring (when not gated by ApprovalDecision), source-material ingest + retire, distillation-run submission, release-notes create + revise, publication. Operator-scoped (app.user_id) with no domain RLS, keyed on (operator_id, target_type, target_id, action, occurred_at, correlation_id). Discriminators by target_type and action. The correlation_id column doubles as the idempotency anchor for the originating mutate API.

ReleaseNotes

The version-scoped restatement artifact published with each world-model version per ADR-026. Operator-authored narrative + structured correction-record content. Lifecycle follows the parent WorldModel version: mutable while parent is in draft; locked at publication. No independent review-gate.

ReleaseNotesCorrection

The structured per-correction child entity under ReleaseNotes: corrected rule reference, prior version restated, restatement narrative. Carries the three-category restatement discipline (configuration restatement, rule restatement, action restatement) per ADR-026.

State machines

A handful of entities drive lifecycle state through transitions worth understanding at the primitives level. The five with the most consequence:

Rule — candidate → enshrined → retired. Enshrinement is operator sign-off on the natural-language rule intent; generated predicate code, behavioral tests, and input declarations are machine-checked artifacts around that intent. Publication/deployment are separate version boundaries that gather assigned enshrined rules; retirement carries through restatement.
ActionModule — built → reviewed → enshrined → published → loaded. Published modules are immutable; subsequent versions ship as new module IDs keyed on a new world-model version.
Decision — terminal one-shot; no state machine. Status (GREEN / GREEN-SKIP / YELLOW / RED) is the audit-grade headline.
Agent task — queued → running → completed | failed; failed tasks may be retried into a new task with a parent reference.
Conversation — open → closed; closed conversations may be reopened by a new message.