feat: TrackRegistry — presence follows track extent

The spine of the redesign. Presence is now the extent of a track an actor owns,
[first_seen, last_seen], rather than the subset of frames in which recognition
happened to succeed. An actor recognised only at the end of a long track is
present for all of it, which is what the scene-scoped ground truth actually
records.

AR-013 — `last_seen` as an optional carries the entire liveness state: unset
means on screen, set means went off at that timestamp and still revivable,
reaped means emitted and erased. No missing-frame counter, no expired flag. It
subsumes the tracker's existing two-pool split, so there is no separate revival
path — matching a dormant track is ordinary inter-frame association.

The asymmetry is the point: interior gaps are claimed, the trailing cool-down is
not. A face lost and re-associated within the timeout never closed its track, so
the gap is presence — someone briefly occluded has not left the scene. But a
track that dies ends at its last sighting, never at the death time. That is
precisely the over-claim the retired extinction_sec keep-alive produced, where
presence ran on into the closing credits.

AR-014 — a belief swap A→B closes the track and opens a successor at the swap
frame. Not a correction: two non-twins both clearing the threshold on one face
is not realistic, whereas a track_id carried across a viewpoint change onto a
different person is. Treating it as a swap-and-continue would emit one window
blending two people; treating it as a boundary yields two that are each right.

AR-015 — two live tracks owned by one actor means at least one is wrong, since a
person cannot be in two places at once. A reverse index catches it on the update
that causes it rather than by scanning. This makes identity a third cut
detector, independent of the histogram and TransNetV2 and firing where those
failed.

AR-016 — flush() closes tracks still live at EOF. Without it a film ending
mid-shot silently drops its closing cast, which presents as a recognition miss
rather than a bookkeeping bug.

Reaping hands the dead track to the aggregator and erases it, so the registry
holds only live tracks and its size is bounded by concurrent on-screen faces
rather than growing with the film.

Locking: a frame's association pass is atomic as a unit via FrameScope, since
per-call locking would let another thread observe a half-updated frame.
owner() reads tally and verdict under one lock — separately, a track could be
both unowned and owned within a single promotion decision. A vote for an
already-reaped track is dropped and counted, because a nonzero count means the
timeout is shorter than the matcher's lag.

11 unit tests, driven directly against the registry with no network and no
fixture — the awkward cases are constructed rather than hunted for. Suite: 75
cases, 3236 assertions. Coverage 14/63 to 20/63.

Not yet wired into FaceTrackerFunc; that is AR-007/AR-008.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

TRACES: AR-012, AR-013, AR-014, AR-015, AR-016, AR-017 | SR-002

docs/traceability.md

@@ -3,7 +3,7 @@
 <!-- GENERATED FILE - do not edit by hand. -->
 <!-- Regenerate: scripts/traceability/traceability-gate.sh -->
 
-**Generated:** 2026-07-30T19:19:47+00:00
+**Generated:** 2026-07-31T07:07:04+00:00
 
 Denominators are read from [`requirements.md`](requirements.md) at run time, never hardcoded. Coverage counts a requirement only when it is tagged in source **and** has a verification tier this repo's CI host can execute (`T1, T2, T3, static`).
 
@@ -11,13 +11,13 @@ Denominators are read from [`requirements.md`](requirements.md) at run time, nev
 
 | Metric | Value |
 |---|---|
-| Source files scanned | 92 |
-| TRACES tags found | 74 |
+| Source files scanned | 94 |
+| TRACES tags found | 76 |
 | EXCEPTION tags found | 0 |
 | Requirements defined | 63 |
-| Requirements covered | 14 |
-| **Coverage** | **22.2%** (14/63) |
-| Coverage of CI-executable scope | 26.9% (14/52) |
+| Requirements covered | 20 |
+| **Coverage** | **31.7%** (20/63) |
+| Coverage of CI-executable scope | 38.5% (20/52) |
 | Tagged but unexecuted in CI | 3 |
 | Orphan tags | 0 |
 
@@ -25,13 +25,13 @@ Denominators are read from [`requirements.md`](requirements.md) at run time, nev
 
 | Type | Covered | Tagged but unexecuted | Defined |
 |---|---|---|---|
-| AR | 3 | 0 | 27 |
+| AR | 9 | 0 | 27 |
 | DP | 2 | 0 | 8 |
 | IR | 6 | 0 | 8 |
 | GR | 3 | 0 | 9 |
 | VR | 0 | 3 | 11 |
 
-- **UT** tags present (separate taxonomy, not counted in coverage): UT-101, UT-102, UT-103, UT-104
+- **UT** tags present (separate taxonomy, not counted in coverage): UT-001, UT-101, UT-102, UT-103, UT-104
 - **PR** tags present (separate taxonomy, not counted in coverage): PR-002, PR-004
 - **SR** tags present (separate taxonomy, not counted in coverage): SR-001, SR-002, SR-003, SR-005
 
