feat(run): restore verified local action results

Map eligible macOS hermetic Cargo-check action keys to bounded machine-local CAS results and restore exact declared outputs before Cargo or rustc starts. Fail closed on invalid objects and integrate cache decisions into run explanations, diagnostics, and validated cleanup.

Author: loadingalias

.changes/local-action-cache-7f31.md

@@ -0,0 +1,8 @@
+---
+"cargo-rail" = "minor"
+---
+
+Add a bounded machine-local action/output cache for eligible macOS hermetic Cargo checks. Verified hits restore exact
+declared outputs into a clean root without starting Cargo or rustc; changed inputs, corrupt objects, unsupported
+classes, and other platforms remain fail-closed. Add `--no-cache` and extend `run --explain`, diagnostics, and
+`clean --cache` with local-cache decisions.

docs/architecture.md

@@ -140,7 +140,8 @@ Cargo-rail neither stores result artifacts nor writes or restores Cargo fingerpr
 ## Hermetic execution profile
 
 `cargo rail run --all --action build --hermetic` is an explicit proof profile. It does not alter ordinary `run`
-execution and it is not yet an action-result cache.
+execution. On macOS, an eligible P6 action key now also addresses a machine-local action/output cache. This is not a
+Cargo fingerprint cache or a native per-rustc-invocation cache.
 
 Actual hermetic execution currently requires the explicit built-in `--action build`. Default, profile, workflow, and
 other action dispatch is rejected before workspace context or hermetic state is created; dry-run remains a planning
@@ -182,9 +183,39 @@ boundary is implemented.
 
 The result is a versioned manifest of every declared compiler-output file, directory, symlink, mode, digest, and byte
 count under the isolated Cargo build directory. Cargo's internal fingerprints and incremental state are intentionally
-excluded: their layout is unstable, they are never synthesized, and P7 must not restore a whole Cargo build directory
-as if it were valid state. After source, inventory, toolchain, and platform revalidation, every declared output is
-re-read and compared with that manifest immediately before the report is published.
+excluded: their layout is unstable, they are never synthesized, and cargo-rail never restores a whole Cargo build
+directory as if it were valid state. After source, inventory, toolchain, and platform revalidation, every declared
+output is re-read and compared with that manifest immediately before the report is published.
+
+Eligible action results are stored beneath `$CARGO_RAIL_CACHE_DIR/cargo-rail/local-cas-v1`, or under `CARGO_HOME` and
+then `$HOME/.cargo` when the override is absent. The default byte bound is 10 GiB and
+`CARGO_RAIL_CACHE_MAX_BYTES` may set a different positive bound. A pin maps one exact P6 action key to a versioned,
+length-framed `ActionResult`; that object binds the result digest, output-manifest identity, recursive `Tree` identity,
+and compiler-unit count. Trees bind names, kinds, modes, symlink targets, and versioned `Blob` identities. Blobs are
+streamed and SHA-256-verified from exact bytes. Result bundles are staged, synced, and atomically published before the
+action-key pin. Leases protect active results and deterministic oldest-pin garbage collection enforces the bound.
+
+A lookup verifies the pin, action result, manifest, every tree, object-directory membership, and blob metadata before
+materialization. It then streams blobs into a new private tree while hashing them, validates the complete manifest,
+syncs the tree, and atomically renames it into the clean declared output root. Absolute, parent, NUL, non-portable,
+colliding, oversized, special-file, hard-link, and escaping-symlink forms fail closed. Cargo fingerprints,
+incremental state, mtimes, and sizes never authorize reuse.
+
+The process-free lookup is deliberately narrow: exact text-mode
+`run --all --action build --hermetic`, optionally with `--explain` or `--print-cmd`, and no explicit configuration
+override. A root-independent lookup digest over the exact request and raw root manifests/configuration is only an
+index. Each candidate retains the P6 source,
+resolution, configuration, environment, toolchain, platform, dependency-inventory, package-selection, and action-key
+evidence. Those inputs are revalidated before materialization and again after restore; the lookup digest alone never
+authorizes a hit. Other requests keep their existing cold, unsupported, or platform-limited behavior.
+
+`cache.status = "hit"` means the hermetic `cargo check` action and all compilation units were skipped and the verified
+output manifest was restored. The hit path runs before `WorkspaceContext`, so it launches no Cargo metadata, Cargo,
+rustc, or rustdoc process. It still hashes the exact retained P6 inputs and performs the two current-host platform
+identity probes. `--no-cache` retains the explicit cold proof path. `run --explain` reports hit, ordinary miss,
+uncacheable, and disabled states; corrupt or incompatible selected objects produce an explained error with
+`--no-cache` and validated-cleanup guidance instead of an implicit cold fallback. `clean --cache` removes a shared
+cache only through a canonical workspace reference and an exact ownership marker.
 
 | Action class | macOS proof | Other hosts | Current contract |
 |---|---|---|---|

docs/commands.md

@@ -111,6 +111,9 @@ Options:
       --hermetic
           Execute supported Rust actions in fresh isolated roots
 
+      --no-cache
+          Disable local action-result reuse for this hermetic execution
+
   -f, --format <FORMAT>
           Dry-run action plan format (json/github require --dry-run)
 
@@ -1291,7 +1294,7 @@ Usage: cargo rail clean [OPTIONS]
 
 Options:
       --cache
