Skip to content

Specification · RFC

RFC-0007: Runtime Image Production Contract

Version: 0.5.0 | Status: normative | Phase: impl Owners: @Zihua Wu


[RFC-0007:C-SUMMARY] Summary (Informative)

Section titled “[RFC-0007:C-SUMMARY] Summary (Informative) ”

This RFC governs runtime image production: building validated OCI images from one named stack, content-closure reuse, recipe-and-server-case validation, local placement eligibility, and artifact landing. RFC-0001 holds the specification overview and authority map.

Since: v0.1.0


[RFC-0007:C-IMAGE-BUILD] Runtime Image Production Boundary (Normative)

Section titled “[RFC-0007:C-IMAGE-BUILD] Runtime Image Production Boundary (Normative) ”

InferLab MUST support runtime-image production as a workflow separate from the long-running server and closed-loop recipe lifecycles.

An image definition MUST identify one reproducible runtime-image unit with exactly one stack, one base_image, one or more platforms, optional packages drawn only from that stack’s source_paths, and zero or more validations. When the package subset is omitted, every stack source_paths entry is selected. A stack with no source paths therefore supports only an empty local-package selection.

Each validation MUST name one recipe and MAY name server_case for that recipe’s server. When server_case is omitted, the server’s normal case-selection rule applies. The referenced server stack MUST equal the image stack. A validation MUST NOT restate server, placement, model locator, or measurement configuration.

Runtime-image production MUST use the selected stack, workspace source state, Pixi lock, integration selection, local builder and placement bindings, and evidence facilities defined by this specification where those facts apply.

A runtime-image build MUST reject a dirty workspace.

Every referenced stack, recipe, server, server case, package path, placement, and builder binding MUST be structurally valid before the first state-affecting external command. A missing reference, invalid explicit case, package outside the image stack’s source paths, selected package path inside which the stack’s Pixi environment installs no source-backed project, or server/image stack mismatch MUST fail the image build before a record or builder effect.

The public runtime CLI MUST provide image build <image> with optional --builder, --placement, --export, --local, and --dry-run. It MUST execute resolution, assembly, inspection, requested export, and eligible validations as one closed-loop workflow.

A non-dry-run image build MUST report the record identity on the operator diagnostic stream as soon as the record exists, and MUST report each package build, assembly, inspection, export, and validation phase as it begins, including the durable log path where one exists. Machine-readable output MUST remain a single final report.

image build MUST support dry-run. Dry-run MUST report each target platform, content-closure identity, assembly deduplication plan, resolution observations, selected placement when applicable, and each validation eligibility classification. It MUST NOT assemble, export, launch validation servers, execute stack checks, or create a record claiming execution.

InferLab MUST generate the image build context from resolved stack facts: the committed Pixi lock, locally built selected packages, and resolved base image. Image production MUST NOT require authored container build files. The frozen context MUST contain only generated build files, selected-stack check and postprocess scripts, projected activation scripts, and packaged artifacts; package scratch, sanitized source copies, and durable logs MUST remain outside. Failure to remove sanitized copies MUST fail assembly and be preserved even when another failure is primary.

Image resolution MUST resolve the declared base image to an immutable per-platform image digest before assembly.

Image resolution MUST scope the assembly plan to the declared target platforms the selected builder can produce. An unproducible platform MUST be excluded before its content closure is derived and MUST be reported with a reason in dry-run output, the execution record, and the product manifest; exclusion is not a failure. When the selected builder can produce none of the declared platforms, resolution MUST fail.

Every packages entry MUST equal one path in the image stack’s source_paths. A selected package path MUST produce one locally built package for each source-backed project that the stack’s Pixi environment installs from inside that path, built at the project directory reported by Pixi within the sanitized source copy; the selected path’s committed identity is unchanged. The environment listing MUST be read from the committed lock without re-solving or installing. A source-backed project is a locked PyPI entry without a registry hash whose location is a workspace-relative path; a location with a URL scheme is never a source-backed project. Dry-run MUST report the derived project directories. Source paths consumed only at build time remain inputs without producing their own wheel.

Before building any required package, a non-dry-run image build MUST execute the selected stack checks against its local Pixi realization (RFC-0002:C-ENVIRONMENT-CHECKS). Failure MUST abort before package build, present the repair hint for a check verdict, finalize the record, and still emit the single failed machine-readable report.

