Skip to content
Spectral Codex
GitHub
Decisions

ADR-017: Event-driven signal path from Spectral to Worlds

Status: Accepted (2026-04-20)

Source: migrated from planning/swms-decisions.md ADR-026 as part of SPEC-270.

Context

spectral.platform executes optimization scans against evaluation frameworks generated by spectral.worlds. The results of those scans are valuable signals for world model evolution. However, spectral.platform cannot import from spectral.worlds directly (per ADR-001), and the World Agent must never read platform memory directly. A communication path is required that respects context boundaries and the governed evolution process of the world model.

Operational semantics of that path — delivery guarantees, ordering, schema ownership, failure handling, and back-pressure — were under-specified in the initial version of this ADR and are resolved here.

Decision

Communication from packages/spectral to packages/worlds is exclusively event-driven. When spectral executes a scan against an EvaluationFramework with world model attribution, it raises domain events targeted at the world and version identified in the framework’s attribution envelope. These events carry structured observations: deviation signals, performance patterns, scan outcomes. packages/worlds receives these events and routes them through the governed evolution process — the same enshrinement pipeline that all rule candidates pass through. worlds decides what to do with the signals; spectral does not prescribe how they are interpreted. There is no synchronous call between contexts at runtime.

Operational semantics

  • Delivery: at-least-once with idempotent handlers. The observation signal path is statistically robust rather than event-exact. Missed observations are tolerable; duplicate observations are absorbed by the conformity gate at the promotion boundary.
  • Ordering: best-effort is sufficient. The observation signal path does not require strict ordering. The conformity gate and human sign-off are the integrity controls, not event order.
  • Schema ownership: superseded by ADR-065 D2. Event schemas live in <producer>.contracts.events.* (the producer context owns the wire shape); the original “shared contractual types in spectral.core” framing is replaced. The producer/consumer attribution for the signal path itself stands: spectral.platform is the producer, spectral.worlds is the consumer.
  • Dead-letter handling: failed events are routed to a dead-letter queue owned by packages/spectral as the producer. packages/worlds does not reach back across the context boundary to recover a failed event.
  • Back-pressure: packages/worlds signals capacity constraints to the event infrastructure, never directly to packages/spectral. Infrastructure throttles ingestion; spectral does not change behavior based on worlds’ internal state. The context boundary stays clean.

Consequences

  • spectral.platform raises events; spectral.worlds governs interpretation. The signal path is one-directional at the context level.
  • Events are targeted at a specific world and version via the attribution envelope on the EvaluationFramework. spectral does not need to know what world model it is attributed to beyond the identifier in the envelope.
  • The World Agent is never exposed to Spectral memory or Spectral execution context. It is an internal system component, not a customer-facing surface at launch.
  • The compounding flywheel is preserved through this event path rather than through shared memory (per ADR-018).
  • World model evolution triggered by Spectral events is subject to the full enshrinement governance process. Events are signals, not directives.
  • Idempotency requirements are explicit on the worlds consumer side. Handlers must tolerate duplicate delivery without producing duplicate rule candidates or duplicate observations in the enshrinement pipeline.
  • Dead-letter queue ownership on the spectral side aligns failure recovery with producer responsibility and keeps worlds free of spectral-side operational concerns.
  • Back-pressure via infrastructure rather than context-to-context signaling preserves the one-directional signal path and prevents spectral behavior from becoming coupled to worlds’ capacity state.