ops(stage1): capture live-arm status, rate-limit headers and request timing

[paulieb89]

The first authorised Stage 1 comparison made three live HMLR requests: S1 and S2 completed, S3 returned HTTP 429. The comparator stopped correctly and did not retry — but its report preserved only "HTTPError: HTTP Error 429: Too Many Requests". The status, the reason and any Retry-After were on the exception at that moment and were discarded, so the question the failure raised — how long to wait before the next authorised run — cannot be answered from the evidence we have.

This adds the diagnostics, and nothing else.

What changed

Two files: tools/ppd_snapshot/stage1_shadow.py and its tests. No file under property_core/, app/, property_app/ or property_cli/ is touched, PPDCompsResponse is not widened, and there is no version, changelog or lockfile change.

1. The capture catches as well as returns. A success-only wrapper records nothing about the one case that needs explaining: a 429 raises out of the transport rather than returning, so the exception is the only place the status and headers exist. LiveEvidenceCapture now describes the failure at that seam and re-raises it untouched — observing a failure must not change what the caller sees, and must not retry it.

2. Failures record status, reason and an allow-listed header subset. Exactly Retry-After, RateLimit-* and X-RateLimit-*, matched case-insensitively, values truncated. An allow-list rather than a deny-list: a failed response's headers are upstream-controlled and can carry cookies and infrastructure detail. The response body is never read — HTTPError is itself a readable file object, and pulling upstream content into an evidence file buys no diagnosis. status/reason are null for a non-HTTP failure (a timeout is a different fact from a status of zero); headers is {} when none qualify.

3. Every live observation is timed, on both the success and failure paths. The delay is applied after the call and was dwarfed by it — 2 s against 58 s — so realised spacing can only be read off timestamps, never inferred from live_delay_seconds.

Report schema added

cases[].live_timing        { started_at, finished_at, elapsed_ms, outcome }   // both paths
cases[].live_error_detail  { type, message, status, reason, headers }         // failure only
live_errors[]              { shape, error, type, message, status, reason, headers }

live_error and transport_evidence keep their existing shape.

Proof of failure-path capture (synthetic 429, no network)

"live_errors": [{ "shape": "S1", "status": 429, "reason": "Too Many Requests",
   "headers": { "retry-after": "120", "ratelimit-limit": "100",
                "ratelimit-remaining": "0", "x-ratelimit-reset": "1756820000" } }]
"live_timing": { "started_at": "...", "finished_at": "...", "elapsed_ms": 0.05, "outcome": "error" }
"live_calls_made": 1

Same run, with Set-Cookie, Server, Content-Type and a JSON body present on the response: none reached the report.

Semantics preserved, and asserted

One live observation per case; the existing budget guard unchanged; no retry on 429; no resume-from-case; no automatic backoff; no corpus change. A source-scan test fails if backoff, tenacity, max_retries or a retry loop ever appears on this path. Retry-After is captured so a human can pace the next authorised run — honouring it in-run by waiting and re-issuing would be a second observation for one case, which is the rule this gate exists to hold.

The report's key allow-list gained the new fields deliberately, as its own guard test demands. Allow-listed header names are exempted as a dynamic key space by asking the production allow-list rather than restating it, so a header the comparator would refuse to keep is still an un-reviewed key in the test.

Tests

17 new synthetic tests, no network (the module hard-fails sockets), covering all six required proofs. Focused suite tests/snapshot/test_stage1_shadow.py: 235 passed. ./scripts/validate.sh: exit 0 — 2011 passed, 27 skipped (was 1994).

Scope

No qualify, no compare, no HMLR or live call; no release, deploy or restart; no secret, flag or configuration change. Stage 1 has still not passed and snapshot serving remains off.

Held for review.