Decision record · ADR
ADR-0005: Produce runtime images from generated contexts with recipe-referenced validation
Status: accepted | Date: 2026-07-01
References: ADR-0001, RFC-0007:C-IMAGE-BUILD, RFC-0003:C-RECIPE-COMPOSITION, RFC-0002:C-WORKSPACE-AUTHORITY, RFC-0003:C-RUNTIME-WORKFLOWS, RFC-0003:C-RESOLUTION, RFC-0005:C-EVIDENCE, RFC-0004:C-MEASUREMENTS, ADR-0070
Context
Section titled “Context”RFC-0007:C-IMAGE-BUILD establishes runtime-image production as a workflow separate from serving and recipe execution, with clean-by-default inputs, external model weights, content-closure reuse, and no registry push. Before implementation, the workflow’s declaration surface, command shape, builder scope, validation depth, context authorship, and artifact landing had to be decided. These decisions were confirmed with the project owner during design review and are reflected in the governing RFC; this ADR records the rationale and the rejected alternatives.
Runtime-image production can take two shapes: harness-generated runtime-only contexts (environment spec, locally built wheelhouse, entrypoint, provenance) built and scanned with import checks, or a typed artifact DAG with content-addressed package, build, and OCI nodes. InferLab provides the first capability without the DAG machinery (RFC-0001:C-SUMMARY).
Problem Statement
Section titled “Problem Statement”Runtime-image production must be a reproducible, shareable workspace fact that batches target platforms and model validations, deduplicates identical content closures, and yields validated evidence — without introducing a second configuration authority, a general artifact DAG, or a workspace-authored Dockerfile whose content closure InferLab cannot compute.
Constraints
Section titled “Constraints”- The Workspace Authority clause in RFC-0002 makes one versioned downstream workspace authoritative for source revisions, Pixi locks, integration selection, and named definitions; local bindings must not change collaborative behavior.
- The Recipe Composition clause keeps named configuration classes behind the recipe-first collaboration unit and forbids a public workflow DAG.
- The Runtime Workflows and Measurements clauses own server lifecycle and Eval/Bench semantics; one authority per fact forbids restating them for validation.
- ADR-0001 fixes the committed Pixi manifest and lock as the package authority.
- Model weights and credentials must never enter build contexts or shareable outputs.
- Available qualification hardware provides a local Docker daemon only; remote SSH builders and cross-platform emulation are not available for qualification.
Options Considered
Section titled “Options Considered”We considered where image requests are declared (named workspace definition, CLI-assembled request, recipe-attached output), how the command surface is shaped (one closed-loop command, split build/validate commands, exposed pipeline steps), who authors the build context (InferLab-generated, workspace-authored Dockerfile, hybrid fragments), how validation is expressed (recipe references, standalone validation declarations, container import checks), builder scope (local Docker now, SSH remote now, cross-build now), and artifact landing (daemon-default with optional export, always-export OCI archives).
Amended 2026-09-04: the implementation-notes rationale for the builder-tool seam originally claimed the trait exists “with deterministic fakes for fixture tests”. That was inaccurate: the fixture tests substitute a fake docker executable on PATH and exercise the real DockerBuilderTool, so the test suite never substitutes the trait. The seam’s actual basis is the deferred remote-builder direction recorded in this decision — the BuilderTool trait is the injection point an SSH remote builder would implement without changing the orchestration and evidence layer — and the corrected text below records that basis.
Amended 2026-10-28: the override semantics and feature-scoped composition in the activation-entrypoint implementation note are superseded by ADR-0070 and RFC-0007:C-IMAGE-BUILD 0.5.0. Composed activation scripts now run before projected variables, so the ${VAR:-...} form alone no longer gives the required precedence; the runtime-injection precedence it expressed is retained there.
Decision
Section titled “Decision”We will declare runtime images as the ninth named workspace configuration class, build them with one closed-loop image build command from InferLab-generated contexts, and validate them through recipe references on the local Docker builder.
This option was selected because:
- Shareable production unit: A named
imagedefinition makes image production a versioned workspace fact that collaborators build by name, matching the recipe-first collaboration model instead of unshareable CLI-assembled requests. - Product-oriented surface: One
image build <image-id>command executes resolution, assembly, inspection, requested export, and eligible validations as a closed loop with first-class dry-run, consistent withrecipe runand avoiding implementation-noun pipeline steps. - Computable content closure: InferLab generates the runtime-only build context from the committed Pixi lock, locally built framework packages, and the declared base image resolved to an immutable digest. The image content closure derives from those typed resolved facts (the workspace source identity of the required framework packages, the committed Pixi lock digest, the base-image digest, the entrypoint contract, and the package-build and context-generation procedure identities — built package content digests are execution evidence, not closure inputs) and, paired with the target platform, forms the deduplication key — making same-closure reuse verifiable and excluding weights and private workspace content by construction.
- One authority for validation facts: Model validation coordinates reference existing recipes and optional cases. Server topology, parallelism, and measurement selection stay owned by the recipe; image validation runs the same server and measurement lifecycle with server processes launched from the built image, so image results are directly comparable to host runs of the same recipe.
- Scope matched to available hardware: Only the local Docker builder is implemented now. Local bindings define the builder declaration shape so SSH remote builders can be added without changing workspace facts, but remote build and cross-platform emulation are deferred until real hardware and need exist.
- Iteration-friendly artifacts: Built images stay in the local daemon under a recorded immutable identity by default; OCI archive export happens on request or through configured artifact storage. Multi-gigabyte exports are not imposed on every development iteration.
Implementation Notes
Section titled “Implementation Notes”- Eligibility, outcome classification (built-but-unvalidated versus failed-assembly), failure isolation, and record obligations follow RFC-0007:C-IMAGE-BUILD; this ADR adds no requirements beyond that clause.
- Weights are mounted at validation time as external runtime inputs; the measurement toolchain continues to run from its release-owned installation against the container’s endpoint.
- The implementation keeps a strict closure discipline without a typed-DAG host: closure inputs are behavior-affecting facts only (explicit exclusion of builder hosts, workspace paths, weight locators, and model naming; base image pinned by digest; entrypoint contract hashed into the closure), the builder tool is an injected seam retained for the deferred SSH remote-builder direction (fixture tests substitute a fake
dockerexecutable onPATHrather than the trait), and context generation is leak-proof (hash-pinned locally built wheel bytes copied without host paths, plus a fail-closed gate that every required package is covered before rendering). - Portable outputs are guarded by construction and verified before assembly: generated contexts, image labels, and annotations are checked to carry no credentials, hosts, or local filesystem paths. The no-redaction stance of C-EVIDENCE continues to apply to local records only; portable outputs are held to the stricter by-construction guarantee.
- The activation entrypoint is projected from the workspace Pixi manifest’s activation tables — the single activation authority — composed feature-scoped for the selected environment, with override semantics: plain values export as
${VAR:-...}so runtime injection wins, self-referencing values compose through default-empty rewrites, and workspace-tree references ($PIXI_PROJECT_ROOT),CONDA_PREFIX, andCUDA_VISIBLE_DEVICESare skipped and recorded. The rendered script is hashed into the closure’s entrypoint contract. - Wheel builds run against sanitized copies of the owning source trees: committed content plus a materialized standalone git directory (exact SCM version derivation) with untracked build state cleaned, so package builds cannot mutate workspace source state and stale generator caches cannot leak in. Locally built wheels replace identically named locked upstream packages, keeping qualified images unmixed; companion distributions built from the same source tree (for example flashinfer-cubin) must be declared in the image’s package selection to be replaced, and the upstream wheels remain a host-side development convenience.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Image production is reproducible from the workspace revision plus local bindings, with no second configuration authority and no workspace-authored Dockerfile drift.
- Content-closure deduplication avoids redundant multi-model assemblies while every requested validation coordinate is retained.
- Validation results are directly comparable with host-process runs of the same recipe, because both consume identical recipe and measurement resolution.
- The command surface stays product-oriented and small; dry-run reports the full expansion before any external effect.
Negative
Section titled “Negative”- A ninth configuration class widens the workspace schema and required an RFC amendment; schema documentation and strict definition validation are the mitigation for the added comprehension burden.
- Generated contexts constrain image content to what InferLab knows how to derive; workspace-specific image customization needs a future deliberate extension rather than an escape hatch.
- Containerized validation adds a container-launched server path beside the host-process path; the mitigation is that both paths consume the same resolved execution object and lifecycle code, verified by cross-path record expectations in tests.
- Deferring SSH builders and cross-build means non-native platforms in a target batch are always built-but-unvalidated or unbuildable locally until a future release adds that capability.
- Daemon-default artifact landing depends on local Docker state; reproducing an exported artifact after daemon cleanup requires rebuilding from the workspace revision.
Neutral
Section titled “Neutral”- Validation depth in this iteration is qualified by deterministic fixtures and manual end-to-end coverage rather than real multi-platform hardware; broader platform coverage arrives with future builder work.
- Registry distribution remains out of scope by clause; the workflow ends at local or configured artifact storage plus a product manifest.
Alternatives Considered
Section titled “Alternatives Considered”Declare images as the ninth named workspace definition, build with one closed-loop image build command from InferLab-generated lock-derived contexts, validate through recipe references, and keep images in the local daemon by default with optional OCI export (accepted)
Section titled “Declare images as the ninth named workspace definition, build with one closed-loop image build command from InferLab-generated lock-derived contexts, validate through recipe references, and keep images in the local daemon by default with optional OCI export (accepted)”- Pros: Image production becomes a versioned, shareable workspace fact collaborators reproduce by name, Content closure derives from typed resolved facts, making deduplication reliable and excluding weights by construction, Recipe references keep one authority for server and measurement configuration and make image results comparable to host runs, Daemon-default landing avoids multi-gigabyte exports on ordinary iterations
- Cons: A ninth configuration class widens the workspace schema and requires an RFC amendment, Generated contexts limit image content to what InferLab can derive
Assemble image requests from CLI flags over existing definitions without a new configuration class (rejected)
Section titled “Assemble image requests from CLI flags over existing definitions without a new configuration class (rejected)”- Pros: Smallest specification change
- Cons: Image requests are not durably shareable or reproducible from the workspace revision
- Rejected because: Image production must be a versioned workspace fact reproducible by name, matching the recipe-first collaboration model.
Let the workspace author and commit a Dockerfile that InferLab invokes (rejected)
Section titled “Let the workspace author and commit a Dockerfile that InferLab invokes (rejected)”- Pros: Maximum content flexibility with no generator to maintain
- Cons: Content closure degrades to a coarse Dockerfile-plus-context digest, Weight and private-content exclusion becomes after-the-fact scanning instead of construction-time guarantee
- Rejected because: An authored Dockerfile makes the image content closure incomputable and the clean-input guarantee unverifiable by construction.
Expose pipeline steps (context, build, scan, export) as public commands (rejected)
Section titled “Expose pipeline steps (context, build, scan, export) as public commands (rejected)”- Pros: Fine-grained operator control over each stage
- Cons: Promotes implementation nouns into public commands and multiplies surfaces that must stay consistent
- Rejected because: One closed-loop command with first-class dry-run covers the operator need; step commands violate the product-oriented command principle.
Declare standalone validation coordinates with model, serve profile, and measurements inside the image definition (rejected)
Section titled “Declare standalone validation coordinates with model, serve profile, and measurements inside the image definition (rejected)”- Pros: Image validation evolves independently of recipes
- Cons: Restates server and measurement facts that recipes already own, so the two authorities drift
- Rejected because: Violates one authority per fact; recipe references keep image validation identical to host recipe execution.
Implement SSH remote builders and cross-platform emulation in this iteration (rejected)
Section titled “Implement SSH remote builders and cross-platform emulation in this iteration (rejected)”- Pros: Full remote and cross-platform builder capability immediately
- Cons: No remote or non-native hardware is available to qualify the paths, Remote build provenance and cleanup semantics would be designed without a consumer
- Rejected because: Deferred until hardware and need exist; local bindings already reserve the builder declaration shape so workspace facts stay stable.
Attach image production to recipes as a recipe output form (rejected)
Section titled “Attach image production to recipes as a recipe output form (rejected)”- Pros: No new configuration class
- Cons: A recipe identifies one eval and bench protocol while an image batches platforms and validation coordinates across recipes, Couples image lifecycle to serving lifecycle against the separate-workflow clause
- Rejected because: RFC-0007:C-IMAGE-BUILD requires image production to be a workflow separate from serving and recipe lifecycles; the cardinalities do not match.
Split the surface into separate build and validate commands (rejected)
Section titled “Split the surface into separate build and validate commands (rejected)”- Pros: Makes the built-to-validated state transition an explicit operator step
- Cons: The ordinary path needs two invocations and intermediate bookkeeping
- Rejected because: The closed loop already records built-but-unvalidated outcomes per coordinate, preserving the state distinction without a second required command.
Generate a base context but let the workspace inject authored fragments (rejected)
Section titled “Generate a base context but let the workspace inject authored fragments (rejected)”- Pros: Escape hatch for workspace-specific image content
- Cons: Authored fragments reintroduce content the generator cannot derive, weakening closure identity and clean-input guarantees
- Rejected because: No concrete workflow demonstrates the need; a deliberate extension can be added when one does.
Always export an OCI archive on every build (rejected)
Section titled “Always export an OCI archive on every build (rejected)”- Pros: Artifacts are self-contained and independent of daemon state
- Cons: Imposes multi-gigabyte export cost on every development iteration
- Rejected because: Daemon-default landing with on-request export serves iteration and hand-off without per-build export cost.
Validate images with in-container import checks only, without launching a server (rejected)
Section titled “Validate images with in-container import checks only, without launching a server (rejected)”- Pros: Cheapest validation with no GPU or weights requirement
- Cons: Never exercises the serving entrypoint, topology, or measurement path the image exists to provide
- Rejected because: RFC-0007:C-IMAGE-BUILD requires image validation to reuse the recipe server and measurement lifecycle; import checks alone cannot satisfy that obligation.