Decision record · ADR
ADR-0001: Use committed Pixi environments with scoped lock bootstrap
Status: accepted | Date: 2026-06-30
References: RFC-0002
Context
Section titled “Context”RFC-0002:C-WORKSPACE-AUTHORITY makes one versioned downstream workspace authoritative for source revisions, Pixi manifests and locks, integration selection, and recipes. InferLab therefore needs a reproducible way to produce that committed lock and a side-effect-free way to consume the installed environment during dry-run and experiment execution.
Problem Statement
Section titled “Problem Statement”Editable framework packages such as vLLM may execute dynamic package metadata that imports PyPI-provided build dependencies such as PyTorch. Pixi resolves those editable packages before PyPI runtime dependencies are installed, so a clean-prefix lock can fail even though installation from an already committed lock succeeds. Hiding this producer-side bootstrap behind an already committed lock leaves clean lock reproduction unencoded; solving it inside a general dynamic source-set materializer brings generated manifests, overlay closures, cache identities, and garbage collection that exceed the needs of a fixed submodule workspace.
Constraints
Section titled “Constraints”- The committed workspace manifest and lock remain the package authority required by RFC-0002:C-WORKSPACE-AUTHORITY.
- Framework source stays in workspace submodules, while reusable integrations stay in the InferLab monorepo per RFC-0006:C-INTEGRATIONS.
- Dry-run and experiment execution must not silently mutate package state.
- Pixi remains the only dependency resolver and installer authority; an out-of-band package installation step is not acceptable.
- The solution must not introduce per-source-set generated environment closures.
Options Considered
Section titled “Options Considered”We considered relying only on a pre-existing committed lock, adopting a general dynamic source-set materializer, and adding a narrowly scoped lock-production operation for the fixed workspace.
Decision
Section titled “Decision”We will keep each downstream workspace’s root Pixi manifest and lock as the only package authority and add a scoped inferlab env lock maintenance operation for clean lock production because this preserves the simple collaboration model while closing the hidden bootstrap gap without introducing a dynamic environment system.
The operation may use an internal staged Pixi install when a no-build-isolation editable package needs a PyPI-provided build dependency during metadata resolution. Intermediate manifests and locks are transient implementation state; the committed root manifest and final full lock remain authoritative.
Implementation Notes
Section titled “Implementation Notes”- Lock production reads the existing workspace manifest rather than introducing an InferLab environment schema that duplicates Pixi.
- The original manifest is preserved byte-for-byte and restored after success, failure, interruption, or cancellation.
- An existing final lock is restored on failure; a transient base lock is never exposed as the workspace result.
- The scoped operation does not create content-addressed environment directories, source-set overlays, historical closures, or environment garbage collection.
- Ordinary installation remains a locked Pixi install, while integration lowering and experiment execution activate the installed environment with
pixi run --as-is. - The implementation is validated against both a clean-prefix lock production and a separate clean-prefix installation from the resulting committed lock.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- A collaborator can reproduce the package environment from the workspace revision with one locked Pixi installation.
- Maintainers can regenerate the lock from a clean prefix without undocumented warm-environment state.
- Dry-run and experiment execution cannot silently update the lock or rebuild the environment.
- InferLab avoids a second generated package authority and the configuration surface associated with materialized environment closures.
Negative
Section titled “Negative”- Lock production temporarily replaces authoritative workspace files internally. Atomic writes and restoration guards are required so interruption cannot leave base state behind.
- The helper depends on Pixi’s manifest and no-build-isolation behavior. A pinned supported Pixi range and real external-tool coverage are needed to detect upstream changes.
- Lock maintenance remains more expensive than an ordinary install because a clean bootstrap may install large framework build dependencies before resolving editable metadata.
Neutral
Section titled “Neutral”- Workspace owners still decide which Pixi environments, framework revisions, and integration package versions are committed.
- Framework builds and runtime-image production remain separate workflows even though they consume the same committed source and package baseline.
Alternatives Considered
Section titled “Alternatives Considered”Keep one committed workspace manifest and lock, and provide a scoped inferlab env lock operation that bootstraps no-build-isolation editable packages without creating per-run environments (accepted)
Section titled “Keep one committed workspace manifest and lock, and provide a scoped inferlab env lock operation that bootstraps no-build-isolation editable packages without creating per-run environments (accepted)”- Pros: Preserves one-command locked installation and visible workspace authority, Automates the concrete clean-lock failure already proven by vLLM, Keeps dry-run and execution on immutable
pixi run --as-isactivation - Cons: Adds a maintainer-only environment command and crash-recovery responsibility, Depends on Pixi manifest semantics and requires real external-tool coverage
Rely on maintainers to produce the committed lock from an already warm local prefix (rejected)
Section titled “Rely on maintainers to produce the committed lock from an already warm local prefix (rejected)”- Pros: No new InferLab package-management code, Matches the ordinary consumer installation path
- Cons: A clean workspace cannot reproduce the authoritative lock, Hidden machine state determines whether lock production succeeds
- Rejected because: It leaves the producer-side bootstrap gap unresolved and cannot satisfy reproducible workspace maintenance.
Adopt dynamic environment capsules, source-set overlays, generated materialized manifests, closure identities, reuse, and garbage collection (rejected)
Section titled “Adopt dynamic environment capsules, source-set overlays, generated materialized manifests, closure identities, reuse, and garbage collection (rejected)”- Pros: One general mechanism covers arbitrary source and package layouts, Supports dynamic package-origin combinations
- Cons: Introduces configuration and runtime concepts the fixed workspace deliberately avoids, Creates a second generated manifest and lock authority beside the committed workspace, Makes ordinary recipe execution responsible for package materialization
- Rejected because: The fixed submodule workspace does not need dynamic source-set environment closures, so the operational and conceptual cost is not justified.