# Compatibility matrix — v1.2.2 source/tag contract

Nothing here is implied. The executable contract lives in
`backend/src/modelforge_api/domain/release.py`; startup and release tests enforce it.

> Publication and deployment note: this file records the v1.2.2 source/tag compatibility contract.
> At the 2026-09-25 reconciliation checkpoint, Gitea's newest published Release object was v1.2.1;
> v1.2.2 existed as a tag. The observed production record was v1.2.3/schema-0032. The RC source
> is version 1.3.0-rc.1 with schema target 20260924_0039; it must not be treated as deployed until
> its own gates pass.

## Product and database

| Contract | Value |
| --- | --- |
| Version | `1.2.2` |
| Channel | `stable` |
| Version source | repository `VERSION` |
| Runtime schema | `20260830_0024` |
| Direct upgrade-source schema | `20260827_0021`, `20260828_0022`, `20260830_0023` |
| Minimum direct upgrade | `v1.0.0` |
| PostgreSQL | 16+; Compose ships 17 |
| SQLite | unit tests only; **NOT SUPPORTED FOR PRODUCTION** |

v1.2.2 serves only on schema 0024. The upgrade tool accepts 0021, the production 0022 head or the
intermediate auth-only 0023 head, applies the intervening revisions, validates existing node
credential scopes and establishes the PostgreSQL-owned audit boundary before the API starts.
PostgreSQL is the only production database contract; SQLite is used only for isolated tests.

Compatibility answers remain typed and fail closed:

| Answer | Meaning | Operator action |
| --- | --- | --- |
| `COMPATIBLE` | This component understands the observed version | none |
| `TOO_OLD` | The observed version predates the supported range | upgrade it |
| `TOO_NEW` | The observed version belongs to a newer release | upgrade this component |
| `UNKNOWN` | Identity could not be established | investigate; it is refused |

## Agent protocol

| Contract | Value |
| --- | --- |
| Current protocol | 1 |
| Accepted protocols | 1 |

The Node Agent and Runtime Worker remain protocol-compatible with v1.0.0. Release images should
still be upgraded together so their product and provenance identity is v1.2.2. Because the Runtime
Worker dependency update is behavioral, existing profiles require fresh LAB evidence before
production promotion.

## Upgrade matrix

| From | Schema | To | Supported |
| --- | --- | --- | --- |
| `v1.0.0` | `20260827_0021` | `v1.2.2` / `20260830_0024` | yes; backup and rehearsal required |
| `v1.1.0` | `20260828_0022` | `v1.2.2` / `20260830_0024` | yes; scope and audit migration |
| `v1.1.1` | `20260828_0022` | `v1.2.2` / `20260830_0024` | yes; scope and audit migration |
| `v1.2.0` | `20260828_0022` | `v1.2.2` / `20260830_0024` | yes; scope and audit migration |
| `v1.2.1` | `20260828_0022` | `v1.2.2` / `20260830_0024` | yes; scope and audit migration |
| intermediate RC | `20260830_0023` | `v1.2.2` / `20260830_0024` | yes; audit-boundary migration |
| `v1.2.2` | `20260830_0024` | `v1.2.2` | yes; already current |
| older than `v1.0.0` | any | `v1.2.2` | no direct upgrade |

Because 0022 introduces terminal node and decommission-operation state, application-only rollback
to v1.0.0 is unsupported. Restore the verified pre-upgrade backup. Alembic downgrade may be used in
isolated verification to prove DDL mechanics, but it is not the production recovery promise.

## Runtime dependencies

| Component | Version |
| --- | --- |
| PostgreSQL | >= 16 |
| Redis | >= 7 |
| Docker Engine | >= 24 |
| Docker Compose | >= 2 |
| Python host tooling | >= 3.12 |
| NVIDIA container runtime | required on GPU nodes |

The Node Agent image requires a glibc-compatible NVIDIA Container Toolkit/driver injection path.
GPU Compose projections explicitly fail closed when NVML inventory or telemetry is unavailable.
CPU-only agents do not require NVML.

## Why this is a MINOR release

Node Decommission adds operator APIs, a Console workflow and an additive schema revision while
preserving existing capability routes and agent protocol 1. That is a backward-compatible feature
addition and therefore v1.1.0 under SemVer, not v1.0.1 and not v2.0.0.

## Why v1.2.1 is a PATCH release

v1.2.1 changes no contract, no schema, no protocol and no behaviour an application can observe. It
corrects how release artifacts are built and stamped: the console's API origin becomes a required
release input rather than an accidental default, and the Node Agent projection stamps the release
identity it was already expected to carry. Correcting packaging without changing the product is a
PATCH under SemVer.

The console image is the one artifact whose *behaviour* differs, because the previous images could
not reach a non-localhost API at all. That is a defect being repaired, not a capability being added.

## Why v1.2.2 is a PATCH release

v1.2.2 hardens public packaging, dependency and database-authority boundaries without changing the
capability API or agent protocol. The Runtime Worker dependency set changes and is therefore
classified `behavioral` operationally: it remains a patch release, but production promotion is
blocked until exact LAB probes prove compatibility, output shape and unload/reclaim behavior.

## Why v1.2.0 is a MINOR release

v1.2.0 adds substantive, backward-compatible product capability at the console layer: a command
center, a domain-oriented information architecture, a design system, a responsive mobile console and
a consistent guarded-action and accessibility vocabulary. No API contract, domain model, runtime
behavior or schema changed, and no existing route was removed or moved. Adding capability without
breaking a contract is a MINOR release under SemVer — not a patch, and not a major.

The minimum direct upgrade stays `v1.0.0`. v1.2.0 changes nothing about the upgrade surface, so
narrowing the supported source range would withdraw a working, tested path for no engineering
reason.

## Why v1.1.1 is a PATCH release

v1.1.1 changes only the Node Agent runtime packaging and local startup validation needed to restore
the existing NVIDIA-node contract. It adds no API, database migration, agent protocol field,
scheduler contract, or operator capability.