Module restore 

Cache::restore per CACHE-019 and CACHE-020.

Restoration materialises the recorded outputs of a cache entry at their workspace-absolute paths and returns the captured stdout/stderr byte streams for the caller to emit. The caller drives stream emission (subject to the task’s output.mode); the cache layer is only responsible for producing the bytes and publishing the files.

Two-phase publish per CACHE-020:

1. Stage. A per-restore directory under crate::layout::cache_root named .restore-<hex-key>-<random>/ collects every output blob, byte-identical to what the entry directory records. Each staged file is written with the recorded mode and fsync-ed. The target’s parent directory is created in this phase too, so phase 2 can be pure renames.
2. Publish. Each staged file is renamed onto its target workspace-absolute path. Renames are atomic on the host filesystem (same FS, since both source and target sit under <workspace_root>).

The cache holds the workspace root so that workspace_absolute_path strings recorded in the manifest (rooted at /) can be mapped to real filesystem paths.

Failure handling matches the spec’s “all or nothing” intent best-effort: every failure inside restore returns an error, and the staging directory is wiped on the way out (success or failure) so transient publishing state is not leaked. If a failure occurs partway through phase 2, some targets are published and others are not; the caller is expected to treat the result as a miss and re-run the task fresh, per CACHE-020 second paragraph.

Structs

RestoredStreams

Captured streams returned to the caller on a successful restore. The caller decides how to emit them per the task’s configured output.mode (CACHE-019 steps 2 and 3); the cache is opinion-free on emission.

Enums

RestoreError

Failure modes for Cache::restore.