weft
ir 2.6.0 · warp 1.8.0

Versions, and what may change

Two artifacts were versioned before there was a framework, because a wire format cannot be versioned retroactively.

minor
warp 1.7
→
warp 1.8
→
round-trips
major
ir 1.x
→
ir 2.x
→
refused, both versions named
The version a document carries is the constant the build stamped on it, so what a page claims and what the code does cannot drift apart.
✓ Valid A minor version, either direction

Minors round-trip: a newer peer reads an older frame and an older peer reads a newer one.

✕ Refused a peer speaking a different major
what you wrote→the version is a constant the build stamped on the document→refused, both versions named

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.

ArtifactIdVersionReference implementation
Template IRweft.template-ir/22.6.0packages/ir
Payloadsweft.payload/22.6.0packages/ir
Warp framesweft.warp/11.8.0packages/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

ChangeWhat a reader must doWhat it costs you
PatchNothing. No format change.Nothing.
MinorAccept 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.
MajorRefuse 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.