Skip to content

Decision record · ADR

ADR-0051: Derive image package build directories from the stack's Pixi source-backed projects

Status: accepted | Date: 2026-09-27

References: RFC-0007, RFC-0002, ADR-0005

An image selects local packages by naming stack source paths, and image assembly builds one wheel at the root of each selected path. Some engines keep their Python project below the repository root. SGLang’s project lives in python/, so when SGLang is a git submodule, its runtime image cannot be assembled. Naming the submodule builds a directory with no project metadata. Naming sglang/python as a source path fails source identity, because the superproject tree holds only a gitlink at sglang. A downstream workspace worked around this by carrying a tooling-only commit in its SGLang fork: a repository-root PEP 517 backend that delegates to python/.

The build directory is already a recorded fact. For the stack environment to install SGLang at all, the workspace Pixi manifest declares it as a path dependency on sglang/python, and pixi list reports each source-backed project with its workspace-relative path. In the downstream SGLang environment, the three source-backed projects (./sglang/python, ./DeepGEMM-sglang, ./flashinfer) correspond one-to-one to the image’s three selected source paths. Another source path in the same workspace had earlier been split into a nested project (flashinfer/flashinfer-cubin), so one source path can hold more than one project.

A selected image package path builds one wheel for each source-backed project that the stack’s Pixi environment installs from inside that path, at the project directory Pixi reports. The selected path keeps its role as the source-path unit: its committed identity, its sanitized copy, and its place in the record are unchanged, and the build runs inside the sanitized source copy. A selected path inside which the environment installs no source-backed project fails image resolution, because a wheel with no counterpart in the stack environment would make the image diverge from the environment it claims to realize.

A source-backed project is a PyPI entry with no registry hash whose location is a workspace-relative path; entries with a URL scheme are never treated as local projects. The listing is read with --locked --no-install, so resolution reads the committed lock and never rewrites it. The derived project directories enter the image plan, dry-run output, wheel reuse identity, and content closure. No workspace configuration field is added: the Pixi manifest remains the one authority for where each project lives.

This refines ADR-0005’s consequence that a companion distribution must be declared in the image package selection to be replaced. A companion that is a source-backed project inside a selected path is now built without its own declaration, and a registry-installed companion can no longer be replaced by selecting a path the environment does not install from.

Positive: submodule engines whose Python project sits below the repository root assemble without configuration or fork patches, and the image always builds exactly the projects the stack environment installs, including several projects under one source path. Dry-run shows the derived build directories before any build.

Negative: image resolution now reads the locked environment listing (pixi list --locked --no-install), one more Pixi invocation before the record exists. A workspace that selected a package path the environment does not install from source, relying on the old root build replacing a registry release, now fails resolution and must either install that path from source or drop it from packages.

Neutral: RFC-0007:C-IMAGE-BUILD needs an amendment that ties package builds to the environment’s source-backed projects and adds the resolution failure.

Derive build directories from the source-backed projects Pixi installs inside each selected source path, and fail when a selected path contains none (accepted)

Section titled “Derive build directories from the source-backed projects Pixi installs inside each selected source path, and fail when a selected path contains none (accepted)”
  • Pros: No new configuration; the Pixi manifest stays the single authority for project locations, Covers several projects under one source path without extra entries
  • Cons: Selecting a path the environment does not install from source becomes a resolution error

Let an image package entry declare a build subdirectory, for example { path = “sglang”, subdirectory = “python” } (rejected)

Section titled “Let an image package entry declare a build subdirectory, for example { path = “sglang”, subdirectory = “python” } (rejected)”
  • Pros: Mirrors pip and uv #subdirectory= requirement syntax
  • Cons: Restates the project location the Pixi manifest already declares, in every image that packages it, where the two can drift

Keep root builds and require engines to carry a repository-root build entry point (rejected)

Section titled “Keep root builds and require engines to carry a repository-root build entry point (rejected)”
  • Pros: No InferLab change
  • Cons: Forces a tooling-only fork patch on every engine whose project is not at its repository root