Migrate from 0.3 to 0.4

Keep the Linking manifest declarative, replace bare route arrays with the closed runtime artifact, and make every adapter consume the published package through its supported API.

Before you change the pin#

1. Commit the current manifest and deployment build inputs.
2. Capture a known-good 0.3 validation and integration-test result.
3. Locate any copied APIZIT Linking modules or calls to the old route-list API.
4. Plan to rebuild every generated artifact, ZIP, or container image.

1. Pin the published 0.4 package#

requirements.txt or equivalent

apizit-linking[preview]==0.4.0

Do not install from the private engine repository and do not copy its modules into an adapter. PyPI is the supported distribution boundary.

2. Make the manifest canonical#

The canonical authoring contract still uses root version: 1. Explicitly declare it, use uppercase HTTP methods, dotted Python module paths, leading-slash route paths, and only documented fields.

apizit_linking.yaml

version: 1
routes:
  - path: /hello
    method: GET
    function: hello:hello

The compiler may still accept selected historical forms to explain a migration, but that does not make those forms part of the public JSON Schema. New and migrated files should pass both schema validation and the CLI.

Terminal

apizit-linking validate .

3. Replace the bare route list#

Version 0.3 integrations could serialize individual route dictionaries and pass the unversioned list directly to the FastAPI adapter. Version 0.4 makes the complete artifact the supported handoff.

Old migration-only shape#

runtime_routes = [
    route.to_runtime_dict()
    for route in compilation.routes
]
app = create_app_from_runtime_routes(
    runtime_routes,
    project_root=project_root,
)

Supported 0.4 shape#

compilation = compile_linking_file(
    linking_file,
    project_root=project_root,
)
artifact = compilation.to_runtime_dict()
app = create_app_from_runtime_artifact(
    artifact,
    project_root=project_root,
)

Persist the complete artifact unchanged. Its closed envelope contains format, artifact version, engine_version, manifest_version, and routes. Treat it as opaque adapter input.

4. Expect strict signature checks#

Recompilation captures the complete callable contract: ordered parameters, their kinds, required/default state, annotations, callable_kind, and return_annotation. At startup, the adapter imports the callable and rejects any drift before serving requests. If customer Python changes, re-run compilation rather than editing metadata.

5. Remove generator routes#

Functions containing yield and asynchronous generators are not valid Linking targets in 0.4. Convert them to a normal synchronous or asynchronous function returning a supported value. Do not wrap a generator merely to hide its callable kind: streaming remains outside the V1 contract.

6. Rebuild APIZIT integration outputs#

• Pin exactly apizit-linking==0.4.0 in the build and runtime.
• Compile once during the controlled build step.
• Record artifact hash, package version, manifest version, and source revision.
• Package the untouched artifact with the exact 0.4.0 runtime dependency.
• Rebuild ZIP and container outputs; do not reuse 0.3 artifacts.
• Run scan, report, package, image, startup, and HTTP integration tests.

An artifact executes only under its exact engine_version. Changing the dependency without recompiling is expected to fail.

7. Verify the migration#

1. Run apizit-linking validate on every supported project.
2. Load each serialized artifact with the exact pinned engine.
3. Confirm drift tests fail when a fixture callable is deliberately changed.
4. Confirm generator fixtures fail during compilation.
5. Exercise successful requests and structured request errors over ASGI.

Rollback safely#

Restore the exact 0.3 package pin and rebuild its deployment output from the preserved 0.3 inputs. A 0.4 artifact is not a rollback artifact for a 0.3 runtime, and changing version fields by hand is not a rollback strategy.