5.6 KiB
Compatibility matrix — v1.2.1 plus unreleased RC hardening
Nothing here is implied. The executable contract lives in
backend/src/modelforge_api/domain/release.py; startup and release tests enforce it.
RC development note: the unreleased product branch now targets additive schema
20260830_0024, accepts20260828_0022and auth-only20260830_0023as upgrade sources, and refuses to serve until the audit-chain migration completes. Deployed stable v1.2.1 remains frozen on20260828_0022; the released matrix below continues to describe that production artifact until the RC is tagged. Selecting and stamping the post-0024 product version is an explicit pending release tranche; the temporary repository1.2.1constant must not be presented as a released schema-0024 artifact.
Product and database
| Contract | Value |
|---|---|
| Version | 1.2.1 |
| Channel | stable |
| Version source | repository VERSION |
| Runtime schema | 20260830_0023 |
| Direct upgrade-source schema | 20260827_0021, 20260828_0022 |
| Minimum direct upgrade | v1.0.0 |
| PostgreSQL | 16+; Compose ships 17 |
| SQLite | unit tests only; NOT SUPPORTED FOR PRODUCTION |
The hardened candidate serves only on schema 0023. The upgrade tool accepts 0021 or the production 0022 head, applies the intervening revisions, validates all existing node credential scopes, and reaches 0023 before the API starts. PostgreSQL is the only production database contract; SQLite is used only to exercise DDL mechanics in 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.1.
Upgrade matrix
| From | Schema | To | Supported |
|---|---|---|---|
v1.0.0 |
20260827_0021 |
current candidate / 20260830_0023 |
yes; backup and rehearsal required |
v1.1.0 |
20260828_0022 |
current candidate / 20260830_0023 |
yes; scope validation migration |
v1.1.1 |
20260828_0022 |
current candidate / 20260830_0023 |
yes; scope validation migration |
v1.2.0 |
20260828_0022 |
current candidate / 20260830_0023 |
yes; scope validation migration |
v1.2.1 |
20260828_0022 |
current candidate / 20260830_0023 |
yes; scope validation migration |
| current candidate | 20260830_0023 |
current candidate | yes; already current |
older than v1.0.0 |
any | v1.2.1 |
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.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.