dtourolle/scene-actor-extraction
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
50649c1f87afa20e1843406fb058e77e3ca1bdcc
scene-actor-extraction/docs/traceability.md
T
dtourolleandClaude Opus 5 50649c1f87 feat: expansion promotion gated on all three discontinuity signals 
AR-019 — promotion may only borrow same-identity evidence from a span where
identity is certain, so every discontinuity signal now clears the buffers rather
than just the histogram cut.

is_scene_boundary was already named in the gate but never set by anything, so
that half of it was dead until AR-010 gave it a producer. It now does what the
spec always said. The third signal, an identity contradiction, needs no code
here: AR-015 closes a track whose belief swapped, so it can no longer promote.

Ownership now comes from the registry rather than a second tally. TrackGallery
was computing its own plurality vote over accepted frames, which meant two
different answers to "who is this track" could coexist in one run — and the
expansion one ignored the Bayesian accumulation entirely, weighting thirty
near-identical looks the same as thirty distinct ones. The local tally survives
only as a fallback for callers with no registry attached, which is the unit
tests and the replay harness.

Suite: 92 cases, 6133 assertions.

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

TRACES: AR-019, AR-010, AR-015 | SR-005
2026-07-31 15:11:56 +02:00

47 KiB
Raw Blame History

Requirements traceability matrix

Generated: 2026-07-31T13:11:03+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 108
TRACES tags found 110
EXCEPTION tags found 0
Requirements defined 67
Requirements covered 32
Coverage 47.8% (32/67)
Coverage of CI-executable scope 58.2% (32/55)
Tagged but unexecuted in CI 4
Orphan tags 0

By type

Type Covered Tagged but unexecuted Defined
AR 19 1 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 yes 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: AR-027, 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 — `umeyama… T1, T3 SR-002 covered src/face_utils.hpp, tests/test_face_utils.cpp Align to 112×112 via ArcFace 5-point similarity transform, fitted by …
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 Done — decode b… T2 SR-002 covered src/main.cpp, src/nodes/scene_boundary_annotator_node.hpp, src/nodes/scene_detector_node.hpp, src/scene_boundaries.hpp 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 Done — banded a… T1, T2 SR-005 covered src/config.hpp, src/gallery/track_gallery.hpp, src/nodes/identity_matcher_node.hpp 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/gallery/track_gallery.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 covered src/backends/gemm_backend.cpp All similarity computed as GEMM, including annex and deferred pass
AR-027 Planned T4 SR-001 tagged, unexecuted src/backends/gemm_backend.cpp 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 In Progress — m… T1 SR-002 covered src/face_utils.hpp, tests/test_face_utils.cpp 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: 4

AR-005

Locations: 2

AR-007

Locations: 3

AR-008

Locations: 3

AR-010

Locations: 9

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-018

Locations: 3

AR-023

Locations: 3

AR-024

Locations: 10

AR-025

Locations: 3

AR-026

Locations: 1

AR-027

Locations: 1

AR-030

Locations: 2

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: 47

SR-002

Locations: 30

SR-003

Locations: 6

SR-005

Locations: 5

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:230 — {'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