Module compat 

Update compatibility classifier — the safety interlock at the heart of the update model (see the update PRD and docs/design/operator-mailbox.md).

Pure and free of I/O: given the running build’s Fingerprint and an available release’s fingerprint, Fingerprint::classify sorts the change into one of three tiers, and StagedBundle::evaluate enforces the refuse-incompatible interlock for config-as-data bundles.

The fingerprint

A Fingerprint captures only what decides whether one build can talk to another and read another’s data — four axes:

• the Protobuf/wire descriptor version (wire_version),
• the event-log schema version (eventlog_schema),
• the CRD apiVersion the controller reconciles (crd_api_version),
• a hash over the tool catalog (tool_catalog_hash) — the stand-in for the whole config-as-data surface (prompts, persona defs, model routing).

The first three are format axes: a difference in any of them means two builds cannot interoperate without a coordinated move. The fourth is the config-as-data axis: it moves without a binary change at all.

Classification

Comparing the running fingerprint against an available one:

• Compatibility::Cold — a format axis moved (wire, event log, or CRD). Peers cannot interoperate across the change; it needs a coordinated redeploy of the whole fleet.
• Compatibility::Hot — the format axes match and only the config-as-data surface moved. The running binary reloads the new catalog; no restart.
• Compatibility::Warm — the fingerprint is otherwise identical, so the only thing that moved is binary internals. A wire- and schema-compatible binary swap, picked up on restart.

Binary releases and config-as-data bundles are separate delivery channels (the Expo split of native app-store builds versus over-the-air JS bundles): a warm/cold binary roll never simultaneously bumps the catalog hash, and a hot config push never bumps a format axis. The classifier reads the resulting fingerprint delta, so each artifact lands in exactly one tier.

The interlock

A StagedBundle is a config-as-data payload plus the RuntimeTarget it was authored against — the analog of an Expo update’s runtimeVersion. The running binary applies the bundle only if its own runtime matches the target exactly; otherwise StagedBundle::evaluate returns Compatibility::Incompatible and the bundle is refused rather than applied against a runtime it was never built for.

Structs

Fingerprint

The compatibility fingerprint of a build: the four axes that decide whether two builds interoperate and can read one another’s data.

RuntimeTarget

The format-axis subset of a Fingerprint.

StagedBundle

A staged config-as-data bundle: a hot payload (new tool catalog, and with it prompts / persona defs / model routing) plus the RuntimeTarget it was authored against.

Enums

Compatibility

How an available release or staged bundle relates to the running build.

Incompatibility

The format axis on which a running runtime fails to satisfy a staged bundle’s target.