124 lines
6.0 KiB
Markdown
124 lines
6.0 KiB
Markdown
# 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.
|