dtourolle/scene-actor-extraction
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1dfd6fea112c4835d72b4e5cc6a5d366b2ccd583
scene-actor-extraction/docs/traceability.md
T
dtourolleandClaude Opus 5 13bdc27566 feat: join the decode butterfly so scene boundaries reach the face branch 
AR-010 — is_scene_boundary had no producer: SceneDetectorFunc was a terminal
sink writing scenes.json and never annotating the frames flowing to face
detection. The flag was permanently false, so the boundary half of AR-007's
frame-dependent association was dead code that a test could still exercise
synthetically and appear to verify.

The topology already forks after decode — dense frames to TransNetV2, sampled
frames to face detection — so this is a fork-join. SceneBoundaries is the join:
the detector publishes each window's verdict with a watermark, and an annotator
on the sampled branch stamps the flag.

The watermark is the part that matters. TransNetV2 buffers 100 frames before it
can score any of them, so at any instant it has an opinion up to some time T and
none after. Without recording T a consumer cannot tell "no boundary" from "not
scored yet", and those demand opposite behaviour — treating unscored frames as
boundary-free is exactly what makes a downstream check pass while verifying
nothing.

Buffering alone does not work, which was my first attempt. Channel depth creates
lag only when the consumer is slower, and the face branch runs four orders of
magnitude faster per frame than TransNetV2 (0.01ms vs 400ms), so its channels
drain instantly and no lag accumulates. Measured: 106 of 364 frames outran the
detector. The annotator therefore waits on the watermark explicitly. The
detector signals completion so the tail cannot deadlock, and publishes from
flush_remaining too — without that the final frames arrive with no verdict.

Boundaries are deduped on publish, matching what scenes.json does at write time.
A run of adjacent high-scoring frames is one boundary, not several; leaving them
raw made this view report 357 where the file said 13. Now the two agree exactly.

Frames past the detector's last scored window remain unverified and are counted
as such rather than silently marked boundary-free.

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

TRACES: AR-007, AR-010 | SR-002
2026-07-31 14:56:38 +02:00

42 KiB
Raw Blame History

Requirements traceability matrix

Generated: 2026-07-31T12:29:10+00:00

Denominators are read from 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).

Summary

Metric Value
Source files scanned 103
TRACES tags found 95
EXCEPTION tags found 0
Requirements defined 67
Requirements covered 28
Coverage 41.8% (28/67)
Coverage of CI-executable scope 50.9% (28/55)
Tagged but unexecuted in CI 3
Orphan tags 0

By type

Type Covered Tagged but unexecuted Defined
AR 15 0 30
DP 2 0 8
IR 8 0 8
GR 3 0 9
VR 0 3 12
  • UT tags present (separate taxonomy, not counted in coverage): UT-001, UT-101, UT-102, UT-103, UT-104
  • IT tags present (separate taxonomy, not counted in coverage): IT-001
  • 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

Not executable in CI

These requirements have no verification tier this repo's CI host can run, so a tag on them is evidence of intent, not of verification. They are never counted as covered.

