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. Workspace ||--o{ Observation — memory rows are read via ObservationRepo for compounding/retrieval/decay, never through a Workspace load. ChangeSet ||--o{ InterventionLog — intervention logs are read via InterventionLogRepo for supervisor-driven transfer learning, never through a ChangeSet 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

Workspace

The customer’s tenant boundary in spectral.platform. A workspace is the unit of isolation for all platform records (RLS-enforced per ADR-033) and the unit of optimization. Every change set, scan, and agent performance card is workspace-scoped. A workspace is bound to one published world-model version via an authority reference; it never reads world-model rule content directly.

WorkspaceAgent

A customer-facing agent under optimization within a workspace. Carries its prompt template, hyperparameters, and dependency edges to other workspace agents. Optimization runs target a single workspace agent at a time, but dependency edges are how multi-agent system effects (one agent’s change affecting another) are reasoned about.

ChangeSet

The unit of optimization output. A change set bundles proposed modifications — prompt edits, parameter shifts, rule-specific guidance — that emerged from one scan, attaches an agent performance card, and records its lifecycle through proposed → accepted → superseded (or validated / rejected). Every change set carries an EvaluationAuthorityRef stamped at scan-completion time: which world-model version it was evaluated against. Per ADR-026, that reference is permanent. The change set’s authority claim does not retroactively shift when the world model evolves.

EvaluationFramework

The customer-side rubric for a workspace. Encodes the dimensions the customer cares about, the scoring weights, and the parameterization that shapes evaluation toward the customer’s domain priorities. The framework composes with the world-model authority during scoring; the two-authority evaluation discipline keeps customer-rubric outputs and world-model outputs structurally separate.

Sample / SampleSet

Customer-curated input traces. A sample is one input the customer has labelled or annotated; a sample set is a versioned collection. Sample sets feed into change-set evaluation as a customer-curated complement to the world-model-grounded eval set.

WorldModel

The worlds-context primitive: a domain standard, encoded as a graph of enshrined rules grounded in source materials, curated through human-gated evolution, and applied identically across every customer in the same domain. Each published version is the unit of authority per ADR-026; prior versions remain queryable indefinitely.

Rule

A single enforceable expectation in a world model. Rules carry provenance (the source-material excerpt the rule distils), a tier (Authoritative for publication-direct, Curated for cross-referenced interpretation), and edges to other rules (depends_on, conflicts_with, qualifies). The full evolution from candidate to enshrined rule is documented in Evolution Loop.

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 — gateway-enforced; observations are value-added reasoning about records, not records themselves — is the load-bearing invariant. See Memory System.

State machines

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

Change set — proposed → accepted | rejected; accepted change sets later transition to superseded or validated as subsequent scans build on them.
Sample — captured → labelled → in-set | excluded; excluded is reversible.
Agent task — queued → running → completed | failed; failed tasks may be retried into a new task with a parent reference.
Agent approval — pending → approved | rejected | timed-out; approved approvals are immutable.
Conversation — open → closed; closed conversations may be reopened by a new message.

The Rule lifecycle (candidate → enshrined → retired) is documented as part of the Evolution Loop because it cannot be understood without the surrounding governance machinery.