Infrastructure · Safety
ExpandContractMigration
Change a shared format by adding the new form beside the old, moving every consumer, then removing the old
Definition
Mechanism
To change an interface, schema, storage layout or message format shared by producers and consumers that deploy independently, the change runs in three phases with a gate between each. Expand: the new form is introduced beside the old so every deployed reader and writer still works; writers may write both. Migrate: consumers move to the new form and stored data is backfilled, with CompatibilityCheck run for every inventoried producer-consumer pair in each direction in which the pair communicates. Contract: the old form is removed only after an inventory of its remaining consumers, including old versions, caches, copies of the interface and in-flight messages, comes back empty. Each phase records the conditions under which it can be rolled back. Reusing an existing field or name with a new meaning is a contraction of the old meaning and an expansion of the new one in a single step, and its readers are found as in MeaningChangeSweep.
Invariants
- At every point in the transition, every inventoried producer-consumer pair can interoperate in each direction in which it communicates.
- The old form is removed only after an inventory of its remaining consumers comes back empty, with the inventory's scope recorded.
- A change of meaning under an unchanged name or position is treated as a removal plus an addition, never as compatible.
Risks
Failure modes
Forgotten consumer
an offline, embedded or third-party reader, such as an indexer or a hand-copied interface, still depends on the old form when it is removed.
Dual-write divergence
the two forms drift because some writes reach only one of them.
Single-step change
expansion and contraction ship together, so there is never a state where both forms work.
Permanent expansion
contraction never happens and both forms are maintained indefinitely.
Silent repurpose
a field keeps its name and type while its meaning changes, which shape-level compatibility checks cannot detect.
Relationships
Builds on
References
Schema compatibility verification
Mind
When a value's meaning changes, find and recheck every reader of the old meaning
Nothing in this library builds on this pattern yet.