RFC 0002: Build Rust crates hermetically from Cargo metadata

[Windsor Nguyễn (windsornguyen)]

RFC: Build Rust crates hermetically from Cargo metadata

Status: Proposed

Summary

BSMR should integrate with Cargo rather than replace it.

Cargo should remain responsible for Rust ecosystem semantics: interpreting
Cargo.toml, resolving package versions, applying workspace inheritance and
patches, selecting features under Cargo's resolver rules, and writing
Cargo.lock. BSMR should consume the committed Cargo inputs as an immutable
dependency graph, acquire the exact Rust toolchain and crate sources, and
execute crate compilation, procedural macros, build scripts, linking, and tests
as explicit BSMR actions.

This design is successful only if it improves the outcomes developers actually
care about:

• Correctness: BSMR preserves Cargo's selected packages, features,
  dependency kinds, host/target split, build-script behavior, and platform
  predicates without inventing competing Rust semantics.
• Speed: crates compile as fine-grained actions, immutable sources and
  toolchains are shared through the CAS, and local or remote caches reuse work
  across binaries, tests, workspaces, and machines.
• Security: registry and Git sources are authenticated, build scripts and
  procedural macros execute with declared inputs and no public network access,
  and native toolchains are explicit.
• Ease of use: developers continue using ordinary Cargo manifests,
  workspaces, lockfiles, features, profiles, and tools. BSMR must not require a
  second dependency manifest or a BSMR-specific Rust resolver.

The intended boundary follows the strongest public precedents in
rules_rust Crate Universe and Meta's Reindeer: Cargo owns dependency
resolution; the build system imports the result and owns frozen execution.

Decision

The proposed architecture has three explicit phases:

Phase	May use the network?	Contract
Dependency update	Yes	An explicit, developer-requested Cargo resolution operation
Source and toolchain fetch	Yes	Digest-verified acquisition into BSMR's CAS
Frozen build	No	Hermetic analysis and execution from declared source, toolchain, and CAS inputs

BSMR should describe this publicly as hermetic frozen Rust builds, not
"hermetic Cargo resolution." Updating Cargo.lock may consult registry and Git
state. Once the lockfile and toolchain declaration are committed, resolution and
public network access do not belong in the build.

Cargo has two related but distinct resolutions:

1. Package and version resolution, represented by Cargo.lock.
2. Feature and target resolution for the requested packages, dependency kinds,
   host platform, target platform, and command.

Cargo resolver version 2 deliberately avoids unifying build-dependency and
procedural-macro features with ordinary target dependencies, and it avoids
unifying inactive target-specific dependencies. The relevant BSMR identity is
therefore:

(package, features, dependency kind, execution platform, target platform, profile)

It is not merely (crate name, version).

User experience

The normal workflow should remain familiar:

1. A developer edits Cargo.toml or uses Cargo to add or update a dependency.
2. The project's exact Rust toolchain updates Cargo.lock.
3. The developer commits manifests, lockfile, toolchain declaration, and
   relevant Cargo configuration together.
4. BSMR validates that the Cargo inputs are complete and unchanged.
5. BSMR imports the configured Cargo graph for the requested targets.
6. Missing toolchain and crate artifacts are fetched by digest into the CAS.
7. Frozen Rust actions run without public network access.

A stale lockfile, unsupported source, missing native toolchain, or ambiguous
feature graph must produce one actionable error naming the affected package and
the explicit update or configuration required. BSMR must never repair
Cargo.lock during an ordinary build.

Requirements

Each requirement below is intended to become an independently reviewable
implementation issue. The "not desired" sections are part of the contract.

1. Pin the Rust toolchain as a verified BSMR toolchain

Desired

• Resolve an exact Rust release or dated nightly from the project's toolchain
  declaration.
• Record and verify the distribution artifact digest for every supported
  execution platform.
