The street-level review instrument (#103): production-path sheet, probe, reduction, and a pre-registered Denver pilot

[jonfroehlich]

Builds the instrument #103 designed: review location precision against the street-level imagery Stage 1 actually consumes — the panorama, the exact ±18.37° crop, and the government point's projected bearing — with the reviewer's verdict recorded as a signed angular offset in §5j's residual convention, so human review of candidate cities cross-validates against the automatic corpus null. Stacked on #97's branch (retarget to main after #97 merges). Design brief and decisions: #103; the §5o pre-registration in this PR fixes the Denver pass/fail criteria before the review happens.

What's here

• rampnet/gsv.py — the production GSV path (fetch_panorama, both projections, heading_to_azimuth) lifted verbatim out of download_dataset.py, which was unimportable (its inference_isolator import loads the round-2 checkpoint at module scope). download_dataset.py now imports from here — one definition each, the KeypointModel consolidation precedent. Plus new pure helpers: the click↔angle maps, pinned against crop_half_angle_deg().
• Two production fixes found by running it, both now shared by Stage 1 and the instrument:
  • the tile endpoint now 403s python-requests' default User-Agent — the paper-era fetch_panorama fetches nothing today; any explicit UA (ours: RampNet-sourcing/1.0) works. Two lines, documented at the constant.
  • GetMetadata 502s under per-pano metadata bursts (15/59 sites on the first probe pass, all recoverable) — cached_search retries transient statuses with backoff; schema drift still raises immediately.
• street_review_sheet.py — the sheet: full 90° production render with the strip edges drawn where they truly are (asymmetric, −18.458°/+18.368°), the bearing crosshair, a nonlinear degree ruler, and neighbour records' bearings (production 35 m inclusion) always visible to resolve which-ramp ambiguity. One pano per record by a recorded rule (nearest 4–30 m, capture ≥ record date, tie-break newest); mandatory reason tags on unjudgeable verdicts so the street instrument's selection bias is measured, not assumed. §5h made structural: pano absences are readable JSON markers (--refetch-absent), failed searches never cache, every input record leaves a terminal status. §5l's two-path bug class prevented by construction: chips and templates extend one base dict, and the JS export iterates the same Python field list.
• probe_panos_at_sites.py — the sheet's dry run at exactly its sites, running the same imported pick rule.
• street_review_summary.py — the reduction: frac-inside-strip against the true edges (the gate quantity), the distribution via stage1_bearing_residual.summarize() verbatim (§5j-column-comparable), Wilson rates + reason breakdown, a sign-flip null (never a test against zero), per-stratum rows, and the paired aerial calibration: each aerial click_px vector projected through the chosen pano's geometry into a predicted residual (radial error predicts ~0°, per §5g).
• docs §5o — instrument description + pre-registered Denver criteria, amended once with probe-measured numbers, all before any review.
• 74 new tests (642 total green), including a Node harness that pins the JS click-to-angle map against the Python definition to 1e-6, drives the page's real click/keydown/button handlers (mutation-checked: breaking any of four clearing rules is caught), and reads the real export payload's key set.
• Code review applied in cbb3191 — six substantive findings and five minors, the load-bearing one being that the gate quantity censored its own denominator: ramp_outside_view records are certainly outside the strip but classified unjudgeable, so §5o now pre-registers and reports a bound that counts them as failures. See the review comment for the full list. sheet_build is unchanged at 5035ec33, so the committed Denver sheet stays valid.

The Denver pilot, as built

Probe: 58/59 sites pick a pano (median range 5.75 m, captures 2016–2026 median ~2021; the failure is a genuine GSV coverage gap, 68791, recorded as its own status). Build: 58/59 rendered in one pass, 19 MB sheet, build 5035ec33; the unfilled verdicts template is committed as the sheet's provenance (per-record pano choice, range, bearing, status). Export→summary round trip smoke-tested against the real sheet and the real aerial pairing.

What is deliberately NOT here

The review itself (Jon's hour), the resulting verdicts and §-write-up, the Seattle sheet, and the alternate-pano pass over the unjudgeable subset. The aerial sheet is not retired — this instrument yields no metric number (#103's stated price). The sheet HTML stays untracked (embedded Google imagery), same policy as the aerial sheets.

🤖 Generated with Claude Code (claude-fable-5)

[jonfroehlich]

Code review — and the fixes, in cbb3191

Reviewed the whole diff against feat/location-precision-96, ran the new tests and the full suite, and reproduced two of the findings before believing them. All six substantive findings and all five minors are fixed in cbb3191 on this branch — details under each. Posting the review as found, rather than only the fixes, so the record shows what the instrument looked like before Denver's review hour was spent on it.

Verified up front: the rampnet/gsv.py lift really is verbatim — I diffed it line-for-line against the deleted block, and the only changes are the lazy cv2/requests/torch imports and the User-Agent header. I also grepped download_dataset.py for every name dropped from its import list (as_completed, io, Image, torch, F, requests, HTTPAdapter): zero remaining references, so the trimmed imports are correct. Full suite before the fixes: 633 passed / 1 skipped, matching the PR body.

---

1. The gate quantity censored its own denominator — and §5o didn't say so

angular_block() computed frac_inside_strip over classify(r) == "measured" only. But a record whose ramp is visible beyond the ±45° render — the largest coordinate error the sample can contain — is tagged ramp_outside_view, classifies as unjudgeable, and never reached the denominator. Criterion 1 was therefore conditional on judgeability, and the censoring runs in exactly the direction that makes the instrument pass.

The code already knew this: the UNREADABLE_REASONS comment calls ramp_outside_view "a coordinate error too large for this instrument to measure". The pre-registration just didn't inherit it. Post-hoc this is unfixable, which is why it led.

Fixed. The summary now reports frac_inside_strip_bound — every ramp_outside_view record counted as a failure — with its own Wilson interval, and §5o gates on the bound. Occlusion unjudgeables (van, pole, sun, quality, too-far) stay out of both denominators: they are missing at an unknown offset, and assuming the worst of them would be as wrong as assuming the best. §5o also gains an amendment log, since a pre-registration is only worth something if its edits are visible; both amendments predate any recorded verdict.

2. phantom_disagreements conflated "couldn't look" with "saw a ramp"

Reproduced before fixing:

aerial: {'id':'X','unreadable':True}     street: {'id':'X','no_ramp':True}
→ aerial_only_unjudgeable: {'n':1,'ids':['X']}
→ phantom_disagreements : {'n':1,'ids':['X']}     ← should not fire

a.get("no_ramp") is falsy for an unreadable aerial record, so any street phantom over an aerial unjudgeable was double-counted. This pilot deliberately renders all 4 aerial unjudgeables, and criterion 4 is about phantom-rate agreement — so it could have inflated the count by 4 of 58 at exactly the point the pre-registration gets read.

Fixed. Both instruments must have judged. The always-true trailing clause went with it, and there's a regression test.

3. A rebuild silently overwrote a reviewed verdicts.json

main() wrote the blank template to review_<city>-gsv/verdicts.json unconditionally — the same tracked path the reviewer exports over. This PR plans two rebuilds after the review: --refetch-absent for 68791, and the second-vantage pass over the unjudgeable subset. Either destroys the review hour unless it happened to be committed first. (Inherited from inventory_review_sheet.py:1322, so not a regression — but the street workflow makes the rerun expected rather than hypothetical.)

Fixed. The build refuses when the existing file carries any human verdict unless --force, and refuses before spending ~2,000 tile requests rather than after. A 0.0° verdict counts as a verdict — the "click the crosshair for ~0" rubric case would otherwise have stayed silently overwritable. A corrupt JSON blob counts as 0 on purpose: refusing to build over one would be a worse failure than overwriting it.

4. The Node harness re-implemented the state machine instead of driving it

The export assertions drove the real handler (document.getElementById("export").onclick()) — exactly right. But the click and terminal-state assertions copied the page's clearing logic into the harness ("Simulate the stage handler's effect directly"). Drop v.no_ramp = false from the real stage.onclick and every one of those assertions still passed. That's the two-path hazard this PR is otherwise proud of designing out.

Fixed. The harness now drives stage.onclick, the captured keydown listener, and the seg() buttons the page itself wires up (the stub memoises querySelectorAll("button") so b.onclick = … lands on objects the test can press). Confirmed by mutation rather than assertion count — four clearing rules broken one at a time in the page:

CAUGHT    click no longer clears no_ramp
CAUGHT    'u' no longer clears the disowned click
CAUGHT    seg toggle-off no longer clears the reason
CAUGHT    note field no longer guarded against shortcuts
SURVIVING MUTANTS: none

All four survived the old harness.

5. The renderer sign-convention test was skipped in CI

test_gsv.py said "a convention error anywhere in the #103 overlay stack cannot survive CI" — but pytest.importorskip("cv2") guards both renderer tests and requirements-dev.txt shipped torch and no OpenCV. In CI those 5 parametrized cases skipped; the claim was only true on a machine with the full env. That test is the only thing pinning the overlay convention against the real projection, which is what made it worth the dependency.

Fixed. opencv-python-headless added to requirements-dev.txt, with the reason at the line. equirectangular_to_perspective needs cv2 only for Rodrigues, and torch was already a dev dep.

6. The summary reduced with the code's constants, not the manifest's

STRIP_LEFT_DEG/STRIP_RIGHT_DEG were imported from the sheet module, so re-reducing an old verdicts.json with newer code would silently change the gate quantity — while paired_calibration set the right precedent by reading metres_per_pixel/span_px out of the aerial manifest.

Fixed. strip_edges(manifest) prefers manifest['projection'] and falls back to the constants, and the summary records which it used, so a number can be read without knowing which version of the script produced it.

---

Minors — all fixed

• --limit truncated after the provenance was built, so a smoke run wrote a manifest and page header claiming the full 58. Now truncates first, and records limit in sites_source.
• No id-integrity check on the sampling path. Sites fell back to str(i) when --id-field was missing → KeyError; duplicate ids silently took another row's date. The --sites-from-verdicts path had a good explicit check; the sampling path now has the same floor, with a message that names the field.
• A partially reviewed sheet reduced silently. incomplete_review is now set and render() prints !! REVIEW INCOMPLETE — the same treatment convention_check already got.
• Cold vs warm cache differ by one JPEG generation (raw assembly on first fetch, q95 round trip after). Immaterial at review resolution, but sheet_build hashes template + rubric only, so it's now documented rather than implied.
• Count drift: §5o said "40 tests", the PR body says 41. Actual is 74 collected across the five files; §5o corrected.

sheet_build is unchanged at 5035ec33, so the committed Denver sheet and its verdicts template stay valid — no rebuild needed. Full suite after the fixes: 642 passed / 1 skipped (the skip is pyproj not installed, pre-existing and local-only).

---

Things this PR gets right, specifically

• test_render_puts_a_feature_at_its_predicted_column pinning the §5j sign through the real projection on a synthetic pano is the right test to have written — it kills the whole class of 90°-off and sign-flip errors. That's why finding 5 was worth a dependency rather than a softened docstring.
• _stripe_centre_column using an intensity centroid rather than argmax, with the reason in the docstring, is the kind of detail that would otherwise have surfaced as a phantom leftward bias.
• The absence-marker trio — never cache a failure, JSON markers carrying reason and attempt count, --refetch-absent — is a genuinely structural fix for §5h rather than a test for it.
• Building chips and the verdict template from one make_base_record and exporting via META.shared_fields does collapse §5l's third path, and test_base_record_keys_are_exactly_the_shared_fields locks it.
• _TRANSIENT_MARKERS being measured (15/59 HTTP 502s on the first probe pass) rather than guessed, with schema drift still raising immediately, is the right split.

🤖 Generated with Claude Code (claude-opus-5[1m])