Verify the code citations in a PR's SOTA sources (W1b phase A, report-only) - #1003

Scope

The W1b phase-A source checker verifies commit/path/line citations through GitHub REST and writes JSON plus Markdown. Report mode remains advisory. The final adjudicated repair also bounds report rows and repeated display strings, recording exact omissions as indeterminate. This change also preserves malformed-candidate diagnostics, bounds parsing and REST work, avoids false refusal on indeterminate API responses, excludes mutable abbreviated refs, snapshots ancestry and handles authorization configuration safely.

• Base commit / merge base: 65cf2730068429a1c48c8c18fb24aadef8120817.
• Current head: d92893d7359984ac15e1ee62288978bfff40682e, one forward final-round repair of 82c86da668fda5dc351d03ea524b5a360299aaf6 on the CC's adjudicated fix-now cue.
• Lane: lane:foundation.
• Owned paths: tools/sota-sources/, verifier tests and fixtures, and their evidence bindings.
• Report schema: verify-sources/1; CLI: --repo/--pr --mode report --report, with Markdown appended to GITHUB_STEP_SUMMARY.

SOTA sources

• [mechanism] GitHub REST API version 2026-03-10: commit resolution and compare, commit objects, raw contents, exact references, rate limits, and versions. Original response bytes are retained in the source packet. OpenAPI pin: github/rest-api-description@58b1e0c00b39b9e46c24dc4a0ba6a2669c90e9c1, descriptions/api.github.com/api.github.com.json.
• [mechanism] CPython v3.12.3, python/cpython@f6650f9:Lib/urllib/request.py:L675-L679 supplies the redirect handler/request-processor seams. python/cpython@f6650f9:Lib/http/client.py:L1311-L1314 rejects invalid header values; the checker validates before fetch and never formats that exception. The retained installed CPython 3.13.16 client has SHA256 d12e0060428b8389389db2244f9e1bd7fccae1450d43f74bce91b782498c300a.
• [mechanism] CPython's 4,300-digit default integer conversion bound is python/cpython@f6650f9:Include/internal/pycore_long.h:L29 (_PY_LONG_DEFAULT_MAX_STR_DIGITS). The unmodified pinned header is retained with SHA256 84c0c7bd7ba0c2fbbfb106561e32328e478d8350afe756af6a4862c95d921a06; the parser canonicalizes zero padding and bounds tokens before conversion.
• [mechanism] GitHub authentication, Failed login limit documents insufficient-permission 403/404. Ordinary 403 is unavailable; an explicit contents too_large envelope takes precedence. The documented contents codes are github/rest-api-description@58b1e0c:descriptions/api.github.com/api.github.com.json:L55991-L56059 (200/404/403/302/304, no 422). Size refusal remains synthetic, not observed live. A 401 or identified rate limit stops later requests.
• [mechanism] GitHub troubleshooting, 404 Not Found for an existing resource documents hiding private resources. Commit/content/compare 404s require visible repository metadata before establishing failure; a second 404 is unavailable (repository not visible to this token). The original capture is retained, SHA256 2fd859cca1eaff6fce3d3c4f35ace570dc91acbb228a823beaa9ebbe6617f1c0.
• [reference] RFC 9110 section 15.5.9 identifies HTTP 408 as request timeout, classified as unavailable rather than a citation failure.
• [reference] Linux's 12-character floor: torvalds/linux@a5ebb76:Documentation/process/submitting-patches.rst:L145-L147 and torvalds/linux@a5ebb76:scripts/checkpatch.pl:L3471-L3472. Abbreviated refs also require absence of same-named heads/tags; an unresolved prefix is sha-unresolved, not a missing full commit.
• [reference] lycheeverse/lychee@2bba271:lychee-lib/src/quirks/mod.rs:L23-L24 removes GitHub line fragments, so it cannot perform this line check. Document/package/health verification remains deferred.
• [mechanism] Section selection mirrors the existing presence gate at 65cf273:.github/workflows/pr-metadata.yml:L171-L172 and its Python mirror at 65cf273:blueprints/runtime-workers/openhands/resolver.py:L456-L471. Pinned ECMAScript source tc39/ecma262@5345883164f463e87f8b40aca4956157ecba8783:spec.html is retained for the trim and line-break semantics; the Node parity test executes both workflow scripts.

