feat(cargo): project-local [patch]-redirect backend + single fail-closed guard

[Mikola Lysenko (mikolalysenko)]

Project-local cargo [patch]-redirect backend + fail-closed guard

Patching a Rust dependency from the registry cache no longer mutates the shared
$CARGO_HOME registry in place. apply now writes a project-local patched copy
under .socket/cargo-patches/<name>-<version>/ and a managed [patch.crates-io]
entry (+ [env] SOCKET_PATCH_ROOT) into .cargo/config.toml, so patches are
project-scoped and the registry stays pristine for sibling projects. Vendored crates
(vendor/) and --global cargo keep the existing in-place .cargo-checksum.json
path.

Build-time guard — single fail-closed mode

socket-patch setup adds a tiny socket-patch-guard dependency (a normal
[dependencies] entry, so cargo always runs its build script) to each workspace
member. On every relevant cargo build it runs socket-patch apply --check:

• in sync → proceed (cached no-op; zero steady-state overhead);
• drift → heal (apply) then fail the build (the current build already
  compiled the stale copy; the re-run is clean) — recoverable reports
  "regenerated — re-run", unrecoverable reports "could NOT be reconciled";
• missing / cargo-less CLI / unrecoverable → fail closed.

There is no warn/off mode and no SOCKET_PATCH_GUARD env. In normal use the
guard never fires, since changing a patch goes through get/apply, which
regenerate the copies. apply --check doubles as a read-only, offline, lock-free CI
gate and cross-checks Cargo.lock (catching a patched dep that resolved to an
unpatched version).

Ships with cargo enabled by default

default = ["cargo"] in both crates (npm + PyPI are unconditional), so released
binaries and cargo install socket-patch-cli patch Rust deps and run the guard out
of the box; golang/maven/composer/nuget/deno stay opt-in. A
--no-default-features binary's apply --check fails closed rather than reporting
"in sync".

R&D (not shipped): same-tick auto-heal

crates/socket-patch-guard/SAME_TICK_HEAL_RND.md + an #[ignore] experiment
(tests/same_tick_heal_experiment.rs) establish that a patched copy depending on the
guard heals in the same cargo build (verified on cargo 1.93.1), at zero
steady-state cost. It's publish-gated (copies need a portable guard ref) and
deliberately not wired into apply_cargo_redirect; the doc records the
productionization path.

Adversarial pre-push review

Before opening this PR I ran a multi-agent adversarial review of the full diff
(5 reviewers across guard logic / docs / R&D / backend / tests, each finding
independently verified). It surfaced 17 confirmed findings, all fixed in this
branch:

Sev	Fix
blocker	A socket-patch built without the cargo feature returned 0 from apply --check, so the guard passed open. Now fails closed — and cargo ships by default, so the released binary supports it.
major	verify_cargo_redirect_state now checks the [patch] entry path matches the desired version (new Drift::WrongEntryPath + regression test) — a stale-version entry no longer audits as in-sync.
major	Wired guard_build_integration + e2e_cargo_coexist into the CI e2e matrix (the real fail-closed proofs were #[ignore] and never ran in CI).
major	real_cargo_guard_fails_build_on_stale_patch asserted a message that never fires + an always-true || "socket-patch" escape; now asserts the real recoverable-drift message.
minor	Corrupt/unreadable manifest in apply --check now fails closed (was exit 0).
minor	Dropped the spurious || "socket-patch" escape in the unrecoverable-drift + missing-CLI integration tests; assert deterministic messages + sentinel.
minor/nit ×9	Documented duplicate-version + malformed-Cargo.lock cross-check limitations; doc/comment fixes (CHANGELOG "build-dependency", README "no warn" contradiction, R&D no_std caveat, .socket→., "runtime hook"→"build-time guard", stale "Default (strict)" comment).

Testing

• cargo test green in both feature configs (default-with-cargo + --features cargo) and --no-default-features, for core + cli + guard.
• The #[ignore] real-cargo proofs pass: guard_build_integration (4), e2e_cargo_coexist (incl. the fail-closed-on-stale-patch proof), same_tick_heal_experiment.
• clippy clean on all changed files (cargo fmt intentionally not run — repo isn't rustfmt-1.8-clean; only touched lines formatted).

🤖 Generated with Claude Code