• Include rustc, rustdoc, Cargo, the standard library, LLVM tools,
  components, target libraries, and declared linker toolchains in affected
  action identities.
• Verify the extracted toolchain's release metadata before admitting it to the
  CAS.
• Support an explicit project operation for changing toolchain versions,
  components, or targets.

Not desired

• Executing floating stable, beta, or an unpinned nightly during a frozen
  build.
• Selecting whichever rustc or Cargo appears first on PATH.
• Reading ambient rustup state from the developer's home directory.
• Downloading a missing component or target from inside a compilation action.
• Silently substituting a different Rust release when the declared one is
  unavailable.

Acceptance

• A clean machine obtains and verifies the declared toolchain without a global
  Rust installation.
• A missing or mismatched toolchain fails with the expected release, component,
  target, and observed artifact identity.
• Changing only a compiler, standard library, component, target library, or
  linker invalidates every affected action and no unrelated action.

2. Separate dependency updates, acquisition, and frozen builds

Desired

• Treat Cargo.lock creation or update as an explicit operation outside the
  frozen build.
• Permit registry, Git, and toolchain network access only in a distinct fetch
  phase.
• Run graph analysis with locked, offline semantics after all required inputs
  are available.
• Guarantee that the frozen build leaves manifests, lockfiles, and Cargo
  configuration byte-for-byte unchanged.
• Support fully offline replay from the CAS.

Not desired

• Running an implicit cargo update.
• Allowing Cargo to repair missing lock entries during analysis.
• Fetching a crate, Git commit, toolchain component, or build-script input from
  inside a frozen action.
• Claiming that a networked dependency update is hermetic.

Acceptance

• The same requested build succeeds with public network access disabled after
  acquisition completes.
• Removing a required CAS object produces a missing-artifact error instead of a
  new resolution.
• Mutation tests prove that ordinary builds cannot alter Cargo.lock,
  Cargo.toml, .cargo/config.toml, or the toolchain declaration.

3. Validate native Cargo inputs fail-closed

Desired

• Treat all workspace Cargo.toml files, Cargo.lock, the toolchain
  declaration, relevant .cargo/config.toml files, patches, and source
  replacements as semantic inputs.
• Require Cargo.lock whenever the selected Cargo workflow requires it.
• Reject lockfiles that are stale, incomplete, or unsupported by the pinned
  Cargo version.
• Resolve relative path dependencies and configuration from the declared
  workspace root, independent of the client process's current directory.
• Name the exact manifest, package, source, or field when validation fails.

Not desired

• Best-effort parsing of future Cargo or lockfile semantics.
• Ignoring unsupported [patch], [replace], alternate registry, source
  replacement, or workspace inheritance behavior.
• Continuing with a partially imported graph.
• Treating uncommitted ambient Cargo configuration as project policy.

Acceptance

• Fixtures cover workspace inheritance, virtual workspaces, resolver versions,
  patches, alternate registries, Git sources, path sources, target-specific
  dependencies, optional dependencies, and stale lockfiles.
• Every invalid fixture fails before crate code, a build script, or a procedural
  macro executes.
• Validation reports all independent manifest/lock mismatches in one invocation
  without weakening fail-closed behavior.

4. Import Cargo's configured dependency graph

Desired

• Invoke the pinned Cargo with locked and offline semantics to obtain
  cargo metadata --format-version=1 output.
• Treat Cargo package IDs and source IDs as opaque values.
• Preserve packages, targets, dependency kinds, rename information, feature
  edges, resolved feature sets, workspace membership, source identity, and
  target predicates.
• Parameterize graph import by the requested packages, feature flags, target
  triple, and Cargo resolver semantics.
• Store the canonical imported graph in the CAS and make it queryable for
  affected-target analysis, provenance, and policy.

Not desired

• Reimplementing Cargo's version or feature resolver in BSMR.
• Keying packages only by crate name and semantic version.
• Assuming one metadata invocation describes every feature or target
  configuration.
