Decision record · ADR
ADR-0009: distribute adapters as lockstep wheels from the package index
Status: superseded | Date: 2026-07-04 Superseded by: ADR-0021
References: RFC-0006:C-INTEGRATIONS, RFC-0005:C-EVIDENCE, RFC-0008:C-AGENT-PLUGIN, RFC-0004:C-INFERLAB-TOOLCHAIN, ADR-0001, ADR-0008
Context
Section titled “Context”The workspace-side Python packages (the adapter SDK and framework integrations) are today embedded in the inferlab binary as sources and materialized into a workspace-relative toolchain path that committed manifests must reference exclusively. This has an unstated defect: the pixi lock pins a path whose content floats with the operator’s binary, so upgrading the binary silently changes adapter lowering under an unchanged workspace commit, and a workspace cannot bump adapters independently of a binary release. Its strengths are real: binary and adapters update atomically with zero version skew, and offline bootstrap is native. With the GitHub release, wheels become hostable artifacts: the build script already produces and smoke-installs them on every gate run, and the adapter boundary is an enum-versioned one-shot JSON protocol (currently V3) designed to fail loudly on an unknown version. The update model must answer four scenarios: a binary-only update, a workspace-initiated adapter bump, reproduction of an old record, and bootstrap on a machine without network.
Amended 2026-07-06: revised at implementation time by operator direction toward the standard index flow. Preparation surfaced two facts the original weighing missed. First, a pixi lock records no content hash for find-links-sourced wheels — only index-sourced resolution pins content, so the seed transport never carried the hash guarantee attributed to it. Second, the embedded seed never covered the serving environment’s third-party dependencies (pydantic, the frameworks themselves), which always required index or mirror reachability; the seed’s offline value was limited to InferLab’s own wheels, marginal for any site able to realize the rest of the environment offline. Development consistency needs no binary involvement either: development workspaces reference the checkout through editable path dependencies, which was already the practice.
Decision
Section titled “Decision”Wheels are the only artifact form for the workspace-side Python packages, and the package index is their canonical transport. Committed workspace manifests reference them by exact pinned version; when they resolve from the index, the pixi lock pins their content hashes, and that form carries the reproduction guarantee — a workspace commit fully pins serving behavior. A manifest MAY resolve them from a find-links location or a filesystem path for development, pre-release validation, and air-gapped fallback; the lock records no content hash for such sources, so those forms do not carry the guarantee. The binary carries no Python content: the embedded-source payload, the workspace-relative toolchain path, the materialization step, and the in-workspace side effect of inferlab toolchain install all retire — a fresh checkout realizes the serving environment with pixi install --locked alone. The wheels are built once, locally, with the standard Python build backend in the locked project environment — the environment whose gates (license retention, install smoke) every build passes — and the operator publishes that one build to both transports: to the package index with the standard local upload flow, exactly as with the crates registry, and to the GitHub release as assets with checksum sidecars. One build with two manual uploads keeps the transports one artifact set by construction. The release workflow builds no wheels: the operator’s tag push initiates it, it executes its mechanical consequences — building the binaries, creating the GitHub release, uploading its own assets — and it gates that the tag, the crate version, and every wheel version agree, so a version-drifted tag fails before anything publishes. Offline sites use a package-index mirror — locks record index URLs and content hashes, which a mirror serves unchanged and hash-verified — and the release-asset wheels with their checksum sidecars are the manual fallback where no mirror exists. Releases are lockstep: every tag stamps the binary, all published wheels, the published crates, and the agent plugin package with one version; each framework integration pins its adapter SDK by exact version, so mixed-version wheel sets fail at resolution rather than at runtime, and same-version combinations are the tested set. Release artifacts pack deterministically — sorted members, fixed metadata, normalized compression headers — so identical content hashes identically wherever it is packed. Every published artifact retains the license notice, with RFC-0001:C-LICENSE-RETENTION as the governing authority for the per-artifact forms: wheels and sdists ship the license text under a build gate (package copies must match the repository text, and every built artifact must contain it), the plugin tarball packs it, and each release publishes it as a first-class asset — an SPDX expression alone does not satisfy the retention condition. Binaries ship bare and embed the notice themselves — inferlab license prints it — so every copy of the binary retains it by construction, direct downloads and plugin-less installs included; the release-level license asset remains for human discovery, and archives stay unnecessary. There is no separate wheel version channel: post-release suffixes (.postN) and independently bumped wheel versions are explicitly rejected — a Python-level fix ships as a normal patch release of the whole set, with the binary rebuilt even when unchanged, because a post-suffixed wheel would exist outside the tested same-version set and outside the lockstep release-gate version check; the index’s immutability makes a burned version number a whole-set patch release by construction. Cross-version combinations are governed solely by the adapter protocol version: a mismatch fails loudly at the adapter boundary, naming both sides and the remedy — bump the workspace adapter pins and relock, or run the release whose binary speaks the adapter’s protocol; the adapter-bump scenario is the normal producer of such skew — a site that bumps adapters without updating binaries runs cross-version, inside the gate, until the next binary update. Records keep producer-only identity (InferLab version, adapter id and version); no required-version-range field is recorded, because the protocol gate plus the pinned lock reconstruct compatibility when needed. Scenario answers: a binary-only update leaves the serving environment untouched; an adapter bump is a reviewable workspace commit (version bump plus relock); reproducing an old record checks out a revision whose lock pins the old wheel hashes, served by the immutable index or a mirror of it; an offline machine bootstraps from its site mirror, or manually from release-asset wheels at the documented cost of lock-unpinned hashes. The clause rewrites landed with the integrations clause, the toolchain reduction, and the workspace-authority scoping; wheel publication and downstream migration ship with the next release.
Consequences
Section titled “Consequences”Positive:
- The workspace becomes the single authority for serving behavior; binary updates stop silently changing adapter lowering.
- Adapter updates become reviewable, reproducible workspace commits that reach every machine through normal pulls.
- Bootstrap simplifies to
pixi install --lockedalone; the in-workspace materialization step and its ordering friction disappear by construction. - The binary sheds the embedded payload and its build-time generation; cargo builds keep zero Python coupling, and the distribution pipeline is standard tooling end to end.
- Old-record reproduction strengthens: the index is immutable and the lock pins content hashes, so the archive exists without any InferLab-owned retention mechanism.
Negative:
- Offline bootstrap degrades from binary-native to site infrastructure: a package-index mirror serves locked URLs hash-verified, and release-asset wheels with checksum sidecars are the manual fallback whose hashes the lock does not pin.
- Version skew becomes constructible (the embedded model made it impossible); the protocol-gate error text must name both versions and the remedy on both sides of the boundary — validation showed the adapter SDK buries an unknown version among field-validation errors, so the adapter side needs a version pre-parse before request validation.
- Publication depends on an external index account: package-name registration and the manual index upload are operator-owned, and the index’s immutability means a botched upload burns the version number for the whole set.
- C-INTEGRATIONS needs a substantive rewrite, the toolchain clause sheds its in-workspace side effect, and every downstream workspace needs a one-time migration commit.
Neutral:
- Release assets carry the same wheel files as the index; they serve human discovery and air-gapped sites, and their presence changes transport, not the model.
- The measurement toolchains (lm-eval, AIPerf runners) already follow a release-owned versioned model and are unaffected.
Alternatives Considered
Section titled “Alternatives Considered”An embedded same-version find-links seed in the binary as the second transport of the wheels (within the wheel-only lockstep frame, which carries forward) (rejected)
Section titled “An embedded same-version find-links seed in the binary as the second transport of the wheels (within the wheel-only lockstep frame, which carries forward) (rejected)”- Pros: a workspace commit fully pins serving behavior: manifests reference pinned versions and the lock pins wheel hashes, index and seed are two transports of one artifact, so offline bootstrap survives without a second authority
- Cons: version skew becomes constructible (bounded by the loud protocol gate) where the embedded model made it impossible
- Rejected because: Rejected at implementation time by operator direction. Every wheel-byte production route couples something that should stay decoupled: building wheels before the binary couples cargo builds, the Rust CI job, and the closure guards to a Python toolchain forever, while packing wheels in build.rs or at runtime reimplements the wheel format beside the standard backend. The seed’s offline value was limited to InferLab’s own wheels — third-party dependencies always required an index or mirror — and the find-links transport it relies on records no content hashes in the lock, so it never carried the hash guarantee attributed to it. Development consistency is served by editable path dependencies with no binary involvement.
Status quo: binary-embedded sources materialized to a workspace-relative path that manifests must reference (rejected)
Section titled “Status quo: binary-embedded sources materialized to a workspace-relative path that manifests must reference (rejected)”- Pros: atomic binary+adapter updates, zero skew
- Cons: a binary upgrade silently changes lowering under an unchanged workspace commit; workspaces cannot bump adapters; the serving-environment truth splits between the lock and the binary
- Rejected because: The lock pins a path whose content floats with the operator’s binary: a binary upgrade silently changes adapter lowering under an unchanged workspace commit, workspaces cannot bump adapters independently, and the serving-environment truth splits between the lock and the binary.
Wheels published to the package index, with the same files attached to release assets as the manual offline fallback (accepted)
Section titled “Wheels published to the package index, with the same files attached to release assets as the manual offline fallback (accepted)”- Pros: simplest pipeline with standard tooling end to end, index immutability plus lock hashes strengthen old-record reproduction with no InferLab-owned retention mechanism
- Cons: offline sites depend on mirror infrastructure or manual asset downloads whose hashes the lock does not pin
Independently versioned packages with compatibility declared per package (rejected)
Section titled “Independently versioned packages with compatibility declared per package (rejected)”- Pros: packages evolve at their own pace
- Cons: a compatibility matrix to govern and test — a pseudo-need for a single-repo, single-team project
- Rejected because: A compatibility matrix to govern and test is a pseudo-need for a single-repo, single-team project; lockstep stamping with exact SDK pins keeps mixed-version sets unrepresentable at resolution time.
Hybrid: release binaries resolve index wheels while development binaries embed sources (rejected)
Section titled “Hybrid: release binaries resolve index wheels while development binaries embed sources (rejected)”- Pros: release stays standard while in-tree development stays atomic
- Cons: development and release run two distribution mechanisms, and the embedded path survives only in the configuration no user runs
- Rejected because: Development atomicity already comes from editable path dependencies in the development workspace manifest — the checkout is the source, no binary machinery involved — so the hybrid keeps all of the embedding’s maintenance surface to solve a problem that no longer exists, and it forks dev from release mechanics, leaving the embedded path tested only by developers and exercised by no user.