Source packet for both review families: ~/.local/state/native-agent-stack/coordination/ns2604-coop/lanes/currency-work/pr1003-403-fix-20261011/attachments/, with MANIFEST.sha256 and SOURCE-INDEX.json. All original captures and pins remain byte-exact in prior-packet/; its source index maps those sources. The new troubleshooting capture, complete CC micro, current Codex threads and proofs are included. The original trimmed fixture is replay input; it is not presented as an original HTTP capture.

Evidence-class table

The measurements in this table and the original command block record the reviewed 82c86da repair. The final row-bound repair has separate validation below.

Local commands run at reviewed 82c86da

env -u GITHUB_TOKEN -u GITHUB_STEP_SUMMARY python3 -E -s -B -m unittest tests.test_validate_shards tests.test_evidence_manifest tests.test_sota_sources_gate tests.test_verify_sources tests.test_verify_sources_review tests.test_verify_sources_family_findings tests.test_verify_sources_micro -v
Ran 132 tests, no skips; OK, exit 0

env -u GITHUB_TOKEN -u GITHUB_STEP_SUMMARY python3.12 -E -s -B -m unittest tests.test_verify_sources tests.test_verify_sources_review tests.test_verify_sources_family_findings tests.test_verify_sources_micro -v
Ran 101 tests, no skips; OK, exit 0

nice -n 10 ionice -c 2 -n 7 python3 -E -s -B scripts/validate.py
70 components / 11480 files / 4 profiles / 239 receipts; passed, exit 0

python3 -E -s -B scripts/evidence_manifest.py --check
11480 files; passed, exit 0

git diff --check
exit 0

The final publication receipt records the actual PR-range-only gitleaks scan with full redaction and native count-only privacy checks. No full-history scan is used.

Decision record

tools/sota-sources/review-corrections.md records the primary sources, budget choices, failing-before evidence, caller/adjacent-state scope and measured limits.

• Compare limitations, incomplete/oversize responses, HTTP 400/408, transport/rate-limit/auth failures and ambiguous ref lookups are unavailable. An unresolved abbreviated SHA is separately counted as sha-unresolved. Enforce mode exits 3 for indeterminate rows and 1 for established failures; report mode exits 0.
• Per-run limits are 64 recognized citation occurrences (including repetitions) and 256 HTTP requests including redirect hops/PR retrieval. Within the separate report-row budget, excess recognized occurrences retain not-checked rows; after the first rate limit no subsequent request is sent, including for a previously cached URL. Raw file cache entries retain measurements and headers rather than large content bodies.
• Repository identity is normalized before construction and cache lookup; API numeric id/full_name aliases reuse cached state after metadata establishes them. A repository's default tip is resolved once and every comparison uses that full SHA on page 2. not-on-default-branch:behind and :diverged have distinct counts. Release-tag heads and a grammar naming tags are deferred to phase B; extended SWHID verification remains deferred and its candidates receive unchecked diagnostics. No release-tag behavior is claimed.
• Wider checks cover the changed functions' callers and adjacent cache/budget/rate-stop, named-ref/prefix/full-SHA, compare outcome, raw/error/directory/symlink, redirect origin/auth/hop and report/enforce/CLI transitions. ci: report source citations and align six measured runtime pins #1006 invokes the CLI and uses its Markdown; it does not map status names and needs no matching change.

Boundaries: hosted verifier execution is unrun; actual over-100-MB server refusals, synthetic rate limits and malformed responses are fixture controls. The intermittent Linux compare 422 did not recur during public rechecks; its fixture is explicitly reconstructed from source review. The original scratch 22-mutation list is not in the repository and is not claimed as final validation. Symlinks to directories remain a documented raw-API ambiguity.

The combined micro repair retains every recognized occurrence after prose punctuation and joiners across 12 supported grammar spellings; malformed continuations retain diagnostics. Repository/package pins have a distinct unchecked reason and every row has the same span schema. Successful JSON caches retain only consumed fields. Owner/name case aliases share keys; API-established numeric repository ids/full_name also preserve keys and one tip across rename/redirect aliases. Ref/file-path case remains significant. Public .git-suffix metadata and blob rechecks returned 404, so that suffix is not silently stripped or conflated without API identity evidence.

The 70-fresh-repository synthetic budget replay yields 32 ok, 32 unavailable and six not-checked at 256 requests; this request cap binds before the 64-citation cap. The source packet retains the complete Astra micro (SHA256 7185960587ed5ee270235c3488cdae16f3f24791455aa4db6b268cc9ccd9a245), current Codex threads and pinned #1006 consumer at bd9d46f (SHA256 769cc256339d0ed7a1e065dea3348393488585a70b7a2223dc7524845fe965ed). Fresh tag-resolution bodies bind v3.12.3 and lychee-v0.24.2 to their cited full commits. No hosted verifier execution is claimed.

