gha-cache-proof 1.0.1

GitHub Actions cache compatibility checker and local cache-store receipt tool for offline CI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# gha-cache-proof 1.0 Spec

`gha-cache-proof` is a local compatibility oracle for GitHub Actions cache behavior. It exists so offline runners can attach cache decisions to a receipt instead of embedding cache semantics in every executor.

## Goals

- Provide a deterministic local store for cache save/restore behavior.
- Match the public `actions/cache` search model closely enough for offline CI planning and execution.
- Emit receipts that explain why a cache hit, partial hit, miss, save, or skip happened.
- Scan workflow files for cache action steps and evaluate cache key templates with `gha-expression-proof`.

## Non-Goals

- Bit-compatible archives with GitHub's hosted cache service.
- Network upload/download protocol compatibility.
- Cache billing, org quota, or GitHub API management.
- Secret detection inside cached files.

## Commands

- `restore`: searches the local store, optionally restores files to the workspace, and emits `cache-hit`.
- `save`: snapshots matching files into the local store unless the key/version/scope already exists.
- `check-workflow`: finds cache action steps and proves their configured key/path/search behavior without copying files.

## Match Order

For each accessible scope:

1. exact primary key;
2. primary-key prefix match;
3. each restore key exact match;
4. each restore key prefix match.

Scopes are checked in current-ref, base-ref, default-branch order with duplicates removed.

## Store Layout

```text
<store>/
  index.json
  entries/
    <entry-id>/
      files/
        <workspace-relative files>
```

The index records key, version, scope, path list, runner OS, compression, cross-OS setting, timestamps, file count, and byte count.