• Inferring source identity from a local Cargo registry directory layout.

Acceptance

• Differential fixtures produce the same selected package IDs, features, and
  dependency-kind edges as the pinned Cargo toolchain.
• A graph query explains why a crate variant exists and which feature,
  dependency kind, or platform decision selected it.
• Reordering semantically unordered manifest data does not change graph
  identity; changing a semantic Cargo input does.

5. Fetch and verify crate sources into the CAS

Desired

• Fetch each unique registry archive or Git source once by immutable identity.
• Verify registry crate bytes against the checksum recorded in Cargo.lock.
• Require an exact Git commit and compute a BSMR source-tree digest after
  checkout because the commit identifies source history but is not itself a
  content checksum.
• Address normalized, read-only source trees by digest.
• Record registry, URL, commit, subdirectory, checksum, and patch provenance
  without recording credentials.

Not desired

• Depending on the user's mutable Cargo registry or Git checkout cache.
• Accepting an unpinned Git branch or tag as frozen identity.
• Trusting downloaded bytes without verification.
• Retrying through a semantically different registry or source.
• Logging private registry credentials or placing them in action keys.

Acceptance

• Concurrent requests for one source converge on one verified CAS object.
• Corrupted registry archives and substituted Git trees are rejected before
  analysis or compilation.
• Warm and remote-cache builds reuse source trees without registry or Git
  access.

6. Represent host and target crate variants explicitly

Desired

• Compile ordinary dependencies for the declared target platform.
• Compile build dependencies, build scripts, and procedural macros for the
  execution platform.
• Preserve Cargo resolver feature separation between host and target
  dependency kinds.
• Include target triple, execution platform, crate type, features, profile,
  compiler, and relevant configuration in each variant's identity.
• Support multiple versions and multiple configured variants of the same crate
  in one build graph.

Not desired

• Treating one compiled archive as valid for every feature set or platform.
• Selecting target-specific dependencies from the host that launched BSMR.
• Running target binaries, target build scripts, or target procedural macros on
  the execution host.
• Collapsing build, development, and normal dependencies into one edge kind.

Acceptance

• Fixtures cover feature-unification splits, target-specific dependencies,
  cross-compilation, multiple versions, and procedural-macro host execution.
• Cache explanations identify the exact host/target or feature dimension that
  caused a distinct variant.
• Cross-compilation results are independent of the client host.

7. Model each Cargo build script as explicit actions

Desired

• Compile each build.rs program as a host action.
• Execute the compiled build script as a separate sandboxed action.
• Declare the crate source tree, host dependencies, toolchains, allowed
  environment, and platform configuration as inputs.
• Capture generated files and all supported cargo:/cargo:: directives as
  structured outputs.
• Preserve immediate links metadata propagation and Cargo's required ordering.
• Begin with the whole crate tree as the source input; optimize narrower dynamic
  inputs only after correctness is demonstrated.

Not desired

• Executing build scripts during graph import.
• Granting build scripts public network access or ambient home-directory state.
• Treating build-script standard output as unstructured log text.
• Silently rerunning a failed build script outside the sandbox.
• Sharing outputs across incompatible toolchains, platforms, features, or
  environment.

Acceptance

• Fixtures cover generated Rust, rerun-if-changed, rerun-if-env-changed,
  emitted cfg values, linker directives, environment values, warnings,
  metadata, native compilation, undeclared writes, and denied network access.
• A deterministic build script receives a remote-cache hit on a clean machine.
• Unsupported directives fail with the crate, directive, and required BSMR
  capability.

8. Treat procedural macros and native code as first-class toolchain actions

Desired

• Compile procedural macros for the execution platform and expose them only to
  declared dependents.
• Include procedural-macro binaries and their dependency closures in consuming
  rustc action keys.
• Model C, C++, assembly, linker, pkg-config, and system-library inputs
  explicitly when a crate builds or links native code.
