Cargo-Rail

Cargo-Rail uses a multi-layered caching strategy to preserve work. Each layer provides a different level of authority and result type:

• Cargo L0: Uses Cargo fingerprints and incremental state. Allows Cargo to skip fresh work.
• Local L1: Stores exact compiler actions, results, and bytes. Restores a single compiler result locally.
• Remote L2: Uses a machine-owned provider to share verified result packs. Results enter L1 before being restored.
• Distributed miss: Uses a pinned worker capability and validated response to execute an eligible miss remotely.
• Compiler evidence: Uses identity-matched, revalidated observations and typed facts to allow Unify or Surface to skip acquisitions.

Note: A lookup is not authority. If cache evidence is missing, stale, ambiguous, unsupported, or corrupt, the system falls back to standard compiler execution with a stable miss or bypass reason.

Cargo-Rail provides an exact scope for executors (like Cargo, nextest, or CI) by combining source/config changes, target ownership, dependency edges, and observed inputs.

The Workflow:

1. Planning: cargo rail plan generates a plan containing exact cargo_args arrays for every required work decision.
2. Execution: Instead of using path globs, pass the exact cargo_args provided by the planner to your executor.
3. Validation: Cross-process consumers must validate the contract (v9) and verify that the current HEAD and captured source match the saved plan before executing selectors.

Example Workflow for CI (GitHub Actions): Use the loadingalias/cargo-rail-action@v10 to run the planner and extract arguments for nextest.

- uses: loadingalias/cargo-rail-action@v10
  id: rail

- name: Test affected packages
  if: contains(fromJSON(steps.rail.outputs.required-work), 'cargo.test')
  shell: bash
  env:
    PLAN_FILE: ${{ steps.rail.outputs.plan-file }}
  run: |
    ARGS_FILE="$(mktemp "$RUNNER_TEMP/cargo-rail-args.XXXXXX")"
    cargo-rail-action plan cargo-args "$PLAN_FILE" cargo.test > "$ARGS_FILE" || exit "$"
    CARGO_ARGS=()
    while IFS= read -r -d '' argument; do CARGO_ARGS+=("$argument"); done < "$ARGS_FILE"
    rm -- "$ARGS_FILE"
    cargo nextest run "${CARGO_ARGS[@]}" --locked

Cargo-Rail operates using a model of separate, specialized workflows that share captured infrastructure but do not invoke one another implicitly. This separation ensures that each workflow owns a specific domain of responsibility and does not overstep its authority.

Cargo-Rail caches verified compiler results rather than raw target directories. Each hit revalidates the compiler action, inputs, environment, dependencies, outputs, and stored bytes before presenting the result to Cargo.

Caching Layers:

• Cargo L0: Cargo's own freshness and incremental compilation remain authoritative.
• Local L1: Reuses verified results across Cargo, nextest, Just, IDEs, and CI.
• Remote L2: Shares verified results via AWS S3, Cloudflare R2, or Azure Blob Storage.
• Distributed miss: Automatically places new results once sufficient evidence of a material win is collected.

Key Behaviors:

• cargo clean does not delete the local Cargo-Rail CAS (Content Addressable Storage), allowing an empty target tree to still reuse verified work.
• Local storage has a default 10 GiB limit. Cargo-Rail manages this by removing the oldest eligible action authorities when the limit is reached.
• Use CARGO_RAIL_CACHE=off to run a cold build without interacting with the CAS.

If cargo rail plan selects the wrong work, use --explain for human-readable output or --json for programmatic inspection.

When inspecting the JSON output via jq, verify these fields in order:

1. inputs.base, inputs.head, and inputs.head_commit: Ensure the intended comparison base and head are correct.
2. changes: Verify the expected file, Cargo, and configuration deltas.
3. work.NAME.state: Check if the item is required or skipped. Required items include a .cause and refer to the top-level evidence map via .evidence entries.
4. work.NAME.scope: For required items, check the package, target, or variant selector used by the executor.

Note: If the plan is correct but execution is wrong, the issue lies with the consumer that lowered the typed scope. Always transfer the exact plan across CI jobs to avoid discrepancies caused by differing environments (toolchains, catalogs, etc.).

cargo rail plan --explain
cargo rail plan --json | jq '{inputs, changes, required, work, evidence}'