Consolidate tool catalog and pinned delivery contracts before adding uv delivery

Author versions once in the own provisioner's portable artifact and Python definitions. Derive or check public delivery metadata from those owners. Provision tools before use, then execute their prepared commands directly.

Several configuration files in one understandable directory are acceptable. We do not require a universal manifest or identical formats for native tools and Python dependencies.

This is the shared architecture. The provisioning choice determines how the producer realizes and maintains it; it should not leak into every consumer invocation.

Shared complexity, finished-system complexity and migration delta

The existing implementation is not a free or universally understood baseline. Most contributors must learn it before changing it. The same applies to its custom scripts, artifact layout assumptions and version/update behavior, not only to a new manager.

We therefore ask two separate questions:

1. Finished-system complexity: after cleanup, what must someone understand, maintain and operate? Count existing code retained by the own variant as fully as new manager integration.
2. Migration delta: what must we add, change and remove relative to today's setup? Reuse helps here, but this one-time advantage is not a permanent maintenance score.

Common duties are version ownership, selections, Ubuntu/providers, public compatibility, release binding, normal Python dependency metadata and drift checks. Their implementations can change; they cannot simply be declared absent because a manager is used. Conversely, a manager can remove an existing duty by genuinely replacing its mechanism.

Final responsibilities and concrete evidence

Basis and corrections for the 1–5 ratings

Higher numbers mean less SCORE complexity for that row. They are ordinal assessments, not measurements of hours, learning speed or lifetime defect rates. The two best scores differ: 5 directly reuses a shared mechanism with almost no extra layer for the duty; 4 still needs setup/integration. The middle score means bounded custom logic; 2 means additional representations/input coordination; 1 means broad operating machinery. Colors are only visual aids.

• Download/unpacking: 3 / 4 / 4 / 4. The own option retains the engine, which contributors must understand. Managers delegate it; they still need setup and integration. Existing code receives no discount for being old.
• Version change: 4 / 4 / 4 / 2. The executed own/mise/Aqua updates were one intended version decision followed by normal refresh/check operations. The previous own score of 3 was insufficiently justified and is corrected. All retain portable archive-layout assumptions. The tested Nix isolated change required finding/selecting an independent package input; that discovery was supplied, not automated.
• Current inventory exceptions: 4 / 4 / 3 / 3. Own's generic extraction/adjacent-command handling covers the tested inputs without additional per-tool installer code; its artifact descriptions are still maintained. mise's backend coverage avoids the local registry recipes needed by Aqua. Nix has a custom OpenCode derivation. This is a narrow inventory observation, not evidence about every future tool or registry.
• Bazel alignment: 5 / 3 / 3 / 2. Own directly reuses the existing portable owner. mise/Aqua maintain translation from manager records. Nix needs portable information separately from its package/store metadata. All still maintain public selection/label policy.
• Delivery machinery: 4 / 3 / 3 / 1. Own has prepared-state/link machinery, not zero infrastructure. mise/Aqua also operate manager preparation/bootstrap and expose selected output. The current Nix implementation realizes/transfers/activates closures beside Ubuntu providers. This row judges delivery state/operations, not contributor familiarity or one-time migration cost. Nix's runtime composition is a benefit of its broader model.

The old “new knowledge” row is removed: it mixed migration with ongoing complexity and favored the own solution because it already existed. We have not measured contributor onboarding for any option. Learning existing custom code and learning an external model both count.

Migration delta: additions and deletions

These changes were implemented locally, not estimated from manager marketing. They do not establish person-hours. Automatic host uninstall/repair/rollback is out of scope; optional prototype mechanisms do not create adoption gates.

Recorded decision and implementation principle

We choose consolidated own provisioning. Its direct reuse of Bazel artifact definitions and one shared installer fit the confirmed scope better than the demonstrated extra integration of another manager. This does not make its custom engine/state free to maintain or imply that it wins every dimension.

Where equally simple choices are available, prefer patterns and conventions similar to Aqua/mise. Clear declarative definitions and separation of definitions from installation are useful examples. Extra schemas, adapters or feature work solely to resemble those tools are outside that preference.

Use the own implementation as the target; retain other variants as historical evaluation, not ongoing production alternatives. The main remaining validation boundaries are full ARM64 image, actual macOS use and public release distribution. Peer Codespell selection/initial pins differ from the own baseline; the comparison covers common contracts.

Option 4 is now a maintained local implementation, not only the earlier small control. It uses the existing native artifact files and literal Python catalog as owners. The native definition also feeds the ordinary Ruff dependency extra; uv/uvx supplies Ruff without a SCORE launcher.

Implemented boundaries:

