docs(register): record the quality vector, the benchmark, and what lossless fanout costs

Status for the two changes just landed, plus the consequence AR-004's
fix has for the scene join.

The annotator's old comment said blocking there was safe because the
branches are independent. That stopped being true when the fanout became
lossless: it now stops popping once one branch stops taking, so a
starved detector and a waiting annotator would wedge. What actually
makes it safe is join depth -- the fanout can run the dense branch ahead
by the whole of the sampled branch's buffering, which at kSceneJoinDepth
256 and sample_fps 5 against a 25 fps source is ~1200 dense frames
against TransNetV2's 100-frame window. Cutting kSceneJoinDepth below the
window would reintroduce the wedge, so it is now a correctness
precondition rather than a tuning knob.

TRACES: AR-004, AR-010, AR-028, AR-029 | VR-015 | SR-002
This commit is contained in:
2026-08-05 14:38:42 +02:00
parent a5ee3c05ce
commit 718dad688d
4 changed files with 521 additions and 136 deletions
+11 -3
View File
@@ -47,9 +47,17 @@ struct SceneBoundaryAnnotatorFunc {
// consumer is slower, and this branch is orders of magnitude faster per
// frame than TransNetV2. Blocking here is what makes the join real.
//
// Safe under backpressure because the branches are independent: this
// node stalling does not stop the detector consuming dense frames, and
// the fanout keeps feeding it.
// What makes that safe is **join depth**, not branch independence. Now
// that the fanout is lossless (AR-004) it stops popping once this branch
// stops taking, so stalling here does eventually starve the detector —
// the two would wedge if this node could ask about a frame the detector
// has not been given the frames to score. It cannot, by a wide margin:
// the fanout can run the dense branch ahead by the whole of this
// branch's buffering, which is kSceneJoinDepth (256) *sampled* frames,
// and at sample_fps 5 against a ~25 fps source that is on the order of
// 1200 dense frames against TransNetV2's 100-frame window.
//
// Cutting kSceneJoinDepth below the window would reintroduce the wedge.
if (!bounds_->wait_until_scored(f.timestamp_sec)) {
// The detector finished without covering this frame — the tail after
// its last full window. Unknown, not negative; counted so it cannot