Versions, and what may change
Two artifacts were versioned before there was a framework, because a wire format cannot be versioned retroactively.
Minors round-trip: a newer peer reads an older frame and an older peer reads a newer one.
A partial translation that half-works is the one failure nobody could debug in production.
In plain terms
Two wire formats are versioned on their own: the template IR and the Warp frame protocol. A minor version travels in both directions. A major refuses the connection rather than guessing at a translation.
Two artifacts were versioned before there was a framework, because a wire format and a compiler output cannot be versioned retroactively: adding a version field later means every client already in the field is unversioned.
| Artifact | Id | Version | Reference implementation |
|---|---|---|---|
| Template IR | weft.template-ir/2 | 2.6.0 | packages/ir |
| Payloads | weft.payload/2 | 2.6.0 | packages/ir |
| Warp frames | weft.warp/1 | 1.8.0 | packages/warp |
Those three numbers are read from the constants this build stamps on a document, not typed here. The summary table in spec/VERSIONING.md was one minor behind the source when this page was written, which is the argument for generating it made by the thing it happened to.
What each component means
| Change | What a reader must do | What it costs you |
|---|---|---|
| Patch | Nothing. No format change. | Nothing. |
| Minor | Accept it. Additive fields, and a reader must round-trip what it does not understand. | Nothing — an older reader keeps working, and says forward when asked how. |
| Major | Refuse it: E_MAJOR_UNSUPPORTED. | A hard wire break. The id changes too, so the two formats cannot be confused. |
The name is part of the contract: weft.template-ir/2 and weft.template-ir/3 are different formats, not two versions of one. A document whose spec name a reader does not know is E_SPEC_MISMATCH before any version comparison happens.
Migrations are registered, and they go one way
A stored document on an older minor is migrated up by a registered function, and the registry is checked: a gap in the chain is E_MIGRATION_MISSING, a cycle is E_MIGRATION_CYCLE, and a migration pointing down is E_MIGRATION_DIRECTION. None of that is discovered while serving a request.