Skip to content
Multigrid

Contracts, runbooks and rollback

What a clause commits you to, what a runbook must contain, and when to trigger a rollback.

A provider migration fails in two places, and neither of them is the code. It fails at the contract, where a notice period or a retention window quietly decides how long you must pay two vendors at once and which of your own data you can take with you. And it fails at the cutover, where nobody wrote down in advance what “this is going badly” means, so the decision to roll back gets made at two in the morning by whoever is most tired.

These pages are about those two places. The contract pages describe clause types — what a retention clause, a notice clause or a portability clause actually does to a migration, and what to look for in the agreement you signed — rather than any named vendor’s terms, which are negotiated per customer and change without notice. The planning pages produce artefacts: an itemised cost model you fill in with your own numbers, a step-ordered runbook, and rollback triggers expressed as conditions a monitor can evaluate. None of this is legal advice; a lawyer reads your agreement, and this library only tells you where to look.

What a Data Retention Clause Means for a Future Migration

How the retention terms in an AI vendor agreement decide which of your logs, evaluation history and fine-tuning artefacts you can actually take with you.

9 min read

What an Exit Notice Period Means in Practice

How a notice-period clause collides with a real migration timeline, and why a short notice period forces dual-running rather than allowing a clean cutover.

9 min read

Data Portability Clauses Worth Negotiating Before You Sign

The specific export guarantees — format, scope, timeline, fee — worth asking for in an AI vendor agreement, framed around what a later migration will need.

9 min read

What Happens to Prompt-Cached Content When You Leave a Vendor

Why server-side prompt cache entries are ephemeral infrastructure rather than an asset you can export, and what to assume about them at account closure.

8 min read

Estimating the True Cost of a Provider Migration

An itemised cost model for a provider migration — engineering, re-embedding, dual-run overlap, eval re-runs — with the payback arithmetic worked through on labelled assumptions.

10 min read

Building a Migration Runbook for a Provider Cutover

A step-ordered runbook for moving production traffic to a new LLM provider, with the dual-run window, the ramp schedule and the abort conditions written down before the cutover starts.

11 min read

Defining a Rollback Trigger for a Provider Migration

How to turn a vague sense that a cutover is going badly into a pre-agreed condition with a metric, a threshold, a window and an owner, derived from your own baseline.

10 min read

Logging Breaks After Switching LLM Provider: Migrating the Fields

Why a log pipeline keyed to one provider's response field names silently drops rows after a swap, and the field-mapping layer that fixes it.

10 min read

Cost Tracking Is Wrong After Switching LLM Provider

Why a spend dashboard built on one provider's usage-object field names undercounts or zeroes out after a migration, and how to map usage across providers correctly.

10 min read

Migrating a Prompt Versioning System Between Providers

What has to change in a prompt versioning scheme when the same prompt must serve two providers at once during a migration, and how to avoid a permanent fork.

10 min read

Keeping Two Prompt Versions in Sync During a Provider Migration

A pattern for holding one canonical prompt intent and rendering it per provider, so a mid-migration fix is applied once instead of twice.

10 min read

What SDK Version Pinning Actually Protects You From

Pinning a client SDK does not remove risk from your system; it moves the risk to a time you chose, and only for the half of the stack the pin covers.

10 min read

Reading an SDK Changelog Before Upgrading in Production

A method for extracting the handful of changelog entries that affect a production caller from the hundreds that do not.

9 min read

Fixing Breaking Changes After an Automatic SDK Dependency Bump

Diagnosing a production break caused by an unpinned client library picking up a new major, and the pin-and-migrate sequence that stops it recurring.

10 min read

Migrating From a Provider's Native Streaming to Server-Sent Events

How to normalise several providers' streaming dialects into one internal event type, and which parts of each dialect have no counterpart.

11 min read

What the “Responses” API Name Actually Changed

Why a newer endpoint stopped calling its output a completion, and what that rename says about the structure of what comes back.

9 min read

Migrating From a Chat Completions Shape to a Responses Shape

A field-by-field rewrite of a working chat-completions call into the newer responses-shaped equivalent, including the tool round trip.

11 min read

Mapping Conversation State When an API Keeps It For You

What moves in your client when the transcript stops living in your database and starts living on the provider's side.

10 min read

What Changes in Client Retry Logic When the API Holds State

Why a retry after a timeout is harmless against a stateless endpoint and can duplicate a turn against a stateful one, and the ledger pattern that fixes it.

11 min read

Other topics