Module fault_inject 

Deterministic fault-injection points for crash-recovery tests.

W2b shipped the rollback machinery — atomic mapping persistence, mirror Drop guard, HEAD/index restore on failure — but until we actually crash the process between the load-bearing writes, the rollback paths only have unit-test coverage of the helpers, not of the recovery contract itself. The integration story (“crashing here doesn’t corrupt the bridge mapping”) was unverified.

This module exposes a single maybe_panic_at(name) checkpoint that production code threads at the points where a crash would exercise a recovery path. Tests opt in by setting the HEDDLE_FAULT_INJECT environment variable to a comma-separated list of checkpoint names — e.g. HEDDLE_FAULT_INJECT=mapping_after_tmp_before_commit — and the next process to hit that checkpoint panics with a stable message.

The next CLI invocation (a separate process, no inherited env) must recover cleanly. That’s the contract under test.

Why an env var instead of a build-time #[cfg(test)] gate

The crash points sit in objects and cli paths that get spawned as separate child processes during integration tests. A child process can’t see the parent test’s cfg(test) flag, but it does inherit env vars by default. An env var lets the parent test set the crash point, spawn the child, observe the child crash, then spawn a fresh child (without the env var) and verify recovery.

Performance

maybe_panic_at is a single env lookup + string split + linear search. The env var is read once on first call and cached. With no HEDDLE_FAULT_INJECT set (the production default), the cached None short-circuits in well under a microsecond.

Functions

maybe_fail_at

Like maybe_panic_at, but returns an io::Error instead of panicking — for exercising in-process error-recovery paths (a graceful failure that drives a rollback) rather than crash recovery.

maybe_panic_at

Crash the current process if name is listed in HEDDLE_FAULT_INJECT.