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

# Version discovery and exact pinning

> Discover immutable schemas and deliberately upgrade an exact-required engine.

An exact `N.M` pin freezes the released engine configuration plus the request
and response schemas identified by that release. It does not freeze
nondeterministic model output, external source contents, provider behavior,
latency, or the executable artifact. Nexio validates the current runtime against
every supported released contract before deployment.

## Pin policies

| Policy                | Omitted `engine_version`                    | Exact `N.M`            | Major track `N.x`                            | `draft`      |
| --------------------- | ------------------------------------------- | ---------------------- | -------------------------------------------- | ------------ |
| `exact_required`      | `400 engine_version_required`               | Accepted when released | `400 engine_version_exact_required`          | Sandbox only |
| Legacy latest-release | Resolves to latest release on public intake | Accepted when released | Resolves latest released minor in that major | Sandbox only |

The fixture and launch-engine integration use `exact_required`. Do not use
`N.x` for those engines. Bare major and three-part semantic versions are always
rejected.

## Discover versions and immutable schemas

1. Call `GET /api/v1/engines/{engine_slug}/versions` with an `engines:read`
   scoped key bound to the engine.
2. Select an exact version and record its `request_schema_hash`,
   `response_schema_hash`, `released_at`, and `changelog`.
3. Resolve each hash through the published
   [supported-version registry](/contracts/supported-versions/index.json).
4. Download the content-addressed schema path from its immutable manifest and
   verify that the file SHA-256 equals the manifest hash.

The version API intentionally returns hashes and release metadata, not schema
bodies. The checked-in content-addressed files are the immutable launch
contract.

## Deliberate upgrade flow

<Steps>
  <Step title="Freeze the current baseline">
    Record the exact version and both schema hashes currently used in live
    requests.
  </Step>

  <Step title="Review the target">
    Read its changelog and compare the immutable request and response schemas.
  </Step>

  <Step title="Exercise sandbox outcomes">
    Submit the target exact version in a canonical sandbox. For the fixture
    engine, run `completed`, `degraded`, and `failed` test scenarios and verify
    polling plus webhook handling.
  </Step>

  <Step title="Update the integration">
    Change request generation and response parsing deliberately. Deploy the
    exact target pin, never an `N.x` shortcut for an exact-required engine.
  </Step>

  <Step title="Reconcile and retain evidence">
    Store the resolved exact version and schema hashes with your release record.
  </Step>
</Steps>

Rollback means redeploying the previously reviewed exact version. A rollback
does not make execution byte-identical to an earlier date because behavior and
external sources are outside the freeze boundary.