Decision record · ADR
ADR-0010: Track a workspace-local content identity for installed Pixi serving environments
Status: accepted | Date: 2026-07-08
References: RFC-0002, ADR-0001, RFC-0002:C-PIXI-ENVIRONMENT-LIFECYCLE, RFC-0002:C-ADHOC-EXECUTION, RFC-0002:C-ENVIRONMENT-CHECKS
Context
Section titled “Context”RFC-0002:C-PIXI-ENVIRONMENT-LIFECYCLE requires ordinary workflows to fail before launch when the selected serving environment is absent or unusable, naming the environment and the locked install action. environment::ensure_usable enforces this with pixi run --locked --no-install --executable -e <env> -- true, treating exit 0 as usable.
Fixing that gate (a never-installed environment silently fell through to the ambient PATH instead of failing) required an exhaustive empirical survey of pixi 0.72.1’s public CLI surface. That survey also settled a second question the clause now states explicitly: pixi provides no read-only primitive to detect an installed environment that predates a committed lock later regenerated for the same environment. An operator (or CI) who edits the manifest and reruns pixi lock — or who runs inferlab env lock — without also reinstalling every environment that lock selects leaves the on-disk prefix silently stale. Every declared serving-framework version, kernel, or dependency pin in that prefix can diverge from what the committed lock now says, and nothing in the product observes it: pixi run --locked --no-install still exits 0, pixi list --frozen still prints the lock’s declared versions rather than what is actually unpacked, and pixi’s own verbosity logging only reports lock-vs-manifest freshness, never installed-prefix-vs-lock freshness.
Problem Statement
Section titled “Problem Statement”Detecting “this installed environment was solved from an earlier lock” requires either knowing what is actually on disk (which pixi’s own CLI does not expose without installing or re-solving) or maintaining an independent record of which lock content the environment was last confirmed against. The clause already carves this condition out of the fail-before-launch guarantee rather than promise something the implementation could not keep; this ADR decides what mechanism could close that carve-out, leaving whether and when to actually close it to a future RFC amendment.
Constraints
Section titled “Constraints”- RFC-0002:C-PIXI-ENVIRONMENT-LIFECYCLE and ADR-0001 already forbid ordinary workflows — dry-run,
serve start,recipe run, andinferlab run(RFC-0002:C-ADHOC-EXECUTION) — from installing packages. Only the operator’s ownpixi installand theinferlab env lockmaintenance operation may touch an environment or its lock. - Pixi remains the only dependency resolver and installer authority; nothing here may reproduce or override its solve.
- The mechanism must degrade gracefully for every workspace that already exists: no migration step, no forced re-verification burden on first contact.
- Detection must apply to every path that consumes a serving environment: the controller’s own local realization and each remote machine a launch reaches over SSH, the same two sites the presence check already had to cover.
Options Considered
Section titled “Options Considered”Reusing a fact pixi itself already tracks internally, diffing pixi’s own package-listing output against the lock, and having InferLab maintain its own independent record of the lock and manifest content an environment was last confirmed against.
Closing this gap changes what RFC-0002:C-PIXI-ENVIRONMENT-LIFECYCLE currently promises: the clause presently states this condition is explicitly out of the fail-before-launch guarantee’s scope, with the operator solely responsible for reinstalling after a relock. Adopting a mechanism that detects the condition is a prerequisite for extending that guarantee to cover it, not the extension itself — the clause still needs its own amendment, paired with implementation, to actually change what workflows are required to do with a detected mismatch. This ADR decides only the mechanism; it does not itself authorize new launch-time failures.
Decision
Section titled “Decision”We will have InferLab record its own marker of the committed manifest’s and lock’s content hashes at the moment ensure_usable last confirmed a serving environment usable, and compare both recorded hashes against the current ones on every subsequent check, because it is the only option that depends on facts InferLab already owns rather than a private pixi implementation detail or a pixi output already shown to misreport installed content.
Hashing the manifest alongside the lock is a deliberate correction to the naive version of this idea: hashing the lock alone would let a hand-edited manifest that was never relocked hide behind a marker whose lock hash still matches, silently skipping the one probe that currently catches lock-vs-manifest drift. Comparing both hashes means a match is only trusted when nothing about either input has changed since the environment was last confirmed good, so the existing probe’s coverage is never weakened, only supplemented.
The comparison lives behind one shared entry point inside environment.rs that both the existing usability gate and a new public, read-only inferlab env status command call — the natural sibling of the existing inferlab env lock — so an operator or a CI job can ask whether an environment is current directly, instead of only discovering drift as a side effect of a failed launch. This follows a common shape for a build-staleness gate: separate a pure-verify operation from anything that reconciles, so an operator or CI can ask the read-only question on its own terms — except inferlab env status deliberately has no reconcile counterpart at all, since ordinary InferLab workflows are already forbidden from installing packages.
Adopting this mechanism is a prerequisite for closing the gap RFC-0002:C-PIXI-ENVIRONMENT-LIFECYCLE currently names, not the closure itself. The clause presently states the condition this marker detects is explicitly outside the fail-before-launch guarantee, with the operator solely responsible for reinstalling after a relock. Making the usability gate actually fail on a detected mismatch — and requiring inferlab env status to exist at all — are both new normative obligations that belong in a paired RFC-0002 amendment at implementation time, the same pairing pattern the presence-check fix already used. This ADR decides the mechanism a future amendment would rely on; it does not itself change what any workflow is required to do.
Implementation Notes
Section titled “Implementation Notes”- A workspace with no marker yet (upgrade from before this change, or a marker deleted by the operator) falls through to the real pixi probe exactly as
ensure_usabledoes today, then writes the marker on that probe’s first success. No migration step and no forced re-verification are needed for an existing workspace. - The remote SSH preflight script in
server/runtime.rsneeds the equivalent read-compare-write logic against each remote machine’s own marker, the same shape of local-plus-remote duplication the presence check already required. - A
--strictflag oninferlab env statuswould force the real probe regardless of a marker match, for a CI caller that wants maximum certainty over speed. Whetherensure_usableitself ever needs the same escape hatch is left to implementation. - The marker records only content hashes, never package names or paths, so it needs no privacy handling beyond the existing
.inferlab/cacheexclusion from source identity.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- The fail-before-launch guarantee closes its last named gap using only facts InferLab already computes, with no dependency on undocumented pixi internals.
- Operators gain a way to proactively ask whether an environment is current —
inferlab env status— instead of only discovering drift when a real launch fails. - A marker match on both the manifest’s and the lock’s hashes lets ordinary launches skip a redundant
pixisubprocess spawn, a small but real latency win on every repeatedserve start,recipe run, orinferlab run, without weakening the existing lock-vs-manifest check the probe alone performs. - The mechanism degrades to today’s exact behavior for any workspace without a marker yet, so shipping it requires no migration and cannot regress an existing workspace’s first launch after upgrade.
Negative
Section titled “Negative”- New persisted, machine-local state enters the codebase — a marker file per environment, per workspace checkout — that has to be reasoned about alongside the existing
.inferlab/cacheand.inferlab/recordsconventions (mitigation: it lives entirely inside the already-gitignored, already source-digest-excluded.inferlab/cachetree, and its schema is a single versioned, atomically-written JSON record with no cross-file consistency to maintain). - The guarantee only covers launches that go through
ensure_usable; an operator who runs pixi directly, bypassing InferLab, gets no protection (mitigation: this is the same boundary the operator skill’s prohibition on direct materialized-prefix invocation already draws for a different reason, so it does not open a new gap, only leaves an existing one uncovered here too). - This ADR decides the mechanism only; it does not by itself make the usability gate fail on a detected mismatch or require
inferlab env statusto exist. Both are new normative obligations that need a paired RFC-0002 amendment before this decision has any externally observable effect (mitigation: this is by design — see Decision — and the same pairing the presence-check fix already used, not a gap in this ADR). - The remote SSH preflight script needs a second, shell-scripted implementation of the same read-compare-write logic, doubling the surface a future change to the marker’s shape has to touch (mitigation: the presence check already established this pattern, and the marker’s shape is a single hash comparison, not complex state, so the shell-side logic stays small).
- A marker that goes stale relative to content it never actually saw (for example, a workspace directory copied or synced outside git, carrying a marker whose manifest and lock hashes happen to coincidentally both still match a different, unrelated manifest and lock) would report
Validincorrectly (mitigation: this requires an adversarial or badly corrupted local state that the workspace’s other integrity mechanisms — dirty-workspace detection, revision identity — already do not defend against, consistent with the project’s design position that machine-local caches do not need integrity defenses against hypothetical local tampering).
Neutral
Section titled “Neutral”inferlab env status’s relationship to the declared environment checks in RFC-0002:C-ENVIRONMENT-CHECKS is additive, not overlapping: this ADR’s marker answers “is the installed environment current with the lock,” while declared checks answer “does the activated environment pass operator-declared sanity scripts” — the two stay independently owned.- Whether
env lockitself should also reinstall declared environments to reduce how often drift actually occurs for the sanctioned relocking path is a smaller, separable UX question this decision does not resolve either way.
Alternatives Considered
Section titled “Alternatives Considered”Read pixi’s own internal bookkeeping (the installed prefix’s conda-meta/pixi file and its environment_lock_file_hash field, or the adjacent .pixi-environment-fingerprint marker) and compare it against a hash InferLab computes for the current lock (rejected)
Section titled “Read pixi’s own internal bookkeeping (the installed prefix’s conda-meta/pixi file and its environment_lock_file_hash field, or the adjacent .pixi-environment-fingerprint marker) and compare it against a hash InferLab computes for the current lock (rejected)”- Pros: No new persisted state; reuses a fact pixi already writes on every install, Would, if reliable, reflect the true installed content rather than a proxy for it
- Cons: Both files are undocumented, private pixi implementation detail with no stability guarantee across pixi releases, Reproducing pixi’s own hash algorithm to compare against it is exactly the kind of private-format dependency ADR-0001 already avoided for lock production
- Rejected because: A verification mechanism built on an unversioned private file format can silently break on a pixi upgrade with no compile-time or even runtime signal — the workspace would go back to reporting stale environments as usable, the exact failure this ADR exists to close
Diff pixi’s own package-listing output (pixi list –frozen or –locked –no-install, –json) against the packages the committed lock declares (rejected)
Section titled “Diff pixi’s own package-listing output (pixi list –frozen or –locked –no-install, –json) against the packages the committed lock declares (rejected)”- Pros: Uses only pixi’s public, documented CLI surface, Would require no new InferLab-owned storage at all
- Cons: Empirically confirmed misleading on real pixi 0.72.1: after relocking without reinstalling, pixi list still printed the lock’s newly declared package version, not the older version actually unpacked on disk (verified against ground-truth conda-meta package records)
- Rejected because: The technique produces a false negative on exactly the condition it exists to catch — it is not merely incomplete, it actively reports a stale environment as current
InferLab records its own marker — the committed lock’s and manifest’s content hashes — the moment ensure_usable last confirmed the environment usable, and compares both recorded hashes against the current ones on every subsequent check (accepted)
Section titled “InferLab records its own marker — the committed lock’s and manifest’s content hashes — the moment ensure_usable last confirmed the environment usable, and compares both recorded hashes against the current ones on every subsequent check (accepted)”- Pros: Directly answers the question this ADR needs answered — has the committed lock changed since InferLab last saw this environment pass — rather than approximating installed-prefix content, Degrades safely: a workspace with no marker yet, or a malformed one, falls through to today’s real pixi probe and stamps a marker on first success, so no migration is required, Depends on no pixi internals: the only inputs are pixi.toml’s and pixi.lock’s own bytes, both of which the workspace already hashes, A marker match on both hashes lets the gate skip the pixi subprocess probe, a small performance win on every repeated launch, without weakening the existing lock-vs-manifest check the probe alone performs
- Cons: Introduces new, if machine-local and gitignored, persisted state the codebase must reason about, Only protects launches that go through ensure_usable; an operator who bypasses InferLab and runs pixi directly gets no protection from it