fix(AR-013): reap tracks on the evidence watermark, not the tracker's clock

The registry closed a track when the *tracker's* timestamp passed
`track_extinction_sec`. But votes arrive from the matcher, which is a separate
KPN node behind a channel, and much the slower of the pair. Backpressure —
working exactly as AR-004 intends — turns that channel's depth into lag, so
the tracker's clock can be far ahead of the last frame anybody has voted on.
Tracks were therefore closed before their evidence arrived: the votes landed
on ids that no longer existed, were counted as dropped, and the track was
emitted unowned or not at all.

The symptom is the part worth remembering: **a deeper channel produced fewer
identifications, from identical input.** On the SuperHero fixture, 5 actors /
16 windows at depth 32 against 3 actors / 5 windows at depth 10322; through
the replay harness, capacity 32 gave 5 actors and 10322 gave 0. A throughput
knob was silently changing the answer, which makes every sweep tuned against
it suspect.

The fix is not to bound the channel against `track_extinction_sec` — that
makes an algorithm constant police a throughput knob and leaves the result a
function of scheduling. It is to reap on an evidence watermark: the matcher
advances it as it folds each frame in, and a track is only finished once
everything up to its extinction point has actually been voted on. Same device
`SceneBoundaries::scored_through()` uses for the AR-010 join — a consumer past
that point is asking about frames nobody has looked at yet, and the honest
answer is to wait rather than guess.

Association keeps the tracker's clock, and separating the two is the other
half. They answer different questions: "may this detection link to that
track?" is asked now, about a box seen `track_extinction_sec` ago; "is that
track finished?" cannot be answered until every vote is in. Deferring
association to the evidence clock — which deferring the erase alone did — left
retired tracks associable for as long as the matcher lagged, so a new face
re-associated onto a long-dead track and two people merged into one window.

The watermark is monotonic and only ever *delays* a reap, so no window is
extended by it: AR-013's "a window ends at the last sighting, never after" is
a property of `emit_locked`, which takes `last_seen` and never `now`.

`dropped_votes` is exposed and reported — by main at shutdown and through the
replay bindings — because this failed silently for as long as it did precisely
because nothing counted it. It warns rather than aborts: a dropped frame means
the output describes footage nobody analysed and is always wrong, while a
dropped vote degrades a claim without falsifying it, and there is no
measurement yet of how often it happens on real content.

replay.py's channel capacity stops being the whole film. It was sized that way
to dodge a PyNode overflow drop that AR-004 has since replaced with parking,
and removing backpressure that way is what made the defect above so extreme.

Tag separators in kpn_bindings.cpp corrected to pipes between requirement
types, which the traceability gate was reporting as diagnostics; the matrix is
regenerated and reports 0 orphan tags.

149/149.

TRACES: AR-004, AR-012, AR-013, AR-025 | VR-011 | SR-002 | PR-002
This commit is contained in:
2026-08-08 12:08:15 +02:00
parent 0e27339ab6
commit 24d35cbde3
8 changed files with 494 additions and 140 deletions
+22 -1
View File
@@ -152,7 +152,12 @@ struct IdentityMatcherFunc {
/// Where per-frame identity evidence reaches the registry. Optional: with no
/// registry attached the matcher behaves exactly as before, which keeps the
/// replay harness and the unit tests working unchanged.
void set_registry(std::shared_ptr<TrackRegistry> r) { registry_ = std::move(r); }
void set_registry(std::shared_ptr<TrackRegistry> r) {
registry_ = std::move(r);
// This node is the evidence source, so the registry must not close a
// track until this node's watermark has passed it (AR-013).
if (registry_) registry_->expect_evidence();
}
// Runtime setter — lets a persistent pipeline be reused across a threshold sweep
// without rebuilding the (expensive, gallery-resident) matcher. The gallery,
@@ -165,6 +170,22 @@ struct IdentityMatcherFunc {
return {std::move(tf.source), {}};
}
/// TRACES: AR-012, AR-013 | SR-002
// Publish the evidence watermark BEFORE voting on this frame: every
// observation strictly before it has now been folded in, so the registry
// may reap against it. Unconditional -- a frame with no faces still
// advances the watermark, or a long faceless stretch would stall reaping
// and hold every dormant track open to the end of the film.
//
// This is what makes presence independent of node speed. The registry
// used to reap on the TRACKER's clock, and backpressure (working as
// AR-004 intends) means the tracker can be a whole channel's depth ahead
// of this node -- so tracks were closed before their votes arrived, the
// votes were dropped, and the run silently under-reported. Measured on
// the SuperHero fixture before this change: channel depth 32 gave 5
// actors, depth 10322 gave 0, from identical input.
if (registry_) registry_->advance_evidence(tf.source.timestamp_sec);
// A hard cut changes the camera viewpoint. The face_tracker may revive a
// track_id across the cut (identity continuity), but promotion must never
// mix embeddings from two viewpoints under one buffer, so we still drop