@@ -88,12 +88,12 @@ _None._
 | AR-009 | Done | T2 | SR-002 | untagged | - | Camera-cut detection (histogram) as an association hint |
 | AR-010 | **Not started** — `… | T2 | SR-002 | untagged | - | Scene-boundary detection (TransNetV2) as an association hint |
 | AR-011 | Planned | T1, T2 | SR-002 | untagged | - | **Every model is fed the input it was trained for** — cost reduced by… |
-| AR-012 | Planned | T2 | **SR-002** | untagged | - | Presence follows **track extent**, not per-frame recognition |
-| AR-013 | Planned | T2 | SR-002 | untagged | - | `last_seen` optional state machine; window ends at last sighting, nev… |
-| AR-014 | Planned | T2 | SR-002 | untagged | - | Belief swap A→B terminates the track and starts a new one |
-| AR-015 | Planned | T2 | SR-002 | untagged | - | Two live tracks owned by one actor ⇒ treat as a detected cut, re-asso… |
-| AR-016 | Planned | T2 | SR-002 | untagged | - | All tracks closed at EOF — a film ends with faces on screen |
-| AR-017 | Planned | T1, T2 | SR-002 | untagged | - | Every presence claim carries its belief and identification route |
+| AR-012 | Planned | T2 | **SR-002** | covered | `src/track_registry.hpp`, `tests/test_track_registry.cpp` | Presence follows **track extent**, not per-frame recognition |
+| AR-013 | Planned | T2 | SR-002 | covered | `src/track_registry.hpp`, `tests/test_track_registry.cpp` | `last_seen` optional state machine; window ends at last sighting, nev… |
+| AR-014 | Planned | T2 | SR-002 | covered | `src/track_registry.hpp`, `tests/test_track_registry.cpp` | Belief swap A→B terminates the track and starts a new one |
+| AR-015 | Planned | T2 | SR-002 | covered | `src/track_registry.hpp`, `tests/test_track_registry.cpp` | Two live tracks owned by one actor ⇒ treat as a detected cut, re-asso… |
+| AR-016 | Planned | T2 | SR-002 | covered | `src/track_registry.hpp`, `tests/test_track_registry.cpp` | All tracks closed at EOF — a film ends with faces on screen |
+| AR-017 | Planned | T1, T2 | SR-002 | covered | `src/track_registry.hpp`, `tests/test_track_registry.cpp` | Every presence claim carries its belief and identification route |
 | AR-018 | Planned | T1, T2 | SR-005 | untagged | - | Per-subject embedding store with banded admission (novel enough, safe… |
 | AR-019 | In Progress | T2 | SR-005 | untagged | - | Per-film gallery annex from owned tracks; acquires the non-frontal vi… |
 | AR-020 | Planned | T2 | SR-005 | untagged | - | Deferred re-identification of unknown tracks against the final expand… |
@@ -155,6 +155,48 @@ _None._
 
 - [`src/face_utils.hpp:2`](../src/face_utils.hpp#L2) — `inline cv::Mat align_face(const cv::Mat& img,`
 
+### AR-012
+
+**Locations:** 2
+
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
+### AR-013
+
+**Locations:** 2
+
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
+### AR-014
+
+**Locations:** 2
+
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
+### AR-015
+
+**Locations:** 2
+
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
+### AR-016
+
+**Locations:** 2
+
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
+### AR-017
+
+**Locations:** 2
+
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
 ### AR-023
 
 **Locations:** 1
@@ -369,11 +411,12 @@ _None._
 
 ### SR-002
 
-**Locations:** 3
+**Locations:** 4
 
 - [`src/face_utils.hpp:2`](../src/face_utils.hpp#L2) — `inline cv::Mat align_face(const cv::Mat& img,`
 - [`src/gallery/gallery_calibration.hpp:2`](../src/gallery/gallery_calibration.hpp#L2) — `Unknown`
 - [`src/nodes/face_detector_node.hpp:2`](../src/nodes/face_detector_node.hpp#L2) — `Unknown`
+- [`src/track_registry.hpp:2`](../src/track_registry.hpp#L2) — `Unknown`
 
 ### SR-003
 
@@ -389,6 +432,12 @@ _None._
 
 - [`scripts/make_jellyfin_gallery.py:4`](../scripts/make_jellyfin_gallery.py#L4) — `Unknown`
 
+### UT-001
+
+**Locations:** 1
+
+- [`tests/test_track_registry.cpp:3`](../tests/test_track_registry.cpp#L3) — `Unknown`
+
 ### UT-101
 
 **Locations:** 5