The Catalog Moves: Living With Model Versions and Deprecations

The mental model most teams bring from cloud services — pick a thing, it stays picked — does not survive contact with the model market. New versions arrive on the order of weeks, not years. Prices move. Providers retire old ids on schedules measured in months. A model that was the obvious choice when you integrated may be two generations back by your first anniversary, and the integration that felt permanent in the sprint is, in fact, a subscription to a moving catalog.

None of this is a reason for despair; it is the price of living through the fastest-improving technology market anyone has operated in. But it does mean the lifecycle question — what happens when the model you pinned changes, prices, or disappears — belongs in the design doc, not in the incident retro.

We said the same thing about prices in how to read a price list: a comparison without an as-of date is a rumor. Versions are the same discipline applied to capability.

Pinning means your code names an exact version, and nothing changes until you change it. You get reproducibility — the same prompt produces the same behavior next quarter — and you get the full weight of maintenance: watching for deprecation notices, evaluating successors, and scheduling migrations. Pinning is the right default for anything customer-facing, anything evaluated, anything regulated.

Floating means you name a family — an alias that the provider points at the current generation — and you inherit improvements and behavior changes alike, unannounced. Floating is convenient for internal tools and prototypes, and it is a quiet liability everywhere else: the day the alias moves, your prompts meet a model they were never tested against, and "the AI got weird this week" is a genuinely hard bug report to trace.

The mistake is the accidental float: pinning nothing, recording nothing, and discovering your exposure during an incident. Whichever policy you choose, choose it in writing, per workload — the audit question "which model served this answer" should be answerable from your own logs, and the routing post's advice stands: if reproducibility is contractual, pin and log.

You will evaluate providers on this eventually, so here is the checklist before you need it. Notice period: how far in advance a retirement is announced, and whether the notice reaches engineers or just a billing contact. Overlap: whether the old and new versions run side by side long enough to evaluate and migrate, or whether the switch is a cliff. Clarity: whether the provider publishes a changelog you can subscribe to, or whether versions change silently.

Price movement deserves the same scrutiny as retirement. A model whose price changes under you is a quieter failure than a retired id, but the invoice notices either way — the dated-snapshot habit from the price-list post applies here too.

Our own bias is visible in how we run the catalog: every price change lands in a dated, public history (we showed one in the GLM 5.2 post), and the model library always reflects the current state of what you can actually call.

Teams that handle deprecations well share one property: the migration path is warm. The model id is configuration, not code — one string, in one place, owned by someone. The eval suite from the eval-before-purchase post exists and runs against candidates in an afternoon. And a rollback is a config flip, not a redeploy.

With that in place, a deprecation notice becomes a scheduled chore: run the successor through the eval, shadow it on a slice of traffic, flip, keep the old config around for a week. Without it, the same notice is a fire drill conducted against a deadline someone else set.

The OpenAI-compatible surface matters here in a very concrete way: if swapping providers is a two-line change, as we walked through in the migration post, then a deprecation inside one provider is never an existential event. Optionality is the real deprecation policy.

The teams who are never surprised by a deprecation share a cadence, and it is lighter than it sounds. Subscribe to your providers' changelogs — one feed, one owner, five minutes a week. Re-run the eval on current candidates once a quarter, or whenever a successor ships, so the "should we move" answer is never more than an afternoon away. And put the pinned versions you depend on in a document somewhere a new hire would find it: which workload, which version, when it was chosen, and what would trigger a move.

That document is the deliverable. It converts the lifecycle from folklore — one engineer's memory of why a model id is what it is — into an asset the organization owns. When the notice arrives, the question shifts from "what are we exposed to?" to "we know exactly what moves and when".

The quarterly re-eval has a second payoff: it is how you collect the dividend. Prices drift down and quality drifts up; the teams with a standing evaluation habit are the ones who actually capture that, instead of reading about it.

When the model is part of a validated system — a regulated pipeline, a certified workflow, an audit trail — change itself is the risk, and the newest version is a liability until someone re-validates it. Freeze, and budget for the re-validation cycle.

Freezing is also honest for workloads that are done. An internal tool that works, that nobody is improving, and whose failure would be annoying rather than dangerous earns stability over freshness; migrate it when the calendar forces you to, not before.

What freezing is not is a strategy for the product core. The catalog's improvement is the closest thing this industry has to a dividend — quality up, prices down, year after year. A core workload frozen in place is declining that dividend on your behalf. Pin, by all means. But run the drill often enough that unpinning is always cheap.