feat: the pieces for carrying completeness evidence in the shards' job logs

[sotashimozono]

Part of #82. Adds the transport and leaves it unreferenced — the workflow wiring is a follow-up. Pairs with #83, which fixes the other failing job.

Why it is split

The first attempt wired it in the same PR and CI answered:

Can't find 'action.yml' ... for action 'QAtlasHub/TestShards.jl/actions/read-evidence@main'

uses: accepts no expression, so @${{ github.sha }} is not a way out, and a relative path is exactly the trap actions/read-history was extracted to document — a relative reference in a reusable workflow resolves in the caller's checkout, which works in this repo's CI and exits 127 on every consumer. A new action and its first reference cannot land together.

The split has a second benefit: nothing here is called yet, so no consumer's behaviour can change.

The problem this exists for

Every unit ran, exactly once   FAILURE
| units observed | 0 |
TestShards: no shard reported how many units it observed — cannot verify the run.

The only failing step in collect (measured, lab-sotashimozono/ParameterizedITensor.jl run 32238414796), and it fails correctly: the pattern: download succeeds with zero results, the merge succeeds on nothing, and the gate refuses rather than passing blind.

Artifact storage is metered in GigabyteHours against a per-period allowance. Once crossed, CreateArtifact refuses before any bytes are sent, and deleting artifacts does not un-accrue the period. The transport has to stop being storage.

actions/cache was measured and does not work

control	result
save in a matrix leg	succeeds — Cache saved with key: …, listed active on the right ref
restore by exact key, same run	miss
…with a 45 s gap	miss — not propagation
…a key from a previous run, confirmed present via the API	miss — not a same-run race
…a default-branch key written by this repo's own CI	miss — not a ref-scope rule
a key never written	miss (correct)

Four runs, no error, no diagnostic.

What works

Verified end to end in a live run: recovered 3 of 3.

	artifacts	cache	job logs
Actions storage	metered	none	none
works here	yes	no	yes
permission	runtime token	runtime token	actions: read
fork PR	yes	untested	yes
residue	retention	LRU	none
re-run isolation	run-scoped (mixes attempts)	key needs run_attempt	/attempts/{n}/jobs

Why the parsing is in the package

The repo's own rule — "a merge written as a step script is unreachable from Pkg.test()" — and it bites hardest here, because every mistake made while measuring this was a parsing mistake:

1. The runner echoes the step script into the log, so the marker appears twice: once as source with $(...) unexpanded, once as output. First-match decodes the literal $(base64 -w0 ev.tsv). It surfaced as base64: invalid input by luck, not as a wrong answer. Fixed by construction — base64's alphabet cannot spell an unexpanded substitution — so no "prefer the last match" convention is relied on.
2. gh api .../jobs/{id}/logs does not work. 302 to a blob URL; gh exits 1 with no useful message. curl -sSL follows it.
3. The API names a reusable workflow's job with the caller's prefix — ci / test / shard s5. A name filter would depend on the caller's job name, and one matching nothing reads zero logs and reports a complete-looking empty run. No name filter; the marker discriminates.
4. /runs/{id}/attempts/{n}/jobs, not /runs/{id}/jobs — the latter merges attempts, so a re-run double-counts while looking clean. evidence_scan refuses a duplicate shard id outright.

Verification

• test/core/test_evidence.jl — round trip through tabs/newlines/5 KB, the double-marker log verbatim, absent vs corrupt, duplicate shards, and evidence_cli reproducing the two files byte for byte against the real formats read off src/json.jl, then fed to an unchanged completeness_cli.
• Mutation-tested, because a green test proves nothing until it can go red: widening the payload character class (the bug actually shipped in the probe), accepting a duplicate shard, treating "no evidence anywhere" as success. All three go red; restoring goes green.
• actions/read-evidence/read-evidence.test.sh — TS_GH/TS_CURL are indirected so all six branches run with no network and no token: all readable; one unreadable (warned, not fatal — which shard is missing is the gate's judgement, not the fetcher's); none readable (fatal); empty job list (fatal); failing job-list call (fatal).
• actions/read-history/read-history.test.sh still passes.

One finding outside this PR

format-check here resolved JuliaFormatter 2.12.6 from version="2". That floating spec is the defect lab-sotashimozono/.github already fixed and documented — it pins JF_VERSION: '2.10.1' exactly, with a comment recording that a range "silently resolved to 2.3.2 while a laptop resolved 2.10.1". QAtlasHub/.github's copy never got that fix, so formatting locally against the sibling org's pin produces a red check here. Worth a separate issue on QAtlasHub/.github.

🤖 Generated with Claude Code

[github-actions]

📚 Docs preview: https://codes.sota-shimozono.com/TestShards.jl/previews/PR84/

(updates on each push to this PR)

[codecov]

Codecov Report

❌ Patch coverage is 0% with 94 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/evidence.jl	0.00%	94 Missing ⚠️

📢 Thoughts on this report? Let us know!

[sotashimozono]

Closing unmerged — keeping the current behaviour.

The measurements are the part worth keeping, and they are recorded in #82:

• actions/cache does not work here. Save succeeds and the entry lists as active on the right ref; restore misses every key — including a default-branch entry written by this repo's own CI, with a 45 s gap to rule out propagation. Four runs, three controls.
• The log channel does work, verified end to end in a live run: recovered 3 of 3, no storage, no residue, actions: read only.
• A new action and its first reference cannot land in one PR. uses: …@main cannot resolve before the action is on main, uses: takes no expression, and a relative reference in a reusable workflow resolves in the caller's checkout.
• Three parsing traps, each of which would have shipped broken: the runner echoes the step script so the marker appears twice; gh api …/jobs/{id}/logs answers 302 and gh does not follow it; the API names a reusable workflow's job with the caller's prefix (ci / test / shard s5), so any name filter depends on what the caller called its job.

Nothing here was referenced by the workflow, so closing changes no behaviour.