Runtime-image production MUST build required packages from the resolved stack source state and fail before assembly when one cannot be produced. Reuse is allowed only when committed source identity, the built project directory, the stack’s Pixi environment locked closure, editable-package content outside selected source paths, projected activation including the content and order of projected activation scripts, generator and build-procedure identity, and target platform are unchanged. Cache publication MUST be private-staged, atomic, and immutable; a race adopts the existing artifact. Built package content digests and logs are execution evidence, and package payloads MUST NOT remain in a successful build context and MUST NOT enter the image except as installed packages.

A locally built package MUST replace the identically named locked upstream package in the image content, so an image never mixes locally built sources with their lagging upstream releases.

Package builds MUST run in a clean process environment — only the activation Pixi applies to the stack’s local environment (composed manifest activation and package-provided activation scripts), a fixed system-utility path suffix, and sanitized-view redirects reach the build — and MUST use sanitized copies of the selected stack source paths, with build-time source references redirected into that view. An activation value carrying more than one workspace-root reference MUST be rejected rather than partially redirected. Activation projection MUST compose the activation variables and activation scripts the selected stack Pixi environment applies on the target platform, including activation declared directly on the environment and under the target selectors Pixi applies to that platform. Composition MUST match observed Pixi behavior, which this specification records as follows. Composed sources are ordered as activation declared on the environment, then its features in listed order, then the default feature unless the environment excludes it. Within one source, the script list comes from the most specific of the platform name, linux, unix, and the untargeted table that declares scripts; activation variables merge across all applicable selectors and the untargeted table, and a more specific declaration overrides a less specific one for the same name. Activation scripts run in source order, each observing the exports of the scripts before it; when more than one source declares the same activation variable, the earliest source supplies its value. A divergence in later Pixi behavior is a change to this contract. Activation the environment does not compose is inert. Each composed activation script (a projected activation script) MUST be a workspace-relative path to a regular file tracked at the resolved workspace revision, and its text MUST NOT contain PIXI_PROJECT_ROOT or the absolute workspace root; a script failing either condition MUST be rejected at image resolution, in dry-run as well, before any builder effect. Only the content of each declared script file is projected; files a script sources or executes are not. Package builds receive activation as Pixi applies it to the stack’s local environment, including package-provided activation scripts; values that activation scripts export there are not redirected into the sanitized view, and package verification and the workspace mutation audit apply to their effects. InferLab MUST audit workspace source mutation after package builds whether or not the build succeeded, fail assembly while recording mutated paths, preserve the build failure when both occurred, and never clean or revert the workspace. An audit that cannot execute MUST itself fail assembly while preserving the build outcome.

Package builds MUST map the sanitized source tree, the selected stack’s Pixi environment prefix, and the workspace root to fixed InferLab-defined paths that are independent of the builder host, user, and checkout location, through the path-mapping options of the C, C++, and CUDA compilers reached by the package build’s activation. A freshly built package MUST then be made path-neutral and verified before it is cached or assembled. Library search paths naming the stack’s Pixi environment prefix MUST be rewritten to the image environment prefix, the prefix at which the image installs the selected Pixi environment, with their search-path kind preserved; remaining search paths naming the workspace, a package-build directory, or the host home directory MUST be removed. The package MUST then be verified to contain no workspace root, selected stack Pixi environment prefix, host home-directory path, or path of a directory InferLab creates for the package build (sanitized source copy, package scratch, and build output). Verification covers every member as stored, every compressed ELF section decoded, and the device code extracted from every fatbin; a match MUST fail the package naming the member, and a compressed section or fatbin that cannot be decoded MUST fail it as well. Content compressed in other formats inside a member is verified only as stored. The rewriting and verification tools MUST come from the image-packaging runtime of the InferLab toolchain (RFC-0004:C-INFERLAB-TOOLCHAIN). An image build, dry-run or not, whose selection includes at least one package MUST fail before a record or builder effect, identifying inferlab toolchain install, when that runtime is missing or incomplete. Package evidence MUST include the activation environment the package build received, the image-packaging runtime identity, the applied path maps, the rewritten and removed search paths, and the verification outcome. Whether built packages carry debug information remains the workspace’s build configuration.

