feat(replay): the whole replay chain is C++, including the sink

The sae_kpn module has not compiled since the AR-007/AR-008 tracker redesign,
and was switched off at the build rather than patched because the fix is a
restructuring. Two failures, one cause.

It did not compile: `add_face_tracker` built FaceTrackerFunc from a Config
alone, and the tracker has required a TrackRegistry and a calibration since
association moved into probability space.

And presence was rebuilt in Python. `replay.py::build_minimal` merged
per-frame detections into windows by annealing gaps, which is what the
pipeline did before AR-012. The sink builds a window from a TrackRegistry
claim instead — the extent of a track an actor owned, starting when they
appeared rather than when recognition first succeeded. Those answer different
questions, so every sweep was tuning against a contract the shipped code had
stopped honouring.

Both follow from the seam being a factory per node. The chain has a
construction order — the matcher fits the calibration, the registry needs a
discounter built from it, the tracker needs both, and the sink needs the
registry's claims — and independent factories cannot express it, so the
tracker kept being built against a signature that no longer existed. One
`add_pipeline` mirrors main.cpp exactly and is now the only way to build the
chain, so the ordering cannot be got wrong again from Python. DP-001 is the
requirement behind it: a replay harness is a front-end, and its job is to
supply frames and read the result, not to re-derive presence.

Lifetimes needed a home. ResultSinkFunc holds `const Config&` and
`std::atomic<bool>&`, which under main() are locals in a frame outliving the
pipeline; there is no such frame when the network is built and torn down from
Python. ReplaySession owns both for the network's lifetime, keyed by network
and released explicitly — a sweep builds one network per replay and the sink
retains every annotation, so holding them forever would grow with films x
configs. Getting this wrong presented as an empty output_path: the sink
announced `[result_sink] writing ` and wrote nothing.

test_sae_kpn.py is ported rather than left behind. It called all three removed
factories and asserted on SceneAnnotations read back per frame; neither half
survives, so it now waits on pipeline_done and asserts on the file the sink
writes. Verified against gallery_lvface.h5: three frames through the real
chain, timestamps 0/1/2, truth file written. EOF is a control token the sink
flushes on and does not record, so three inputs give three frames, never four.

SAE_BUILD_KPN_BINDINGS goes back to ON.

TRACES: VR-011, VR-002 | DP-001 | PR-002
This commit is contained in:
2026-08-05 19:40:25 +02:00
parent 1141172b04
commit 48332d2041
6 changed files with 414 additions and 229 deletions
+7 -22
View File
@@ -326,32 +326,17 @@ target_link_libraries(sae_embed PRIVATE sae_gallery)
# network (KPN_BUILD_PYTHON is enabled per-TU inside the .cpp). Powers the
# threshold-sweep optimizer in scripts/optimizer/.
#
# OFF by default, and this is a statement of fact rather than a preference: the
# module HAS NOT COMPILED since the AR-007/AR-008 tracker redesign. FaceTrackerFunc
# now requires a TrackRegistry and a calibration at construction, and the binding
# still builds it from a Config alone. The .so in a stale build/ directory
# predates that change.
#
# Fixing it is VR-011's job, not a patch: the tracker needs the calibration, the
# calibration comes from the matcher, and the matcher is added to the network
# afterwards -- so the seam has to be restructured, exactly as main.cpp already
# is (matcher first, then registry, then tracker). Presence claims do not cross
# the seam at all today, which is the other half of the same rewrite.
#
# Recorded as a switch rather than left as a build error so that `cmake --build`
# succeeds and the breakage is attributed instead of rediscovered. Turning it on
# reproduces the failure immediately, which is the point.
#
# TRACES: VR-011 | PR-002
option(SAE_BUILD_KPN_BINDINGS
"Build the sae_kpn Python module (BROKEN pending VR-011)" OFF)
# ON again. It was OFF for one commit because it had not compiled since the
# AR-007/AR-008 tracker redesign -- the binding built FaceTrackerFunc from a
# Config alone, and the tracker had required a registry and a calibration since.
# VR-011 replaced the three per-node factories with one `add_pipeline` that
# builds the chain in main.cpp's order, which is the only order that satisfies
# those dependencies, so the failure mode cannot recur from Python.
option(SAE_BUILD_KPN_BINDINGS "Build the sae_kpn Python module" ON)
if(SAE_BUILD_KPN_BINDINGS)
nanobind_add_module(sae_kpn src/kpn_bindings.cpp)
target_link_libraries(sae_kpn PRIVATE sae_gallery)
else()
message(STATUS
"sae_kpn: SKIPPED (SAE_BUILD_KPN_BINDINGS=OFF). The Python replay "
"bindings do not compile against the post-AR-012 tracker; see VR-011.")
endif()
# ── sae_audio — Python module: the v1 audio signature (IR-004) ────────────────