Decision record · ADR
ADR-0021: Version packages according to their owning release boundary
Status: superseded | Date: 2026-07-17 Superseded by: ADR-0030
References: ADR-0008, ADR-0009, RFC-0004, RFC-0006
Context
Section titled “Context”ADR-0009 selected package-index wheels and exact workspace locks to stop binary upgrades from silently changing framework lowering. It coupled that transport decision to a second decision: every Cargo crate, workspace-side Python package, internal measurement runner, binary, and plugin used one release version.
The implemented boundaries now show that these artifacts do not share one change authority. The Cargo workspace and embedded measurement runners are produced by an InferLab product release. The adapter SDK and framework integrations are independently distributable workspace dependencies, and framework integrations change when their frameworks change. RFC-0006:C-INTEGRATIONS already makes the explicit adapter protocol version the cross-language compatibility contract and records package identity separately. The workspace manifest and Pixi lock already pin the exact adapter artifacts used by an experiment.
Problem Statement
Section titled “Problem Statement”A backend-only rendering or probe fix that does not change the adapter protocol currently forces a patch release of unchanged Rust crates and every unrelated Python integration. Equal package numbers do not add compatibility evidence, registry publication is not atomic across Cargo and the Python package index, and the protocol gate already rejects incompatible combinations. We need version ownership that lets the concrete backend-only workflow publish only the changed integration while retaining reproducibility and the existing failure boundary.
Constraints
Section titled “Constraints”- Package-index wheels, exact workspace pins, lock-file hashes, and the no-embedded-Python boundary from ADR-0009 remain in force.
- RFC-0004:C-INFERLAB-TOOLCHAIN keeps Eval and Bench runners owned by the invoking InferLab release.
- RFC-0006:C-INTEGRATIONS keeps adapter protocol version equality authoritative for runtime compatibility.
- ADR-0008 keeps registry and public-release publication operator initiated.
- The design must not introduce a user-authored compatibility matrix or a second dependency authority beside the workspace manifest and lock.
Decision
Section titled “Decision”We will align package versions with their owning release boundary while retaining the wheel transport and workspace authority selected by ADR-0009.
The InferLab Cargo workspace, binary, plugin, and internal Eval and Bench runners remain product-release artifacts and use the InferLab product version. The adapter SDK and each framework integration use their own package versions and can be released without changing the product version or unrelated integration versions.
Each framework integration continues to declare the adapter SDK dependency it was built and tested against. Runtime compatibility across the Rust/Python boundary continues to be decided only by the explicit adapter protocol version. A package version is producer identity, not a second compatibility protocol.
Workspace manifests continue to select exact adapter package versions, Pixi locks continue to pin their resolved content, and execution records continue to preserve product version, adapter package identity and version, and protocol version. These existing authorities provide reproducibility without requiring numeric equality.
Implementation Notes
Section titled “Implementation Notes”- Product release gates compare the product tag with the Cargo workspace and release-owned runner versions only.
- A workspace-side Python distribution is prepared and published independently under a package-scoped release tag; the package index remains canonical and the identical wheel plus checksum remains available as a GitHub release asset.
- A protocol change is coordinated by changing the Rust wire contract, generated SDK, and affected integrations, but their package versions need not share the same numeric value.
- Development remains checkout-based through editable path dependencies.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- A framework-specific fix can ship without rebuilding or republishing unchanged Rust crates and unrelated framework integrations.
- Package versions describe the artifact that actually changed, while protocol version remains the one compatibility authority.
- Exact workspace pins, lock hashes, and recorded producer identity retain the existing reproducibility model.
- A failed or burned Python package version no longer consumes the InferLab product and Cargo version.
Negative
Section titled “Negative”- Release preparation needs a package-selective path and package-scoped tags in addition to the product release path.
- A protocol change requires an explicitly coordinated multi-package publication sequence.
- Human-facing qualification documentation must name the integration package version instead of assuming it equals the InferLab product version.
Neutral
Section titled “Neutral”- The adapter SDK and different framework integrations may carry different versions in one workspace.
- Package-index mirrors remain the normal offline transport; package-scoped GitHub release assets retain the manual fallback.
- Cargo crates remain lockstep because their current supported consumer is the single InferLab product build, not because Cargo and Python versions must agree.
Alternatives Considered
Section titled “Alternatives Considered”Keep universal lockstep across Cargo crates, internal runners, the adapter SDK, and every framework integration (rejected)
Section titled “Keep universal lockstep across Cargo crates, internal runners, the adapter SDK, and every framework integration (rejected)”- Pros: One numeric version labels the whole repository state, The existing product release helper can publish every artifact as one batch
- Cons: A backend-only fix republishes unchanged crates and unrelated wheels, Numeric equality duplicates the explicit protocol compatibility authority, Cross-registry publication remains non-atomic despite equal numbers
- Rejected because: It couples independently owned framework changes to a product release without adding compatibility or reproducibility evidence
Give every Rust crate, internal runner, SDK, and integration a fully independent release train (rejected)
Section titled “Give every Rust crate, internal runner, SDK, and integration a fully independent release train (rejected)”- Pros: Every artifact version changes only when its own bytes or contract change
- Cons: The Cargo crates currently form one experimental product build rather than separately supported libraries, Eval and Bench runners are fixed members of the versioned InferLab measurement toolchain
- Rejected because: It fragments release-owned artifacts whose supported workflow is intentionally one InferLab product release
Align versions with ownership: keep Cargo crates and internal measurement runners on the InferLab product version, while versioning and releasing the adapter SDK and each framework integration independently (accepted)
Section titled “Align versions with ownership: keep Cargo crates and internal measurement runners on the InferLab product version, while versioning and releasing the adapter SDK and each framework integration independently (accepted)”- Pros: Backend-only fixes publish only the affected workspace dependency, Protocol version remains the single runtime compatibility fact, Exact workspace pins and lock hashes preserve reproducibility
- Cons: Operators and records can legitimately display different product and integration package versions, Protocol changes still require a coordinated SDK, integration, and control-plane release sequence