Image assembly MUST execute the selected stack image-realization postprocess steps and then its checks inside the image build, after environment installation, through the image entrypoint (RFC-0002:C-ENVIRONMENT-CHECKS). A failed check MUST fail assembly before an immutable image identity exists, so builder storage, reuse, export, and product manifest never observe an unchecked image. The durable builder log MUST attribute every executed check and outcome.

A built image’s entrypoint MUST reproduce the selected environment’s composed manifest activation for every process it starts. Projected activation scripts MUST be sourced by bash in composition order, so their exports reach later scripts and the command; while they run, CONDA_PREFIX is the image environment prefix, PATH begins with that prefix’s executable directory, PIXI_PROJECT_ROOT is unset, and projected activation variables are not yet visible. Projected activation variables MUST then take effect with these outcomes: a value that does not reference its own variable replaces what the scripts left, unless that variable was already set to a non-empty value when the entrypoint started, whether supplied at container start or set by the image configuration, in which case the variable keeps what the scripts left from that value; and a value that references variables expands against the environment the scripts left, not against other projected values. Every variable InferLab manages inside the container — CONDA_PREFIX, CUDA_DEVICE_ORDER, CUDA_VISIBLE_DEVICES, HOME, USER, and LOGNAME, the set that pass-through declarations may not name — MUST hold after activation the value InferLab supplied for it; a managed variable InferLab did not supply keeps what the scripts left. A projected script that ends the activation shell with a non-zero status, through exit or a failing command under set -e, MUST make the entrypoint exit with a non-zero status without running the command, naming the script on the diagnostic stream; as in Pixi, neither the status of a script’s last command nor a return status is a failure. The outcome of a projected script invoking exit with status zero is unspecified. Package-provided activation scripts installed in the environment, such as conda etc/conda/activate.d scripts, are not executed by the entrypoint. When an image projects activation scripts, assembly MUST perform its activation once inside the image build environment and fail before an immutable image identity exists if that activation fails or bash is unavailable, with the durable builder log attributing the failure. Activation performed during assembly MUST NOT persist into image configuration; image content that activation scripts produce during assembly is the workspace author’s responsibility under the committed-content posture.

The resolved image content closure MUST derive from pre-assembly facts: selected stack identity, required package source identity, committed Pixi lock digest and selected Pixi environment, resolved base-image digest, generated entrypoint, projected activation script content and order, selected stack check and postprocess content, generator identity, and package-build and context-generation procedure identities. The package-build procedure identity MUST enter package reuse and closure identity. Built package digests are execution evidence, not closure inputs. The closure MUST NOT incorporate builder hosts, workspace paths, placements, machine bindings, model-weight locators, or validations.

Model weights MUST remain external runtime inputs. An image build MUST NOT copy model weights or model-weight locators into its build context or output.

Builder hosts, machine names, local filesystem paths, and the machine-private facts known to resolution MUST NOT enter generated build-context text, image configuration, or OCI metadata, including image labels and annotations. Locally built packages are held to the same exclusion through path mapping and package verification rather than through text verification. Generated context text MUST be verified before assembly against the machine-private facts known to resolution and against host home-directory paths; activation values that would escape the entrypoint’s quoting MUST be rejected. Activation variables whose names identify credential material MUST be excluded from the projected entrypoint and recorded as excluded; this name-based exclusion is best-effort protection for committed workspace content, whose freedom from secrets remains the workspace author’s responsibility. Declared check and postprocess scripts and projected activation scripts copied into the context are committed workspace content under that same posture. InferLab does not promise secret scanning of committed manifests, locks, or package URLs. The no-redaction evidence contract of this specification applies to local execution records; portable image artifacts MUST exclude machine-private facts from generated text, metadata, and locally built packages by construction.

Local bindings MAY declare container environment pass-through variable names per machine. Declared names MUST be validated when bindings load: a name that is not a POSIX shell identifier, a duplicate, or a name InferLab itself manages inside the container MUST be rejected — the launch scripts splice these names into shell parameter references, where anything beyond an identifier can carry expansion side effects, and a non-identifier name could not be referenced by the channel at all. A validation container MUST receive each declared variable by name reference only, so its value never enters the launch command line or the image content; a declared variable absent from the launching environment MUST be reported. The local execution record preserves the launch command as executed.