• One shared downloader/checksum/file/archive installer used by both container and host. The old duplicate container extraction path was removed; APT/npm/provider setup remains.
• Commands from the same archive are prepared together so uvx can find adjacent uv. Python environments use ordinary uv and retain their interpreter dependency; they are not relocatable Nix-like closures.
• Content-keyed prepared trees, completion markers, a prefix lock and direct links. Updates preserve unrelated files and reject user-replaced command conflicts. Existing installations are not automatically adopted; migration uses a fresh prefix.
• Generated/checkable inventory and native Bazel registrations. Removing an owner and its selections stops offering it in new outputs. No automatic host uninstall or ownership database.
• Ordinary release build/check with explicit identity/version, owner hashes, wheel binding and exact generated dependencies. Stale owners/metadata, old-release/new-owner mismatch and changed wheel bytes are rejected.

Executed release proof: A is facade 0.8.0 / Ruff 0.11.13; B is 0.8.1 / Ruff 0.14.6. The same uv project changes only its facade release; real uv and uvx resolve Ruff. The same native prefix updates Ruff while preserving Buildifier and a user file. The public //tools:ruff executes B, preserves a relative spaced filename and returns the expected lint failure. Production owner pins were not changed.

The installer retains archive/platform upkeep. Incomplete Python preparation requires a fresh data directory; prepared trees are trusted rather than rehashed on every call. No whole-profile transaction, rollback or garbage collection is promised. These limits should be judged against the agreed scope, not expanded into requirements merely because another prototype implements them.

The earlier ShellCheck update/control and local mirror recovery are historical supporting experiments. The current report additionally includes actual complete amd64-image and ARM64 prepared-tool execution on original artifact URLs.

All three manager implementations remove the old native archive installation and Python tool installation paths from tools/internal/devcontainer/install.py, including its install and install-python subcommands. Production code no longer depends on experimental paths.

The remaining module is not metadata-only: it still performs selected APT/npm provider setup and supplies selection/metadata queries and verification. Ubuntu/APT lifecycle, Java, CodeQL and specialized features remain intentional responsibilities.

Every candidate still needs:

• Public tool, command and Python-extra identities; published/repository selections and any alias policy.
• Generated or checked inventory, registrations and drift detection.
• Portable upstream URL/hash/archive-layout metadata for existing simple Bazel targets.
• Release binding and ordinary Python dependency-package generation/checking.
• Bootstrap, platform exceptions and integration with container setup, repository post-create and updates.

Historical extra functionality, not a requirement: mise and Aqua additionally retain SCORE-owned prefix reconciliation. This protects other selections and user-owned files when commands are removed. Nix supplies the profile membership replacement mechanism; SCORE still chooses the profile contents and maintains compatibility exports. These are different responsibility boundaries. This cleanup functionality must not count as a mandatory feature or penalize an option that does not implement it. Existing prototype code can be simplified accordingly.

The comparison also led to concrete fixes: mise stale-lock rejection now survives optimized Python, its uv backend resolves the actual prepared uv executable, and Aqua promotes only selected commands so a transitive gh executable does not shadow the existing system command. Nix gained explicit producer/target handling and removed an obsolete standalone comparison Dockerfile. Those completed fixes should not be counted as work recurring on every version update.

Inventory examples

Starpls at the selected release was covered by mise's generic GitHub backend and the locked Nixpkgs package, but required a local Aqua registry recipe. APM required preserving its adjacent runtime/data tree; Aqua uses a local recipe for that layout. The selected OpenCode needed a custom Nix derivation/runtime handling. These are observations about this inventory, not claims about universal registry coverage.

The command-removal and recovery investigations explored additional behavior. Neither automatic uninstall of existing host tools nor installed-tree repair is a prerequisite for offering the tools.

Historical bounded recovery comparison

A separate single-tool Linux amd64 probe distinguishes optional recovery capabilities from the core requirements:

These are historical bounded experiments, not current end-to-end recovery guarantees for every tool or tests of the later maintained own implementation. All options still need a deliberate cache/mirror retention and distribution policy. Nix's installed-tree verification is a distinct benefit; it is not required on every tool call. The trusted-container execution contract remains unchanged.

The following deletion observations concern optional cleanup, not removing a tool from our offering. Earlier fixed-directory deletion probes exposed stale commands in mise/Aqua copied exports. Later implementations added SCORE prefix reconciliation; those early failures must not be presented as their final status. Nix already supplies native profile membership replacement.

All four candidates completed the following local sequence through maintained tooling:

1. Produce release A from its current owners.
2. Change the Ruff version in an isolated source copy; demonstrate rejection of stale generated data.
3. Use the normal refresh/export/inventory operations and produce owner-bound release B.
4. Reject the A artifact against the B owners.
5. Update the same independent uv project from A to B by changing only its SCORE dependency release. Resolve and run Ruff through ordinary uv and uvx, with no consumer-authored Ruff pin.
6. Update the same native prefix/profile, preserving an unrelated selected tool and a user-owned sentinel.
7. Run the updated public //tools:ruff target, including a relative filename containing spaces and an expected nonzero lint exit.

The local facade releases were 0.8.0 and 0.8.1; B selected Ruff 0.14.6. The starting versions differed: own/mise 0.11.13, Aqua 0.11.12 and Nix 0.17.2. The Nix case was therefore a downgrade, not an upgrade. These were fixtures, not a chosen public package API. The target version and historical Nix input were already known; this was not arbitrary version discovery.

