Epic: strict reusable Rust tooling across megarepos

Goal

Introduce strict, state-of-the-art Rust tooling in effect-utils in a way that is enforced across all Rust packages, composable through Nix/devenv, and reusable by other megarepos such as dotfiles.

The rollout should keep Cargo as the current source of truth while preparing a clean Buck2 path. Buck2 should start as an experimental declared-input/evidence lane, not as the first required authority for Rust dependency builds.

Current baseline

• Rust crates are registered in genie/packages.ts as nix-only rust-crate packages.
• CI has a required generated cargo job running build, test, clippy -D warnings, and fmt.
• Nix builds use rustPlatform.buildRustPackage with committed Cargo.lock and doCheck = true.
• Missing today: root Rust workspace, shared lint policy, shared Rust devenv module, cargo-deny, cargo-machete, nextest config, Rust supply-chain policy, and Buck2-compatible Rust policy macros/toolchain cell.

Principles

• One policy surface: Rust packages should inherit strict defaults rather than copy shell snippets.
• No ambient toolchain authority: CI and local tasks should use Nix/devenv-provided tools with explicit package inputs.
• Cargo first, Buck2-ready: use Cargo for authoritative dependency resolution and quality gates until Buck2 third-party Rust generation is proven.
• Reusable by design: expose modules/helpers from effect-utils so downstream megarepos can opt in with minimal repo-local code.
• Evidence before ownership: Buck2 may consume declared evidence and first-party targets before it owns dependency materialization.
• Fail closed on public artifacts: no private repo names, host paths, tokens, or credentials in generated evidence/config.

Rollout checklist

1. Inventory and baseline gate

• Confirm every Rust crate is registered in a single source of truth (genie/packages.ts or successor registry).
• Add a generated/task-level audit that fails if a Cargo.toml crate is missing from the registry.
• Make the local rust:check task equivalent to the required CI Rust gate.
• Fix any current Rust gate failures before raising strictness.

Acceptance:

• devenv tasks run rust:check --no-tui and the generated CI cargo lane cover the same crate set.
• Adding an unregistered Cargo.toml fails a deterministic check.

2. Root Cargo workspace and shared package policy

• Add a root virtual Cargo.toml workspace for Rust crates.
• Use an explicit resolver (resolver = "2" while crates remain edition 2021; consider edition 2024 + resolver 3 as a separate migration).
• Centralize common package metadata where appropriate (workspace.package) without forcing publish semantics.
• Centralize common dependencies where it reduces drift and does not obscure crate-specific feature choices.

Acceptance:

• cargo metadata --workspace sees all Rust crates.
• Existing Nix builds and crate-local workflows still work.

3. Strict lint and formatting policy

• Add [workspace.lints] and opt each crate into [lints] workspace = true.
• Start with rustc lints that should be hard policy, e.g. unsafe_code = "forbid" unless a crate has an explicit exception.
• Enforce warnings = "deny" through CI/task invocation, not hidden local env.
• Add a committed rustfmt.toml only for intentional deviations from stable rustfmt defaults.
• Add clippy.toml only for policy knobs with durable justification.
• Evaluate clippy::pedantic as staged warn-to-deny, with explicit waivers for noise.
• Avoid blanket clippy::restriction; cherry-pick only rules with clear repo value.

Acceptance:

• cargo fmt --all --check passes from the workspace root.
• cargo clippy --workspace --all-targets -- -D warnings passes.
• Any crate-specific lint exception is explicit and justified near the crate.

4. Reusable devenv/Nix Rust module

• Add nix/devenv-modules/tasks/shared/rust.nix.
• Expose tasks: rust:fmt, rust:clippy, rust:test, rust:build, rust:check.
• Parameterize crate/workspace roots, package set, extra flags, and optional tools.
• Export the module from flake.nix under devenvModules.tasks.rust.
• Add module tests or fixture coverage matching existing shared task module patterns.
• Use the module in effect-utils itself.

Acceptance:

• Downstream repos can import effect-utils.devenvModules.tasks.rust and get the same gate shape.
• dotfiles can adopt the module without copying effect-utils-specific paths.

5. Test runner and coverage strategy

• Evaluate cargo-nextest as the default Rust test runner for speed and CI diagnostics.
• Decide whether cargo test remains a compatibility lane for doctests or fallback.
• Add nextest.toml only if a non-default policy is needed.
• Evaluate cargo-llvm-cov as advisory coverage, not initially required unless thresholds are stable.