• Support package-specific fixups for undeclared native sources, tools,
  environment, or system-library mappings.
• Require a declared cross C/C++ toolchain when target-native code is built
  during cross-compilation.

Not desired

• Loading a procedural macro from the target platform.
• Discovering compilers or system libraries from ambient PATH, /usr/lib, or
  mutable package-manager state.
• Pretending arbitrary build.rs native behavior can always be inferred from
  Cargo.toml.
• Falling back to an unsandboxed host build when a native toolchain is absent.

Acceptance

• Fixtures cover proc-macro cross-compilation, C and C++ build helpers,
  pkg-config, static and dynamic linking, bindgen-like tools, and missing
  cross-toolchains.
• Every native file, flag, library, sysroot, and tool that affects output is
  visible in action provenance.
• Fixups are reviewable data, scoped to exact packages, and covered by
  conformance tests.

9. Compile crates and link artifacts as fine-grained BSMR actions

Desired

• Invoke the pinned rustc directly for libraries, binaries, tests, examples,
  benchmarks, and procedural macros after graph import.
• Declare crate source, dependency metadata, extern mappings, cfg values,
  features, profile, lint flags, codegen flags, target specification, linker,
  and toolchain as inputs.
• Capture metadata, rlibs, dylibs, binaries, dep-info, diagnostics, and other
  declared outputs as CAS objects.
• Compile and cache reusable upstream crate variants independently of final
  binaries and tests.
• Keep command lines and response files deterministic and explainable.

Not desired

• Treating cargo build as the permanent opaque compilation primitive.
• Hashing an entire workspace when one crate changes.
• Reusing an artifact because only crate name and version match.
• Omitting flags or environment from the key to improve benchmark results.

Acceptance

• Representative workspaces achieve output and failure parity with the pinned
  Cargo baseline.
• Editing one leaf crate invalidates only its reverse dependency closure.
• A cache explanation identifies the first semantic input that changed.
• Local and remote execution produce behaviorally equivalent results.

10. Expose Rust targets and tools through ordinary BSMR interfaces

Desired

• Represent libraries, binaries, tests, examples, benchmarks, build scripts,
  procedural macros, and documentation operations as distinct target kinds.
• Generate or infer BSMR targets from Cargo metadata without duplicating package
  versions or dependency edges in BUCK files.
• Provide first-class targets for rustfmt, Clippy, and ordinary Rust tests
  using components from the pinned toolchain.
• Support nextest, cargo-deny, cargo-vet, and similar ecosystem tools as pinned
  ordinary actions.
• Define doctest support as an explicit milestone rather than silently omitting
  it.

Not desired

• One manually maintained BUCK target per transitive crate.
• Baking every Cargo subcommand or third-party policy tool into BSMR core.
• Giving every workspace target visibility into every locked crate.
• Reporting an unsupported Cargo target as successfully built.

Acceptance

• A Cargo workspace can expose build and test targets without copying
  dependency versions into BSMR configuration.
• Direct and transitive visibility matches the imported graph.
• Unsupported target kinds fail during analysis with a documented status.

11. Derive cache identity, provenance, policy, and diagnostics from one graph

Desired

• Include source digest, Cargo identity, features, dependency kind, patches,
  build-script outputs, toolchains, target and execution platforms, declared
  environment, profiles, and BSMR rule implementation in action identity.
• Trace every output from manifest and lockfile entry through fetched source,
  generated source, compilation, and linking.
• Support license, registry, vulnerability, source, and version-set policy from
  the same graph BSMR executes.
• Explain "why is this crate here?", "why is this variant distinct?", and "why
  did this rebuild?" in developer-facing terms.

Not desired

• A separate security graph that can disagree with execution.
• Provenance containing only crate names and versions.
• Secrets in cache keys, logs, or provenance.
• Opaque "Rust dependencies changed" cache diagnostics.

Acceptance

