20260925 - Serve each frame's confirmed tracks by timestamp

[Purple10101]

Node ingest 1.6.0 lets a detection frame carry the node tracker's confirmed tracks, each active one naming the detection it took by index into the frame's arrays. Nothing the tracker exposed could fill that: events.jsonl writes nothing for a coasting track and nothing at all when one dies, and names detections by timestamp rather than index. This adds a read-only route that can.

What it adds

GET /frame?timestamp=<ms> on the existing control port (127.0.0.1:30101) returns the tracker's result for that frame: a per-process run id and every confirmed track, each with its state, the detection it took (hit) and its counters. Without a timestamp it returns the latest.

• hit indexes the arrays as received over TCP, before any rejection or SNR gate. process_streaming_frame stamps each detection with frame_index for this; the key is never serialised anywhere, and a test checks every writer.
• State follows the hit, not the internal TrackState. A track that took a detection this frame is active; a confirmed one that did not is coasting; one removed this frame is deleted, once. So an M-of-N promotion on a missed frame first appears as coasting.
• The last 32 frames are held. A frame not held is a 404 carrying run and latest, which tells a caller whether waiting is worth it: latest behind the asked timestamp means not processed yet, ahead means evicted, null means never fed.
• run separates id namespaces. Track ids repeat after a same-day restart; run changes only on a process restart, and survives /reset, since the id counter does too.

Nothing existing changes: events.jsonl, /events, /reset and the ingest socket behave as before.

Evidence

• ruff check, ruff format --check, pytest (390 passed, 1 expected xfail) and pre-commit run --all-files.
• Against production, on jonathan-node-1 on 2026-09-25: this branch mounted into the node's own tracker container and fed by blah2-api's real forwarding, with retina-telemetry sending its tracks to api.retina.fm. Over 2,200 frames, every one had a /frame answer for its own timestamp, and all 279 active hits checked named the detection this tracker's own events.jsonl recorded for that track. One track was bound to aircraft a92361. See 20260925 - Adopt node ingest v1.6.1: ADS-B position tags and the node's tracks retina-telemetry#23 for the full run, including the node's unexplained reboot at the end.

Worth knowing

• avg_snr reads high on a young track: total_snr includes the detection that started it and n_associated does not count it, so a steady 15 dB reads 20.0 at three associations. It is sent as Track.to_dict has always computed it. A separate fix, if wanted.
• latest is the most recently recorded frame, not the largest timestamp held. The two differ only after the node's clock steps backwards.

Release

retina-telemetry reads this route. It is safe in either order: against a tracker without /frame it sends frames without tracks and logs one line. Once released, retina-node's RETINA_TRACKER_V default should move to the new tag.

🤖 Generated with Claude Code

[claude]

Claude finished @Purple10101's task in 3m 48s —— View job

---

Claude's review

• Gather context (read changed files, diff against origin/main)
• Understand the request (code review)
• Review retina_tracker/control.py changes
• Review retina_tracker/server.py changes
• Review retina_tracker/tracker.py changes
• Review tests/test_frame_record.py
• Post review feedback

I traced the whole feature end to end — the frame_index stamping in server.py, the took/deleted bookkeeping and frame_records eviction in tracker.py, and the /frame route in control.py — plus the concurrency story and the test suite. This is careful, well-tested work. I didn't find any correctness bugs. Notes below are things worth confirming or minor observations, not blockers.

Correctness checks that held up:

• Snapshot-before-merge ordering (tracker.py:398-400): deleted is materialized via _frame_track before _merge_tracks() runs on self.all_tracks, so a merge folding a later track into one that died this frame can't corrupt the frozen "deleted" record. The comment explains this and the code matches it.
• took decided at association time, not from state_status afterward (tracker.py:284-289): correctly avoids the trap where a track promoted this frame reads ACTIVE internally regardless of whether it associated. test_a_track_promoted_on_a_frame_it_missed_is_coasting nails this case.
• Locking: process_frame (called from the TCP ingest path) and the /frame HTTP handler both take tracker_lock, so frame_records mutation and reads are properly serialized (server.py grep confirms _handle_line wraps process_frame in the same lock passed to start_control_server). The lock is released before the socket write in _frame(), which is right.
• frame_index isolation: confirmed via grep that no other code assumes a fixed detection key set, so adding frame_index in server.py:40 is safe. test_frame_index_reaches_no_output independently backs this by checking events.jsonl, innovations.jsonl, history.snapshot(), and tracker.to_dict().
• Eviction / replacement: frame_records.pop(timestamp, None) before re-insert correctly handles a repeated timestamp (moves it to the newest position rather than leaving a stale entry), and the while len(...) > MAX_FRAME_RECORDS: popitem(last=False) correctly evicts oldest-first. Both are exercised by tests.
• track.id truthiness (tracker.py:396, 469): Track._generate_id returns a non-empty hex string, so if not track.id / if track.id can't misfire on a falsy-but-valid id (e.g. 0).

Worth confirming / minor notes:

• The avg_snr inflation on young tracks (total_snr includes the seeding detection, n_associated doesn't) is already flagged explicitly in the PR description as a known, separate issue — not something this PR needs to fix, just noting I saw the same thing in _frame_track (tracker.py, near the bottom) and agree it's out of scope here.
• _frame() in control.py parses timestamp with plain int(raw), which accepts negative numbers and leading + (e.g. timestamp=-5 won't 400, it'll just miss and 404 with latest). That's harmless since it's just a dict-key lookup, but worth confirming that's intentional rather than an oversight, since every other value in that space is a real epoch-ms timestamp.
• Ordering in the returned tracks list is: live tracks in self.tracks order, then deleted ones appended at the end. Nothing in the contract (or tests) implies an ordering guarantee, so this is a non-issue unless a consumer starts relying on order.

Verification note: I was not able to execute ruff check, ruff format --check, or pytest in this sandbox (the commands required approval that wasn't available non-interactively), so I relied on static reading of the diff, the surrounding tracker.py/track.py/server.py code, and the new test file rather than running the suite myself. The PR body states pytest (390 passed, 1 xfail), ruff check, ruff format --check, and pre-commit run --all-files all pass, and the production validation against jonathan-node-1 (2,200+ frames, 279 active hits cross-checked against events.jsonl) is strong independent evidence this behaves as designed.

Overall: clean, well-reasoned design (especially the hit-indexes-raw-arrays and run-id-survives-reset decisions), thorough test coverage including the HTTP-level 404/400 cases, and no regressions to existing routes. Nothing here should block merge.