# Versions and routing

Source: https://convergingthought.com/docs/concepts/versions-and-routing

> Immutable candidates, explicit activation, and a stable subject for every new request.



A subject has at most one active adapter. Internalization creates a new candidate; activation chooses which candidate new requests use. The platform hosts checkpoints and resolves routing, so clients use subject and version IDs rather than storage paths or provider handles.

## Request snapshots [#request-snapshots]

The platform resolves the active version when it admits a model request. That selection is recorded in `adapter_version` on the job. Running requests keep the snapshot even if the subject changes while they are queued or executing.

For inference, this field identifies the weights used to answer. For internalization, it identifies the parent weights used to learn. The newly created version is returned separately in `result.candidate.version_id`.

By default inference follows the active subject route. Set `adapter_version` to a retained candidate to evaluate it before activation. A pinned version must belong to the same project, tenant, and subject; foreign or expired versions fail. Use `adapter_version: "base"` for a deliberate clean-base comparison.

## Automatic activation [#automatic-activation]

Internalization defaults to `activate: true`. A validated saved candidate activates only if the subject's active version still matches the version captured at admission. This comparison prevents an older training result from silently overwriting a newer release.

Consider two jobs admitted while version A is active:

| Event                    | Active version | Result                                         |
| ------------------------ | -------------- | ---------------------------------------------- |
| Job B and job C start    | A              | Both train from A                              |
| B finishes and activates | B              | B becomes active                               |
| C finishes later         | B              | C is saved, but automatic activation conflicts |

C can still be `ready`, with `activated: false` and `activation_conflict: true`. It is a valid candidate that did not become the current route. Its successful internalization fee still applies. “Latest” means the latest accepted activation, not simply the version with the newest creation time.

## Manual activation [#manual-activation]

Submit `activate: false` if a human or release process must decide. After the job is ready, inspect the candidate, read the subject's current `active_version`, and call:

```json
{
  "version_id": "CANDIDATE_VERSION",
  "expected_version_id": "CURRENT_VERSION"
}
```

Send this body to `POST /v1/adapters/activate` with the `adapters` scope. Use `null` for `expected_version_id` when the subject has no active adapter. The response returns the selected `version_id` and incremented `revision`.

On `409 activation_conflict`, read the subject again and decide whether the proposed activation still makes sense. Blindly replacing the expected value defeats the concurrency protection. The endpoint has no separate idempotency-key contract; after a network timeout, read state before repeating it.

## Rollback and retention [#rollback-and-retention]

You can activate a retained older version with the same endpoint. This changes future routing; it does not undo completed responses, charges, or other saved versions. There is no public operation to reset an existing subject to base. A new subject starts clean.

Each version exposes its confirmed `expires_at`. Background hosting renews retained checkpoints, but the recorded deadline matters. If an active adapter is missing or expired, the request fails explicitly. It never silently falls back to base or another subject.

A successful activation is not permanent archival storage. Watch retention metadata and maintain your canonical source outside the adapter. See [Deploying updates](/docs/guides/rollouts) and the [activation reference](/docs/api-reference/activation) for operational examples.