Acceptance:

• The test task has clear semantics: unit/integration/doctest coverage is not accidentally dropped.
• CI output improves without changing test behavior.

6. Dependency hygiene and supply-chain policy

• Add cargo-deny with advisories, licenses, bans, and sources policy.
• Add cargo-machete for unused dependency detection, with explicit false-positive metadata.
• Evaluate cargo-vet for audited third-party provenance; adopt only if the process overhead is justified.
• Decide duplicate-version policy: deny obvious duplicates, allow temporary duplicates with tracked exceptions.
• Keep dependency policy public-safe: no private repo context in comments/evidence.

Acceptance:

• rust:check includes dependency hygiene gates, or an explicit rust:audit task is required by CI.
• Policy exceptions are stable, reviewed, and mechanically visible.

7. Feature, MSRV, and API compatibility gates

• Add cargo hack feature checks once crates expose optional features.
• Decide whether MSRV is pinned; if yes, encode it in rust-version and test it explicitly.
• Add cargo-semver-checks for crates treated as externally consumed APIs.
• Define which crates are internal tools versus public Rust libraries.

Acceptance:

• Feature/API gates apply only where they add signal.
• Public compatibility checks are not confused with internal binary/tool crates.

8. Buck2 experiment lane

• Add an isolated Buck2 prototype for first-party Rust crates only.
• Define a Nix-backed Buck2 toolchain cell instead of relying on ambient PATH.
• Add shared rust_strict_library, rust_strict_binary, and rust_strict_test macros that apply the same strict rustc flags as Cargo policy.
• Ensure Buck2 targets use declared source/toolchain inputs and emit no host-private paths.
• Keep Buck2 non-required until first-party targets build reproducibly on CI.

Experiment evidence from 2026-06-29:

• buck2 init + bundled prelude can build a tiny Rust library/binary.
• A working Nix shell needed buck2, rustc, clang, and lld.
• Buck2 daemon isolation matters: stale daemon/action environments can fail to find rustc.
• rustc_flags = ["-Dwarnings", "-Dunsafe_code", "-Dmissing_docs"] were enforced; an undocumented public function failed the Buck2 build.

Acceptance:

• buck2 build / buck2 test first-party Rust targets pass in CI as advisory checks.
• Buck2 failures do not block the Cargo-authoritative Rust gate until the toolchain cell and dependency story are stable.

9. Buck2 third-party dependency research

• Evaluate Reindeer vendored mode for crates.io dependencies.
• Document build-script fixup requirements for current Rust dependencies.
• Compare generated Buck graph against Cargo/Nix dependency graph.
• Decide whether Buck2 should own Rust third-party builds or only consume evidence for now.

Acceptance:

• No live network or mutable dependency repair occurs inside required Buck2 actions.
• Any future Buck2 dependency materialization follows the existing dependency-materialization principle: declared inputs, stable evidence, no live ownership until proven.

10. Downstream adoption proof

• Create a minimal downstream fixture that imports the Rust module from this flake.
• Prove a second megarepo shape, ideally dotfiles, can opt into the module with local crate registry config only.
• Document the integration contract: inputs, tasks, optional tools, and expected CI wiring.
• Add an upgrade path for repos with no Rust crates yet.

Acceptance:

• Downstream adoption does not require copying shell snippets from effect-utils.
• Repos with zero Rust crates can either no-op cleanly or fail with an intentional configuration error, depending on selected mode.

Proposed milestones

1. Cargo strict baseline: workspace + shared lints + green required gate.
2. Reusable Rust devenv module: exported and consumed by effect-utils.
3. Dependency hygiene: cargo-deny and cargo-machete in CI.
4. Test modernization: nextest decision and rollout.
5. Buck2 first-party advisory lane: Nix-backed toolchain and strict macros.
6. Downstream proof: fixture plus one real megarepo adoption plan.

Non-goals for first pass

• Replacing Cargo as dependency resolver.
• Making Buck2 the required Rust gate before first-party and third-party behavior is proven.
• Introducing private repository details into this public repo.
• Blanket-enabling noisy lint groups without staged cleanup and exception policy.

Start with the current Rust package registry in genie/packages.ts, the generated Cargo CI lane, and existing shared task module patterns under nix/devenv-modules/tasks/shared. Map the rollout checklist before choosing a focused milestone, then verify its stated acceptance criteria, including workspace metadata, strict checks, reusable module behavior, or advisory Buck2 evidence as applicable.