How to Read the Model Changelog

The changelog at /models/changelog is the platform's promise made inspectable: model behavior changes only with a version bump, and every bump explains itself in public.

Integrators watch the changelog for one reason: it is the complete record of when any model's behavior moved and why. The page is generated from the changelog sections of the model specs themselves — the same documents the engine is verified against — so the changelog cannot drift from the specs any more than the specs can drift from the engine. This piece is the reading guide: what an entry contains, what the version arithmetic means, and how a real entry reads when you know what to look for.

The version arithmetic

Model versions follow the semantic pattern integrators already know, applied to computational behavior. A patch-level change moves no numeric output — but it is not automatically inert: several patch entries removed dead inputs and are flagged BREAKING, because the API rejects unknown fields and a caller still sending them fails. The version number tells you no arithmetic moved; only the entry tells you whether the contract did. Read the entry even on a patch. A minor bump means behavior changed — outputs for some inputs are different, and the entry says which and why. The word BREAKING inside an entry flags changes that alter the shape of the contract itself: an input removed, an output's meaning redefined. The practical rule for a caller is simple: your CI fixture asserts the specVersion it integrated against, and any mismatch routes you here, to the entry that explains the delta before you decide whether your product cares.

A real entry, unpacked

Take a recent entry from the divorce model, version 1.2.0: the yearlyData.year field changed from the wall-clock calendar year to a 1-based relative year index, removing the model's only wall-clock dependence so that identical inputs produce identical outputs — and a stable record hash on replay — across calendar-year boundaries. Everything a changelog entry owes you is in that one paragraph: what moved (one output field's meaning), why (replay determinism), the blast radius (chart labels only — no other output moves), and the severity flag (BREAKING, because the field's meaning changed even though the arithmetic did not). A caller with a fixture on that model reads the entry, re-runs the fixture, updates the stored expectation, and merges — the designed response to a designed event.

Reading history, not just news

The changelog's second job is retrospective. A stored envelope carries the specVersion that produced it; the changelog carries every entry since. Together they answer the auditor's favorite question — why does the tool's answer today differ from the answer it gave in March — with a citation instead of a shrug: the March answer was computed under the March version, here is the entry describing what changed and when, and here is the hash proving the March answer is exactly what the envelope says it was. Version history most places is engineering housekeeping; here it is the explanation layer for every number the platform has ever produced.

What absence of entries means

Models with no entries beyond their initial version have not changed behavior since shipping — and that silence is information with teeth, because the dual-implementation harness re-verifies every model against its spec on every release. A quiet changelog over a busy release history means the behavior held still while the platform moved around it. The changelog's value is exactly that its silence is as trustworthy as its entries: nothing moves off the record, so no news genuinely is no news.

• ✓Bookmark /models/changelog — it is the only place behavior changes are announced.
• ✓Let your CI fixture do the watching — version assert first, hash assert second.
• ✓On a bump, read the entry before re-running anything — the why decides whether you care.
• ✓Use entries plus stored specVersions to explain historical answers.
• ✓Treat BREAKING as a spec-reading event, not just a fixture update.