115 lines
5.6 KiB
Markdown
115 lines
5.6 KiB
Markdown
# 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`, accepts `20260828_0022` and auth-only `20260830_0023` as upgrade sources, and refuses to serve until the
|
|
> audit-chain migration completes. Deployed stable v1.2.1 remains frozen on `20260828_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 repository `1.2.1` constant 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.
|