Aqua's recopy/reinstall behavior is the current SCORE adapter's implementation, not an inherent Aqua limitation or a performance measurement. Nix's tested profile update also considers independently updatable foreign entries; preservation of every possible foreign flake entry was not established.

The native updates and ordinary uv consumers are separate outputs from the same authority. Installing the dependency facade is not the mechanism for installing a native manager profile.

All four have substantial local implementations. None is a completed upstream production migration. Tests are bound to recorded source snapshots; the table does not assert identical inventories, initial versions or transitive environments.

The retained ARM Bazel provider was separately exercised after the download failure: real Bazel 8.6.0 downloaded and ran under ARM QEMU, then ran again offline from its cache. That diagnoses the failure without claiming a complete image or suite pass.

The peers' ARM selection also included Codespell; it was not silently added to the own baseline. Their full integration checkpoint predates later targeted fixes, which received affected regressions rather than a full repeated image suite. Own's new amd64 gate is bound to its current implementation. These source boundaries remain explicit.

Parent review, separately from Copilot's report

The parent inspected the maintained provisioning, package build/check, catalog/registration code and relevant regressions. It independently:

• Reran 45 unit tests and generated inventory/registration checking: passed.
• Verified 99 archived file hashes/sizes and 48 current-source hashes, source snapshots and recorded integration bindings: passed.
• Inspected both actual wheel dependency records: A selects Ruff 0.11.13, B 0.14.6, with explicit facade identities/releases.
• Reran the prepared amd64 runtime as uid 1000, network disabled, read-only root/prefix: 16 direct/strict pairs, two behavior tests and three LSP exchanges passed, with no manager/Bazel interception.

This is focused independent review, not a second full build, an exhaustive audit or native hardware validation. Source and checked-in evidence snapshots are linked above; additional full logs/runtime payloads remain local. This issue does not imply published reproducibility. No hosted release, full offline acquisition or fully locked build toolchain is established.

The architecture decision is recorded below. The remaining boxes track landed and supported upstream behavior, not whether an equivalent local experiment passed. The foundation must land before downstream adoption of #189; consumer validation can proceed in parallel.

• Choose consolidated own provisioning; prefer Aqua/mise-like design patterns when they add no implementation or maintenance effort.
• Land the authoritative own-provisioning definitions and explicit delivery/platform boundaries.
• Land shared metadata/selection boundaries and drift checks; preserve existing public compatibility while removing competing authored pins.
• Integrate the own provisioning path into both the published image and repository setup, including non-root command/IDE exposure and the supported provisioning/update path. Removing a tool from the offering must remove it from generated metadata/targets and newly built images; automatic cleanup of existing developer installations is out of scope.
• Remove superseded/duplicate installation code and obsolete configuration, while retaining deliberate OS/feature providers. The own option keeps one shared native installer; it does not keep a duplicate container engine.
• Keep generated portable metadata for supported simple Bazel labels; explicitly exclude complex runtime packaging from that promise.
• Land release-bound ordinary Python dependency metadata and direct uv/uvx consumer checks for #189, without requiring the producer manager or a SCORE launcher.
• Select immutable release references, public package/artifact identity and hosting; automate owner refresh, export checks, release binding and publication.
• Run full amd64 integration gates on the final source, full ARM64 image/feature gates, and representative actual macOS ARM host checks; document per-tool exceptions.
• Replace prototype documentation with one supported operator/consumer guide and publish reviewable evidence with the implementation changes.

The implementation should be split from the own working local target into small coherent PRs. Each PR needs a usable boundary and preserved callers; this is not a plan to merge four parallel provisioners or defer cleanup until after #189.

#189 motivates release-selected Python delivery; #155 covers broader version ownership/locking concerns; #115 concerns inventory. This issue defines a bounded foundation rather than requiring all of those issues to be solved.

Two clarifications supersede the earlier issue text: a prepared container is trusted to contain its pins, and direct uv/uvx dependency resolution is a first-class interface. A custom SCORE launcher may be optional, but cannot be the only path.

Not required by this issue:

• A universal configuration format or identical artifacts across every delivery path.
• Handwritten transitive dependency descriptions, APT snapshotting, full reproducible builds or a general SBOM project. Additional locking work remains separately discussable under #155.
• Packaging complex, runtime-heavy tools in Bazel merely to make every CLI reachable through it.
• Requiring a manager, container or custom wrapper for an ordinary Python consumer.
• Moving every OS package or specialized feature into the selected manager.
• Promising Windows or Intel macOS support.
• Centrally replacing consumer-owned hook revisions just because the pre-commit executable is pinned.

Historical baseline: tool inventory, version sources and delivery paths on docs/tooling-status-quo. It describes the starting implementation, not the completed local experiments summarized above.

Architecture context: Infrastructure DR-001, Infrastructure DR-003. Implementation must respect those decisions. Build integration and the delivery of interactive CLI tools should remain explicitly distinguished.