The current micro repair checks HTTP 100–599 at every reachable REST step and both contents envelope forms. Explicit 403 size refusal precedes generic unavailable while preserving rate-limit stop; no-response states remain unavailable. Hidden 404s require a repository visibility probe at initial resolution and later checks. Unsupported numeric Unicode-dash/comma/tilde ranges produce diagnostics; prose punctuation and joined citations retain each occurrence. Historic family-suite counts are corrected by scope: 29F/7E unadapted, 28F/8E with the retained local comparison-route adapter. The complete replay is attached. Optional additional status semantics and repository-pin grammar remain deferred.

Host evidence

No host receipt or platform status changes.

Checklist

• No workflow or action pin changes in this PR.
• Report-only integration and read-only API use.
• Tests use artificial authorization only; no real credential inspected or exposed.
• No new paid service or hosting.
• Retained peer worktrees and files preserved.

Final adjudicated row-bound repair

MAX_ROWS permits 256 data rows plus one exact omission row across recognized occurrences, malformed candidates and candidate-free entries. Omitted work sends no requests and is indeterminate: report mode stays 0, enforce returns 3 unless an established failure already requires 1. Entry and other row display fields retain at most 1,024 characters with an ellipsis/note; verification and spans use the original input. JSON records all limits and the omitted count; Markdown exposes the bounds and keeps the omission marker out of its checked-citation tally. The grammar, HTTP classifications, compare and cache mechanisms are unchanged by this repair.

Primary mechanism: python/cpython v3.13.16 at cbc944f4bc59639a444dd971c737788ba2283a91:Lib/json/encoder.py:L280-L299 and L336-L358 iterates list rows and dictionary values. The installed mirror blob is retained whole. These are local report-budget choices; no vendor-defined row limit is claimed.

Seven permanent methods replayed on exact 82c86da give six intended assertion failures and zero errors; the exact-boundary preservation case passes. The actual 1,000-token CLI report is 6,557,147 bytes before the repair and fails a 30,000-byte ceiling with the test budgets. With production budgets, an actual 66,017-byte/11,000-candidate input produces 425,301 JSON bytes, 256 data rows plus one omission row and 10,744 exact omissions, enforce exit 3, and zero requests. The earlier 730,517,298-byte large-output value was derived row by row; its full list was never allocated and no worker OOM is claimed.

Final gates: 139 surrounding tests without skips on CPython 3.13.16; 108 verifier tests without skips on 3.12.3; FULL 70 components / 11,481 hashed files / four profiles / 239 receipts; evidence/diff checks pass. Only five repair paths change. Native registration changes three existing bindings plus the new row-limit test; all other evidence metadata is exact. PR-range-only gitleaks scans five commits with 100% redaction and no leaks.

Receipt correction: exact original/current learned-key fixtures both fail at 20eac57 on 9 != 5, one failure/zero errors. The previous statement that the original failed on an unrouted metadata request was wrong. The separate case/URL-form preservation test instead stops there on an unrouted mixed-case commit request; it is not claimed as an intended identity fail-before. Its preservation behavior remains tested.

Follow-ups

• Phase B: release-tag history checks and the grammar for naming tags; extended SWHID verification.

• Document, package and health verification beyond phase A's code-citation checks.

• Optional HTTP 405/409/410/451 classifications and repository-pin grammar.

• Distinguishing symlinks to directories from files beyond one raw contents request.

• Hosted verifier acceptance and a real over-limit contents response remain unmeasured; current controls are synthetic.

• CC final P3: the compare visibility clause's reachability remains a follow-up.

• CC final P3: additional citation joiner variants remain a follow-up.

• CC final P3: refine the remaining 64-citation wording where it does not specify recognized occurrences.

• the encoder citation names the Python fallback; the C path is at L253-L256.

• no test checks the omission row in the Markdown tally.

• omitted rows are reported as indeterminate.

• CC P3 4242461609: treat a 200 from /repos followed by a 404 on contents as indeterminate for tokens with Metadata read but no Contents read. No failure reproduces with the deployed github.token; the private repository probe itself returns 404 and correctly reports unavailable.

• CC P3 4242461612: reject binary blobs before checking line ranges. No committed citation currently points at a binary blob with a line range.