ADR-030: Authority version as metadata-only across the context boundary

Status: Accepted (2026-04-20)

Context

The three-context topology (ADR-001) makes spectral.platform the scanning / evaluation / optimization context and spectral.worlds the world-model-authority context, with spectral.core as the contractual seam. World models evolve across versions; a scan run at time t1 may be attributed to version 0.1.0 and a scan run at time t2 to version 0.2.0 even within the same workspace.

During 0.3.0 planning, a tempting line of framing crept into several epics and walkthroughs: treat world-model version transitions as events between contexts, with Spectral reacting — supervisor resets on version bump, dashboards rendering hard boundaries between versions, trend aggregations filtered by version, changeset acceptance windows paused during publication. The framing is plausible on first read and wrong on reflection: it makes spectral.platform version-aware, which re-couples the contexts through a state machine rather than through the spectral.core type surface.

The clean framing is simpler: the EvalSet (with its attribution envelope) is the sole data carrier between worlds and spectral, and the authority version on that envelope is metadata, not a synchronization signal. Worlds decides which version is current for its own reasoning; Spectral runs against whatever EvalSet Worlds hands it and records the attribution. Nothing in Spectral’s state machine changes when Worlds publishes a new version.

This ADR makes that framing explicit so subsequent refinement does not drift back into the coupled model.

Decision

World-model authority version is metadata carried on the EvalSet attribution envelope. It is not an inter-context synchronization signal and it does not drive any Spectral-side state transitions.

Concretely:

1. Interface invariant. The attributed EvalSet (stimuli + ground truth + attribution envelope including world_model_id and world_model_version) is the sole data carrier between packages/worlds and packages/spectral. No “version-transition” event type exists in packages/core.

2. Spectral is version-unaware. packages/spectral has no supervisor reset on version bump, no cross-version aggregation filter, no changeset-acceptance pause on version publication, no “version boundary flag” in internal data structures. Spectral stores the version value the EvalSet carries and surfaces it on artifacts (AgentPerformanceCard); it does not branch on version identity.

3. Worlds-side version awareness stays internal. packages/worlds knows what the current published version is, filters incoming world signals against that concept, and emits EvalSets keyed to whichever version it is currently authoritative for. This awareness does not cross the context boundary — it manifests only as the value on the attribution envelope.

4. Dashboard / trend visualization uses markers, not boundaries. Where version transitions are visible to customers (trend charts, scan history), they appear as Sentry-style overlay markers on continuous data, not as hard dividers that reset axes or partition aggregates. Correlation between a version change and a behavioral shift is human-driven interpretation, not a mechanical filter.

5. WorldModelCard review at publication is worlds-internal. Publication triggers WorldModelCard generation inside packages/worlds. The operator reviews it in the Operations app. packages/spectral is not in the publication critical path.

Alternatives considered

• Version-transition as a first-class spectral.core event (worldmodel.version.published consumed by Spectral). Rejected: no Spectral-side state changes on the event, so subscribing to it has no operational use. The AgentPerformanceCard already carries the version via attribution; a separate event is redundant.
• Supervisor reset on version bump — the supervisor’s mode classification (ACTIVE / PLATEAU / FRONTIER / NO_DATA) would reset when the world model’s version increments. Rejected: the supervisor reasons about agent behavior across scans; behavioral continuity does not break because the domain standard got more precise. Cross-version trend is legitimate signal, not noise to be flushed.
• Cross-version aggregation filter — trend charts and metrics would be automatically partitioned by version. Rejected: hides signal. A customer whose agent’s score dropped at a version bump wants to see the drop, not an aggregation that splits it into two disjoint series.
• Hard boundary in changeset acceptance windows — pause acceptance during publication, resume after. Rejected: publication is a worlds-internal event; there is no mechanical reason the scan pipeline must pause.

Consequences

• The EvaluationAuthorityRef (producer-typed payload per ADR-065 D2; consumer-side ACL parse per D4) carrying world_model_id + world_model_version is the full contract surface for authority identity. No additional events or state-sync protocols are needed.
• Epic descriptions that previously implied version-transition coupling — supervisor reset, boundary dividers on dashboards, aggregation splits — are audited and corrected as part of spike SPEC-269 closure.
• The dashboard’s trend visualization uses a version-marker overlay pattern, not a partition-by-version pattern. The marker is clickable and shows the version metadata.
• The supervisor’s mode classification considers scan history as continuous; version transitions appear only as attribution metadata in the per-scan records.
• WorldAgent’s internal version awareness (which version is current, which signals apply to which version) stays private to spectral.worlds. It does not manifest as a spectral.core type.
• Future work that wants to correlate version changes with behavior is a visualization / narrative concern, not a data-layer concern. Human operators and customers draw the correlation from the overlay markers; the data layer does not pre-compute the causal link.

Decided in spike SPEC-269 (S12). The Codex page at /system-design/world-model-system/version-attribution/ carries the readable reference for contributors; this ADR is the source of record.