[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change (tests/project: 420 OK; new test_workflow_apt_cache.py pins the mirror fallback, package-list agreement, cache key and single saver; TestAptRetry still pins the install loop)
• Changelog entry: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• ci — workflows or build tooling

---

Description of your pull request and other information

Closes #1432. Both apt sites (engine-tests, pypcap-parity) now plan, restore, seed, install, collect and save:

• .deb cache (actions/cache, which works under contents: read). The key is ImageOS + arch + package set + a digest of apt-get install -s's Inst lines, so any new version makes a new key. restore-keys reuses an older set, apt checks each file's hash against the signed index, and only the installed versions get saved.
• Fallback mirror on the retry. azure is dropped from /etc/apt/apt-mirrors.txt, because apt only fails over on an error. The partial download resumes.
• The install loop, its 60s/180s bounds, the 10-minute cap and the ::warnings are unchanged. TestAptRetry pins the bounds.
• The docs' unit-tests.yml:N citations move by +188 lines (pinned by TestDocCitationsResolve).

Checked in ubuntu:24.04. A cold run at 600 kB/s with a 50s bound failed attempt 1, switched to archive.ubuntu.com, fetched only 11.2 of the 24.4 MB left, and succeeded. A warm run printed Need to get 0 B (7s).

What to look for in this PR's CI: every job is a cold miss. Expect Plan … to print a key and Save … to store it. A rerun should show Seeded N .deb files and Need to get 0 B.

• Only parity's Python 3.10 cell saves the cache (APT_CACHE_SAVE), so the matrix cells no longer race on one key.

[github-actions]

Coverage: 89.45% (unit tier, Python 3.14, bc76d3e5c, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	4	93.55%
pcapkit/const	18791	968	2352	869	90.90%
pcapkit/corekit	2038	89	634	25	94.76%
pcapkit/dumpkit	234	2	84	2	98.74%
pcapkit/foundation	2637	98	928	48	94.78%
pcapkit/interface	112	7	40	5	92.11%
pcapkit/protocols	16615	221	4474	185	98.04%
pcapkit/toolkit	539	74	168	3	84.58%
pcapkit/utilities	429	4	122	4	98.55%
pcapkit/vendor	4409	2342	1006	157	43.25%

Per-file detail: the coverage-html artifact of this run.

[JarryShaw]

Verdict: NEEDS CHANGES at 650fa45df (Sonnet cross-review; the author ran on Opus). The code is sound, but it has no tests.

• Works, re-checked by me: PyShark job 113530529150 logs Cache hit for: apt-debs-ubuntu24-X64-PyShark-5f14b79b393a0f71 and then Need to get 0 B/26.5 MB of archives, so the install finishes in 7 s instead of stalling past 180 s.
• Reviewer confirmed:
  • The key (ImageOS, arch, APT_SET, sha256 of the sorted Inst lines) cannot give a stale exact hit.
  • restore-keys falls back only to the same image and package set.
  • apt rejects any seeded file whose hash does not match the signed index.
  • The fallback drops the azure line from apt-mirrors.txt only when another http mirror remains.
  • The worst case still fits the 10-minute step cap.
  • No new permissions, so the 4 contents: read callers are unaffected.
  • The renumbered doc citations resolve.
• Needs: no test pins the new logic. A grep of tests/ for apt-mirrors, apt-debs and APT_SET finds nothing. Add tests for:
  • the mirror drop, including the azure-only and first-attempt-succeeded cases
  • the APT_PACKAGES ↔ install-list agreement
  • the cache key format
• Optional: the two parity matrix cells race to save one key (Unable to reserve cache … another job may be creating this cache). It is harmless, but noisy.
• Unexercised: the live slow-mirror retry path has not run in CI.

The worker is adding the tests.

[JarryShaw]

Verdict: GOOD TO GO at bc76d3e5c (round 2, Sonnet cross-review; the author ran on Opus).

• Tests now pin the new logic. tests/project/test_workflow_apt_cache.py has 15 tests that run each step's real run: text, extracted from the workflow at test time and executed under bash -e with apt/sudo stubbed.

  • Re-derived by me: 15 OK on this head; 25 failures against main's unit-tests.yml.
  • tests/project: 420 OK.

• Save race fixed. Only the Python 3.10 parity cell saves the cache (APT_CACHE_SAVE). The matrix uses quoted "3.10"/"3.11", so exactly one cell saves.

• This head's CI. PyShark logs Cache hit for: apt-debs-ubuntu24-X64-PyShark-5f14b79b393a0f71 and Need to get 0 B/26.5 MB. Both parity cells hit the key the earlier head saved (0 B/27.9 MB). Every install step finished in ≤ 14 s.

• Non-blocking, mutation gaps the reviewer found. These mutations went undetected:

  • removing the cache-hit != 'true' gate on collect/save
  • the seed if: condition
  • the collect step's installed-version filter
  • the seed cp
  • the plan step's apt-get update retry

  The seed and collect scripts never run under test. If any of these broke, the cache would quietly degrade, but the install itself would still be correct.

• Unverified. The fallback-mirror retry has not yet fired in live CI.