• Provenance for a representative native crate traces its registry archive,
  checksum, build script, native compiler, crate variants, and consuming target.
• Policy checks run before package code executes.
• Cache mutation tests cover every semantic identity dimension.

12. Prove Cargo parity and performance before cutover

Desired

• Maintain a differential conformance suite against the exact supported Cargo
  and Rust toolchain.
• Compare selected packages, features, target predicates, build-script outputs,
  compiler invocations, test behavior, diagnostics, and final artifacts.
• Benchmark cold acquisition, warm compilation, no-op builds, affected-crate
  rebuilds, offline replay, and remote-cache restoration.
• Publish methodology and correctness differences with timing results.
• Keep native execution opt-in until compatibility gates pass, then remove the
  old frozen compilation path at cutover.

Not desired

• Declaring parity because one workspace compiles.
• Comparing wall-clock time while ignoring different features or artifacts.
• Maintaining a permanent silent fallback to cargo build.
• Making native execution the default before unsupported behavior fails clearly.

Acceptance

• The suite covers resolver feature splits, multiple versions, patches, Git
  dependencies, target-specific dependencies, build scripts, links,
  procedural macros, native code, workspace inheritance, dev dependencies,
  tests, examples, and cross-compilation.
• Known unsupported cases fail before execution.
• Performance reports include machine, platform, toolchains, cache state, graph
  size, affected closure, and correctness result.

Delivery milestones

Milestone 0: establish the pinned Cargo baseline

Run the exact, verified Rust toolchain in a sandbox with locked dependency
semantics. Capture package graph, features, outputs, failures, and performance.

Exit criterion: a tested baseline with no ambient compiler, mutable lockfile, or
floating toolchain.

Milestone 1: import and validate Cargo metadata

Add a read-only Cargo graph provider and canonical Rust variants. Use the graph
for queries, policy, provenance, and target analysis while Cargo still performs
compilation.

Exit criterion: differential graph tests pass for the initial supported Cargo
surface and importing the graph changes no build behavior.

Milestone 2: own source and toolchain acquisition

Fetch and verify Rust distributions, registry crates, and Git sources as
individual CAS objects.

Exit criterion: the baseline build runs fully offline and every external input
has immutable provenance.

Milestone 3: compile hook-free Rust targets natively

Invoke rustc directly for crate graphs that do not require build scripts or
native fixups.

Exit criterion: supported libraries, binaries, and tests match Cargo across
clean machines and remote execution.

Milestone 4: actionize build scripts, procedural macros, and native code

Add structured build-script execution, host procedural macros, native
toolchains, and package fixups.

Exit criterion: representative generated and native crates reproduce with
network access denied and sound remote-cache hits.

Milestone 5: cut over

Make BSMR-native Rust execution the only frozen-build path for the supported
surface. Keep Cargo solely for explicit dependency updates and graph analysis.

Exit criterion: compatibility, security, performance, documentation, and
migration gates pass; no automatic fallback remains.

Initial scope

The first production-quality release should support:

• Cargo workspaces and virtual workspaces
• Cargo.lock version used by the pinned Cargo toolchain
• Registry, immutable Git, and path dependencies
• Workspace inheritance and resolver version 2
• Features, renamed dependencies, patches, and target-specific dependencies
• Libraries, binaries, ordinary tests, and procedural macros
• Sandboxed build scripts with the supported directive surface
• Declared native C/C++ toolchains and package-specific fixups
• Host/target separation and an initial cross-compilation matrix

Support must be defined by conformance fixtures, not by optimistically
accepting arbitrary Cargo behavior.

Non-goals

• Reimplement Cargo's package or feature resolver.
• Replace Cargo manifests, workspaces, lockfiles, or registry protocols.
• Support every historical Cargo or lockfile version initially.
• Infer arbitrary build-script inputs perfectly.
• Permit build scripts, procedural macros, or compilers to access the public
  network during frozen builds.
