# cargo-gamma — Implementation guide
This guide records executable and end-to-end mechanics behind
[`DESIGN.md`](DESIGN.md).
## Executable boundary
The binary implements the real terminal host and calls
`cargo_gamma_lib::run`. Installed-binary tests launch that executable in both
direct and Cargo subcommand argument shapes, then compare its complete version
output with the package version.
The command layer normalizes Cargo's inserted `gamma` argument and inserts
`run` only for a bare option-first invocation. Clap owns syntax and generated
help; configuration is resolved afterward so split settings such as shard count
in `gamma.toml` and shard index on the command line can be validated as one
effective value. The top-level boundary maps help and success to `0`, usage to
`1`, failed score or source-expectation gates to `2`, inability to proceed to
`3`, and an uncaught internal panic to `70`.
## Scratch layout
The coordinator synchronizes sources and vendors the dependency-free guard
runtime under an external per-workspace scratch base. By default, Cargo
artifacts and campaign state live under
`<resolved-target>/cargo-gamma/cache/<workspace-identity>`. An explicit cache
directory keeps the all-in-one layout. Published reports remain under the
artifact directory rather than reusable cache state.
The external cache also carries `campaign-location`, an atomically written
pointer to the campaign base used by the latest completed run. Completion
writes and serializes the merged record first, retains that merged value in
memory, publishes the locator second, and enables postprocessing notes only
when the same locator lookup used by `hints` and `suppress` resolves the
record.
The default cache name is a pinned BLAKE3-derived physical-workspace identity
used by both locations. The stable process-held lock remains under the platform
cache home, so deleting the Cargo target cannot create a second lock domain.
Ownership markers prevent two workspaces from sharing mutable state
accidentally. An explicit cache directory is validated before use and must be
empty when first claimed.
Completed runs always publish JSON, self-contained HTML, SARIF, Markdown
performance advice, and a versioned diagnostics bundle. Before a build,
cargo-gamma clears stale `baseline-failures/` records. Each named baseline test
failure receives a readable
`baseline-failures/<package>/<target>/tests/<test>/` directory containing
`failure.json` and `diags.json`; categorical leaves represent unnamed
binary-level failures. Filesystem sanitization and length limits are
collision-checked, with a short identity digest added only when needed.
Artifact publication is separate from the cache, and `--artifact-dir` moves
the complete user-facing set.
## Compiler convergence
The library filters historical compiler exclusions during discovery, before
assigning ordinals or writing guards. The cumulative `compiler-exclusions.json`
inventory is independent of incremental reuse and is atomically extended as new
individual failures are proved. Interaction-only removals are never added.
Pristine validation fixes the package roots, targets, features, and compiler
options once. Every exclusion and proof check repeats `cargo check --tests
--keep-going`; the final `cargo build --tests --keep-going` retains that scope.
Library-only campaigns preserve their `cargo test --no-run --lib --no-fail-fast`
invocation instead. Unattributed failures enter diagnostic-scoped isolation with
exact active subsets in the failed dependency-connected components. Other
mutations in those components are restored; disconnected successful components
remain instrumented. Identical source selections and bytes are not rewritten. Local
limits are 4,096 candidates per search and 32 proofs per context. Diagnostic-local
searches precede deterministically partitioned oversized tiers; passing partitions
do not disprove cross-partition interactions. After the complete diagnostic-local
tier group yields proven progress, the next ordinary convergence check replaces
broader clean-tier proof builds. All local partitions are still considered;
contexts without diagnostic locality retain the broader search. Each Cargo invocation
admits 64 contexts and therefore at most 2,048 proofs, preserving a complete
local proof allowance for every admitted context. Larger dependency cones run
first. Exhausted contexts preserve unjudged candidates. Confirmed causes permit
another convergence round; no-progress exhaustion stops the campaign with an
actionable error instead of abandoning a package or dependency population.
The initial validation is the pristine control: isolation launches no additional
controls, historical probes, target reductions, or scope-widening retries.
Confirmed singleton counts are published during isolation, before subsequent proofs.
Isolation and interaction minimization live in
`cargo-gamma-lib/src/exec/build/isolation.rs`; splice deltas and the incremental
guard index remain in `build/splices.rs`. Ordinary reporters do not request
Cargo evidence decoding, while diagnostic reporters opt in through `Events`.
Target-frontier acceptance was rejected by deterministic invocation-count
fixtures: retaining global confirmation always adds work, while omitting it is
unsound for feature-unified downstream and cross-target interaction cases.
## Runtime protocol
The injected runtime uses fixed static buffers and native startup-environment
access because it has no allocator or production dependencies during
construction. Startup acquisition failures use a fixed marker and reserved exit
status so the coordinator cannot mistake an unselected mutant for a baseline
run.
The same guard protocol records sealed active-mutant reach observations through
`GAMMA_REACH`, without separate sampling launches. Incomplete observations never
establish absence. During the sweep, workers claim
mutants from an assignment-time scheduler that tracks active files and items.
The four execution phases share the configured mutant concurrency; same-item
siblings remain runnable while related work is active. Completed mutants publish
exact-test, file, and safe same-site negative reach learning before releasing
their assignments.
Checked-in hints use version-4 YAML grouped by source file, with repeated killer
identities interned per file and generalized schema-v3 identities interned
globally. Promotion projects workspace-relative identities directly from the
persisted campaign record; it performs no population rediscovery. Incremental
promotion upserts that campaign's knowledge and preserves other scopes;
`--replace` rebuilds from the campaign population. Both modes publish against
the exact generation read and verify the replacement. YAML generations are
scanned for forbidden references before strict deserialization begins.
Incremental generalized merging and change accounting use keyed Fx tables,
then restore canonical ordering before publication.
## Test fixtures
Cross-process tests use owned temporary directories and explicit environment
markers. Concurrency tests observe channels, process completion, or ownership
state where those transitions are controllable; watchdogs remain only as
last-resort harness protection outside mutation campaigns.
Tests requiring a host capability are ignored with an explicit reason when the
suite is run generally and fail when invoked specifically without that
capability. Registry and cgroup mechanics use isolated registries and recording
killers. Tests that must exercise the production signal handler run in child
processes, so they cannot leak process-global interrupt state or direct a
fabricated process group from the main test process.