Stabilize and optimize Zapbrew current architecture

[metaphorics]

Destination

Stabilize every in-scope Rust Module within Zapbrew's current signed-JSON, bottles-only, no-Ruby architecture against the applicable behavior of Homebrew 6.0.16 on Linux and macOS. Each atomic parity tranche must preserve Zapbrew's independent design and pass both functional evidence and the Extremely-Optimize performance-floor gates.

Notes

• Domain: Rust package-manager client; behavioral parity, not architectural parity.
• Fixed architecture: signed Homebrew JSON catalogs, bottles, no Ruby evaluation, no runtime Homebrew checkout.
• Parity authority: Homebrew 6.0.16, published 2026-08-10. Behavior that requires source definitions, arbitrary Ruby evaluation, or formula-authoring machinery is outside this architecture.
• Platforms: Linux and macOS must both be complete inside the settled scope. Native file-system and host-tool effects require native process integration; cross-compilation and command construction never complete them.
• Performance: every atomic behavior tranche runs Extremely-Optimize in order: trusted baseline, hot/cold split, computed floors, blind derivation, divergence audit, explicit boundary decisions, >=1.05x measured win, and cold-path grading. Half-rebuilt targets never land.
• Architecture: use the codebase-design vocabulary. Prefer deep Modules, narrow Interfaces, real Seams, high Leverage, and strong Locality.
• Skills to consult: wayfinder, source-driven, extremely-optimize, improve-architecture, codebase-design, ground-latest, verification-before-completion, and zapbrew-verification.
• Charting baseline on 2026-08-11: cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, and cargo test --workspace passed; 713 tests passed across 69 suites.
• Enhance report on the discovered AI-facing project surface (README.md and docs/*): no HIGH, MEDIUM, or LOW findings; --apply was not requested, so no files changed.

Decisions so far

• Map Homebrew 6.0.16 parity gaps — All 30 current commands are paired with exact 6.0.16 sources; priority expressible gaps include Linux casks, inert policy and mirror settings, Linux service persistence, and cask variants, while source and Ruby-authoring workflows remain exclusions.
• Audit Linux and macOS verification coverage — Current proof is native Linux plus macOS cross-compilation and host-independent fixtures; native launchd, systemd-user, cask-tool, and codesign side effects remain unverified.
• Identify representative stabilization workloads — Four controlled candidates cover catalog ingestion, catalog queries, dependency expansion, and offline pour-relocate-link; measurement must select and baseline a candidate before optimization.
• Inventory types and prefix Modules — Thirteen production files own value types, environment detection, prefix paths, locks, receipts, command execution, and Linux linker setup; the corrected artifact restores missed cross-crate reachability.
• Inventory API and network Modules — Thirteen production files own JWS verification, signed catalog transport and indexing, cache confinement, bottle selection, bounded downloads, and atomic publication.
• Inventory bottle-pour Modules — Six production files own archive preflight/extraction, content-based relocation, atomic file replacement, and planned link/unlink mutation.
• Inventory formula operation Modules — Thirty-two production files own shared operation state, dependency traversal, install-step and transaction state machines, and formula command entry points.
• Inventory cask service and tap Modules — Fourteen production files own cask, service, platform-command, tap, untap, shim, and operation-export behavior, with native host-tool evidence limits recorded.
• Inventory CLI Modules — Six production files own the 30-command clap surface, 32-operation dispatch, fast paths, catalog gating, reporting, completions, and process exit contract.
• Inventory Zapbrew production Modules — The six scoped inventories account for all 84 production Rust files and record the end-to-end Interfaces, trust and transaction boundaries, platform controls, reachability limits, and evidence limits.
• Set parity and safety precedence — Parity is the default. An exact proved invariant may constrain it only when no equally safe parity-preserving implementation exists, the deviation is minimal, and a repository maintainer approves the complete evidence record. The ledger cannot approve itself.
• Choose first module-deepening target — Install-step journal ownership is implemented as rollback plus take_cleanup_root: the journal resets itself, callers retain physical cleanup and OpError context, the transaction keeps the cleanup-failure seam and rollback order, and external commands remain non-transactional.
• Define stabilization ledger and evidence gates — Five canonical JSON/JSONL/Python artifacts own the 84-file scope, behavior cells, achieved evidence, digest-bound approvals, and replayed tranche state. Missing, defective, unresolved, deferred, native-unproved, stale, or hot-above-floor cells make global completion false.
• Define first atomic parity-performance tranche — The first behavior tranche is Linux install-step journal lifecycle: five success/failure/isolation cells, deterministic W4 baseline and profiling, strict noise/floor gates, and a separate unresolved macOS mirror that requires native process integration.

Not yet specified

• The canonical scope cell set and its repository-maintainer digest binding.
• Product decisions that remove or rename live surfaces, including completions and per-surface output parity bars.
• Performance floors and tranche order after the first W4 profile ranks measured hot units.
• Native Linux user-bus and macOS host availability for effects that cannot be proved on this workstation.
• Cleanup, user documentation, and changelog work required by each landed tranche.

Out of scope

• Ruby DSL or arbitrary formula evaluation, source builds, formula authoring, and other behavior that cannot be expressed by the fixed architecture.
• Reproducing Homebrew's Ruby architecture or delegating unsupported behavior to an installed brew.
• Hosted Homebrew ecosystem infrastructure beyond the distributed client.
• Unmeasured performance rewrites, noisy baselines, changes below the 1.05x win gate, and half-rebuilt targets.