Schema Evolution & Compatibility

Schemas change over a machine's life; compatibility rules let old and new events coexist without breaking replay or in-flight procedures.

L4 · Orchestration — its place in the stack (left, click any layer) and its internal components (right). Telemetry rises; control descends.

Long-lived machines, changing schemas

The breeder and burner control stacks will evolve for years. Event schemas gain fields, diagnostics are added, and models are versioned. Without discipline, a schema change would break replay of old data or crash consumers still reading old formats. Compatibility rules in the schema registry keep every version readable and every consumer resilient.

Compatibility classes

Change	Backward	Forward	Allowed in place
add optional field	yes	yes	yes
add required field	no	yes	no (new version)
remove field	yes	no	no (new version)
change type/units	no	no	never (new topic)

Rules that hold the line

Additive, optional changes only for in-place evolution; anything breaking gets a new major version or topic.
Units and types are immutable for a given schema name; a burner plug-field value never silently changes units.
Every event stamps its schema_version so decoders pick the exact schema that wrote it.

Replay across versions

Because old events carry their schema version, replay years later decodes them with their original schema and re-runs the procedure version that was in force. A 2030 breeder shot remains replayable after later stack upgrades. This is why breaking changes must never mutate an existing schema in place; doing so would corrupt the historical record.

python

decoder = registry.get(event.schema, event.schema_version)  # exact original
record  = decoder.decode(event.payload)
# new consumers read old records via backward-compatible readers

Command schemas are strictest

Command schemas change only through the same two-person process as safety rules, because a command's meaning must never drift. A command also references the envelope and rules versions it was checked against, so a schema or policy upgrade cannot retroactively validate a stale command (see authorization).