Local bindings MAY also declare per-machine container hardware facts for that same containerized substitution: host device paths, an unlimited pinned-memory ulimit, and Linux capabilities. These facts are operator-declared and MUST NOT be auto-detected. Declarations MUST be validated when bindings load: a device path that is not absolute, a duplicate device, a capability outside the fixed set InferLab recognizes, or a duplicate capability MUST be rejected. A validation container MUST receive each declared device, the declared ulimit, and each declared capability; a containerized launch MUST NOT request privileged mode. Container hardware facts are runtime launch facts: they MUST NOT enter image content, content closures, or portable artifacts.

Within one image build invocation, equal content closure and target platform MUST reuse one assembly even when several validations consume it.

The immutable image identity MUST enter the assembly evidence the moment the builder returns it, so a later cleanup, inspection, or export failure cannot lose which image the assembly produced. Image inspection MUST establish and record the immutable image identity and the entrypoint contract of the built artifact.

Every validation in one invocation MUST use the same placement selected by --placement or the normal local placement-selection rule; InferLab MUST NOT choose a placement per validation. Validation MUST reuse the referenced server and case resolution, readiness, workload-suite measurement, evidence, and cleanup semantics, with the built image substituting for the local stack realization.

A validation is eligible for a target platform only when that platform matches the selected local builder host, the selected placement can realize every server rank on that host without semantic incompatibility, and a model locator resolves for every model-serving rank. Eligible validations run against that platform’s assembled image.

An ineligible validation MUST be recorded as built-but-unvalidated with its reason, not failed. A validation whose target-platform assembly failed MUST record failed-assembly, not built-but-unvalidated. Once eligible validation execution begins, a server, readiness, measurement, or cleanup failure MUST record a failed validation.

A failed assembly or validation for one platform or validation MUST NOT prevent other requested platforms or validations from completing.

Builder selection MUST be deterministic. When local bindings declare more than one builder, the invocation MUST select one explicitly.

Built images MUST remain in local builder storage under a recorded immutable image identity by default. An operator MUST be able to request export to a local OCI archive. Each exported archive path MUST be unique to its producing record, so no repeated or concurrent build overwrites another record’s artifact evidence. Configured artifact storage MAY receive exported artifacts.

The image-production workflow defined by this specification MUST stop at local or configured artifact storage and a product manifest. The image-production workflow MUST NOT push images to a registry.

The product manifest MUST map each requested platform and validation to image identity, equal-closure deduplication, produced artifacts, validation references, eligibility and execution outcomes, and complete or partial workflow outcome.

Dry-run output and image records MUST list the projected activation scripts in composition order with their content digests. Image records MUST preserve build inputs, selected stack and placement, native builder commands, immutable image identity, inspection and export evidence, stack-check outcomes for every realization, validation outcomes, partial failures, and cleanup. Read-only builder-platform and base-image-digest probes MUST be recorded with exact commands in the resolved plan. Every state-affecting builder command MUST be persisted before execution and equal the executed command.

Rationale: Multi-platform and multi-model image output is an established product goal, but it does not require runtime serving and recipe execution to share a general operation DAG. A named image definition keeps image production a shareable workspace fact, recipe-referenced validation keeps one authority for server and measurement configuration, and a content closure derived only from generated, digest-pinned inputs makes deduplication verifiable while excluding weights and private facts by construction. Records stay honest locally while the generated text, metadata, and built packages that leave the machine carry no machine-private facts: evidence is preserved where it is private, and excluded where it is portable. The portability promises are sized to what the tool can actually enforce — fail-closed verification for facts InferLab knows, best-effort exclusion for committed content, sanitized views plus mutation detection instead of an unenforceable no-mutation absolute — because a guarantee the mechanism cannot honor is worse than a narrower one it can. Clean-only image inputs protect reproducible artifacts, and external weights with content-based reuse keep image outputs portable and avoid redundant assembly. Projected activation scripts carry host-dependent activation, such as a driver-conditional library path, that static values cannot express; executing them for every process the image starts keeps one activation authority between host and image runs. Entry checks price a doomed build at seconds instead of an hour, and in-image checks executed as build steps mean an image that exists has passed its declared invariants — no unverified artifact can be cached, exported, or validated. Declared container hardware facts keep RDMA-dependent serving launchable in containers — pinned memory, InfiniBand and GPUDirect device nodes — while the operator states exactly what each host grants: no auto-detection to guess wrong, no privileged mode to grant everything, and no machine facts leaking into portable artifacts.

Since: v0.1.0