fix(optics): no FOV gate for frames from an unknown optical train

[brickbots]

Grilling session output for "debug mode stopped solving after the 2.6.2/3 lens system". Two commits: the decision (CONTEXT.md + ADR 0029 amendment), then the code.

The bug

--camera debug derives its FOV gate from hq × whatever lens the config states. ADR 0027 fixed the sensor half (relabelled the debug camera imx296 → hq, PR #609) and left the lens half reading live from camera_lens, which resolve_lens honours whatever profile it is handed. Measured against the real solver and the shipped default_database.npz:

train	derived FOV	gate	debug_01 / debug_02
hq + no stated lens	10.33°	[8.78, 11.88]	solves (fits 10.20°)
hq + stated 25mm	10.33°	[8.78, 11.88]	solves
hq + stated 16mm	17.12°	[14.55, 19.69]	no solve
hq + stated 12mm	20.43°	[17.37, 23.49]	no solve

So anyone who has opened the Lens menu — and every device whose lens 0029's self-heal has written — loses debug mode. tests/test_optics_solving.py missed it because every case called build_optical_train("hq") with no lens key, exercising only the assumed path.

Second bug, live since 0029, fixed here too. With no camera_lens in config, debug mode solves at 10.20°, identify_lens_from_fitted_fov matches that to the hq's 25mm within 1.3%, and the integrator states it. It is in Rich's own log firing on 2026-08-17:

Lens self-heal: 3 solves fitted 10.20 deg, which is the 25mm (10.33 deg derived).
Stating it in config; the FOV gate narrows from the assumed range to this lens...

Attach a real imx462 afterwards and the now-stated 25 mm derives 6.4°, nothing solves, and self-heal can't undo it — it only ever writes into an absence.

The decision

A new term, unknown optical train: a camera whose frames did not come through this device's optics. It extends 0029's ladder rather than special-casing the debug camera —

stated → ±15% · assumed → union over shipped lenses · unknown → no gate at all

— and one rule covers both bugs: nothing about the device may be asserted about the frames (no FOV hint), and nothing about the device may be inferred from them (no self-heal write).

Rejected, with reasons in the ADR: declaring a lens from the camera (needs a second writer for camera_lens, and gates out frames you drop in yourself — the main use of debug mode); emulating the configured train (right answer to a different question, wants captures we don't have); a database-range gate (no-hint with extra steps); rejecting non-shipped pairings in resolve_lens (fixes this and the sensor-swap deadlock, but makes a user's statement conditionally non-authoritative — a direct contradiction of 0027, and it deserves its own decision).

Cost of no-hint, measured: all three widths return identical RA/Dec, Matches and Prob on the shipped frames, within ~1 ms. What it gives up is the upper bound that rejected confident mis-solves in 0029's noise trials — a protection that matters to a device under the stars, and nothing is under the stars in debug mode.

What changed

• CameraInterface.optical_train_known() defaults True, so a camera has to opt out — a new hardware backend inherits the gate rather than silently losing it. CameraDebug returns False.
• Published beside camera_type in get_image_loop; SharedStateObj defaults it True so the boot window before the camera reports keeps its gate on real hardware.
• solver.py omits fov_estimate/fov_max_error entirely, and says so in the one-shot train log line. _warn_if_outside_solver_database is skipped — it's only meaningful against a gate we're actually handing over.
• LensSelfHeal._observe returns early, ahead of the stated-lens branch so a streak counted on real optics can't be spent on a recording.

Scope stops there. The frustum keeps deriving from the configured optics — it answers "what would my camera image", a question about the device, and propagating would delete a frustum that is correct on a dev laptop (10.33° vs 10.20° frames). SQM is unaffected: only camera_pi publishes radiometer samples.

Verification

End to end, not just unit tests. Launched headless with camera_lens: "16mm" stated — the exact config that produced zero solves:

"camera_solve": { "RA": 296.37, "Dec": -1.70, "Roll": 312.18 },
"constellation": "Aql", "FOV": 10.2016, "Matches": 21, "solve_source": "CAM"

with Optical train is unknown ... lens self-heal is off in the log and the config left unwritten. (A stated 16mm gates [14.55, 19.69], so a solve is only possible via the no-gate branch.)

• 1313 passed, -m "unit or smoke"; 20 passed in test_optics_solving.py
• ruff check + format clean; mypy clean on all five touched modules
• Two -m integration failures (test_radec_entry, test_all_ui_modules_covered) reproduce on untouched origin/main — the second only when test_battery_titlebar_icon.py's _BareModule helper is loaded in the same session. Pre-existing, unrelated.

New tests: every lens a config can name, asserting both that the derived gate rejects these frames and that no-gate solves them; the self-heal bar plus a control showing the identical fit would have promoted on real optics; the opt-out default in both directions.

Not in scope

The sensor-swap deadlock — switch imx296 → hq from the Camera Type menu with a stated 16 mm → 17.12°, no solves, no way to measure out. Real hardware, real statement, different failure class. Rich says it's filed; the closest issue I found is #613.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CUbR3ryYDL7RizsNhPxGkX