# Migrate from Linking 0.5 to 1.0

Existing manifest v1 routes keep legacy conversion unless you explicitly add typed validation. Upgrade the exact package, regenerate build artifacts and verify the API before enabling new policies.

## Qualify the stable upgrade

Record the existing lock, source snapshot, runtime artifact and tests. Use a separate virtual environment with `apizit-linking[preview,models]==1.0.1`. Run static validation and direct function/HTTP tests. The optional models extra is needed only for typed routes; core-only validation remains available.

## Regenerate artifacts

1. Compile the original manifest using 1.0.1.
2. Replace the old runtime artifact and its provenance together.
3. Verify engine_version matches the installed distribution.
4. Exercise HTTP status/body/header and permission behavior.

Format v1 artifacts from 0.5 are rejected by the 1.0 runtime. Manifest version 1 does not mean artifact format 1. Never change only engine_version or the artifact version by hand. Recompile instead.

## Opt in one policy at a time

Add response/errors when HTTP statuses or headers should change. Add validation: typed only when annotations, model configuration and serialized responses have been reviewed. Add dependencies/security with an explicit factory. Injected parameters cannot also bind client input. Compose route files only after checking the expanded map for collisions; security remains explicit on each route.

Unmapped failures now use a generic JSON error envelope rather than relying on the server's plain-text 500 page. Static warnings distinguish model preparation from AST validation. Existing documentary response annotations do not become typed enforcement automatically.

## Check and roll back

```text
apizit-linking validate . --json
apizit-linking routes . --json
apizit-linking export . --resolve-models --output candidate.json
python -m unittest discover -s tests
```

diff compares Linking contract exports version 1, not old bare runtime routes. Take a baseline with the new export tool while preserving old application behavior, then compare each intentional policy change. Breaking and unresolved changes require review. A contract check does not prove business correctness.

Rollback restores the preceding engine, lock, source and freshly corresponding artifact together. Retain database state and application migrations; do not infer that framework rollback reverses a schema change. APIZIT pins are managed by its integration release process and cannot be overridden in a customer production manifest. See [compatibility](/apizit-linking-examples/reference/compatibility/), [models](/apizit-linking-examples/reference/models/) and [responses](/apizit-linking-examples/reference/responses/).