[mdarocha]

Generated by Claude Opus 5.5

Requires #163. Without it, gc deletes superseded manifests by key across all refs, so one pull request's m3pr# chain would delete another's head; #163 makes that cleanup per ref.

A pull request's cache lookup returns its own m3# manifest before the default branch's (GitHub searches the current ref first), so once a PR has committed a manifest it no longer sees anything the default branch builds afterwards. This makes PR runs write their own family, m3pr#N, and load m3# (which only the default branch writes) together with it, merged with Manifest::merge.

• PR mode is detected from GITHUB_REF (refs/pull/*), or set with --pr-manifest / the pr-manifest action input.
• gc cleans both families and protects packs referenced by PR manifests.
• Tests and docs (README, action README, docs/cli.md) are updated.

[mdarocha]

Generated by Claude Opus 5.5

Results from a private NixOS configuration repository (two hosts, GitHub-hosted 2-core runners, one job per host that builds the host's install and VM tests), running this branch through a composite action.

The case this targets is repeated runs of the same pull request. Before, pull requests ran with read-only: true, because a PR that wrote m3# hid everything the default branch cached afterwards and gc could delete the default branch's chain (#162). So every push to a PR rebuilt whatever the PR changed. With this branch, the PR writes m3pr# and reads it together with m3#.

Same PR, same check derivations in every run (the later read-only push only changed the workflow), both host jobs in minutes:

Run	Host A	Host B	Built in host B job
read-only, first push	15.6	19.8	everything the PR changed
read-only, next push	11.5	16.8	the same again
this branch, first run	11.1	17.6	109 derivations
this branch, re-run	2.2	3.3	3 derivations (4 substituted from hestia)

The re-run logged hestia serve: manifest m3pr#4 unioned with m3#: 1504 paths; the first run logged m3pr#0 unioned with m3#: 1314 paths, i.e. it saw the default branch's 1314 paths before writing anything.

Costs observed:

• Cache space: each PR's own chain was about 30 MB, since most of what a PR needs is already on the default branch.
• Load time: loading both manifests added no visible delay; the drain's load stage took about 6 s, as before.
• Sharing between different pull requests still doesn't happen, because GitHub scopes PR caches to refs/pull/N/merge. Two PRs with the same change both build it.

In this repository it's worth it. A second push to a PR went from about 28 job-minutes to about 5.5. A gc run on the default branch while PR chains existed kept each ref's newest manifest; that run used this branch together with #163, which it requires.