ID Tiers Tagged in source Requirement
AR-027 T4 no Throughput acceptable for arbitrary gallery size
VR-001 out-of-ci yes HDF5 post-inference dump at the embedded-frame boundary
VR-002 out-of-ci yes Replay drives the real KPN nodes, not a reimplementation
VR-003 out-of-ci yes Scoring: micro-F1 against X-Ray, precision/recall logged at every eva…
VR-004 out-of-ci no Reproducible validation corpus with ground truth
VR-005 out-of-ci no Minimum face size study — TPI/FPI vs probe size, gallery held at nati…
VR-006 out-of-ci no Re-tune scene_threshold once native-rate decode lands
VR-007 out-of-ci no Expansion band, clustering threshold, and deferred-pass ablation
VR-008 out-of-ci no Gallery scaling benchmark — throughput vs gallery size
VR-010 out-of-ci no Dump provenance attributes — embedder model, detector settings, `dens…
VR-011 out-of-ci no Rewrite the replay harness for the post-AR-012 output contract
VR-012 T4, out-of-ci no Quality-knee study — TPI/FPI vs sharpness and vs pose, as VR-005 did …

Tagged but unexecuted: VR-001, VR-002, VR-003 — a test exists and is tagged, but this CI host cannot run it. Report those runs separately.

Orphan tags

A tag naming an ID requirements.md does not define. This is what renumbering produces, and what a typo produces.

None.

Requirements tracing up to nothing

A register row whose Traces to cell names no parent. Work serving no stated goal is how scope creeps in, and it is invisible unless something looks.

None.

Recorded exceptions

Deliberate, documented departures from an invariant (EXCEPTION: XX-nnn <reason>). Reported separately and never counted as coverage — an exception is a decision to be reviewed, not evidence a requirement is met.

None.

Register

ID Status Tier Traces to Trace state Tagged in Requirement
AR-001 Done T3 SR-002 covered src/nodes/face_detector_node.hpp Detect faces in sampled frames; emit bbox, confidence, 5-point landma…
AR-002 Planned T2 SR-002 untagged - Minimum face size 32×32 px (VR-005 measured), expressed in **orig…
AR-003 Done — `max_fac… T1, T2, T4 SR-002 covered src/config.hpp, src/nodes/face_detector_node.hpp, src/nodes/identity_matcher_node.hpp No fixed per-frame face cap — crowd scenes must not lose background c…
AR-004 Done — KPN node… T1, T4 SR-002 covered src/main.cpp, src/nodes/identity_matcher_node.hpp, tests/test_replay_fixtures.cpp Backpressure: unbounded faces/frame absorbed by slowing, never by dro…
AR-005 Done T1, T3 SR-002 covered src/face_utils.hpp Align to 112×112 via ArcFace 5-point similarity transform
AR-006 Done T3 SR-002 untagged - 512-d L2-normalised embeddings, batched
AR-007 Done — `track_a… T2 SR-002 covered src/config.hpp, src/main.cpp, src/nodes/face_tracker_node.hpp Associate detections by IoU + embedding, with frame-dependent wei…
AR-008 Done — one pool… T2 SR-002 covered src/config.hpp, src/main.cpp, src/nodes/face_tracker_node.hpp One track pool keyed on last_seen; no separate revival path
AR-009 Done T2 SR-002 untagged - Camera-cut detection (histogram) as an association hint
AR-010 **Blocked on a desi… 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 Done — `src/tra… T2 SR-002 covered src/main.cpp, src/nodes/identity_matcher_node.hpp, src/nodes/result_sink_node.hpp, src/track_registry.hpp, tests/test_replay_fixtures.cpp, tests/test_track_registry.cpp Presence follows track extent, not per-frame recognition
AR-013 Done — `last_se… T2 SR-002 covered src/track_registry.hpp, tests/test_replay_fixtures.cpp, tests/test_track_registry.cpp last_seen optional state machine; window ends at last sighting, nev…
AR-014 Done — swap clo… 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 Done — reverse … 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 Done — `flush()… T2 SR-002 covered src/main.cpp, src/nodes/result_sink_node.hpp, src/track_registry.hpp, tests/test_track_registry.cpp All tracks closed at EOF — a film ends with faces on screen
AR-017 Done — `DeadTra… T1, T2 SR-002 covered src/nodes/result_sink_node.hpp, 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…
AR-021 Planned T2 SR-005 untagged - Cluster unknown tracks into one entity per person, under temporal can…
AR-022 Planned T1, T2 §4 untagged - Capture still-unidentified tracks: embeddings, metadata, **context cr…
AR-023 Done T1 SR-002 covered src/gallery/gallery_calibration.hpp, src/nodes/identity_matcher_node.hpp Fit sigmoid calibration from intra/inter similarity distributions
AR-024 Done — associat… T1, static SR-002 covered src/config.hpp, src/evidence_discount.hpp, src/gallery/gallery_calibration.hpp, src/main.cpp, src/nodes/face_tracker_node.hpp, src/nodes/identity_matcher_node.hpp Always the calibrated probability, never a raw cosine — exception…
AR-025 Done — log-odds… T1 SR-002 covered src/evidence_discount.hpp, src/nodes/identity_matcher_node.hpp Per-track Bayesian accumulation in log-odds, with correlated-observat…
AR-026 In Progress T1, T4 SR-001 untagged - All similarity computed as GEMM, including annex and deferred pass
AR-027 Planned T4 SR-001 untagged - Throughput acceptable for arbitrary gallery size
AR-028 Planned T2 SR-002 untagged - Embedding input quality assessed and carried — every face scored …
AR-029 Planned T1 SR-002 untagged - Sharpness measure on the aligned crop (scale-normalised, so it ca…
AR-030 Planned T1 SR-002 untagged - Visibility measure from the AR-001 5-point landmarks — extreme pose o…
DP-001 Done T1, manual PR-004 covered src/main.cpp One analysis core; modes are front-ends and must not fork pipeline lo…
DP-002 Done T1, manual PR-004 covered src/main.cpp Batch CLI over one title
DP-003 Planned T1, manual PR-004 untagged - On-demand resident service with bounded, observable queue
DP-004 Planned T1, manual PR-004 untagged - Opportunistic/idle mode: external trigger, hard stop, implicit re-que…
DP-005 Planned T1, manual PR-004 untagged - Native installer, no Docker; Fedora + Arch
DP-006 Planned T1, manual PR-003 untagged - Background incremental gallery refresh on a timer
DP-007 Planned T1, manual PR-004 untagged - CI builder image, CPU-only, pinned by tag in the Gitea container regi…
DP-008 Planned T1, manual PR-004 untagged - Builder images + release jobs per backend (cpu / cuda / rocm); ship b…
IR-001 Done T1 SR-003 covered src/nodes/result_sink_node.hpp Emit the JRay truth format as sibling .jray.json
IR-002 Done — `schema_… T1 SR-003 covered src/config.hpp, src/main.cpp, src/nodes/result_sink_node.hpp Windows carry belief + route; extraction.* carries extinction_sec…
IR-003 In Progress — s… T1 SR-003 covered src/main.cpp Output written after the deferred pass, not at EOF
IR-004 Done — `src/aud… T1 SR-003 covered src/audio_signature.cpp, src/audio_signature.hpp, tests/test_audio_signature.cpp Compute the audio signature exactly per server spec §3
IR-005 Done — `tests/f… T1 SR-003 covered src/audio_signature.cpp, src/audio_signature.hpp, tests/test_audio_signature.cpp Golden-vector fixture shared with the plugin repo to prove bit-exactn…
IR-006 Done T1, manual SR-001 covered scripts/run_from_jellyfin.py Jellyfin round-trip: pull pending queue, push complete results only
IR-007 Done T1 SR-003 covered src/audio_signature.cpp, src/audio_signature.hpp, tests/test_audio_signature.cpp Media < 120 s: emit no signature, apply no sync offset — identical ru…
IR-008 Done T1 SR-003 covered src/audio_signature.cpp, src/audio_signature.hpp, tests/test_audio_signature.cpp Emit and honour the signature's own v1: version prefix
GR-001 Done T1, T3 SR-001, SR-005 covered scripts/make_jellyfin_gallery.py Build gallery from Jellyfin library cast, TMDB profile fallback
GR-002 Done T1, T3 PR-003 covered scripts/make_jellyfin_gallery.py Incremental --merge refresh without re-embedding known actors
GR-003 Planned T1, T3 SR-001 untagged - Report coverage: zero-image actors, under-referenced actors, dedup, c…
GR-004 Done — basename… T1, T3 SR-001 covered scripts/filter_gallery.py, scripts/make_gallery.py, scripts/make_jellyfin_gallery.py, scripts/movienet_eval.py, scripts/optimizer/fetch_missing_actors.py, scripts/optimizer/optimize.py, scripts/optimizer/reembed_gallery.py, scripts/optimizer/replay.py, scripts/sae_embed_loader.py, scripts/sae_gallery.py, scripts/sae_stamp.py, scripts/stamp_gallery.py, src/config.hpp, src/gallery/embedder_stamp.cpp, src/gallery/embedder_stamp.hpp, src/gallery/gallery_builder.cpp, src/gallery/gallery_store.cpp, src/kpn_bindings.cpp, src/main.cpp, src/nodes/embedding_dump_node.hpp, src/scene_preview.cpp, src/types.hpp, tests/test_gallery_store.cpp Stamp embedder identity into the gallery; hard startup error on m…
GR-005 Done T1, T3 SR-005 untagged - Gallery data never leaves the instance
GR-006 Planned T1 SR-005 untagged - Provenance tiers: baked / harvested / confirmed, distinguishable per …
GR-007 Planned T1 SR-005 untagged - Persist harvested embeddings flagged and reviewable, never silent…
GR-008 Planned T1 SR-005 untagged - Flag distributional outliers among an actor's references (poisoning g…
GR-009 TBD T1 §4 untagged - Human-confirmed associations persist and improve future extractions
VR-001 Done out-of-ci PR-002 tagged, unexecuted src/nodes/embedding_dump_node.hpp, tests/test_replay_fixtures.cpp HDF5 post-inference dump at the embedded-frame boundary
VR-002 Done — replay d… out-of-ci PR-002 tagged, unexecuted scripts/optimizer/replay.py, tests/test_replay_fixtures.cpp Replay drives the real KPN nodes, not a reimplementation
VR-003 Done out-of-ci PR-002 tagged, unexecuted scripts/optimizer/second_score.py Scoring: micro-F1 against X-Ray, precision/recall logged at every eva…
VR-004 Done out-of-ci PR-002 untagged - Reproducible validation corpus with ground truth
VR-005 Done — knee at … out-of-ci PR-002 untagged - Minimum face size study — TPI/FPI vs probe size, gallery held at nati…
VR-006 Planned out-of-ci PR-002 untagged - Re-tune scene_threshold once native-rate decode lands
VR-007 Planned out-of-ci PR-002 untagged - Expansion band, clustering threshold, and deferred-pass ablation
VR-008 Planned out-of-ci PR-002 untagged - Gallery scaling benchmark — throughput vs gallery size
VR-009 Planned T1, out-of-ci PR-002 untagged - Verify accumulated posteriors are calibrated against held-out tracks
VR-010 Planned out-of-ci PR-002 untagged - Dump provenance attributes — embedder model, detector settings, `dens…
VR-011 Planned out-of-ci PR-002 untagged - Rewrite the replay harness for the post-AR-012 output contract
VR-012 Planned T4, out-of-ci PR-002 untagged - Quality-knee study — TPI/FPI vs sharpness and vs pose, as VR-005 did …

Detailed mapping

AR-001

Locations: 1

AR-003

Locations: 3

AR-004

Locations: 3

AR-005

Locations: 1

AR-007

Locations: 3

AR-008

Locations: 3

AR-012

Locations: 9

AR-013

Locations: 3

AR-014

Locations: 2

AR-015

Locations: 2

AR-016

Locations: 4

AR-017

Locations: 3

AR-023

Locations: 3

AR-024

Locations: 6

AR-025

Locations: 3

DP-001

Locations: 1

DP-002

Locations: 1

GR-001

Locations: 1

GR-002

Locations: 1

GR-004

Locations: 44

IR-001

Locations: 1

IR-002

Locations: 5

IR-003

Locations: 1

IR-004

Locations: 16

IR-005

Locations: 5

IR-006

Locations: 1

IR-007

Locations: 8

IR-008

Locations: 7

IT-001

Locations: 1

PR-002

Locations: 3

PR-004

Locations: 1

SR-001

Locations: 46

SR-002

Locations: 20

SR-003

Locations: 6

SR-005

Locations: 1

UT-001

Locations: 1

UT-101

Locations: 5

UT-102

Locations: 5

UT-103

Locations: 2

UT-104

Locations: 5

VR-001

Locations: 2

VR-002

Locations: 2

VR-003

Locations: 1

Tag diagnostics

Malformed tags:

  • scripts/filter_gallery.py:80 — {'ignored': ['— a filtered gallery holds the SAME vectors as its']}
  • scripts/make_gallery.py:181 — {'ignored': ['— stamp with the model actually loaded', 'resolved']}
  • scripts/make_jellyfin_gallery.py:456 — {'ignored': ["— --merge keeps the existing actors' vectors and"]}
  • scripts/movienet_eval.py:65 — {'ignored': ['— match() below is a bare dot product against the']}
  • scripts/optimizer/fetch_missing_actors.py:109 — {'ignored': ['— the legacy JSON gallery carries the same stamp as']}
  • scripts/optimizer/fetch_missing_actors.py:123 — {'ignored': ['— merging two galleries from different models makes']}
  • scripts/optimizer/optimize.py:202 — {'ignored': ['— every (dump', 'gallery) pair is checked ONCE here']}
  • scripts/optimizer/reembed_gallery.py:62 — {'ignored': ['— this script exists to produce a gallery in a']}
  • scripts/optimizer/replay.py:113 — {'ignored': ['— checked here', 'before any network is built', 'so a']}
  • scripts/optimizer/replay.py:252 — {'ignored': ['— promote an unprovable gallery/dump binding from a']}
  • scripts/sae_embed_loader.py:22 — {'ignored': ['— single source of truth for "which model is this"']}
  • scripts/sae_gallery.py:171 — {'ignored': ['— omitted entirely when unknown', 'so "unstamped"']}
  • scripts/sae_gallery.py:199 — {'ignored': ['— carried through so a derived gallery (filter']}

Groups mixing requirement types (pipe separates types):

  • src/main.cpp:216 — {'group': ['AR-012', 'AR-016', 'IR-002', 'IR-003']}
  • src/nodes/result_sink_node.hpp:49 — {'group': ['AR-012', 'AR-017', 'IR-002']}
  • src/nodes/result_sink_node.hpp:161 — {'group': ['AR-012', 'IR-002']}
  • tests/test_replay_fixtures.cpp:3 — {'group': ['AR-012', 'AR-013', 'AR-004', 'VR-001', 'VR-002']}
Reference in New Issue View Git Blame Copy Permalink