-          Clean metadata cache only
+          Clean validated local and workspace cache state
 
   -q, --quiet
           Suppress progress messages (for CI/automation)
@@ -1331,7 +1334,7 @@ Options:
 
 Examples:
   cargo rail clean                      # Clean all artifacts
-  cargo rail clean --cache              # Clean metadata cache only
+  cargo rail clean --cache              # Clean validated local and workspace cache state
   cargo rail clean --backups            # Prune old backups
   cargo rail clean --reports            # Clean generated reports
   cargo rail clean --check              # Check for pending cleanup (exit 1)

docs/troubleshooting.md

@@ -36,13 +36,17 @@ not itself a cache key.
 
 ```bash
 cargo rail run --all --action build --hermetic
+cargo rail run --all --action build --hermetic --explain
+cargo rail run --all --action build --hermetic --no-cache
 cargo rail run --all --action build --hermetic --dry-run --format json
 ```
 
-The first command requires a reviewed `Cargo.lock` and executes the explicit built-in `cargo check` action in a fresh
-source, target, build, Cargo-home, home, and temporary root. Before the fetch boundary, only local-package metadata runs
-locked/offline. The explicit fetch action may use the network; full metadata and the check then run locked/offline. The
-JSON preview names the intended boundary without executing it; preview planning is not itself a network-denial proof.
+On a cold run, the first command requires a reviewed `Cargo.lock` and executes the explicit built-in `cargo check`
+action in fresh source, target, build, Cargo-home, home, and temporary roots. Before the fetch boundary, only
+local-package metadata runs locked/offline. The explicit fetch action may use the network; full metadata and the check
+then run locked/offline. An eligible local-cache hit restores before workspace context, metadata, fetch, Cargo, or
+rustc starts. The JSON preview names the intended boundary without executing it; preview planning is not itself a
+network-denial proof.
 Actual execution currently requires `--action build`; default, profile, workflow, and other action selection is
 rejected before workspace context or hermetic state is created.
 Feature, target, target-kind, and profile arguments remain available after `--`. Workspace/package selectors,
@@ -56,7 +60,7 @@ global wrapper records workspace and external dependency compiler units. Cargo a
 emitted outputs, and dep-info must agree exactly or the action remains uncacheable.
 
 Successful executions write a redaction-safe report under `target/cargo-rail/hermetic/reports/`. Read `support`,
-`enforcement`, `action_key`, `result_digest`, `fetch`, `output_manifest`, and `reasons` together:
+`enforcement`, `action_key`, `result_digest`, `fetch`, `output_manifest`, `cache`, and `reasons` together:
 
 - `eligible` currently means a pure current-host Cargo check protected by the macOS filesystem/network sandbox.
 - `platform_limited` means isolated roots and offline Cargo ran, but the host could not enforce the complete boundary;
@@ -69,11 +73,31 @@ Successful executions write a redaction-safe report under `target/cargo-rail/her
 `cargo check --all-targets` proves compilation of library, binary, test, example, and bench units; it does not execute
 tests or benchmarks. Ordinary `cargo rail run` behavior is unchanged and remains the way to run unsupported classes.
 
-A warm `fetch.reused = true` means only that the exact immutable dependency inventory was reused. P6 does not contain
-an action-result CAS and never restores compiler outputs or Cargo fingerprints. That begins in P7. Remove reports,
-inventories, run state, and the existing diagnostic evidence with:
+A warm `fetch.reused = true` means only that the exact immutable dependency inventory was reused. It is independent of
+the local action/output cache. The process-free lookup currently accepts only exact text-mode
+`run --all --action build --hermetic`, with optional `--explain` or `--print-cmd`, no `--config` override, and no
+trailing Cargo arguments. For an eligible P6 key, the cache surfaces have these meanings:
+
+- `hit`: every CAS object and exact blob byte verified, the complete output manifest was restored into a new root, and
+  the hermetic `cargo check` action and compiler units did not execute;
+- `miss`: no action-key pin exists, so cold execution may populate it;
+- `corrupt` or `incompatible`: a selected pin or object was missing, malformed, tampered, oversized, or from another
+  schema. The command fails with an explanation; use `--no-cache` for an intentional cold run or `clean --cache` for
+  validated cleanup;
+- `disabled`: `--no-cache` was requested or the cache root/reference was unavailable;
+- `uncacheable`: P6 did not issue an eligible action key.
+
+These booleans are named `cargo_check_executed` and `compiler_units_executed` deliberately. A hit launches no Cargo,
+rustc, or rustdoc process, but it is an action/output restore rather than native per-invocation compiler caching. The
+lookup digest is non-authorizing; retained P6 inputs, all CAS objects, exact blob bytes, and final platform/input state
+must verify. Cache objects default to `$CARGO_HOME/cargo-rail/local-cas-v1` or
+`$HOME/.cargo/cargo-rail/local-cas-v1`. Set `CARGO_RAIL_CACHE_DIR` to choose the base and
+`CARGO_RAIL_CACHE_MAX_BYTES` to change the 10 GiB bound.
+
+Preview cleanup without deleting anything, then remove only the validated cargo-rail-owned root and workspace state:
 
 ```bash
+cargo rail clean --cache --check
 cargo rail clean --cache
 ```