> ## Documentation Index
> Fetch the complete documentation index at: https://infercrane.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade and compatibility

> Version guarantees, database migration safety, rolling-upgrade boundaries, and rollback policy.

# Upgrade and compatibility

InferCrane v1 separates four compatibility surfaces: the control API, DeploymentSpec, integration
contracts, and PostgreSQL schema. A passing runtime or provider conformance test does not override
the policy for another surface.

## Before upgrading

1. Read the release notes and compatibility matrix.
2. Back up PostgreSQL and verify the dump with `pg_restore --list`.
3. Run `infercrane plan` for representative DeploymentSpecs with the new CLI.
4. Run local qualification against the exact candidate commit.
5. Verify provider credentials and inventory with `infercrane doctor` and `infercrane orphans`.
6. Upgrade the control plane before upgrading generated SDKs or automation clients.

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
scripts/backup-postgres.sh /secure/path/infercrane-before-v1.dump
make qualify-local
```

## PostgreSQL migration contract

Migrations are embedded, ordered, forward-only, and transactionally applied under a PostgreSQL
advisory lock. The migration ledger stores a SHA-256 checksum for every migration. Startup fails if:

* a previously applied migration was edited;
* the ledger has a gap;
* the database contains a migration unknown to the running binary; or
* a migration cannot commit atomically.

The first v1 startup backfills checksums for a pre-v1 ledger after matching every known migration
name. This is a trust-on-first-v1-upgrade bootstrap: a legacy ledger did not retain enough
information to prove the bytes originally executed. Back up and inspect that database before the
first v1 startup. Every subsequent startup verifies the persisted checksum. Automated qualification
upgrades every historical migration prefix to the current schema.

Do not delete ledger rows, edit released SQL files, or start an older binary after a newer migration
has run. Restore the pre-upgrade backup if application rollback requires schema rollback.

## DeploymentSpec

The current file contract is:

```yaml theme={"theme":{"light":"github-light-default","dark":"vesper"}}
apiVersion: infercrane.dev/v1
kind: Deployment
```

Pre-v1 files without these two fields are read as v1 for compatibility. New files should include
them. Unknown fields, versions, and kinds fail closed. Additive optional v1 fields are compatible;
removing or changing a v1 field requires a future versioned conversion path.

## Control API and SDKs

`/api/v1` is the stable v1 namespace. Within v1:

* new optional response fields are additive;
* clients must ignore response fields they do not understand;
* existing field meaning and error codes do not change silently;
* removal requires deprecation in release notes for at least two minor releases;
* generated SDK major versions track the API major version.

CLI human output is not a parsing contract. Automation must use `--output json`, the generated SDKs,
or Terraform.

## Provider and runtime contracts

Provider Contract `infercrane.provider/v1` and Runtime Contract `infercrane.runtime/v1` are versioned
separately from the product. Registration exposes an adapter to composition; only the capability and
qualification inventory establishes evidence for an exact runtime/provider/mode combination.

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
infercrane integrations --output json
```

## Rolling upgrades

Every live replica registers its binary version and control protocol interval. Startup
fails before serving when that interval cannot overlap a live member. Inspect the actual window:

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
infercrane system instances --output json
```

For an adjacent-version rollout, first confirm the release notes declare overlapping protocol
intervals. Add one new replica, verify `/readyz` and the membership list, then remove old replicas one
at a time. An expired operation lease is reclaimed by another worker; the old fence token cannot
checkpoint or complete work. This is not permission to mix arbitrary schema versions: take a verified
backup first and follow the migration compatibility statement for both releases.

Rotate server or client certificates by temporarily trusting both CA generations, rolling clients,
then servers, and finally removing the old CA. InferCrane reads certificate files at process startup,
so each trust change requires a graceful rolling restart.

## Support window

Release candidates receive best-effort migration fixes and may still change with release notes.
For stable releases, security fixes target the latest minor and the immediately preceding minor;
provider/runtime compatibility remains scoped to the published matrix and immutable evidence.