# Rust and Cargo compatibility

The Phase 8 checkpoint packages the official Rust 1.93.0
`aarch64-unknown-linux-musl` host tools and standard library. Generated
toolchains, registry data, build outputs, and snapshots stay in the
repository's ignored `.tmp` directory.

## Verified behavior

- Dynamically linked guest rustc and Cargo start through the packaged musl
  loader and report their expected versions.
- Rustc compiles a checked-in freestanding `no_std` source file, and packaged
  LLD links the persisted object into a static AArch64 ELF.
- Cargo resolves a checksum-locked `itoa` 1.0.18 dependency from a minimal
  crates.io sparse-index and crate-archive overlay with `--offline --locked`.
- Cargo extracts registry archives and applies their modification times
  through `utimensat` without host filesystem access.
- Cargo compiles and executes the fixture's `std`-using `build.rs` child. The
  script reads `OUT_DIR`, writes a generated Rust source file, and emits a
  `cargo:rerun-if-changed` directive through Cargo's stdout protocol.
- The project, registry sources, dependency outputs, and incremental target
  directory survive deterministic filesystem snapshot export and restore.
- A second verbose Cargo build reports both `itoa` and the fixture binary as
  `Fresh`. Executables from both build snapshots print `guest cargo dependency
  hello` and exit 42.

Run the reproducible verifier after building the toolchain:

```sh
toolchains/rust-musl/build.sh
toolchains/rust-musl/verify.sh
```

The build script is the only networked stage. It checksum-pins the official
Rust distribution and fetches the fixture's committed lockfile into
`.tmp/cargo-home`. The verifier runs its host-side preparation offline, packs
only the selected registry records, and gives guest Cargo no network service.

## Compatibility policy

The verified dependency tier is a locked, pure-Rust crate that compiles for
the packaged AArch64 musl host without its own build script. The root package
may use a single Rust `build.rs` process for filesystem-based code generation
and Cargo stdout directives, as covered by the fixture. A crate belongs to
this tier only after the same offline build, build-script execution, cache
replay, and resulting-ELF checks pass. Registry resolution alone is not a
compatibility claim.

The following remain unverified and outside the current support contract:

- procedural-macro dependencies built as part of a project;
- native library discovery and linking;
- C, C++, assembly, or other compiler invocations from dependencies;
- build scripts that spawn additional tools, probe the host, or require
  capabilities beyond the verified environment, output-file, and stdout
  protocol subset;
- package-index access or dependency downloads from inside the guest; and
- general-purpose guest threading beyond rustc's covered cooperative topology.

Cargo may emit a nonfatal warning that it cannot save global-cache last-use
data because SQLite advisory locks are not implemented. This does not affect
locked dependency resolution or artifact reuse; the verifier treats actual
resolution, compilation, or freshness failures as fatal.