• Treat rustup's mutable home-directory state as a build input.
• Bake all Cargo ecosystem policy tools into BSMR core.
• Promise byte-for-byte reproducible artifacts from tools that embed timestamps,
  paths, randomness, or undeclared state. Hermeticity is necessary but not
  sufficient for reproducibility.

Alternatives considered

Shell out to Cargo forever

This is the correct baseline and may remain sufficient for small repositories.
It leaves compilation, build scripts, target closure, and many cache boundaries
inside one comparatively opaque process and limits BSMR's remote execution,
provenance, and affected-target analysis.

Reimplement Cargo resolution

This would make BSMR responsible for registry selection, semantic versions,
features, resolver evolution, workspaces, patches, target predicates, source
replacement, and years of compatibility behavior. It does not improve the
initial developer workflow and should occur only if a measured requirement
cannot be satisfied through Cargo's native contract.

Adopt rules_rust directly

rules_rust is the strongest Bazel precedent and should inform BSMR's variant
model, toolchain acquisition, build-script handling, and conformance suite. Its
Bazel repository, module-extension, provider, and Starlark APIs are not BSMR's
native architecture.

Adopt Reindeer as the permanent importer

Reindeer provides excellent prior art for translating Cargo metadata and
package fixups into a build graph. BSMR should learn from its contracts and may
use it in early experiments, but should not make its public graph dependent on
another build system's generated-file model.

Risks

• Cargo semantic drift: mitigate with versioned adapters and differential
  fixtures against each supported toolchain.
• feature-variant explosion: measure and deduplicate only when complete
  identity proves variants equivalent.
• build-script impurity: sandbox, deny network access, declare environment,
  and use exact package fixups.
• native toolchain leakage: require declared compilers, sysroots, libraries,
  and linkers.
• Git source ambiguity: pin commits and compute source-tree digests.
• diagnostic mismatch: preserve structured compiler output and compare
  failure behavior with Cargo.
• fine-grained overhead: benchmark analysis, action count, CAS operations,
  and remote scheduling at large workspace scale.

Success criteria

This RFC is complete when a developer can:

1. Use normal Cargo files and the declared Rust toolchain to update dependencies.
2. Commit a lockfile that BSMR validates without reinterpretation.
3. Build a selected Rust target offline after acquisition.
4. Cross-compile with an explicit host/target and native-toolchain boundary.
5. Receive sound local or remote cache hits across clean machines.
6. Inspect why a crate variant exists, what generated or native inputs affected
   it, and why it rebuilt.
7. Encounter a precise pre-execution failure for unsupported or undeclared
   behavior.

The project should optimize for those outcomes, not for ownership of Cargo
internals.

Prior art and references

• Cargo's
  resolver documentation
  defines package, feature, dependency-kind, and target resolution.
• cargo metadata
  is Cargo's structured graph interface for external tooling.
• rules_rust Crate Universe
  imports Cargo dependencies into hermetic Bazel targets.
• Reindeer translates Cargo
  metadata into Buck targets and maintains package-specific fixups.
• Cargo's
  build-script reference
  defines the directives and ordering that BSMR must preserve.
• The Rust
  platform support table
  defines target tiers; BSMR support remains narrower and fixture-defined.

Questions for design review

These questions should be settled before their respective implementation
milestones; they do not reopen the core Cargo/BSMR boundary.

1. Which exact stable and nightly Rust releases form the first supported
   toolchain matrix?
2. Should BSMR consume rust-toolchain.toml directly, or expose a generated
   digest lock adjacent to it for official distribution artifacts?
3. Which cargo metadata feature configurations are imported eagerly versus on
   demand?
4. What is the stable crate-source tree representation in BSMR's CAS?
5. Which build-script directives and native build helpers are release-blocking?
6. Which public workspaces form the correctness and performance corpus?
7. Are doctests part of the first production release or an explicitly later
   milestone?