refactor(traceability): parameterise the extractor for all three components

The tool is moving into the jray-project submodule to be shared by scene-actor-extraction (C++/Python), jRay (C#) and JRay-public-server (Rust). Two constants blocked that: LOCAL_TYPES and SOURCE_SUFFIXES were hardcoded to this repo, so either sibling parsed zero requirements and scanned zero files. Both, plus the register path, scan roots, system-spec path, exclude list and CI-executable tier set, are now configuration. One implementation, parameterised. A second copy for "the other language" is how two implementations start drifting apart, so there is exactly one - the same code path now produces: scene-actor-extraction AR/DP/IR/GR/VR 59 defined 0 tagged 0.0% jRay JR 46 defined 24 covered 52.2% JRay-public-server UR/DR 32 defined 23 covered 71.9% Configuration is traceability.toml at the component repo root, CLI flags, or both (flags win). Its directory defines the repo root, so the gate works from any subdirectory. `--print-example-config` emits the annotated schema. The JSON report echoes the settings it ran with, since a shared tool's output is otherwise ambiguous about which repo it describes. The refusal behaviour is kept and sharpened, because parameterising is exactly what makes it easy to point a repo at the wrong prefixes or the wrong suffixes. Zero requirements parsed or zero files scanned is still a hard failure, and the message now names the setting that is wrong rather than printing a plausible 0%. Config errors exit 2, not 1: a broken config is not a coverage failure, and conflating them makes CI logs lie about why the job went red. Also fixed while adapting to the sibling registers, which are read but not modified here: * escaped `\|` inside a markdown cell no longer shifts every later column (the server's register contains `small-\|M\|`); * a tag above an attribute-decorated declaration attributes to the declaration, not to `[HttpGet(...)]` or `#[derive(...)]` - the gap jRay's register calls out; * Rust and C# declaration patterns for context extraction; * the missing-tier warning is suppressed for a register that assigns no tiers at all, rather than listing every requirement in it. The workflow is now component-agnostic too: the changed-file check reads its extension list out of the report the gate just wrote, so the definition of "source file" lives in one place. 79 tests, still fixture-based, now including the cross-repo cases: the same parser over JR and UR/DR registers, the same scanner over Rust and C#, and both misconfigurations failing loudly.
build: requirement traceability extractor, gate, and CI workflow
2026-07-30 18:35:56 +02:00 · 2026-07-30 18:16:58 +02:00
126 changed files with 3957 additions and 18023 deletions
@@ -53,7 +53,7 @@ jobs:
      # before it does. JellyTau's gate was believed for months while it was
      # dividing by frozen literals; untested gate logic is how that happens.
      - name: Test the extractor
-        run: python3 scripts/vendor/jray-project/scripts/traceability/test_extract_traces.py
+        run: python3 scripts/traceability/test_extract_traces.py
      # Threshold policy and every other repo-specific setting live in
      # traceability.toml, not here, so local runs and CI runs cannot disagree
@@ -63,16 +63,7 @@ jobs:
      # A misconfigured run (zero requirements parsed, zero files scanned) is a
      # hard failure rather than a plausible-looking 0%.
      - name: Traceability gate
-        run: sh scripts/vendor/jray-project/scripts/traceability/traceability-gate.sh
+        run: sh scripts/traceability/traceability-gate.sh
      # AR-024's register row names its verification tier as "Static check --
      # no bare cosine outside a tagged EXCEPTION". This is that check, and it
      # belongs here rather than in unit-tests.yml because it is static
      # analysis of source text, like everything else in this job, and needs
      # no toolchain. It blocks: an untagged bare cosine is a defect by the
      # invariant's own wording, not a warning.
      - name: AR-024 — no bare cosine outside a recorded exception
        run: python3 scripts/ci/check_raw_cosine.py
      - name: Check modified files for traces
        if: github.event_name == 'pull_request'
@@ -1,140 +0,0 @@
 name: Unit tests
 # TRACES: DP-007 | PR-004
 #
 # The tier the verification strategy is built on, finally executing.
 #
 # docs/requirements.md describes a four-tier plan in which T1 (functor unit)
 # and T2 (replay) are "the only tiers that can exist in CI at all", and the
 # traceability gate reports a CI-scope coverage fraction over exactly those
 # tiers. Until this workflow existed, nothing ran them: "covered" meant a
 # TRACES tag was present in a file, not that any test had been executed. That
 # is the same failure mode as counting a test that cannot run, one level up,
 # and the gate cannot detect it because a tag is all it can see.
 #
 # The runner is an Intel N100 with no discrete GPU. Nothing here calls a model:
 # T1 constructs node functors directly, and T2 replays a precomputed HDF5 dump.
 # T3 (ORT CPU smoke) and T4 (GPU) are deliberately absent -- the embedder is
 # ~930 ms/frame on this hardware, so a 77 s clip at 5 fps would be six minutes
 # of inference alone.
 on:
  push:
    branches:
      - main
      - master
      - develop
  pull_request:
    branches:
      - main
      - master
      - develop
 jobs:
  unit-tests:
    runs-on: linux/amd64
    name: Build and run the GPU-free suite
    # Pinned by tag, never `latest`, so rebuilding the image cannot silently
    # change what a previous green build meant. Bumping the dependency set means
    # bumping the tag in scripts/ci/build_builder_image.sh AND here, in one
    # commit -- see that script's header.
    container:
      image: gitea.tourolle.paris/dtourolle/sae-builder-cpu:v1
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # KPN is a submodule and the pipeline does not build without it.
          #
          # NOTE: this checks out the commit this repo PINS, which is the whole
          # point and is also the first thing this job will disagree with a
          # developer about. A local KPN working copy that is ahead of
          # origin/master builds and passes here while CI builds something else
          # entirely; the AR-004 evidence in docs/requirements.md was gathered
          # that way. If this job fails on tests that pass locally, check
          # `git -C external/KPN log origin/master..HEAD` before suspecting the
          # tests.
          # LFS is deliberately NOT fetched: SAE_MODELS_DIR is baked into the
          # binary as a path string and nothing in T1/T2 opens a model file, so
          # pulling ~hundreds of MB of ONNX would cost the job everything and
          # buy it nothing.
          submodules: recursive
          lfs: false
      - name: Assert the builder image is the pinned one
        run: |
          set -e
          echo "builder=$SAE_BUILDER version=$SAE_BUILDER_VERSION"
          echo "ort=$SAE_ORT_VERSION opencv=$SAE_OPENCV_VERSION"
          # The image reports its own tag. A mismatch means the `container:`
          # line above and the image that actually landed disagree, which is
          # exactly the drift the pinning exists to prevent -- so it fails the
          # job rather than building against an unknown toolchain.
          [ "$SAE_BUILDER_VERSION" = "v1" ] || {
            echo "image reports version '$SAE_BUILDER_VERSION', workflow pins v1" >&2
            exit 1
          }
      - name: Fetch replay fixtures
        env:
          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
        # bash, not sh: the script declares #!/bin/bash and uses `set -o
        # pipefail` and arrays, which dash does not have.
        run: bash scripts/artifacts/pull_artifacts.sh replay-fixtures latest
      # pull_artifacts.sh warns and continues when a package version is missing,
      # which is right for a developer pulling one artifact of several and wrong
      # here. A T2 test whose fixture never arrived must not look like a pass:
      # the dumps are the entire input to the replay tier, and VR-002's claim is
      # that replay drives the real nodes over real data.
      - name: Verify the fixtures actually arrived
        run: |
          set -e
          missing=0
          for f in tests/fixtures/dumps/superhero.h5; do
            if [ -s "$f" ]; then
              echo "  ok: $f ($(wc -c < "$f") bytes)"
            else
              echo "  MISSING: $f" >&2
              missing=1
            fi
          done
          if [ "$missing" -ne 0 ]; then
            echo "" >&2
            echo "Replay fixtures are absent, so the T2 tier cannot run." >&2
            echo "They are not in git (tests/fixtures/dumps/.gitignore) -- they" >&2
            echo "live in the Gitea generic package registry and are pulled by" >&2
            echo "the step above, which needs GITEA_TOKEN to resolve 'latest'." >&2
            exit 1
          fi
      - name: Configure
        run: |
          set -e
          # SAE_GEMM_BACKEND defaults to ROCM and the auto-detect prefers a GPU
          # backend where it finds one; CPU is stated explicitly so this job
          # cannot start depending on what happens to be installed on the runner.
          # The CPU kernel is OpenBLAS in this image (tests/CMakeLists.txt fails
          # the configure if it is not), so the suite exercises the kernel the
          # CPU release actually ships.
          cmake -S . -B build \
            -DCMAKE_BUILD_TYPE=Release \
            -DSAE_BUILD_TESTS=ON \
            -DSAE_GEMM_BACKEND=CPU
      - name: Build the test suite
        run: cmake --build build --target sae_tests --parallel
      - name: Run the tests
        run: ctest --test-dir build --output-on-failure
      - name: Save test output
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: unit-test-results
          path: build/Testing/
          retention-days: 30
@@ -1,6 +1,5 @@
 # Build
 build/
 build-*/
 cmake-build-*/
 CMakeCache.txt
 CMakeFiles/
@@ -20,10 +19,6 @@ compile_commands.json
 # coverage). Regenerate with scripts/docs/run_holdout_all_models.py and
 # scripts/docs/gallery_coverage_per_film.py.
 !docs_data/*.json
 # Exception: test fixtures are inputs, not build output. The audio golden
 # vector (IR-005) is shared verbatim with the jRay plugin repo, so it has to be
 # tracked. Regenerate the media with tests/fixtures/audio/make_fixture.py.
 !tests/fixtures/**
 # Video files
 *.mp4
 *.mkv
@@ -2,6 +2,3 @@
 	path = external/KPN
 	url = https://gitea.tourolle.paris/dtourolle/KPN.git
 	branch = master
 [submodule "jray-project"]
 	path = scripts/vendor/jray-project
 	url = git@gitea.tourolle.paris:dtourolle/jray-project.git
@@ -55,13 +55,6 @@ set_property(CACHE SAE_GEMM_BACKEND       PROPERTY STRINGS ROCM CUDA CPU)
 # default so ROCm/CPU builds don't reference unavailable EPs.
 option(SAE_ORT_TRT_EP "ORT backend: enable TensorRT/CUDA execution providers" OFF)
 # AR-026/AR-027: the CPU GEMM path is backed by OpenBLAS, and its absence is a
 # configure error rather than a silent downgrade to the scalar loop. Declared at
 # top level because the unit-test target compiles the CPU kernel regardless of
 # which backend the main build selected, and both must make the same choice.
 option(SAE_ALLOW_SCALAR_GEMM
       "Permit the scalar-loop GEMM fallback when OpenBLAS is absent" OFF)
 # Back-compat: a legacy -DSAE_WITH_TRT=ON/OFF seeds the new vars (ON⇒TRT+CUDA,
 # OFF⇒ORT+ROCM) unless the user set them explicitly.
 if(DEFINED SAE_WITH_TRT)
@@ -159,37 +152,6 @@ if(SAE_GEMM_BACKEND STREQUAL "CPU")
    set_target_properties(gemm_backend PROPERTIES POSITION_INDEPENDENT_CODE ON)
    target_include_directories(gemm_backend PRIVATE src)
    target_compile_definitions(gemm_backend PRIVATE SAE_GEMM_CPU)
    # AR-026/AR-027: the CPU path is backed by OpenBLAS, and that is REQUIRED
    # rather than opportunistic. The CPU backend is what CI (no GPU) and the cpu
    # builder image actually run, so a silent fall back to the scalar loop means
    # AR-027 is measured — or worse, believed — on a path no release uses. A
    # missing dependency should stop the build and name itself, not degrade into
    # a slower answer nobody notices.
    #
    # The scalar loop survives as the correctness oracle the two backends are
    # diffed against; -DSAE_ALLOW_SCALAR_GEMM=ON is how you ask for it, which
    # keeps that an explicit, visible choice.
    find_package(PkgConfig QUIET)
    if(PkgConfig_FOUND)
        pkg_check_modules(OPENBLAS QUIET openblas)
    endif()
    if(OPENBLAS_FOUND)
        message(STATUS "GEMM backend: CPU + OpenBLAS ${OPENBLAS_VERSION}")
        target_compile_definitions(gemm_backend PRIVATE SAE_GEMM_CBLAS)
        target_include_directories(gemm_backend PRIVATE ${OPENBLAS_INCLUDE_DIRS})
        target_link_libraries(gemm_backend PRIVATE ${OPENBLAS_LINK_LIBRARIES})
    elseif(SAE_ALLOW_SCALAR_GEMM)
        message(WARNING "GEMM backend: CPU scalar fallback (SAE_ALLOW_SCALAR_GEMM=ON) — "
                        "correct, but slow on a large gallery. Do not measure AR-027 here.")
    else()
        message(FATAL_ERROR
            "OpenBLAS not found, and the CPU GEMM backend requires it (AR-026/AR-027).\n"
            "  Install it:  Fedora  dnf install openblas-devel\n"
            "               Arch    pacman -S openblas\n"
            "               Debian  apt install libopenblas-dev\n"
            "  Or build the scalar fallback deliberately: -DSAE_ALLOW_SCALAR_GEMM=ON")
    endif()
 elseif(SAE_GEMM_BACKEND STREQUAL "CUDA")
    find_library(CUBLAS_LIB cublas
        HINTS /opt/cuda/targets/x86_64-linux/lib /opt/cuda/lib64
@@ -234,31 +196,23 @@ endif()
 # FFmpeg (hwaccel video decode: CUDA/VAAPI, runtime-detected + swscale colour
 # conversion). Hwaccel support is built into libavcodec/libavutil; no extra
 # libraries are needed here.
 # libswresample is the audio side of the same dependency — downmix + resample
 # for the audio signature (IR-004, src/audio_signature.cpp). Not a new project
 # dependency: it ships with the libav* set already required above.
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(AVFORMAT REQUIRED libavformat)
 pkg_check_modules(AVCODEC  REQUIRED libavcodec)
 pkg_check_modules(AVUTIL   REQUIRED libavutil)
 pkg_check_modules(SWSCALE  REQUIRED libswscale)
 pkg_check_modules(SWRESAMPLE REQUIRED libswresample)
 add_library(ffmpeg_libs INTERFACE)
 target_compile_options(ffmpeg_libs INTERFACE
    ${AVFORMAT_CFLAGS_OTHER} ${AVCODEC_CFLAGS_OTHER}
-    ${AVUTIL_CFLAGS_OTHER}   ${SWSCALE_CFLAGS_OTHER}
+    ${AVUTIL_CFLAGS_OTHER}   ${SWSCALE_CFLAGS_OTHER})
    ${SWRESAMPLE_CFLAGS_OTHER})
 target_include_directories(ffmpeg_libs INTERFACE
    ${AVFORMAT_INCLUDE_DIRS} ${AVCODEC_INCLUDE_DIRS}
-    ${AVUTIL_INCLUDE_DIRS}   ${SWSCALE_INCLUDE_DIRS}
+    ${AVUTIL_INCLUDE_DIRS}   ${SWSCALE_INCLUDE_DIRS})
    ${SWRESAMPLE_INCLUDE_DIRS})
 target_link_libraries(ffmpeg_libs INTERFACE
    ${AVFORMAT_LIBRARIES} ${AVCODEC_LIBRARIES}
-    ${AVUTIL_LIBRARIES}   ${SWSCALE_LIBRARIES}
+    ${AVUTIL_LIBRARIES}   ${SWSCALE_LIBRARIES})
-    ${SWRESAMPLE_LIBRARIES})
+message(STATUS "FFmpeg: avformat=${AVFORMAT_VERSION} avcodec=${AVCODEC_VERSION}")
 message(STATUS "FFmpeg: avformat=${AVFORMAT_VERSION} avcodec=${AVCODEC_VERSION} "
               "swresample=${SWRESAMPLE_VERSION}")
 # nlohmann/json (gallery + output serialisation)
 include(FetchContent)
@@ -295,8 +249,6 @@ find_package(HDF5 REQUIRED COMPONENTS CXX)
 add_library(sae_gallery STATIC
    src/gallery/gallery_store.cpp
    src/gallery/gallery_builder.cpp
    src/audio_signature.cpp        # IR-004 — content-derived audio signature
    src/gallery/embedder_stamp.cpp # GR-004 — gallery/embedder binding
 )
 set_target_properties(sae_gallery PROPERTIES POSITION_INDEPENDENT_CODE ON)
 target_include_directories(sae_gallery PUBLIC src ${HDF5_INCLUDE_DIRS})
@@ -322,32 +274,11 @@ nanobind_add_module(sae_embed src/python_bindings.cpp)
 target_link_libraries(sae_embed PRIVATE sae_gallery)
 # ── sae_kpn — Python module: run the real downstream nodes over dumped embeddings ─
-# Assembles face_tracker/identity_matcher/frame_annotation in a Python-driven KPN
+# Assembles face_tracker/identity_matcher/scene_tracker in a Python-driven KPN
 # network (KPN_BUILD_PYTHON is enabled per-TU inside the .cpp). Powers the
 # threshold-sweep optimizer in scripts/optimizer/.
-#
+nanobind_add_module(sae_kpn src/kpn_bindings.cpp)
-# TRACES: VR-011 | PR-002
+target_link_libraries(sae_kpn PRIVATE sae_gallery)
 # 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)
 endif()
 # ── sae_audio — Python module: the v1 audio signature (IR-004) ────────────────
 # Compiles audio_signature.cpp directly and links only FFmpeg, rather than
 # linking sae_gallery: the signature needs no model, no OpenCV and no HDF5, and
 # a module that dragged all three in would make `import sae_audio` depend on a
 # GPU-capable build of a repo whose audio path is pure CPU DSP. tests/ compiles
 # the same source the same way, for the same reason.
 nanobind_add_module(sae_audio src/audio_bindings.cpp src/audio_signature.cpp)
 target_include_directories(sae_audio PRIVATE src)
 target_link_libraries(sae_audio PRIVATE ffmpeg_libs)
 # HDF5 already found above (before sae_gallery); vars HDF5_CXX_LIBRARIES / _INCLUDE_DIRS
 # are reused by scene_analyze / dump_embeddings below.
@@ -1,342 +0,0 @@
 # sae-builder-cpu — the CI build image
 #
 # TRACES: DP-007 | PR-004
 #
 # Build/push:  scripts/ci/build_builder_image.sh --push
 # Consumed by: .gitea/workflows/unit-tests.yml  (pinned by tag, never :latest)
 # Docs:        docs/ci-image.md
 #
 # This is the CPU corner of the DP-008 builder matrix and the DP-007 CI image at
 # the same time — one artifact, two uses. The CUDA and ROCm siblings differ only
 # in the accelerator stack layered on top of this dependency set.
 #
 # CI runs on an Intel N100 with no discrete GPU. Everything here is chosen so
 # that `-DSAE_INFERENCE_BACKEND=ORT -DSAE_GEMM_BACKEND=CPU -DSAE_BUILD_TESTS=ON`
 # configures, builds and runs without a GPU, without a model, and without
 # reaching GitHub.
 # ─── Base image ──────────────────────────────────────────────────────────────
 #
 # Chosen for the OLDEST glibc to be supported, not for recency. A binary built
 # in a container runs against the *host's* glibc; glibc is backward compatible
 # but not forward, so the build base sets the floor for every machine DP-008's
 # binaries can ever run on. Building on a newer base than the oldest supported
 # host produces the classic `GLIBC_2.xx not found` failure at load time.
 #
 # Debian 12 "bookworm" = glibc 2.36 (Aug 2022). What that floor covers:
 #
 #   Distro                       glibc   Covered?
 #   Arch / CachyOS (rolling)     2.41+   yes
 #   Fedora 37 and later          2.36+   yes   ← DP-005's targets are Fedora+Arch
 #   Debian 12 / 13               2.36+   yes
 #   Ubuntu 24.04 LTS             2.39    yes
 #   Ubuntu 22.04 LTS             2.35    NO
 #   RHEL / Rocky / Alma 9        2.34    NO
 #   Debian 11                    2.31    NO
 #
 # The three misses are accepted deliberately: DP-005 puts Debian/Ubuntu out of
 # installer scope and names Fedora + Arch as the supported distros, and every
 # supported Fedora is 2.36 or newer. Going lower costs the toolchain rather than
 # buying reach — Debian 11 ships GCC 10 (incomplete C++20) and Python 3.9, which
 # has no `tomllib` and therefore cannot read the traceability gate's
 # traceability.toml.
 #
 # Escape hatch, recorded now so it is not rediscovered under pressure: if the
 # floor must drop to glibc 2.28 (RHEL 8 / manylinux_2_28 — the same baseline the
 # ONNX Runtime and PyTorch wheels target), the move is a Rocky 8 base plus
 # gcc-toolset-13, and OpenCV/FFmpeg/HDF5 all leave apt for source or
 # EPEL/RPM Fusion. That is a different image, not a flag on this one.
 #
 # Not a glibc problem but worth stating: the binaries this image produces also
 # link OpenCV, FFmpeg and HDF5 shared objects by soname. Making a *portable*
 # release binary (DP-008) is a separate question from the glibc floor, and is
 # answered by static linking or bundling, not by the base image.
 FROM debian:12-slim
 # Pins. Every version this image installs from source is an ARG so a rebuild is
 # a one-line diff and `docker history` records what a given tag actually holds.
 #
 # ORT 1.28.0 and OpenCV 5.0.0 match the developer machine, so CI and local
 # builds exercise the same libraries rather than merely similar ones.
 # Catch2 / nlohmann_json / nanobind match the FetchContent pins in
 # CMakeLists.txt:248 and tests/CMakeLists.txt:12 exactly — a vendored copy at a
 # different version would be a silent divergence, not a convenience.
 ARG ORT_VERSION=1.28.0
 ARG OPENCV_VERSION=5.0.0
 ARG CATCH2_VERSION=v3.5.3
 ARG NLOHMANN_JSON_VERSION=v3.11.3
 ARG NANOBIND_VERSION=v2.4.0
 # Stamped so a build can prove which image it ran in, and so a green tick can be
 # traced back to a specific dependency set. See the "Confirm the builder image"
 # step in .gitea/workflows/unit-tests.yml.
 ARG IMAGE_TAG=dev
 ENV SAE_BUILDER=cpu \
    SAE_BUILDER_VERSION=${IMAGE_TAG} \
    SAE_ORT_VERSION=${ORT_VERSION} \
    SAE_OPENCV_VERSION=${OPENCV_VERSION} \
    DEBIAN_FRONTEND=noninteractive
 # ─── System dependencies ─────────────────────────────────────────────────────
 #
 # One layer, ordered by why it is here rather than alphabetically.
 RUN apt-get update && apt-get install -y --no-install-recommends \
    # Toolchain. bookworm's default gcc is 12.2 — enough for the C++20 the
    # project sets unconditionally (CMakeLists.txt:4). cmake is 3.25, above the
    # 3.21 minimum. Ninja because the N100 has four cores and every second of
    # build scheduling shows.
    build-essential \
    cmake \
    ninja-build \
    pkg-config \
    git \
    ca-certificates \
    curl \
    # Gitea's act_runner executes JS actions (actions/checkout, upload-artifact)
    # with the `node` found *inside* the container. Without this the job cannot
    # even check the repository out. Same reason as the kpnpp-builder image.
    nodejs \
    # HDF5 with the C++ API: galleries are HDF5-native and it is also the VR-001
    # dump format. find_package(HDF5 COMPONENTS CXX) at CMakeLists.txt:273.
    libhdf5-dev \
    # FFmpeg decode. swresample is on this list deliberately: the audio
    # signature (IR-004) downmixes to mono and resamples to 11025 Hz, and
    # tests/test_audio_signature.cpp decodes the golden FLAC fixture, so the
    # test build needs it as much as the main build does.
    libavformat-dev \
    libavcodec-dev \
    libavutil-dev \
    libswscale-dev \
    libswresample-dev \
    # OpenBLAS — required here, not optional. CI has no GPU, so SAE_GEMM_BACKEND
    # =CPU is the only path it ever exercises, and without OpenBLAS the CPU GEMM
    # falls back to a scalar loop that does not scale against a library-sized
    # gallery (AR-027). The build only *warns* when it is missing so a developer
    # without it still gets a working tree; the image must never be that case.
    # Both the main build (CMakeLists.txt:162) and the test target
    # (tests/CMakeLists.txt:42) discover it through pkg-config `openblas`.
    libopenblas-dev \
    # Python: the build itself needs the interpreter and headers
    # (find_package(Python COMPONENTS Interpreter Development.Module) at
    # CMakeLists.txt:254, for the nanobind modules). numpy/h5py/scipy are for
    # the Python-side tooling — fixture generation, replay, validation scripts.
    # From apt rather than pip: bookworm marks the environment externally
    # managed (PEP 668), and apt's h5py is already linked against the same
    # libhdf5 installed above. bookworm's python3 is 3.11, which has tomllib —
    # the traceability gate needs it to read traceability.toml.
    python3 \
    python3-dev \
    python3-numpy \
    python3-h5py \
    python3-scipy \
    # Image codecs for the OpenCV build below. Without these OpenCV silently
    # builds an imgcodecs that cannot read a JPEG, which fails at run time in a
    # gallery build rather than at compile time here.
    libjpeg62-turbo-dev \
    libpng-dev \
    libtiff-dev \
    libwebp-dev \
    libopenjp2-7-dev \
    zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*
 # Fail the image build, not the CI run, if OpenBLAS or swresample are not
 # discoverable the way CMakeLists.txt discovers them. An image that ships
 # libopenblas but no openblas.pc would compile the scalar fallback in silence.
 RUN set -eux; \
    pkg-config --exists openblas; \
    echo "openblas    $(pkg-config --modversion openblas)"; \
    pkg-config --exists libswresample; \
    echo "swresample  $(pkg-config --modversion libswresample)"
 # ─── ONNX Runtime, CPU provider only ─────────────────────────────────────────
 #
 # The official prebuilt linux-x64 tarball is the CPU build: no CUDA, no
 # TensorRT, no ROCm execution providers. That is the whole requirement here —
 # excluding the GPU providers is not a size optimisation, it is the point.
 #
 # Verified against the 1.28.0 tarball: the shared object's highest versioned
 # symbol requirement is GLIBC_2.27 / GLIBCXX_3.4.21, well under this base's
 # 2.36, so ORT does not raise the floor set above.
 #
 # Installed to /usr/local/{lib,include/onnxruntime} because CMakeLists.txt
 # includes <onnxruntime/onnxruntime_cxx_api.h> and needs the *parent* of that
 # directory on the include path (CMakeLists.txt:108-113).
 #
 # CI never calls a model — the embedder measures ~930 ms/frame on this CPU
 # provider — so ORT is present to satisfy the link, not to run inference.
 RUN set -eux; \
    curl -fsSL -o /tmp/ort.tgz \
      "https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-linux-x64-${ORT_VERSION}.tgz"; \
    mkdir -p /tmp/ort; \
    tar -xzf /tmp/ort.tgz -C /tmp/ort --strip-components=1; \
    cp -a /tmp/ort/lib/libonnxruntime.so* /usr/local/lib/; \
    mkdir -p /usr/local/include/onnxruntime; \
    cp -a /tmp/ort/include/. /usr/local/include/onnxruntime/; \
    ldconfig; \
    rm -rf /tmp/ort /tmp/ort.tgz; \
    test -f /usr/local/include/onnxruntime/onnxruntime_cxx_api.h
 # ─── OpenCV 5, from source ───────────────────────────────────────────────────
 #
 # This is the reason the image is prebuilt at all. CMakeLists.txt:25 probes for
 # OpenCV 5 first and falls back to 4; the branch targets 5, which no Debian
 # release ships (bookworm has 4.6), and building it inside every CI run would
 # dominate the run on an N100.
 #
 # BUILD_LIST is exactly the seven components find_package asks for
 # (CMakeLists.txt:25-29) — OpenCV resolves their internal dependencies itself.
 # Everything else is off: tests, samples, Java/Python bindings, and the apps.
 #
 # No GUI backend. highgui still builds (find_package REQUIREs the component) but
 # with a stub — CI never calls imshow, and pulling GTK/Qt into a headless build
 # image buys nothing. scene_preview is a developer tool, not a CI target.
 #
 # CUDA/cuDNN explicitly off: DP-007 excludes the GPU stack outright.
 #
 # The source tree and build tree are removed in the same layer, so the ~3 GB of
 # intermediates cost nothing in the published image.
 RUN set -eux; \
    curl -fsSL -o /tmp/opencv.tar.gz \
      "https://github.com/opencv/opencv/archive/refs/tags/${OPENCV_VERSION}.tar.gz"; \
    mkdir -p /tmp/opencv-src; \
    tar -xzf /tmp/opencv.tar.gz -C /tmp/opencv-src --strip-components=1; \
    cmake -S /tmp/opencv-src -B /tmp/opencv-build -G Ninja \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=/usr/local \
      -DBUILD_LIST=core,imgproc,imgcodecs,videoio,dnn,objdetect,highgui \
      -DBUILD_SHARED_LIBS=ON \
      -DBUILD_TESTS=OFF \
      -DBUILD_PERF_TESTS=OFF \
      -DBUILD_EXAMPLES=OFF \
      -DBUILD_DOCS=OFF \
      -DBUILD_opencv_apps=OFF \
      -DBUILD_JAVA=OFF \
      -DBUILD_opencv_python3=OFF \
      -DWITH_FFMPEG=ON \
      -DWITH_GTK=OFF \
      -DWITH_QT=OFF \
      -DWITH_OPENGL=OFF \
      -DWITH_CUDA=OFF \
      -DWITH_CUDNN=OFF \
      -DOPENCV_GENERATE_PKGCONFIG=ON \
      -DCMAKE_INSTALL_RPATH=/usr/local/lib; \
    cmake --build /tmp/opencv-build --parallel; \
    cmake --install /tmp/opencv-build; \
    ldconfig; \
    rm -rf /tmp/opencv-src /tmp/opencv-build /tmp/opencv.tar.gz
 # ─── Vendored dependencies: Catch2, nlohmann/json, nanobind ──────────────────
 #
 # All three are FetchContent'ed by the build today, which makes every CI run
 # depend on GitHub being reachable — a network outage would present as a code
 # failure. Baking them in removes that dependency entirely.
 #
 # Catch2 is *installed*, so tests/CMakeLists.txt:6 `find_package(Catch2 3 QUIET)`
 # succeeds and the FetchContent fallback is never reached. Its source is kept as
 # well so the override below can cover the case where find_package somehow does
 # not fire.
 #
 # nanobind must be cloned with submodules: its `ext/robin_map` is a git
 # submodule, and a GitHub source tarball does not contain it. This is the one
 # dependency where "download the tarball" produces a tree that configures and
 # then fails to compile.
 RUN set -eux; \
    mkdir -p /opt/vendor; \
    git clone --depth 1 --branch "${NLOHMANN_JSON_VERSION}" \
      https://github.com/nlohmann/json.git /opt/vendor/nlohmann_json; \
    git clone --depth 1 --branch "${NANOBIND_VERSION}" --recurse-submodules \
      https://github.com/wjakob/nanobind.git /opt/vendor/nanobind; \
    git clone --depth 1 --branch "${CATCH2_VERSION}" \
      https://github.com/catchorg/Catch2.git /opt/vendor/Catch2; \
    cmake -S /opt/vendor/Catch2 -B /tmp/catch2-build -G Ninja \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=/usr/local \
      -DBUILD_TESTING=OFF; \
    cmake --build /tmp/catch2-build --parallel; \
    cmake --install /tmp/catch2-build; \
    rm -rf /tmp/catch2-build; \
    find /opt/vendor -maxdepth 2 -name .git -exec rm -rf {} +; \
    ldconfig
 # The initial-cache script the build is configured with. It lives in the image,
 # not in the workflow, so the vendor paths have exactly one owner: move a
 # directory here and no consumer needs editing.
 #
 # FETCHCONTENT_FULLY_DISCONNECTED=ON is the load-bearing line. With it, any
 # FetchContent dependency that is *not* covered by an override above is a hard
 # configure error instead of a silent download — so "this build does not touch
 # GitHub" is enforced by the build system rather than asserted in a comment.
 RUN set -eux; \
    printf '%s\n' \
      '# Baked into sae-builder-cpu. Use with: cmake -C /opt/vendor/vendored-deps.cmake ...' \
      '# TRACES: DP-007' \
      'set(FETCHCONTENT_SOURCE_DIR_NLOHMANN_JSON "/opt/vendor/nlohmann_json" CACHE PATH "vendored in the CI image")' \
      'set(FETCHCONTENT_SOURCE_DIR_NANOBIND      "/opt/vendor/nanobind"      CACHE PATH "vendored in the CI image")' \
      'set(FETCHCONTENT_SOURCE_DIR_CATCH2        "/opt/vendor/Catch2"        CACHE PATH "vendored in the CI image")' \
      'set(FETCHCONTENT_FULLY_DISCONNECTED       ON  CACHE BOOL "no CI build may fetch from the network")' \
      > /opt/vendor/vendored-deps.cmake; \
    cat /opt/vendor/vendored-deps.cmake
 # ─── Self-check ──────────────────────────────────────────────────────────────
 #
 # Run the project's own dependency discovery — the same find_package and
 # pkg_check_modules calls CMakeLists.txt makes — against this image, at image
 # build time. An image that cannot satisfy them should fail here, loudly, once,
 # rather than in every CI run that pulls it.
 #
 # Deliberately not a build of the project: the image must be buildable without
 # the repository, and the repository's own configure step is what CI is for.
 RUN set -eux; \
    mkdir -p /tmp/selfcheck; \
    printf '%s\n' \
      'cmake_minimum_required(VERSION 3.21)' \
      'project(sae_image_selfcheck LANGUAGES CXX)' \
      'set(CMAKE_CXX_STANDARD 20)' \
      'set(CMAKE_CXX_STANDARD_REQUIRED ON)' \
      'find_package(OpenCV 5 REQUIRED COMPONENTS core imgproc imgcodecs videoio dnn objdetect highgui)' \
      'message(STATUS "OpenCV ${OpenCV_VERSION}")' \
      'find_package(HDF5 REQUIRED COMPONENTS CXX)' \
      'message(STATUS "HDF5 ${HDF5_VERSION}")' \
      'find_package(Catch2 3 REQUIRED)' \
      'message(STATUS "Catch2 ${Catch2_VERSION}")' \
      'find_package(Python 3.8 REQUIRED COMPONENTS Interpreter Development.Module)' \
      'find_package(PkgConfig REQUIRED)' \
      'pkg_check_modules(AVFORMAT   REQUIRED libavformat)' \
      'pkg_check_modules(AVCODEC    REQUIRED libavcodec)' \
      'pkg_check_modules(AVUTIL     REQUIRED libavutil)' \
      'pkg_check_modules(SWSCALE    REQUIRED libswscale)' \
      'pkg_check_modules(SWRESAMPLE REQUIRED libswresample)' \
      'pkg_check_modules(OPENBLAS   REQUIRED openblas)' \
      'find_library(ORT_LIB onnxruntime REQUIRED HINTS /usr/lib /usr/local/lib)' \
      'find_path(ORT_INCLUDE onnxruntime_cxx_api.h PATH_SUFFIXES onnxruntime' \
      '          HINTS /usr/include/onnxruntime /usr/local/include/onnxruntime /usr/local/include REQUIRED)' \
      'message(STATUS "ORT ${ORT_LIB} / ${ORT_INCLUDE}")' \
      > /tmp/selfcheck/CMakeLists.txt; \
    cmake -S /tmp/selfcheck -B /tmp/selfcheck/build -G Ninja; \
    rm -rf /tmp/selfcheck
 # Python-side tooling the fixture and validation scripts import. Checked here so
 # a missing wheel is an image failure rather than a mid-run traceback.
 RUN python3 -c "import numpy, h5py, scipy; print('numpy', numpy.__version__, 'h5py', h5py.__version__, 'scipy', scipy.__version__)"
 # ─── What is deliberately NOT here ───────────────────────────────────────────
 #
 #   CUDA, TensorRT, ROCm, and the ORT GPU execution providers
 #       No GPU to use them. They belong to the sae-builder-cuda and
 #       sae-builder-rocm siblings (DP-008).
 #
 #   The ONNX models
 #       Seven files, ~725 MB, in Git LFS. T1/T2 tests are model-free by design
 #       (tests/CMakeLists.txt:1-4), so the CI image needs none of them, and
 #       baking them in would inflate the image roughly tenfold to serve the T3
 #       smoke tests alone. Those pull the model they need via LFS in a separate
 #       job. The CI workflow checks out with LFS off for the same reason.
 #
 #   The repository
 #       Nothing from the source tree is COPYed in. The image is a toolchain, and
 #       a toolchain that embeds the code it builds has to be rebuilt whenever the
 #       code changes — which is exactly the per-run cost this image exists to
 #       avoid.
 WORKDIR /src
@@ -40,28 +40,12 @@ Detect faces in sampled video frames.
  presence (SR-002) a lower rate still answers the question, but it lengthens the
  interval between samples and so weakens IoU-based association; sweep the two
  together (VR-002).
- **Minimum face size is 40×40 px**, expressed in **original video resolution**,
+- **Minimum face size is 66×66 px**, expressed in **original video resolution**,
  not decoded-frame pixels. Stating it in original space decouples it from
  `dense_scale`: otherwise a 0.5 downscale silently doubles the effective
  threshold, and dense mode is exactly what scene detection uses.
-
+  66 is a working estimate of where ArcFace embeddings stop being reliable, not a
-  40 is **measured, not estimated** — it replaces an earlier 66 px guess. Two
+  measured value — it should be replaced by the result of VR-005.
  studies bracket it, and the difference between them is the whole reason the
  number is 40 rather than 32:
    - **VR-005** degrades an already-aligned 112×112 crop and matches it against
      a native-resolution gallery. Alignment is held perfect, so it isolates the
      *embedder*: the knee sits at 24–32 px, and 32 px still returns 98.1% TPI.
    - **VR-013** downscales the **whole frame before the detector**, so detection
      and landmark regression degrade along with it. End to end, holding 90% of
      the plateau needs roughly **50 px**, against VR-005's ~22 px.
  The gap is detection and landmark error, which VR-005 excludes by construction
  — so VR-005 is an **upper bound on quality**, not a threshold, and reading a
  floor off it would admit faces in the falling region. **AR-002 therefore takes
  VR-013's number.** 40 sits below the 50 px plateau deliberately: FPI is 0.0% at
  every scale in both studies, so resolution loss costs recall and never
  precision, and an over-tight floor discards presence that SR-002 requires.
 - Emits bounding box, detector confidence, and 5-point landmarks.
 - Bounding boxes must be reported in **original video pixel space**. When
  `dense_scale < 1` downscales the decoded frame, coordinates are rescaled by
@@ -75,9 +59,7 @@ Detect faces in sampled video frames.
 **Current:** SCRFD-500MF via `face_detector_node.hpp`, thresholds in `config.hpp`
 (`detector_conf` 0.5, `detector_nms` 0.4), `min_face_px` 40, `max_faces` 10.
-**Gap:** `min_face_px` re-expressed in original resolution — the value 40 is
+**Gap:** `min_face_px` → 66 and re-expressed in original resolution; `max_faces`
 already correct after VR-013, so what remains is the space it is measured in, not
 the number; `max_faces`
 removed, gated on backpressure (AR-004).
 ## AR-004 — Backpressure
@@ -98,82 +80,8 @@ by dropping work or growing without limit.
 - Memory is the real limit: faces carry 112×112 crops plus 512-float embeddings.
  Backpressure must engage on bytes in flight, not just item counts.
-### The fix is not in this repo
+**Gap:** entire requirement. This is a prerequisite for removing `max_faces`, not
-
+a follow-up to it.
 **Every node output in KPN uses the dropping `push()`** (`pool_node.hpp:404`,
 `:710`; also `branch.hpp`, `fanout.hpp`, `interrupt_node.hpp`). A lossless
 `push_blocking()` — "wait for the consumer to drain instead of dropping; the
 producer just runs slower" — already exists on both `Channel`
 (`channel.hpp:144`) and `OutputPort` (`variant_node.hpp:81`), **and nothing
 calls it.**
 So AR-004 is a change to the KPN repository, not to this one. It needs either a
 per-channel lossless policy or a network-wide default, and this pipeline should
 select lossless: a dropped frame here does not degrade a result, it silently
 changes one.
 **Measured, not inferred.** One 77 s clip at 5 fps should yield ~385 sampled
 frames. On CPU it produced 49, ending at 51 s, with 285 frames dropped at
 `camera_pos` and 51 at `face_aligner`. Rebuilt with CUDA the same clip ran in
 29 s and reached EOF correctly — and still dropped **320** frames at
 `camera_pos`, yielding 65. Faster hardware moves where the queue backs up; it
 does not change what happens when it does.
 Two consequences worth stating:
 - **Raising channel capacity is a stopgap, not a fix.** It lowers the
  probability of overflow without changing the behaviour on overflow, and the
  failure it hides is silent corruption of the output.
 - **Fixture generation is blocked on this** (VR-001), because what gets dropped
  depends on timing. The same command run twice can produce different dumps, and
  a golden fixture cannot be built on that.
 **Current:** fixed in KPN. Node data outputs *park* on a full channel — the
 value is held in a one-slot buffer, the worker is released, and the channel's
 space callback resubmits the node once the consumer drains. That replaced
 `push_blocking`, which slept inside the push and, with one thread per node,
 stopped that node draining its own input. Sentinels remain out-of-band so EOF
 can always overtake a stalled data path. Verified on the same clip: 385 of 385
 sampled frames written, zero drops, and two consecutive runs byte-identical
 where previously they were not.
 A later audit found the losslessness was still incomplete in three places, all
 now closed and each pinned by a regression case in the KPN suite:
 - **`FilterNode` and `RouterNode`** were the last data paths still using the
  throwing `push()` with the exception swallowed. A full output discarded the
  value, and that included the **EOF sentinel**. The decimator passes EOF by
  predicate but its output is reliably full — the embedder is the slowest node
  in the chain — so the token was discarded, nothing downstream shut down, and
  the run had to be killed. This was the wedge.
 - **The sentinel could arrive ahead of a value still queued behind it.** `pop()`
  observed the ring empty and then took the sentinel; a producer can push a
  value *and* publish the sentinel inside that window, so a consumer treating
  EOF as a hard stop loses the tail.
 - **Two firings of one node could overlap**, because the submit gate was
  released before the firing had finished with the node's state. That breaks the
  one-slot park itself: a parked value can be overwritten by the other firing,
  with no drop recorded anywhere.
 **New constraint:** a channel carries at most one undelivered sentinel. A second
 offered before the first is taken is refused and reported, never queued and
 never overwritten — two control tokens on one channel means the stream ended
 twice. Single-shot EOF is what everything does today; this becomes live the
 moment a pipeline is reused for a second input.
 **Consequence:** a lossless decimator is a backpressure point, not a relief
 valve. The source now throttles to the face branch rather than quietly thinning
 it. That is what this requirement asks for, but it changes the shape of a loaded
 run and has not yet been benchmarked.
 It also ran *faster* (29 s → 17 s). A dropped frame has already cost its decode,
 and the overflow exception cost more — so the lossy path was paying for work it
 then discarded.
 **Gap:** the remaining half — bounding by **bytes in flight** rather than item
 count. Channel capacity is still a count of items, and a face carries a 112×112
 crop plus a 512-float embedding, so a crowded frame occupies far more memory per
 slot than a sparse one. That matters once `max_faces` is removed (AR-003).
 ## AR-005 — Face alignment and crop
@@ -184,71 +92,9 @@ Produce the exact input ArcFace expects.
  nose, left mouth, right mouth).
 - Alignment is the *only* geometric normalisation; no additional augmentation at
  inference.
 - **The transform is fitted by Umeyama's closed-form least squares over all five
  points**, which is what InsightFace uses (skimage's `SimilarityTransform` *is*
  `_umeyama`) and therefore what produced the crops ArcFace and LVFace were
  trained on. The canonical warp is part of the input distribution, not an
  implementation detail (AR-011).
 - **Not a robust estimator.** A RANSAC fit buys a small residual by discarding
  the landmarks that disagree with the model, and on a turned face those are the
  foreshortened ones — the signal AR-030 reads. With five points and a two-point
  minimal sample it also cannot separate a mis-detected landmark from honest
  out-of-plane rotation, so the robustness is nominal while the cost to AR-030 is
  total. It is RNG-driven besides, which made replay determinism a property of
  thread scheduling.
-**Current:** `align_face()` in `src/face_utils.hpp`, Umeyama fit via
+**Current:** `align_face()` in `src/face_utils.hpp:9-22`, `cv::warpAffine` to
-`umeyama_similarity()`, `cv::warpAffine` to `{112, 112}`. **Gap:** none.
+`{112, 112}`. **Gap:** none.
 > **Migration note — this was a defect, not a refinement.** Until this landed the
 > fit was `cv::estimateAffinePartial2D(…, cv::RANSAC, 3.0)`. The expectation was
 > that the two agree wherever RANSAC keeps all five points, leaving a small
 > divergence on non-frontal faces. **Measured, that is wrong.** On 400 random
 > gallery headshots, one model held fixed and only the estimator varied:
 >
 > | | median | p90 | max |
 > |---|---|---|---|
 > | Crop disagreement (source px, over the crop corners) | 16.97 | 75.91 | 223.31 |
 > | `cos(umeyama, ransac)` for the resulting embedding | 0.791 | — | — |
 >
 > 83.5 % of crops embed to a cosine below 0.99 of their Umeyama counterpart —
 > they are not the same face crop. The mechanism is that a 4-DoF similarity is
 > exactly determined by **two** points, so every minimal RANSAC sample fits its
 > own pair perfectly and is then scored on the other three. Real landmarks sit a
 > median 2.74 canonical px from any similarity fit to the template (see AR-030
 > below), so images with a landmark outside the 3 px band are the common case,
 > not the exception; RANSAC then keeps two or three inliers and returns a wildly
 > under-determined transform.
 >
 > **Every gallery baked before this change must be rebuilt** — GR-004's embedder
 > stamp catches a model change, not an aligner change, so nothing else would say
 > so.
 >
 > **How much this cost in accuracy is a separate question, and the answer appears
 > to be: less than the crop numbers suggest.** Rebuilding the full gallery
 > (2456 actors) moved the intra/inter separation the AR-023 calibration is fitted
 > from only slightly:
 >
 > | | intra-actor | inter-actor | separation |
 > |---|---|---|---|
 > | RANSAC | 0.6234 | 0.0407 | 0.5827 |
 > | Umeyama | 0.6340 | 0.0440 | 0.5900 |
 >
 > The reconciliation is that the old warp was *wrong but self-consistent*: it
 > produced a differently-framed face rather than a scrambled one, gallery and
 > probe went through the same estimator, and the embedder tolerates framing
 > variation. So the figures in `model-bakeoff.md`, `best-model.md` and
 > `pose-expansion.md` were all produced through the broken warp on both sides and
 > should be re-run, but there is no measured basis for expecting them to move far.
 >
 > The sharper evidence of the old instability is duplicate detection: rebuilding
 > with an unchanged `dedup_tol` dropped **1614** near-duplicate images, where the
 > original build dropped on the order of a hundred. Near-identical source images
 > used to embed to visibly different vectors — RANSAC fitting two-point subsets is
 > unstable under small landmark perturbations, and being RNG-driven it was not
 > reproducible either. That instability is what a tracker accumulating evidence
 > across frames pays for, and it is the strongest reason the fix is worth having
 > independently of any accuracy delta.
 ## AR-006 — Embedding
@@ -264,166 +110,6 @@ Generate a 512-d embedding per aligned crop.
 **Current:** `embedder_node.hpp` + `face_embedder_engine.hpp`; default
 LVFace-B_Glint360K. **Gap:** none.
 ## AR-028 … AR-030 — Embedding input quality
 An embedder handed a face it cannot represent does not fail. It returns a
 confident, plausible, wrong vector, and that vector then competes on equal terms
 with every good one in the gallery — the same failure mode AR-011 names for
 whole models, occurring here at the level of a single region. Quality assessment
 is how that is caught **at inference**, rather than inferred afterwards from a
 study of why a film scored badly.
 Three axes, assessed on every face before its embedding is used as identity
 evidence. They are kept separate and **not collapsed into one scalar**: they fail
 for different reasons, have different remedies, and — as below — do not even earn
 the same response.
 - **Size** — already AR-002, floor at 40×40 px in original resolution, measured
  end to end by VR-013. It is the precedent for the other two: the
  threshold was *located*, not chosen.
 - **Sharpness** — motion blur and soft focus destroy the high-frequency detail
  the embedder keys on, and unlike size they leave the bounding box looking
  perfectly healthy. Measured on the **112×112 aligned crop**, not the raw box:
  the crop is already scale-normalised, so a measure taken there cannot silently
  re-measure face size and double-count it against AR-002.
  The measure is the **variance of the Laplacian divided by the variance of the
  crop** — `crop_sharpness()`, dimensionless. The division is the part that
  earns its place: a raw Laplacian variance, the textbook measure, scales with
  the square of image contrast, so a dim scene reads as soft and a graded-up one
  as sharp, and VR-012 would locate a different knee in every film. That is
  AR-024's objection to the raw cosine in another metric. Normalised, the axis
  means the same thing everywhere, which is the precondition for a single knee
  existing at all.
  Read spectrally it is `E[|ω|⁴]` under the crop's own energy distribution, so
  the blur ladder is monotone by construction rather than by fitting: Gaussian
  blur multiplies that distribution by `e^{-σ²|ω|²}`, which can only move mass
  downward. Two consequences follow from the same identity and are recorded on
  the function: it needs the low-frequency mass real images have (on a
  flat-spectrum synthetic an anisotropic smear makes it *rise*, because the
  surviving perpendicular detail really is as fine as before), and it conflates
  focus with intrinsic texture, so a bearded face outscores a smooth one at equal
  focus. Both are true of every no-reference sharpness measure, and both are
  reasons AR-028 carries the number rather than thresholding on it.
 - **Visibility** — extreme pose or occlusion means the face presents fewer of the
  features the embedding assumes are present. The measure is the **residual of
  the AR-005 alignment fit**: the RMS landmark error, in canonical 112×112
  pixels, left over after the best similarity transform onto the ArcFace
  template. It costs nothing — the transform is computed for the warp regardless,
  and the residual is what that fit could not explain.
  Two properties earn it the job over an explicit yaw estimate:
    - A similarity absorbs rotation, uniform scale and translation **exactly**,
      so the residual is by construction the non-similarity part of the
      deformation: out-of-plane rotation and foreshortening. In-plane roll
      contributes nothing, so "a tilted head reads as a turned one" is excluded
      structurally rather than by tuning. The destination frame is fixed, so face
      size cannot leak in either — that is AR-002's axis, and double-counting it
      would make a small frontal face look occluded.
    - It responds to **occlusion** and to plainly broken landmark sets, which an
      angle regressor by construction does not: a hand across the face is not a
      rotation, but it does displace landmarks.
  Indicative magnitudes from a synthetic foreshortening sweep (`k ≈ cos yaw`):
  `k=1.0 → 0.00`, `0.9 → 1.18`, `0.75 → 3.11`, `0.5 → 6.72`, `0.3 → 9.85`
  canonical px. Smooth and monotone with a usable range; the mapping onto real
  faces is VR-012's to establish, and no threshold is set from these numbers.
  **The synthetic ladder is noise-free and therefore optimistic about the low
  end.** Measured on 400 real TMDB/Jellyfin headshots — the most frontal, most
  cooperative population the pipeline ever sees — the residual runs p5 1.11,
  median 2.74, p90 4.82, max 6.35 canonical px. So landmark noise alone occupies
  roughly the first 3 px, and the synthetic sweep's "26° yaw ≈ 1.2 px" sits
  *below* the noise floor on real data. VR-012 must set any threshold against
  this measured distribution, and a discount curve has to treat the first few
  pixels as uninformative rather than as mild pose.
  Neither a dedicated landmark model (`models/2d106det.onnx` is present but
  referenced nowhere — and it emits points, not pose) nor a direct pose CNN is
  adopted unless VR-012 shows the residual insufficient. If one is needed the
  candidate is **6DRepNet** (MIT, RepVGG-B1g2, 3.47° MAE on AFLW2000) rather than
  Hopenet, which it dominates on accuracy, licence, recency and export
  friendliness. Two caveats to record before that happens: both are trained on
  **300W-LP**, which inherits research-only terms from 300W's constituent sets,
  and both want their own loosely-framed ROI rather than the ArcFace crop — a
  second warp and a second image in flight, which lands on AR-004's byte-based
  backpressure gap. It would also have to run **per track** — over the bounded
  view set AR-019's diversity buffer already keeps — not per face per frame,
  which is the cost rule applied as written: fewer regions, never a degraded
  input.
 **Failing an axis discounts the observation; it does not delete the detection.**
 Only size drops the face outright, and only because VR-005 measured a knee below
 which the embedding carries no signal to discount. Blur and pose are different:
 - A blurred or turned face is still evidence of **presence**, which is what
  SR-002 actually asks about.
 - The tracker admits a link on position *or* identity precisely so that a face
  "whose embedding degraded (blur, profile turn)" stays linkable. Remove the
  detection and the track fragments, costing the window extent AR-012/AR-013
  exist to protect.
 - AR-019 harvests non-frontal views *because* TMDB headshots are frontal.
  Discarding turned faces starves the mechanism built to fix the pose problem of
  its raw material, and AR-020 then has nothing to resolve at EOF.
 The natural home for the discount is `EvidenceDiscounter` (AR-025), which already
 weights how far one observation may move a track's belief. Note that its present
 weight is pure *novelty*, so a profile view — maximally distant from everything
 counted so far — currently scores near 1.0 and moves the belief hardest, when
 against a frontal gallery it deserves the least trust. Novelty and reliability
 are orthogonal and multiply; quality supplies the second term.
 **Quality is carried, not consumed.** The vector travels with the face and is
 written to the VR-001 dump alongside the embedding, so a threshold can be
 re-litigated against recorded data instead of by re-running video, and so
 VR-010's provenance records what the run actually admitted.
 **No quality threshold is hand-set.** Each axis either has a measured knee
 (VR-012, as VR-005 did for size) or it discounts rather than drops — a
 hand-chosen cutoff on an uncalibrated measure is the same unfalsifiable magic
 number AR-024 retired for similarity, and it would fail the same way: meaning
 something different for every detector, every embedder and every film.
 **Current:** all three axes are measured and carried, and the vector reaches the
 dump. `FaceAlignerFunc` is where it is filled in, because both measured axes fall
 out of work the warp already does: visibility is the residual from
 `estimate_alignment()`, and sharpness is `crop_sharpness()` on the 112×112 crop
 the node has just produced. Size stays `bbox` — deliberately not copied into a
 field of its own, since that would hold the same quantity in two coordinate
 spaces and the copy is the one that drifts. No face is admitted unscored, so a
 negative value downstream is a bug rather than a poor-quality face. The
 degenerate-fit case is still dropped — it has no crop and no fit to score — but
 is now **counted** and reported once at EOF instead of vanishing.
 `sharpness` and `alignment_residual` are written to the VR-001 dump as per-face
 columns parallel to `confidence`, taking the dump to `schema_version` 2. The bump
 is not for readers — both sides check by name, and a v1 dump still replays — but
 so that a consumer of the vector can tell *never scored* from *scored zero*,
 which is a real reading on this axis. Nothing yet *consumes* any of it.
 **Gap:** three, in the order they block each other.
 1. **The fixtures do not carry the vector.** They are v1, and re-dumping needs a
   GPU host (`scripts/make_fixtures.sh`), so until that runs VR-012 has recorded
   data available in principle and none in hand.
 2. **AR-030's discount does not exist.** The measure must reach
   `EvidenceDiscounter` as the reliability term, multiplying the novelty weight
   rather than replacing it.
 3. **Two properties of the sharpness measure are recorded but unquantified on
   real faces**, and both distort the low end of the axis, which is where a knee
   would go. It is exactly contrast-invariant in the algebra, but the 8-bit
   quantisation floor lands in the numerator, so a crop that is *dim and soft*
   reads sharper than it is — on the synthetic ladder a half-contrast copy reads
   0.9% high when sharp and 148% high at σ 2.5. Separately, `align_face` warps
   with `BORDER_CONSTANT`, so a face crossing the frame edge brings a hard black
   step into the crop, and a step edge is high-frequency; the normalisation
   blunts this but does not remove it. Neither is corrected here. The candidate
   fixes are a validity mask or a different border mode, and the second changes
   what the embedder is fed (AR-011) — so VR-012 measures the size of each effect
   on the dumped distribution first, and no correction is chosen before that.
 ## AR-007, AR-008 — Tracking
 Link detections across frames into tracks representing one physical person.
@@ -468,55 +154,11 @@ Two distinct signals, deliberately kept separate:
 - **`is_scene_boundary`** — opt-in (`--scene-detect`). TransNetV2 over a densely
  decoded, downscaled stream flags a *true shot/scene boundary*.
 > **`is_scene_boundary` currently has no producer.** `grep -rn is_scene_boundary
 > src/` finds no assignment anywhere: `SceneDetectorFunc` is a *terminal sink*
 > (`main.cpp:298-300`, `kpn::out<>`) that writes `scenes.json` and never
 > annotates the `Frame` flowing to the face pipeline. The field is therefore
 > always `false`, and the dump column (`embedding_dump_node.hpp:38`) is a
 > constant 0. Compounding it, `main.cpp:280` returns from the
 > `--dump-embeddings` branch *before* the `scene_detect` branch at `:296`, so no
 > dump-producing path even instantiates the detector.
 >
 >
 > **It cannot be fixed by making the node a pass-through.** TransNetV2 buffers
 > `kWindow` = 100 dense frames before it can score any of them, runs inference
 > every `scene_stride` (50) frames, and trusts only each window's centre. So a
 > boundary at time *T* is not known until roughly 100 dense frames after *T* —
 > about **3.3 s at 30 fps**. The face pipeline runs on a parallel branch and has
 > long since passed *T* by then. An association hint that arrives after the
 > association is worthless.
 >
 > Three ways out, none free:
 >
 > 1. **Two-pass.** Run scene detection to completion, then analyse faces with
 >    boundaries already known. Simple and correct; costs a second decode of the
 >    whole file, and dense decode is already the pipeline's dominant cost.
 > 2. **Delay the face branch** by the detector's window latency. Keeps one pass;
 >    adds a buffering stage and couples the two branches' timing, which is the
 >    kind of coupling that produces heisenbugs under backpressure.
 > 3. **Leave it unwired.** Accept that `is_cut` is the only association hint.
 >
 > **Option 3 costs less than it appears**, which is why this is a decision rather
 > than a bug. Since the redesign made cuts and boundaries do the *same thing* —
 > both say "spatial continuity is broken, associate on embedding" — TransNetV2
 > adds nothing over the histogram except on transitions the histogram misses:
 > slow dissolves and fades, where there is no frame-to-frame discontinuity to
 > detect. That is a real but narrow gap.
 >
 > The value TransNetV2 retains is in **AR-019**, whose promotion gate requires a
 > span with no cut *and* no boundary. There a late answer is still usable,
 > because promotion happens when a track is confirmed rather than per frame.
 > Wiring it there — offline, against the collected boundary list — is cheaper
 > than any of the three options above and does not touch the hot path.
 >
 > **Recommendation: option 3 plus the AR-019 wiring**, and revisit if dissolve-
 > heavy material shows association failures the histogram misses.
 Both feed AR-007 as **association hints**: they tell the tracker that spatial
 continuity is broken and that association should weight embedding over IoU.
 Neither ends a presence window (AR-012).
-In dense mode the source decodes at `scene_decode_fps` (default 0 = native) and a
+In dense mode the source decodes at `scene_decode_fps` (default 12) and a
 decimator splits the stream: full-resolution sampled frames to the face pipeline,
 downscaled dense frames to the scene detector
 (`frame_source_node.hpp:63`). `sample_fps` is independent of this — the face
@@ -537,44 +179,31 @@ degrading what a single inference sees. A model run off-distribution produces
 confident, plausible, wrong output, and the error is invisible without a study
 that should not have been necessary.
-Two places this was violated, both now closed:
+Two places this is currently violated:
-1. **`scene_decode_fps = 12` starved TransNetV2.** `kWindow` is 100 frames. At
+1. **`scene_decode_fps = 12` starves TransNetV2.** `kWindow` is 100 frames. At
-   native 25 fps that window spans ~4 s; at 12 fps it spanned ~8.3 s, so the
+   native 25 fps that window spans ~4 s; at 12 fps it spans ~8.3 s, so the model
-   model saw roughly half-speed motion over twice the temporal context it was
+   sees roughly half-speed motion over twice the temporal context it was trained
-   trained on. **Requirement: feed TransNetV2 at the source's native frame
+   on. **Requirement: feed TransNetV2 at the source's native frame rate**, so a
-   rate**, so a 100-frame window covers the duration the model expects. The
+   100-frame window covers the duration the model expects. The
-   "tolerates ~12fps" note in `config.hpp` described a compromise, and the
+   "tolerates ~12fps" note in `config.hpp` describes a compromise, and the
-   recorded margin was consistent with it — a non-boundary baseline at ~0.50 with
+   recorded margin is consistent with it — a non-boundary baseline at ~0.50 with
   real boundaries reaching only ~0.7+ is a compressed separation, not a healthy
-   one. **Done:** `scene_decode_fps` defaults to 0.
+   one.
-2. **Hardcoded 25 fps in boundary dedup.** The node merged boundaries closer than
+2. **Hardcoded 25 fps in boundary dedup.** `scene_detector_node.hpp:138` merges
-   `0.04 s` — "~1 frame @25fps". **Requirement: derive this from the source's
+   boundaries closer than `0.04 s` — "~1 frame @25fps". **Requirement: derive
-   actual frame rate. Done:** `SceneDetectorFunc::dedup_window_sec()` takes the
+   this from the source's actual frame rate.**
   median of the frame intervals the detector was actually fed and halves it.
   Half a frame rather than a whole one, because the only thing being merged is
   one frame scored by two overlapping windows; two distinct frames are a full
   interval apart and both have to survive.
 The two are one change, not two. A native-rate stream is where the old constant
 did the most damage — at 30 fps, 0.04 s is wider than a frame, so two cuts on
 consecutive frames merged into one and the loss showed up nowhere: the file
 simply had fewer boundaries.
 Dense decode is the pipeline's cost driver, so (1) is not free. The cost is
 accepted: the alternative is a boundary signal that steers association (AR-007) while
 being quietly unreliable. `dense_scale` remains available as a spatial reduction,
 since downscaling is a documented, understood degradation rather than a temporal
-one the model has no defence against — and TransNetV2 downsamples to 48×27
+one the model has no defence against.
 regardless.
 **Current:** histogram cut in the decoder; `scene_detector_node.hpp` for
-TransNetV2, fed at native rate with a framerate-derived dedup window.
+TransNetV2. **Gap:** native-rate dense decode; framerate-derived dedup;
-**Gap:** `scene_threshold` (0.60) is still the value picked against 12 fps input
+`--scene-detect` is default-off despite now feeding association.
 and is now certainly wrong — VR-006 re-fits it, and until it does, boundary
 recall at native rate is untuned rather than better. `--scene-detect` is
 default-off despite now feeding association.
 ## AR-012 … AR-017 — Track-level identity propagation — **CHANGED BEHAVIOUR**
@@ -757,30 +386,12 @@ An embedding is admitted only if its similarity to one already in the store fall
  admitting it risks poisoning the store.
 A starting band of roughly **0.90–0.95** is the working estimate, to be tuned
-(VR-007). Note this is deliberately conservative compared to the retired
+(VR-007). Note this is deliberately conservative compared to the current
-`expand_novelty_sim` (0.55), which promoted embeddings *far* from the gallery —
+`expand_novelty_sim` (0.55), which promotes embeddings *far* from the gallery —
 much more aggressive, and much more exposed to admitting the wrong person.
 Both bounds must be expressed as calibrated probabilities, not raw cosines (AR-024).
 The lower bound is asked twice. `admit` compares a newcomer against its
 *closest* existing member, which a gradually drifting track can chain past: every
 step inside the band while the endpoints are strangers — the shape a track-ID
 collision takes over a slow pan. So the same bound is re-applied across **every
 pair** in the store before promotion. One bound, two enforcement points; not a
 second constant.
 Novelty is deliberately **not** a threshold. The store's eviction policy orders
 its members by similarity to the actor's existing references and drops the
 best-recognised one, so novelty-seeking is a ranking with nothing to tune, and
 the band's upper bound already refuses the redundant views at the door.
 **Current:** implemented in `gallery/track_gallery.hpp` — `admit` at the door,
 `store_coherence` at promotion, both bounds from `Config::expand_band_lo/hi`.
 Refusals are counted (`band_rejected`).
 **Gap:** the bounds themselves are unswept working values (VR-007).
 ### AR-019 — Expansion of known actors
 When a track is owned (AR-012), its store is promoted into a **per-film, in-memory
@@ -881,14 +492,14 @@ natural unit for anonymous presence, should that be adopted (AR-012, TBD).
  open (VR-007).
 **Current:** `src/gallery/track_gallery.hpp` implements a per-track diversity
-buffer with eviction biased to gallery-far poses, admission and promotion both
+buffer with eviction biased to gallery-far poses, promotion gated on
-gated on the AR-018 band in probability space, cleared on `is_cut`. Wired at
+`expand_novelty_sim` / `expand_track_spread_max`, cleared on `is_cut`. Wired at
-`identity_matcher_node.hpp:227`, cleared at `:126`; the calibration is handed
+`identity_matcher_node.hpp:227`, cleared at `:126`.
 over at `:114`.
-**Gap:** all three quiet-signal conditions rather than only `is_cut`; and the
+**Gap:** the band rule of AR-018 replacing the current novelty/spread gates; all
-whole of AR-020 — the TBI queue, the deferred pass, and deferring output until it
+three quiet-signal conditions rather than only `is_cut`; probability space
-completes.
+throughout (AR-024); and the whole of AR-020 — the TBI queue, the deferred pass, and
 deferring output until it completes.
 ## AR-022 — Unidentified-track capture
@@ -1036,45 +647,21 @@ is the only viable formulation — a per-pair loop is orders of magnitude off.
 **All similarity computation goes through the GEMM path**, with no exception
 justified by "this set is small". Three call sites:
-1. **Baked gallery** — GEMM (`sim_engine_->compute()`, backend from
+1. **Baked gallery** — already GEMM (`sim_engine_->compute()`,
-   `SAE_GEMM_BACKEND`). ✓
+   `identity_matcher_node.hpp:143`, backend from `SAE_GEMM_BACKEND`). ✓
-2. **Per-film annex** — was a **CPU loop**, justified in-comment by "tens of
+2. **Per-film annex** — currently a **CPU loop**
-   embeddings". AR-018…AR-021 invalidated that assumption: every owned track
+   (`identity_matcher_node.hpp:159-162`), justified in-comment by "tens of
-   contributes, so the annex grows with cast size and film length. Now appended
+   embeddings". AR-018…AR-021 invalidates that assumption: every owned track now
-   to the gallery matrix rather than scored separately — promotions are pushed
+   contributes, so the annex grows with cast size and film length. It must move
-   into the engine's resident matrix (`ISimilarityEngine::append_rows`,
+   into the GEMM path — appended to the gallery matrix, or a second multiply.
   capacity doubling, device-to-device on the GPU backends) and `flat_actor_`
   grows in lockstep, so one multiply covers baked and promoted references and
   best-of-N is a single pass over one similarity column. ✓
 3. **Deferred TBI pass (AR-020)** — the most GEMM-friendly operation in the
   pipeline: all TBI embeddings against the full gallery-plus-annex, offline,
   operands resident, no streaming. One large multiply, not a loop over entries.
   Not yet built; AR-020 owns it.
 **Current:** 1 and 2 done. `TrackGallery` holds the annex as a contiguous
 row-major matrix plus a parallel actor index, and hands newly promoted rows to
 the matcher once per frame (`drain_promotions`), which is what call site 3 will
 score against.
 **Gap:** call site 3, gated on AR-020 existing at all.
 This constrains AR-018…AR-021's implementation: the annex must be a **contiguous matrix**
 with promotions appended, plus a parallel actor-index mapping — exactly the
 `flat_emb_`/`flat_actor_` arrangement the baked gallery already uses.
 **Ordering note.** Absorbing promotions is a once-per-frame step that runs after
 every face in the frame has been scored, not mid-frame. Appending mid-frame would
 invalidate the similarity pointer the matcher is still reading, and it also
 removes an accidental dependence on face order within a frame: a promotion helps
 subsequent frames, never the one that produced it, which is the semantics the
 expansion store already documents.
 **The CPU GEMM path requires OpenBLAS.** It is what CI and the cpu builder image
 run, so a silent fall back to the scalar loop would mean AR-027 is measured — or
 believed — on a path no release uses. Absence is a configure error; the scalar
 loop survives as the correctness oracle, reachable only via
 `-DSAE_ALLOW_SCALAR_GEMM=ON`.
 ### Scaling characteristics that must be known, not assumed
 - **Throughput versus gallery size must be measured** (VR-008) and published. The
@@ -1170,16 +757,9 @@ prerequisite.
 ## DP-005 — Installation and provisioning
- Native install, **no Docker at runtime** — GPU passthrough is the most fragile
+- Native install, **no Docker** — GPU passthrough is the most fragile part of a
-  part of a containerised setup and exists only because of the container.
+  containerised setup and exists only because of the container. Natively the GPU
-  Natively the GPU works with the host drivers and media paths need no
+  works with the host drivers and media paths need no re-mounting.
  re-mounting. This constrains how the software *runs*, not how it is *built*:
  DP-008 uses containers as build environments precisely because that side has
  none of these problems.
 - The installer may **fetch a prebuilt binary** (DP-008) instead of compiling.
  Compiling stays supported, but should not be the only path — it is the slowest
  and most fragile step of a first install. TRT engines are still built locally
  either way (DP-008).
 - An installer (`scripts/build_install.py`) consuming one `install.yaml`:
  platform (nvidia/amd/cpu), embedder model, gallery scan cadence, install
  prefix; runtime secrets written to a `.env`, editable without recompiling.
@@ -1190,130 +770,6 @@ prerequisite.
 **Gap:** installer unbuilt.
 ## DP-007 — CI build image
 CI runs on an Intel N100 with no discrete GPU, so the test build must configure
 **CPU-only** and must not require CUDA, TensorRT or ROCm:
 ```
 -DSAE_INFERENCE_BACKEND=ORT  -DSAE_GEMM_BACKEND=CPU
 ```
 A prebuilt container image supplies the toolchain, published to the **Gitea
 container registry** and pinned by tag — matching the `jellytau-builder`
 precedent. Building dependencies per CI run is untenable on an N100, and OpenCV 5
 from source would dominate every run.
 The same registry stores corpus dump fixtures as generic packages (see the
 fixtures table in `requirements.md`). Rebuild the image when its dependency set
 changes, not per run, and pin CI to a tag rather than `latest` so a rebuild
 cannot silently change what a green build meant.
 **Required in the image:**
 | Dependency | Why |
 |---|---|
 | CMake, C++ toolchain, pkg-config | Build |
 | **OpenCV 5** | `CMakeLists.txt:25` prefers 5, falls back to 4. The branch targets 5, so the image should carry it — it is not yet in most distro repos and building it per-run is prohibitive |
 | HDF5 (C++) | Galleries are HDF5-native; also the dump format |
 | FFmpeg dev libs — `libavformat`, `libavcodec`, `libavutil`, `libswscale`, **`libswresample`** | Decode. See the note below on swresample |
 | Python 3 + numpy, h5py, scipy | Python-side tests, replay, traceability tooling |
 | **OpenBLAS** | Backs the CPU similarity GEMM. Without it the fallback is a scalar loop, and the CPU path is exactly what this host runs — see below |
 | Catch2, nlohmann/json | **Vendored into the image, not fetched.** Both are `FetchContent`-ed today (`CMakeLists.txt:220`, `tests/CMakeLists.txt:8`), which makes every CI run depend on GitHub reachability |
 **OpenBLAS is not optional here, despite being optional in the build.** CI has no
 GPU, so `SAE_GEMM_BACKEND=CPU` is the only path it exercises — and since AR-003
 removed the per-frame face cap, a crowded frame scores many faces against a
 library-scale gallery. The scalar fallback is correct but scales badly, which
 would make the CPU path the bottleneck in the one place it cannot be avoided
 (AR-027). The build warns when it is missing rather than failing, so a developer
 without it still gets a working tree; the image must not be that case.
 The test target links it too. Otherwise the suite compiles the scalar fallback
 while the image ships CBLAS, and CI would verify a kernel that is not the one
 running in production.
 **Deliberately excluded:** CUDA, TensorRT, ROCm — no GPU to use them. Also the
 ONNX Runtime *GPU* providers; only the CPU provider is relevant, and only for T3
 smoke tests.
 **Models are not baked into the image.** The seven ONNX files total ~725 MB and
 live in Git LFS. T1/T2 tests are model-free by design
 (`tests/CMakeLists.txt:1-4`), so the default image needs none. T3 smoke tests
 require a model and should pull it via LFS in a separate job rather than
 inflating the image tenfold for a minority of tests.
 **`libswresample` is a real gap, not a formality.** The current
 `pkg_check_modules` list (`CMakeLists.txt:200-203`) covers avformat, avcodec,
 avutil and swscale but **not** swresample — which IR-004 needs to downmix to mono
 and resample to 11025 Hz. It must be added alongside the audio-signature work.
 **Gap:** entire requirement. The image does not exist, and no CI config is
 present in this repo.
 ## DP-008 — Builder images and release binaries
 Produce prebuilt binaries per backend so deployment does not require every user
 to compile the project.
 **This does not contradict DP-005.** That requirement rejects Docker as a
 *runtime* — GPU passthrough is the most fragile part of a containerised setup and
 exists only because of the container. Using Docker as a *build* environment is
 the opposite case: hermetic, reproducible, and it lets one machine produce
 binaries for backends it cannot itself run. Build in a container; run natively.
 ### Image matrix
 The build has two independent axes (`CMakeLists.txt:48-49`), so the useful
 combinations are:
 | Image | `SAE_INFERENCE_BACKEND` | `SAE_GEMM_BACKEND` | Target |
 |---|---|---|---|
 | `sae-builder-cpu` | ORT | CPU | CI (DP-007), and the smoke-test fallback |
 | `sae-builder-cuda` | TRT | CUDA | NVIDIA |
 | `sae-builder-rocm` | ORT | ROCM | AMD |
 All three carry the DP-007 dependency set (OpenCV 5, HDF5, FFmpeg incl.
 swresample, vendored Catch2/nlohmann) and differ only in the accelerator stack.
 The CPU image is the CI image — one artifact, two uses.
 Published to the Gitea container registry, pinned by tag, rebuilt when the
 dependency set changes rather than per run.
 ### What ships, and what cannot
 **Ships:** the `scene_analyze` binary and its companions, per backend.
 **Cannot ship: TensorRT engines.** `.engine` files are specific to the GPU
 architecture and TRT version they were built on — `scripts/build_trt_engines.sh`
 must still run on the target machine. A prebuilt binary shortens the install; it
 does not remove the local engine-build step, and the installer must not imply
 otherwise.
 **Cannot ship: models.** ~725 MB in LFS, and orthogonal to the binary.
 ### The constraint that decides the base image
 **A binary built in a container runs against the host's glibc.** Build on a
 newer base than the oldest supported host and it fails at load with
 `GLIBC_2.xx not found` — the classic and entirely avoidable trap when shipping
 binaries out of containers.
 So the base is chosen for the *oldest* glibc to be supported, not for
 convenience or recency. Accelerator libraries have the same shape of problem:
 the binary links against a driver-provided runtime, so each image must document
 the CUDA/ROCm version range its output is compatible with, and the installer
 must check it rather than discovering a mismatch at first inference.
 ### Jobs
 A release job per backend, producing a tagged artifact in the registry. These are
 **not** the CI gate — the gate runs the CPU image on every push (DP-007);
 release builds run on tag. Their outputs are what DP-005's installer fetches
 when the user does not want to compile.
 **Gap:** entire requirement. No images, no release jobs.
 ## DP-006 — Gallery maintenance as a background concern
 - Incremental gallery refresh runs on a timer (`gallery_scan_interval`, default
@@ -1403,10 +859,8 @@ rewritten.
 **Media shorter than 120 s.** The window `runtime/2 ± 60 s` underflows, so no
 signature is emitted and **no sync offset is applied**. Such items fall back to
-the runtime tier, which is adequate: a 90-second extra or trailer is not the
+the runtime/exact tiers, which is adequate: a 90-second extra or trailer is not
-content whose cut alignment matters. (There is no `exact` tier: the file-hash
+the content whose cut alignment matters. Both producers must apply the identical
 tier was withdrawn on legal grounds — it fingerprinted an individual copy rather
 than the cut the timings describe. See the server spec §3.) Both producers must apply the identical
 rule, or they diverge on exactly the short items most likely to be
 mis-identified.
@@ -1428,47 +882,7 @@ plugin. Consequences to carry through:
 - Files never processed by this pipeline still get a signature from the plugin;
  the two paths coexist deliberately.
-**Current:** `src/audio_signature.*` implements the construction, and
+**Gap:** entire requirement — no audio path exists in the pipeline today.
 `tests/fixtures/audio/` holds the golden vector shared verbatim with the plugin
 repo, which now matches it byte for byte from C# (jRay `JR-042`/`JR-043`).
 `sae_audio` (nanobind, as `sae_embed` and `sae_kpn` are) exposes the same C++ to
 Python so a study drives the shipped code rather than a numpy port.
 **VR-014 measures what the golden vector cannot** — that the signature actually
 aligns a differently trimmed release, on real film audio rather than a synthetic
 tone. It does, with an order of magnitude to spare.
 **The accuracy question is settled and is not close.** What the offset is *for*
 is shifting scene windows, which are seconds long, so half a second of error is
 invisible; the budget is 500 ms. Over 40 random offsets inside the ±600-frame cap
 the recovered offset was the nearest frame every time — **worst error 46 ms**.
 That figure is the quantisation floor rather than a measurement of quality: the
 offset is expressed in whole 92.88 ms frames, so no correct answer can ever be
 worse than half a frame. The `runtime/2` anchor behaves as specified through real
 head-trimmed files (cutting `delta` from the head moves the window by
 `delta/2`), and both an out-of-cap offset and unrelated content are declined
 outright (0.10 and 0.07).
 **Where it is soft is tier labelling, not alignment.** The *score* at the correct
 offset falls with sub-frame misalignment — 0.94–0.99 when the true offset lands
 within 0.1 of a frame boundary, 0.69–0.73 at half a frame — because the two
 windows' frame grids no longer coincide. The offset stays right, but only 13 of
 40 cleared the server's 0.85 `audio` threshold and the other 27 were demoted to
 `loose`, a tier that means "possibly the same cut, degraded audio". The threshold
 was calibrated on a re-encode at *zero* offset, where the score is 1.00.
 The remedy is measured, not proposed (UT-108): counting a frame as agreeing if
 its peak bin matches **within ±1 frame** returns all 40 to `audio` (worst 0.906)
 while unrelated content and out-of-cap offsets stay at 0.12 and 0.16 — the gap
 that makes the threshold mean anything is untouched. It costs 81 ms of offset
 accuracy, of a 500 ms budget, because the flattened peak lets the argmax pick an
 adjacent frame. ±2 frames buys nothing further. Adopting it is a
 [server spec](../../JRay-public-server/SPEC.md) §3 change — the score is
 normative and shared by three repos — so this repo measures it and leaves the
 decision there.
 **Gap:** the signature is computed but **not yet emitted** into the truth file —
 that is the `IR-002` field and the coordinated `schema_version` bump.
 ## IR-006 — Jellyfin round-trip
@@ -1531,57 +945,8 @@ surfaced as a build report.
  different models are meaningless but *look* plausible — this fails silently and
  expensively otherwise.
-### The stamp
+**Gap:** named as step 4 of the `service-conversion.md` implementation plan;
-
+unbuilt. This is the highest-value small fix in the document.
 Two fields, written together: the model file's **basename** and the **SHA-256 of
 its bytes** (plus `embed_dim` as a cheap extra guard). Stored as the `/embedder`
 group in the gallery HDF5, and as an optional top-level `"embedder"` object in
 the legacy JSON format.
 The hash *decides*; the name is what a human *reads*. Neither alone is enough. A
 name is a promise rather than a fact — models get re-exported, re-quantised and
 overwritten in place under an unchanged filename, which is exactly the case where
 the weights differ and nothing else does, so a name-only stamp is blind to the
 failure it exists to catch. A hash alone is correct but unactionable: *"expected
 3f2a…, got 9c1b…"* tells an operator nothing about what to do next. SHA-256 over
 the file is derived from the artefact rather than asserted about it, needs no
 registry kept up to date, and costs ~0.1 s for a 250 MB ONNX once per process.
 ### Verdicts
 | Verdict | When | Default | Under strict mode |
 |---|---|---|---|
 | `match` | hashes agree | proceed | proceed |
 | `weak_match` | names agree, one side unhashable | **warn** | **error** |
 | `unstamped` | gallery predates GR-004 | **warn** | **error** |
 | `unknown_embedder` | gallery stamped, embedder unidentifiable | **warn** | **error** |
 | `mismatch` | proven different models | **error** | **error** |
 **A mismatch is fatal in every mode, with no bypass**, and the message names both
 sides — what the gallery was built with and what is loaded.
 The three "cannot prove it" verdicts warn loudly instead, because they describe an
 *unknown* state rather than a *known-bad* one, and because every gallery built
 before this requirement is unstamped. Hard-failing all of them would make the
 check something people route around rather than trust. Strict mode
 (`--require-gallery-stamp`, or `SAE_REQUIRE_GALLERY_STAMP=1`, which propagates to
 subprocesses) promotes them to errors — that is the mode measurement work runs in.
 `scripts/stamp_gallery.py` re-binds an existing gallery without re-embedding, so
 migration costs one command; that is what makes "warn" a temporary state rather
 than a permanent one.
 ### Scope of the check
 Embedding **dumps** carry the same stamp (`embedder_model` / `embedder_sha256`
 root attributes, `scripts/optimizer/SCHEMA.md`): a replay has no live embedder, so
 the dump *is* the embedder as far as the gallery is concerned. Derived galleries
 (filter, cast-restrict) inherit their source's stamp; `--merge` and the JSON
 gallery merge check *before* writing, since a merged file holding two embedding
 spaces cannot be untangled afterwards by any later check.
 **Gap:** none. Stamped in `gallery_builder.cpp` and the Python builders; verified
 in `scene_analyze`, `scene_preview`, the `sae_kpn` matcher binding, `replay.py`,
 `optimize.py`, `movienet_eval.py` and the merge paths.
 ## GR-006 … GR-009 — Provenance tiers and poisoning guard
@@ -1653,30 +1018,19 @@ Persist pipeline state at the point where the expensive work ends.
  per-frame index table (`face_offset`, `face_count`) pointing into them. Avoids
  variable-length HDF5 types and reads straight into numpy.
 - Stores per frame: `timestamp_sec`, `frame_idx`, `is_cut`, `is_scene_boundary`.
-  Per face: `embedding` [N,512], `bbox` [N,4], `landmarks` [N,10], `confidence`,
+  Per face: `embedding` [N,512], `bbox` [N,4], `landmarks` [N,10], `confidence`.
-  and from v2 the AR-028 quality vector — `sharpness` [N] and
+- Invariants: embeddings unit-norm; `face_offset` contiguous; bboxes already in
-  `alignment_residual` [N]. Size, its third axis, is `bbox` and is not
+  original resolution; frames with no faces still get a row so timestamps stay
-  duplicated.
+  dense; EOF sentinels not written.
 - Invariants: embeddings unit-norm; `face_offset` contiguous; bboxes and
  landmarks in **decoded-frame** pixels with `bbox_upscale` recorded alongside
  (the dump is a faithful tap, so it does not transform what the tracker saw —
  see VR-010); frames with no faces still get a row so timestamps stay dense;
  EOF sentinels not written.
 - Enabled by `--dump-embeddings out.h5`; teeing must not perturb the live result.
 Schema owned by [`scripts/optimizer/SCHEMA.md`](../scripts/optimizer/SCHEMA.md).
 **Current:** C++ dump sink (`embedding_dump_node.hpp`, `dump_embeddings.cpp`),
-read by `replay.py`. At `schema_version` 2, which AR-028 took it to by adding the
+read by `replay.py`. **Gap:** **AR-012 breaks the replay contract.** Track extents
 quality columns; readers on both sides check the datasets by name, so a v1 dump
 still replays and reports the vector as unknown rather than as zero.
 **Gap:** **AR-012 breaks the replay contract.** Track extents
 are decided in the tracker, which is *downstream* of the dump — so a replay can
 reproduce them, but only if the dump preserves everything the tracker needs.
 Verify `landmarks`/`bbox`/`is_cut` suffice, and bump `schema_version` if not.
 The committed fixtures are still v1, so they carry no quality vector until
 `scripts/make_fixtures.sh` is re-run on a GPU host.
 ## VR-002 — Replay and sweep
@@ -1726,14 +1080,6 @@ The committed fixtures are still v1, so they carry no quality vector until
 Quantify where ArcFace degrades, replacing the 66×66 estimate in A1 with a
 measurement.
 > **Result, and its limit.** Knee at 24–32 px; 32 px returns 98.1% TPI at 0.0
 > FPI. But the probe is an already-aligned 112×112 crop, so alignment is held
 > perfect and this measures the **embedder alone** — an upper bound, not a
 > threshold. **VR-013** re-asks the question end to end, downscaling the whole
 > frame before the detector, and lands near 50 px. AR-002's floor of 40 px comes
 > from VR-013; this study is what shows how much of the gap is detection and
 > landmark error rather than embedding.
 **Method.**
 1. Select ~100 gallery actors having more than one mugshot.
@@ -1799,54 +1145,6 @@ round 1 seeding references that corrupt round 2.
 "expansion helps live matching" from "expansion helps the second pass", which the
 current all-or-nothing `expand_gallery` flag cannot distinguish.
 ## VR-015 — Per-node cost and bottleneck attribution
 **Requirement: a run must be able to report where its time went, per node, and
 which node is setting the pace.** Without it, optimisation is guesswork, and
 worse than guesswork — the obvious number is wrong in a specific, repeatable
 direction, so acting on it makes the pipeline slower.
 **Why the obvious number is wrong.** KPN times a node across `fire_once`, which
 wraps the functor *and* `push_outputs`. Under AR-004 a push parks on a full
 downstream channel, so a node that is merely waiting bills that wait to itself.
 On the SuperHero reference run (`docs/benchmark.md`) `frame_source` reported
 `ema=141.899ms` per frame while its own decoder logged 12-18 ms: it was
 backpressured, and the report named the *fastest* node in the graph as the most
 expensive one. A second trap sits behind the first — `ema_exec_ms` is an
 exponentially weighted average, so `frames × ema` is not a total; on a film whose
 per-frame cost swings between crowd scenes and landscapes the two differ
 substantially.
 **Method.** Three measurements per node, none of which is sufficient alone:
 | Measure | What it is | What it cannot tell you |
 |---|---|---|
 | `cpu_ms` | thread CPU time (`CLOCK_THREAD_CPUTIME_ID`) | GPU wait — a device-bound node looks idle |
 | `exec_ms` | cumulative wall time inside the node | work from waiting — backpressure inflates it |
 | `pressure` | mean input fill − mean output fill | how expensive the node is, only that it paces |
 Queue occupancy has to be **sampled during the run**. `current_fill` is
 instantaneous and every channel has drained by shutdown, so a single read at the
 end describes an idle pipeline however congested it was.
 **The number that matters** is `pressure`, because work piles up in front of the
 bottleneck and starves everything after it, and that ordering holds whether the
 node is waiting on a core, a GPU or a disk. `cpu_share` then selects the repair:
 a pacing node with a saturated thread is CPU-bound and the work must get cheaper,
 while a pacing node with an idle thread is device-bound, where batch size and
 engine precision are the knobs and the C++ is not.
 **Current:** `--benchmark <path>` writes the JSON report and prints a table at
 shutdown; `src/benchmark.hpp`. Attribution is a pure function over KPN snapshots,
 so it is verified on CI's GPU-free N100 (UT-120…UT-124) rather than only by
 running the pipeline. The node graph is recovered from KPN's channel names, so a
 re-wired topology needs no change here. Required `NodeStats::total_exec_us` in
 the KPN submodule — the EMA could not be turned into a total.
 **Gap:** GPU utilisation and memory are not sampled, so a device-bound verdict
 says *that* a node waits on the GPU, not whether the GPU is saturated or merely
 badly fed. That distinction needs NVML, and it is what VR-008 will want anyway.
 ## VR-008 — Gallery scaling benchmark
 Establish the throughput-versus-gallery-size curve required by A10.
@@ -1,344 +0,0 @@
 # Benchmark — SuperHero
 The reference film for end-to-end accuracy. Replaces Road to Bali, which was
 withdrawn for the reason in [Why not Road to Bali](#why-not-road-to-bali).
 TRACES: AR-011, AR-012, AR-013 | VR-001, VR-005 | SR-002
 ---
 ## The film
 SuperHero, from the [NIST TRECVID Deep Video Understanding development
 set](https://www-nlpir.nist.gov/projects/trecvid/dvu/dvu.development.dataset/).
 14 films are asserted Creative Commons and need no data agreement; only the 5
 KinoLorber test films are gated.
 | | |
 |---|---|
 | Runtime | 1025.5 s (17.1 min), 10 scenes |
 | Resolution | 640×360 |
 | Ground truth | Per-scene presence, from the scene knowledge graphs |
 | Gallery | 5 characters, 14 references |
 The DVU set is what makes this workable: it ships **character** face crops cut
 from the film itself, so ground truth and gallery are both in character space
 and scoring needs no actor→character mapping.
 **Licence caveat.** NIST links licence evidence for only 4 of the 14 films, and
 SuperHero is not one of them — its end credits carry no copyright or CC notice,
 list a "Temporary Musical Score" and a SAG cast, and it has no traceable online
 release. Fine for internal benchmarking; do not redistribute frames from it.
 Valkaama is the one film with an independently documented licence (CC BY-SA 3.0)
 if provenance ever has to be defended.
 ---
 ## Reproducing it
 ```sh
 # 1. Annotations, character mugshots, scene segmentation.
 #    NIST names the same film three different ways, hence the overrides.
 KG_DIR=superHero KG_FILE=superhero scripts/fetch_dvu.sh SuperHero ../dvu-hero
 # 2. Scene clips (movie.shots), then fuse them into one stream.
 #    Fusing matters — see "Run it as one film" below.
 #    SuperHero-1.webm … SuperHero-10.webm from
 #    <dataset>/movie.shots/, then:
 ffmpeg -f concat -safe 0 -i concat.txt -c copy SuperHero_full.webm
 # 3. Gallery, with the face-size floor that keeps references in distribution.
 ./build/build_gallery --root ../dvu-hero/root \
    --output ../dvu-hero/hero66.h5 --min-face-px 66
 # 4. Run, on the GPU path (see "Check you are on the GPU").
 ./build/scene_analyze --movie hero/SuperHero_full.webm \
    --gallery ../dvu-hero/hero66.h5 \
    --detector-engine trt_cache/scrfd.scrfd_500m_bnkps.640.fp16.engine \
    --arcface-engine  trt_cache/arcface.LVFace-B_Glint360K.b4.fp16.engine \
    --fps 5 --min-face-px 32 --expand-gallery \
    --output pred.json
 ```
 Nothing here is in git: the clips are ~130 MB and the annotations are
 regenerable. Replay fixtures derived from the run ship through the artifact
 registry instead:
 ```sh
 scripts/artifacts/push_artifacts.sh replay-fixtures
 scripts/artifacts/pull_artifacts.sh replay-fixtures [version]
 ```
 The gallery travels in the same archive as the dumps deliberately — a dump only
 replays meaningfully against the gallery it was produced with, and pairing one
 with a different gallery silently changes every identity decision in it.
 ---
 ## Results
 Measured on the fused film, gallery expansion on.
 | Metric | Value |
 |---|---|
 | Precision | **1.00** |
 | Recall | 0.65 |
 | F1 | 0.79 |
 | True positives | 13 |
 | False positives | **0** |
 | False negatives | 7 |
 Six of ten scenes scored exactly right, including the three-character scenes 4
 and 5.
 **Zero false positives is the result worth keeping.** Every out-of-gallery
 character — Beast, Mighty Celestial, Ms. Johnson, Doctor, two Masked Persons —
 was declined rather than forced onto a nearest match. That is the calibrated
 probability (AR-024) doing its job, and it is the right failure direction for an
 X-Ray overlay: a miss is a gap, an invention is a lie.
 **The misses have a shape.** Scenes 1, 2, 3 and 8 were missed, and 1–3 are the
 three shortest scenes in the film (14 s, 38 s, 27 s). That is consistent with
 per-track Bayesian accumulation (AR-025) needing enough sightings before belief
 crosses threshold. Scene 8 is 65 s and does not fit that story — it is the one
 to look at first when improving recall.
 Running the same scenes as isolated clips did *not* do better, so cross-scene
 gallery expansion is not currently compensating for short scenes.
 ### Run it as one film, not as clips
 Per-scene clips defeat per-film gallery expansion (AR-019), which grows a
 temporary gallery from track continuity across the whole film and re-assesses
 unknown tracks at the end. Ten isolated clips give it nothing to work with, and
 pay model and gallery load ten times over.
 Fusing also makes presence windows cross real scene boundaries, which is how
 SR-002's scene-scoped question is asked in production. Note the joins are
 artificial cuts — consecutive scenes were never contiguous footage — so presence
 bleeding across a boundary may be the join rather than a tracking fault.
 ---
 ## Throughput
 | Path | Realtime factor | Sampled fps | 17-min film |
 |---|---|---|---|
 | `build/` (TensorRT) | **8.25×** | 41.3 | **2.1 min** |
 | `build-ort/` (ORT) | 0.54× | 2.7 | ~32 min |
 TensorRT figure re-measured 2026-08-04 over the whole film at `--fps 5
 --min-face-px 32 --expand-gallery`: 5129 frames, 1025.4 s of film in 124.2 s
 wall. Two runs agreed to 0.4% (124.2 s clean, 124.7 s under gdb). It supersedes
 an earlier 2.0×; that figure predates the current tree and was not re-derived
 here, so treat the gain as measured rather than explained.
 Throughput varies strongly with face density, and **a short window is not a
 sample of the film**. The opening 60 s benchmarks at 23.9× — decode there costs
 4-6 ms/frame against a 12.35 ms whole-film mean (n=510), because seeking forward
 in VP8/WebM gets dearer the deeper you go, and there are few faces. Always quote
 the whole-film average.
 ### Where the time goes (VR-015)
 Measured over the whole film, 2026-08-04:
 | node | cpu_s | % of pipeline CPU | cpu/f | exec/f | stall/f | in% | out% |
 |---|---|---|---|---|---|---|---|
 | **embedder** | **91.0** | **60%** | 17.74 | 21.61 | 3.87 | 12 | 0 |
 | **face_detector** ▶ | 41.4 | 27% | 8.07 | 24.20 | **16.14** | **99** | **0** |
 | frame_source | 12.1 | 8% | 2.36 | 11.26 | 8.90 | — | 97 |
 | camera_pos | 3.2 | 2% | 0.63 | 0.64 | 0.01 | 97 | 99 |
 | face_aligner | 1.7 | 1% | 0.33 | 0.34 | 0.01 | 0 | 12 |
 | identity_matcher | 1.3 | 1% | 0.26 | 0.34 | 0.09 | 0 | 0 |
 | tracker / sink | 0.5 | <1% | — | — | — | 0 | 0 |
 **`face_detector` paces the run**: its input channel is 97.8% full while its
 output is 99.4% empty — everything upstream jammed, everything downstream
 starved. It occupies 5129 × 24.20 ms ≈ 124.1 s of a 124.2 s run, essentially
 100% wall occupancy, yet only 33% of that is CPU. The other 16.14 ms/frame is
 device wait.
 **The embedder is the larger cost but not the constraint**: 60% of all pipeline
 CPU, 73% of wall as thread-busy. Whether that is real work or a spinning
 `cudaStreamSynchronize` is unresolved — see the sync caveat below, which is a
 one-line experiment.
 **`frame_source` is the trap this table exists to defuse.** It reports
 `exec/f = 11.26 ms` against `cpu/f = 2.36 ms`, and its output channel is 97%
 full: it is backpressured, not expensive. The old KPN `ema` reading made it look
 like the most costly node in the pipeline at 141.899 ms/frame.
 `--benchmark <path>` writes a per-node timing report and prints a table at
 shutdown. `hero/run_bench.sh` is `run_trt.sh` with it switched on:
 ```bash
 ./build/scene_analyze … --benchmark $H/bench_trt.json --output $H/pred_bench.json
 ```
 **Do not read the `ema` column of the old KPN diagnostics block as a cost.** KPN
 times a node across `fire_once`, which wraps the functor *and* the push to the
 next channel, and a push parks when that channel is full (AR-004). A
 backpressured node therefore bills its waiting to itself. On this film that
 produced a genuinely inverted answer:
 ```
 │  frame_source  frames=5132  ema=141.899ms      ← reported cost
 [frame_source] decode  avg=16.6127ms  fps=60.19  ← actual decode
 ```
 The source is not expensive; it is idle, holding a frame nobody has taken yet.
 Optimising against that number means optimising the fastest node in the graph.
 The benchmark report separates the two:
 | Column | Meaning | Blind spot |
 |---|---|---|
 | `cpu_s`, `cpu%tot` | thread CPU time, and this node's share of all of it | a GPU wait looks like idleness |
 | `cpu/f` | CPU ms per frame — backpressure cannot inflate it | as above |
 | `exec/f` | wall ms per frame in the node, **including parked pushes** | overstates a blocked node |
 | `stall/f` | `exec/f − cpu/f`: parked, or waiting on a device | does not say which |
 | `in%`, `out%` | mean fill of the node's input and output channels | — |
 | `press` | `in% − out%`; **the node marked ▶ is pacing the run** | not a cost, an ordering |
 Read `press` first: work queues up in front of the bottleneck and starves
 everything after it, so the pacing node is the one with a full input and an empty
 output. Then read `cpu%run` to decide the repair — a saturated thread means the
 work itself must get cheaper, while an idle thread under pressure means the node
 is waiting on the GPU or the disk, where batch size and engine precision are the
 knobs and the C++ is not.
 Channel fills are sampled every 100 ms (`--benchmark-interval-ms`) because
 `current_fill` is instantaneous: by shutdown every channel has drained, so a
 single read at the end reports an idle pipeline no matter how congested it was.
 #### Check the GPU is not throttled before comparing anything
 **On this hardware, thermal state moves the result more than any code change
 we are likely to make.** The same binary measured **8.25× cool and 3.12× once
 heat-soaked** — a 2.6× swing — because the laptop RTX 3050 hits `SW Thermal
 Slowdown` and pins the SM clock to **210 MHz out of 2100**:
 ```
 $ nvidia-smi -q -d PERFORMANCE | grep -E "SW Power Cap|SW Thermal"
        SW Power Cap        : Active
        SW Thermal Slowdown : Active
 ```
 A number recorded without its clock state is not comparable to any other
 number, and back-to-back full-film runs guarantee the later ones are throttled.
 `run_bench.sh` now records `nvidia-smi` either side of the run into
 `bench_gpu.txt`; check it before believing a regression. Let the GPU idle back
 to full clock between measurements, and never A/B two runs across a heat-soak.
 This one cost real time here: a 2.7× "regression" was attributed to a code
 change and reverted on that basis, when the change was innocent and the GPU had
 simply warmed up between the two measurements.
 #### `cpu_s` on a GPU node is mostly spin — measured
 CUDA's default sync policy (`cudaDeviceScheduleAuto`) spin-waits before it
 yields, so `cudaStreamSynchronize` charges the *calling thread's* CPU while the
 GPU works. A GPU-bound node therefore reports a large `cpu_s` and reads as
 CPU-bound.
 `SAE_CUDA_BLOCKING_SYNC=1` switches to a blocking wait. Measured over 300 s of
 film, four cases, identical otherwise:
 | case | realtime | total CPU | embedder CPU |
 |---|---|---|---|
 | baseline | 3.29× | 103 s | 66 s |
 | **`SAE_CUDA_BLOCKING_SYNC=1`** | 3.29× | **23 s** | **4 s** |
 | `SAE_CV_THREADS=1` | 3.30× | 101 s | 66 s |
 | both | 3.29× | 25 s | 5 s |
 **94% of the embedder's CPU was spin, not work**, and 78% of the pipeline's.
 Throughput is unchanged, so this is free CPU — which matters for a service
 sharing a box (DP-003) and makes `cpu_s` mean what it says. Prefer it for any
 run where the CPU numbers are being read.
 `SAE_CV_THREADS=1` does nothing measurable: the only OpenCV-heavy node is
 `face_aligner` at 1-2% of the pipeline, so the TBB arena is not worth removing
 and `warpAffine` is not worth replacing.
 **Caveat: measured with the GPU clamped at 210 MHz** (see below). A device at
 full clock spends less time in the sync, so the absolute spin figure will fall;
 the ranking should not.
 #### `cpu_s` counts one thread — mind the TBB arena
 OpenCV 5 here is built against TBB, and every OpenCV module links it, so
 `cv::parallel_for_` dispatches onto a TBB arena of `nproc − 1` workers (19 on the
 20-core dev box; visible as `libtbb.so.12` frames in a thread dump). Since
 `CLOCK_THREAD_CPUTIME_ID` is per-thread, work a node fans out that way is billed
 to the TBB workers, **not** to the node.
 So a node using `warpAffine`, a histogram compare or a colour conversion reads
 cheaper in `cpu_s` than it really is, and the missing time appears in `stall/f`,
 where it looks identical to a GPU wait. `exec/f` does capture it — the functor
 does not return until the parallel region joins — so the tell is a node whose
 `exec/f` far exceeds its `cpu/f` **while its output channel is empty**: that is
 fan-out, not blocking.
 Worth knowing for its own sake, too: 9 KPN node threads plus 19 TBB workers plus
 the CUDA and NVDEC threads is heavy oversubscription on 20 cores.
 The JSON carries the same data plus the run's configuration, so two runs can be
 diffed directly — which is the point, when sweeping `--embed-batch`, `--fps` or
 an engine precision.
 ### Check you are on the GPU
 ORT's CUDA execution provider fails to load on this machine and **silently falls
 back to CPU**:
 ```
 Failed to load library libonnxruntime_providers_cuda.so:
  undefined symbol: cudnnGetConvolutionBackwardDataAlgorithm_v7
 ```
 That symbol was removed in cuDNN 9; the packaged ORT is built against cuDNN 8.
 ORT logs this once at startup and then runs happily on CPU, so a `build-ort`
 timing is a CPU number wearing a GPU label — a 15× error with no symptom other
 than a figure you have no baseline for. Grep the log for `Failed to load
 library` before trusting any throughput measurement.
 The TensorRT path (`build/`) needs prebuilt engines from
 `scripts/build_trt_engines.sh` and reports what it loaded:
 ```
 [TrtScrfd] loaded: … [TrtArcFace] loaded: … max_batch=4
 [similarity] cuBLAS/CUDA engine: gallery resident on GPU
 ```
 ---
 ## Why not Road to Bali
 Bali was chosen because DVU ships character mugshots for it. It was withdrawn on
 **face scale**, measured on its own reference crops:
 | | Bali | SuperHero |
 |---|---|---|
 | Median detected face | 27 px | **69 px** |
 | Maximum detected face | 69 px | **241 px** |
 | References ≥66 px | 2 of 69 | 14 of 27 |
 The DVU images are scene crops, not mugshots, so the crop dimensions say nothing
 about face scale — the face has to be detected and measured. Bali's median
 reference was being upscaled roughly 4× to reach ArcFace's 112×112, and the
 worst 7×, which violates AR-011: every model gets the input it was trained for.
 A model run off-distribution returns confident, plausible, wrong output.
 In a gallery that error is permanent. A bad frame costs one frame; a poisoned
 reference corrupts every future match against that identity.
 No threshold rescued it. At 66 px only 2 of 69 references survived — the largest
 face in the entire set is 69 px — so there was no cut that both kept references
 in distribution and left enough of them to calibrate. SuperHero's gallery builds
 at a 66 px floor and calibrates on its own (`a=15.2867 b=-4.98633`, 100 % train
 accuracy) rather than borrowing constants.
 Any accuracy figure recorded against Bali predates this and should be treated as
 measuring upscaling artifacts as much as the pipeline.
@@ -243,9 +243,7 @@ Context crops opt-in behind `--dump-unidentified-crops`.
 **Depends on:** nothing (AR-002, AR-011); AR-004 blocks AR-003.
- **AR-002** — `min_face_px` stays **40** (VR-013 measured it end to end) but must
+- **AR-002** — `min_face_px` → 66, expressed in original resolution.
  be expressed in original resolution rather than decoded-frame space. The value
  is already right in `config.hpp`; the change is the coordinate space.
 - **AR-011** — feed TransNetV2 at native rate; derive the dedup window from
  source fps rather than the hardcoded `0.04 s`.
 - **AR-004** — backpressure. `kMaxFaces` (`identity_matcher_node.hpp:133`)
@@ -255,33 +253,20 @@ Context crops opt-in behind `--dump-unidentified-crops`.
 ## AR-026, AR-027 — GEMM and scale
-**Depends on:** nothing to start. The annex CPU loop has moved into the GEMM
+**Depends on:** nothing to start. The annex CPU loop
-path: the annex is a contiguous matrix, promotions are appended to the engine's
+(`identity_matcher_node.hpp:159-162`) moves into the GEMM path.
 resident gallery, and the CPU backend now requires OpenBLAS. What is left of
 AR-026 is call site 3, the deferred pass — so the rest of AR-026 lands *with*
 AR-020 rather than before it.
 ---
 # Gallery
-## GR-004 — Model binding — **DONE**
+## GR-004 — Model binding
-**Depended on:** nothing. Landed before any measurement work, as intended.
+**Depends on:** nothing. **Startable immediately, highest value per line.**
-Stamp = model basename + SHA-256 of the ONNX, written as the `/embedder` group at
+Stamp embedder identity into the gallery at build; verify at load in
-build time (`gallery_builder.cpp`, `sae_gallery.save_gallery_hdf5`) and verified
+`scene_analyze`, `replay.py` and the optimizer. Mismatch is a hard error naming
-at load in `scene_analyze`, `scene_preview`, the `sae_kpn` matcher binding,
+both sides.
 `replay.py`, `optimize.py` and `movienet_eval.py`. Mismatch is a hard error naming
 both sides, with no bypass. Embedding dumps carry the same stamp, since a replay
 has no live embedder to check against.
 Unstamped legacy galleries **warn loudly and proceed** rather than failing:
 unknown is not known-bad, and hard-failing every pre-existing gallery would turn
 the check into something people disable. `--require-gallery-stamp` /
 `SAE_REQUIRE_GALLERY_STAMP=1` promotes that to a hard error — measurement runs
 should set it. `scripts/stamp_gallery.py` re-binds an existing gallery without
 re-embedding, so the warning state is cheap to leave.
 Cross-model similarities are meaningless but *look* plausible — this fails
 silently and expensively, and it would corrupt every measurement taken during the
@@ -329,67 +314,8 @@ Windows carry belief and route; `extraction.*` gains `extinction_sec` and
 ## VR-005 — Minimum face size study
-**Depends on:** nothing. Standalone Python, no C++ contact. **Done** — knee at
+**Depends on:** nothing. Standalone Python, no C++ contact. Produces the measured
-24–32 px. It measures the embedder with alignment held perfect, so it bounds the
+value replacing AR-002's 66 px estimate.
 answer from below rather than setting it; AR-002's floor comes from **VR-013**,
 which sweeps input resolution end to end and lands at 40 px.
 ## VR-013 — Cross-source identification probe
 **Depends on:** `sae_embed` exposing `detect()`, `align_face()`, `embed_crop()`
 and the gallery calibration — it drives the shipped C++ rather than reimplementing
 it, which is what VR-005 could not do.
 Gallery from one recording, probes from another, sweeping the probe's **input
 resolution before the detector**, so detection and landmark regression degrade
 with the frame. `experiments/xsource/`.
 **Findings.** Holding 90% of the plateau needs ~50 px end to end against VR-005's
 ~22 px; `min_face_px` 40 is right and 32 would admit faces in the falling region.
 FPI is 0.0% at every scale — resolution loss goes entirely to TBI, never to a
 wrong name. The ceiling is **cross-view, not resolution**: everyone matches
 themselves within a recording (0.55–0.85) and collapses across two (0.14–0.45),
 and only the subject with frontal *gallery* references identified reliably — so
 the lever is gallery pose coverage (`docs/pose-expansion.md`), not a better
 landmark model. Averaging SCRFD's NMS-discarded landmark estimates lifts
 cross-clip TPI 41% → 49% for one forward pass.
 **Open.** Four identities and one shoot, so the shape is the result and the
 absolute rates are not. Both clips hold all four people, so there is no
 out-of-gallery class and the 10×-weighted out-of-cast misID is untested — holding
 one identity out of the gallery would fix that.
 ## VR-014 — Audio-signature offset recovery
 **Depends on:** `sae_audio` exposing `compute_signature()` and
 `signature_from_mono()` — it drives the shipped C++, as VR-013 does, so the
 thing measured is the thing that ships.
 `scripts/validation/test_audio_offset.py` over
 `tests/fixtures/audio/superhero_offset_200s.flac`: 200 s of public-domain film audio
 (the same SuperHero clips the replay fixtures use), long enough for a 120 s
 window to slide past the ±600-frame search cap. The slide itself is numpy here
 on purpose — matching belongs to the consumer, so writing it out keeps this a
 test of the signature rather than of somebody's matcher.
 **Findings.** Alignment is a solved problem here: the offset is the nearest frame
 in every in-cap trial, worst error **46 ms against a 500 ms budget**, and 46 ms is
 the quantisation floor — offsets are whole 92.88 ms frames, so no correct answer
 can be worse. The `runtime/2` anchor's factor of two holds through real trimmed
 files, and out-of-cap offsets and unrelated content are both declined.
 **The score is where the slack is, and it costs a tier rather than accuracy.** It
 tracks sub-frame misalignment — 0.94–0.99 near a frame boundary, 0.69–0.73 at
 half a frame — so two thirds of correct alignments miss the server's 0.85 `audio`
 threshold and land in `loose`. UT-108 measures the fix rather than proposing one:
 ±1 frame of slack in the score returns all 40 to `audio` (min 0.906) with false
 matches unmoved at 0.12–0.16, costing 81 ms of the budget. See
 [`SPEC.md`](SPEC.md) IR-004 — the score is normative in the server spec, so the
 change is theirs to make.
 **Open.** One source, one language, one era of recording. The shape (offset exact,
 score set by sub-frame phase) should hold generally, but the absolute scores are
 this fixture's.
 ## VR-001 — Dump audit
@@ -29,60 +29,55 @@ Status: `Done` · `In Progress` · `Planned` · `TBD` · `Withdrawn`
 | ID | Requirement | Traces to | Priority | Status |
 |---|---|---|---|---|
 | AR-001 | Detect faces in sampled frames; emit bbox, confidence, 5-point landmarks in original pixel space | SR-002 | High | Done |
-| AR-002 | Minimum face size **40×40 px** (VR-013 measured end to end; VR-005's 32 px is an embedder-only upper bound), expressed in **original** resolution (decoupled from `dense_scale`) | SR-002 | High | **Done** — `FaceDetectorFunc::drop_undersized()`. The threshold is divided by `bbox_upscale` rather than every box multiplied, which keeps the comparison on the detector's own numbers and means turning `dense_scale` on cannot silently raise the minimum face the pipeline accepts. Verified at the threshold and at `dense_scale` 0.5 (UT-002), and end to end on the fixture (IT-001) — the superhero dump's smallest side is *exactly* its recorded 32 px, so the filter is binding there rather than vacuously satisfied |
+| AR-002 | Minimum face size 66×66 px, expressed in **original** resolution (decoupled from `dense_scale`) | SR-002 | High | Planned |
-| AR-003 | No fixed per-frame face cap — crowd scenes must not lose background cast | SR-002 | Medium | **Done** — `max_faces` defaults to 0 (no cap); the matcher batches through its GEMM buffer instead of throwing |
+| AR-003 | No fixed per-frame face cap — crowd scenes must not lose background cast | SR-002 | Medium | Planned |
-| AR-004 | Backpressure: unbounded faces/frame absorbed by slowing, never by dropping or throwing | SR-002 | High | **Mostly** — node outputs *park* on a full channel: the value is held, the worker released, and a channel space-callback resumes the node. Replaces `push_blocking`, which parked a scheduler worker inside the push and, with one thread per node, stopped that node draining its own input. Verified: 385/385 frames, 0 drops. Holes closed since, in the order they surfaced: **(a)** `FanoutNode` dropped on overflow rather than waiting, so the AR-010 scene join shed frames exactly when the dense branch fell behind — measured at **9 of 2192 items delivered** to the slower of two branches, now lossless with the fast branch throttled to within its buffering; **(b)** the residual hang, recorded as ~1 run in 20 at a 300 s timeout, was a **startup** lost wake, not a mid-stream one — `start()` enables a node's inputs several statements before it installs the push callback, and a producer firing into that gap is accepted by the ring while waking nobody, since `Channel::push` signals only the empty→non-empty edge. Signature is zero items delivered, never a partial stall. Reproduced 7 times in 24 under CPU contention and 0 in 10 without; `start()` now closes with the level-triggered `on_input_ready()`, giving 0 in 24 on the same harness — though the *cause* was narrower than recorded there and is fixed properly in **(e)**; **(c)** `FilterNode` and `RouterNode` were the last data paths still using the throwing `push()` with the exception swallowed, so a full output discarded the value — including the **EOF sentinel**. The decimator passes EOF by predicate (`if (f.eof) return true;`) but its output is reliably full, the embedder being the slowest node in the chain, so the token was discarded, nothing downstream ever shut down, and the run had to be killed. **This is the wedge.** Both now route sentinels out-of-band and retry data until taken; the regression case delivers 6 of 40 values and never sets `saw_eof` before, 40 and terminating after; **(d)** the sentinel could be delivered *ahead of* a value still queued behind it — `pop()` observed the ring empty and then took the sentinel, and a producer can push a value *and* publish the sentinel inside that window, so any consumer treating EOF as a hard stop loses the tail. `take_sentinel` now re-checks emptiness *after* observing `has_eof_`, which is sound because the sentinel is published with a release store after the ring pushes. ~1 run in 15 before, 0 in 25 after; **(e)** two `fire_once` invocations for one node could overlap, because the submit gate was released before the firing had finished touching node state. That breaks the one-slot park the whole scheme rests on — a parked value can be overwritten by the other firing, with no drop recorded anywhere. ThreadSanitizer caught it as a race on `pending_done_`; the release is now the last act of a firing. The same sweep found the callbacks themselves being written while a running neighbour read them (ten TSan races), which is the *actual* cause of the startup lost wake in **(b)** — callbacks are now installed in a `prepare()` pass before any node starts. **New constraint:** a channel carries at most **one undelivered sentinel**; a second offered before the first is taken is refused and reported, never queued and never overwritten, since two control tokens on one channel means the stream ended twice. Single-shot EOF today, live the moment a pipeline is reused for a second input. **Consequence to hold onto:** a lossless fanout makes join depth a correctness precondition — one branch can now run ahead of another only by the slower branch's buffering, so `kSceneJoinDepth` must exceed the TransNetV2 window. Making the decimator lossless also makes it a backpressure point rather than a relief valve: the source now throttles to the face branch instead of quietly thinning it. Correct under this requirement, but it changes the shape of a loaded run and is **not yet benchmarked**. **Gap:** capacity is still counted in *items*, not bytes, so a crowd frame carrying 60 crops occupies one slot exactly as an empty one does — the memory ceiling the plan asks for is unenforced |
+| AR-004 | Backpressure: unbounded faces/frame absorbed by slowing, never by dropping or throwing | SR-002 | High | Planned |
-| AR-005 | Align to 112×112 via ArcFace 5-point similarity transform, fitted by **Umeyama least squares over all five points** (as InsightFace does) — never a robust fit, which would discard the landmarks AR-030 reads | SR-002 | High | **Done** — `umeyama_similarity()`. The RANSAC fit it replaces disagreed by a median 17 source px on 400 headshots, 83.5% of crops embedding below cos 0.99, and was unstable and RNG-driven: rebuilding caught 1614 near-duplicates against the original build's ~100. **All galleries rebuilt** (2456 actors, 10254 embeddings); measured separation gain is small (0.583 → 0.590), so recorded accuracy figures should be re-run but are not expected to move far |
+| AR-005 | Align to 112×112 via ArcFace 5-point similarity transform | SR-002 | High | Done |
 | AR-006 | 512-d L2-normalised embeddings, batched | SR-002 | High | Done |
-| AR-007 | Associate detections by IoU + embedding, with **frame-dependent** weighting | SR-002 | High | **Done** — `track_alpha` is the base for ordinary frames; drops to embedding-only on cut/boundary and for dormant tracks |
+| AR-007 | Associate detections by IoU + embedding, with **frame-dependent** weighting | SR-002 | High | In Progress |
-| AR-008 | One track pool keyed on `last_seen`; no separate revival path | SR-002 | High | **Done** — one pool keyed on `last_seen`; park/revive branch deleted |
+| AR-008 | One track pool keyed on `last_seen`; no separate revival path | SR-002 | High | Planned |
 | AR-009 | Camera-cut detection (histogram) as an association hint | SR-002 | High | Done |
-| AR-010 | Scene-boundary detection (TransNetV2) as an association hint | SR-002 | Medium | **Done** — decode butterfly joined via `SceneBoundaries`; the sampled branch waits for the detector's watermark. Frames past its last scored window are counted as unverified, never assumed boundary-free |
+| AR-010 | Scene-boundary detection (TransNetV2) as an association hint | SR-002 | Medium | In Progress |
-| AR-011 | **Every model is fed the input it was trained for** — cost reduced by running less often, never by degrading one inference | SR-002 | High | **Done** — both violations SPEC.md named are closed. (1) `scene_decode_fps` defaults to 0 (native): at 12 fps a 100-frame `kWindow` spanned ~8.3 s instead of the ~4 s TransNetV2 was trained on, half-speed motion over twice its temporal context. (2) The boundary dedup window is derived from the cadence the detector was actually fed (`SceneDetectorFunc::dedup_window_sec()`, median observed interval, halved) rather than the literal 0.04 s — one frame at 25 fps, and at 30 fps wider than a frame, so two cuts on consecutive frames merged into one and the loss was invisible: the file simply had fewer boundaries. Derivation checked at 24/25/30 fps and under a seek (UT-003). **Consequence, not a gap:** `scene_threshold` 0.60 was fitted against the 12 fps input and is now certainly wrong — VR-006 re-fits it, and until then boundary recall at native rate is untuned rather than better. Dense decode is the cost driver, so this is not free; `dense_scale` and `scene_stride` remain the reductions that do not run the model off-distribution. **Half-applied until now:** the derived window reached `scenes.json` and nothing else. `SceneBoundaries` — the path that actually feeds `is_scene_boundary` to the tracker — kept the literal 0.04 s under a comment claiming the two views agreed. They did not. The detector now supplies the window it derived to both |
+| AR-011 | **Every model is fed the input it was trained for** — cost reduced by running less often, never by degrading one inference | SR-002 | High | Planned |
-| AR-012 | Presence follows **track extent**, not per-frame recognition | **SR-002** | High | **Done** — `src/track_registry.hpp`; window is `[first_seen, last_seen]` of an owned track |
+| AR-012 | Presence follows **track extent**, not per-frame recognition | **SR-002** | High | Planned |
-| AR-013 | `last_seen` optional state machine; window ends at last sighting, never after | SR-002 | High | **Done** — `last_seen` optional is the whole state machine; interior gaps absorbed, trailing cool-down never claimed |
+| AR-013 | `last_seen` optional state machine; window ends at last sighting, never after | SR-002 | High | Planned |
-| AR-014 | Belief swap A→B terminates the track and starts a new one | SR-002 | Medium | **Done** — swap closes at `last_seen` and opens a successor at the swap frame; counted |
+| AR-014 | Belief swap A→B terminates the track and starts a new one | SR-002 | Medium | Planned |
-| AR-015 | Two live tracks owned by one actor ⇒ treat as a detected cut, re-associate | SR-002 | Medium | **Done** — reverse index detects it on the causing update; counted |
+| AR-015 | Two live tracks owned by one actor ⇒ treat as a detected cut, re-associate | SR-002 | Medium | Planned |
-| AR-016 | All tracks closed at EOF — a film ends with faces on screen | SR-002 | High | **Done** — `flush()`, idempotent, closes at last sighting or final tick |
+| AR-016 | All tracks closed at EOF — a film ends with faces on screen | SR-002 | High | Planned |
-| AR-017 | Every presence claim carries its belief and identification route | SR-002 | High | **Done** — `DeadTrack` carries belief, observation count, and now a `route` enum. The route was previously the literal string `"live"` written at serialisation time, so the published field could not distinguish anything and AR-017's own edge case ("deferred and pooled routes distinguishable") was unmeetable. Only `live` occurs until AR-020 lands; `deferred` exists so that pass has somewhere to write instead of a schema change to make |
+| AR-017 | Every presence claim carries its belief and identification route | SR-002 | High | Planned |
-| AR-018 | Per-subject embedding store with banded admission (novel enough, safe enough) | SR-005 | Medium | **Done** — banded admission in probability space, bounds from `expand_band_lo/hi`; the lower bound re-asked pairwise at promotion, since `admit` compares only against the nearest member and a drifting track can chain past it. Retires `expand_novelty_sim` and `expand_track_spread_max` — novelty is now the eviction ordering, not a threshold. Rejections counted. Bounds unswept (VR-007) |
+| AR-018 | Per-subject embedding store with banded admission (novel enough, safe enough) | SR-005 | Medium | Planned |
-| AR-019 | Per-film gallery annex from owned tracks; acquires the non-frontal views TMDB lacks | SR-005 | Medium | **Done** — all three discontinuity signals clear the buffers; ownership comes from the registry, not a second local tally. **Correction:** the local tally was still there and still deciding. Promotion fired on a local accepted-frame count and fell back to a local per-actor plurality whenever the registry had not yet claimed the track — which is the common case, since three accepted frames arrive well before a posterior crosses `ownership_logodds`. So in practice the plurality usually decided, and it could not see the AR-025 discounting it was supposed to defer to. Promotion now requires the registry's verdict; the accepted-frame count is an explicit evidence floor. `forget()`, which had no callers under a comment claiming the matcher called it, is replaced by `prune_dead` against the registry's own liveness |
+| AR-019 | Per-film gallery annex from owned tracks; acquires the non-frontal views TMDB lacks | SR-005 | Medium | In Progress |
 | AR-020 | Deferred re-identification of unknown tracks against the final expanded gallery | SR-005 | High | Planned |
 | AR-021 | Cluster unknown tracks into one entity per person, under temporal cannot-link constraints | SR-005 | Medium | Planned |
 | AR-022 | Capture still-unidentified tracks: embeddings, metadata, **context crops** for human review | §4 | Medium | Planned |
-| AR-023 | Fit sigmoid calibration from intra/inter similarity distributions | SR-002 | High | **Done** — and the meaning of "the fit failed" is now uniform. `valid=false` used to send the matcher to a raw-cosine accept rule while `same_person_probability` sent every other stage to the untuned default sigmoid: one run, two policies, no announcement. Both now take the default sigmoid and warn loudly that the probabilities are not meaningful |
+| AR-023 | Fit sigmoid calibration from intra/inter similarity distributions | SR-002 | High | Done |
-| AR-024 | **Always the calibrated probability, never a raw cosine** — exceptions recorded | SR-002 | High | **Done** — association, accumulation and expansion all in probability space; `track_max_embed_dist`, `cut_revive_sim`, `expand_novelty_sim`, `expand_track_spread_max` retired. Enforcement now exists rather than being asserted: `scripts/ci/check_raw_cosine.py` blocks in CI. It immediately caught a live violation — the matcher's no-calibration fallback thresholded raw cosine distance **and fed `max(0, cosine)` into `TrackRegistry::observe`**, whose contract says in terms that it cannot be handed an uncalibrated number by a careless caller. `match_threshold`, `match_ratio` and `match_ratio_ceil` are retired with it, and `TrackGallery`'s `max(0, cosine)` default calibration is now a hard error. One exception recorded, in the calibration's own dedup |
+| AR-024 | **Always the calibrated probability, never a raw cosine** — exceptions recorded | SR-002 | High | Planned |
-| AR-025 | Per-track Bayesian accumulation in log-odds, with correlated-observation discounting | SR-002 | High | **Done** — log-odds accumulation with correlation discounting owned by the registry, `src/evidence_discount.hpp`. The four constants governing this — `ownership_logodds`, `rho_max`, `admit_below`, `max_views` — were unreachable in-class defaults until now; see VR-007 |
+| AR-025 | Per-track Bayesian accumulation in log-odds, with correlated-observation discounting | SR-002 | High | Planned |
-| AR-026 | All similarity computed as GEMM, including annex and deferred pass | SR-001 | High | **In Progress** — two of the three call sites done. Baked gallery was already GEMM; the annex now is too — it is a contiguous row-major matrix (`track_gallery.hpp`) whose promoted rows are appended to the engine's resident matrix (`ISimilarityEngine::append_rows`), so one multiply covers baked and promoted references and the host-side cosine loop is gone. CPU path requires OpenBLAS (scalar fallback now opt-in behind `SAE_ALLOW_SCALAR_GEMM`). Remaining: the deferred pass, which does not exist until AR-020 |
+| AR-026 | All similarity computed as GEMM, including annex and deferred pass | SR-001 | High | In Progress |
 | AR-027 | Throughput acceptable for **arbitrary** gallery size | SR-001 | High | Planned |
 | AR-028 | **Embedding input quality assessed and carried** — every face scored on size, sharpness and visibility before its embedding is used as identity evidence; the vector travels with the face and reaches the VR-001 dump | SR-002 | High | **Done** — filled in by `FaceAlignerFunc`, where both measured axes come free from the warp; carried on `DetectedFace` and written to the dump as `faces/sharpness` + `faces/alignment_residual`, taking it to `schema_version` 2. Size is `bbox`, not duplicated into a field that would drift. No face is admitted unscored (-1 sentinel), and the degenerate-fit case is now counted and reported rather than silently dropped. **Carried, not consumed** — no discount and no threshold, which is AR-030 and VR-012. Verified UT-137, UT-138 (aligner) and UT-139…UT-141 (dump round-trip, version, sentinel). The committed fixtures are still v1, so they carry no vector until `make_fixtures.sh` is re-run on a GPU host |
 | AR-029 | Sharpness measure on the **aligned crop** (scale-normalised, so it cannot re-measure size) | SR-002 | Medium | **Done** — `crop_sharpness()`: variance of the Laplacian over variance of the crop, so contrast cannot leak in the way it does for the raw textbook measure. Both blur ladders monotone, Gaussian and motion. Three properties recorded on the function for VR-012 rather than corrected here: the contrast invariance is exact in the algebra but bends at the 8-bit quantisation floor (a dim *and* soft crop reads sharper than it is — 148% high at σ 2.5), `BORDER_CONSTANT` fill from a frame-edge face adds a step edge, and the measure conflates focus with intrinsic texture. Verified UT-130…UT-136 |
 | AR-030 | Visibility measure from the AR-001 5-point landmarks — extreme pose or occlusion **discounts the observation, never deletes the detection** | SR-002 | Medium | **In Progress** — measure is the AR-005 alignment residual (`estimate_alignment()`), carried on `DetectedFace`; roll/scale invariance and monotonicity under foreshortening asserted. Nothing consumes it as a discount yet |
 ## Deployment (DP)
 | ID | Requirement | Traces to | Priority | Status |
 |---|---|---|---|---|
-| DP-001 | One analysis core; modes are front-ends and must not fork pipeline logic | PR-004 | High | **Done, after a repair.** `scene_preview` had forked the construction sequence and then rotted: it built `FaceTrackerFunc{cfg}` against a signature that stopped existing with the AR-007/AR-008 redesign, so **it had not compiled since**, and it never wired registry claims into its sink. It now mirrors `main.cpp` exactly — matcher, then registry, then tracker. The lesson is that "must not fork" needs the build to notice; a front-end nothing compiles is a fork that rots in silence |
+| DP-001 | One analysis core; modes are front-ends and must not fork pipeline logic | PR-004 | High | Done |
 | DP-002 | Batch CLI over one title | PR-004 | High | Done |
 | DP-003 | On-demand resident service with bounded, observable queue | PR-004 | Medium | Planned |
 | DP-004 | Opportunistic/idle mode: external trigger, hard stop, implicit re-queue | PR-004 | Medium | Planned |
 | DP-005 | Native installer, no Docker; Fedora + Arch | PR-004 | Medium | Planned |
 | DP-006 | Background incremental gallery refresh on a timer | PR-003 | Medium | Planned |
 | DP-007 | CI builder image, CPU-only, pinned by tag in the Gitea container registry | PR-004 | High | **Mostly** — image and publish script exist (`Dockerfile.builder-cpu`, `scripts/ci/build_builder_image.sh`) and `.gitea/workflows/unit-tests.yml` now consumes it, pinned to `v1` and asserting at run time that the image reports that tag. **Gap:** the image is built and pushed by hand from an authenticated host; nothing rebuilds it on a change to the Dockerfile |
 | DP-008 | Builder images + release jobs per backend (cpu / cuda / rocm); ship binaries, not engines | PR-004 | Medium | Planned |
 ## Integration (IR)
 | ID | Requirement | Traces to | Priority | Status |
 |---|---|---|---|---|
 | IR-001 | Emit the JRay truth format as sibling `.jray.json` | SR-003 | High | Done |
-| IR-002 | Windows carry belief + route; `extraction.*` carries `extinction_sec`, `gallery_scope` | SR-003 | High | **Done** — `schema_version: 2`; windows are objects with `belief` + `route`; `extraction.*` carries `extinction_sec` and `gallery_scope`; `anneal_sec` removed |
+| IR-002 | Windows carry belief + route; `extraction.*` carries `extinction_sec`, `gallery_scope` | SR-003 | High | Planned |
-| IR-003 | Output written **after** the deferred pass, not at EOF | SR-003 | High | **In Progress** — sink builds windows from registry claims and flushes at EOF; the deferred pass (AR-020) does not exist yet, so output is still final at EOF |
+| IR-003 | Output written **after** the deferred pass, not at EOF | SR-003 | High | Planned |
-| IR-004 | Compute the audio signature exactly per server spec §3 | SR-003 | Medium | **Done** — `src/audio_signature.*`; not yet emitted into the truth file (IR-002). One real defect found and fixed since: the resampler's `AVChannelLayout`s were not zero-initialised, and `av_channel_layout_copy` uninitialises its destination first, so `av_freep` was handed stack garbage. It aborted about 1 run in 4 of UT-103 — invisible in the aggregate test binary, where the case usually passes, and absent under a sanitizer build because it is stack-dependent. `ctest`, one process per case, is what turned it into a reproducible failure |
+| IR-004 | Compute the audio signature exactly per server spec §3 | SR-003 | Medium | Planned |
-| IR-005 | Golden-vector fixture shared with the plugin repo to prove bit-exactness | SR-003 | High | **Done** — `tests/fixtures/audio/`; v1 parameters now normative in server spec §3 |
+| IR-005 | Golden-vector fixture shared with the plugin repo to prove bit-exactness | SR-003 | High | Planned |
-| IR-007 | Media < 120 s: emit no signature, apply no sync offset — identical rule in both producers | SR-003 | Low | **Done** |
+| IR-007 | Media < 120 s: emit no signature, apply no sync offset — identical rule in both producers | SR-003 | Low | Planned |
-| IR-008 | Emit and honour the signature's own `v1:` version prefix | SR-003 | Low | **Done** |
+| IR-008 | Emit and honour the signature's own `v1:` version prefix | SR-003 | Low | Planned |
 | IR-006 | Jellyfin round-trip: pull pending queue, push complete results only | SR-001 | High | Done |
 ## Gallery (GR)
@@ -91,8 +86,8 @@ Status: `Done` · `In Progress` · `Planned` · `TBD` · `Withdrawn`
 |---|---|---|---|---|
 | GR-001 | Build gallery from Jellyfin library cast, TMDB profile fallback | SR-001, SR-005 | High | Done |
 | GR-002 | Incremental `--merge` refresh without re-embedding known actors | PR-003 | High | Done |
-| GR-003 | Report coverage: zero-image actors, under-referenced actors, dedup, calibration PDFs | SR-001 | Medium | **Done** — `gallery/gallery_report.hpp`, written next to the gallery by `build_gallery`. Zero-usable-image actors come from the build audit, which a stored gallery cannot reconstruct; also `distinct_references`, `duplicates_removed`, and the intra/inter distributions the calibration fits and would otherwise discard |
+| GR-003 | Report coverage: zero-image actors, under-referenced actors, dedup, calibration PDFs | SR-001 | Medium | Planned |
-| GR-004 | Stamp embedder identity into the gallery; **hard startup error** on mismatch | SR-001 | High | **Done** — basename + SHA-256 + `embed_dim`; mismatch fatal with no bypass, unstamped warns unless `--require-gallery-stamp`; `scripts/stamp_gallery.py` migrates in place |
+| GR-004 | Stamp embedder identity into the gallery; **hard startup error** on mismatch | SR-001 | High | Planned |
 | GR-005 | Gallery data never leaves the instance | **SR-005** | High | Done |
 | GR-006 | Provenance tiers: baked / harvested / confirmed, distinguishable per embedding | SR-005 | High | Planned |
 | GR-007 | Persist harvested embeddings **flagged and reviewable**, never silently equal to baked | SR-005 | Medium | Planned |
@@ -104,22 +99,14 @@ Status: `Done` · `In Progress` · `Planned` · `TBD` · `Withdrawn`
 | ID | Requirement | Traces to | Priority | Status |
 |---|---|---|---|---|
 | VR-001 | HDF5 post-inference dump at the embedded-frame boundary | PR-002 | High | Done |
-| VR-002 | Replay drives the **real** KPN nodes, not a reimplementation | PR-002 | High | **Done** — including the sink, as of VR-011. Worth recording what the reimplementation was hiding: `build_minimal` rebuilt windows in Python from per-frame annotations, which never consult the registry, so it kept producing plausible output while registry-based presence in replay was returning **nothing at all**. The first run of the real chain emitted 0 actors on a film where 1647 frames carried an identified face. A reimplementation does not merely risk disagreeing with the pipeline; it can conceal the pipeline being broken |
+| VR-002 | Replay drives the **real** KPN nodes, not a reimplementation | PR-002 | High | Done |
 | VR-003 | Scoring: micro-F1 against X-Ray, precision/recall logged at every evaluation | PR-002 | High | Done |
 | VR-004 | Reproducible validation corpus with ground truth | PR-002 | High | Done |
-| VR-005 | Minimum face size study — TPI/FPI vs probe size, gallery held at native res | PR-002 | Medium | **Done** — knee at 24–32 px; 32 px gives 98.1% TPI, 0.0 FPI at every size. Degrades an already-aligned 112×112 crop, so it isolates the embedder and is an **upper bound**; VR-013 measures the same question end to end and AR-002 takes its number, not this one |
+| VR-005 | Minimum face size study — TPI/FPI vs probe size, gallery held at native res | PR-002 | Medium | Planned |
-| VR-006 | Re-tune `scene_threshold` once native-rate decode lands | PR-002 | **Medium** | **Planned, now unblocked** — native-rate decode landed with AR-011, so the prerequisite is met and the current 0.60 is a value fitted against input the pipeline no longer produces. Raised from Low for that reason: it is no longer a refinement, it is a stale constant |
+| VR-006 | Re-tune `scene_threshold` once native-rate decode lands | PR-002 | Low | Planned |
-| VR-007 | Expansion band, clustering threshold, deferred-pass ablation, **and the AR-025 accumulation knobs** | PR-002 | Medium | **Planned — scope corrected.** `rho_max`'s own comment already deferred to this row, and four constants it names were unreachable: `ownership_logodds` on `TrackRegistry::Config`, and `max_views`/`admit_below`/`rho_max` on `EvidenceDiscounter::Config`, which `main` built through the one-argument constructor. No sweep could vary them. They are in `Config` with CLI flags now, so this row can be run. `ownership_logodds` is the one to start with: below it a track makes **no presence claim at all**, so it decides whether an actor is reported rather than how confidently |
+| VR-007 | Expansion band, clustering threshold, and deferred-pass ablation | PR-002 | Medium | Planned |
 | VR-008 | Gallery scaling benchmark — throughput vs gallery size | PR-002 | Medium | Planned |
 | VR-009 | Verify accumulated posteriors are calibrated against held-out tracks | PR-002 | High | Planned |
 | VR-010 | Dump provenance attributes — embedder model, detector settings, `dense_scale`, `scene_detect`, sample rate | PR-002 | **High** | **Done** — `DumpProvenance` in `embedding_dump_node.hpp`, written as root attributes and read back tolerantly. Every field is optional so a pre-VR-010 dump reads as *unknown* rather than as a default; a silently-defaulted `detector_conf` is exactly the fabricated provenance this exists to prevent. This row said `Planned` while five VR-010 tags sat in the code — stale in the opposite direction to the rest of this register |
 | VR-011 | Rewrite the replay harness for the post-AR-012 output contract | PR-002 | High | **Done** — `sae_kpn` compiles again and the replay drives the whole chain including `ResultSinkFunc`, so presence comes from `TrackRegistry` claims rather than being rebuilt in Python. The three per-node factories are replaced by one `add_pipeline` that mirrors `main.cpp`'s construction order — the ordering constraint (matcher fits the calibration, registry needs a discounter from it, tracker needs both, sink needs the claims) is what a factory-per-node API could not express, and is why the tracker factory kept building `FaceTrackerFunc{cfg}` against a signature that had stopped existing. `build_minimal` and `anneal_sec` are gone. Verified end to end on the SuperHero fixture: 5 actors, 32 windows, 0 dropped votes |
 | VR-012 | Quality-knee study — TPI/FPI vs sharpness and vs pose, as VR-005 did for size; also settles whether the 5-point pose proxy needs a dedicated landmark model | PR-002 | Medium | Planned |
 | VR-014 | Audio-signature **offset recovery on real content** — a known trim recovered from film audio, not from the synthetic golden tone | PR-002 | Medium | **Done** — 40 random in-cap offsets, every one recovered to the nearest frame: **worst error 46 ms against a 500 ms budget**, and 46 ms is the floor rather than a result, since the offset is quantised to whole 92.88 ms frames. The `runtime/2` anchor confirmed through real head-trimmed files (a `delta` trim moves the window by `delta/2`). The one soft spot is **tier labelling, not accuracy**: the score falls with sub-frame misalignment (0.94–0.99 near a frame boundary, 0.69–0.73 at half a frame), so 27/40 correct alignments were demoted to `loose`. ±1 frame of slack in the *score* fixes it — measured, all 40 back to `audio` (min 0.906), false matches unmoved at 0.12–0.16, costing 81 ms of the budget |
 | VR-015 | Per-node cost and bottleneck attribution for a run — where the time actually goes | PR-004 | High | **Done** — `--benchmark <path>` on `scene_analyze`; `src/benchmark.hpp`. Reports cumulative CPU and wall time per node, and locates the pacing node from sampled channel occupancy rather than from time-in-node, which backpressure inflates. Verified UT-120…UT-124 |
 | VR-013 | Cross-source identification probe — gallery from one recording, probes from another, swept over input resolution end to end | PR-002 | Medium | **In Progress** — holding 90% of the plateau needs ~50 px end to end against VR-005's ~22 px, the gap being detection and landmark error; **`min_face_px` 40, since 32 admits faces in the falling region** (AR-002). FPI 0.0% at every scale. Ceiling is cross-view, not resolution |
 | VR-016 | **Cut-detection cadence study** — is `cut_threshold` 0.70 meaningful at the rate `camera_pos` is actually fed? | PR-002 | Medium | **Planned.** The histogram cut detector is the one always-on signal with no recorded provenance, and its input rate is not the rate it was fitted at. With `--scene-detect` off, `camera_pos` sits downstream of a source already decimated to `sample_fps`, so at the 1.0 default it compares frames **one second apart** — inside a single shot those differ enormously, and 0.70 correlation is a low bar to clear. With `--scene-detect` on it sees native-rate frames instead, so the same constant means two different things depending on an unrelated flag. This is AR-011's argument ("every model gets the input it was trained for") applied to a non-neural detector, and it matters because `is_cut` drives `track_alpha` to 0 and clears every expansion buffer. Cheap first measurement: run `camera_pos` over a `hero/` clip at 1/2/5 fps and compare cut counts against `tests/fixtures/dumps/scene_bounds.json`. The committed 5 fps dump shows 2.6% of frames flagged; nobody has measured 1 fps |
 | VR-017 | **Vote-lag study** — how often does the matcher fall more than `track_extinction_sec` behind the tracker on real content? | PR-002 | **High** | **Planned.** Channel depth is a correctness parameter between `face_tracker` and `identity_matcher`, and the constraint runs opposite to the scene join's: there `kSceneJoinDepth` must EXCEED the TransNetV2 window, here the depth must be UNDER `track_extinction_sec × sample_fps`. Backpressure is what makes it bite — it is working, and a lossless channel converts depth into lag by design. Both nodes are 16 deep in `main.cpp`, which at the default `sample_fps` 1.0 is ~16 s of lag against a 5 s window, so `scene_analyze` can drop identity votes and until now said nothing. It now reports `dropped_votes` at shutdown; this row is the measurement that decides whether that should be fatal, and whether the right fix is bounding the depth or removing the coupling (reap on the matcher's clock rather than the tracker's, so a vote cannot be late by construction) |
 ---
@@ -133,62 +120,21 @@ Four tiers, in decreasing order of preference:
 | Tier | Runs in CI | What it covers |
 |---|---|---|
-| **T1 — Functor unit** | Yes | A KPN node's `operator()` driven directly with hand-built inputs |
+| **T1 — CPU unit** | Yes | Pure logic: registry state machine, belief accumulation, clustering, band admission, calibration maths |
-| **T2 — Replay** | Yes | The composed pipeline driven from an HDF5 fixture — no GPU, no video |
+| **T2 — Replay** | Yes | Real pipeline nodes driven from an HDF5 fixture — no GPU, no video |
 | **T3 — CPU inference** | Yes, slowly | ORT CPU provider over a handful of frames; smoke tests only |
 | **T4 — GPU** | **No** | Throughput, TRT engines, large-gallery GEMM |
-### T1 is the primary tier, and KPN is why
+**T2 is the reason this is workable.** The HDF5 dump (VR-001) captures state
 after decode → detect → align → embed and before tracking and matching, so
 everything downstream — which is where nearly all of the new design lives — is
 cheap CPU maths replayable from a fixture. Tracking, presence windows, belief
 accumulation, expansion, deferred re-identification and clustering are all
 verifiable on an N100 at full fidelity, not in miniature.
-**Node functors are plain callable structs, constructed independently of the
+That was already true for the optimizer. It now doubles as the CI strategy, which
-network that wraps them** (`main.cpp:186-207` builds them as stack objects;
+is a strong argument for keeping the dump schema honest (VR-001) and for the
-`ObjectNode` merely adapts them). So a node is testable by constructing it and
+replay driving the *real* nodes rather than a reimplementation (VR-002).
 calling `operator()` — no channels, no threads, no network, no fixture.
 This is already the established pattern, not a proposal:
 `tests/test_face_tracker.cpp` "drives the node's `operator()` with hand-built
 `EmbeddedSceneFrame`s and inspects the emitted `track_ids`", and does so
 "pure, GPU-free, model-free".
 The consequence is that most of the redesign is verifiable **without any
 fixture at all**: construct exactly the awkward state — a belief swap, two live
 tracks converging on one actor, a film ending mid-track, a gap one frame under
 the timeout — rather than hunting for a clip that happens to exhibit it.
 Four hazards this removes outright:
 - **No fixture-provenance risk** for these tests — the inputs are synthetic and
  explicit.
 - **No "fixture must be replayed from frame 0"** concern — state is constructed
  directly.
 - **No cross-test state leakage** (e.g. a tracker's `next_id_` persisting) — each
  test constructs a fresh functor.
 - **No replay-harness nondeterminism** — no channels, so no EOF-tail heuristics
  or silent drops.
 It also means **a dead upstream producer does not block testing a downstream
 consumer.** `is_scene_boundary` currently has no producer (see AR-010), which
 would make a *replay* test of the frame-dependent `track_alpha` pass vacuously —
 but a T1 test simply constructs a frame with `is_scene_boundary = true` and
 asserts the weighting changes. The producer gap is a pipeline defect to fix, not
 a verification blocker.
 ### T2 covers what T1 cannot
 Replay remains necessary for **composition** — that the nodes wired together
 behave as the sum of their parts — and for realistic data at scale, which
 synthetic inputs cannot honestly imitate. It is the tier that would catch a
 wiring error, a channel-capacity problem, or an ordering assumption that only
 appears under concurrency.
 The HDF5 dump (VR-001) captures state after decode → detect → align → embed, so
 replay needs no GPU and no video. That was built for the optimizer; it doubles as
 CI, which is a strong argument for keeping the schema honest and for replay
 driving the *real* nodes rather than a reimplementation (VR-002).
 **Fixtures and studies are generated locally**, on the development machine where
 the models, galleries and media already exist. CI consumes them; it never
 produces them.
 **Small committed fixtures are required.** A few HDF5 dumps covering the awkward
 cases — a cut, a belief swap, two live tracks converging, a film ending
@@ -216,54 +162,12 @@ as such rather than counted as covered.
 | GR-001 … GR-005 | T1 + T3 | Gallery assembly is I/O and bookkeeping; embedding is T3 smoke |
 | GR-006 … GR-008 | T1 | Tiering and outlier detection operate on stored embeddings |
 | VR-* | Out of CI | Studies are run deliberately and their results committed as documents |
 | VR-014 | **T2** | The exception, and the reason the blanket row above is not the whole story: its fixture is committed and its signature is CPU-only DSP, so the study *is* a test a CI host can run — not a measurement someone has to remember to repeat |
 **One consequence worth stating:** AR-027 (arbitrary gallery scale) is
 structurally unverifiable on the CI host. It needs a GPU host and a synthetic
 large gallery, so it is the requirement most likely to silently regress. Its
 benchmark (VR-008) should run on a schedule rather than on demand.
 ### CI never calls a model
 **Not "should not" — cannot.** The N100 has no GPU, and even the ONNX Runtime CPU
 provider is impractical: a measured run of the embedder on this hardware sits at
 ~930 ms per frame, so a 77 s clip at 5 fps would take roughly six minutes of
 inference alone. Every model invocation therefore happens **locally, ahead of
 time**, and CI consumes the result as data.
 This is what makes the T1/T2 split load-bearing rather than a preference: T1 and
 T2 are the only tiers that can exist in CI at all.
 ### Fixture corpus — `hero/`
 Five clips of **SuperHero (1952)**, ~77 s each, 480×360, 30 fps, 42 MB total.
 Public domain, and that is the reason to use it rather than a convenience:
 **derived fixtures — dumps, crops, golden outputs — can be committed without the
 rights question that rules out sharing gallery data (SR-005).** A fixture cut
 from a copyrighted title could not live in the repository at all.
 Two properties to design around rather than discover:
 - **480×360 means small faces.** At this resolution a face is often 40–80 px, so
  the AR-002 minimum of 40 px (original resolution) sits at the very bottom of
  that range: the filter is close to binding, and anything shot wider is lost.
  Fixture generation must set `--min-face-px` explicitly and record it, or the
  dumps will be sparse for reasons unrelated to what is being tested.
 - **77 s is short.** At 1 fps that is 77 frames — too thin to exercise an
  extinction window measured in tens of seconds. Generate at 5 fps (≈385 frames,
  ~1 MB) and record the rate in provenance, since the behaviour under test
  changes with it.
 > **AR-004 blocks reproducible fixture generation.** A trial run of one clip
 > produced 49 frames of an expected ~385, ending at 51 s of 77 s, with the
 > diagnostics reporting 285 frames dropped at `camera_pos` and 51 at
 > `face_aligner`. Channels overflow and **drop** rather than blocking, and what
 > gets dropped depends on timing — so the same command run twice can produce
 > different dumps. Golden fixtures cannot be built on that. AR-004 is therefore
 > a prerequisite for VR-001 fixtures, not merely a throughput concern for crowd
 > scenes.
 ### Fixtures — precomputed inference, pulled by CI
 The N100 cannot run inference at any useful rate, so **inference output is
@@ -272,29 +176,16 @@ what looks like GPU work into pure CPU replay.
 | Fixture | Contents | Size | Storage |
 |---|---|---|---|
-| **Edge-case dumps** | ~6 short clips (30–60 s), one per awkward behaviour | ~0.1–1 MB each | **Committed in-repo** |
+| **Edge-case dumps** | ~6 short clips (30–60 s), one per awkward behaviour | ~1 MB each | **Committed in-repo** |
-| **Corpus dumps** | Full-length titles from the validation corpus | ~21–38 MB each | **Gitea package registry**, pinned by version + checksum |
+| **Corpus dumps** | Full-length titles from the validation corpus | ~30 MB each | Pinned artifact, fetched by checksum |
 | **Synthetic gallery** | Random unit-norm embeddings, fixed seed | small | Generated at test time |
 | **Golden truth files** | Expected output for each edge-case dump | KB | Committed |
-| **Audio golden vectors** | FLAC + expected signature + parameter contract | ~600 KB | Committed, **shared with the plugin repo** |
+| **Audio golden vectors** | Short WAV + expected signature | KB | Committed, **shared with the plugin repo** |
 Edge-case dumps are small enough to commit, and being in-repo means they version
-with the code that reads them.
+with the code that reads them. Corpus dumps are pulled by pinned checksum from
-
+the artifact store rather than committed, since they are large and change only
-**Corpus dumps go to the Gitea package registry, not Git LFS.** Both are
+when the dump schema does.
 available — the models already use LFS — but their fetch semantics differ in a
 way that matters here. LFS objects are pulled on clone unless a developer
 explicitly skips them, so ~38 MB per title behind LFS taxes everyone who clones,
 forever, for data that only CI and the optimizer ever read. Registry artifacts
 are fetched on demand by the job that needs them.
 Rule of thumb: **LFS for what the build needs; the package registry for what a
 particular job needs.** Models are the former; corpus dumps and the CI image
 (DP-007) are the latter.
 Pin by version and verify by checksum on fetch. A fixture that changes silently
 under CI is worse than a missing one, because the failure presents as a code
 regression.
 **Generation must be reproducible and versioned.** A script, run on a GPU host,
 regenerates every fixture from source clips; it is re-run when the VR-001 schema
@@ -313,10 +204,10 @@ because it will be trusted.
 | ID | Tier | Test asserts | Edge cases to cover |
 |---|---|---|---|
 | AR-001 | T3 | Detector returns plausible boxes on a known frame | — smoke only |
-| AR-002 | T2 | Faces below 40 px (original res) are dropped | Exactly at threshold; with `dense_scale` 0.5 — the interaction that motivated the requirement |
+| AR-002 | T2 | Faces below 66 px (original res) are dropped | Exactly at threshold; with `dense_scale` 0.5 — the interaction that motivated the requirement |
 | AR-003 | T2 | No cap applied; a 40-face frame yields 40 | Crowd frame |
-| AR-004 | T1 | Saturated input blocks rather than drops or throws | Bounded queue at capacity; **byte-based** limit with large crops; SIGTERM mid-block. Cases the KPN suite now pins, each of which failed before being written: a fanout feeding an unequal pair loses nothing *and* throttles the fast branch (either assertion alone passes on a broken implementation); a filter delivers EOF into a saturated output; a sentinel is never delivered ahead of a queued value; a twice-parked value keeps its payload; and a node started with data already in its input still fires — the startup lost wake, which needs no contention to reproduce once the state is constructed directly |
+| AR-004 | T1 | Saturated input blocks rather than drops or throws | Bounded queue at capacity; **byte-based** limit with large crops; SIGTERM mid-block |
-| AR-005 | T1 | Known landmarks → expected 112×112 warp; the fit never mirrors | Landmarks near frame edge; degenerate/collinear points; a mirrored set — SVD returns a reflection unless the determinant guard rejects it |
+| AR-005 | T1 | Known landmarks → expected 112×112 warp | Landmarks near frame edge; degenerate/collinear points |
 | AR-006 | T3 | Embeddings are unit-norm | Batch smaller than, equal to, larger than `embed_batch_size` |
 | AR-007 | T2 | Association picks the right track | Two faces crossing paths; one leaving frame as another enters |
 | AR-008 | T2 | One pool; dormant tracks match on embedding, not IoU | Dormant track whose old bbox overlaps a *different* new face — must not match on position |
@@ -327,32 +218,21 @@ because it will be trusted.
 | AR-014 | T2 | Belief swap closes one window, opens another | No blended window; no overlap at the swap frame |
 | AR-015 | T2 | Two live tracks on one actor trigger re-association | Counter increments |
 | AR-016 | **T2** | Every track closed at EOF | Film ending mid-shot — window ends at final frame, not dropped |
-| AR-017 | T1 | Claim carries posterior and route | Deferred and pooled routes distinguishable — now possible: `route` is an enum on `DeadTrack` rather than the literal `"live"` the sink used to write. Only `live` occurs until AR-020 exists, so the test that matters today is that the field survives serialisation |
+| AR-017 | T1 | Claim carries posterior and route | Deferred and pooled routes distinguishable |
 | AR-018 | T1 | Band admits only within bounds | At each bound exactly; store never admits below lower bound |
 | AR-019 | T2 | Promotion only when all three signals quiet | Cut mid-track blocks promotion |
 | AR-020 | **T2** | Unknown resolved after expansion | Track failing at minute 12, resolved at EOF — the ordering-independence claim |
 | AR-021 | T2 | Clustering merges same person, respects cannot-link | **Temporally overlapping tracks never merge**; measure how many merges the constraint rejects |
 | AR-022 | T1 | Context crops retained, bounded per track | Track running for minutes |
-| AR-023 | T1 | Sigmoid fit on synthetic separable data | Too few positive pairs → `valid=false`, and the fallback that engages is the **default sigmoid**, not the retired cosine rule. Assert the warning fires: an unfitted sigmoid returns plausible-looking probabilities, so nothing downstream can tell |
+| AR-023 | T1 | Sigmoid fit on synthetic separable data | Too few positive pairs → `valid=false`, fallback engages |
-| AR-024 | **Static check** | No bare cosine outside a tagged `EXCEPTION` | `scripts/ci/check_raw_cosine.py`, blocking in the traceability workflow. Honest about its reach: it catches direct `cosine_similarity()` uses not routed through a calibration and **cannot follow a cosine through a variable across statements**, which is a convention backed by review rather than by the tool. Scans `src` only — a test legitimately asserts properties of the metric space, and sweeping those in would produce blanket exceptions that devalue the tag |
+| AR-024 | **Static check** | No bare cosine outside a tagged `EXCEPTION` | Grep-based; this is the invariant's enforcement |
 | AR-025 | T1 | Log-odds accumulate; correlated frames discounted | 30 identical frames must **not** reach the certainty of 30 diverse ones |
 | AR-026 | T1 + T4 | GEMM path produces same result as reference loop | Equivalence on small input in CI; throughput on GPU host |
 | AR-027 | **T4** | Throughput at 10²…10⁵ actors | Scheduled, not on-demand |
 | AR-028 | **T2** | No embedding reaches the matcher unscored; the vector survives into the dump | Face failing exactly one axis; all three healthy; a face whose landmarks are degenerate — dropped for want of a crop to score, but **counted** rather than silently vanished (UT-138) |
 | AR-029 | T1 | Synthetic blur ladder → monotonically falling sharpness | Gaussian vs motion blur; **small sharp face vs large soft one** — size must not leak into this axis. The blur ladder must be measured on a **1/f texture**: on a flat-spectrum one the motion ladder *rises*, since an anisotropic smear takes energy out of numerator and denominator together (UT-131). Contrast must not leak either — exact in the algebra, and the 8-bit floor that bends it is pinned by UT-133 |
 | AR-030 | T1 | Alignment residual rises monotonically with foreshortening | **In-plane roll, scale and translation must leave it at zero** — the property that makes it a pose measure rather than a pose-and-everything-else measure; face size must not shift it; degenerate landmarks report not-ok rather than a number |
 | VR-012 | **T4** | Knee located per axis on held-out films | Report each candidate threshold's cost in **lost true presence**, not only its gain in precision — a gate that improves misID by discarding half the cast has not helped |
 | VR-013 | **T4** | Identification holds across two recordings of the same people, and degrades to TBI rather than to a wrong name as input resolution falls | Gallery and probes must come from *different* recordings — a hold-one-out over one recording measures a much easier problem and will not surface the cross-view failure. Ground truth is hand-sorted; labels propagated by embedding similarity would keep only the faces the embedder already gets right |
 | VR-016 | **T2** | Cut rate as a function of the cadence `camera_pos` is fed | Same clip at 1/2/5 fps, `--scene-detect` on and off. The dump already records `cut_threshold` and `sample_fps` (VR-010), so a replay can score this without re-decoding. A finding of "0.70 is fine at every rate" is a real result and should be recorded as one |
 | IR-001/002 | T1 | Serialised output matches golden file | Zero-length window; actor with many windows |
 | IR-003 | T1 | Output written after deferred pass | Not at EOF |
-| IR-004/005 | **T1** | Signature matches golden vector bit-for-bit | Identical result in both producer repos |
+| IR-004/005 | **T1** | Signature matches golden vector bit-for-bit | **Media < 120 s → no signature**; identical result in both repos |
-| VR-014 | **T2** | A known trim offset is recovered from **real film audio**, to the nearest frame | An offset past the ±600-frame cap and unrelated content must both be *declined*, never given a best-effort alignment. Fixture and signature are both CPU-only, so unlike the other VR rows this one is CI-*executable* — though the repo's only workflow today is the traceability gate, so nothing runs it there yet. The signature comes from the shipped C++ through `sae_audio`; a numpy port would be a third implementation nobody checks against the golden vector |
+| GR-004 | T1 | Mismatched embedder → hard startup error | Error names both sides |
 | IR-006 | T1 + manual | Queue pull and result push against a stubbed Jellyfin API | Partial result never pushed; push only after the deferred pass |
 | IR-007 | **T1** | Media < 120 s emits no signature at all | Exactly 120 s; just under; zero-length audio. Must match the plugin's cutoff exactly — a caller-varying window length is what SR-004 forbids |
 | IR-008 | T1 | `v1:` prefix emitted and honoured on read | Unknown prefix rejected, not guessed |
 | GR-009 | T1 | Human-confirmed associations persist and are tier-tagged | Survives a gallery rebuild; distinguishable from baked and harvested |
 | GR-004 | T1 | Mismatched embedder → hard startup error | Error names both sides; **unstamped warns, and errors under `SAE_REQUIRE_GALLERY_STAMP`**; same filename + different SHA-256 must still be a mismatch |
 | GR-008 | T1 | Outlier flagged among an actor's references | Injected poisoned embedding detected |
 | VR-009 | T1 | Posterior calibration holds | A 0.99 posterior is wrong ~1% of the time on held-out tracks |
@@ -372,29 +252,8 @@ accumulation from being decoration.
 | — | `anneal_sec` window merging | Superseded by AR-012/AR-013: a track survives its own gaps, so there is nothing to anneal |
 | — | `extinction_sec` actor keep-alive | Superseded by AR-013: windows end at last sighting, which is what this over-claimed |
-Both are now deleted rather than retained at zero — a field naming a mechanism
+Both were deleted rather than retained at zero — a field naming a mechanism the
-the pipeline no longer has is actively misleading (see `SPEC.md` A6.6).
+pipeline no longer has is actively misleading (see `SPEC.md` A6.6).
 **This paragraph was false for some time, and the failure is worth keeping.** It
 was written in the present perfect as though the removal had happened. It had
 not: `Config::extinction_sec` (57.4) and `Config::anneal_sec` (35.5) were still
 there, `--extinction` and `--anneal` still parsed, and `SceneTrackerFunc` still
 ran its keep-alive in both shipped pipelines, printing its timeout at every
 startup. `SPEC.md`'s removal list ends "grep for both names and expect no
 survivors"; there were about forty.
 Nothing in the tooling could have caught it. The traceability gate reads tags,
 not behaviour, and a withdrawn requirement has no tag to be orphaned — the
 register simply asserted a state of the code, and no test asked. The general
 form is worth stating: **a status column is a claim, and the only claims this
 project can check automatically are the ones a test or a static check makes.**
 The same pattern produced three other rows corrected in this pass (AR-011,
 AR-017, AR-019), each recorded as done and done in one place out of two.
 `SceneTrackerFunc` is replaced by the stateless `FrameAnnotationFunc`. One
 visible consequence: `--verbosity standard`'s `frames[].identified` used to
 include every actor inside the keep-alive window, and now lists what was matched
 in that frame. Minimal and xray output never consulted the node.
 ---
@@ -11,17 +11,6 @@ manifests/
 trajectories/
 results/
 # Cross-source identification study: source clips and the hand-sorted face
 # crops. The sorting is human ground truth and expensive to redo, so it goes to
 # the artifact registry rather than being regenerated — push it once sorted.
 xsource/clips/
 xsource/labelling/
 xsource/frames/
 xsource/cache/
 xsource/results_*.json
 xsource/failure_analysis.json
 xsource/*.jpg
 # Raw run logs and scratch scripts (regenerated by every run).
 _scratch/
@@ -1,54 +0,0 @@
 #!/usr/bin/env bash
 # Fresh LVFace-B embedding dumps (HDF5) for all 9 X-Ray films with the current
 # feature/opencv5 build, for the flood-fill GA optimisation. Plain front-half
 # (decode -> campos -> detect -> align -> embed); no scene detection (histogram
 # cuts is_cut are baked in for flood-fill). Hardware VAAPI decode, no MIGraphX,
 # no crash. Serial -- ROCm GPU wedges at concurrency>2-3.
 set -uo pipefail
 REPO="/home/dtourolle/Development/scene-actor-extraction"
 cd "$REPO"
 ARC="models/LVFace-B_Glint360K.onnx"
 BIN="build/dump_embeddings"
 LUT="experiments/file-lut.json"
 FILMS="experiments/manifests/films.json"
 OUT="experiments/dumps/LVFace-B_Glint360K_opencv5"
 mkdir -p "$OUT"
 # Persist MIOpen tuning so SCRFD/ArcFace kernel search is paid once, not per film.
 export MIOPEN_USER_DB_PATH="$HOME/.cache/miopen-sae"
 export MIOPEN_FIND_MODE=NORMAL
 mkdir -p "$MIOPEN_USER_DB_PATH"
 mapfile -t SLUGS < <(python3 -c 'import json;[print(f["slug"]) for f in json.load(open("'"$FILMS"'"))]')
 echo "=== LVFace-B dumps (feature/opencv5) — $(date) ===" | tee "$OUT/dump.log"
 for slug in "${SLUGS[@]}"; do
    movie="$(python3 -c 'import json;print(json.load(open("'"$LUT"'"))["'"$slug"'"])')"
    out="$OUT/dump_${slug}.h5"
    echo "" | tee -a "$OUT/dump.log"
    echo ">>> $slug" | tee -a "$OUT/dump.log"
    if [ -f "$out" ]; then echo "  exists, skip" | tee -a "$OUT/dump.log"; continue; fi
    if [ ! -f "$movie" ]; then echo "  SKIP missing: $movie" | tee -a "$OUT/dump.log"; continue; fi
    # No --max-decode-fps cap: that cap existed only to stop LVFace dump truncation
    # under PARALLEL load (3 concurrent dumps). This runner is serial, so the cap
    # just halved throughput for nothing — measured 54s vs 27s per 300s of film,
    # identical face counts. Uncapped ~9 min/film vs ~18 min capped.
    "$BIN" --movie "$movie" --arcface "$ARC" --out "$out" --fps 1 \
        >"$OUT/${slug}.log" 2>&1
    rc=$?
    if [ $rc -ne 0 ] || [ ! -f "$out" ]; then
        echo "  DUMP FAILED (rc=$rc) — see ${slug}.log" | tee -a "$OUT/dump.log"
    else
        stats=$(python3 -c 'import h5py,sys
 f=h5py.File(sys.argv[1])
 n=f["frames/timestamp_sec"].shape[0]
 faces=f["faces/embedding"].shape[0]
 cuts=int(f["frames/is_cut"][:].sum())
 print(f"frames={n} faces={faces} cuts={cuts}")' "$out" 2>/dev/null)
        echo "  ok ($(du -h "$out" | cut -f1), $stats)" | tee -a "$OUT/dump.log"
    fi
 done
 echo "" | tee -a "$OUT/dump.log"
 echo "=== DONE — $(date) ===" | tee -a "$OUT/dump.log"
@@ -1,60 +0,0 @@
 #!/usr/bin/env bash
 # Re-benchmark the feature/opencv5 pipeline against Amazon X-Ray, all 9 films, LVFace-B.
 # Full end-to-end scene_analyze (decode→detect→scene→embed→match→presence) — NOT a replay,
 # because the framework changed enough that old embedding dumps no longer represent the front half.
 # Outputs land in experiments/results/xray_opencv5_lvface/ (durable; /tmp gets wiped).
 set -uo pipefail
 REPO="/home/dtourolle/Development/scene-actor-extraction"
 cd "$REPO"
 ARC="models/LVFace-B_Glint360K.onnx"
 GAL="experiments/galleries/gallery_LVFace-B_Glint360K.h5"
 OUT="experiments/results/xray_opencv5_lvface"
 mkdir -p "$OUT"
 BIN="build/scene_analyze"
 LUT="experiments/file-lut.json"
 FILMS="experiments/manifests/films.json"
 # film slugs and their xray dirs, from films.json
 mapfile -t ROWS < <(python3 -c '
 import json
 for f in json.load(open("'"$FILMS"'")):
    print(f["slug"] + "\t" + f["xray"])
 ')
 echo "=== X-Ray re-benchmark (feature/opencv5, LVFace-B) — $(date) ===" | tee "$OUT/run.log"
 for row in "${ROWS[@]}"; do
    slug="${row%%$'\t'*}"
    xray="${row#*$'\t'}"
    movie="$(python3 -c 'import json,sys; print(json.load(open("'"$LUT"'"))["'"$slug"'"])')"
    pred="$OUT/${slug}.json"
    echo "" | tee -a "$OUT/run.log"
    echo ">>> $slug" | tee -a "$OUT/run.log"
    if [ ! -f "$movie" ]; then
        echo "  SKIP: movie missing: $movie" | tee -a "$OUT/run.log"
        continue
    fi
    # Run the full pipeline (serial — ROCm GPU wedges at concurrency>2-3).
    "$BIN" --movie "$movie" --arcface "$ARC" --gallery "$GAL" \
        --output "$pred" >"$OUT/${slug}.pipeline.log" 2>&1
    rc=$?
    if [ $rc -ne 0 ] || [ ! -f "$pred" ]; then
        echo "  PIPELINE FAILED (rc=$rc) — see ${slug}.pipeline.log" | tee -a "$OUT/run.log"
        continue
    fi
    echo "  pipeline ok" | tee -a "$OUT/run.log"
    # Score against X-Ray, masked to gallery∩GT, 1s grid.
    python scripts/validation/sample_eval.py \
        --pred "$pred" --xray "$xray" --gallery "$GAL" --step 1.0 \
        >"$OUT/${slug}.eval.txt" 2>&1
    tail -8 "$OUT/${slug}.eval.txt" | tee -a "$OUT/run.log"
 done
 echo "" | tee -a "$OUT/run.log"
 echo "=== DONE — $(date) ===" | tee -a "$OUT/run.log"
@@ -1,92 +0,0 @@
 # xsource — cross-source identification probe (VR-013)
 Gallery from **one** recording, probes from **another**, swept over the probe's
 input resolution. Complements VR-005, which asked the same question over gallery
 mugshots: that one degrades an already-aligned 112×112 crop, holding alignment
 perfect, so it isolates the embedder. This one downscales the **whole frame**
 before the detector, so detection and landmark regression degrade with it.
 Corpus: two Pexels clips of one shoot (4096×2160, 25 fps), four people, all four
 present in both.
 ## Getting the data
 Clips, frames and hand-sorted crops are gitignored; they live in the artifact
 registry.
    scripts/artifacts/pull_artifacts.sh xsource     # clips + labelling, frames regenerated
    scripts/artifacts/push_artifacts.sh xsource     # after correcting labels
 Pulling fetches the two clips and the hand-sorted crops, then regenerates the
 frames with ffmpeg — ~320 MB of PNG that is deterministic from the clips, so it
 is not worth shipping. Extraction settings are pinned in the pull script because
 the manifests key on frame filenames *and* on detection order within each frame;
 `verify_labels.py` runs at the end and will fail loudly if they drift.
 Pull never overwrites an existing `labelling/`. That directory is human ground
 truth — somebody looked at all 167 crops and put each one in a folder — and it
 is the expensive part of this study, so push it once corrected.
 Clips are Pexels-licensed: free to use, no attribution required, but not
 CC or MIT. Fine as a frozen CI artifact on private infrastructure; do not
 redistribute them as stock content.
 ## Scripts
 | script | does |
 |---|---|
 | `dump_faces.py` | detect every face, write a context crop per detection + a manifest |
 | `redraw_boxes.py` | redraw those crops with the detection boxed, in place |
 | `propose_labels.py` | propose labels for one clip from another clip's hand-sorted folders |
 | `make_review_site.py` | local `review.html` — current label, crop, better match, correct and export |
 | `apply_corrections.py` | apply the exported `corrections.json` |
 | `verify_labels.py` | integrity gate: index consistency, duplicates, separation. Exits non-zero on failure |
 | `resolution_sweep.py` | the VR-013 measurement |
 | `failure_analysis.py` | what explains the misses — pose, size, blur, detector confidence |
 | `landmark_voting.py` | average SCRFD's overlapping detections instead of discarding them |
 | `pose_label.py` | mesh-estimated head pose, for hand correction (feeds VR-012) |
 Everything drives the shipped C++ through `sae_embed`; nothing reimplements
 detection, alignment, the embedder or the calibration. Scoring goes through the
 production gallery sigmoid — never a raw cosine (AR-024).
    LD_PRELOAD=/usr/lib/libcudnn_cnn.so.9 python3 resolution_sweep.py
 The preload is needed while ORT's CUDA provider looks for
 `cudnnGetConvolutionBackwardDataAlgorithm_v7`, which cuDNN 9 moved into
 `libcudnn_cnn.so.9` behind a dispatch stub. Without it everything silently falls
 back to CPU.
 ## What it found
 **Resolution is not the binding constraint here.** TPI holds ~41–47% from 4096×2160
 down to ~45 px faces, then falls: 23 px → 26%, 18 px → 12%, 14 px → 1.5%. Holding
 90% of the plateau needs roughly 50 px end to end, against VR-005's ~22 px — the
 gap is detection and landmark error, which VR-005 excludes by construction.
 **FPI is 0.0% at every scale.** Resolution loss goes entirely to TBI: the pipeline
 stops naming people rather than naming the wrong one.
 **The ceiling is cross-view, not resolution.** Every person matches themselves
 strongly *within* a recording (sim 0.55–0.85) and collapses *across* the two
 (0.14–0.45, threshold 0.335). Only the person with frontal **gallery** references
 identified reliably, whatever their probe pose — so the lever is gallery pose
 coverage (`docs/pose-expansion.md`), not a better landmark model.
 **Landmark voting helps.** SCRFD predicts each face from several anchors and NMS
 discards all but one, throwing away a median of 3 landmark estimates per face.
 Averaging them, weighted by confidence, lifts cross-clip TPI 41% → 49% for one
 forward pass and no extra model. A MediaPipe mesh as landmark source went the
 other way (41% → 16%): more stable within a recording, but a ring centroid is not
 the annotated landmark ArcFace was trained on, and the embedder punishes the
 off-distribution crop.
 ## Reading these numbers
 Four identities, 70 probes, one shoot. The ~47% plateau is pose, not resolution —
 half these faces are turned away and never clear threshold at any scale, so the
 absolute rates say little and the *shape* is the result. Both clips contain all
 four people, so there is no out-of-gallery class and the 10×-weighted out-of-cast
 misID is **untested** here; holding one identity out of the gallery would fix
 that. And the resolution curve is dominated by the single subject whose gallery
 references are frontal.
@@ -1,44 +0,0 @@
 #!/usr/bin/env python3
 """Apply corrections.json exported from review.html.
    python3 apply_corrections.py ~/Downloads/corrections.json [--dry-run]
 Moves each crop to the folder you chose. "discard" goes to labelling/<clip>/discard/,
 which the sweep ignores — nothing is deleted, so a misclick is recoverable.
 Refuses to move a file it cannot find exactly once, rather than guessing: a
 half-applied correction set would put a crop in two folders and quietly
 duplicate a label.
 """
 import sys, json, glob, os, shutil
 if len(sys.argv) < 2:
    sys.exit(__doc__)
 path = sys.argv[1]
 DRY = "--dry-run" in sys.argv
 corr = json.load(open(path))
 if not corr:
    sys.exit("no corrections in that file")
 moved = skipped = 0
 for fname, c in corr.items():
    clip, to = c["clip"], c["to"]
    hits = glob.glob(f"labelling/{clip}/**/{fname}", recursive=True)
    if len(hits) != 1:
        print(f"[skip] {fname}: found {len(hits)} copies, expected 1")
        skipped += 1
        continue
    src = hits[0]
    dst_dir = f"labelling/{clip}/{to}"
    dst = f"{dst_dir}/{fname}"
    if os.path.abspath(src) == os.path.abspath(dst):
        continue
    print(f"{'would move' if DRY else 'move'} {c['from']} -> {to}: {fname}")
    if not DRY:
        os.makedirs(dst_dir, exist_ok=True)
        shutil.move(src, dst)
    moved += 1
 print(f"\n{moved} moved, {skipped} skipped{' (dry run)' if DRY else ''}")
 if not DRY and moved:
    print("re-run verify_labels.py to confirm the set is still consistent")
@@ -1,90 +0,0 @@
 #!/usr/bin/env python3
 """Dump face crops from both clips for hand-labelling.
 Writes labelling/<clip>/unsorted/<name>.jpg — a context crop around each
 detection, big enough to recognise a person by eye. Move them into
 labelling/<clip>/person_A/, person_B/, ... and the sweep reads those folders as
 ground truth.
 Filenames carry a cNN_ cluster-hint prefix so visually similar faces sort next
 to each other in a file manager. The hint is only an ordering convenience —
 the folder you drop a file into is what counts, and the sweep never reads the
 prefix.
 Detection and alignment run through the shipped C++ (sae_embed). Every crop
 keeps its clip, frame and native-resolution bbox in manifest.json, so probe
 detections at reduced scale can be tied back to a labelled face geometrically,
 by position, rather than by embedding similarity — which would be circular.
 """
 import sys, glob, json, os, shutil
 import numpy as np
 import cv2
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 M = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/models/"
 CLIPS = ["5157339", "5157344"]
 MIN_PX = 60
 CTX = 256          # context-crop side, for human recognisability
 eng = sae_embed.FaceEmbedder(detector_model=M + "scrfd_500m_bnkps.onnx",
                             arcface_model=M + "arcface_w600k_r50.onnx",
                             conf=0.5, nms=0.4, max_side=0)
 for clip in CLIPS:
    out_dir = f"labelling/{clip}/unsorted"
    if os.path.isdir(f"labelling/{clip}"):
        print(f"[skip] labelling/{clip} exists — not overwriting your sorting",
              file=sys.stderr)
        continue
    os.makedirs(out_dir, exist_ok=True)
    entries = []
    for p in sorted(glob.glob(f"pex/d{clip}_*.png")):
        frame = p.rsplit("_", 1)[-1].split(".")[0]
        img = cv2.imread(p)
        for i, d in enumerate(eng.detect(img)):
            x, y, w, h = d.bbox
            if min(w, h) < MIN_PX:
                continue
            lm = np.array(d.landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm)
            if crop is None:
                continue
            emb = np.asarray(eng.embed_crop(crop), dtype=np.float32)
            pad = int(0.5 * max(w, h))
            x0, y0 = max(0, int(x) - pad), max(0, int(y) - pad)
            x1, y1 = min(img.shape[1], int(x + w) + pad), min(img.shape[0], int(y + h) + pad)
            ctx = cv2.resize(img[y0:y1, x0:x1], (CTX, CTX))
            entries.append({"clip": clip, "frame": frame, "idx": i,
                            "bbox": [float(x), float(y), float(w), float(h)],
                            "px": float(min(w, h)), "conf": float(d.confidence),
                            "emb": emb, "ctx": ctx})
    # cluster hint only — greedy, purely to group similar faces in the file list
    E = np.stack([e["emb"] for e in entries])
    hint = -np.ones(len(entries), int)
    k = 0
    for i in range(len(entries)):
        if hint[i] >= 0:
            continue
        hint[i] = k
        for j in range(i + 1, len(entries)):
            if hint[j] < 0 and float(E[i] @ E[j]) > 0.5:
                hint[j] = k
        k += 1
    manifest = []
    for e, h in zip(entries, hint):
        name = f"c{h:02d}_{e['clip']}_f{e['frame']}_i{e['idx']}_{int(e['px'])}px.jpg"
        cv2.imwrite(f"{out_dir}/{name}", e["ctx"])
        manifest.append({k: v for k, v in e.items() if k not in ("emb", "ctx")}
                        | {"file": name, "cluster_hint": int(h)})
    json.dump(manifest, open(f"labelling/{clip}/manifest.json", "w"), indent=1)
    print(f"[{clip}] {len(manifest)} crops in {out_dir}, {k} cluster hints, "
          f"face px {min(m['px'] for m in manifest):.0f}–{max(m['px'] for m in manifest):.0f}",
          file=sys.stderr)
@@ -1,174 +0,0 @@
 #!/usr/bin/env python3
 """What explains the misses? Head pose, face size, blur, detector confidence.
 For every hand-labelled probe face, computes the calibrated probability against
 its OWN gallery entry — so a low value is a false negative, not a mistake about
 who it is — and pairs it with covariates that might explain the failure.
 Head pose comes from solvePnP of the 5 landmarks against a canonical 3D face,
 giving yaw/pitch/roll in degrees.
    CAVEAT, and it matters: the pose estimate is derived from the same 5
    landmarks the alignment uses. Where those landmarks are unreliable the pose
    estimate is unreliable too, and both degrade for the same reason. So this
    can show that failures concentrate at high yaw; it cannot cleanly separate
    "the head was turned" from "the landmarks were wrong because the head was
    turned". Those are the same physical cause, but not the same fix — the
    first argues for gallery pose coverage, the second for a better landmark
    source.
 A sanity check is printed first: pose is estimated per person, and if it does
 not recover what is visible in the review sheets (one subject frontal, another
 in profile, another looking down) then the estimate is not worth reading.
 Similarities go through the production gallery sigmoid, never compared raw.
 """
 import sys, glob, json, os
 import numpy as np
 import cv2
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 GALLERY_CLIP, PROBE_CLIP = "5157344", "5157339"
 PROB_THRESHOLD = 0.754
 # Canonical 3D face, ordered as types.hpp:60 —
 # [0] right-eye [1] left-eye [2] nose [3] right-mouth [4] left-mouth.
 # The subject's right eye sits to the LEFT in image space, hence the negative X.
 FACE_3D = np.array([
    (-34.0,  35.0, -28.0),
    ( 34.0,  35.0, -28.0),
    (  0.0,   0.0,   0.0),
    (-26.0, -32.0, -25.0),
    ( 26.0, -32.0, -25.0),
 ], dtype=np.float64)
 eng = sae_embed.FaceEmbedder(detector_model=M + "scrfd_500m_bnkps.onnx",
                             arcface_model=M + "LVFace-B_Glint360K.onnx",
                             conf=0.5, nms=0.4, max_side=0)
 cal = sae_embed.gallery_calibration(ROOT + "gallery_lvface.h5")
 def head_pose(lm, w, h):
    """yaw, pitch, roll in degrees. Focal length assumed = image width."""
    cam = np.array([[w, 0, w / 2], [0, w, h / 2], [0, 0, 1]], dtype=np.float64)
    ok, rvec, _ = cv2.solvePnP(FACE_3D, lm.astype(np.float64), cam, None,
                               flags=cv2.SOLVEPNP_EPNP)
    if not ok:
        return None
    R, _ = cv2.Rodrigues(rvec)
    sy = np.sqrt(R[0, 0] ** 2 + R[1, 0] ** 2)
    if sy > 1e-6:
        pitch = np.degrees(np.arctan2(-R[2, 0], sy))
        yaw = np.degrees(np.arctan2(R[1, 0], R[0, 0]))
        roll = np.degrees(np.arctan2(R[2, 1], R[2, 2]))
    else:
        pitch = np.degrees(np.arctan2(-R[2, 0], sy)); yaw = 0.0
        roll = np.degrees(np.arctan2(-R[1, 2], R[1, 1]))
    # solvePnP's yaw wraps near +/-180 for a face pointing at the camera;
    # fold it to a "degrees away from frontal" magnitude.
    yaw = ((yaw + 180) % 360) - 180
    if abs(yaw) > 90:
        yaw = np.sign(yaw) * (180 - abs(yaw))
    return yaw, pitch, roll
 def collect(clip):
    lab = {os.path.basename(p): os.path.basename(os.path.dirname(p))
           for p in glob.glob(f"labelling/{clip}/*/*.jpg")
           if os.path.basename(os.path.dirname(p)) not in ("discard", "unsorted")}
    man = {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
    rows = []
    for frame in sorted({man[f]["frame"] for f in lab}):
        img = cv2.imread(f"frames/d{clip}_{frame}.png")
        dets = eng.detect(img)
        H, W = img.shape[:2]
        for f, person in lab.items():
            m = man[f]
            if m["frame"] != frame or m["idx"] >= len(dets):
                continue
            d = dets[m["idx"]]
            lm = np.array(d.landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm)
            if crop is None:
                continue
            pose = head_pose(lm, W, H)
            x, y, w, h = d.bbox
            g = cv2.cvtColor(np.asarray(crop), cv2.COLOR_BGR2GRAY)
            rows.append({
                "person": person, "px": float(min(w, h)), "conf": float(d.confidence),
                "yaw": pose[0] if pose else np.nan, "pitch": pose[1] if pose else np.nan,
                "roll": pose[2] if pose else np.nan,
                "blur": float(cv2.Laplacian(g, cv2.CV_64F).var()),
                "emb": np.asarray(eng.embed_crop(crop), dtype=np.float32)})
    return rows
 gal_rows = collect(GALLERY_CLIP)
 prb_rows = collect(PROBE_CLIP)
 gal = {}
 for r in gal_rows:
    gal.setdefault(r["person"], []).append(r["emb"])
 gal = {p: np.stack(v) for p, v in gal.items()}
 for r in prb_rows:
    if r["person"] in gal:
        s = float((gal[r["person"]] @ r["emb"]).max())     # best-of-N, own actor
        r["p"] = cal.probability(s)
        r["sim"] = s
    else:
        r["p"] = np.nan
 rows = [r for r in prb_rows if not np.isnan(r.get("p", np.nan))]
 print(f"[data] {len(rows)} labelled probe faces with a gallery entry\n", file=sys.stderr)
 # ── sanity check: does the pose estimate recover what the sheets show? ───────
 print("pose by person (does this match the review sheets?)")
 print(f"{'person':>7}{'n':>5}{'|yaw| med':>11}{'pitch med':>11}{'P med':>8}{'hit rate':>10}")
 for p in sorted({r['person'] for r in rows}):
    sub = [r for r in rows if r["person"] == p]
    print(f"{p:>7}{len(sub):>5}"
          f"{np.median([abs(r['yaw']) for r in sub]):>11.1f}"
          f"{np.median([r['pitch'] for r in sub]):>11.1f}"
          f"{np.median([r['p'] for r in sub]):>8.3f}"
          f"{100*np.mean([r['p'] > PROB_THRESHOLD for r in sub]):>9.0f}%")
 # ── P binned by each covariate ───────────────────────────────────────────────
 def binned(name, key, edges, fmt="{:.0f}"):
    print(f"\nP(match) by {name}")
    print(f"{'bin':>16}{'n':>5}{'P med':>9}{'hit rate':>10}{'sim med':>9}")
    vals = np.array([r[key] for r in rows])
    for lo, hi in zip(edges[:-1], edges[1:]):
        sub = [r for r, v in zip(rows, vals) if lo <= v < hi]
        if not sub:
            continue
        lbl = f"{fmt.format(lo)}–{fmt.format(hi)}"
        print(f"{lbl:>16}{len(sub):>5}"
              f"{np.median([r['p'] for r in sub]):>9.3f}"
              f"{100*np.mean([r['p'] > PROB_THRESHOLD for r in sub]):>9.0f}%"
              f"{np.median([r['sim'] for r in sub]):>9.3f}")
 for r in rows:
    r["absyaw"] = abs(r["yaw"])
    r["abspitch"] = abs(r["pitch"])
 binned("|yaw| (deg from frontal)", "absyaw", [0, 10, 20, 30, 45, 60, 91])
 binned("|pitch| (deg)", "abspitch", [0, 10, 20, 30, 45, 91])
 binned("face size (px)", "px", [0, 130, 150, 175, 200, 400])
 binned("blur (laplacian var)", "blur", [0, 50, 150, 400, 1000, 1e9])
 binned("detector confidence", "conf", [0.5, 0.6, 0.7, 0.8, 0.9, 1.01], "{:.2f}")
 # ── how much does each covariate actually explain? ───────────────────────────
 print("\nSpearman rank correlation with P(match):")
 def spearman(a, b):
    ra = np.argsort(np.argsort(a)); rb = np.argsort(np.argsort(b))
    return float(np.corrcoef(ra, rb)[0, 1])
 P = np.array([r["p"] for r in rows])
 for key, label in [("absyaw", "|yaw|"), ("abspitch", "|pitch|"), ("px", "face px"),
                   ("blur", "blur"), ("conf", "detector conf")]:
    v = np.array([r[key] for r in rows])
    print(f"   {label:>14}: {spearman(v, P):+.3f}")
 json.dump([{k: v for k, v in r.items() if k != "emb"} for r in rows],
          open("failure_analysis.json", "w"), indent=1, default=float)
@@ -1,223 +0,0 @@
 #!/usr/bin/env python3
 """Landmark voting: average SCRFD's overlapping detections instead of discarding them.
 SCRFD predicts a face from many anchors; NMS keeps the single highest-scoring
 box and throws the rest away. Each discarded box carries its own 5-landmark
 estimate of the SAME face, so the survivors are one sample from a distribution
 we could be averaging over.
    baseline  conf 0.50, nms 0.40 — the shipped settings, one box per face
    voted     conf 0.30, nms 0.90 — duplicates survive, then grouped by IoU and
              the 5 landmarks averaged, weighted by detection confidence
 Why this is worth trying when the mesh failed: the mesh moved the landmarks off
 the definition ArcFace was trained on (a lip-ring centroid is not an annotated
 mouth corner), and the embedder punished it. A confidence-weighted mean of
 SCRFD's OWN landmark predictions is the same kind of point, just with less
 variance — it should stay on-distribution while being steadier.
 Scored on cross-clip identification through the production sigmoid, which is
 the thing that actually broke. Raw similarity shown only to locate the
 threshold; it decides nothing.
    LD_PRELOAD=/usr/lib/libcudnn_cnn.so.9 python3 landmark_voting.py
 """
 import sys, glob, json, os
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed          # before cv2 — see alignment_compare.py
 import numpy as np
 import cv2
 import argparse
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 CLIPS = ["5157344", "5157339"]
 PROB_THRESHOLD = 0.754
 GROUP_IOU = 0.55          # detections overlapping this much are the same face
 MATCH_IOU = 0.35          # tie a detection to the hand-labelled face
 _ap = argparse.ArgumentParser()
 _ap.add_argument("--detector", default="scrfd_500m_bnkps.onnx",
                 help="detector under models/. SCRFD sizes 500m / 2.5g / 10g come "
                      "from InsightFace's buffalo_sc / buffalo_m / buffalo_l packs")
 _ap.add_argument("--vote-conf", type=float, default=None,
                 help="confidence floor for the voting pass. Omit to auto-tune "
                      "it to --target-votes")
 _ap.add_argument("--target-votes", type=int, default=3,
                 help="votes per face to tune --vote-conf towards, so detectors "
                      "are compared at equal redundancy rather than equal settings")
 _args = _ap.parse_args()
 base_eng = sae_embed.FaceEmbedder(detector_model=M + _args.detector,
                                  arcface_model=M + "LVFace-B_Glint360K.onnx",
                                  conf=0.5, nms=0.4, max_side=0)
 def _make_vote_engine(conf):
    # Same models, looser suppression: keep the duplicates NMS would have removed.
    return sae_embed.FaceEmbedder(detector_model=M + _args.detector,
                                  arcface_model=M + "LVFace-B_Glint360K.onnx",
                                  conf=conf, nms=0.9, max_side=0)
 cal = sae_embed.gallery_calibration(ROOT + "gallery_lvface.h5")
 def iou(a, b):
    ax, ay, aw, ah = a; bx, by, bw, bh = b
    x0, y0 = max(ax, bx), max(ay, by)
    x1, y1 = min(ax + aw, bx + bw), min(ay + ah, by + bh)
    if x1 <= x0 or y1 <= y0:
        return 0.0
    i = (x1 - x0) * (y1 - y0)
    return i / (aw * ah + bw * bh - i)
 def vote(dets):
    """Group overlapping detections, return (bbox, landmarks, conf, n_votes)."""
    items = sorted(dets, key=lambda d: -d.confidence)
    used, out = [False] * len(items), []
    for i, d in enumerate(items):
        if used[i]:
            continue
        grp = [d]
        used[i] = True
        for j in range(i + 1, len(items)):
            if not used[j] and iou(list(d.bbox), list(items[j].bbox)) >= GROUP_IOU:
                used[j] = True
                grp.append(items[j])
        w = np.array([g.confidence for g in grp], dtype=np.float32)
        w = w / w.sum()
        lms = np.stack([np.array(g.landmarks, dtype=np.float32).reshape(5, 2) for g in grp])
        bxs = np.stack([np.array(list(g.bbox), dtype=np.float32) for g in grp])
        out.append((( w[:, None] * bxs).sum(0), (w[:, None, None] * lms).sum(0),
                    float(grp[0].confidence), len(grp)))
    return out
 def tune_vote_conf(target, sample=6):
    """Pick the confidence floor giving ~target detections per face to average.
    A larger SCRFD is more confident and suppresses harder, so at a fixed floor
    it emits fewer overlapping anchors — median 2 against 500m's 3. Comparing
    detectors at equal SETTINGS therefore also compares them at unequal
    redundancy, and the voting arm is handicapped for the bigger models. Tuning
    each to the same votes-per-face isolates landmark quality from how much
    there was to average.
    """
    frames = sorted(glob.glob(f"frames/d{CLIPS[0]}_*.png"))[:sample]
    imgs = [cv2.imread(f) for f in frames]
    best = (None, None, 1e9)
    for conf in (0.30, 0.20, 0.12, 0.07, 0.04, 0.02, 0.01):
        eng = _make_vote_engine(conf)
        sizes = [n for img in imgs for _, _, _, n in vote(eng.detect(img))]
        if not sizes:
            continue
        med = float(np.median(sizes))
        if abs(med - target) < best[2]:
            best = (conf, eng, abs(med - target))
        print(f"[tune] conf={conf:.2f} -> median {med:.0f} votes/face", file=sys.stderr)
        if med >= target:
            break
    if best[1] is None:
        print(f"[tune] no confidence floor reached {target} votes/face; "
              f"falling back to 0.30", file=sys.stderr)
        return 0.30, _make_vote_engine(0.30)
    print(f"[tune] chose conf={best[0]:.2f} for ~{target} votes/face", file=sys.stderr)
    return best[0], best[1]
 if _args.vote_conf is not None:
    VOTE_CONF, vote_eng = _args.vote_conf, _make_vote_engine(_args.vote_conf)
 else:
    VOTE_CONF, vote_eng = tune_vote_conf(_args.target_votes)
 cal = sae_embed.gallery_calibration(ROOT + "gallery_lvface.h5")
 def collect(clip):
    lab = {os.path.basename(p): os.path.basename(os.path.dirname(p))
           for p in glob.glob(f"labelling/{clip}/*/*.jpg")
           if os.path.basename(os.path.dirname(p)) not in ("discard", "unsorted")}
    man = {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
    rows, votes = [], []
    for frame in sorted({man[f]["frame"] for f in lab}):
        img = cv2.imread(f"frames/d{clip}_{frame}.png")
        base = base_eng.detect(img)
        voted = vote(vote_eng.detect(img))
        for fname, person in lab.items():
            m = man[fname]
            if m["frame"] != frame or m["idx"] >= len(base):
                continue
            d = base[m["idx"]]
            lm5 = np.array(d.landmarks, dtype=np.float32).reshape(5, 2)
            c_b = sae_embed.align_face(img, lm5)
            # the voted group covering the same face
            best, best_v = None, 0.0
            for bbox, lms, conf, n in voted:
                v = iou(list(bbox), list(d.bbox))
                if v > best_v:
                    best_v, best = v, (lms, n)
            c_v = None
            if best and best_v >= MATCH_IOU:
                c_v = sae_embed.align_face(img, best[0].astype(np.float32))
                votes.append(best[1])
            rec = {"person": person}
            rec["base"] = np.asarray(base_eng.embed_crop(c_b), np.float32) if c_b is not None else None
            rec["voted"] = np.asarray(base_eng.embed_crop(c_v), np.float32) if c_v is not None else None
            rows.append(rec)
    return rows, votes
 data, allv = {}, []
 for c in CLIPS:
    data[c], v = collect(c)
    allv += v
    print(f"[{c}] {len(data[c])} crops", file=sys.stderr)
 print(f"[voting] group size: median {np.median(allv):.0f}, "
      f"mean {np.mean(allv):.1f}, max {max(allv)} detections averaged per face",
      file=sys.stderr)
 GAL, PRB = "5157344", "5157339"
 print(f"\ndetector={_args.detector}  vote_conf={VOTE_CONF:.2f}  "
      f"gallery {GAL} -> probe {PRB}, P>{PROB_THRESHOLD}\n")
 print(f"{'align':>8}{'person':>8}{'n_gal':>7}{'n_prb':>7}"
      f"{'within-clip':>13}{'cross-clip':>12}{'hit rate':>10}")
 summary = {}
 for key in ("base", "voted"):
    gal, prb = {}, {}
    for r in data[GAL]:
        if r[key] is not None:
            gal.setdefault(r["person"], []).append(r[key])
    for r in data[PRB]:
        if r[key] is not None:
            prb.setdefault(r["person"], []).append(r[key])
    gal = {p: np.stack(v) for p, v in gal.items()}
    prb = {p: np.stack(v) for p, v in prb.items()}
    hits = tot = 0
    for p in sorted(set(gal) & set(prb)):
        pp = prb[p] @ prb[p].T
        np.fill_diagonal(pp, -1)
        within = float(np.median(pp.max(axis=1))) if len(pp) > 1 else float("nan")
        cross = float(np.median((gal[p] @ prb[p].T).max(axis=0)))
        h = 0
        for e in prb[p]:
            bp, bn = 0.0, None
            for q in gal:
                v = cal.probability(float((gal[q] @ e).max()))
                if v > bp:
                    bp, bn = v, q
            if bp > PROB_THRESHOLD and bn == p:
                h += 1
        hits += h; tot += len(prb[p])
        print(f"{key:>8}{p:>8}{len(gal[p]):>7}{len(prb[p]):>7}"
              f"{cal.probability(within):>6.3f}/{within:<6.3f}"
              f"{cal.probability(cross):>6.3f}/{cross:<5.3f}{100*h/len(prb[p]):>9.0f}%")
    summary[key] = (hits, tot)
    print(f"{key:>8}{'ALL':>8}{'':>14}{'':>25}{100*hits/max(tot,1):>9.0f}%\n")
 hb, tb = summary["base"]; hv, tv = summary["voted"]
 print(f"voting vs baseline: {100*hv/max(tv,1) - 100*hb/max(tb,1):+.1f} points "
      f"of cross-clip TPI ({hb}/{tb} -> {hv}/{tv})")
@@ -1,235 +0,0 @@
 #!/usr/bin/env python3
 """Build labelling/review.html — a local page for correcting the labels.
 One row per crop, ordered most-suspicious first:
    left    the person it is currently filed under (medoid of that person's
            hand-sorted crops, so the reference is one you trust)
    centre  the crop under review — context with the detection boxed, and
            beneath it the 112x112 the embedder actually receives
    right   the person it matches better, if any, with both probabilities
 Pick a destination per row, then Export to download corrections.json and apply
 it with apply_corrections.py. Nothing is moved by this script.
 Self-contained: images are inlined as data URIs and the page is opened from
 disk, so no server runs and no face crop leaves the machine.
 Ordering is by P(other) - P(self), both from the global gallery sigmoid, so
 rows where the evidence disagrees with the label float to the top and the
 agreement cases sink. It is a review order, not a verdict — you are the
 arbiter, which is the whole point of labelling by hand.
 """
 import sys, glob, json, os, base64
 import numpy as np
 import cv2
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 EMBEDDER = M + "LVFace-B_Glint360K.onnx"
 GALLERY  = ROOT + "gallery_lvface.h5"
 REF_CLIP = "5157344"          # the clip sorted by hand — reference faces come from here
 CLIPS = ["5157344", "5157339"]
 eng = sae_embed.FaceEmbedder(detector_model=M + "scrfd_500m_bnkps.onnx",
                             arcface_model=EMBEDDER, conf=0.5, nms=0.4, max_side=0)
 cal = sae_embed.gallery_calibration(GALLERY)
 def b64(img, size, q=72):
    img = cv2.resize(img, (size, size))
    ok, buf = cv2.imencode(".jpg", img, [cv2.IMWRITE_JPEG_QUALITY, q])
    return "data:image/jpeg;base64," + base64.b64encode(buf).decode() if ok else ""
 rows = []
 for clip in CLIPS:
    man = {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
    placed = {os.path.basename(p): (os.path.basename(os.path.dirname(p)), p)
              for p in glob.glob(f"labelling/{clip}/*/*.jpg")}
    by_frame = {}
    for fname, (person, path) in placed.items():
        if fname in man and person != "unsorted":
            by_frame.setdefault(man[fname]["frame"], []).append((fname, person, path))
    for frame, items in sorted(by_frame.items()):
        img = cv2.imread(f"frames/d{clip}_{frame}.png")
        if img is None:
            continue
        dets = eng.detect(img)
        for fname, person, path in items:
            i = man[fname]["idx"]
            if i >= len(dets):
                continue
            lm = np.array(dets[i].landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm)
            if crop is None:
                continue
            rows.append({"clip": clip, "person": person, "file": fname, "path": path,
                         "px": man[fname]["px"], "aligned": np.asarray(crop),
                         "emb": np.asarray(eng.embed_crop(crop), dtype=np.float32)})
 people = sorted({r["person"] for r in rows})
 E = np.stack([r["emb"] for r in rows])
 lab = np.array([people.index(r["person"]) for r in rows])
 S = E @ E.T
 np.fill_diagonal(S, -1.0)
 # reference face per person: medoid of their REF_CLIP crops
 ref_img = {}
 for k, p in enumerate(people):
    idx = [i for i in np.where(lab == k)[0] if rows[i]["clip"] == REF_CLIP]
    if not idx:
        idx = list(np.where(lab == k)[0])
    if not idx:
        continue
    sub = S[np.ix_(idx, idx)].copy()
    medoid = idx[int(np.argmax(sub.mean(axis=1)))]
    ref_img[p] = b64(rows[medoid]["aligned"], 112)
 items = []
 for i, r in enumerate(rows):
    k = lab[i]
    same = [j for j in np.where(lab == k)[0] if j != i]
    p_self = cal.probability(float(S[i, same].max())) if same else 0.0
    best_other, p_other = None, 0.0
    for k2, p2 in enumerate(people):
        if k2 == k:
            continue
        other = np.where(lab == k2)[0]
        if not len(other):
            continue
        pv = cal.probability(float(S[i, other].max()))
        if pv > p_other:
            p_other, best_other = pv, p2
    ctx = cv2.imread(r["path"])
    items.append({
        "file": r["file"], "clip": r["clip"], "person": r["person"],
        "px": int(r["px"]), "p_self": round(p_self, 3), "p_other": round(p_other, 3),
        "other": best_other, "delta": round(p_other - p_self, 3),
        "ctx": b64(ctx, 150) if ctx is not None else "",
        "ali": b64(r["aligned"], 112),
    })
 items.sort(key=lambda x: -x["delta"])
 payload = json.dumps({"people": people, "refs": ref_img, "items": items})
 HTML = """<meta charset="utf-8"><title>JRay — label review</title>
 <style>
 :root{color-scheme:dark;--bg:#14161a;--fg:#e6e8ea;--mut:#8b929c;--line:#262b33;--warn:#e0654a;--ok:#4a9d6a}
 body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.5 system-ui,sans-serif}
 header{position:sticky;top:0;background:#181b20;border-bottom:1px solid var(--line);
 padding:12px 18px;display:flex;gap:18px;align-items:center;flex-wrap:wrap;z-index:5}
 h1{font-size:15px;margin:0;font-weight:600}
 .stat{color:var(--mut);font-size:13px}
 button{background:#232830;color:var(--fg);border:1px solid var(--line);border-radius:6px;
 padding:7px 13px;cursor:pointer;font:inherit}
 button:hover{background:#2c323c}
 button.go{background:#2f5d43;border-color:#3c7555}
 .row{display:grid;grid-template-columns:150px 1fr 190px;gap:20px;align-items:center;
 padding:14px 18px;border-bottom:1px solid var(--line)}
 .row.flag{background:#1e1719}
 .row.done{opacity:.4}
 .cell{display:flex;gap:10px;align-items:center}
 img{border-radius:5px;display:block;background:#000}
 .lab{font-weight:600;font-size:15px}
 .mut{color:var(--mut);font-size:12px}
 .p{font-variant-numeric:tabular-nums}
 .hi{color:var(--warn);font-weight:600}
 .choices{display:flex;flex-wrap:wrap;gap:6px}
 .choices button{padding:5px 10px;font-size:13px}
 .choices button.sel{background:#2f5d43;border-color:#3c7555}
 .legend{padding:10px 18px;color:var(--mut);font-size:12px;border-bottom:1px solid var(--line)}
 </style>
 <header>
  <h1>Label review</h1>
  <span class="stat" id="stat"></span>
  <button id="exp" class="go">Export corrections.json</button>
  <button id="onlyflag">Show only disagreements</button>
 </header>
 <div class="legend">Left: the person this crop is filed under. Centre: the crop (context with the
 detection boxed, and the 112&times;112 the embedder actually sees). Right: the person it matches
 better, if any. Ordered by P(other) &minus; P(self) &mdash; disagreements first.</div>
 <div id="list"></div>
 <script>
 const D = __PAYLOAD__;
 const choice = {};
 const list = document.getElementById('list');
 function render(){
  list.innerHTML = '';
  const flagOnly = document.body.dataset.flag === '1';
  for (const it of D.items){
    if (flagOnly && it.delta <= 0) continue;
    const row = document.createElement('div');
    row.className = 'row' + (it.delta > 0 ? ' flag' : '') + (choice[it.file] ? ' done' : '');
    const left = document.createElement('div');
    left.className = 'cell';
    left.innerHTML = `<img src="${D.refs[it.person]||''}" width="72" height="72">
      <div><div class="lab">${it.person}</div>
      <div class="mut p">P(self) ${it.p_self.toFixed(3)}</div></div>`;
    const mid = document.createElement('div');
    mid.className = 'cell';
    mid.innerHTML = `<img src="${it.ctx}" width="120" height="120">
      <img src="${it.ali}" width="90" height="90">
      <div><div class="mut">${it.clip} &middot; ${it.px}px</div>
      <div class="mut">${it.file}</div></div>`;
    const right = document.createElement('div');
    const worse = it.delta > 0;
    right.innerHTML = it.other
      ? `<div class="cell"><img src="${D.refs[it.other]||''}" width="56" height="56">
         <div><div class="lab ${worse?'hi':''}">${it.other}</div>
         <div class="mut p ${worse?'hi':''}">P ${it.p_other.toFixed(3)}</div></div></div>`
      : '<div class="mut">—</div>';
    const ch = document.createElement('div');
    ch.className = 'choices';
    for (const p of D.people.concat(['discard'])){
      const b = document.createElement('button');
      b.textContent = p === it.person ? p + ' (keep)' : p;
      if (choice[it.file] === p || (!choice[it.file] && p === it.person)) b.classList.add('sel');
      b.onclick = () => { choice[it.file] = p; render(); };
      ch.appendChild(b);
    }
    right.appendChild(ch);
    row.append(left, mid, right);
    list.appendChild(row);
  }
  const changed = Object.entries(choice).filter(([f,p]) =>
    p !== (D.items.find(i=>i.file===f)||{}).person).length;
  document.getElementById('stat').textContent =
    `${D.items.length} crops · ${D.items.filter(i=>i.delta>0).length} disagreements · ${changed} changes staged`;
 }
 document.getElementById('onlyflag').onclick = () => {
  document.body.dataset.flag = document.body.dataset.flag === '1' ? '0' : '1';
  render();
 };
 document.getElementById('exp').onclick = () => {
  const out = {};
  for (const it of D.items){
    const p = choice[it.file] || it.person;
    if (p !== it.person) out[it.file] = {from: it.person, to: p, clip: it.clip};
  }
  const blob = new Blob([JSON.stringify(out, null, 1)], {type:'application/json'});
  const a = document.createElement('a');
  a.href = URL.createObjectURL(blob); a.download = 'corrections.json'; a.click();
 };
 render();
 </script>
 """
 os.makedirs("labelling", exist_ok=True)
 out = "labelling/review.html"
 with open(out, "w") as f:
    f.write(HTML.replace("__PAYLOAD__", payload))
 size = os.path.getsize(out) / 1e6
 flagged = sum(1 for i in items if i["delta"] > 0)
 print(f"{out}  {size:.1f} MB  {len(items)} crops, {flagged} disagreements", file=sys.stderr)
 print(f"open file://{os.path.abspath(out)}", file=sys.stderr)
@@ -1,200 +0,0 @@
 #!/usr/bin/env python3
 """Estimate head pose per crop, and build a page to confirm or correct it.
 Why not solvePnP on the 5 detector landmarks: those landmarks collapse on
 turned faces, so the estimator breaks precisely on the crops whose pose we care
 about. Run that way it reported the profile subject as the MOST frontal of the
 four, which is how we know not to trust it.
 Instead the estimate comes from the MediaPipe face mesh (468 points, run via
 OpenCV DNN — the same model rPPG-kahn uses) and a symmetry measure that needs
 no 3D model:
    yaw_ratio = (dL - dR) / (dL + dR)
 over left/right symmetric vertex pairs, where dL and dR are each side's
 distance from the face midline. Frontal ~ 0, profile -> +/-1. It degrades
 gracefully because it averages many pairs rather than trusting any one point,
 and it is scale- and translation-free.
 It is still an estimate. So this writes pose_review.html with the estimate
 PRE-FILLED as a proposal, ordered by confidence, for you to correct — and the
 correlation is only run against your corrected labels. If the estimate turns
 out to disagree with you often, that is the finding, and the automatic number
 gets dropped rather than reported.
 Bins are coarse on purpose: frontal / three-quarter / profile / down-or-hidden.
 Finer than that and the labelling is slower and less reliable, and the question
 ("does pose explain the misses") does not need degrees.
 """
 import sys, glob, json, os, base64
 # sae_embed MUST be imported before cv2: OpenCV's DNN module loads the system
 # libonnxruntime, which then shadows the newer one this module links against and
 # the import fails on a missing symbol version. Order matters, so do not tidy
 # these into alphabetical order.
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 import numpy as np
 import cv2
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 MESH = "/home/dtourolle/Development/rPPG-kahn/models/face_landmark.tflite"
 CLIPS = ["5157344", "5157339"]
 BINS = ["frontal", "three-quarter", "profile", "down-or-hidden"]
 # Symmetric vertex pairs (subject-left, subject-right) on the MediaPipe mesh:
 # outer eye corners, inner eye corners, cheeks, mouth corners, jaw.
 PAIRS = [(33, 263), (133, 362), (130, 359), (243, 463),
         (61, 291), (91, 321), (146, 375), (58, 288), (172, 397), (215, 435)]
 MIDLINE = [10, 168, 1, 4, 5, 195, 197, 152]      # forehead -> nose -> chin
 net = cv2.dnn.readNetFromTFLite(MESH)
 NAMES = net.getUnconnectedOutLayersNames()
 LMI, PRI = NAMES.index("conv2d_21"), NAMES.index("conv2d_31")
 eng = sae_embed.FaceEmbedder(detector_model=M + "scrfd_500m_bnkps.onnx",
                             arcface_model=M + "LVFace-B_Glint360K.onnx",
                             conf=0.5, nms=0.4, max_side=0)
 def mesh_pose(img, bbox, expand=1.6):
    """(yaw_ratio, presence) or (nan, 0). yaw_ratio in [-1, 1], 0 = frontal."""
    x, y, w, h = bbox
    cx, cy, s = x + w / 2, y + h / 2, max(w, h) * expand
    crop = cv2.getRectSubPix(img, (int(s), int(s)), (float(cx), float(cy)))
    net.setInput(cv2.dnn.blobFromImage(crop, 1 / 255.0, (192, 192), (0, 0, 0), swapRB=True))
    o = net.forward(NAMES)
    pres = 1 / (1 + np.exp(-float(o[PRI].ravel()[0])))
    lm = o[LMI].reshape(468, 3)[:, :2]
    mid = lm[MIDLINE]
    # least-squares midline direction, then signed distance of each pair member
    c = mid.mean(axis=0)
    u, _, _ = np.linalg.svd(mid - c)
    d = (mid - c)
    axis = np.linalg.svd(d.T @ d)[0][:, 0]        # principal direction of the midline
    normal = np.array([-axis[1], axis[0]])
    ratios = []
    for a, b in PAIRS:
        dl = float(np.dot(lm[a] - c, normal))
        dr = float(np.dot(lm[b] - c, normal))
        if abs(dl) + abs(dr) < 1e-6:
            continue
        ratios.append((abs(dl) - abs(dr)) / (abs(dl) + abs(dr)))
    return (float(np.median(ratios)) if ratios else np.nan), pres
 def b64(img, size, q=72):
    ok, buf = cv2.imencode(".jpg", cv2.resize(img, (size, size)),
                           [cv2.IMWRITE_JPEG_QUALITY, q])
    return "data:image/jpeg;base64," + base64.b64encode(buf).decode() if ok else ""
 items = []
 for clip in CLIPS:
    lab = {os.path.basename(p): (os.path.basename(os.path.dirname(p)), p)
           for p in glob.glob(f"labelling/{clip}/*/*.jpg")
           if os.path.basename(os.path.dirname(p)) not in ("discard", "unsorted")}
    man = {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
    for frame in sorted({man[f]["frame"] for f in lab}):
        img = cv2.imread(f"frames/d{clip}_{frame}.png")
        dets = eng.detect(img)
        for fname, (person, path) in lab.items():
            m = man[fname]
            if m["frame"] != frame or m["idx"] >= len(dets):
                continue
            d = dets[m["idx"]]
            lm5 = np.array(d.landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm5)
            if crop is None:
                continue
            yaw, pres = mesh_pose(img, d.bbox)
            a = abs(yaw) if not np.isnan(yaw) else 1.0
            guess = ("frontal" if a < 0.15 else "three-quarter" if a < 0.45
                     else "profile")
            if pres < 0.5:
                guess = "down-or-hidden"      # mesh could not fit at all
            ctx = cv2.imread(path)
            items.append({"file": fname, "clip": clip, "person": person,
                          "px": int(m["px"]), "yaw": None if np.isnan(yaw) else round(yaw, 3),
                          "pres": round(pres, 3), "guess": guess,
                          "ctx": b64(ctx, 140) if ctx is not None else "",
                          "ali": b64(np.asarray(crop), 112)})
 # least-confident first: near a bin boundary, or the mesh could not fit
 def uncertainty(it):
    if it["pres"] < 0.5:
        return 0.0
    a = abs(it["yaw"]) if it["yaw"] is not None else 1.0
    return min(abs(a - 0.15), abs(a - 0.45))
 items.sort(key=uncertainty)
 payload = json.dumps({"bins": BINS, "items": items})
 HTML = """<meta charset="utf-8"><title>JRay — head pose labelling</title>
 <style>
 :root{color-scheme:dark}
 body{margin:0;background:#14161a;color:#e6e8ea;font:14px/1.5 system-ui,sans-serif}
 header{position:sticky;top:0;background:#181b20;border-bottom:1px solid #262b33;
 padding:12px 18px;display:flex;gap:16px;align-items:center;flex-wrap:wrap;z-index:5}
 h1{font-size:15px;margin:0}
 button{background:#232830;color:#e6e8ea;border:1px solid #262b33;border-radius:6px;
 padding:7px 12px;cursor:pointer;font:inherit}
 button:hover{background:#2c323c}
 button.go{background:#2f5d43;border-color:#3c7555}
 .g{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:10px;padding:14px}
 .c{border:1px solid #262b33;border-radius:8px;padding:9px;display:flex;gap:9px;align-items:center}
 .c.edited{border-color:#3c7555}
 img{border-radius:5px;background:#000;display:block}
 .m{color:#8b929c;font-size:11px}
 .b{display:flex;flex-wrap:wrap;gap:4px;margin-top:5px}
 .b button{padding:3px 7px;font-size:11px}
 .b button.sel{background:#2f5d43;border-color:#3c7555}
 </style>
 <header><h1>Head pose</h1><span class="m" id="stat"></span>
 <button class="go" id="exp">Export pose_labels.json</button></header>
 <div class="g" id="g"></div>
 <script>
 const D=__PAYLOAD__; const pick={};
 function render(){
 const g=document.getElementById('g'); g.innerHTML='';
 for(const it of D.items){
  const cur=pick[it.file]||it.guess;
  const c=document.createElement('div');
  c.className='c'+(pick[it.file]&&pick[it.file]!==it.guess?' edited':'');
  const b=D.bins.map(x=>`<button class="${x===cur?'sel':''}" data-f="${it.file}" data-b="${x}">${x}</button>`).join('');
  c.innerHTML=`<img src="${it.ctx}" width="88" height="88"><img src="${it.ali}" width="66" height="66">
   <div><div class="m">${it.person} · ${it.clip.slice(-3)} · ${it.px}px</div>
   <div class="m">yaw ${it.yaw===null?'—':it.yaw} · presence ${it.pres}</div>
   <div class="b">${b}</div></div>`;
  g.appendChild(c);
 }
 g.onclick=e=>{const t=e.target; if(t.dataset&&t.dataset.b){pick[t.dataset.f]=t.dataset.b; render();}};
 const ed=Object.entries(pick).filter(([f,v])=>v!==(D.items.find(i=>i.file===f)||{}).guess).length;
 document.getElementById('stat').textContent=`${D.items.length} crops · ${ed} corrections`;
 }
 document.getElementById('exp').onclick=()=>{
 const out={}; for(const it of D.items) out[it.file]={pose:pick[it.file]||it.guess,
   guess:it.guess, yaw:it.yaw, pres:it.pres, person:it.person, clip:it.clip};
 const a=document.createElement('a');
 a.href=URL.createObjectURL(new Blob([JSON.stringify(out,null,1)],{type:'application/json'}));
 a.download='pose_labels.json'; a.click();
 };
 render();
 </script>
 """
 out = "labelling/pose_review.html"
 open(out, "w").write(HTML.replace("__PAYLOAD__", payload))
 from collections import Counter
 print(f"{out}  {os.path.getsize(out)/1e6:.1f} MB  {len(items)} crops", file=sys.stderr)
 print(f"estimate: {dict(Counter(i['guess'] for i in items))}", file=sys.stderr)
 print("\nestimated pose per person (does this match what you see?):", file=sys.stderr)
 for p in sorted({i["person"] for i in items}):
    for clip in CLIPS:
        sub = [i for i in items if i["person"] == p and i["clip"] == clip]
        if sub:
            print(f"   {p} {clip[-3:]}: {dict(Counter(i['guess'] for i in sub))}",
                  file=sys.stderr)
 print(f"\nopen file://{os.path.abspath(out)}", file=sys.stderr)
@@ -1,242 +0,0 @@
 #!/usr/bin/env python3
 """Propose person labels for one clip using another clip's hand-sorted labels.
 Reads the clip you have already sorted (REF_CLIP) as ground truth, then proposes
 a person for every crop in the other clip (TARGET_CLIP) and writes them into
 matching folders for you to correct.
    python3 propose_labels.py                  # propose, write folders + sheets
    python3 propose_labels.py --dry-run        # report only, move nothing
 Output:
    labelling/<target>/unsorted/A|B|C|D/       proposed, same names as the ref clip
    labelling/<target>/unsorted/               left in place when no person is
                                               confident enough to name
    labelling/review_<person>.jpg              contact sheet spanning BOTH clips:
                                               confirmed crops first, then
                                               proposed ones with their P
 Correcting it: open a review sheet. Every face on it should be one person. The
 lower block is the proposal — move any intruder to the right folder, or back to
 unsorted/. The folder a file sits in is the ground truth; nothing downstream
 reads the proposed name or its probability.
 The proposal is a labelling aid, never the label. Scoring the sweep against
 embedding-derived labels would be circular: it keeps the faces the embedder
 already gets right and drops the hard ones the sweep exists to find. Your
 correction is what breaks that loop, which is why the proposal is deliberately
 conservative and leaves anything doubtful unnamed.
 Assignment is on the calibrated probability, per-actor best-of-N, exactly as
 identity_matcher_node does — never a bare cosine (AR-024). The calibration is
 fitted on your labelled reference crops, which is what calibrate_gallery is for.
 """
 import sys, glob, json, os, shutil
 import numpy as np
 import cv2
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 # The embedder and the gallery whose calibration scores it MUST be the same
 # model: a Platt fit is specific to one embedding space, so LVFace probabilities
 # read through an ArcFace fit are meaningless.
 EMBEDDER = M + "LVFace-B_Glint360K.onnx"
 GALLERY  = ROOT + "gallery_lvface.h5"      # 291 actors, cached fit
 REF_CLIP, TARGET_CLIP = "5157344", "5157339"
 ASSIGN_P  = 0.90      # propose a name only when this confident
 SHEET_COLS = 8
 THUMB = 150
 DRY = "--dry-run" in sys.argv
 eng = sae_embed.FaceEmbedder(detector_model=M + "scrfd_500m_bnkps.onnx",
                             arcface_model=EMBEDDER,
                             conf=0.5, nms=0.4, max_side=0)
 def embed_manifest(clip):
    """Re-derive each dumped crop's embedding from its source frame, cached.
    The dumped .jpg is a context thumbnail for human eyes; the embedding must
    come from the aligned crop the pipeline would actually produce, so the
    frame is re-detected and the manifest's idx picks the same face.
    Detecting 24 4K frames per clip costs far more than the rest of this script
    put together, and the result only changes when the manifest does — so it is
    cached and keyed on the manifest's mtime. Delete cache/ to force a redo.
    """
    man_path = f"labelling/{clip}/manifest.json"
    cache_path = f"cache/emb_{clip}.npz"
    os.makedirs("cache", exist_ok=True)
    if os.path.exists(cache_path) and \
       os.path.getmtime(cache_path) >= os.path.getmtime(man_path):
        z = np.load(cache_path, allow_pickle=True)
        print(f"[cache] {clip}: {len(z['meta'])} embeddings reused", file=sys.stderr)
        return [{**m, "emb": e} for m, e in zip(z["meta"], z["emb"])]
    man = json.load(open(man_path))
    by_frame = {}
    for m in man:
        by_frame.setdefault(m["frame"], []).append(m)
    out = []
    for frame, ms in sorted(by_frame.items()):
        img = cv2.imread(f"frames/d{clip}_{frame}.png")
        if img is None:
            sys.exit(f"missing frames/d{clip}_{frame}.png — extract with\n"
                     f"  ffmpeg -i clips/{clip}.mp4 -vf fps=2 -frames:v 24 "
                     f"frames/d{clip}_%03d.png")
        dets = eng.detect(img)
        for m in ms:
            if m["idx"] >= len(dets):
                continue
            d = dets[m["idx"]]
            lm = np.array(d.landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm)
            if crop is None:
                continue
            out.append({**m, "emb": np.asarray(eng.embed_crop(crop), dtype=np.float32)})
    np.savez(cache_path,
             meta=np.array([{k: v for k, v in o.items() if k != "emb"} for o in out],
                           dtype=object),
             emb=np.stack([o["emb"] for o in out]))
    print(f"[cache] {clip}: {len(out)} embeddings written to {cache_path}",
          file=sys.stderr)
    return out
 def sorted_dirs(clip):
    """Person folders you created, wherever you put them under labelling/<clip>."""
    found = {}
    for path in glob.glob(f"labelling/{clip}/**/", recursive=True):
        name = os.path.basename(path.rstrip("/"))
        if name in ("unsorted", "discard") or name.startswith("5157"):
            continue
        files = [os.path.basename(f) for f in glob.glob(path + "*.jpg")]
        if files:
            found[name] = files
    return found
 # ── reference side: your labels ──────────────────────────────────────────────
 ref_rows = embed_manifest(REF_CLIP)
 ref_dirs = sorted_dirs(REF_CLIP)
 if not ref_dirs:
    sys.exit(f"no person folders under labelling/{REF_CLIP} — sort that clip first")
 file_to_person = {f: p for p, fs in ref_dirs.items() for f in fs}
 ref = [(file_to_person[r["file"]], r["emb"]) for r in ref_rows
       if r["file"] in file_to_person]
 people = sorted({p for p, _ in ref})
 print(f"[ref] {REF_CLIP}: {len(ref)} labelled crops over {len(people)} people "
      f"{ {p: sum(1 for q, _ in ref if q == p) for p in people} }", file=sys.stderr)
 R = np.stack([e for _, e in ref])
 r_actor = [people.index(p) for p, _ in ref]
 # The global gallery's sigmoid — NOT a fit over these four people. A Platt fit
 # over a handful of identities saturates: it will hand back P=0.99 for faces it
 # has no basis to separate, which is exactly how a wrong label acquires a
 # convincing probability. The production fit spans the whole actor population,
 # so a probability means the same thing here as it does in the matcher.
 cal = sae_embed.gallery_calibration(GALLERY)
 print(f"[calibration] global: {cal}  assign boundary = sim "
      f"{cal.boundary_at(ASSIGN_P):.4f}", file=sys.stderr)
 # ── target side: propose ─────────────────────────────────────────────────────
 tgt_rows = embed_manifest(TARGET_CLIP)
 T = np.stack([t["emb"] for t in tgt_rows])
 r_actor_arr = np.asarray(r_actor)
 # per-actor best-of-N for every target crop at once: (n_people, n_target)
 best_sim = np.stack([(R[r_actor_arr == people.index(p)] @ T.T).max(axis=0)
                     for p in people])
 proposals = []
 for j, t in enumerate(tgt_rows):
    k = int(np.argmax(best_sim[:, j]))
    prob = cal.probability(float(best_sim[k, j]))       # calibrated, never a bare cosine
    proposals.append({**t, "person": people[k] if prob >= ASSIGN_P else None,
                      "p": prob, "top1": people[k]})
 # At the production threshold the global fit stays silent on most of these
 # faces, which is the honest answer for profile and downward-gaze shots — but a
 # labelling aid wants throughput, not caution. --all proposes the top-1 person
 # for every crop and orders the review sheets by descending probability, so the
 # proposals degrade visibly down the sheet and you can stop correcting where
 # they stop being right. The probability is shown, never hidden.
 if "--all" in sys.argv:
    for x in proposals:
        x["person"] = x["top1"]
 named = [x for x in proposals if x["person"]]
 print(f"[propose] {TARGET_CLIP}: {len(named)}/{len(proposals)} named at P>={ASSIGN_P}; "
      f"{len(proposals) - len(named)} left unsorted", file=sys.stderr)
 for p in people:
    got = [x for x in named if x["person"] == p]
    if got:
        ps = [x["p"] for x in got]
        print(f"   {p}: {len(got):>3} crops   P {min(ps):.3f}–{max(ps):.3f}", file=sys.stderr)
 if DRY:
    sys.exit(0)
 # ── write proposed folders, mirroring the ref clip's layout ──────────────────
 ref_parent = os.path.dirname(next(iter(glob.glob(f"labelling/{REF_CLIP}/**/{people[0]}/",
                                                 recursive=True))).rstrip("/"))
 tgt_parent = ref_parent.replace(REF_CLIP, TARGET_CLIP)
 for p in people:
    d = f"{tgt_parent}/{p}"
    if os.path.isdir(d):                # never clobber corrections already made
        print(f"[skip] {d} exists — leaving your sorting alone", file=sys.stderr)
        continue
    os.makedirs(d, exist_ok=True)
 def find_crop(clip, fname):
    """Locate a crop wherever it currently sits under labelling/<clip>."""
    hits = glob.glob(f"labelling/{clip}/**/{fname}", recursive=True)
    return hits[0] if hits else None
 moved = 0
 for x in named:
    src = find_crop(TARGET_CLIP, x["file"])
    dst = f"{tgt_parent}/{x['person']}/{x['file']}"
    if src and os.path.abspath(src) != os.path.abspath(dst):
        shutil.move(src, dst)
        moved += 1
 print(f"[write] moved {moved} crops into proposed folders", file=sys.stderr)
 # ── review sheets: confirmed block, then proposed block ─────────────────────
 def load(clip, person, fname):
    for cand in glob.glob(f"labelling/{clip}/**/{person}/{fname}", recursive=True):
        return cv2.imread(cand)
    return None
 for person in people:
    conf = [(REF_CLIP, f, None) for f in ref_dirs.get(person, [])]
    prop = sorted([(TARGET_CLIP, x["file"], x["p"]) for x in named
                   if x["person"] == person],
                  key=lambda t: -t[2])          # most confident first
    items = conf + prop
    if not items:
        continue
    rows_n = (len(items) + SHEET_COLS - 1) // SHEET_COLS
    sheet = np.full((rows_n * (THUMB + 26), SHEET_COLS * THUMB, 3), 30, np.uint8)
    for n, (clip, fname, p) in enumerate(items):
        img = load(clip, person, fname)
        if img is None:
            continue
        rr, cc = divmod(n, SHEET_COLS)
        y, x = rr * (THUMB + 26), cc * THUMB
        sheet[y:y + THUMB, x:x + THUMB] = cv2.resize(img, (THUMB, THUMB))
        if p is None:
            tag, col = f"{clip[-3:]} CONFIRMED", (170, 170, 170)
        else:
            tag, col = f"{clip[-3:]} P={p:.2f}", (140, 255, 140)
        cv2.putText(sheet, tag, (x + 3, y + THUMB + 17),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.42, col, 1)
    cv2.imwrite(f"labelling/review_{person}.jpg", sheet)
    print(f"   review_{person}.jpg: {len(conf)} confirmed + {len(prop)} proposed",
          file=sys.stderr)
 json.dump({x["file"]: {"person": x["person"], "p": x["p"]} for x in proposals},
          open(f"labelling/proposed_{TARGET_CLIP}.json", "w"), indent=1)
@@ -1,55 +0,0 @@
 #!/usr/bin/env python3
 """Redraw every dumped crop with its detection box marked.
 The original thumbnails padded by 0.5x the face on each side for
 recognisability, which in a crowded frame pulls a neighbour into shot — often
 more prominently than the subject. A label cannot be corrected from a picture
 that does not say which face it refers to.
 This rewrites each .jpg IN PLACE, wherever it currently sits, so any sorting
 already done is preserved: only the pixels change, never the filename or the
 folder. Re-run it after dump_faces.py, and re-check any sorting done before it.
 """
 import glob, json, os, sys
 import cv2
 CLIPS = ["5157339", "5157344"]
 OUT = 256
 for clip in CLIPS:
    man = {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
    n = 0
    for path in glob.glob(f"labelling/{clip}/**/*.jpg", recursive=True):
        fname = os.path.basename(path)
        m = man.get(fname)
        if m is None:
            continue
        img = cv2.imread(f"frames/d{clip}_{m['frame']}.png")
        if img is None:
            sys.exit(f"missing frames/d{clip}_{m['frame']}.png")
        x, y, w, h = (int(v) for v in m["bbox"])
        pad = int(0.55 * max(w, h))
        x0, y0 = max(0, x - pad), max(0, y - pad)
        x1, y1 = min(img.shape[1], x + w + pad), min(img.shape[0], y + h + pad)
        sub = img[y0:y1, x0:x1].copy()
        # Box in the sub-image's coordinates, drawn before the resize so the
        # line lands exactly on the face at any output size.
        cv2.rectangle(sub, (x - x0, y - y0), (x - x0 + w, y - y0 + h), (0, 0, 255), 3)
        # Dim everything outside the box so the subject is unmistakable even
        # when a neighbour's face is larger or better lit.
        mask = sub.copy()
        mask[y - y0:y - y0 + h, x - x0:x - x0 + w] = 0
        sub = cv2.addWeighted(sub, 1.0, mask, -0.35, 0)
        scale = OUT / max(sub.shape[:2])
        sub = cv2.resize(sub, (int(sub.shape[1] * scale), int(sub.shape[0] * scale)))
        canvas = cv2.copyMakeBorder(
            sub, 0, max(0, OUT - sub.shape[0]), 0, max(0, OUT - sub.shape[1]),
            cv2.BORDER_CONSTANT, value=(20, 20, 20))[:OUT, :OUT]
        cv2.putText(canvas, f"{int(m['px'])}px", (5, OUT - 8),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.45, (0, 255, 255), 1)
        cv2.imwrite(path, canvas)
        n += 1
    print(f"[{clip}] redrew {n} crops in place", file=sys.stderr)
@@ -1,184 +0,0 @@
 #!/usr/bin/env python3
 """Impact of input resolution on cross-source identification.
 TRACES: VR-013 | PR-002
 Gallery is built from one clip at NATIVE resolution. Probes come from the other
 clip with the WHOLE FRAME downscaled before it reaches the detector, so
 detection and landmark regression degrade together with the pixels. That is the
 measurement VR-005 structurally could not make: it degraded an already-aligned
 112x112 crop, holding alignment perfect, so it isolated the embedder's
 resolution sensitivity and excluded everything upstream of it.
    python3 resolution_sweep.py [--gallery-clip 5157339] [--detector scrfd_500m_bnkps.onnx]
 Ground truth
 ------------
 Hand-sorted person folders. Probe detections at reduced scale are tied back to
 a labelled face GEOMETRICALLY — the box is mapped to native coordinates and
 matched by IoU. Never by embedding similarity, which would be circular: it
 would keep the faces the embedder still gets right and silently drop the ones
 this sweep exists to find.
 A probe whose label is only in the probe clip is OUT OF GALLERY. Naming it is a
 true out-of-cast misID, the error the per-scene scorer weights 10x, so it is
 counted separately from naming the wrong gallery member.
 Metric
 ------
 The calibrated probability from the PRODUCTION gallery sigmoid, never a raw
 cosine (AR-024). Per-actor best-of-N similarity -> probability -> accept above
 prob_threshold. This is identification, so the matcher's prior applies;
 config.hpp has match_prior 0.5, i.e. log_prior_odds = 0.
 Everything runs through the shipped C++ via sae_embed.
 """
 import sys, glob, json, os, argparse
 import numpy as np
 import cv2
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 PROB_THRESHOLD = 0.754      # config.hpp:67
 LOG_PRIOR_ODDS = 0.0        # config.hpp:61 match_prior=0.5
 IOU_MIN = 0.3               # geometric label carry-down
 SCALES = [1.0, 0.8, 0.6, 0.5, 0.4, 0.3, 0.25, 0.2, 0.15, 0.12, 0.09, 0.06]
 ap = argparse.ArgumentParser()
 ap.add_argument("--gallery-clip", default="5157339")
 ap.add_argument("--probe-clip", default="5157344")
 ap.add_argument("--detector", default="scrfd_500m_bnkps.onnx")
 ap.add_argument("--embedder", default="LVFace-B_Glint360K.onnx")
 ap.add_argument("--gallery-calibration", default=ROOT + "gallery_lvface.h5")
 ap.add_argument("--out", default="results_resolution_sweep.json")
 args = ap.parse_args()
 eng = sae_embed.FaceEmbedder(detector_model=M + args.detector,
                             arcface_model=M + args.embedder,
                             conf=0.5, nms=0.4, max_side=0)
 cal = sae_embed.gallery_calibration(args.gallery_calibration)
 print(f"[calibration] global: {cal}", file=sys.stderr)
 def labelled(clip):
    """{filename: person} from the hand-sorted folders, ignoring discard."""
    out = {}
    for path in glob.glob(f"labelling/{clip}/*/*.jpg"):
        person = os.path.basename(os.path.dirname(path))
        if person in ("discard", "unsorted"):
            continue
        out[os.path.basename(path)] = person
    return out
 def manifest(clip):
    return {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
 def iou(a, b):
    ax, ay, aw, ah = a; bx, by, bw, bh = b
    x0, y0 = max(ax, bx), max(ay, by)
    x1, y1 = min(ax + aw, bx + bw), min(ay + ah, by + bh)
    if x1 <= x0 or y1 <= y0:
        return 0.0
    inter = (x1 - x0) * (y1 - y0)
    return inter / (aw * ah + bw * bh - inter)
 # ── gallery: native resolution, labelled faces only ──────────────────────────
 g_lab, g_man = labelled(args.gallery_clip), manifest(args.gallery_clip)
 gal = {}
 for frame in sorted({g_man[f]["frame"] for f in g_lab}):
    img = cv2.imread(f"frames/d{args.gallery_clip}_{frame}.png")
    dets = eng.detect(img)
    for fname, person in g_lab.items():
        m = g_man[fname]
        if m["frame"] != frame or m["idx"] >= len(dets):
            continue
        lm = np.array(dets[m["idx"]].landmarks, dtype=np.float32).reshape(5, 2)
        crop = sae_embed.align_face(img, lm)
        if crop is None:
            continue
        gal.setdefault(person, []).append(np.asarray(eng.embed_crop(crop), dtype=np.float32))
 gal = {p: np.stack(v) for p, v in gal.items() if v}
 people = sorted(gal)
 print(f"[gallery] {args.gallery_clip} @native: "
      f"{ {p: len(v) for p, v in gal.items()} }", file=sys.stderr)
 # ── probe ground truth at native resolution ──────────────────────────────────
 p_lab, p_man = labelled(args.probe_clip), manifest(args.probe_clip)
 truth = {}          # frame -> [(bbox_native, person)]
 for fname, person in p_lab.items():
    m = p_man[fname]
    truth.setdefault(m["frame"], []).append((m["bbox"], person))
 n_out = sum(1 for p in set(p_lab.values()) if p not in people)
 print(f"[probe] {args.probe_clip}: {len(p_lab)} labelled faces, "
      f"{len(set(p_lab.values()))} people, {n_out} of them out-of-gallery",
      file=sys.stderr)
 # ── sweep ────────────────────────────────────────────────────────────────────
 print(f"\n{'scale':>6}{'frame':>11}{'face px':>9}{'found':>7}{'matched':>9}"
      f"{'TPI':>8}{'FPI-in':>8}{'FPI-out':>9}{'TBI':>8}")
 results = []
 for s in SCALES:
    tpi = fpi_in = fpi_out = tbi = 0
    n_found = n_matched = 0
    pxs = []
    for frame, gts in sorted(truth.items()):
        img = cv2.imread(f"frames/d{args.probe_clip}_{frame}.png")
        if s != 1.0:
            img = cv2.resize(img, None, fx=s, fy=s, interpolation=cv2.INTER_AREA)
        dets = eng.detect(img)
        n_found += len(dets)
        for d in dets:
            x, y, w, h = d.bbox
            native = (x / s, y / s, w / s, h / s)       # geometric carry-down
            best, best_iou = None, 0.0
            for gt_box, person in gts:
                v = iou(native, gt_box)
                if v > best_iou:
                    best_iou, best = v, person
            if best_iou < IOU_MIN:
                continue                                 # spurious / unlabelled
            n_matched += 1
            pxs.append(min(w, h))
            lm = np.array(d.landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm)
            if crop is None:
                tbi += 1                                 # degenerate alignment
                continue
            emb = np.asarray(eng.embed_crop(crop), dtype=np.float32)
            best_p, best_name = 0.0, None
            for p in people:                             # per-actor best-of-N
                prob = cal.probability(float((gal[p] @ emb).max()), LOG_PRIOR_ODDS)
                if prob > best_p:
                    best_p, best_name = prob, p
            if best_p <= PROB_THRESHOLD:
                tbi += 1
            elif best not in people:
                fpi_out += 1                             # named someone absent from the gallery
            elif best_name == best:
                tpi += 1
            else:
                fpi_in += 1
    n = max(1, n_matched)
    med_px = float(np.median(pxs)) if pxs else 0.0
    print(f"{s:>6.2f}{f'{int(4096*s)}x{int(2160*s)}':>11}{med_px:>9.0f}"
          f"{n_found:>7}{n_matched:>9}"
          f"{100*tpi/n:>7.1f}%{100*fpi_in/n:>7.1f}%{100*fpi_out/n:>8.1f}%{100*tbi/n:>7.1f}%")
    results.append({"scale": s, "median_face_px": med_px, "detections": n_found,
                    "matched_to_truth": n_matched, "tpi_pct": 100*tpi/n,
                    "fpi_in_gallery_pct": 100*fpi_in/n, "fpi_out_of_gallery_pct": 100*fpi_out/n,
                    "tbi_pct": 100*tbi/n})
 json.dump({"gallery_clip": args.gallery_clip, "probe_clip": args.probe_clip,
           "detector": args.detector, "embedder": args.embedder,
           "prob_threshold": PROB_THRESHOLD, "log_prior_odds": LOG_PRIOR_ODDS,
           "calibration": {"a": cal.a, "b": cal.b},
           "gallery_people": people, "results": results},
          open(args.out, "w"), indent=2)
 print(f"\nwrote {args.out}", file=sys.stderr)
@@ -1,175 +0,0 @@
 #!/usr/bin/env python3
 """Integrity check on the labelled set, before it is used as ground truth.
 TRACES: VR-013 | PR-002
 VR-013's ground truth is hand-sorted rather than propagated by embedding
 similarity, because propagation would keep only the faces the embedder already
 gets right and silently drop the ones the sweep exists to find. This script is
 what makes that claim checkable, so it is part of the requirement rather than a
 helper of it.
 Checks, loudest failure first:
 1. INDEX INTEGRITY. Each crop's embedding is taken by re-detecting its source
   frame and indexing with the manifest's `idx`. If detection order is not
   reproducible, the thumbnail you sorted and the embedding that gets scored
   are different faces — you would see a correct picture and score the wrong
   person, with nothing to signal it. Every crop's re-detected bbox is compared
   against the manifest's.
 2. NO CROP IN TWO FOLDERS, and every manifest entry accounted for — so a
   move that half-completed cannot silently duplicate or drop a label.
 3. ALIGNMENT. The 112x112 warp is what the embedder actually sees; the
   thumbnail is only context for your eyes. verify_<person>.jpg pairs them:
   context-with-box on top, the real aligned crop beneath. A profile face whose
   alignment has collapsed is obvious there and nowhere else.
 4. SEPARATION. Per person, the calibrated P of their own crops against the
   other people's, using the global gallery sigmoid. A label set where someone
   matches another person better than themselves is mislabelled.
 Nothing here changes a label. It reports.
 """
 import sys, glob, json, os
 import numpy as np
 import cv2
 sys.path.insert(0, "/home/dtourolle/Development/Jray-project/scene-actor-extraction/build-ort")
 import sae_embed
 ROOT = "/home/dtourolle/Development/Jray-project/scene-actor-extraction/"
 M = ROOT + "models/"
 EMBEDDER = M + "LVFace-B_Glint360K.onnx"
 GALLERY  = ROOT + "gallery_lvface.h5"
 CLIPS = ["5157344", "5157339"]
 THUMB = 130
 COLS = 10
 eng = sae_embed.FaceEmbedder(detector_model=M + "scrfd_500m_bnkps.onnx",
                             arcface_model=EMBEDDER, conf=0.5, nms=0.4, max_side=0)
 fail = 0
 rows = []
 for clip in CLIPS:
    man = {m["file"]: m for m in json.load(open(f"labelling/{clip}/manifest.json"))}
    # where each crop currently sits -> its label
    placed = {}
    for path in glob.glob(f"labelling/{clip}/*/*.jpg"):
        person = os.path.basename(os.path.dirname(path))
        if person in ("discard", "unsorted"):
            continue   # not people; scoring them would invent an extra identity
        fname = os.path.basename(path)
        if fname in placed:
            print(f"[FAIL] {fname} appears in both {placed[fname][0]} and {person}")
            fail += 1
        placed[fname] = (person, path)
    missing = set(man) - set(placed)
    extra = set(placed) - set(man)
    if missing:
        print(f"[warn] {clip}: {len(missing)} manifest crops not in any folder")
    if extra:
        print(f"[FAIL] {clip}: {len(extra)} files with no manifest entry: "
              f"{sorted(extra)[:3]}")
        fail += 1
    # index integrity + alignment, frame by frame
    by_frame = {}
    for fname, (person, path) in placed.items():
        if fname in man:
            by_frame.setdefault(man[fname]["frame"], []).append((fname, person, path))
    bad_idx = 0
    for frame, items in sorted(by_frame.items()):
        img = cv2.imread(f"frames/d{clip}_{frame}.png")
        if img is None:
            print(f"[FAIL] missing frames/d{clip}_{frame}.png")
            fail += 1
            continue
        dets = eng.detect(img)
        for fname, person, path in items:
            m = man[fname]
            i = m["idx"]
            if i >= len(dets):
                print(f"[FAIL] {fname}: idx {i} >= {len(dets)} detections now")
                bad_idx += 1
                continue
            got = [float(v) for v in dets[i].bbox]
            want = m["bbox"]
            if max(abs(a - b) for a, b in zip(got, want)) > 1.0:
                print(f"[FAIL] {fname}: manifest bbox {[round(v) for v in want]} "
                      f"!= re-detected {[round(v) for v in got]}")
                bad_idx += 1
                continue
            lm = np.array(dets[i].landmarks, dtype=np.float32).reshape(5, 2)
            crop = sae_embed.align_face(img, lm)
            if crop is None:
                print(f"[warn] {fname}: alignment degenerate, no crop reaches the embedder")
                continue
            rows.append({"clip": clip, "person": person, "file": fname, "path": path,
                         "px": m["px"], "aligned": np.asarray(crop),
                         "emb": np.asarray(eng.embed_crop(crop), dtype=np.float32)})
    fail += bad_idx
    print(f"[{clip}] {len(placed)} placed, {len(by_frame)} frames, "
          f"index mismatches: {bad_idx}")
 if not rows:
    sys.exit("nothing to verify")
 # ── separation, through the global gallery sigmoid ───────────────────────────
 cal = sae_embed.gallery_calibration(GALLERY)
 E = np.stack([r["emb"] for r in rows])
 people = sorted({r["person"] for r in rows})
 lab = np.array([people.index(r["person"]) for r in rows])
 S = E @ E.T
 np.fill_diagonal(S, -1.0)
 print(f"\n{'person':>8}{'crops':>7}{'344':>6}{'339':>6}"
      f"{'P(self)':>10}{'P(other)':>10}{'worst':>8}")
 for k, p in enumerate(people):
    mine = np.where(lab == k)[0]
    if len(mine) < 2:
        continue
    self_sim = S[np.ix_(mine, mine)].max(axis=1)
    other_sim = S[np.ix_(mine, np.where(lab != k)[0])].max(axis=1)
    p_self = np.array([cal.probability(float(s)) for s in self_sim])
    p_other = np.array([cal.probability(float(s)) for s in other_sim])
    n344 = sum(1 for i in mine if rows[i]["clip"] == "5157344")
    n339 = len(mine) - n344
    # a crop that matches someone else better than anyone of its own label
    worst = int((other_sim > self_sim).sum())
    print(f"{p:>8}{len(mine):>7}{n344:>6}{n339:>6}"
          f"{np.median(p_self):>10.3f}{np.median(p_other):>10.3f}{worst:>8}")
    if worst:
        for i in mine[other_sim > self_sim]:
            print(f"          suspect: {rows[i]['file']}  "
                  f"P(self)={cal.probability(float(self_sim[list(mine).index(i)])):.3f} "
                  f"< P(other)={cal.probability(float(other_sim[list(mine).index(i)])):.3f}")
 # ── verify sheets: context+box over the actual aligned crop ──────────────────
 for p in people:
    items = [r for r in rows if r["person"] == p]
    items.sort(key=lambda r: (r["clip"], r["file"]))
    n = len(items)
    sheet_rows = (n + COLS - 1) // COLS
    H = THUMB * 2 + 22
    sheet = np.full((sheet_rows * H, COLS * THUMB, 3), 25, np.uint8)
    for j, r in enumerate(items):
        rr, cc = divmod(j, COLS)
        y, x = rr * H, cc * THUMB
        ctx = cv2.imread(r["path"])
        if ctx is not None:
            sheet[y:y + THUMB, x:x + THUMB] = cv2.resize(ctx, (THUMB, THUMB))
        sheet[y + THUMB:y + 2 * THUMB, x:x + THUMB] = cv2.resize(r["aligned"], (THUMB, THUMB))
        cv2.putText(sheet, f"{r['clip'][-3:]} {int(r['px'])}px",
                    (x + 3, y + 2 * THUMB + 15),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.38, (150, 220, 150), 1)
    cv2.imwrite(f"labelling/verify_{p}.jpg", sheet)
    print(f"  verify_{p}.jpg: {n} crops (top row context, bottom row what the embedder sees)")
 print(f"\n{'PASS' if fail == 0 else f'{fail} FAILURES'}")
 sys.exit(1 if fail else 0)
@@ -35,7 +35,6 @@ extra_css:
 nav:
  - Home: index.md
  - How We Score Against X-Ray: methodology.md
  - Benchmark — SuperHero: benchmark.md
  - Findings:
    - Best Model: best-model.md
    - Gallery Scope (Full vs. Limited): gallery-scope.md
@@ -10,9 +10,7 @@
 #   scripts/artifacts/pull_artifacts.sh galleries [version]
 #   scripts/artifacts/pull_artifacts.sh montage-frames <film-slug> [version]
 #   scripts/artifacts/pull_artifacts.sh experiment-data [version]
 #   scripts/artifacts/pull_artifacts.sh replay-fixtures [version]
 #   scripts/artifacts/pull_artifacts.sh report-highlights <name> [version]
 #   scripts/artifacts/pull_artifacts.sh xsource [version]
 # version defaults to "latest" (newest uploaded version, by created_at).
 set -euo pipefail
@@ -43,22 +41,6 @@ print(matches[-1]['version'])
 "
 }
 pull_replay_fixtures() {
    local version="$1"
    local dest="${REPO_ROOT}/tests/fixtures/dumps"
    mkdir -p "$dest"
    echo "=== replay-fixtures (version ${version}) ==="
    local tmp; tmp="$(mktemp -d)"
    if curl -sf "${DL_BASE}/generic/replay-fixtures/${version}/replay-fixtures.zip" \
            -o "${tmp}/f.zip"; then
        unzip -qo "${tmp}/f.zip" -d "$dest"
        echo "  restored: $(ls "$dest" | wc -l) files into tests/fixtures/dumps/"
    else
        echo "    [warn] replay-fixtures.zip not found at version ${version}" >&2
    fi
    rm -rf "$tmp"
 }
 pull_galleries() {
    local version="$1"
    local dest="${REPO_ROOT}/experiments/galleries"
@@ -101,71 +83,11 @@ pull_report_highlight() {
    curl -sf "${DL_BASE}/generic/report-highlights/${version}/${name}" -o "${dest}/${name}"
 }
 pull_xsource() {
    local version="$1"
    local dest="${REPO_ROOT}/experiments/xsource"
    echo "=== xsource (version ${version}) ==="
    mkdir -p "${dest}/clips" "${dest}/frames"
    for clip in 5157339 5157344; do
        if [ -f "${dest}/clips/${clip}.mp4" ]; then
            echo "  ${clip}.mp4 already present, skipping"
        else
            echo "  fetching ${clip}.mp4..."
            curl -sf "${DL_BASE}/generic/xsource/${version}/${clip}.mp4" \
                -o "${dest}/clips/${clip}.mp4" \
                || { echo "    [warn] ${clip}.mp4 not found at version ${version}" >&2; continue; }
        fi
    done
    if [ -d "${dest}/labelling" ]; then
        echo "  labelling/ already present — NOT overwriting (it is hand-sorted"
        echo "  ground truth; move it aside first if you really want the remote copy)"
    else
        echo "  fetching labelling.zip..."
        local tmp; tmp="$(mktemp)"
        curl -sf "${DL_BASE}/generic/xsource/${version}/labelling.zip" -o "$tmp"
        unzip -qo "$tmp" -d "$dest"
        rm "$tmp"
    fi
    # Frames are regenerated rather than shipped: they are ~320 MB of PNG that
    # ffmpeg reproduces exactly from the clips. The manifests key on these
    # filenames and on detection order within each frame, so the extraction
    # settings must match the ones dump_faces.py ran against — hence fps and
    # frame count are pinned here rather than left to the caller.
    if ! command -v ffmpeg >/dev/null; then
        echo "  [warn] ffmpeg not found — frames not regenerated; the study" >&2
        echo "         scripts will fail until you extract them" >&2
        return
    fi
    for clip in 5157339 5157344; do
        [ -f "${dest}/clips/${clip}.mp4" ] || continue
        if [ -f "${dest}/frames/d${clip}_001.png" ]; then
            echo "  frames for ${clip} already present, skipping"
            continue
        fi
        echo "  extracting frames for ${clip}..."
        ffmpeg -v error -i "${dest}/clips/${clip}.mp4" -vf fps=2 -frames:v 24 \
            "${dest}/frames/d${clip}_%03d.png"
    done
    echo "  verifying the labelled set..."
    if (cd "$dest" && python3 verify_labels.py >/dev/null 2>&1); then
        echo "    verify_labels.py passed"
    else
        echo "    [warn] verify_labels.py failed — run it directly to see why." >&2
        echo "           A frame/manifest mismatch means the extraction settings" >&2
        echo "           differ from the ones the crops were dumped against." >&2
    fi
 }
 if [ $# -eq 0 ]; then
    echo "usage: $0 galleries [version]" >&2
    echo "       $0 montage-frames <film-slug> [version]" >&2
    echo "       $0 experiment-data [version]" >&2
    echo "       $0 report-highlights <name> [version]" >&2
    echo "       $0 xsource [version]" >&2
    exit 1
 fi
@@ -193,18 +115,8 @@ case "$TARGET" in
        [ "$VERSION" = "latest" ] && VERSION="$(resolve_latest_version report-highlights)"
        pull_report_highlight "$VERSION" "$NAME"
        ;;
    xsource)
        VERSION="${2:-latest}"
        [ "$VERSION" = "latest" ] && VERSION="$(resolve_latest_version xsource)"
        pull_xsource "$VERSION"
        ;;
    replay-fixtures)
        VERSION="${2:-latest}"
        [ "$VERSION" = "latest" ] && VERSION="$(resolve_latest_version replay-fixtures)"
        pull_replay_fixtures "$VERSION"
        ;;
    *)
-        echo "unknown target: $TARGET (expected galleries, montage-frames, experiment-data, report-highlights, xsource, or replay-fixtures)" >&2
+        echo "unknown target: $TARGET (expected galleries, montage-frames, experiment-data, or report-highlights)" >&2
        exit 1
        ;;
 esac
@@ -12,13 +12,10 @@
 #   scripts/artifacts/push_artifacts.sh montage-frames
 #   scripts/artifacts/push_artifacts.sh experiment-data
 #   scripts/artifacts/push_artifacts.sh report-highlights
 #   scripts/artifacts/push_artifacts.sh xsource
 #   scripts/artifacts/push_artifacts.sh replay-fixtures
 #   scripts/artifacts/push_artifacts.sh galleries montage-frames experiment-data report-highlights
 #
 # Package layout (owner=dtourolle, repo=scene-actor-extraction):
 #   generic/galleries/<version>/gallery_<model>.h5        (one file per model)
 #   generic/replay-fixtures/<version>/replay-fixtures.zip (T2 dumps + their gallery)
 #   generic/montage-frames/<version>/<film-slug>.zip      (zipped per-film frames)
 #   generic/experiment-data/<version>/experiment-data.zip (manifests/trajectories/results)
 #   generic/report-highlights/<version>/<name>.jpg        (individual, hand-picked
@@ -52,29 +49,6 @@ upload() {
        -o /dev/null -w "    HTTP %{http_code}\n"
 }
 push_replay_fixtures() {
    echo "=== replay-fixtures (version ${VERSION}) ==="
    # T2 replay fixtures: per-frame detections, landmarks and embeddings dumped
    # from a real run, so the tracker and identity stages can be replayed on CPU
    # with no GPU, no models and no film. Too large for git (superhero.h5 alone
    # is ~9 MB) and regenerating them needs the film plus a GPU, which CI has
    # neither of — so they ship as artifacts and CI pulls them.
    #
    # The gallery travels with them: a dump replays against the gallery it was
    # produced with, and pairing a dump with a different gallery silently
    # changes every identity decision in it.
    local dir="${REPO_ROOT}/tests/fixtures/dumps"
    if [ ! -d "$dir" ]; then
        echo "  no tests/fixtures/dumps dir, skipping" >&2
        return
    fi
    local tmp
    tmp="$(mktemp -d)"
    ( cd "$dir" && zip -qr "$tmp/replay-fixtures.zip" . )
    upload "replay-fixtures" "replay-fixtures.zip" "$tmp/replay-fixtures.zip"
    rm -rf "$tmp"
 }
 push_galleries() {
    echo "=== galleries (version ${VERSION}) ==="
    local dir="${REPO_ROOT}/experiments/galleries"
@@ -135,35 +109,8 @@ push_report_highlights() {
    upload "report-highlights" "germar_beats_xray.jpg" "$src"
 }
 push_xsource() {
    echo "=== xsource (version ${VERSION}) ==="
    local root="${REPO_ROOT}/experiments/xsource"
    if [ ! -d "$root/labelling" ]; then
        echo "  no experiments/xsource/labelling found, skipping" >&2
        return
    fi
    # Source recordings. Already compressed, so uploaded as-is rather than zipped.
    shopt -s nullglob
    for f in "$root"/clips/*.mp4; do
        upload "xsource" "$(basename "$f")" "$f"
    done
    shopt -u nullglob
    # The hand-sorted crops and their manifests. This is human ground truth and
    # the expensive part of the study — a person looked at every crop and put it
    # in a folder. Frames are deliberately NOT pushed: they are deterministic
    # from the clips, and pulling regenerates them.
    local tmp; tmp="$(mktemp -d)"
    trap 'rm -rf "$tmp"' RETURN
    local zipfile="${tmp}/labelling.zip"
    (cd "$root" && zip -qr "$zipfile" labelling -x 'labelling/*.html' -x 'labelling/review_*.jpg' \
        -x 'labelling/verify_*.jpg')
    upload "xsource" "labelling.zip" "$zipfile"
 }
 if [ $# -eq 0 ]; then
-    echo "usage: $0 <galleries|montage-frames|experiment-data|report-highlights|xsource> [...]" >&2
+    echo "usage: $0 <galleries|montage-frames|experiment-data|report-highlights> [...]" >&2
    exit 1
 fi
@@ -173,9 +120,7 @@ for target in "$@"; do
        montage-frames)     push_montage_frames ;;
        experiment-data)    push_experiment_data ;;
        report-highlights)  push_report_highlights ;;
-        xsource)            push_xsource ;;
+        *) echo "unknown target: $target (expected galleries, montage-frames, experiment-data, or report-highlights)" >&2; exit 1 ;;
        replay-fixtures)    push_replay_fixtures ;;
        *) echo "unknown target: $target (expected galleries, montage-frames, experiment-data, report-highlights, xsource, or replay-fixtures)" >&2; exit 1 ;;
    esac
 done
@@ -1,118 +0,0 @@
 #!/bin/bash
 # build_builder_image.sh — build and publish the DP-007 CI builder image to the
 # Gitea container registry.
 #
 # TRACES: DP-007 | PR-004
 #
 # Usage:
 #   scripts/ci/build_builder_image.sh                  # build only, tag v1
 #   scripts/ci/build_builder_image.sh --push           # build and push
 #   scripts/ci/build_builder_image.sh --tag v2 --push  # bump the pinned tag
 #   scripts/ci/build_builder_image.sh --no-cache       # force a clean rebuild
 #
 # The tag is the contract with CI. .gitea/workflows/unit-tests.yml names an
 # explicit tag in its `container:` block and never `latest`, so that rebuilding
 # the image cannot silently change what a previous green build meant. Bumping
 # the dependency set means bumping the tag AND editing the workflow — the two
 # edits landing in the same commit is the point, not an inconvenience.
 #
 # Registry auth: this script does not log in. Do it once, out of band:
 #   docker login gitea.tourolle.paris
 # The CI host is already authenticated this way (its cached credentials in
 # ~/.docker/config.json are what the kpnpp-builder push relies on), so a
 # workflow that calls this script needs no secret plumbing.
 set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 REGISTRY="gitea.tourolle.paris"
 OWNER="dtourolle"
 IMAGE="sae-builder-cpu"
 DOCKERFILE="Dockerfile.builder-cpu"
 # The tag CI pins to today. Keep this in step with the `container.image` line in
 # .gitea/workflows/unit-tests.yml; the workflow asserts at run time that the
 # image it landed in reports this same version, so a drift shows up as a failed
 # job rather than as a build against the wrong toolchain.
 TAG="v1"
 PUSH=0
 EXTRA_ARGS=()
 while [ $# -gt 0 ]; do
    case "$1" in
        --push)     PUSH=1 ;;
        --tag)      TAG="${2:?--tag needs a value}"; shift ;;
        --no-cache) EXTRA_ARGS+=(--no-cache) ;;
        -h|--help)  sed -n '2,30p' "${BASH_SOURCE[0]}"; exit 0 ;;
        *)          echo "error: unknown argument '$1'" >&2; exit 2 ;;
    esac
    shift
 done
 if [ "$TAG" = "latest" ]; then
    echo "error: refusing to build the tag 'latest'." >&2
    echo "DP-007 requires CI to pin an immutable tag. A moving 'latest' means a" >&2
    echo "rebuild retroactively changes what every earlier green build proved." >&2
    exit 2
 fi
 REF="${REGISTRY}/${OWNER}/${IMAGE}:${TAG}"
 # A second tag carrying the commit that produced the image. The workflow pins
 # the human-readable tag; this one is the audit trail — given any image you can
 # recover the Dockerfile that built it.
 SHA="$(git -C "$REPO_ROOT" rev-parse --short HEAD)"
 REF_SHA="${REGISTRY}/${OWNER}/${IMAGE}:${TAG}-${SHA}"
 # The Dockerfile COPYs nothing from the repository on purpose (see its closing
 # comment), so the build context is an empty directory rather than the repo
 # root. Sending ~1 GB of models, fixtures and experiment data to the daemon for
 # a build that reads none of it is pure latency.
 CONTEXT="$(mktemp -d)"
 trap 'rm -rf "$CONTEXT"' EXIT
 echo "=== building ${REF}"
 echo "    dockerfile: ${REPO_ROOT}/${DOCKERFILE}"
 echo "    context:    (empty — the image embeds no repository content)"
 echo
 echo "    Expect this to take a while: OpenCV 5 is compiled from source because"
 echo "    no Debian release ships it. That cost is paid once per image, which is"
 echo "    the entire reason DP-007 asks for a prebuilt image instead of"
 echo "    installing dependencies inside each CI run."
 echo
 docker build \
    "${EXTRA_ARGS[@]}" \
    --build-arg "IMAGE_TAG=${TAG}" \
    -f "${REPO_ROOT}/${DOCKERFILE}" \
    -t "${REF}" \
    -t "${REF_SHA}" \
    "${CONTEXT}"
 echo
 echo "=== built"
 docker image inspect "${REF}" --format '    {{.RepoTags}}  {{.Size}} bytes'
 docker run --rm "${REF}" sh -c 'echo "    SAE_BUILDER=$SAE_BUILDER version=$SAE_BUILDER_VERSION ort=$SAE_ORT_VERSION opencv=$SAE_OPENCV_VERSION"'
 if [ "$PUSH" -eq 0 ]; then
    echo
    echo "Not pushed. Re-run with --push, or push by hand:"
    echo "    docker push ${REF}"
    echo "    docker push ${REF_SHA}"
    exit 0
 fi
 echo
 echo "=== pushing"
 # No `latest` tag is pushed, by design. Publishing one invites a workflow to use
 # it, and DP-007 exists to prevent exactly that.
 docker push "${REF}"
 docker push "${REF_SHA}"
 echo
 echo "=== published ${REF}"
 echo "If this was a dependency-set change, bump the tag in"
 echo "    .gitea/workflows/unit-tests.yml   (container.image)"
 echo "    scripts/ci/build_builder_image.sh (TAG, above)"
 echo "in the same commit, so no run can build against an image the repository"
 echo "does not describe."
@@ -1,225 +0,0 @@
 #!/usr/bin/env python3
 """Enforce the AR-024 invariant: never a raw cosine, always the calibration.
 TRACES: AR-024 | SR-002
 docs/requirements.md gives AR-024's verification tier as "Static check -- no
 bare cosine outside a tagged EXCEPTION | Grep-based; this is the invariant's
 enforcement". This is that check. Until it existed the invariant was enforced
 by reading, and reading missed a live violation: the identity matcher's
 no-calibration fallback thresholded raw cosine distance and fed `max(0, cosine)`
 into the Bayesian accumulation as though it were a posterior.
 WHAT IT CHECKS, precisely, because a static check that overclaims its reach is
 worse than one with a stated scope:
  Every call to `cosine_similarity(...)` in C++ source must either
    (a) have its result consumed immediately by a calibration -- the call is
        textually wrapped in `cal_(...)`, `calibrate_(...)`, `.probability(...)`
        or similar; or
    (b) sit under an exception comment -- the token is `EXCEPTION:` followed by
        `AR-024` and a reason -- within EXCEPTION_SCOPE_LINES above it.
 Note that this file deliberately never spells that token out. The traceability
 extractor scans scripts/ as source, so prose here describing the tag would be
 counted as recorded exceptions; four of them were, until this was noticed. The
 same trap the shared config warns about for the vendored parser tests.
  Anything else is a defect, per CLAUDE.md: "treat any bare cosine comparison in
  the code as a defect to be fixed".
 WHAT IT DOES NOT CHECK, and why you should not read a pass as more than it is:
  - It cannot follow a cosine through a variable across statements. A file that
    stores `float s = cosine_similarity(a, b);` and compares `s` three lines
    later is not caught. The codebase does not currently do this, and this check
    exists partly to keep it that way, but it is a convention backed by review,
    not by the tool.
  - It says nothing about GEMM output. The similarity engine returns a whole
    matrix of cosines and the matcher reads them directly; that path is correct
    by inspection (every value goes through `cal_.probability`) and is not
    verified here.
  - A retired constant reintroduced under a new name is invisible to it.
 Exit status is 0 when clean, 1 when a violation is found, 2 on a usage error.
 """
 import argparse
 import pathlib
 import re
 import sys
 # How far above a use an exception tag may sit and still cover it.
 # Generous, because the house style puts a paragraph of reasoning between the
 # tag and the code -- but bounded, so a tag cannot silently cover a whole file.
 EXCEPTION_SCOPE_LINES = 25
 CPP_SUFFIXES = {".h", ".hpp", ".hxx", ".cc", ".cpp", ".cxx", ".cu", ".cuh"}
 # src only, deliberately. The invariant governs what the PIPELINE decides --
 # CLAUDE.md's rule is "tag the unit that decides" -- whereas a test legitimately
 # asserts properties of the metric space itself (that a vector's cosine with
 # itself is 1, that the annex ended up holding the spoke it should have). Those
 # are measurements of the code under test, not decisions shipped to a user, and
 # sweeping them in would produce a wall of blanket EXCEPTION tags that would
 # devalue the tag everywhere else. Pass --source-root tests to scan them anyway.
 DEFAULT_ROOTS = ["src"]
 # Directories that are never this repo's code.
 EXCLUDE_DIRS = {
    "build", "build-ort", "external", "vendor", "__pycache__",
    ".git", "node_modules", "models",
 }
 COSINE_CALL = re.compile(r"\bcosine_similarity\s*\(")
 # The result is immediately handed to a calibration. Matches the house shapes:
 #   cal_(cosine_similarity(a, b))
 #   calibrate_(cosine_similarity(a, b))
 #   same_person(cosine_similarity(a, b))
 #   cal_.probability(cosine_similarity(a, b))
 CALIBRATED = re.compile(
    r"(?:\b(?:cal_|cal|calibrate_|calibrate|same_person|same_person_probability)"
    r"\s*(?:\.\s*probability\s*)?\(\s*|\.\s*probability\s*\(\s*)"
    r"cosine_similarity\s*\("
 )
 EXCEPTION_TAG = re.compile(r"EXCEPT" + r"ION:\s*AR-" + r"024\b(.*)")
 # The function's own definition is not a use of it.
 DEFINITION = re.compile(r"^\s*(?:inline\s+|static\s+|constexpr\s+)*float\s+"
                        r"cosine_similarity\s*\(")
 # The house style wraps long calls across lines:
 #     const float p = calibrate_(
 #         cosine_similarity(a, b));
 # so the calibration and the call it guards are not always on one line. Joining
 # a small window before testing is what makes this check usable on real code
 # rather than a generator of false positives that trains people to ignore it.
 JOIN_LOOKBEHIND = 2
 def iter_sources(root: pathlib.Path, roots):
    for rel in roots:
        base = root / rel
        if not base.exists():
            continue
        for p in sorted(base.rglob("*")):
            if p.suffix.lower() not in CPP_SUFFIXES:
                continue
            if any(part in EXCLUDE_DIRS for part in p.relative_to(root).parts):
                continue
            yield p
 def covering_exception(lines, idx):
    """Return the reason text of an exception tag covering line `idx`."""
    lo = max(0, idx - EXCEPTION_SCOPE_LINES)
    for j in range(idx, lo - 1, -1):
        m = EXCEPTION_TAG.search(lines[j])
        if m:
            return m.group(1).strip(" -—*/") or "(no reason given)"
    return None
 def check_file(path: pathlib.Path, root: pathlib.Path):
    violations, exceptions = [], []
    try:
        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
    except OSError as e:
        print(f"error: cannot read {path}: {e}", file=sys.stderr)
        return violations, exceptions
    rel = path.relative_to(root)
    for i, line in enumerate(lines):
        if not COSINE_CALL.search(line):
            continue
        # A comment mentioning the function is prose, not a use.
        stripped = line.lstrip()
        if stripped.startswith(("//", "///", "*", "/*")):
            continue
        if DEFINITION.match(line):
            continue
        # Join a small window so a call wrapped across lines is still seen as
        # calibrated. Whitespace is collapsed so the join reads as one statement.
        window = " ".join(
            lines[max(0, i - JOIN_LOOKBEHIND):i + 1]
        )
        window = re.sub(r"\s+", " ", window)
        if CALIBRATED.search(window):
            continue
        reason = covering_exception(lines, i)
        if reason:
            exceptions.append((rel, i + 1, line.strip(), reason))
        else:
            violations.append((rel, i + 1, line.strip()))
    return violations, exceptions
 def main():
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--root", default=None,
                    help="repository root (default: the script's ../..)")
    ap.add_argument("--source-root", action="append", default=None,
                    help="directory to scan; repeatable (default: src, tests)")
    args = ap.parse_args()
    root = pathlib.Path(args.root) if args.root \
        else pathlib.Path(__file__).resolve().parents[2]
    roots = args.source_root or DEFAULT_ROOTS
    if not root.is_dir():
        print(f"error: root {root} is not a directory", file=sys.stderr)
        return 2
    all_violations, all_exceptions, n_files = [], [], 0
    for p in iter_sources(root, roots):
        n_files += 1
        v, e = check_file(p, root)
        all_violations += v
        all_exceptions += e
    if n_files == 0:
        # A scan that found nothing to read is a misconfiguration reporting a
        # pass, which is the failure mode the traceability gate also guards.
        print(f"error: scanned 0 source files under {root} ({', '.join(roots)})",
              file=sys.stderr)
        return 2
    print("AR-024 — always the calibrated probability, never a raw cosine")
    print("=" * 72)
    print(f"Repo root      : {root}")
    print(f"Files scanned  : {n_files} ({', '.join(roots)})")
    print(f"Recorded excs. : {len(all_exceptions)}")
    print(f"Violations     : {len(all_violations)}")
    if all_exceptions:
        print("\nRecorded exceptions (allowed, and each one is a claim to re-read):")
        for rel, ln, src, reason in all_exceptions:
            print(f"   {rel}:{ln}  {reason}")
            print(f"      {src}")
    if all_violations:
        print("\nVIOLATIONS — a bare cosine with no recorded exception:")
        for rel, ln, src in all_violations:
            print(f"   {rel}:{ln}")
            print(f"      {src}")
        print("\nEvery similarity is converted through the sigmoid calibration")
        print("before it is used, compared, or thresholded. A raw cosine means")
        print("something different for every model, gallery and face size, and")
        print("it cannot be combined with anything else.")
        print("\nEither route it through the calibration, or, if the use is")
        print("genuinely about the metric space rather than about a decision,")
        print("record it:")
        print("      // " + "EXCEPT" + "ION: AR-" + "024 <why this one is not a decision>")
        print("and add a row to CLAUDE.md's agreed-exceptions table.")
        return 1
    print("\nOK: no bare cosine outside a recorded exception.")
    return 0
 if __name__ == "__main__":
    sys.exit(main())
@@ -79,9 +79,8 @@ def main():
                "--dump", str(dump), "--gallery", str(gallery),
                "--out", str(pred_path),
                "--prob-threshold", str(cfg["prob_threshold"]),
-                # anneal_sec and extinction_sec are both gone: presence is
+                "--anneal-sec", str(cfg["anneal_sec"]),
-                # the registry's, built from track extents (AR-012/AR-013), and
+                "--extinction-sec", str(cfg["extinction_sec"]),
                # replay.py no longer windows anything itself (VR-011).
                "--expand-gallery",
            ]
            print(f"RUN {model}/{film['slug']}...", file=sys.stderr)
@@ -1,98 +0,0 @@
 #!/bin/bash
 # fetch_dvu.sh — pull one film's character mugshots and presence annotations from
 # the NIST TRECVID Deep Video Understanding development set.
 #
 # The DVU dev set is the reason Road to Bali is our benchmark film: it ships
 # 5-7 face crops per *character*, cut from the film itself, alongside
 # scene-scoped presence annotations. That matches SR-002 directly — presence is
 # per scene, not per frame — and it keeps ground truth in character space, so
 # scoring needs no actor->character mapping.
 #
 # This exists as a script, rather than as ad hoc commands, because the first
 # copy of this data lived in a temp directory and was lost to a /tmp wipe,
 # taking the working gallery with it.
 #
 # 14 films are asserted Creative Commons and need no data agreement (only the
 # 5 KinoLorber test films are gated).
 #
 # Usage:
 #   scripts/fetch_dvu.sh [film] [dest]
 #     film  default Road_To_Bali
 #     dest  default ./dvu
 set -euo pipefail
 BASE="https://www-nlpir.nist.gov/projects/trecvid/dvu/dvu.development.dataset"
 FILM="${1:-Road_To_Bali}"
 DEST="${2:-dvu}"
 mkdir -p "$DEST/images" "$DEST/scenes"
 echo "[dvu] $FILM -> $DEST"
 # Scene segmentation: start/end as HH:MM:SS. Note valkaama.csv line 38 carries a
 # shift-key typo (01:!4:00) — parse defensively if you extend this to that film.
 echo "[dvu] scene segmentation"
 curl -fsSL "$BASE/scene.segmentation.reference/${FILM}.csv" \
    -o "$DEST/${FILM}.csv" || echo "  (missing: ${FILM}.csv)"
 # Entity types: which entities are Person vs Location/Concept. Only Person rows
 # become gallery identities — the images/ directory also holds Location and
 # Concept crops (bedroom, boat, ...), which must not enter a face gallery.
 #
 # Directory and file naming are inconsistent with the film slug used elsewhere:
 # the folder is Road_to_Bali (lowercase "to") while the entity file is
 # RoadToBali.entity.types.txt. Both are derived here rather than assumed.
 # NIST is inconsistent across all three axes, and not by a rule worth deriving:
 # Road to Bali is Road_To_Bali.csv / Road_to_Bali/ / RoadToBali.entity.types.txt,
 # while SuperHero is SuperHero.csv / superHero/ / superhero.entity.types.txt.
 # Defaults cover the Bali shape; override per film rather than guessing.
 #   KG_DIR=superHero KG_FILE=superhero scripts/fetch_dvu.sh SuperHero dvu-hero
 KG_DIR="${KG_DIR:-${FILM//_To_/_to_}}"
 KG_FILE="${KG_FILE:-$(echo "$FILM" | sed -E 's/_([a-z])/\U\1/g; s/_//g')}"
 echo "[dvu] entity types ($KG_DIR/$KG_FILE)"
 curl -fsSL "$BASE/movie_knowledge_graph/${KG_DIR}/${KG_FILE}.entity.types.txt" \
    -o "$DEST/${FILM}.entity.types.txt" || echo "  (missing: entity types)"
 # Character face crops. Names are discovered from the directory listing rather
 # than probed as <Character>_N, since the crop count varies per character and
 # the listing is authoritative.
 echo "[dvu] character mugshots"
 PERSONS="$DEST/persons.txt"
 if [ -f "$DEST/${FILM}.entity.types.txt" ]; then
    grep -iE "person" "$DEST/${FILM}.entity.types.txt" \
        | sed -E 's/[[:space:]]*[:,].*$//' | tr -d '\r' \
        | awk '{print tolower($1)}' | sort -u > "$PERSONS"
 fi
 curl -fsSL "$BASE/movie_knowledge_graph/${KG_DIR}/images/" 2>/dev/null \
    | grep -oE 'href="[^"?/][^"]*\.png"' | sed -E 's/href="//; s/"//' | sort -u \
    > "$DEST/all_images.txt"
 while read -r img; do
    [ -z "$img" ] && continue
    # Strip the trailing _N to recover the entity name.
    who="$(echo "$img" | sed -E 's/_[0-9]+\.png$//' | awk '{print tolower($0)}')"
    if [ -s "$PERSONS" ] && ! grep -qx "$who" "$PERSONS"; then
        continue   # Location/Concept crop, not a face
    fi
    curl -fsSL "$BASE/movie_knowledge_graph/${KG_DIR}/images/${img}" \
        -o "$DEST/images/${img}" 2>/dev/null || rm -f "$DEST/images/${img}"
 done < "$DEST/all_images.txt"
 # Per-scene knowledge graphs. A Person->Location edge means that person was
 # present for the whole scene. Some of these contain a stray ", ," that breaks
 # strict JSON parsers.
 echo "[dvu] scene graphs"
 for n in $(seq 1 60); do
    curl -fsSL "$BASE/scenes_knowledge_graphs/${FILM//_/ }-${n}.json" \
        -o "$DEST/scenes/${FILM}-${n}.json" 2>/dev/null \
        || curl -fsSL "$BASE/scenes_knowledge_graphs/${FILM}-${n}.json" \
            -o "$DEST/scenes/${FILM}-${n}.json" 2>/dev/null \
            || rm -f "$DEST/scenes/${FILM}-${n}.json"
 done
 echo "[dvu] done:"
 echo "  mugshots: $(ls "$DEST/images" 2>/dev/null | wc -l)"
 echo "  scenes:   $(ls "$DEST/scenes" 2>/dev/null | wc -l)"
 echo "  csv:      $([ -f "$DEST/${FILM}.csv" ] && echo yes || echo no)"
@@ -77,12 +77,7 @@ def main():
    if missing > 0:
        print(f"[warn] {missing} cast member(s) not present in gallery (not yet embedded)", file=sys.stderr)
-    # TRACES: GR-004 | SR-001
+    save_gallery_hdf5({"actors": actors}, Path(args.output))
    # a filtered gallery holds the SAME vectors as its
    # source, so it inherits the source's binding. Dropping the stamp here would
    # silently launder a stamped gallery into an unstamped one.
    save_gallery_hdf5({"actors": actors}, Path(args.output),
                      gallery.get("embedder"))
    print(f"Saved {len(actors)} actor(s) to {args.output}", file=sys.stderr)
@@ -1,67 +0,0 @@
 #!/usr/bin/env bash
 # make_fixtures.sh — regenerate the committed replay fixtures.
 #
 # TRACES: VR-001 | PR-002
 #
 # CI never calls a model (see docs/requirements.md, "CI never calls a model"):
 # the embedder is impractical on the N100 CI host, so inference happens HERE, on
 # a machine with a GPU, and CI consumes the HDF5 dumps as data. Everything
 # downstream of embedding — tracking, presence windows, belief accumulation,
 # expansion — is cheap CPU maths and replays from these files.
 #
 # Reproducibility is a requirement, not a nicety. A fixture whose provenance is
 # unknown is worse than no fixture, because it will be trusted. Every parameter
 # that affects the output is pinned below rather than left to a default, and the
 # dumps carry the embedder identity and SHA-256 (GR-004) so a replay cannot be
 # silently scored against the wrong gallery.
 #
 # These are byte-reproducible only because node outputs block rather than drop
 # on a full channel (AR-004). Before that fix the same command produced
 # different dumps run to run, since what got dropped depended on timing.
 #
 # Source: hero/ — SuperHero, from the TRECVID DVU development set. Chosen over
 # SuperHero on face scale: Bali reference crops had a median detected face of
 # 27 px against a 69 px maximum, so every reference was upscaled far past what
 # the embedder was trained for. SuperHero is 69 px median, 241 px max. That matters: derived
 # fixtures can be committed, where anything cut from a copyrighted title could
 # not live in the repository at all.
 set -euo pipefail
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 CLIPS="${CLIPS:-$REPO/../hero}"
 GALLERY="${GALLERY:-$REPO/gallery_lvface.h5}"
 BIN="${BIN:-$REPO/build/scene_analyze}"
 OUT="$REPO/tests/fixtures/dumps"
 # Pinned. Changing either invalidates every committed fixture.
 #   fps 5      — 1 fps over a 77 s clip is 77 frames, too thin to exercise an
 #                extinction window measured in tens of seconds.
 #   min-face   — 32 px. This is a *fixture* setting, deliberately below AR-002's
 #                production floor of 40 px (VR-013, measured end to end): the
 #                corpus is 480x360, where faces run 40-80 px, so pinning at 40
 #                would thin the dumps for reasons unrelated to what they test.
 #                32 px is where VR-005 still shows 98.1% TPI, so the faces kept
 #                are identifiable; it is not the threshold the pipeline ships.
 FPS=5
 MIN_FACE_PX=32
 [[ -x "$BIN"      ]] || { echo "no scene_analyze at $BIN (set BIN=)" >&2; exit 1; }
 [[ -f "$GALLERY"  ]] || { echo "no gallery at $GALLERY (set GALLERY=)" >&2; exit 1; }
 [[ -d "$CLIPS"    ]] || { echo "no clips at $CLIPS (set CLIPS=)" >&2; exit 1; }
 mkdir -p "$OUT"
 for clip in "$CLIPS"/SuperHero-*.webm; do
    n="$(basename "$clip" .webm)"; n="${n##*-}"
    echo "── superhero_$n"
    "$BIN" --movie "$clip" --gallery "$GALLERY" \
           --fps "$FPS" --min-face-px "$MIN_FACE_PX" \
           --dump-embeddings "$OUT/superhero_$n.h5" \
           --output /dev/null 2>&1 | grep -E "wrote|dropped" || true
 done
 echo
 echo "Regenerated in $OUT — verify the diff is empty if nothing upstream changed."
 echo "A non-empty diff means detection, alignment or embedding moved. That is"
 echo "either a regression or a deliberate change, and either way the golden"
 echo "outputs derived from these fixtures need reviewing."
@@ -36,9 +36,8 @@ import time
 from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from sae_embed_loader import load_embedder, resolve_arcface
+from sae_embed_loader import load_embedder
-from sae_gallery import (download_images, embedder_stamp, save_gallery,
+from sae_gallery import download_images, save_gallery, wikidata_image_urls
                         wikidata_image_urls)
 from sae_tmdb import TMDB_IMG, tmdb_get, tmdb_id_from_imdb
@@ -178,12 +177,7 @@ def main():
    output     = Path(args.output)
    image_root = Path(args.image_dir) if args.image_dir else output.parent / "images"
    # TRACES: GR-004 | SR-001
    # stamp with the model actually loaded, resolved
    # through the same helper load_embedder uses so the two cannot diverge.
    arcface_path = resolve_arcface(args.models_dir, args.arcface)
    embedder = load_embedder(args.build_dir, args.models_dir, args.arcface)
    stamp = embedder_stamp(arcface_path)
    # Resolve movie ID
    movie_id = args.movie_id
@@ -209,7 +203,7 @@ def main():
    if n_actors == 0:
        sys.exit("No actors could be processed — check models and images.")
-    save_gallery(gallery, missing, output, embedder=stamp)
+    save_gallery(gallery, missing, output)
 if __name__ == "__main__":
@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 """make_jellyfin_gallery.py — build a gallery.h5 spanning an entire Jellyfin library.
 TRACES: GR-001, GR-002 | SR-001, SR-005
 Queries the Jellyfin API for every Movie/Series, collects the unique cast
 across the whole library, downloads each actor's headshot directly from
 Jellyfin (no TMDB key needed), embeds them with the sae_embed module (SCRFD +
@@ -53,9 +51,8 @@ import requests
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import sae_env  # noqa: F401  — loads .env into os.environ on import
-from sae_embed_loader import load_embedder, resolve_arcface
+from sae_embed_loader import load_embedder
-from sae_gallery import (download_image, download_images, embedder_stamp,
+from sae_gallery import (download_image, download_images, load_gallery_hdf5,
                        enforce_embedder_stamp, load_gallery_hdf5,
                        save_gallery, wikidata_image_urls)
 from sae_jellyfin import actor_jellyfin_id, jf_get, normalize_jellyfin_url
 from sae_tmdb import (
@@ -445,21 +442,11 @@ def main():
    image_root = Path(args.image_dir) if args.image_dir else output.parent / "images"
    item_types = [t.strip() for t in args.item_types.split(",") if t.strip()]
    # TRACES: GR-004 | SR-001
    arcface_path = resolve_arcface(args.models_dir, args.arcface)
    embedder = load_embedder(args.build_dir, args.models_dir, args.arcface)
    stamp = embedder_stamp(arcface_path)
    existing_actors = {}
    if args.merge and output.is_file():
        existing = load_gallery_hdf5(output)
        # TRACES: GR-004 | SR-001
        # --merge keeps the existing actors' vectors and
        # embeds the new ones with THIS model. If they disagree, the result is one
        # gallery holding two incompatible embedding spaces, which is worse than a
        # mismatched gallery: no later check can separate them again.
        enforce_embedder_stamp(existing.get("embedder"), stamp, str(output),
                               arcface_path)
        for actor in existing.get("actors", []):
            pid = actor_jellyfin_id(actor)
            if pid:
@@ -488,7 +475,7 @@ def main():
    if n_actors == 0:
        sys.exit("No actors could be processed — check Jellyfin URL/API key and models.")
-    save_gallery(gallery, missing, output, embedder=stamp)
+    save_gallery(gallery, missing, output)
 if __name__ == "__main__":
@@ -22,8 +22,8 @@ from pathlib import Path
 import numpy as np
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from sae_embed_loader import load_embedder, resolve_arcface
+from sae_embed_loader import load_embedder
-from sae_gallery import load_gallery_hdf5, verify_gallery_stamp
+from sae_gallery import load_gallery_hdf5
 def load_gallery(path: str) -> dict[str, dict]:
@@ -62,12 +62,6 @@ def main():
    args = p.parse_args()
    embedder = load_embedder(args.build_dir, args.models_dir, args.arcface)
    # TRACES: GR-004 | SR-001
    # match() below is a bare dot product against the
    # gallery's vectors; if the gallery came from another model those numbers are
    # noise wearing a similarity's clothes.
    verify_gallery_stamp(args.gallery,
                         resolve_arcface(args.models_dir, args.arcface))
    gallery = load_gallery(args.gallery)
    print(f"[eval] gallery: {len(gallery)} actors", file=sys.stderr)
@@ -1,4 +1,4 @@
-# Embedding-dump HDF5 schema (v2)
+# Embedding-dump HDF5 schema (v1)
 One file per analysed title. Captures the pipeline state at the `EmbeddedSceneFrame`
 channel — i.e. after decode → detect → align → embed, but **before** tracking and
@@ -18,34 +18,11 @@ variable-length HDF5 types and reads straight into numpy.
 ```
 /                                     (root)
  attrs:
-    schema_version : int   = 2
+    schema_version : int   = 1
    movie          : str   (source video path)
    sample_fps     : float
    embed_dim      : int   = 512
    # ── what produced the vectors (GR-004) ──────────────────────────────────
    embedder_model : str   basename of the embedding model
    embedder_sha256: str   SHA-256 of that model file
    # ── what produced the faces (VR-010) ────────────────────────────────────
    detector_model : str   basename of the detector .onnx
    detector_conf  : float score floor a detection had to clear to be dumped
    detector_nms   : float NMS IoU threshold
    min_face_px    : float minimum box side, ORIGINAL-resolution px (AR-002)
    max_faces      : int   per-frame cap; 0 = uncapped, the default (AR-003)
    # ── what produced the frames (VR-010) ───────────────────────────────────
    movie          : str   source video path
    sample_fps     : float frames analysed per second of movie
    start_sec      : float seek point
    end_sec        : float stop point; -1 = end of file
    cut_threshold  : float histogram correlation below which is_cut fires
    dense_scale    : float decoded-frame downscale in dense mode; 1 = off
    bbox_upscale   : float multiply faces/bbox and faces/landmarks by this to
                           reach original video pixels; 1 when dense_scale is 1
    scene_detect   : uint8 0/1 — was TransNetV2 running at all (see below)
    # ── downstream setting recorded for comparability (VR-010) ──────────────
    track_assoc_min_prob : float  the run's tracker admission probability
  frames/                             group — one row per sampled frame
    timestamp_sec  : float64 [F]
    frame_idx      : int64   [F]
@@ -56,136 +33,18 @@ variable-length HDF5 types and reads straight into numpy.
  faces/                              group — one row per detected face, concatenated
    embedding      : float32 [N, 512] L2-normalised ArcFace embedding
-    bbox           : float32 [N, 4]   x, y, w, h in DECODED-frame pixels
+    bbox           : float32 [N, 4]   x, y, w, h in original video pixels
-    landmarks      : float32 [N, 10]  5 (x,y) pairs, SCRFD/ArcFace order,
+    landmarks      : float32 [N, 10]  5 (x,y) pairs, SCRFD/ArcFace order
                                      same space as bbox
    confidence     : float32 [N]      detector confidence
    # ── embedding input quality (AR-028), v2 onward ─────────────────────────
    sharpness          : float32 [N]  normalised Laplacian variance on the
                                      112x112 aligned crop (AR-029)
    alignment_residual : float32 [N]  RMS landmark misfit in canonical px,
                                      after the AR-005 similarity fit (AR-030)
 ```
 `F` = number of sampled frames, `N` = total faces (= sum of face_count).
 Frame *i*'s faces are `faces/*[ face_offset[i] : face_offset[i]+face_count[i] ]`.
 ## Provenance (VR-010)
 The attributes above are not documentation; they are the only thing that makes a
 dump interpretable. Two dumps of the same film at `detector_conf` 0.5 and 0.7, or
 at `dense_scale` 1.0 and 0.5, or with scene detection on and off, are different
 measurements of different things — and they are byte-shaped identically. Without
 provenance a consumer that mixes them gets a plausible number from an incoherent
 input, and nothing anywhere reports a problem.
 **`scene_detect` is the one that cannot be inferred.** `is_scene_boundary` is
 all-zero both when TransNetV2 found no boundaries in the clip and when it was
 never enabled, and those mean opposite things: the first says *this footage has
 no shot changes*, the second says *nobody looked*. A consumer that reads the
 array alone must guess. The flag is what removes the guess. (`dump_embeddings`
 has no `--scene-detect`, so every dump it writes records `false` — which is
 exactly the fact the committed fixtures needed to state.)
 **`bbox_upscale` is recorded, not applied.** See the coordinate-space note below.
 Reading is by name with a default or an existence check on **both** sides —
 `replay.py` (`f.attrs.get(...)`) and `read_dump_provenance()` in
 `src/nodes/embedding_dump_node.hpp` (`attrExists`). So the attributes are
 additive and did not themselves move `schema_version` off 1: a pre-VR-010 dump
 still loads, and a post-VR-010 dump still reads on old code. (AR-028 later took
 it to 2 by adding *datasets* — see below.)
 A missing attribute means **unknown**, never a default value. Substituting
 `detector_conf = 0.5` for a dump that does not say so manufactures the provenance
 the requirement exists to prevent — per `docs/requirements.md`, *"a fixture whose
 provenance is unknown is worse than no fixture, because it will be trusted."*
 The committed `tests/fixtures/dumps/*.h5` predate VR-010 and carry none of these
 attributes; re-dump to bind them, as with GR-004.
 ## Embedding input quality (AR-028) — and why this one bumps the version
 `sharpness` and `alignment_residual` are two of the three AR-028 quality axes,
 written beside the embedding they describe. **The third axis, size, is already
 here**: it is `bbox`, scaled by `bbox_upscale` to reach the original resolution
 AR-002 thresholds in. It is not duplicated into a third column, because that
 would put the same quantity in two coordinate spaces inside one file — the trap
 the `bbox_upscale` note below records — and the copy is the one that drifts.
 The vector is **carried, not consumed**. Nothing in the pipeline thresholds or
 discounts on it yet; VR-012 locates the knees from these columns, which is only
 possible if they were recorded at inference. A study cannot recover how sharp a
 face was from an embedding, any more than it can recover which model produced it.
 **This is the change that bumps `schema_version` to 2**, where VR-010's
 attributes did not. The rule is unchanged — a bump is for the *datasets* — and
 so is the reason behind it. Readers are fine either way: `replay.py` and
 `test_replay_fixtures.cpp` take these datasets by name with an existence check,
 so a v1 dump still replays and loses only what it never had. The version exists
 for a *consumer of the quality vector*, which otherwise cannot tell **"this
 film's faces were never scored"** from **"this film's faces scored zero"** —
 sharpness 0 is a real reading, meaning a featureless crop. That is the same
 distinction `scene_detect` exists to make, and it is equally unrecoverable from
 the arrays.
 A v1 dump reports the vector as **unknown, never as a default** — `load_frames`
 omits the keys rather than filling zeros, and the C++ side leaves the
 `DetectedFace` fields at their -1 "unscored" sentinel. Re-dump to acquire it;
 there is no migration, for the same reason GR-004 has none.
 > The committed `tests/fixtures/dumps/*.h5` are v1 and carry no quality vector.
 > Re-dumping needs a GPU host (`scripts/make_fixtures.sh`), so until that runs,
 > anything driven from the fixtures sees the sentinel.
 ## Model binding (GR-004)
 `embedder_model` / `embedder_sha256` record which embedder produced every vector
 in `faces/embedding`. A replay has no live embedder, so **the dump is the embedder
 as far as the gallery is concerned**: `replay.py` checks these two attributes
 against the gallery's own `/embedder` stamp and refuses to run on a mismatch,
 naming both sides. Cross-model cosines are meaningless but look plausible.
 The attributes are additive, not a format break — `schema_version` stays 1. Dumps
 written before GR-004 simply lack them, which reports as *unverifiable* (a loud
 warning, or a hard error under `SAE_REQUIRE_GALLERY_STAMP=1`) rather than as a
 pass. Re-dump to bind an old dump; there is no in-place migration, because unlike
 a gallery nobody can assert after the fact which model produced a vector.
 ## Coordinate space — `bbox`, `landmarks`, `bbox_upscale`
 `bbox` and `landmarks` are in **decoded-frame pixels**: exactly the numbers SCRFD
 produced, untransformed. To reach original video pixels, multiply by
 `bbox_upscale`. With `dense_scale == 1` (the default, and every committed
 fixture) `bbox_upscale == 1` and the two spaces coincide.
 > Earlier revisions of this document claimed the upscale was applied at dump time.
 > It never was. `embedding_dump_node.hpp` writes `f.bbox` raw; the upscale lives
 > in `identity_matcher_node.hpp`, which is *downstream* of the dump tap. The
 > claim was harmless only because `dense_scale` was 1 in practice.
 The fix is to record the factor rather than to apply it, because the dump's whole
 contract is to be a **faithful tap** at the `EmbeddedSceneFrame` channel — VR-002
 requires replay to drive the real nodes, and a replay is only equivalent to the
 live run if the tracker is fed the geometry the live tracker saw. Rescaling at
 the tap would break that: the replayed tracker would associate on boxes the live
 one never received. Two further reasons:
 - The matcher's upscale is applied to `bbox` **only**, not to `landmarks`.
  Pre-multiplying at the tap would leave the two arrays in different coordinate
  spaces inside one file — a worse trap than the one being fixed.
 - Pre-multiplying is lossy in the sense that matters: a dump that had been
  upscaled would be indistinguishable from one taken at `dense_scale == 1`, so
  you would have to record `bbox_upscale` anyway to know which you were holding.
 ## Invariants
 - `embedding` rows are unit-norm (cosine == dot product against the gallery).
 - `face_offset[0] == 0`; `face_offset[i+1] == face_offset[i] + face_count[i]`.
- `bbox` and `landmarks` share one coordinate space; `bbox_upscale` maps both to
+- `bbox` is already mapped to original resolution (bbox_upscale applied at dump time),
-  original resolution (see above).
+  matching what the identity matcher would emit.
 - A frame with no faces has `face_count == 0` (still gets a row, so timestamps stay dense).
 - EOF sentinel frames are NOT written.
 - v2 onward: `sharpness` and `alignment_residual` are `[N]`, parallel to
  `confidence`, so face *i*'s quality indexes with the same slice as its
  embedding. Both are `>= 0` for any face the aligner admitted; a negative value
  means unscored and must never be read as a quality.
@@ -35,9 +35,7 @@ REPO = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(REPO / "scripts"))
 import sae_env  # noqa: E402  loads .env
 from sae_tmdb import tmdb_get, tmdb_person_for_imdb, TMDB_IMG  # noqa: E402
-from sae_embed_loader import resolve_arcface                   # noqa: E402
+from sae_gallery import download_images, wikidata_image_urls   # noqa: E402
 from sae_gallery import (download_images, embedder_stamp,      # noqa: E402
                         enforce_embedder_stamp, wikidata_image_urls)
 from sae_embed_loader import load_embedder                     # noqa: E402
@@ -59,7 +57,6 @@ def fetch(missing_path, out_path, token, build_dir, models_dir, arcface,
    src = "TMDB + Wikidata fallback" if use_wikidata else "TMDB"
    print(f"[fetch] {len(missing)} missing actors to resolve via {src}", file=sys.stderr)
    embedder = load_embedder(build_dir, models_dir, arcface)
    stamp = embedder_stamp(resolve_arcface(models_dir, arcface))   # TRACES: GR-004 | SR-001
    img_root = Path(tempfile.mkdtemp(prefix="missing_gallery_"))
    actors = []
@@ -106,10 +103,7 @@ def fetch(missing_path, out_path, token, build_dir, models_dir, arcface,
                  f"(wiki={n_via_wikidata}) no_tmdb={n_no_tmdb} no_img={n_no_img} "
                  f"no_face={n_no_face}", file=sys.stderr)
-    # TRACES: GR-004 | SR-001
+    Path(out_path).write_text(json.dumps({"actors": actors}, indent=2))
    # the legacy JSON gallery carries the same stamp as
    # the HDF5 one; src/gallery/gallery_store.cpp reads it from either.
    Path(out_path).write_text(json.dumps({"embedder": stamp, "actors": actors}, indent=2))
    n_emb = sum(len(a["embeddings"]) for a in actors)
    print(f"\n[fetch] recovered {n_resolved}/{len(missing)} actors "
          f"({n_via_wikidata} via Wikidata), {n_emb} embeddings → {out_path}",
@@ -121,13 +115,6 @@ def fetch(missing_path, out_path, token, build_dir, models_dir, arcface,
 def merge(base_path, add_path, out_path):
    base = json.loads(Path(base_path).read_text())
    add = json.loads(Path(add_path).read_text())
    # TRACES: GR-004 | SR-001
    # merging two galleries from different models makes
    # ONE file containing two incompatible embedding spaces. Nothing downstream can
    # ever untangle that, so this is the one place the check must run before, not
    # after, the write.
    enforce_embedder_stamp(base.get("embedder"), add.get("embedder"),
                           str(base_path), str(add_path))
    have = {a.get("imdb_id") for a in base["actors"] if a.get("imdb_id")}
    added = [a for a in add["actors"] if a.get("imdb_id") not in have]
    base["actors"].extend(added)
@@ -17,7 +17,7 @@ point from the trajectory (--trajectory).
 Usage:
  python scripts/optimizer/optimize.py --manifest films.json \
      --gallery gallery_arcface_w600k_r50.json \
-      --params prob_threshold:0.5:0.999 ownership_logodds:0.5:4 track_alpha:0:1 \
+      --params prob_threshold:0.5:0.999 anneal_sec:1:30 extinction_sec:1:15 \
      --popsize 20 --maxiter 25 --trajectory traj.json
 """
 from __future__ import annotations
@@ -34,7 +34,6 @@ from scipy.optimize import differential_evolution
 REPO = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(REPO / "scripts" / "optimizer"))
 sys.path.insert(0, str(REPO / "scripts" / "validation"))
 sys.path.insert(0, str(REPO / "scripts"))
 import json as _json
 import os
@@ -57,8 +56,6 @@ DE_WORKERS = int(os.environ.get("DE_WORKERS", "1"))
 from second_score import score_seconds  # noqa: E402  uniform per-second TPI/FPI scoring
 from sample_eval import load_gallery_keys  # noqa: E402
 from replay import dump_embedder_stamp  # noqa: E402
 from sae_stamp import EmbedderMismatch, verify_gallery_stamp  # noqa: E402
 _GAL_KEYS: dict = {}  # gallery path → key set (fair-recall FN mask), loaded once
 _REPLAY_TIMEOUT = 45  # seconds per film; a wedged replay is killed, not left to hang
@@ -183,15 +180,7 @@ def main():
    p.add_argument("--seed", type=int, default=0)
    p.add_argument("--trajectory", help="write every evaluation here (JSON lines)")
    p.add_argument("--out", help="write best config + metrics")
    # TRACES: GR-004 | SR-001
    p.add_argument("--require-gallery-stamp", action="store_true",
                   help="unprovable gallery/dump model binding is a hard error, "
                        "not a warning (also via SAE_REQUIRE_GALLERY_STAMP=1)")
    args = p.parse_args()
    if args.require_gallery_stamp:
        # Set the env var rather than threading a flag through cfg: replays run as
        # subprocesses and inherit it, so strictness cannot be lost in the handoff.
        os.environ["SAE_REQUIRE_GALLERY_STAMP"] = "1"
    films = json.loads(Path(args.manifest).read_text())
    for f in films:
@@ -199,19 +188,6 @@ def main():
        if not Path(f["dump"]).exists():
            sys.exit(f"[opt] missing dump for {f['name']}: {f['dump']}")
    # TRACES: GR-004 | SR-001
    # every (dump, gallery) pair is checked ONCE here,
    # before the first evaluation. A DE sweep is thousands of replays; discovering
    # a cross-model pair at the end (or never) means every number it produced was
    # noise. Each replay subprocess re-checks its own pair anyway.
    for f in films:
        try:
            verify_gallery_stamp(f["gallery"], stamp=dump_embedder_stamp(f["dump"]),
                                 embedder_desc=f"embedding dump {Path(f['dump']).name}",
                                 require_stamp=args.require_gallery_stamp)
        except EmbedderMismatch as e:
            sys.exit(f"[opt] {f['name']}: {e}")
    names, bounds = [], []
    int_knobs = {"track_max_frames_missing", "cut_inactive_max_frames"}
    for spec in args.params:
@@ -229,20 +205,6 @@ def main():
        cfg = {}
        for k, v in zip(names, x):
            cfg[k] = int(round(v)) if k in int_knobs else float(v)
        # The expansion band is [lo, hi]; independent DE bounds can invert it,
        # and an inverted band admits nothing (track_gallery.hpp). Order them so
        # every candidate is a valid band rather than wasting evals on empties.
        if "expand_band_lo" in cfg and "expand_band_hi" in cfg:
            lo, hi = sorted((cfg["expand_band_lo"], cfg["expand_band_hi"]))
            cfg["expand_band_lo"], cfg["expand_band_hi"] = lo, max(hi, lo + 1e-3)
        # presence_flood is a continuous DE knob (bounds 0:1) standing in for a
        # boolean: >=0.5 selects flood-fill presence. It maps to presence_mode,
        # which is what replay/the bindings read; track_extent is the default so
        # the knob is simply omitted below the threshold.
        if "presence_flood" in cfg:
            flood = cfg.pop("presence_flood") >= 0.5
            if flood:
                cfg["presence_mode"] = "flood"
        return cfg
    def objective(x):
@@ -253,7 +215,7 @@ def main():
            rec = {"eval": evals[0], "config": cfg, **m, "t": round(time.time() - t0, 1)}
            traj.append(rec)
            print(f"[opt] eval {evals[0]:3d}  thr={cfg['prob_threshold']:.2f} "
-                  f"own={cfg.get('ownership_logodds', float('nan')):.2f}  → "
+                  f"ann={cfg['anneal_sec']:.0f} ext={cfg['extinction_sec']:.1f}  → "
                  f"F1={m['f1']*100:.1f}% P={m['precision']*100:.1f}% R={m['recall']*100:.1f}% "
                  f"agree={m.get('agreement', 0)*100:.1f}% misID={m.get('FPI_misid', 0)}",
                  file=sys.stderr)
@@ -27,9 +27,8 @@ from pathlib import Path
 REPO = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(REPO / "scripts"))
-from sae_embed_loader import load_embedder, resolve_arcface  # noqa: E402
+from sae_embed_loader import load_embedder  # noqa: E402
-from sae_gallery import (embedder_stamp, load_gallery_hdf5,  # noqa: E402
+from sae_gallery import load_gallery_hdf5, save_gallery_hdf5  # noqa: E402
                         save_gallery_hdf5)
 def find_dir(images_root: Path, jellyfin_id: str, name: str) -> Path | None:
@@ -59,12 +58,6 @@ def main():
    ref = load_gallery_hdf5(Path(args.ref))
    images_root = Path(args.images)
    embedder = load_embedder(args.build_dir, args.models_dir, args.arcface)
    # TRACES: GR-004 | SR-001
    # this script exists to produce a gallery in a
    # DIFFERENT model's space from the reference. The output must therefore never
    # inherit the reference's stamp; it carries the stamp of --arcface, which is
    # the whole point of the bake-off being safe to run.
    stamp = embedder_stamp(resolve_arcface(args.models_dir, args.arcface))
    out_actors = []
    n_ok = n_nodir = n_noemb = 0
@@ -91,7 +84,7 @@ def main():
            print(f"  [{i}/{total}] ok={n_ok} no_dir={n_nodir} no_emb={n_noemb}",
                  file=sys.stderr)
-    save_gallery_hdf5({"actors": out_actors}, Path(args.out), stamp)
+    save_gallery_hdf5({"actors": out_actors}, Path(args.out))
    n_emb = sum(len(a["embeddings"]) for a in out_actors)
    print(f"[reembed] {Path(args.arcface).stem}: {n_ok}/{total} actors, {n_emb} embeddings "
          f"→ {args.out}", file=sys.stderr)
@@ -2,22 +2,16 @@
 """
 replay.py — replay a dumped embedding HDF5 through the real KPN downstream nodes.
 TRACES: VR-002, VR-011 | PR-002
 Reads an embedding dump (scripts/optimizer/SCHEMA.md), feeds each frame as an
 EmbeddedSceneFrame into a Python-assembled KPN network wiring the *real* C++
-face_tracker → identity_matcher → frame_annotation → result_sink, and reads back
+face_tracker → identity_matcher → scene_tracker, and returns the same presence-window
-the truth file that sink wrote. No decode, no GPU embedding — only the cheap
+JSON that scene_analyze's result_sink produces (minimal schema). No decode, no GPU
-downstream tail runs, so a sweep can vary Config knobs freely.
+embedding — only the cheap downstream tail runs, so a sweep can vary Config knobs
-
+freely. See [[kpn-python-replay-optimizer]].
 The sink is part of the network, not a Python reimplementation of it. That is
 VR-011: presence comes from TrackRegistry claims, so a replayed window and a
 scene_analyze window are produced by the same code rather than by two functions
 that agreed once. See [[kpn-python-replay-optimizer]].
 CLI:
  python scripts/optimizer/replay.py --dump film.h5 --gallery gallery.json \
-      --out replayed.json [--prob-threshold 0.99] [--track-extinction-sec 5] ...
+      --out replayed.json [--prob-threshold 0.99] [--anneal 10] ...
 """
 from __future__ import annotations
@@ -31,22 +25,6 @@ import h5py
 import numpy as np
 REPO = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(REPO / "scripts"))
 from sae_stamp import verify_gallery_stamp  # noqa: E402
 def dump_embedder_stamp(dump_path: str) -> dict:
    """The GR-004 embedder stamp recorded in an embedding dump.
    A replay has no live embedder — the dump IS the embedder as far as the gallery
    is concerned, so the dump's stamp is what the gallery must be checked against.
    Dumps written before GR-004 have no attributes and yield an empty stamp, which
    the check reports as unverifiable rather than silently accepting."""
    with h5py.File(dump_path, "r") as f:
        name = f.attrs.get("embedder_model", "")
        sha = f.attrs.get("embedder_sha256", "")
    dec = lambda v: v.decode() if isinstance(v, bytes) else ("" if v is None else str(v))
    return {"model_name": dec(name), "model_sha256": dec(sha), "embed_dim": 512}
 def load_frames(dump_path: str, min_conf: float = 0.0):
@@ -61,27 +39,12 @@ def load_frames(dump_path: str, min_conf: float = 0.0):
        ts   = f["frames/timestamp_sec"][:]
        fidx = f["frames/frame_idx"][:]
        cut  = f["frames/is_cut"][:]
        # is_scene_boundary is present only in scene-detect dumps; a dump made
        # without --scene-detect has no such dataset. Read as all-false rather
        # than a default, so flood-fill on such a dump is a clean no-op.
        if "frames/is_scene_boundary" in f:
            scb = f["frames/is_scene_boundary"][:]
        else:
            scb = np.zeros(len(ts), dtype=np.uint8)
        off  = f["frames/face_offset"][:]
        cnt  = f["frames/face_count"][:]
        emb  = f["faces/embedding"][:]
        bbox = f["faces/bbox"][:]
        lmk  = f["faces/landmarks"][:]
        conf = f["faces/confidence"][:]
        # TRACES: AR-028 | SR-002
        # The quality vector, present from schema v2. A v1 dump predates AR-028
        # and simply has no such dataset — read as absent, never as a default,
        # so a face from an old dump stays at the C++ -1 "unscored" sentinel
        # rather than acquiring a fabricated sharpness of 0 (which is a real
        # value on this axis, meaning a featureless crop).
        qual = {k: f[f"faces/{k}"][:] for k in ("sharpness", "alignment_residual")
                if f"faces/{k}" in f}
        movie = f.attrs.get("movie", "")
        fps   = float(f.attrs.get("sample_fps", 1.0))
@@ -95,69 +58,40 @@ def load_frames(dump_path: str, min_conf: float = 0.0):
            sel = np.where(m)[0]
            frames.append({
                "timestamp_sec": float(ts[i]), "frame_idx": int(fidx[i]),
-                "is_cut": bool(cut[i]), "is_scene_boundary": bool(scb[i]), "eof": False,
+                "is_cut": bool(cut[i]), "eof": False,
                "bbox":       np.ascontiguousarray(bbox[keep][sel], dtype=np.float32),
                "landmarks":  np.ascontiguousarray(lmk[keep][sel],  dtype=np.float32),
                "confidence": np.ascontiguousarray(c[sel],          dtype=np.float32),
                "embeddings": np.ascontiguousarray(emb[keep][sel],  dtype=np.float32),
                **{k: np.ascontiguousarray(v[keep][sel], dtype=np.float32)
                   for k, v in qual.items()},
            })
        else:
            frames.append({
                "timestamp_sec": float(ts[i]), "frame_idx": int(fidx[i]),
-                "is_cut": bool(cut[i]), "is_scene_boundary": bool(scb[i]), "eof": False,
+                "is_cut": bool(cut[i]), "eof": False,
                "bbox":       np.ascontiguousarray(bbox[keep], dtype=np.float32),
                "landmarks":  np.ascontiguousarray(lmk[keep],  dtype=np.float32),
                "confidence": c,
                "embeddings": np.ascontiguousarray(emb[keep],  dtype=np.float32),
                **{k: np.ascontiguousarray(v[keep], dtype=np.float32)
                   for k, v in qual.items()},
            })
    last_ts = float(ts[-1]) if len(ts) else 0.0
    frames.append({"timestamp_sec": last_ts, "eof": True})
    return frames, str(movie), fps
-def replay(dump_path: str, gallery: str, cfg: dict, build_dir: str,
+def replay(dump_path: str, gallery: str, cfg: dict, build_dir: str, stop: bool = True,
-           out_path: str, stop: bool = True, raw_out: str | None = None,
+          raw_out: str | None = None) -> dict:
-           eof_timeout: float = 300.0) -> dict:
+    """Run the dump through the real KPN chain; return minimal-schema presence JSON.
    """Run the dump through the real KPN chain and return the truth file it wrote.
-    TRACES: VR-011, VR-002 | PR-002
+    cfg may include "detector_conf" to prune dumped detections below that confidence
    (upward-only from the 0.5 dump floor) before matching.
-    `out_path` is where the C++ sink writes. That is the change VR-011 makes:
+    raw_out: if set, also write the raw per-frame annotations (timestamp, actor_idx,
-    the presence windows in that file are built by ResultSinkFunc from
+    name, bbox, similarity — one entry per input frame, before merging into windows)
-    TrackRegistry claims -- the extent of a track an actor owned (AR-012),
+    as JSON lines to this path. Needed to draw bounding boxes on extracted frames;
-    ending at the last sighting (AR-013) -- and are byte-for-byte the same
+    the merged window schema returned by this function has no per-frame bbox."""
    construction scene_analyze ships. This function used to build them itself,
    in Python, by annealing gaps between per-frame detections, which is what the
    pipeline did BEFORE AR-012. A sweep tuned against that was tuning a contract
    the shipped code had stopped honouring.
    cfg may include "detector_conf" to prune dumped detections below that
    confidence (upward-only from the 0.5 dump floor) before matching.
    raw_out: if set, also write per-frame annotations as JSON lines for the
    montage renderers. Derived from the truth file's own `frames` array rather
    than tapped separately out of the network -- see write_raw_frames.
    eof_timeout: how long to wait for the sink to write. A replay that never
    reaches EOF is a wedged pipeline, and returning an empty result would look
    like a film with no cast rather than like a failure."""
    sys.path.insert(0, build_dir)
    import sae_kpn
    # TRACES: GR-004 | SR-001
    # checked here, before any network is built, so a
    # cross-model replay dies with one readable error instead of producing a
    # plausible-looking score. add_identity_matcher re-checks it C++-side below;
    # that is the backstop for any other caller of the binding.
    stamp = dump_embedder_stamp(dump_path)
    verify_gallery_stamp(gallery, stamp=stamp,
                         embedder_desc=f"embedding dump {Path(dump_path).name}",
                         require_stamp=bool(cfg.get("require_gallery_stamp", False)))
    frames, movie, fps = load_frames(dump_path, min_conf=float(cfg.get("detector_conf", 0.0)))
    net = sae_kpn.Network()
@@ -178,171 +112,100 @@ def replay(dump_path: str, gallery: str, cfg: dict, build_dir: str,
        time.sleep(0.05)
        return eof
-    # TRACES: VR-011 | AR-004 | PR-002
+    # Channel capacity must exceed the frame count so the fast source can't overflow
-    # Purely a throughput and memory choice, and that is the point: the answer
+    # a downstream FIFO before the serial reader drains it — PyNode DROPS on overflow,
-    # must not depend on it. It used to be `len(frames) * 2 + 64` -- the whole
+    # which would silently truncate the replay. Size to the whole film + slack.
-    # film -- to dodge a PyNode overflow drop that AR-004 has since replaced
+    # Every channel gets capacity ≥ the whole film so NOTHING can ever overflow-drop:
-    # with parking.
+    # the source can push all frames before any downstream node has drained, and a
-    #
+    # dropped frame silently corrupts the score. Memory is cheap (a few k pointers);
-    # Removing backpressure that way was catastrophic and silent. The registry
+    # correctness is not. Generous slack on top.
-    # reaped on the TRACKER's clock while evidence arrived later from the
+    cap = len(frames) * 2 + 64
    # matcher, so a deep channel closed tracks before their votes landed: on the
    # SuperHero fixture, capacity 32 gave 5 actors and capacity 10322 gave 0,
    # from identical input.
    #
    # The fix was NOT to bound this against track_extinction_sec. That would put
    # an algorithm constant in charge of a throughput knob and leave presence a
    # function of scheduling. The registry now reaps on the matcher's evidence
    # watermark (TrackRegistry::advance_evidence), so a vote cannot be late by
    # construction and this number is free again.
    cap = 64
    sae_kpn.add_node_python(net, "replay", source, [], ["EmbeddedSceneFrame"], cap)
-
+    sae_kpn.add_face_tracker(net, "tracker", cfg, cap)
-    # TRACES: VR-011, VR-002 | DP-001 | PR-002
+    sae_kpn.add_identity_matcher(net, "matcher", gallery, cfg, cap)
-    # One call builds tracker -> matcher -> annotation -> sink in the only order
+    sae_kpn.add_scene_tracker(net, "scene", cfg, cap)
    # that works (the matcher fits the calibration the tracker needs, and the
    # sink needs the registry's claims). This used to be three factory calls
    # assembled here, which is how the seam broke: the ordering constraint could
    # not be expressed, so the tracker was built from a Config alone long after
    # it had started requiring a registry and a calibration.
    cfg = dict(cfg)
    cfg["output_path"] = out_path
    cfg["movie_path"]  = movie
    cfg["sample_fps"]  = fps
    # Verbosity 1 (standard) adds the per-frame array; only pay for it when the
    # caller wants raw frames, since it retains every annotation in memory.
    cfg["verbosity"] = 1 if raw_out else 0
    sae_kpn.add_pipeline(net, gallery, cfg, cap,
                         stamp["model_name"], stamp["model_sha256"])
    net.connect("replay", 0, "tracker", 0)
    net.connect("tracker", 0, "matcher", 0)
-    net.connect("matcher", 0, "annotation", 0)
+    net.connect("matcher", 0, "scene", 0)
    net.connect("annotation", 0, "sink", 0)
    net.build()
    net.start()
-    # The sink writes on the EOF annotation. Wait for it rather than reading
+    # Read exactly one annotation per input frame. The source emits EOF as an ordinary
-    # anything back through the seam: presence is the registry's answer, and the
+    # value AFTER the last frame, but the concurrent pipeline lets that EOF OVERTAKE
-    # registry lives entirely on the C++ side.
+    # the last few real frames still flowing tracker→matcher→scene. Breaking on the
-    #
+    # first eof therefore dropped a random tail (~0.5–1%, race-dependent). Instead we
-    # This replaces a read loop that pulled one SceneAnnotation per input frame
+    # keep reading past eof until we've collected all n_frames annotations (or hit a
-    # and rebuilt windows in Python. That loop needed a heuristic -- "keep
+    # run of consecutive eofs meaning the pipeline is genuinely drained).
-    # reading past eof until we've collected all n_frames annotations, or hit a
+    n_expected = len(frames) - 1   # excludes the trailing eof frame
-    # run of 8 consecutive eofs" -- to work around a tail it was losing. None of
+    annotations = []
-    # that exists now: nothing is read per frame, so nothing can be lost per
+    eof_streak = 0
-    # frame.
+    max_reads = n_expected * 2 + 32
-    deadline = time.time() + eof_timeout
+    for _ in range(max_reads):
-    while not sae_kpn.pipeline_done(net):
+        sa = net.read("scene", 0)
-        if time.time() > deadline:
+        if sa.get("eof"):
-            sae_kpn.release_pipeline(net)
+            eof_streak += 1
-            raise TimeoutError(
+            # stragglers can still arrive after an eof; only stop once we've either
-                f"replay did not finish within {eof_timeout}s "
+            # got everything or seen several eofs in a row (truly drained).
-                f"({len(frames) - 1} frames); the sink never saw EOF")
+            if len(annotations) >= n_expected or eof_streak >= 8:
-        time.sleep(0.02)
+                break
-
+            continue
-    diag = sae_kpn.pipeline_diagnostics(net)
+        eof_streak = 0
-    if stop:
+        annotations.append(sa)
-        net.stop()
+        if len(annotations) >= n_expected:
-    sae_kpn.release_pipeline(net)
+            break
    # TRACES: VR-011 | PR-002
    # A dropped vote means the matcher lagged the tracker by more than
    # track_extinction_sec of film, so evidence arrived for a track that had
    # already been reaped. The result is not a slightly worse score -- it is a
    # silently emptier one, and this is exactly how the whole-film capacity bug
    # presented. Refuse the number rather than report it.
    # A dropped vote means a vote landed on a track already reaped. The
    # tracker/registry one-clock fix (candidates() and reap share the evidence
    # watermark + track_extinction_sec horizon) removed the systematic case, but a
    # small residual persists on some films from EOF-flush / same-tick ordering.
    # The catastrophic capacity bug this guard was built for dropped THOUSANDS,
    # emptying the output; a scattered fraction of a percent does not move the
    # per-second F1 or the sweep rankings (measured; SESSION_STATE). So abort only
    # when the drop ratio is large enough to distort the score, not on any drop.
    dropped = int(diag.get("dropped_votes", 0))
    total_faces = sum(len(f.get("embeddings", [])) for f in frames if not f.get("eof"))
    drop_ratio = dropped / total_faces if total_faces else 0.0
    kMaxDropRatio = 0.02   # 2%: well above the ~0.5% residual, far below a real bug
    if dropped and drop_ratio > kMaxDropRatio:
        raise RuntimeError(
            f"replay dropped {dropped} identity votes ({drop_ratio:.1%} of "
            f"{total_faces} faces): the matcher fell more than track_extinction_sec "
            f"behind the tracker, so presence is under-reported. Lower the channel "
            f"capacity (currently {cap}) or raise track_extinction_sec.")
    if dropped:
        print(f"[replay] tolerated {dropped} dropped votes "
              f"({drop_ratio:.2%} of {total_faces} faces)", file=sys.stderr)
    with open(out_path) as f:
        result = json.load(f)
    if raw_out:
-        write_raw_frames(result, raw_out)
+        with open(raw_out, "w") as f:
            for sa in annotations:
                f.write(json.dumps(sa) + "\n")
    result = build_minimal(annotations, movie, fps, cfg)
    if stop:
        net.stop()
    return result
-def write_raw_frames(truth: dict, raw_out: str) -> None:
+def build_minimal(annotations, movie, fps, cfg) -> dict:
-    """Per-frame annotations as JSONL, for the montage/error-frame renderers.
+    """Reproduce result_sink's minimal schema: per-actor annealed [start,end] windows.
-    TRACES: VR-011 | PR-002
+    Mirrors ResultSinkFunc::build_actor_windows — merge each actor's detection
-
+    timestamps into windows, bridging gaps shorter than anneal_sec.
    Derived from the truth file's own `frames` array (verbosity 1) rather than
    from a second stream tapped out of the network. One producer, one set of
    numbers: a bbox drawn on a montage is now provably the bbox the sink
    recorded, which it was not when Python read annotations separately.
    The shape is the legacy one -- {timestamp_sec, visible_actors:[...]} with
    actor_idx/bbox/name/similarity -- because dump_scene_montage.py and
    dump_error_frames.py read exactly those fields, and rewriting them is not
    what this requirement is about.
    """
-    with open(raw_out, "w") as f:
+    anneal = float(cfg.get("anneal_sec", 10.0))
-        for fr in truth.get("frames", []):
+    info = {}           # actor_idx -> identity fields
-            visible = []
+    times = {}          # actor_idx -> [timestamps]
-            for a in fr.get("identified", []):
+    for sa in annotations:
-                visible.append({
+        for a in sa["visible_actors"]:
-                    "actor_idx":  0,          # >= 0 means "known"; the renderers
+            if a["actor_idx"] < 0:
-                                              # test the sign, never the value
+                continue
-                    "name":       a.get("name", ""),
+            info[a["actor_idx"]] = a
-                    "imdb_id":    a.get("imdb_id", ""),
+            times.setdefault(a["actor_idx"], []).append(sa["timestamp_sec"])
-                    "tmdb_id":    a.get("tmdb_id", ""),
+
-                    "jellyfin_id": a.get("jellyfin_id", ""),
+    actors = []
-                    "similarity": a.get("similarity", 0.0),
+    for idx, ts in times.items():
-                    "track_id":   a.get("track_id", -1),
+        ts.sort()
-                    "bbox":       a.get("bbox", [0, 0, 0, 0]),
+        scenes = []
        ws = we = ts[0]
        for t in ts[1:]:
            if t - we > anneal:
                scenes.append([ws, we])
                ws = t
            we = t
        scenes.append([ws, we])
        a = info[idx]
        actors.append({
            "name": a["name"], "imdb_id": a["imdb_id"], "tmdb_id": a["tmdb_id"],
            "jellyfin_id": a["jellyfin_id"], "scenes": scenes,
        })
-            for u in fr.get("unknowns", []):
+
-                visible.append({
+    return {"schema_version": 1, "movie": movie, "sample_fps": fps,
-                    "actor_idx":  -1,
+            "anneal_sec": anneal, "actors": actors}
                    "name":       "",
                    "similarity": u.get("confidence", 0.0),
                    "track_id":   u.get("track_id", -1),
                    "bbox":       u.get("bbox", [0, 0, 0, 0]),
                })
            f.write(json.dumps({"timestamp_sec": fr.get("t", 0.0),
                                "visible_actors": visible}) + "\n")
-CFG_KEYS = ["detector_conf", "prob_threshold", "match_prior",
+CFG_KEYS = ["detector_conf", "prob_threshold", "match_prior", "match_threshold", "match_ratio",
-            "track_alpha", "track_min_iou", "track_assoc_min_prob",
+            "match_ratio_ceil", "track_alpha", "track_min_iou", "track_max_embed_dist",
-            "track_extinction_sec",
+            "track_max_frames_missing", "cut_revive_sim", "cut_inactive_max_frames",
-            # AR-025 ownership and evidence accumulation. Newly reachable:
+            "extinction_sec", "anneal_sec"]
            # these were in-class defaults no sweep could vary, which is why
            # VR-007 never covered them despite rho_max deferring to it.
            "ownership_logodds", "evidence_rho_max", "evidence_admit_below",
            "evidence_max_views",
            # AR-018 expansion bands (probability space). Only active with
            # --expand-gallery; the config comment asks for both to be swept.
            "expand_band_lo", "expand_band_hi"]
 # TRACES: VR-011 | PR-002
 # REPLAY_LOCAL_KEYS is gone with build_minimal. It held anneal_sec, the last
 # parameter this harness applied itself -- and the only reason it needed a
 # separate list was that the harness was still doing windowing the pipeline had
 # stopped doing. Every key is a Config key now, because every decision is the
 # pipeline's.
 def main():
@@ -358,34 +221,18 @@ def main():
    # per-film gallery expansion: promotes pose-varied views of confidently-identified
    # actors into an in-memory annex, recovering ~+4 recall at no precision cost.
    p.add_argument("--expand-gallery", action="store_true")
    # Presence derivation. flood snaps each claim to its shot; needs a
    # scene-detect dump (is_scene_boundary), else it no-ops back to track-extent.
    p.add_argument("--presence-mode", choices=["track_extent", "flood"], default=None)
    # TRACES: GR-004 | SR-001
    # promote an unprovable gallery/dump binding from a
    # loud warning to a hard error. Measurement sweeps should set this (or
    # SAE_REQUIRE_GALLERY_STAMP=1) so no number comes from an unbound pair.
    p.add_argument("--require-gallery-stamp", action="store_true")
    args = p.parse_args()
    cfg = {k: getattr(args, k) for k in CFG_KEYS if getattr(args, k) is not None}
    if args.expand_gallery:
        cfg["expand_gallery"] = True
    if args.presence_mode:
        cfg["presence_mode"] = args.presence_mode
    if args.require_gallery_stamp:
        cfg["require_gallery_stamp"] = True
    # stop=True: PyNode::stop() sets stop_flag_ before joining, so the source
    # thread's run_loop actually exits. stop=False skips that, leaving stop_flag_
    # false forever — the PyNode destructor's jthread.join() then blocks forever
    # (verified via gdb: stuck in the source node's run_loop, not the GEMM path).
-    result = replay(args.dump, args.gallery, cfg, args.build_dir,
+    result = replay(args.dump, args.gallery, cfg, args.build_dir, stop=True,
-                    out_path=args.out, stop=True, raw_out=args.raw_out)
+                    raw_out=args.raw_out)
-    # NOT rewritten here: the sink already wrote args.out, and that file is the
+    Path(args.out).write_text(json.dumps(result, indent=2))
    # artifact. Dumping `result` back over it would make this script the last
    # writer of a file it did not produce -- and any formatting difference would
    # be a diff between the replayed truth file and a scene_analyze one that is
    # this script's doing rather than the pipeline's.
    print(f"[replay] {len(result['actors'])} actors → {args.out}", file=sys.stderr)
@@ -2,8 +2,6 @@
 """
 second_score.py — uniform per-second agreement with X-Ray.
 TRACES: VR-003 | PR-002
 Unlike scene_score.py (which unions our detections over a whole X-Ray scene), this
 samples EVERY SECOND of the film and asks: at second t, do we name the same actors
 X-Ray says are on screen?
@@ -95,15 +93,7 @@ def load_pred_intervals(pred_json: dict):
    for a in pred_json.get("actors", []):
        keys = frozenset(keys_for(imdb_id=a.get("imdb_id"), tmdb_id=a.get("tmdb_id"),
                                  jellyfin_id=a.get("jellyfin_id"), name=a.get("name")))
-        # schema_version 1: scenes is [[t0, t1], ...]; schema_version 2:
+        out.append((keys, [(float(t0), float(t1)) for t0, t1 in a.get("scenes", [])]))
        # scenes is [{"start":…, "end":…, "belief":…, "route":…}, …].
        windows = []
        for s in a.get("scenes", []):
            if isinstance(s, dict):
                windows.append((float(s["start"]), float(s["end"])))
            else:
                windows.append((float(s[0]), float(s[1])))
        out.append((keys, windows))
    return out
@@ -1,29 +1,16 @@
 #!/usr/bin/env python3
 """
-Smoke test for the sae_kpn module: assemble the real downstream pipeline
+Smoke test for the sae_kpn module: assemble the real downstream pipeline nodes
-(tracker → matcher → annotation → sink) in a Python-driven KPN network, fed by a
+(face_tracker → identity_matcher → scene_tracker) in a Python-driven KPN network,
-no-input Python source node, and verify the sink writes a truth file.
+fed by a no-input Python source node, and verify SceneAnnotations flow out.
 TRACES: VR-011 | PR-002
 Proves the KPN-native replay path works without any numpy port of node logic.
 Rewritten for `add_pipeline`. It previously called three node factories and read
 SceneAnnotations back through the seam, asserting on what came out per frame.
 Neither half of that survives VR-011: the factories are gone because the chain
 has a construction order Python could not express, and presence is now the C++
 sink's answer, derived from TrackRegistry claims. Nothing is read per frame, so
 the assertions are on the file the sink writes.
 Run:  python scripts/optimizer/test_sae_kpn.py [gallery.json] [build_dir]
 """
 import json
 import sys
-import tempfile
+import queue
 import time
 from pathlib import Path
 import numpy as np
 from pathlib import Path
 REPO = Path(__file__).resolve().parent.parent.parent
 GAL = sys.argv[1] if len(sys.argv) > 1 else str(REPO / "gallery_arcface_w600k_r50.json")
@@ -44,6 +31,7 @@ def make_frame(t, n):
 def main():
    net = sae_kpn.Network()
    sae_kpn._register_types(net)
    cfg = {"prob_threshold": 0.99, "anneal_sec": 10.0, "extinction_sec": 5.0}
    frames = [make_frame(float(t), 1) for t in range(3)]
    frames.append({"timestamp_sec": 3.0, "eof": True})
@@ -51,67 +39,36 @@ def main():
    eof_frame = {"timestamp_sec": 3.0, "eof": True}
    def source():
-        # Emit each frame once, then keep returning EOF so the node thread stays
+        # Emit each frame once, then keep returning EOF (never block) so the node
-        # responsive to stop(). The sleep matters: a no-input source is called in
+        # thread stays responsive to stop() after the sink has seen EOF.
        # a tight loop, and hot-spinning EOFs pegs a core and floods the channel.
        i = idx[0]
        idx[0] += 1
-        if i < len(frames):
+        return frames[i] if i < len(frames) else eof_frame
            return frames[i]
        time.sleep(0.05)
        return eof_frame
    with tempfile.TemporaryDirectory() as tmp:
        out_path = str(Path(tmp) / "truth.json")
        cfg = {
            "prob_threshold": 0.99,
            "track_extinction_sec": 5.0,
            "output_path": out_path,
            "movie_path": "sae_kpn smoke test",
            "sample_fps": 1.0,
            # Standard verbosity emits the per-frame array this test asserts on.
            # At 0 the file carries only the actor epochs, and three random
            # embeddings against a real gallery need not produce any.
            "verbosity": 1,
        }
        sae_kpn.add_node_python(net, "replay", source, [], ["EmbeddedSceneFrame"], 16)
        # No embedder stamp: these embeddings are random, not the output of any
        # model, so there is nothing truthful to claim. That warns rather than
        # failing, and would be fatal under SAE_REQUIRE_GALLERY_STAMP — which is
        # correct, since an unverifiable binding is exactly what it guards.
        sae_kpn.add_pipeline(net, GAL, cfg, 16)
    sae_kpn.add_node_python(net, "replay", source, [], ["EmbeddedSceneFrame"], 8)
    sae_kpn.add_face_tracker(net, "tracker", cfg, 16)
    sae_kpn.add_identity_matcher(net, "matcher", GAL, cfg, 16)
    sae_kpn.add_scene_tracker(net, "scene", cfg, 16)
    net.connect("replay", 0, "tracker", 0)
    net.connect("tracker", 0, "matcher", 0)
-        net.connect("matcher", 0, "annotation", 0)
+    net.connect("matcher", 0, "scene", 0)
        net.connect("annotation", 0, "sink", 0)
    net.build()
    net.start()
-        # The sink writes on the EOF annotation. Wait for that rather than
+    got = []
-        # reading anything back: presence lives entirely on the C++ side.
+    for _ in range(4):
-        deadline = time.time() + 30.0
+        sa = net.read("scene", 0)
-        while not sae_kpn.pipeline_done(net):
+        got.append(sa)
-            if time.time() > deadline:
+        if sa.get("eof"):
-                sae_kpn.release_pipeline(net)
+            break
                raise TimeoutError("sink never saw EOF within 30s")
            time.sleep(0.02)
    net.stop()
        sae_kpn.release_pipeline(net)
-        with open(out_path) as f:
+    non_eof = [g for g in got if not g.get("eof")]
-            truth = json.load(f)
+    assert len(non_eof) == 3, f"expected 3 annotations, got {len(non_eof)}"
-
+    assert got[-1].get("eof"), "expected trailing EOF"
-    per_frame = truth.get("frames", [])
+    assert [g["timestamp_sec"] for g in non_eof] == [0.0, 1.0, 2.0], "timestamps wrong"
-    assert "actors" in truth, "truth file has no actors array"
+    assert all("visible_actors" in g for g in non_eof), "missing visible_actors"
-    assert len(per_frame) == 3, f"expected 3 frames, got {len(per_frame)}"
+    print(f"OK: {len(non_eof)} annotations through the real KPN chain, EOF received")
    # EOF is a control token, not an observation: the sink flushes on it and does
    # not record it, so three inputs give three frames and never four.
    assert [f["t"] for f in per_frame] == [0.0, 1.0, 2.0], "timestamps wrong"
    assert all("identified" in f for f in per_frame), "missing identified"
    print(f"OK: {len(per_frame)} frames through the real KPN chain, sink wrote its truth file")
 if __name__ == "__main__":
@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 """run_from_jellyfin.py — resolve a Jellyfin title to its media file and run scene_analyze.
 TRACES: IR-006 | SR-001
 Looks up a Movie/Episode in Jellyfin, reads its on-disk Path (Jellyfin and this
 tool must share the same media mount), filters the gallery down to that
 title's credited cast (via filter_gallery's logic, fewer look-alike
@@ -3,29 +3,11 @@
 sae_embed.FaceEmbedder loads both ONNX sessions once and exposes an
 embed(path) -> FaceResult method, avoiding the per-process model reload cost
 of spawning the embed_faces CLI binary for every image.
 resolve_arcface() exposes the same default-resolution logic load_embedder uses,
 so a caller can stamp the gallery it is about to write with the model that
 actually produced its embeddings (GR-004) — the resolved path, not the CLI
 argument, which is often None.
 """
 import sys
 import os
 from pathlib import Path
 DEFAULT_ARCFACE = "arcface_w600k_r50.onnx"
 def resolve_arcface(models_dir: str, arcface: str | None = None) -> str:
    """The ArcFace/LVFace ONNX path load_embedder would use for these arguments.
    TRACES: GR-004 | SR-001
    Single source of truth for "which model is this", so the stamp written into
    a gallery can never drift from the model loaded."""
    return arcface if arcface else str(Path(models_dir) / DEFAULT_ARCFACE)
 def load_embedder(build_dir: str, models_dir: str, arcface: str | None = None,
                   conf: float = 0.5, nms: float = 0.4, max_side: int = 500):
@@ -46,27 +28,19 @@ def load_embedder(build_dir: str, models_dir: str, arcface: str | None = None,
    models_path = Path(models_dir)
    detector_path = str(models_path / "scrfd_500m_bnkps.onnx")
-    arcface_path = resolve_arcface(models_dir, arcface)
+    arcface_path = arcface if arcface else str(models_path / "arcface_w600k_r50.onnx")
    for model, name in [(detector_path, "SCRFD"), (arcface_path, "ArcFace")]:
        if not Path(model).is_file():
            sys.exit(f"{name} model not found: {model}\nRun: bash scripts/download_models.sh")
    # A TRT-backend build cannot load .onnx; it needs pre-built engines from
-    # scripts/build_trt_engines.sh.
+    # scripts/build_trt_engines.sh. Pass them when present (ignored by ORT).
    #
    # These are passed only on request. The old comment here claimed they were
    # "ignored by ORT" — they are not. The ORT backend treats an engine path as
    # an instruction and raises, which is the right behaviour (silently ignoring
    # a requested engine would be worse), but it meant that merely HAVING a
    # populated trt_cache/ broke every ORT gallery build in the repo, with an
    # error naming a flag the caller never set.
    use_engines = os.environ.get("SAE_USE_TRT_ENGINES", "") not in ("", "0", "false")
    trt = Path(models_path).parent / "trt_cache"
    det_engine = trt / "scrfd.scrfd_500m_bnkps.640.fp16.engine"
    arc_engine = trt / f"arcface.{Path(arcface_path).stem}.b4.fp16.engine"
    return sae_embed.FaceEmbedder(
        detector_path, arcface_path, conf, nms, max_side,
-        str(det_engine) if (use_engines and det_engine.is_file()) else "",
+        str(det_engine) if det_engine.is_file() else "",
-        str(arc_engine) if (use_engines and arc_engine.is_file()) else "",
+        str(arc_engine) if arc_engine.is_file() else "",
    )
@@ -6,13 +6,9 @@ make_jellyfin_gallery.download_urls + download_person_images) and the duplicated
 Galleries are written directly as HDF5 — never JSON. Same layout the C++ side
 reads/writes (src/gallery/gallery_store.cpp): flat [N,512] embeddings + per-actor
-offset/count, parallel imdb_id/tmdb_id/jellyfin_id/name string arrays, a
+offset/count, parallel imdb_id/tmdb_id/jellyfin_id/name string arrays, and a
-per-embedding-row source_images array, and an /embedder group carrying the
+per-embedding-row source_images array. calibration is left absent (calib_hash=0);
-GR-004 model binding. calibration is left absent (calib_hash=0); the C++
+the C++ identity_matcher fits and writes it back into the file on first use.
 identity_matcher fits and writes it back into the file on first use.
 The GR-004 embedder stamp written into that /embedder group lives in sae_stamp
 and is re-exported below, so existing callers keep importing it from here.
 """
 import io
@@ -105,36 +101,11 @@ def download_images(urls: list[str], dest_dir: Path, n: int,
    return paths
-# ── GR-004: gallery ↔ embedder binding ───────────────────────────────────────
+def save_gallery_hdf5(gallery: dict, output: Path) -> None:
 # Implemented in sae_stamp (kept dependency-light so the optimizer's replay
 # subprocesses can import it without pulling requests/Pillow); re-exported here
 # because the gallery writers and every existing caller reach for it via this
 # module. See src/gallery/embedder_stamp.hpp for the C++ twin and the rationale.
 from sae_stamp import (  # noqa: F401
    EmbedderMismatch,
    check_embedder_stamp,
    describe_stamp,
    embedder_stamp,
    enforce_embedder_stamp,
    read_gallery_stamp,
    require_gallery_stamp_from_env,
    sha256_file,
    verify_gallery_stamp,
    _as_str,
    _stamp_empty,
 )
 def save_gallery_hdf5(gallery: dict, output: Path, embedder: dict | None = None) -> None:
    """Write a gallery dict ({"actors": [...]}) directly as HDF5 — same schema
    src/gallery/gallery_store.cpp reads/writes. No calibration group; the
    C++ identity_matcher computes and writes it back into this file on first
-    use against an unseen set of embeddings.
+    use against an unseen set of embeddings."""
    `embedder` is the GR-004 stamp (see embedder_stamp()); it may also be carried
    on the gallery dict under "embedder", which is how a filtered/derived gallery
    keeps its binding without the caller having to re-hash anything."""
    embedder = embedder if embedder is not None else gallery.get("embedder")
    actors = gallery["actors"]
    embs, offsets, counts = [], [], []
    imdb, tmdb, jf, name, src_images = [], [], [], [], []
@@ -168,18 +139,8 @@ def save_gallery_hdf5(gallery: dict, output: Path, embedder: dict | None = None)
        f.create_dataset("jellyfin_id", data=np.asarray(jf, dtype=object), dtype=str_t)
        f.create_dataset("name", data=np.asarray(name, dtype=object), dtype=str_t)
        f.create_dataset("source_images", data=np.asarray(src_images, dtype=object), dtype=str_t)
-        # TRACES: GR-004 | SR-001
+    print(f"Saved: {output} ({len(actors)} actors, {emb_arr.shape[0]} embeddings)",
-        # omitted entirely when unknown, so "unstamped"
+          file=sys.stderr)
        # round-trips as unstamped rather than as a stamp naming no model.
        if not _stamp_empty(embedder):
            g = f.create_group("embedder")
            g.attrs["model_name"] = embedder.get("model_name", "")
            g.attrs["model_sha256"] = embedder.get("model_sha256", "")
            g.attrs["embed_dim"] = np.int32(embedder.get("embed_dim", 512))
    stamp_note = (f", embedder {embedder['model_name']}" if not _stamp_empty(embedder)
                  else ", NO EMBEDDER STAMP (GR-004)")
    print(f"Saved: {output} ({len(actors)} actors, {emb_arr.shape[0]} embeddings"
          f"{stamp_note})", file=sys.stderr)
 def load_gallery_hdf5(path: Path) -> dict:
@@ -197,15 +158,6 @@ def load_gallery_hdf5(path: Path) -> dict:
        if "source_images" in f:
            src_images = [s.decode() if isinstance(s, bytes) else s
                         for s in f["source_images"][:]]
        # TRACES: GR-004 | SR-001
        # carried through so a derived gallery (filter,
        # merge, cast-restrict) keeps the binding of the gallery it came from.
        stamp = None
        if "embedder" in f:
            a = f["embedder"].attrs
            stamp = {"model_name": _as_str(a.get("model_name", "")),
                     "model_sha256": _as_str(a.get("model_sha256", "")),
                     "embed_dim": int(a.get("embed_dim", 512))}
    actors = []
    for a in range(len(offset)):
@@ -215,19 +167,15 @@ def load_gallery_hdf5(path: Path) -> dict:
        if src_images is not None:
            actor["source_images"] = [src_images[s + i] for i in range(n)]
        actors.append(actor)
-    out = {"actors": actors}
+    return {"actors": actors}
    if stamp is not None:
        out["embedder"] = stamp
    return out
-def save_gallery(gallery: dict, missing: list[dict], output: Path,
+def save_gallery(gallery: dict, missing: list[dict], output: Path) -> None:
                 embedder: dict | None = None) -> None:
    """Write the gallery as HDF5 (forcing a .h5 extension) and, if any actors
    lack images, a .missing_images.json sidecar."""
    if output.suffix not in (".h5", ".hdf5"):
        output = output.with_suffix(".h5")
-    save_gallery_hdf5(gallery, output, embedder)
+    save_gallery_hdf5(gallery, output)
    if missing:
        missing_path = output.with_name(output.stem + ".missing_images.json")
@@ -1,217 +0,0 @@
 """Gallery ↔ embedder model binding (GR-004).
 TRACES: GR-004 | SR-001
 Python twin of src/gallery/embedder_stamp.{hpp,cpp}; the two implement the same
 comparison rules and must stay in agreement. Kept as its own module — rather than
 folded into sae_gallery — because scripts/optimizer/replay.py imports it once per
 replay subprocess, thousands of times in a DE sweep, and must not pay for
 sae_gallery's requests/Pillow imports to ask "were these made by the same model?".
 Dependencies here are hashlib, json and h5py, all of which a replay already loads.
 A gallery is only valid for the embedder that built it: cosine similarities across
 models are meaningless but look plausible, so the mistake is silent and every
 measurement taken afterwards is suspect. Identity = model filename + SHA-256 of
 the model file. The hash decides (a model re-exported in place keeps its name but
 not its bytes); the name is what makes the error readable. See
 src/gallery/embedder_stamp.hpp for the full rationale.
 """
 import hashlib
 import json
 import os
 import sys
 from pathlib import Path
 import h5py
 def _as_str(v) -> str:
    return v.decode() if isinstance(v, bytes) else ("" if v is None else str(v))
 _STAMP_CACHE: dict = {}
 class EmbedderMismatch(RuntimeError):
    """Gallery was built with a different embedder than the one about to be used."""
 def sha256_file(path) -> str:
    """Lowercase hex SHA-256 of a file's bytes; "" if it cannot be read."""
    path = Path(path)
    try:
        st = path.stat()
    except OSError:
        return ""
    key = (str(path), st.st_mtime_ns, st.st_size)
    if key in _STAMP_CACHE:
        return _STAMP_CACHE[key]
    h = hashlib.sha256()
    try:
        with open(path, "rb") as f:
            for chunk in iter(lambda: f.read(1 << 20), b""):
                h.update(chunk)
    except OSError:
        return ""
    _STAMP_CACHE[key] = h.hexdigest()
    return _STAMP_CACHE[key]
 def embedder_stamp(model_path, embed_dim: int = 512) -> dict:
    """Identify an embedder model file → {"model_name", "model_sha256", "embed_dim"}.
    A model file that is absent (e.g. a TRT deployment running from a prebuilt
    .engine) yields a name-only stamp: still comparable, just not provable."""
    if not model_path:
        return {"model_name": "", "model_sha256": "", "embed_dim": embed_dim}
    sha = sha256_file(model_path)
    if not sha:
        print(f"[gallery] cannot hash embedder model {model_path} — model binding "
              f"falls back to filename only (GR-004)", file=sys.stderr)
    return {"model_name": Path(model_path).name, "model_sha256": sha,
            "embed_dim": embed_dim}
 def _stamp_empty(s) -> bool:
    return not s or (not s.get("model_name") and not s.get("model_sha256"))
 def describe_stamp(s) -> str:
    if _stamp_empty(s):
        return "UNKNOWN"
    name = s.get("model_name") or "<unnamed model>"
    sha = s.get("model_sha256") or ""
    return f"{name} (sha256 {sha[:12]}…)" if sha else f"{name} (sha256 unavailable)"
 def require_gallery_stamp_from_env() -> bool:
    """SAE_REQUIRE_GALLERY_STAMP=1 → an unprovable binding is fatal, not a warning."""
    return os.environ.get("SAE_REQUIRE_GALLERY_STAMP", "0") not in ("", "0")
 def check_embedder_stamp(built_with: dict | None, loading_with: dict | None,
                         gallery_desc: str = "gallery",
                         embedder_desc: str = "embedder") -> tuple[str, str]:
    """Pure comparison. Returns (verdict, message); verdict is one of
    match / weak_match / unstamped / unknown_embedder / mismatch.
    Same rules as compare_embedder_stamps() in src/gallery/embedder_stamp.cpp."""
    if _stamp_empty(built_with):
        return "unstamped", (
            f"gallery '{gallery_desc}' carries no embedder stamp (GR-004).\n"
            f"  gallery was built with : UNKNOWN — this file predates model binding\n"
            f"  embedder now loaded    : {describe_stamp(loading_with)}  [{embedder_desc}]\n"
            f"  If these are not the same model every similarity from this run is\n"
            f"  meaningless but will look plausible. Rebuild or re-stamp the gallery\n"
            f"  (scripts/stamp_gallery.py), or run with SAE_REQUIRE_GALLERY_STAMP=1 to\n"
            f"  make this a hard error.")
    if _stamp_empty(loading_with):
        return "unknown_embedder", (
            f"cannot identify the embedder being used against gallery "
            f"'{gallery_desc}' (GR-004).\n"
            f"  gallery was built with : {describe_stamp(built_with)}\n"
            f"  embedder now loaded    : UNKNOWN [{embedder_desc}]\n"
            f"  The binding cannot be checked, so it is not being checked.")
    mismatch_tail = (
        "  Cosine similarities between embeddings from different models are\n"
        "  meaningless but look plausible. Rebuild the gallery with the loaded\n"
        "  model, or point the embedder at the model the gallery was built with.")
    if int(built_with.get("embed_dim", 512)) != int(loading_with.get("embed_dim", 512)):
        return "mismatch", (
            f"gallery/embedder MODEL MISMATCH — refusing to run (GR-004).\n"
            f"  gallery was built with : {describe_stamp(built_with)}, "
            f"dim={built_with.get('embed_dim')}  [{gallery_desc}]\n"
            f"  embedder now loaded    : {describe_stamp(loading_with)}, "
            f"dim={loading_with.get('embed_dim')}  [{embedder_desc}]\n"
            f"  Embedding dimensions differ; these are not the same space.")
    a, b = built_with.get("model_sha256", ""), loading_with.get("model_sha256", "")
    if a and b:
        if a == b:
            note = ""
            if built_with.get("model_name") != loading_with.get("model_name"):
                note = (f" (gallery recorded it as '{built_with.get('model_name')}', "
                        f"loaded from '{loading_with.get('model_name')}' — "
                        f"same bytes, renamed file)")
            return "match", f"embedder binding verified: {describe_stamp(built_with)}{note}"
        return "mismatch", (
            f"gallery/embedder MODEL MISMATCH — refusing to run (GR-004).\n"
            f"  gallery was built with : {built_with.get('model_name')}  sha256={a}\n"
            f"                           [{gallery_desc}]\n"
            f"  embedder now loaded    : {loading_with.get('model_name')}  sha256={b}\n"
            f"                           [{embedder_desc}]\n" + mismatch_tail)
    if built_with.get("model_name") and \
            built_with.get("model_name") == loading_with.get("model_name"):
        return "weak_match", (
            f"embedder binding UNPROVEN for gallery '{gallery_desc}' (GR-004).\n"
            f"  gallery was built with : {describe_stamp(built_with)}\n"
            f"  embedder now loaded    : {describe_stamp(loading_with)}  [{embedder_desc}]\n"
            f"  Filenames agree but at least one SHA-256 is unavailable, so an\n"
            f"  in-place re-export under the same name would not be detected.")
    return "mismatch", (
        f"gallery/embedder MODEL MISMATCH — refusing to run (GR-004).\n"
        f"  gallery was built with : {describe_stamp(built_with)}  [{gallery_desc}]\n"
        f"  embedder now loaded    : {describe_stamp(loading_with)}  [{embedder_desc}]\n"
        + mismatch_tail)
 def enforce_embedder_stamp(built_with, loading_with, gallery_desc, embedder_desc,
                           require_stamp: bool = False) -> str:
    """Apply check_embedder_stamp: raise EmbedderMismatch when fatal, else warn.
    A mismatch is fatal unconditionally — there is no bypass, because a mismatch is
    a known-wrong state, not an unknown one. The three "cannot prove it" verdicts
    warn loudly and become fatal under require_stamp / SAE_REQUIRE_GALLERY_STAMP."""
    strict = require_stamp or require_gallery_stamp_from_env()
    verdict, msg = check_embedder_stamp(built_with, loading_with,
                                        gallery_desc, embedder_desc)
    if verdict == "mismatch":
        raise EmbedderMismatch(msg)
    if strict and verdict != "match":
        raise EmbedderMismatch(
            msg + "\n  (fatal because SAE_REQUIRE_GALLERY_STAMP is set)")
    if verdict == "match":
        print(f"[gallery] {msg}", file=sys.stderr)
    else:
        print(f"\n[gallery] ***** WARNING (GR-004) *****\n{msg}\n"
              f"[gallery] ****************************\n", file=sys.stderr)
    return verdict
 def read_gallery_stamp(path) -> dict | None:
    """The embedder stamp recorded in a gallery file, or None if unstamped.
    Handles both the HDF5 /embedder group and the legacy JSON "embedder" object."""
    path = Path(path)
    if path.suffix in (".h5", ".hdf5"):
        with h5py.File(path, "r") as f:
            if "embedder" not in f:
                return None
            a = f["embedder"].attrs
            return {"model_name": _as_str(a.get("model_name", "")),
                    "model_sha256": _as_str(a.get("model_sha256", "")),
                    "embed_dim": int(a.get("embed_dim", 512))}
    data = json.loads(path.read_text())
    return data.get("embedder") or None
 def verify_gallery_stamp(gallery_path, model_path=None, *, stamp=None,
                         embedder_desc: str | None = None,
                         require_stamp: bool = False) -> str:
    """Load a gallery's stamp and check it against a model file (or an explicit
    stamp, e.g. one read off an embedding dump). Raises EmbedderMismatch."""
    loading = stamp if stamp is not None else embedder_stamp(model_path)
    return enforce_embedder_stamp(read_gallery_stamp(gallery_path), loading,
                                  str(gallery_path),
                                  embedder_desc or str(model_path or "unknown"),
                                  require_stamp)
 def _as_str(v) -> str:
    return v.decode() if isinstance(v, bytes) else ("" if v is None else str(v))
@@ -1,86 +0,0 @@
 #!/usr/bin/env python3
 """stamp_gallery.py — bind an existing gallery to the embedder that built it.
 TRACES: GR-004 | SR-001
 Galleries built before model binding carry no embedder stamp. They still load,
 but every consumer warns that it cannot tell whether the gallery and the embedder
 belong together — and under SAE_REQUIRE_GALLERY_STAMP=1 they refuse to run.
 This is the migration path, and the reason the unstamped case is a warning rather
 than a hard failure: re-binding an existing gallery costs one command and no
 re-embedding, so nobody has to choose between a bricked setup and a check they
 route around.
    python scripts/stamp_gallery.py --gallery gallery.h5 \\
        --arcface models/LVFace-B_Glint360K.onnx
 The stamp is an ASSERTION: you are stating which model produced these vectors.
 Nothing can verify it from the vectors themselves, which is exactly why the stamp
 has to be written at build time going forward. Stamping the wrong model is worse
 than leaving it unstamped, because it converts a loud warning into a false
 all-clear — so --show it first if you are not certain.
    python scripts/stamp_gallery.py --gallery gallery.h5 --show
 """
 from __future__ import annotations
 import argparse
 import sys
 from pathlib import Path
 import h5py
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from sae_gallery import (describe_stamp, embedder_stamp,  # noqa: E402
                         read_gallery_stamp)
 def main() -> int:
    p = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--gallery", required=True, help="gallery .h5 to stamp in place")
    p.add_argument("--arcface", help="the ONNX that built it (hashed into the stamp)")
    p.add_argument("--show", action="store_true", help="print the current stamp and exit")
    p.add_argument("--force", action="store_true",
                   help="overwrite an existing stamp (refused otherwise)")
    args = p.parse_args()
    path = Path(args.gallery)
    if path.suffix not in (".h5", ".hdf5"):
        return err(f"{path}: only HDF5 galleries can be stamped in place")
    current = read_gallery_stamp(path)
    print(f"{path}: current stamp = {describe_stamp(current)}", file=sys.stderr)
    if args.show:
        return 0
    if not args.arcface:
        return err("--arcface is required (or use --show)")
    if current and not args.force:
        return err("gallery is already stamped — pass --force to overwrite, but be "
                   "sure: a wrong stamp turns a warning into a false all-clear")
    stamp = embedder_stamp(args.arcface)
    if not stamp["model_sha256"]:
        return err(f"cannot hash {args.arcface} — refusing to write a name-only "
                   "stamp, which would claim more certainty than it has")
    with h5py.File(path, "r+") as f:
        if "embedder" in f:
            del f["embedder"]
        g = f.create_group("embedder")
        g.attrs["model_name"] = stamp["model_name"]
        g.attrs["model_sha256"] = stamp["model_sha256"]
        g.attrs["embed_dim"] = stamp["embed_dim"]
    print(f"{path}: stamped with {describe_stamp(stamp)}", file=sys.stderr)
    return 0
 def err(msg: str) -> int:
    print(f"[stamp_gallery] {msg}", file=sys.stderr)
    return 1
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,62 @@
 #!/bin/sh
 #
 # Requirement traceability gate. Run locally exactly as CI runs it, from the
 # component repo root:
 #
 #     scripts/traceability/traceability-gate.sh
 #
 # Writes the JSON report and the markdown matrix, prints the coverage report,
 # and exits non-zero when the gate fails.
 #
 # This script is shared by every JRay component, so it knows nothing about any
 # one repo. All repo-specific settings - requirement ID prefixes, source
 # suffixes, scan roots, register path, thresholds - live in `traceability.toml`
 # at the component repo root. Run
 #
 #     scripts/traceability/extract_traces.py --print-example-config
 #
 # for the annotated schema. A repo whose config is wrong parses zero
 # requirements or scans zero files, and the gate refuses to report rather than
 # printing a misleading 0%.
 #
 # Environment (all optional; each overrides the config file):
 #   TRACES_CONFIG   path to traceability.toml
 #   TRACES_ROOT     repo root (default: nearest dir containing traceability.toml)
 #   MIN_COVERAGE    minimum overall coverage percent
 #   ALLOW_ORPHANS   1 to report orphan tags without failing
 #   TRACES_JSON     JSON report path
 #   TRACES_MD       markdown matrix path
 #   SYSTEM_SPEC     SPEC.md defining PR/SR; enables PR/SR orphan checking
 #   PYTHON          interpreter (default: python3)
 #
 # Threshold policy belongs in traceability.toml, not here and not in the
 # workflow YAML: a threshold written in two places is a threshold that will
 # disagree with itself.
 #
 # POSIX sh, no bashisms, no jq - the extractor does its own arithmetic and
 # printing, so CI needs nothing beyond python3.
 set -eu
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 PYTHON="${PYTHON:-python3}"
 command -v "$PYTHON" >/dev/null 2>&1 || {
    echo "FAILED: $PYTHON not found. The traceability gate needs Python 3.9+," >&2
    echo "        or 3.11+ to read traceability.toml." >&2
    exit 2
 }
 set -- --format coverage
 # Explicit `if` rather than `[ ... ] && ...`, because a trailing false test in
 # an && list exits under `set -e` in some POSIX shells.
 if [ -n "${TRACES_CONFIG:-}" ]; then set -- "$@" --config "$TRACES_CONFIG"; fi
 if [ -n "${TRACES_ROOT:-}" ];   then set -- "$@" --root "$TRACES_ROOT"; fi
 if [ -n "${MIN_COVERAGE:-}" ];  then set -- "$@" --min-coverage "$MIN_COVERAGE"; fi
 if [ -n "${TRACES_JSON:-}" ];   then set -- "$@" --json-out "$TRACES_JSON"; fi
 if [ -n "${TRACES_MD:-}" ];     then set -- "$@" --markdown-out "$TRACES_MD"; fi
 if [ -n "${SYSTEM_SPEC:-}" ];   then set -- "$@" --system-spec "$SYSTEM_SPEC"; fi
 if [ "${ALLOW_ORPHANS:-0}" = "1" ]; then set -- "$@" --allow-orphans; fi
 exec "$PYTHON" "$SCRIPT_DIR/extract_traces.py" "$@"
@@ -79,30 +79,9 @@ The table caches nulls (tmdb ids TMDB has no IMDb id for) and checkpoints, so a
 re-run only resolves new ids. TMDB is authoritative for this crosswalk — there is
 no clean free bulk `tmdb_person ↔ nm` file, so we query the API once and cache.
 ## Minimum face size (VR-005)
 `min_face_size.py` is a separate, self-contained study: it needs no video and no
 ground truth, only the gallery mugshot cache. It holds out one image per actor,
 degrades that probe to each candidate face size and matches it against a gallery
 held at **native** resolution, reporting TPI/FPI per size — the measurement that
 replaces AR-002's 66×66 px estimate.
 ```bash
 python scripts/validation/min_face_size.py \
    --images images --gallery gallery_lvface.h5 \
    --arcface models/LVFace-B_Glint360K.onnx \
    --actors 100 --out experiments/results/vr005_min_face_size
 ```
 FPI grows with the number of actors competing, so a 100-actor run understates it
 against a library of thousands: read FPI as relative across sizes, not as an
 absolute rate. Re-run per `--arcface` model to see whether `min_face_px` should be
 one constant or scale with the embedder (GR-004).
 ## Files
 - `sample_eval.py`   — CLI scorer.
 - `ground_truth.py`  — `XRayGroundTruth`, `MovieNetGroundTruth` loaders.
 - `identity.py`      — provider-agnostic match keys.
 - `tmdb_imdb_map.py` — build/consult the cached `tmdb→imdb` crosswalk.
 - `min_face_size.py` — VR-005 probe-size sweep (see above).
 - `test_sample_eval.py` — self-contained tests (`python scripts/validation/test_sample_eval.py`).
@@ -17,11 +17,6 @@ X-Ray/MovieNet key on IMDb nm-ids — see [[per-scene-presence-eval-design]].
 Two sources implemented:
  * XRayGroundTruth  — Zenodo scene-level Amazon X-Ray CSVs (cast-in-scene).
  * MovieNetGroundTruth — MovieNet-PS per-shot face annotations (on-screen faces).
 Both are published corpora addressed by title, so a scoring run is reproducible
 from the identifiers alone — no annotation of ours travels with the code.
 TRACES: VR-004 | PR-002
 """
 from __future__ import annotations
@@ -1,822 +0,0 @@
 #!/usr/bin/env python3
 """
 min_face_size.py — VR-005: at what face size do embeddings stop identifying people?
 TRACES: VR-005
 `min_face_px` is currently a working estimate (AR-002: 66x66 px in original video
 resolution). This script replaces the guess with a measurement, using only gallery
 mugshots already on disk — no video, no C++ changes.
 Protocol
 --------
 1. Select ~100 gallery actors that have more than one mugshot.
 2. Per actor hold out ONE image as the *probe*; that actor's remaining images stay
   in the gallery at native resolution.
 3. For each target size S, take the probe's native aligned 112x112 crop, downscale
   it to SxS and upscale it back to 112x112, then embed. Detail is genuinely
   destroyed and then the same warp the pipeline applies is re-applied on top —
   which is what a face detected at SxS in a frame actually suffers.
 4. Match each degraded probe against the whole gallery.
 5. Record, per size, TPI (identified as the correct actor) and FPI (identified as
   someone else). Everything else is an unidentified probe (TBI).
 The asymmetry is the point: **the gallery stays at native resolution and only the
 probe degrades.** That is the production case — reference mugshots are clean, the
 face coming out of the video is small. Degrading both sides would measure
 something the pipeline never does.
 What this deliberately does NOT measure
 ---------------------------------------
 The cosine between the size-S embedding and the native embedding of the *same*
 image. That is embedding *drift*, and it answers the wrong question: an embedding
 can drift a long way and stay perfectly separable, or drift a little in a
 direction that destroys separation. What matters is the decision the pipeline
 makes — probe against a competing gallery — so that is what is recorded.
 CAVEAT — FPI IS RELATIVE, NOT ABSOLUTE
 --------------------------------------
 False positives grow with the number of actors competing for the match. A
 ~100-actor gallery therefore *understates* the false-positive rate against a
 production library of thousands. Read the FPI column as a relative curve across
 sizes ("FPI is 4x worse at 32 px than at 64 px"), never as the rate you would see
 in production. Re-run with `--actors` at production scale before setting a
 threshold from an absolute FPI number.
 Decision rule
 -------------
 Per the repo invariant (CLAUDE.md: "always use the calibrated probability, never a
 raw cosine"), identification goes through the same path as `identity_matcher_node`:
 per-actor best-of-N cosine -> Platt sigmoid P(match) = sigma(a*sim + b + log-prior)
 -> accept if P > `prob_threshold`. The sigmoid is fitted here by the same
 histogram/gradient-descent procedure as `src/gallery/gallery_calibration.hpp`,
 over the native gallery embeddings only (held-out probes are excluded, so the
 calibration cannot see the images it will be scored on).
 How this runs
 -------------
 Through the `sae_embed` bindings, which expose the shipped C++ stages directly:
 `detect()`, `align_face()`, `embed_crops()` and `GalleryCalibration`. Nothing
 here re-implements detection, the ArcFace warp, the embedder or the Platt fit.
 That matters most for the calibration. A second copy of the sigmoid is exactly
 where "always the calibrated probability, never a raw cosine" (AR-024) gets
 broken without anyone noticing, because the copy keeps returning plausible
 numbers after the original has moved. Scoring through the binding makes the rule
 structural instead of remembered.
 The backend is whichever was compiled in. Under `SAE_INFERENCE_BACKEND=ORT`
 that is the reference fp32 path, which loads the .onnx directly. A TensorRT fp16
 build is a *different realisation* of the same model and its embeddings are
 measurably not the same vectors: on LVFace-B_Glint360K the stored TRT-fp16 gallery
 agrees with an fp32 recompute of the same mugshot at only ~0.85 cosine, while
 same-actor/different-actor separation is essentially unchanged (d' 5.3 vs 5.7).
 Nothing here is invalidated by that — gallery and probes go through one session,
 so the comparison is internally consistent — but the two embedding spaces are not
 interchangeable, and `--verify-against <gallery.h5>` will show ~0.85, not ~1.0,
 against a TRT-built gallery. It reports the separation of both sets alongside the
 agreement so the two causes are distinguishable: a broken port collapses
 separation, a different backend does not.
 Secondary output (VR-005): running the sweep per `--arcface` model shows whether
 `min_face_px` should be one constant at all, or should scale with the embedder —
 which matters because the model is a build-time choice (GR-004).
 Usage
 -----
  python scripts/validation/min_face_size.py \
      --images images \
      --gallery gallery_lvface.h5 \
      --arcface models/LVFace-B_Glint360K.onnx \
      --actors 100 --seed 0 \
      --out experiments/results/vr005_min_face_size
 Writes <out>.csv, <out>.json and <out>.png (plus <out>.per_probe.csv with
 --per-probe).
 """
 from __future__ import annotations
 import argparse
 import csv
 import json
 import random
 import re
 import sys
 import time
 from pathlib import Path
 REPO = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(REPO / "scripts"))
 def _find_sae_embed() -> Path | None:
    """Locate the built sae_embed module.
    A git worktree has no build tree of its own, so fall back to the main
    checkout via the shared git dir — otherwise running this study from a
    feature worktree cannot find the bindings it now depends on.
    """
    roots = [REPO]
    try:
        import subprocess
        common = subprocess.run(["git", "-C", str(REPO), "rev-parse",
                                 "--path-format=absolute", "--git-common-dir"],
                                capture_output=True, text=True, check=True).stdout.strip()
        if common:
            roots.append(Path(common).parent)
    except Exception:
        pass
    for root in roots:
        for b in ("build-ort", "build"):
            if list((root / b).glob("sae_embed*.so")):
                return root / b
    return None
 _SAE_BUILD = _find_sae_embed()
 if _SAE_BUILD is None:
    sys.exit("cannot find the built sae_embed module — build it with\n"
             "  cmake --build build-ort --target sae_embed")
 sys.path.insert(0, str(_SAE_BUILD))
 # Before cv2: OpenCV's DNN module loads the system libonnxruntime, which then
 # shadows the one sae_embed links against and the import fails on a missing
 # symbol version. Order matters here.
 import sae_embed
 import cv2
 import numpy as np
 IMAGE_EXTS = (".jpg", ".jpeg", ".png", ".webp")
 JELLYFIN_ID_RE = re.compile(r"^[0-9a-f]{32}$")
 # Interpolation used for the two halves of the degradation. Downscaling uses
 # INTER_AREA (correct low-pass for shrinking, i.e. detail that a small detection
 # genuinely never had); upscaling uses INTER_LINEAR, which is what warpAffine in
 # align_face() uses when it blows a small detection up to 112x112.
 INTERP = {
    "area":    cv2.INTER_AREA,
    "linear":  cv2.INTER_LINEAR,
    "cubic":   cv2.INTER_CUBIC,
    "nearest": cv2.INTER_NEAREST,
    "lanczos": cv2.INTER_LANCZOS4,
 }
 # House chart palette, shared with scripts/docs/experiment_charts.py so figures
 # across the report read as one set.
 INK, MUTED, GRID, SURFACE = "#0b0b0b", "#898781", "#e1e0d9", "#fcfcfb"
 BLUE, GREEN, RED, AMBER = "#2a78d6", "#008300", "#e34948", "#eda100"
 # ── Production stages, via the sae_embed bindings ─────────────────────────────
 # detect / align_face / embed_crops / calibrate_gallery all call the shipped C++.
 # There is deliberately no Python re-implementation of any of them: a second copy
 # drifts from what ships, and the calibration is the one that must not — AR-024
 # requires every similarity to pass through the same sigmoid the matcher uses.
 # These two mirror constants in gallery_calibration.hpp. They are NOT a second
 # copy of the fit — that is the binding's job — but the script reproduces the
 # same dedup and eligibility filtering so the actor counts it reports describe
 # the population the C++ actually fitted on. Keep them in step with the header.
 MIN_EMB_FOR_POSITIVE = 5
 DEDUP_SIM = 1.0 - 1e-7
 class Stages:
    """Thin holder so the rest of the script has one object to call."""
    def __init__(self, detector: str, arcface: str, conf: float, nms: float):
        self.engine = sae_embed.FaceEmbedder(
            detector_model=detector, arcface_model=arcface,
            conf=conf, nms=nms, max_side=0)
    def detect(self, img):
        return self.engine.detect(img)
    def align(self, img, landmarks):
        return sae_embed.align_face(img, np.asarray(landmarks, dtype=np.float32).reshape(5, 2))
    def enhance(self, img):
        return sae_embed.enhance_for_retry(img)
    def embed(self, crops):
        """(N,112,112,3) uint8 BGR -> (N,512) float32.
        Chunked at the backend's max_batch: the engine does not split an
        oversized request, so handing it a whole gallery at once asks CUDA for
        a multi-gigabyte activation buffer and the allocator refuses.
        """
        if not len(crops):
            return np.zeros((0, 512), dtype=np.float32)
        n = max(1, int(self.engine.max_batch))
        arr = np.ascontiguousarray(np.stack(crops), dtype=np.uint8)
        out = [np.asarray(self.engine.embed_crops(np.ascontiguousarray(arr[i:i + n])))
               for i in range(0, len(arr), n)]
        return np.concatenate(out, axis=0)
 def calibrate_gallery(emb: np.ndarray, actor: np.ndarray) -> dict:
    """The production Platt fit (gallery_calibration.hpp), via the binding."""
    cal = sae_embed.calibrate_gallery(
        np.ascontiguousarray(emb, dtype=np.float32), [int(a) for a in actor])
    print(f"[calibration] a={cal.a:.4f} b={cal.b:.4f} valid={cal.valid} "
          f"boundary(P=0.5)=sim{cal.boundary_at(0.5):.4f}", file=sys.stderr)
    # Held module-side rather than returned: the returned dict lands in the run
    # metadata, and a native object there breaks the JSON dump.
    _CAL["cal"] = cal
    return {"a": float(cal.a), "b": float(cal.b), "valid": bool(cal.valid)}
 def probability(sim, a: float, b: float, log_prior_odds: float = 0.0):
    """P(match) through GalleryCalibration — the C++ sigmoid, not a copy of it."""
    cal = _CAL.get("cal")
    if cal is None:
        raise RuntimeError("probability() called before calibrate_gallery()")
    sim = np.asarray(sim, dtype=np.float64)
    flat = np.atleast_1d(sim).ravel()
    out = np.array([cal.probability(float(v), log_prior_odds) for v in flat])
    return out.reshape(sim.shape) if sim.shape else float(out[0])
 _CAL: dict = {}
 # ── Runtime / actor discovery ─────────────────────────────────────────────────
 def normalise_name(name: str) -> str:
    return re.sub(r"[^a-z0-9]+", "", name.lower())
 def discover_actors(images_root: Path) -> list[dict]:
    """Enumerate the gallery-build image cache: <root>/<jellyfin_id>_<Name>/NN.jpg
    (the layout make_jellyfin_gallery.py / reembed_gallery.py use)."""
    actors = []
    for d in sorted(p for p in images_root.iterdir() if p.is_dir()):
        imgs = sorted(p for p in d.iterdir()
                      if p.is_file() and p.suffix.lower() in IMAGE_EXTS)
        if not imgs:
            continue
        head, _, tail = d.name.partition("_")
        if JELLYFIN_ID_RE.match(head) and tail:
            jellyfin_id, name = head, tail.replace("_", " ")
        else:
            jellyfin_id, name = "", d.name.replace("_", " ")
        actors.append({"dir": d, "jellyfin_id": jellyfin_id, "name": name,
                       "images": imgs})
    return actors
 def gallery_keys(gallery_path: Path) -> tuple[set[str], set[str]]:
    """(jellyfin ids, normalised names) of the actors an existing gallery holds."""
    from sae_gallery import load_gallery_hdf5
    g = load_gallery_hdf5(gallery_path)
    ids = {a.get("jellyfin_id", "") for a in g["actors"] if a.get("jellyfin_id")}
    names = {normalise_name(a.get("name", "")) for a in g["actors"] if a.get("name")}
    return ids, names
 # ── Degradation ───────────────────────────────────────────────────────────────
 def degrade(crop: np.ndarray, size: int, down: int, up: int) -> np.ndarray:
    """Throw away everything a face detected at size x size never had, then warp
    it back up to the 112x112 the embedder is fed."""
    if size == 112:
        return crop
    small = cv2.resize(crop, (size, size), interpolation=down)
    return cv2.resize(small, (112, 112), interpolation=up)
 # ── Reporting ─────────────────────────────────────────────────────────────────
 CAVEAT = (
    "CAVEAT: FPI grows with gallery size. This ran against {n_actors} actors, so it "
    "UNDERSTATES the false-positive rate of a production library of thousands. Read "
    "FPI as relative across sizes, not as an absolute rate."
 )
 def write_plot(rows: list[dict], out_png: Path, meta: dict) -> None:
    import matplotlib
    matplotlib.use("Agg")
    import matplotlib.pyplot as plt
    plt.rcParams.update({
        "figure.facecolor": SURFACE, "axes.facecolor": SURFACE,
        "savefig.facecolor": SURFACE, "text.color": INK,
        "axes.edgecolor": MUTED, "axes.labelcolor": INK,
        "xtick.color": MUTED, "ytick.color": MUTED,
        "axes.grid": True, "grid.color": GRID, "grid.linewidth": 0.8,
        "axes.spines.top": False, "axes.spines.right": False,
    })
    sizes = [r["size_px"] for r in rows]
    fig, ax = plt.subplots(figsize=(9, 5.6))
    ax.plot(sizes, [100 * r["tpi_rate"] for r in rows], "-o", color=GREEN,
            lw=2, label="TPI — identified, correct actor")
    ax.plot(sizes, [100 * r["fpi_rate"] for r in rows], "-s", color=RED,
            lw=2, label="FPI — identified, wrong actor")
    ax.plot(sizes, [100 * r["unidentified_rate"] for r in rows], color=MUTED,
            marker="^", lw=1.4, ls="--", label="unidentified (below P threshold)")
    ax.plot(sizes, [100 * r["rank1_rate"] for r in rows], ":", color=BLUE,
            lw=1.6, label="rank-1 correct (ignoring threshold)")
    op = meta.get("operating_point")
    if op:
        ax.axvline(op, color=AMBER, lw=1.6, ls="-.", zorder=1)
        ax.annotate(f"operating point {op} px", xy=(op, 50),
                    xytext=(4, 0), textcoords="offset points",
                    color=AMBER, fontsize=9, rotation=90, va="center")
    ax.set_xlabel("probe face size before upscaling (px)")
    ax.set_ylabel("% of probes")
    ax.set_ylim(-2, 102)
    ax.set_xticks(sizes)
    ax.set_title(f"VR-005 — identification vs. probe face size\n"
                 f"{meta['model']}, {meta['n_actors']} actors, "
                 f"{meta['n_probes']} probes/size, gallery at native resolution",
                 fontsize=11, loc="left")
    ax.legend(frameon=False, fontsize=9, loc="center left")
    fig.text(0.01, 0.005, CAVEAT.format(n_actors=meta["n_actors"]),
             fontsize=7.5, color=MUTED, wrap=True)
    fig.tight_layout(rect=(0, 0.05, 1, 1))
    out_png.parent.mkdir(parents=True, exist_ok=True)
    fig.savefig(out_png, dpi=150)
    plt.close(fig)
 def pick_operating_point(rows: list[dict], retention: float, fpi_slack: float) -> int | None:
    """Smallest size that keeps `retention` of the undegraded (112 px control)
    TPI rate and does not add more than `fpi_slack` absolute FPI over it.
    A stated rule, not a magic number — change the rule, not the answer."""
    control = next((r for r in rows if r["size_px"] == 112), None)
    if control is None or control["n_probes"] == 0:
        return None
    tpi_floor = retention * control["tpi_rate"]
    fpi_ceil = control["fpi_rate"] + fpi_slack
    ok = [r["size_px"] for r in rows
          if r["tpi_rate"] >= tpi_floor and r["fpi_rate"] <= fpi_ceil]
    return min(ok) if ok else None
 # ── Main ──────────────────────────────────────────────────────────────────────
 def main() -> int:
    p = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--images", required=True,
                   help="gallery image cache root (<jellyfin_id>_<Name>/NN.jpg)")
    p.add_argument("--gallery", default=None,
                   help="gallery .h5 — restricts the actor pool to its members")
    p.add_argument("--out", default=str(REPO / "experiments/results/vr005_min_face_size"),
                   help="output path prefix (.csv/.json/.png are appended)")
    p.add_argument("--per-probe", action="store_true",
                   help="also write <out>.per_probe.csv, one row per probe per size")
    p.add_argument("--actors", type=int, default=100, help="actors to sample (default 100)")
    p.add_argument("--min-images", type=int, default=2,
                   help="minimum mugshots for an actor to be eligible (default 2)")
    p.add_argument("--probes-per-actor", type=int, default=1,
                   help="images held out per actor; 1 is the VR-005 protocol")
    p.add_argument("--seed", type=int, default=0, help="actor/probe selection seed")
    p.add_argument("--keep-duplicates", action="store_true",
                   help="keep mugshots that are the same photograph twice; by "
                        "default they are dropped, since a probe identical to a "
                        "gallery reference is identified for free at every size")
    p.add_argument("--sizes", default="12,16,20,24,32,40,48,56,64,72,80,96,112",
                   help="comma-separated probe sizes; 112 is the undegraded control")
    p.add_argument("--models-dir", default=str(REPO / "models"))
    p.add_argument("--arcface", default=None,
                   help="embedder ONNX (default <models-dir>/LVFace-B_Glint360K.onnx)")
    p.add_argument("--detector", default=None,
                   help="SCRFD ONNX (default <models-dir>/scrfd_500m_bnkps.onnx)")
    p.add_argument("--conf", type=float, default=0.5, help="detector confidence")
    p.add_argument("--nms", type=float, default=0.4, help="detector NMS IoU")
    p.add_argument("--max-side", type=int, default=500,
                   help="downscale mugshots to this longest side before detection, "
                        "matching the gallery builders' embedder settings")
    p.add_argument("--prob-threshold", type=float, default=0.754,
                   help="accept if P(match) exceeds this (Config::prob_threshold)")
    p.add_argument("--match-prior", type=float, default=0.5,
                   help="base-rate prior (Config::match_prior)")
    p.add_argument("--calib-a", type=float, default=None,
                   help="override the fitted sigmoid scale instead of fitting")
    p.add_argument("--calib-b", type=float, default=None,
                   help="override the fitted sigmoid bias instead of fitting")
    p.add_argument("--down-interp", default="area", choices=sorted(INTERP),
                   help="interpolation for the 112 -> S downscale (default area)")
    p.add_argument("--up-interp", default="linear", choices=sorted(INTERP),
                   help="interpolation for the S -> 112 upscale (default linear, "
                        "as warpAffine uses in align_face)")
    p.add_argument("--tpi-retention", type=float, default=0.95,
                   help="operating point keeps this fraction of the control TPI rate")
    p.add_argument("--fpi-slack", type=float, default=0.01,
                   help="operating point may add at most this absolute FPI over control")
    p.add_argument("--verify-against", default=None,
                   help="gallery .h5 built from --images with the same model: report "
                        "agreement and separation of recomputed vs stored embeddings "
                        "(a TensorRT-built gallery will not agree; see the docstring)")
    args = p.parse_args()
    if (args.calib_a is None) != (args.calib_b is None):
        return err("--calib-a and --calib-b must be given together")
    models_dir = Path(args.models_dir)
    arcface = Path(args.arcface) if args.arcface else models_dir / "LVFace-B_Glint360K.onnx"
    detector = Path(args.detector) if args.detector else models_dir / "scrfd_500m_bnkps.onnx"
    for path, what in ((arcface, "embedder"), (detector, "detector")):
        if not path.is_file():
            return err(f"{what} model not found: {path}\n"
                       f"Run: bash scripts/download_models.sh")
    images_root = Path(args.images)
    if not images_root.is_dir():
        return err(f"image cache not found: {images_root}")
    sizes = sorted({int(s) for s in args.sizes.split(",") if s.strip()})
    if not sizes:
        return err("--sizes is empty")
    if args.probes_per_actor < 1:
        return err("--probes-per-actor must be >= 1")
    cv2.setRNGSeed(args.seed)  # estimateAffinePartial2D's RANSAC draws from this
    # ── actor pool ────────────────────────────────────────────────────────────
    pool = discover_actors(images_root)
    print(f"[select] {len(pool)} actor dirs with images under {images_root}",
          file=sys.stderr)
    if args.gallery:
        ids, names = gallery_keys(Path(args.gallery))
        pool = [a for a in pool
                if (a["jellyfin_id"] and a["jellyfin_id"] in ids)
                or normalise_name(a["name"]) in names]
        print(f"[select] {len(pool)} of them are in {args.gallery}", file=sys.stderr)
    need = max(args.min_images, args.probes_per_actor + 1)
    eligible = [a for a in pool if len(a["images"]) >= need]
    print(f"[select] {len(eligible)} have >= {need} mugshots", file=sys.stderr)
    if len(eligible) < 2:
        return err(f"need at least 2 actors with >= {need} mugshots; found "
                   f"{len(eligible)}. Build the image cache first "
                   f"(scripts/make_jellyfin_gallery.py) or lower --min-images.")
    rng = random.Random(args.seed)
    selected = sorted(rng.sample(eligible, min(args.actors, len(eligible))),
                      key=lambda a: a["dir"].name)
    if len(selected) < args.actors:
        print(f"[select] WARNING: only {len(selected)} eligible actors, "
              f"--actors {args.actors} requested. FPI is gallery-size dependent — "
              f"see the caveat.", file=sys.stderr)
    # ── detect + align every mugshot of the selected actors, once ─────────────
    stages = Stages(str(detector), str(arcface), args.conf, args.nms)
    print(f"[models] detector={detector.name} embedder={arcface.name} "
          f"batch={stages.engine.max_batch} (provider chosen by the C++ backend: "
          f"CUDA, then ROCm, then CPU)", file=sys.stderr)
    t0 = time.time()
    crops: list[np.ndarray] = []
    rows: list[dict] = []          # parallel to crops: {actor, actor_idx, image}
    actors: list[dict] = []
    n_nodetect = 0
    for a in selected:
        actor_crops, actor_paths = [], []
        for img_path in a["images"]:
            img = cv2.imread(str(img_path))
            if img is None:
                n_nodetect += 1
                continue
            if args.max_side > 0 and max(img.shape[:2]) > args.max_side:
                s = args.max_side / max(img.shape[:2])
                img = cv2.resize(img, None, fx=s, fy=s, interpolation=cv2.INTER_AREA)
            faces = stages.detect(img)
            if not faces:
                enhanced = stages.enhance(img)
                faces = stages.detect(enhanced)
                if faces:
                    img = enhanced
            if not faces:
                n_nodetect += 1
                continue
            best = max(faces, key=lambda f: f.confidence)
            crop = stages.align(img, best.landmarks)
            if crop is None:
                n_nodetect += 1
                continue
            actor_crops.append(crop)
            actor_paths.append(img_path)
        if len(actor_crops) < args.probes_per_actor + 1:
            continue
        ai = len(actors)
        actors.append({"name": a["name"], "jellyfin_id": a["jellyfin_id"],
                       "dir": a["dir"].name, "n_images": len(actor_crops)})
        for crop, img_path in zip(actor_crops, actor_paths):
            rows.append({"actor_idx": ai, "image": str(img_path)})
            crops.append(crop)
        if len(actors) % 20 == 0:
            print(f"  [align] {len(actors)}/{len(selected)} actors, "
                  f"{len(crops)} crops", file=sys.stderr)
    if len(actors) < 2:
        return err(f"only {len(actors)} actors survived detection/alignment — "
                   f"nothing to match against")
    print(f"[align] {len(actors)} actors, {len(crops)} aligned crops, "
          f"{n_nodetect} images skipped (no face / unreadable) in "
          f"{time.time() - t0:.1f}s", file=sys.stderr)
    actor_of = np.array([r["actor_idx"] for r in rows], dtype=int)
    # ── embed everything at native resolution ────────────────────────────────
    t0 = time.time()
    native = stages.embed(crops)
    print(f"[embed] {len(crops)} native crops in {time.time() - t0:.1f}s",
          file=sys.stderr)
    if args.verify_against:
        verify_embeddings(Path(args.verify_against), rows, native, actor_of)
    # ── drop duplicate mugshots ───────────────────────────────────────────────
    # The cache holds the same photograph twice for some actors (two provider
    # URLs, one picture). A probe that is identical to a gallery reference is
    # identified for free at every size, which flatters the whole curve, so
    # remove duplicates the same way calibrate_gallery does.
    n_dup = 0
    if not args.keep_duplicates:
        keep = np.ones(len(rows), bool)
        for ai in range(len(actors)):
            kept: list[int] = []
            for i in np.nonzero(actor_of == ai)[0]:
                if any(float(native[i] @ native[k]) > DEDUP_SIM for k in kept):
                    keep[i] = False
                else:
                    kept.append(int(i))
        n_dup = int((~keep).sum())
        # An actor left with too few distinct mugshots to hold one out drops out.
        counts = np.bincount(actor_of[keep], minlength=len(actors))
        drop_actor = counts < args.probes_per_actor + 1
        keep &= ~drop_actor[actor_of]
        remap = np.full(len(actors), -1, dtype=int)
        remap[~drop_actor] = np.arange(int((~drop_actor).sum()))
        actors = [a for a, d in zip(actors, drop_actor) if not d]
        rows = [r for r, k in zip(rows, keep) if k]
        crops = [c for c, k in zip(crops, keep) if k]
        native = native[keep]
        actor_of = remap[actor_of[keep]]
        for r, ai in zip(rows, actor_of):
            r["actor_idx"] = int(ai)
        for ai, a in enumerate(actors):
            a["n_images"] = int(np.sum(actor_of == ai))
        print(f"[dedup] dropped {n_dup} duplicate mugshots and "
              f"{int(drop_actor.sum())} actors left with too few; "
              f"{len(actors)} actors, {len(rows)} images remain", file=sys.stderr)
        if len(actors) < 2:
            return err("fewer than 2 actors survive de-duplication — the image "
                       "cache holds too few distinct mugshots")
    # ── hold out the probes ───────────────────────────────────────────────────
    is_probe = np.zeros(len(rows), bool)
    for ai in range(len(actors)):
        idx = np.nonzero(actor_of == ai)[0]
        # Seeded per actor so the choice does not depend on iteration order.
        r = random.Random(f"{args.seed}:{actors[ai]['dir']}")
        for pick in r.sample(list(idx), args.probes_per_actor):
            is_probe[pick] = True
    probe_rows = np.nonzero(is_probe)[0]
    gal_rows = np.nonzero(~is_probe)[0]
    print(f"[holdout] {len(probe_rows)} probes held out, "
          f"{len(gal_rows)} gallery embeddings remain", file=sys.stderr)
    gal_emb = native[gal_rows]
    gal_actor = actor_of[gal_rows]
    probe_actor = actor_of[probe_rows]
    # Per-actor column masks for the best-of-N scan (identity_matcher_node).
    actor_cols = [np.nonzero(gal_actor == ai)[0] for ai in range(len(actors))]
    have_refs = np.array([len(c) > 0 for c in actor_cols])
    if not have_refs.all():
        return err("an actor ended up with no gallery references left; "
                   "raise --min-images")
    # ── calibration ───────────────────────────────────────────────────────────
    if args.calib_a is not None:
        cal = {"a": args.calib_a, "b": args.calib_b, "valid": True}
        print(f"[calibration] using supplied a={cal['a']} b={cal['b']}", file=sys.stderr)
    else:
        cal = calibrate_gallery(gal_emb, gal_actor)
    if not cal["valid"]:
        return err(
            "calibration could not be fitted, and this study will not fall back to a "
            "raw cosine threshold (CLAUDE.md invariant). Use more actors with >= "
            f"{MIN_EMB_FOR_POSITIVE} mugshots, or pass --calib-a/--calib-b from a "
            "production gallery.")
    log_prior_odds = float(np.log(args.match_prior / (1.0 - args.match_prior)))
    # ── sweep ─────────────────────────────────────────────────────────────────
    down, up = INTERP[args.down_interp], INTERP[args.up_interp]
    probe_crops = [crops[i] for i in probe_rows]
    results, per_probe = [], []
    for size in sizes:
        t0 = time.time()
        degraded = [degrade(c, size, down, up) for c in probe_crops]
        q = stages.embed(degraded)
        sims = q @ gal_emb.T                                   # [n_probe, n_gal]
        best_per_actor = np.stack([sims[:, cols].max(axis=1) for cols in actor_cols],
                                  axis=1)                       # [n_probe, n_actor]
        best_actor = best_per_actor.argmax(axis=1)
        best_sim = best_per_actor.max(axis=1)
        p_match = np.asarray(probability(best_sim, cal["a"], cal["b"], log_prior_odds))
        accept = p_match > args.prob_threshold
        correct = best_actor == probe_actor
        tpi = int(np.sum(accept & correct))
        fpi = int(np.sum(accept & ~correct))
        unid = int(np.sum(~accept))
        n = len(probe_rows)
        results.append({
            "size_px": size,
            "n_probes": n,
            "tpi": tpi, "fpi": fpi, "unidentified": unid,
            "tpi_rate": tpi / n, "fpi_rate": fpi / n, "unidentified_rate": unid / n,
            "rank1_rate": float(np.mean(correct)),
            "mean_best_sim": float(np.mean(best_sim)),
            "mean_p_match": float(np.mean(p_match)),
            "mean_sim_true_actor": float(np.mean(
                best_per_actor[np.arange(n), probe_actor])),
        })
        if args.per_probe:
            for j in range(n):
                per_probe.append({
                    "size_px": size,
                    "probe_image": rows[probe_rows[j]]["image"],
                    "true_actor": actors[probe_actor[j]]["name"],
                    "matched_actor": actors[best_actor[j]]["name"],
                    "best_sim": float(best_sim[j]),
                    "p_match": float(p_match[j]),
                    "outcome": ("TPI" if accept[j] and correct[j]
                                else "FPI" if accept[j] else "unidentified"),
                })
        print(f"[sweep] {size:3d}px  TPI {tpi:4d} ({100 * tpi / n:5.1f}%)  "
              f"FPI {fpi:4d} ({100 * fpi / n:5.1f}%)  "
              f"unid {unid:4d} ({100 * unid / n:5.1f}%)  "
              f"rank1 {100 * np.mean(correct):5.1f}%  "
              f"[{time.time() - t0:.1f}s]", file=sys.stderr)
    op = pick_operating_point(results, args.tpi_retention, args.fpi_slack)
    # ── outputs ───────────────────────────────────────────────────────────────
    out = Path(args.out)
    out.parent.mkdir(parents=True, exist_ok=True)
    # Append rather than with_suffix() so a prefix containing a dot keeps its name.
    csv_path = out.with_name(out.name + ".csv")
    json_path = out.with_name(out.name + ".json")
    png_path = out.with_name(out.name + ".png")
    fields = list(results[0].keys())
    with open(csv_path, "w", newline="") as f:
        w = csv.DictWriter(f, fieldnames=fields)
        w.writeheader()
        w.writerows(results)
    meta = {
        "requirement": "VR-005",
        "caveat": CAVEAT.format(n_actors=len(actors)),
        "model": arcface.stem,
        "detector": detector.stem,
        "backend": "sae_embed / the compiled-in inference backend (fp32 ONNX under "
                   "SAE_INFERENCE_BACKEND=ORT; a TensorRT fp16 build is a different "
                   "embedding space)",
        "n_actors": len(actors),
        "n_probes": len(probe_rows),
        "n_gallery_embeddings": len(gal_rows),
        "probes_per_actor": args.probes_per_actor,
        "seed": args.seed,
        "sizes": sizes,
        "prob_threshold": args.prob_threshold,
        "match_prior": args.match_prior,
        "calibration": cal,
        "calibration_source": "supplied" if args.calib_a is not None else "fitted",
        "sim_boundary_at_threshold": float(
            (np.log(args.prob_threshold / (1 - args.prob_threshold))
             - cal["b"] - log_prior_odds) / cal["a"]),
        "down_interp": args.down_interp,
        "up_interp": args.up_interp,
        "max_side": args.max_side,
        "duplicate_mugshots_dropped": n_dup,
        "operating_point_rule": (
            f"smallest size retaining >= {args.tpi_retention:.0%} of the 112 px "
            f"control TPI rate with <= +{args.fpi_slack:.1%} absolute FPI"),
        "operating_point": op,
        "images_skipped_no_face": n_nodetect,
        "curve": results,
        "actors": actors,
    }
    json_path.write_text(json.dumps(meta, indent=2) + "\n")
    if per_probe:
        pp = out.with_name(out.name + ".per_probe.csv")
        with open(pp, "w", newline="") as f:
            w = csv.DictWriter(f, fieldnames=list(per_probe[0].keys()))
            w.writeheader()
            w.writerows(per_probe)
        print(f"[out] {pp}", file=sys.stderr)
    write_plot(results, png_path, meta)
    # ── stdout report ─────────────────────────────────────────────────────────
    print(f"\nVR-005 — minimum face size, {arcface.stem}")
    print(f"{len(actors)} actors, {len(probe_rows)} probes/size, "
          f"{len(gal_rows)} gallery embeddings at native resolution")
    print(f"identify when P>{args.prob_threshold}, i.e. cosine above "
          f"{meta['sim_boundary_at_threshold']:.4f} under the calibration fitted "
          f"on this gallery\n")
    print(f"{'size':>5} {'TPI':>8} {'FPI':>8} {'unid':>8} {'rank1':>8} {'mean sim':>9}")
    for r in results:
        print(f"{r['size_px']:>5} {100 * r['tpi_rate']:>7.1f}% "
              f"{100 * r['fpi_rate']:>7.1f}% {100 * r['unidentified_rate']:>7.1f}% "
              f"{100 * r['rank1_rate']:>7.1f}% {r['mean_best_sim']:>9.4f}")
    print(f"\noperating point: {op if op else 'none of the swept sizes qualifies'}"
          f"   ({meta['operating_point_rule']})")
    print(f"\n{meta['caveat']}")
    print(f"\n[out] {csv_path}\n[out] {json_path}\n[out] {png_path}")
    return 0
 def _separation(emb: np.ndarray, actor: np.ndarray) -> tuple[float, float, float]:
    """(mean same-actor sim, mean different-actor sim, d') — the property that has
    to survive for an embedding space to be usable, whatever its coordinates."""
    iu, ju = np.triu_indices(len(actor), k=1)
    sims = (emb @ emb.T)[iu, ju]
    same = actor[iu] == actor[ju]
    pos = sims[same & (sims < 0.9999)]   # drop duplicate source images
    neg = sims[~same]
    if pos.size < 2 or neg.size < 2:
        return float("nan"), float("nan"), float("nan")
    d = (pos.mean() - neg.mean()) / np.sqrt(0.5 * (pos.var() + neg.var()))
    return float(pos.mean()), float(neg.mean()), float(d)
 def verify_embeddings(gallery_path: Path, rows: list[dict], native: np.ndarray,
                      actor_of: np.ndarray) -> None:
    """Cross-check this script's ONNX port against a gallery built by the C++
    pipeline from the same mugshots.
    Agreement is ~1.0 only if that gallery was built with the same backend. A
    TensorRT fp16 build lands around 0.85 on LVFace-B while separating just as
    well, so the separation figures — not the agreement — are what says whether
    the port is sound."""
    from sae_gallery import load_gallery_hdf5
    g = load_gallery_hdf5(gallery_path)
    stored: dict[tuple[str, str], np.ndarray] = {}
    for a in g["actors"]:
        key = a.get("jellyfin_id") or normalise_name(a.get("name", ""))
        for e, src in zip(a.get("embeddings", []), a.get("source_images", [])):
            if src:
                stored[(key, src)] = np.asarray(e, np.float32)
    sims, paired_mine, paired_ref, paired_actor = [], [], [], []
    for i, r in enumerate(rows):
        path = Path(r["image"])
        head, _, _ = path.parent.name.partition("_")
        key = head if JELLYFIN_ID_RE.match(head) else normalise_name(
            path.parent.name.replace("_", " "))
        ref = stored.get((key, path.name))
        if ref is None or ref.shape != native[i].shape:
            continue
        ref = ref / max(float(np.linalg.norm(ref)), 1e-6)
        sims.append(float(native[i] @ ref))
        paired_mine.append(native[i])
        paired_ref.append(ref)
        paired_actor.append(actor_of[i])
    if not sims:
        print(f"[verify] no overlap with {gallery_path} — nothing checked",
              file=sys.stderr)
        return
    sims_arr = np.asarray(sims)
    print(f"[verify] {len(sims)} embeddings vs {gallery_path.name}: "
          f"mean cos={sims_arr.mean():.4f}  min={sims_arr.min():.4f}",
          file=sys.stderr)
    act = np.asarray(paired_actor)
    for label, mat in (("this script", np.asarray(paired_mine)),
                       ("stored gallery", np.asarray(paired_ref))):
        pos, neg, d = _separation(mat, act)
        print(f"[verify]   {label:>14s}: same-actor {pos:.3f}  "
              f"different-actor {neg:.3f}  d'={d:.2f}", file=sys.stderr)
    if sims_arr.mean() < 0.99:
        print("[verify]   embeddings differ from the stored gallery. If d' is "
              "comparable this is a backend difference (e.g. a TensorRT fp16 "
              "build), not a broken port; the study is self-consistent either "
              "way. If d' collapsed, the port is wrong.", file=sys.stderr)
 def err(msg: str) -> int:
    print(f"error: {msg}", file=sys.stderr)
    return 2
 if __name__ == "__main__":
    sys.exit(main())
@@ -61,15 +61,7 @@ class Prediction:
            keys = keys_for(imdb_id=a.get("imdb_id"), tmdb_id=a.get("tmdb_id"),
                            jellyfin_id=a.get("jellyfin_id"), name=a.get("name"),
                            crosswalk=crosswalk)
-            # schema_version 1: scenes is [[t0, t1], ...]  (list of pairs)
+            windows = [(float(t0), float(t1)) for t0, t1 in a.get("scenes", [])]
            # schema_version 2: scenes is [{"start":…, "end":…, "belief":…, …}, …]
            windows = []
            for s in a.get("scenes", []):
                if isinstance(s, dict):
                    windows.append((float(s["start"]), float(s["end"])))
                else:
                    t0, t1 = s[0], s[1]
                    windows.append((float(t0), float(t1)))
            for _, t1 in windows:
                self._max_t = max(self._max_t, t1)
            self.actors.append({"keys": keys, "windows": windows})
@@ -1,370 +0,0 @@
 #!/usr/bin/env python3
 """
 VR-014 — the v1 audio signature recovers a known trim offset on real audio.
 TRACES: UT-105, UT-106, UT-107, UT-108 | VR-014 | IR-004
    python scripts/validation/test_audio_offset.py [build_dir]
 The golden vector (IR-005) proves the *arithmetic* is identical in both
 producers. It cannot prove the thing the signature exists for: that when the
 same cut arrives trimmed differently, sliding one signature against the other
 finds the true alignment and only the true alignment. Its fixture is a synthetic
 tone sweep, which is pathologically easy to align; film dialogue and score are
 not, and that is what this measures.
 The signature is computed by the **shipped C++**, through the `sae_audio`
 nanobind module — never a numpy port. A third implementation of a fingerprint
 whose whole value rests on three implementations agreeing byte for byte would be
 the one nobody checks against the golden vector.
 The slide *is* written here in numpy, deliberately: matching is the consumer's
 algorithm (server SPEC.md section 3), owned by the server and the jRay plugin,
 not by this repo. Writing it out is what makes this a test of the signature
 rather than a test of somebody's matcher.
 Two independent offset mechanisms are checked, because they can fail
 separately:
  * a **window offset** (UT-105) — two 120 s excerpts taken from different
    points, which is the alignment search itself; and
  * a **head trim** (UT-106) — a real file with delta seconds removed from the
    front, which additionally exercises the runtime/2 anchor: the window follows
    the midpoint, so cutting delta from the head moves it by delta/2, not delta.
    That factor of two is the easiest thing in the whole feature to get wrong
    and nothing else checks it.
 """
 import base64
 import random
 import shutil
 import subprocess
 import sys
 import tempfile
 from pathlib import Path
 import numpy as np
 REPO = Path(__file__).resolve().parent.parent.parent
 BUILD = Path(sys.argv[1]) if len(sys.argv) > 1 else REPO / "build"
 sys.path.insert(0, str(BUILD))
 import sae_audio  # noqa: E402
 FIXTURE = REPO / "tests" / "fixtures" / "audio" / "superhero_offset_200s.flac"
 TONE = REPO / "tests" / "fixtures" / "audio" / "jray_audio_v1_tone.flac"
 # Server SPEC.md section 3, "Matching and offset recovery". The cap is the
 # spec's, not a convenience: +/-600 frames is ~56 s, which covers realistic trim
 # differences, and an offset outside it must be declined rather than guessed at.
 SEARCH_CAP_FRAMES = 600
 AUDIO_TIER = 0.85
 LOOSE_TIER = 0.60
 TRIALS = 40
 SEED = 20250731
 HOP_SEC = sae_audio.hop_size / sae_audio.sample_rate
 # What the offset is actually *for*: shifting scene windows, which are seconds
 # long. Half a second of error is invisible against them, and that budget is
 # what makes the numbers below readable — an offset is quantised to whole
 # frames, so no correct answer can be worse than half a frame (46 ms) and the
 # feature has an order of magnitude in hand before anything is at stake.
 OFFSET_BUDGET_SEC = 0.5
 def peak_bins(signature):
    """The per-frame peak band index, which is what the slide compares.
    The `v1:` prefix is checked against the constant the C++ exports rather
    than a literal, so a producer bump cannot be silently parsed as v1 here
    (IR-008).
    """
    prefix = sae_audio.version_prefix
    if not signature.startswith(prefix):
        raise AssertionError(f"signature is not {prefix!r}: {signature[:8]!r}")
    packed = np.frombuffer(base64.b64decode(signature[len(prefix):]), dtype=np.uint8)
    if np.any(packed & 0x80):
        raise AssertionError("reserved bit set — not a structurally valid signature")
    return packed >> 2
 def best_match(reference, query, cap=SEARCH_CAP_FRAMES, slack=0):
    """Slide `query` against `reference`; return (score, offset_frames).
    `offset` is how many frames later the query's window begins, so
    ``query[i]`` lines up with ``reference[i + offset]``. Score is the fraction
    of overlapping frames whose peak bin agrees, exactly as the spec defines it.
    `slack` widens what counts as agreement to a frame within +/-slack, which is
    not the spec's rule — it is the candidate remedy UT-108 measures. It changes
    the *score* only; the offset it reports is still a whole-frame alignment.
    """
    best_score, best_offset = -1.0, 0
    for offset in range(-cap, cap + 1):
        if offset >= 0:
            a, b = reference[offset:], query[: len(query) - offset]
        else:
            a, b = reference[: len(reference) + offset], query[-offset:]
        n = min(len(a), len(b))
        if n < 100:            # too little overlap to mean anything
            continue
        a, b = a[:n], b[:n]
        if slack == 0:
            agree = a == b
        else:
            agree = np.zeros(n, dtype=bool)
            for shift in range(-slack, slack + 1):
                shifted = np.roll(a, shift)
                # 255 is not a band index, so the wrapped end can never agree.
                if shift > 0:
                    shifted[:shift] = 255
                elif shift < 0:
                    shifted[shift:] = 255
                agree |= shifted == b
        score = float(np.mean(agree))
        if score > best_score:
            best_score, best_offset = score, offset
    return best_score, best_offset
 def decode_mono(path):
    """The whole fixture as float32 mono at 11025 Hz — the signature's own rate."""
    raw = subprocess.run(
        ["ffmpeg", "-nostdin", "-v", "error", "-i", str(path),
         "-ac", "1", "-ar", str(sae_audio.sample_rate), "-f", "f32le", "-"],
        capture_output=True, check=True).stdout
    return np.frombuffer(raw, dtype="<f4")
 def trim_head(source, seconds, out):
    """`source` with `seconds` removed from the front — a differently trimmed release."""
    subprocess.run(
        ["ffmpeg", "-nostdin", "-v", "error", "-y", "-ss", f"{seconds:.3f}", "-i", str(source),
         "-ac", "1", "-ar", str(sae_audio.sample_rate), "-sample_fmt", "s16",
         "-c:a", "flac", str(out)], check=True)
    return out
 def tier(score):
    if score >= AUDIO_TIER:
        return "audio"
    return "loose" if score >= LOOSE_TIER else "none"
 # ── The random trial set, signed once and reused ─────────────────────────────
 def random_trials(pcm):
    """(reference bins, [(expected_frames, query bins)]) for TRIALS excerpts.
    Signing 40 windows is the expensive part of this file, so UT-105 and UT-108
    share one set — they ask different questions of the same measurements.
    """
    window = sae_audio.window_samples
    reference = peak_bins(sae_audio.signature_from_mono(pcm[:window]))
    rng = random.Random(SEED)
    queries = []
    for _ in range(TRIALS):
        # Within the search cap: past it, no offset is recoverable by
        # construction, which UT-107 checks separately.
        start = rng.randrange(0, SEARCH_CAP_FRAMES * sae_audio.hop_size)
        signature = sae_audio.signature_from_mono(pcm[start:start + window])
        assert signature is not None, "a full window must always sign"
        queries.append((start / sae_audio.hop_size, peak_bins(signature)))
    return reference, queries
 # ── UT-105 — window offsets from random excerpt starts ───────────────────────
 def test_random_window_offsets(reference, queries):
    """Every in-cap offset is recovered to the nearest frame, on real audio."""
    rows = []
    for want, query in queries:
        score, offset = best_match(reference, query)
        rows.append((want, offset, score, abs(want - round(want))))
    expected = np.array([r[0] for r in rows])
    offset = np.array([r[1] for r in rows])
    score = np.array([r[2] for r in rows])
    subframe = np.array([r[3] for r in rows])
    error = np.abs(offset - expected)
    # The offset is quantised to whole frames, so the best any correct answer
    # can do is half a frame — 46 ms. What matters is the budget that half-frame
    # is measured against, and it is an order of magnitude away from it.
    assert error.max() <= 1.0, f"offset missed by {error.max():.2f} frames"
    assert error.max() * HOP_SEC <= OFFSET_BUDGET_SEC, (
        f"offset error {error.max() * HOP_SEC:.3f}s exceeds the {OFFSET_BUDGET_SEC}s budget")
    # Never mistaken for different content. This is the floor that matters: the
    # audio genuinely is the same cut, so a "no match" would be a false negative
    # on the case the feature exists for.
    assert score.min() >= LOOSE_TIER, f"same content scored {score.min():.3f}"
    # An offset that lands near a frame boundary has no excuse: it should reach
    # the top tier, and does.
    aligned = subframe <= 0.1
    assert aligned.any(), "seed no longer produces a near-aligned trial"
    assert score[aligned].min() >= AUDIO_TIER, (
        f"near-frame-aligned offset scored only {score[aligned].min():.3f}")
    print(f"UT-105  {TRIALS} random window offsets, all within the +/-600 frame cap")
    print(f"        offset error   : max {error.max():.2f} frames"
          f" = {error.max() * HOP_SEC * 1000:.0f} ms, against a"
          f" {OFFSET_BUDGET_SEC * 1000:.0f} ms budget")
    print(f"        score          : min {score.min():.3f}  median {np.median(score):.3f}"
          f"  max {score.max():.3f}")
    print("        score by sub-frame misalignment — the offset is exact in every row:")
    for lo, hi in ((0.0, 0.1), (0.1, 0.2), (0.2, 0.3), (0.3, 0.4), (0.4, 0.5)):
        m = (subframe >= lo) & (subframe < hi)
        if m.any():
            print(f"          {lo:.1f}-{hi:.1f} frame  n={m.sum():2d}"
                  f"  score {score[m].min():.3f}-{score[m].max():.3f}"
                  f"  tier {tier(np.median(score[m]))}")
    counts = {t: int(sum(1 for s in score if tier(s) == t)) for t in ("audio", "loose", "none")}
    print(f"        tiers          : {counts}")
    return counts
 # ── UT-106 — head trims through real files, including the runtime/2 anchor ───
 def test_head_trims():
    """A release with delta seconds of head removed aligns at delta/2 frames."""
    reference = peak_bins(sae_audio.compute_signature(str(FIXTURE)))
    results = []
    with tempfile.TemporaryDirectory() as tmp:
        for delta in (7.0, 23.5, 41.25, 60.0):
            trimmed = trim_head(FIXTURE, delta, Path(tmp) / f"trim_{delta}.flac")
            signature = sae_audio.compute_signature(str(trimmed))
            assert signature is not None, f"trim of {delta}s should still sign"
            score, offset = best_match(reference, peak_bins(signature))
            # The window follows the midpoint, so removing delta from the head
            # moves it by delta/2 — not by delta.
            expected = (delta / 2.0) / HOP_SEC
            assert abs(offset - expected) <= 1.0, (
                f"head trim {delta}s: expected ~{expected:.1f} frames, got {offset}")
            assert score >= LOOSE_TIER, f"head trim {delta}s scored {score:.3f}"
            results.append((delta, expected, offset, score))
    print("UT-106  head trims through the real decode path (compute_signature on a file)")
    for delta, expected, offset, score in results:
        print(f"        -{delta:6.2f}s head  expected {expected:7.2f} fr"
              f"  recovered {offset:5d}  score {score:.3f} ({tier(score)})")
 # ── UT-107 — what must NOT match ─────────────────────────────────────────────
 def test_declines(pcm, reference):
    """Out-of-cap offsets and unrelated content are declined, not guessed at."""
    window = sae_audio.window_samples
    beyond = int(75.0 * sae_audio.sample_rate)          # ~807 frames, past the cap
    assert beyond + window <= len(pcm), "fixture too short for the out-of-cap case"
    far = peak_bins(sae_audio.signature_from_mono(pcm[beyond:beyond + window]))
    score_beyond, offset_beyond = best_match(reference, far)
    assert score_beyond < LOOSE_TIER, (
        f"an offset past the cap scored {score_beyond:.3f} at {offset_beyond} — "
        "the search invented an alignment rather than declining")
    tone = peak_bins(sae_audio.compute_signature(str(TONE)))
    score_tone, offset_tone = best_match(reference, tone)
    assert score_tone < LOOSE_TIER, f"unrelated content scored {score_tone:.3f}"
    print("UT-107  declines rather than guesses")
    print(f"        offset past the +/-600 frame cap : best {score_beyond:.3f}"
          f" at {offset_beyond} ({tier(score_beyond)})")
    print(f"        unrelated content (tone fixture) : best {score_tone:.3f}"
          f" at {offset_tone} ({tier(score_tone)})")
    return far, tone
 # ── UT-108 — the sub-frame demotion, and what one frame of slack costs ───────
 def test_scoring_slack(reference, queries, far, tone):
    """Measured: +/-1 frame of slack in the *score* restores the `audio` tier.
    UT-105 leaves a real question open. Every offset is right, but two thirds of
    them score below the server's 0.85 `audio` threshold purely because the two
    windows' frame grids do not coincide — so a correctly aligned release is
    demoted to `loose`, which is the tier meaning "possibly the same cut,
    degraded audio". The obvious remedy is to stop demanding that frames line up
    exactly, and the question is what that costs in discrimination.
    Nothing is asserted about the spec's own rule here; this measures a
    candidate change to it, which is the server's to make (SPEC.md section 3).
    """
    print("UT-108  cost of relaxing the score's frame alignment")
    print(f"        {'slack':>5} {'audio':>6} {'loose':>6} {'none':>5}"
          f" {'min true':>9} {'worst err':>10} {'unrelated':>10} {'out-of-cap':>11}")
    measured = {}
    for slack in (0, 1, 2):
        score, error = [], []
        for want, query in queries:
            s, offset = best_match(reference, query, slack=slack)
            score.append(s)
            error.append(abs(offset - want))
        score, error = np.array(score), np.array(error)
        false_tone, _ = best_match(reference, tone, slack=slack)
        false_far, _ = best_match(reference, far, slack=slack)
        counts = {t: int(sum(1 for s in score if tier(s) == t)) for t in ("audio", "loose", "none")}
        measured[slack] = (score, error, max(false_tone, false_far))
        print(f"        {slack:>5} {counts['audio']:>6} {counts['loose']:>6} {counts['none']:>5}"
              f" {score.min():>9.3f} {error.max() * HOP_SEC * 1000:>7.0f} ms"
              f" {false_tone:>10.3f} {false_far:>11.3f}")
    score, error, worst_false = measured[1]
    # One frame of slack lifts every correct alignment to the top tier...
    assert score.min() >= AUDIO_TIER, (
        f"one frame of slack still leaves a true match at {score.min():.3f}")
    # ...without narrowing the gap that makes the threshold mean anything...
    assert worst_false < LOOSE_TIER, (
        f"slack lifted a false match to {worst_false:.3f}")
    # ...and the offset it costs is still far inside the budget: the score's
    # peak flattens slightly, so the argmax can pick an adjacent frame.
    assert error.max() * HOP_SEC <= OFFSET_BUDGET_SEC, (
        f"slack cost {error.max() * HOP_SEC:.3f}s of offset accuracy")
    print(f"        +/-1 frame: every true match reaches `audio` (min {score.min():.3f}),"
          f" worst false stays at {worst_false:.3f},")
    print(f"        and the offset costs {error.max() * HOP_SEC * 1000:.0f} ms of a"
          f" {OFFSET_BUDGET_SEC * 1000:.0f} ms budget. +/-2 buys nothing more.")
 def main():
    if not FIXTURE.exists():
        print(f"missing fixture {FIXTURE} — regenerate with make_offset_fixture.sh", file=sys.stderr)
        return 2
    if shutil.which("ffmpeg") is None:
        print("this validation needs the ffmpeg CLI to trim the fixture", file=sys.stderr)
        return 2
    print(f"VR-014  audio-signature offset recovery on {FIXTURE.name}")
    print(f"        {sae_audio.expected_frames} frames per signature,"
          f" {HOP_SEC * 1000:.2f} ms per frame, cap +/-{SEARCH_CAP_FRAMES} frames")
    pcm = decode_mono(FIXTURE)
    reference, queries = random_trials(pcm)
    counts = test_random_window_offsets(reference, queries)
    test_head_trims()
    far, tone = test_declines(pcm, reference)
    test_scoring_slack(reference, queries, far, tone)
    print()
    print(f"PASS — every in-cap offset recovered to the nearest frame, worst"
          f" {1000 * HOP_SEC / 2:.0f} ms against a {OFFSET_BUDGET_SEC * 1000:.0f} ms budget.")
    if counts["audio"] < TRIALS:
        # Stated rather than asserted against the spec's rule: the offset is
        # right in every case, so this is the 0.85 threshold meeting a sub-frame
        # shift, not a defect in the signature. The threshold was calibrated on
        # a re-encode at zero offset, where the score is 1.00. UT-108 measures
        # the remedy; adopting it is the server spec's call, not this repo's.
        print(f"NOTE  — under the spec's exact-frame score only {counts['audio']}/{TRIALS}"
              f" reach `audio`; {counts['loose']} are demoted to `loose` by sub-frame"
              " shift alone. See UT-108.")
    return 0
 if __name__ == "__main__":
    sys.exit(main())
@@ -1,125 +0,0 @@
 // sae_audio — Python module wrapping the v1 audio signature (audio_signature.*).
 //
 /// TRACES: IR-004, IR-005 | SR-003
 //
 // Exists so a study or a test can drive the **shipped** signature code from
 // Python instead of porting the DSP to numpy. A numpy port would be a third
 // implementation of a fingerprint that only works if every implementation
 // agrees byte for byte, and it would be the one nobody checks against the
 // golden vector — so the offset-recovery validation (VR-014) calls this.
 //
 // Bound with nanobind, as `sae_embed` and `sae_kpn` are. Not pybind11: a second
 // binding framework in one build is a second set of ABI and lifetime rules to
 // get right, for a module that needs nothing nanobind lacks.
 //
 // The module deliberately stops at the producer's edge. Matching — sliding one
 // signature against another and scoring the overlap — is the *consumer's*
 // algorithm (server SPEC §3, and the jRay plugin implements it), so it is not
 // bound here and a caller writing a slide in numpy is not re-implementing
 // anything this repo owns.
 #include "audio_signature.hpp"
 #include <nanobind/nanobind.h>
 #include <nanobind/ndarray.h>
 #include <nanobind/stl/optional.h>
 #include <nanobind/stl/pair.h>
 #include <nanobind/stl/string.h>
 #include <nanobind/stl/vector.h>
 #include <cstdint>
 #include <optional>
 #include <string>
 #include <utility>
 #include <vector>
 namespace nb = nanobind;
 using namespace nb::literals;
 using namespace sae::audio;
 namespace {
 using MonoArray = nb::ndarray<const float, nb::ndim<1>, nb::c_contig, nb::device::cpu>;
 // Hand the vector's buffer to Python without copying 1.3 M samples, and let a
 // capsule own it: the array outlives this call, so the storage has to as well.
 nb::object own_as_ndarray(std::vector<float>&& samples) {
    auto* held = new std::vector<float>(std::move(samples));
    nb::capsule owner(held, [](void* p) noexcept {
        delete static_cast<std::vector<float>*>(p);
    });
    const std::size_t n = held->size();
    return nb::cast(nb::ndarray<nb::numpy, float, nb::ndim<1>>(held->data(), {n}, owner));
 }
 std::vector<float> to_vector(const MonoArray& a) {
    return std::vector<float>(a.data(), a.data() + a.shape(0));
 }
 }  // namespace
 NB_MODULE(sae_audio, m) {
    m.doc() =
        "JRay v1 audio signature (JRay-public-server SPEC.md section 3), as the "
        "extraction pipeline computes it. The constants below are the contract: "
        "changing any of them is a v1 -> v2 change.";
    m.attr("sample_rate") = kSampleRate;
    m.attr("frame_size") = kFrameSize;
    m.attr("hop_size") = kHopSize;
    m.attr("num_bands") = kNumBands;
    m.attr("band_lo_hz") = kBandLoHz;
    m.attr("band_hi_hz") = kBandHiHz;
    m.attr("window_sec") = kWindowSec;
    m.attr("window_samples") = kWindowSamples;
    m.attr("expected_frames") = kExpectedFrames;
    m.attr("version_prefix") = std::string(kVersionPrefix);
    m.def(
        "compute_signature",
        [](const std::string& path) { return compute_signature(path); },
        "path"_a,
        "Signature of the 120 s window centred on the media's midpoint, or None "
        "for media shorter than the window (IR-007), media with no audio "
        "stream, and any decode failure — degradation, never an exception.");
    m.def(
        "decode_centre_window",
        [](const std::string& path) -> nb::object {
            std::optional<std::vector<float>> mono = decode_centre_window(path);
            if (!mono) {
                return nb::none();
            }
            return own_as_ndarray(std::move(*mono));
        },
        "path"_a,
        "The decoded centre window as float32 mono at 11025 Hz, or None. Exposed "
        "so a caller can slice or perturb real audio and re-sign it without "
        "going back through a container.");
    m.def(
        "signature_from_mono",
        [](const MonoArray& mono) { return signature_from_mono(to_vector(mono)); },
        "mono"_a,
        "Signature of mono float32 samples already at 11025 Hz, in [-1, 1). None "
        "when fewer than one whole frame is given.");
    m.def(
        "pack_frames",
        [](const MonoArray& mono) {
            std::vector<std::uint8_t> packed = pack_frames(to_vector(mono));
            return nb::bytes(reinterpret_cast<const char*>(packed.data()), packed.size());
        },
        "mono"_a,
        "One packed byte per whole STFT frame: (band << 2) | energy_class. This "
        "is the payload the signature base64-encodes.");
    m.def(
        "band_fft_bins",
        [] {
            const auto& table = band_fft_bins();
            return std::vector<std::pair<int, int>>(table.begin(), table.end());
        },
        "The half-open FFT bin range owned by each of the 32 log-spaced bands.");
 }
@@ -1,443 +0,0 @@
 // ── JRay audio signature, v1 — implementation ────────────────────────────────
 //
 /// TRACES: IR-004, IR-007, IR-008 | SR-003
 //
 // The contract this implements is documented in full in audio_signature.hpp;
 // read that before changing anything here. Every constant is load-bearing: the
 // JRay Jellyfin plugin computes the same bytes in C#, and a signature that
 // differs in any parameter simply does not match.
 //
 // Audio decode is a *second stream from an existing dependency* — the pipeline
 // already links libavformat/libavcodec/libavutil for video (ffmpeg_decoder.hpp);
 // this adds libswresample for the downmix+resample, no new project dependency.
 // The FFT is written out here rather than pulled from a library for the same
 // reason the plugin vendors one: it is a fixed, fully specified transform, and
 // a dependency whose version could change the numerics is a liability when the
 // output has to be bit-identical across two languages.
 #include "audio_signature.hpp"
 extern "C" {
 #include <libavcodec/avcodec.h>
 #include <libavformat/avformat.h>
 #include <libavutil/avutil.h>
 #include <libavutil/channel_layout.h>
 #include <libavutil/opt.h>
 #include <libavutil/samplefmt.h>
 #include <libswresample/swresample.h>
 }
 #include <algorithm>
 #include <cmath>
 #include <cstring>
 #include <vector>
 namespace sae::audio {
 namespace {
 constexpr double kPi = 3.14159265358979323846;
 // ── Band table ───────────────────────────────────────────────────────────────
 // edge[b] = 300 * 10^(b/32); band b owns FFT bins [k_lo[b], k_lo[b+1]).
 // ceil() of the edge in bins, so membership is decided once by integers rather
 // than by a float comparison per bin per frame. The bands tile [112, 1115)
 // contiguously with no gap and no overlap, which is what lets the frame energy
 // below be accumulated from the per-band sums.
 std::array<std::pair<int, int>, kNumBands> build_band_table() {
    const double hz_per_bin = static_cast<double>(kSampleRate) / kFrameSize;
    std::array<int, kNumBands + 1> k{};
    for (int b = 0; b <= kNumBands; ++b) {
        const double edge = kBandLoHz * std::pow(kBandHiHz / kBandLoHz,
                                                 static_cast<double>(b) / kNumBands);
        k[b] = static_cast<int>(std::ceil(edge / hz_per_bin));
    }
    std::array<std::pair<int, int>, kNumBands> tbl{};
    for (int b = 0; b < kNumBands; ++b) tbl[b] = {k[b], k[b + 1]};
    return tbl;
 }
 // Hann, periodic: w[n] = 0.5 * (1 - cos(2*pi*n/N)). Not the symmetric (N-1)
 // variant — the two differ, and the difference is observable.
 const std::vector<double>& hann_window() {
    static const std::vector<double> w = [] {
        std::vector<double> v(kFrameSize);
        for (int n = 0; n < kFrameSize; ++n)
            v[n] = 0.5 * (1.0 - std::cos(2.0 * kPi * n / kFrameSize));
        return v;
    }();
    return w;
 }
 // ── Radix-2 decimation-in-time complex FFT, in place, no normalisation ──────
 // Twiddles are precomputed per stage from cos/sin of -2*pi*j/len so the angle
 // is an exactly reproducible double in any language and only the libm rounding
 // of cos/sin (≤1 ulp) can differ — orders of magnitude below the decision
 // margins in the golden fixture.
 struct FftTables {
    std::vector<int> rev;                       // bit-reversal permutation
    std::vector<std::vector<double>> wr, wi;    // per stage
 };
 const FftTables& fft_tables() {
    static const FftTables t = [] {
        FftTables f;
        f.rev.resize(kFrameSize);
        int bits = 0;
        while ((1 << bits) < kFrameSize) ++bits;
        for (int i = 0; i < kFrameSize; ++i) {
            int r = 0;
            for (int b = 0; b < bits; ++b)
                if (i & (1 << b)) r |= 1 << (bits - 1 - b);
            f.rev[i] = r;
        }
        for (int len = 2; len <= kFrameSize; len <<= 1) {
            const int half = len / 2;
            std::vector<double> cr(half), ci(half);
            for (int j = 0; j < half; ++j) {
                const double ang = -2.0 * kPi * j / len;
                cr[j] = std::cos(ang);
                ci[j] = std::sin(ang);
            }
            f.wr.push_back(std::move(cr));
            f.wi.push_back(std::move(ci));
        }
        return f;
    }();
    return t;
 }
 void fft_4096(std::vector<double>& re, std::vector<double>& im) {
    const FftTables& t = fft_tables();
    for (int i = 0; i < kFrameSize; ++i) {
        const int j = t.rev[i];
        if (i < j) { std::swap(re[i], re[j]); std::swap(im[i], im[j]); }
    }
    int stage = 0;
    for (int len = 2; len <= kFrameSize; len <<= 1, ++stage) {
        const int half = len / 2;
        const std::vector<double>& wr = t.wr[stage];
        const std::vector<double>& wi = t.wi[stage];
        for (int base = 0; base < kFrameSize; base += len) {
            for (int j = 0; j < half; ++j) {
                const int a = base + j;
                const int b = a + half;
                const double tr = re[b] * wr[j] - im[b] * wi[j];
                const double ti = re[b] * wi[j] + im[b] * wr[j];
                re[b] = re[a] - tr;  im[b] = im[a] - ti;
                re[a] = re[a] + tr;  im[a] = im[a] + ti;
            }
        }
    }
 }
 int energy_class(double r) {
    if (r < kEnergyClassEdges[0]) return 0;
    if (r < kEnergyClassEdges[1]) return 1;
    if (r < kEnergyClassEdges[2]) return 2;
    return 3;
 }
 // ── FFmpeg RAII ─────────────────────────────────────────────────────────────
 struct DecodeCtx {
    AVFormatContext* fmt  = nullptr;
    AVCodecContext*  dec  = nullptr;
    SwrContext*      swr  = nullptr;
    AVFrame*         frm  = nullptr;
    AVPacket*        pkt  = nullptr;
    ~DecodeCtx() {
        if (swr) swr_free(&swr);
        if (frm) av_frame_free(&frm);
        if (pkt) av_packet_free(&pkt);
        if (dec) avcodec_free_context(&dec);
        if (fmt) avformat_close_input(&fmt);
    }
 };
 bool open_resampler(DecodeCtx& c, const AVFrame* f) {
 #if LIBAVUTIL_VERSION_INT >= AV_VERSION_INT(57, 24, 100)
    // Both MUST be zero-initialised. av_channel_layout_copy documents that it
    // "will always uninitialize the destination before copy", and
    // av_channel_layout_uninit() calls av_freep() on u.map — so a declaration
    // without {} hands free() whatever pointer-shaped garbage the stack frame
    // happened to hold. That is a real crash ("free(): invalid pointer"), not a
    // theoretical one: it reproduced in roughly 1 run in 4 of UT-103, the only
    // test that exercises this branch, because it is the only one whose input
    // is stereo and so the only one that reaches the downmix path at all.
    //
    // It hid for two reasons worth remembering. It is stack-dependent, so it
    // vanishes under a sanitizer build and looks like a flake in the aggregate
    // test binary; and the golden-vector tests (UT-101) pass a mono 11025 Hz
    // fixture, which is chosen precisely so the vector does not depend on the
    // resampler — so bit-exactness against the golden vector proves nothing
    // about this function.
    AVChannelLayout out_layout{};
    av_channel_layout_default(&out_layout, 1);          // mono
    AVChannelLayout in_layout{};
    if (av_channel_layout_copy(&in_layout, &f->ch_layout) < 0) return false;
    if (in_layout.nb_channels <= 0) {
        av_channel_layout_uninit(&in_layout);
        av_channel_layout_default(&in_layout, 1);
    }
    const int rc = swr_alloc_set_opts2(
        &c.swr,
        &out_layout, AV_SAMPLE_FMT_FLT, kSampleRate,
        &in_layout, static_cast<AVSampleFormat>(f->format),
        f->sample_rate ? f->sample_rate : kSampleRate,
        0, nullptr);
    av_channel_layout_uninit(&in_layout);
    av_channel_layout_uninit(&out_layout);
    if (rc < 0 || !c.swr) return false;
 #else
    const int64_t in_layout = f->channel_layout
        ? static_cast<int64_t>(f->channel_layout)
        : av_get_default_channel_layout(f->channels ? f->channels : 1);
    c.swr = swr_alloc_set_opts(
        nullptr,
        AV_CH_LAYOUT_MONO, AV_SAMPLE_FMT_FLT, kSampleRate,
        in_layout, static_cast<AVSampleFormat>(f->format),
        f->sample_rate ? f->sample_rate : kSampleRate,
        0, nullptr);
    if (!c.swr) return false;
 #endif
    return swr_init(c.swr) >= 0;
 }
 // Push one decoded frame (or a flush) through the resampler, dropping the
 // leading `to_skip` output samples, and append to `out`.
 void drain(SwrContext* swr, const AVFrame* f, int in_rate,
           std::size_t& to_skip, std::vector<float>& out) {
    const int64_t delay   = swr_get_delay(swr, in_rate ? in_rate : kSampleRate);
    const int     in_n    = f ? f->nb_samples : 0;
    const int     max_out = static_cast<int>(av_rescale_rnd(
        delay + in_n, kSampleRate, in_rate ? in_rate : kSampleRate, AV_ROUND_UP)) + 32;
    if (max_out <= 0) return;
    std::vector<float> buf(static_cast<std::size_t>(max_out));
    uint8_t* dst = reinterpret_cast<uint8_t*>(buf.data());
    const int n = swr_convert(swr, &dst, max_out,
                              f ? const_cast<const uint8_t**>(f->extended_data) : nullptr,
                              in_n);
    if (n <= 0) return;
    std::size_t produced = static_cast<std::size_t>(n);
    std::size_t off = 0;
    if (to_skip) {
        const std::size_t drop = std::min(to_skip, produced);
        to_skip -= drop;
        off = drop;
        produced -= drop;
    }
    if (produced)
        out.insert(out.end(), buf.begin() + off, buf.begin() + off + produced);
 }
 }  // namespace
 // ── Public surface ──────────────────────────────────────────────────────────
 const std::array<std::pair<int, int>, kNumBands>& band_fft_bins() {
    static const std::array<std::pair<int, int>, kNumBands> tbl = build_band_table();
    return tbl;
 }
 std::string base64_encode(const std::uint8_t* data, std::size_t n) {
    static constexpr char kAlphabet[] =
        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    std::string out;
    out.reserve(((n + 2) / 3) * 4);
    std::size_t i = 0;
    for (; i + 3 <= n; i += 3) {
        const std::uint32_t v = (std::uint32_t(data[i]) << 16) |
                                (std::uint32_t(data[i + 1]) << 8) |
                                 std::uint32_t(data[i + 2]);
        out += kAlphabet[(v >> 18) & 0x3F];
        out += kAlphabet[(v >> 12) & 0x3F];
        out += kAlphabet[(v >> 6) & 0x3F];
        out += kAlphabet[v & 0x3F];
    }
    if (i < n) {
        const bool two = (n - i) == 2;
        const std::uint32_t v = (std::uint32_t(data[i]) << 16) |
                                (two ? (std::uint32_t(data[i + 1]) << 8) : 0u);
        out += kAlphabet[(v >> 18) & 0x3F];
        out += kAlphabet[(v >> 12) & 0x3F];
        out += two ? kAlphabet[(v >> 6) & 0x3F] : '=';
        out += '=';
    }
    return out;
 }
 std::uint64_t fnv1a64(const void* data, std::size_t n) {
    const auto* p = static_cast<const std::uint8_t*>(data);
    std::uint64_t h = 0xcbf29ce484222325ULL;
    for (std::size_t i = 0; i < n; ++i) {
        h ^= p[i];
        h *= 0x100000001b3ULL;
    }
    return h;
 }
 /// TRACES: IR-004
 std::vector<std::uint8_t> pack_frames(const std::vector<float>& mono) {
    if (mono.size() < static_cast<std::size_t>(kFrameSize)) return {};
    const std::size_t nframes = 1 + (mono.size() - kFrameSize) / kHopSize;
    const auto& bands = band_fft_bins();
    const auto& win   = hann_window();
    const int   k_lo  = bands.front().first;
    const int   k_hi  = bands.back().second;      // exclusive
    const double bin_count = static_cast<double>(k_hi - k_lo);
    std::vector<double>       re(kFrameSize), im(kFrameSize);
    std::vector<std::uint8_t> peak(nframes);
    std::vector<double>       energy(nframes);
    for (std::size_t f = 0; f < nframes; ++f) {
        const float* src = mono.data() + f * kHopSize;
        for (int n = 0; n < kFrameSize; ++n) {
            re[n] = static_cast<double>(src[n]) * win[n];
            im[n] = 0.0;
        }
        fft_4096(re, im);
        // Per-band mean magnitude; the bands tile the 300–3000 Hz range with no
        // gaps, so the frame's band-limited energy is the sum of the band sums.
        double best = -1.0, total = 0.0;
        int    best_b = 0;
        for (int b = 0; b < kNumBands; ++b) {
            double sum = 0.0;
            for (int k = bands[b].first; k < bands[b].second; ++k)
                sum += std::sqrt(re[k] * re[k] + im[k] * im[k]);
            total += sum;
            const double mean = sum / (bands[b].second - bands[b].first);
            if (mean > best) { best = mean; best_b = b; }   // ties → lowest index
        }
        peak[f]   = static_cast<std::uint8_t>(best_b);
        energy[f] = total / bin_count;
    }
    // Reference is the upper median of the frame energies: an actually observed
    // value (no averaging of the two middle samples), so it is bit-reproducible,
    // gain-invariant and barely moves when the window is trimmed.
    std::vector<double> sorted = energy;
    std::sort(sorted.begin(), sorted.end());
    const double ref = sorted[sorted.size() / 2];
    std::vector<std::uint8_t> out(nframes);
    for (std::size_t f = 0; f < nframes; ++f) {
        const double r = std::log10((energy[f] + kEnergyEps) / (ref + kEnergyEps));
        out[f] = static_cast<std::uint8_t>(((peak[f] & 0x1F) << 2) |
                                           (energy_class(r) & 0x03));
    }
    return out;
 }
 /// TRACES: IR-004, IR-008
 std::optional<std::string> signature_from_mono(const std::vector<float>& mono) {
    const std::vector<std::uint8_t> packed = pack_frames(mono);
    if (packed.empty()) return std::nullopt;
    return std::string(kVersionPrefix) + base64_encode(packed.data(), packed.size());
 }
 /// TRACES: IR-004, IR-007
 std::optional<std::vector<float>> decode_centre_window(const std::string& path) {
    av_log_set_level(AV_LOG_ERROR);
    DecodeCtx c;
    if (avformat_open_input(&c.fmt, path.c_str(), nullptr, nullptr) < 0)
        return std::nullopt;
    if (avformat_find_stream_info(c.fmt, nullptr) < 0) return std::nullopt;
    if (c.fmt->duration == AV_NOPTS_VALUE) return std::nullopt;
    const double duration = static_cast<double>(c.fmt->duration) / AV_TIME_BASE;
    // IR-007 — the window underflows, so there is no signature and no sync
    // offset downstream. The plugin applies the identical rule.
    if (duration < kWindowSec) return std::nullopt;
    const int idx = av_find_best_stream(c.fmt, AVMEDIA_TYPE_AUDIO, -1, -1, nullptr, 0);
    if (idx < 0) return std::nullopt;                     // no audio → no signature
    AVStream* st = c.fmt->streams[idx];
    const AVCodec* codec = avcodec_find_decoder(st->codecpar->codec_id);
    if (!codec) return std::nullopt;
    c.dec = avcodec_alloc_context3(codec);
    if (!c.dec) return std::nullopt;
    if (avcodec_parameters_to_context(c.dec, st->codecpar) < 0) return std::nullopt;
    c.dec->thread_count = 0;
    if (avcodec_open2(c.dec, codec, nullptr) < 0) return std::nullopt;
    const double start_sec = duration / 2.0 - kWindowSec / 2.0;
    // Seek to a packet at or before the window start; the exact start is then
    // reached by discarding the leading output samples, which is what
    // `ffmpeg -ss <t> -i <file>` does and therefore what the plugin sees.
    if (start_sec > 0.0) {
        const int64_t tgt = av_rescale_q(
            static_cast<int64_t>(start_sec * AV_TIME_BASE), AV_TIME_BASE_Q, st->time_base);
        if (av_seek_frame(c.fmt, idx, tgt, AVSEEK_FLAG_BACKWARD) >= 0)
            avcodec_flush_buffers(c.dec);
    }
    c.frm = av_frame_alloc();
    c.pkt = av_packet_alloc();
    if (!c.frm || !c.pkt) return std::nullopt;
    std::vector<float> mono;
    mono.reserve(kWindowSamples + kSampleRate);
    std::size_t to_skip  = 0;
    bool        have_swr = false;
    int         in_rate  = kSampleRate;
    bool        eof      = false;
    while (mono.size() < kWindowSamples && !eof) {
        const int rr = av_read_frame(c.fmt, c.pkt);
        if (rr < 0) {
            eof = true;
            avcodec_send_packet(c.dec, nullptr);          // flush the decoder
        } else if (c.pkt->stream_index != idx) {
            av_packet_unref(c.pkt);
            continue;
        } else {
            avcodec_send_packet(c.dec, c.pkt);
            av_packet_unref(c.pkt);
        }
        while (avcodec_receive_frame(c.dec, c.frm) == 0) {
            if (!have_swr) {
                if (!open_resampler(c, c.frm)) return std::nullopt;
                have_swr = true;
                in_rate  = c.frm->sample_rate ? c.frm->sample_rate : kSampleRate;
                int64_t pts = c.frm->best_effort_timestamp;
                if (pts == AV_NOPTS_VALUE) pts = c.frm->pts;
                const double t0 = (pts == AV_NOPTS_VALUE)
                    ? start_sec : av_q2d(st->time_base) * static_cast<double>(pts);
                const double lead = start_sec - t0;
                to_skip = lead > 0.0
                    ? static_cast<std::size_t>(std::llround(lead * kSampleRate)) : 0;
            }
            drain(c.swr, c.frm, in_rate, to_skip, mono);
            av_frame_unref(c.frm);
            if (mono.size() >= kWindowSamples) break;
        }
    }
    if (have_swr && mono.size() < kWindowSamples)
        drain(c.swr, nullptr, in_rate, to_skip, mono);     // flush the resampler
    if (mono.empty()) return std::nullopt;
    // Truncate to exactly 120.000 s so the frame count is 1288 for every input
    // and does not wobble with seek granularity or the resampler tail.
    if (mono.size() > kWindowSamples) mono.resize(kWindowSamples);
    return mono;
 }
 /// TRACES: IR-004, IR-005, IR-007, IR-008
 std::optional<std::string> compute_signature(const std::string& path) {
    const std::optional<std::vector<float>> mono = decode_centre_window(path);
    if (!mono) return std::nullopt;
    return signature_from_mono(*mono);
 }
 }  // namespace sae::audio
@@ -1,158 +0,0 @@
 #pragma once
 // ── JRay audio signature, v1 ─────────────────────────────────────────────────
 //
 /// TRACES: IR-004, IR-005, IR-007, IR-008 | SR-003
 //
 // A content-derived spectral-peak signature taken from the *centre* of the
 // media, so a truth file is self-identifying: a consumer can tell whether a
 // local file is the same cut as the one a manifest describes, and recover the
 // frame offset when it is the same cut trimmed differently.
 //
 // The construction is owned by `JRay-public-server/SPEC.md` §3 and is
 // reproduced by the JRay Jellyfin plugin in C#. **The two implementations must
 // agree byte for byte** — a signature that differs in any parameter simply does
 // not match, which defeats the entire point. Every deviation is therefore a
 // breaking change and must go through the `v1:` prefix (see kVersionPrefix).
 //
 // Server spec §3, restated:
 //
 //   1. Decode a 120 s window centred on the midpoint (runtime/2 ± 60 s).
 //   2. Downmix to mono, resample to 11025 Hz.
 //   3. STFT: 4096-sample frame, 1024-sample hop, Hann window (~1290 frames).
 //   4. Per frame, log-magnitude spectrum over 300–3000 Hz.
 //   5. 32 logarithmically spaced bins; peak bin index + coarse 2-bit energy
 //      class.
 //   6. Pack one byte per frame; base64-encode.
 //   7. Prefix `v1:`.
 //
 // ── Details the server spec leaves open, pinned here for v1 ──────────────────
 //
 // The prose above is not sufficient to reproduce a byte stream, so the choices
 // below are the contract. They are mirrored in
 // `tests/fixtures/audio/jray_audio_v1_golden.json`, which is the artefact
 // shared with the plugin repo (IR-005).
 //
 //   Arithmetic     All DSP in IEEE-754 **double**. float32 is not sufficient:
 //                  the golden fixture has frames whose two strongest bands are
 //                  within 1.3% of each other, which double resolves identically
 //                  everywhere and float32 does not.
 //   Sample scale   FFmpeg's native s16→flt conversion, x * (1/32768), then
 //                  widened to double. Values in [-1, 1).
 //   Framing        Only whole frames: n_frames = 1 + (n_samples - 4096) / 1024,
 //                  integer division, 0 when n_samples < 4096. A 120.000 s
 //                  window is 1 323 000 samples → **1288 frames**.
 //                  ("~1290" in the spec; the server accepts a tolerance.)
 //   Window         Hann, **periodic**: w[n] = 0.5 * (1 - cos(2*pi*n/4096)).
 //                  Not the symmetric (N-1) variant.
 //   Transform      Plain radix-2 decimation-in-time complex FFT over 4096 real
 //                  samples (imag = 0), no normalisation. Magnitude is
 //                  sqrt(re² + im²). Twiddles from cos/sin of
 //                  -2*pi*k/len computed in double.
 //   Band edges     edge[b] = 300 * (3000/300)^(b/32), b = 0..32. Band b spans
 //                  FFT bins [k_lo[b], k_lo[b+1]) with
 //                  k_lo[b] = ceil(edge[b] * 4096 / 11025) — i.e. bins 112..1114
 //                  inclusive, 8 bins in the narrowest band. Precomputed as an
 //                  integer table so no float comparison decides membership.
 //   Band value     **Mean** of the linear magnitudes in the band. Mean, not
 //                  sum, so a wide high band is not favoured over a narrow low
 //                  one; magnitude, not power, because it is an energy proxy and
 //                  more codec-robust than a single bin's peak.
 //   Peak bin       argmax over the 32 band values; ties resolve to the **lowest
 //                  index**. The log of step 4 is a monotone squash and so
 //                  cannot change an argmax — it is applied only where it is
 //                  observable, in the energy class below.
 //   Energy class   The spec says "coarse 2-bit energy class" and no more. v1
 //                  defines it as the frame's band-limited energy relative to
 //                  the window, which is invariant to gain (loudness
 //                  normalisation must not change a signature) and robust to
 //                  trimming (the median barely moves):
 //                    E_f  = mean magnitude over *all* FFT bins 112..1114
 //                    Eref = median over frames of E_f, taken as the upper
 //                           median sorted[n/2] — no averaging of the two middle
 //                           values, so the reference is always an actual
 //                           observed value and is bit-reproducible
 //                    r    = log10((E_f + 1e-12) / (Eref + 1e-12))
 //                    class = 0 if r < -0.6, 1 if r < -0.2, 2 if r < 0.2, else 3
 //                  The thresholds deliberately straddle r = 0 rather than sit
 //                  on it, so the median frame itself is not on a boundary.
 //   Byte layout    bit 7 = 0 (reserved), bits 6..2 = 5-bit band index,
 //                  bits 1..0 = 2-bit energy class:
 //                    byte = (band << 2) | class          → always 0..127
 //                  This is the structural constraint the server validates on
 //                  upload (§3 "Validation and abuse").
 //   Base64         Standard alphabet A–Za–z0–9+/ with '=' padding.
 //
 // ── Short media (IR-007) ─────────────────────────────────────────────────────
 //
 // `runtime/2 ± 60 s` underflows below 120 s, so **no signature is emitted** and
 // no sync offset is applied downstream. Both producers apply the identical
 // rule; diverging here would break exactly the short items most likely to be
 // misidentified. `compute_signature` returns `std::nullopt`.
 //
 // The same nullopt is returned for a file with no audio stream, an unopenable
 // file, or an unknown duration. UR-9 is an enhancement and must never be able
 // to break a fetch — degradation, not failure.
 #include <array>
 #include <cstddef>
 #include <cstdint>
 #include <optional>
 #include <string>
 #include <utility>
 #include <vector>
 namespace sae::audio {
 // ── Contract constants — changing any of these is a `v1:` bump ───────────────
 inline constexpr int    kSampleRate    = 11025;
 inline constexpr int    kFrameSize     = 4096;
 inline constexpr int    kHopSize       = 1024;
 inline constexpr int    kNumBands      = 32;
 inline constexpr double kBandLoHz      = 300.0;
 inline constexpr double kBandHiHz      = 3000.0;
 inline constexpr double kWindowSec     = 120.0;
 inline constexpr double kEnergyEps     = 1e-12;
 // Class thresholds on log10(E_frame / E_median); see the header comment.
 inline constexpr double kEnergyClassEdges[3] = {-0.6, -0.2, 0.2};
 // 120.000 s at 11025 Hz. The decoded window is truncated to exactly this so the
 // frame count does not wobble with seek granularity or resampler tail.
 inline constexpr std::size_t kWindowSamples =
    static_cast<std::size_t>(kWindowSec * kSampleRate);          // 1 323 000
 inline constexpr std::size_t kExpectedFrames =
    1 + (kWindowSamples - kFrameSize) / kHopSize;                // 1288
 static_assert(kWindowSamples == 1323000, "120 s at 11025 Hz");
 static_assert(kExpectedFrames == 1288, "server spec's ~1290 frames");
 /// The version prefix is the signature's own, separate from `schema_version`:
 /// a future change to the DSP chain must be *detectable* rather than silently
 /// producing non-matching signatures (IR-008).
 inline constexpr const char* kVersionPrefix = "v1:";
 /// FFT bin range [first, last) for each of the 32 log-spaced bands.
 /// Computed once from the constants above; exposed so the golden fixture can
 /// assert the table itself, not merely the signature it produces.
 const std::array<std::pair<int, int>, kNumBands>& band_fft_bins();
 /// Decode the centre window of `path` as mono float PCM at 11025 Hz.
 /// nullopt when the media is shorter than 120 s (IR-007), has no audio stream,
 /// or cannot be opened. Never throws.
 std::optional<std::vector<float>> decode_centre_window(const std::string& path);
 /// One packed byte per whole STFT frame. Empty when `mono` is shorter than one
 /// frame. This is the payload that gets base64-encoded.
 std::vector<std::uint8_t> pack_frames(const std::vector<float>& mono);
 /// `v1:` + base64(pack_frames(mono)). nullopt when no whole frame fits.
 std::optional<std::string> signature_from_mono(const std::vector<float>& mono);
 /// Decode + sign. The one call the pipeline makes. nullopt per IR-007 and on
 /// any decode failure — degradation, not failure.
 std::optional<std::string> compute_signature(const std::string& path);
 // ── Small utilities, exposed for the golden-fixture test ────────────────────
 std::string   base64_encode(const std::uint8_t* data, std::size_t n);
 /// FNV-1a 64. Used only to pin the *decoded PCM* in the golden fixture, so a
 /// codec-level difference is distinguishable from a DSP-level one.
 std::uint64_t fnv1a64(const void* data, std::size_t n);
 }  // namespace sae::audio
@@ -34,28 +34,11 @@ constexpr int kDim = 512;
 #if defined(SAE_GEMM_CPU)
 #if defined(SAE_GEMM_CBLAS)
 #include <cblas.h>
 #endif
 // ── CPU reference engine ──────────────────────────────────────────────────────
-// Used for CI and as the correctness oracle for the GPU backends.
+// Portable, dependency-free path used for CI and as the correctness oracle for
-//
+// the GPU backends. The gallery is L2-normalised (as are the queries), so each
-// TRACES: AR-026, AR-027 | SR-001
+// similarity is a plain dot product. S is stored column-major to match the GPU
-// Backed by CBLAS (OpenBLAS), which CMake now REQUIRES for this backend. The
+// backends: the gallery similarities for face fi start at result + fi*n_gallery.
 // scalar loop below is portable but scales badly: scoring one face against a
 // 5000-embedding gallery is 2.6 MFLOP, and a crowded frame multiplies that by
 // the face count. Since AR-003 removed the per-frame face cap and CI has no GPU,
 // the CPU path is the one that has to hold up under a library-scale gallery
 // (AR-027) rather than merely be correct — so falling back to it silently would
 // mean measuring AR-027 on a path no release runs.
 //
 // The fallback is kept as the correctness oracle the two BLAS backends are
 // diffed against when a similarity looks wrong, and is reachable only via
 // -DSAE_ALLOW_SCALAR_GEMM=ON. The gallery is L2-normalised (as are the queries),
 // so each similarity is a plain dot product. S is stored column-major to match
 // the GPU backends: the gallery similarities for face fi start at
 // result + fi*n_gallery().
 class SimilarityEngine final : public ISimilarityEngine {
 public:
    SimilarityEngine(const float* gallery_row_major, int n_gallery, int max_faces)
@@ -64,48 +47,18 @@ public:
                   gallery_row_major + static_cast<size_t>(n_gallery) * kDim)
    {
        host_sims_.resize(static_cast<size_t>(max_faces_) * n_gallery_);
-        std::cerr << "[similarity] CPU engine ("
+        std::cerr << "[similarity] CPU reference engine: gallery resident in host RAM ("
 #if defined(SAE_GEMM_CBLAS)
                  << "CBLAS"
 #else
                  << "scalar fallback — no CBLAS; expect poor scaling on a large gallery"
 #endif
                  << "): gallery resident in host RAM ("
                  << (gallery_.size() * sizeof(float)) / (1024 * 1024) << " MiB)\n";
    }
    int max_faces() const override { return max_faces_; }
    int n_gallery() const override { return n_gallery_; }
    /// TRACES: AR-026 | SR-001
    /// Promotions join the resident matrix, so the annex is scored by the same
    /// SGEMM as the baked references. std::vector already grows geometrically,
    /// so this is amortised O(1) per row.
    void append_rows(const float* rows_row_major, int n_rows) override {
        if (n_rows <= 0) return;
        gallery_.insert(gallery_.end(), rows_row_major,
                        rows_row_major + static_cast<size_t>(n_rows) * kDim);
        n_gallery_ += n_rows;
        host_sims_.resize(static_cast<size_t>(max_faces_) * n_gallery_);
    }
    const float* compute(const float* query_row_major, int n_faces) override {
        if (n_faces <= 0) return host_sims_.data();
        if (n_faces > max_faces_)
            throw std::runtime_error("SimilarityEngine: n_faces exceeds max_faces");
-        // S(g, f) col-major = dot(gallery[g], query[f]). Viewed as row-major
+        // S(g, f) col-major = dot(gallery[g], query[f]).
        // [n_faces x n_gallery] that is exactly query * gallery^T, so it is one
        // GEMM rather than a loop nest.
 #if defined(SAE_GEMM_CBLAS)
        cblas_sgemm(CblasRowMajor, CblasNoTrans, CblasTrans,
                    /*M=*/n_faces, /*N=*/n_gallery_, /*K=*/kDim,
                    /*alpha=*/1.0f,
                    query_row_major, /*lda=*/kDim,
                    gallery_.data(), /*ldb=*/kDim,
                    /*beta=*/0.0f,
                    host_sims_.data(), /*ldc=*/n_gallery_);
 #else
        for (int f = 0; f < n_faces; ++f) {
            const float* q = query_row_major + static_cast<size_t>(f) * kDim;
            float* out = host_sims_.data() + static_cast<size_t>(f) * n_gallery_;
@@ -116,7 +69,6 @@ public:
                out[g] = acc;
            }
        }
 #endif
        return host_sims_.data();
    }
@@ -159,7 +111,6 @@ inline void gpu_free(void* p)                                      { cudaFree(p)
 inline void gpu_memcpy_h2d(void* dst, const void* src, size_t n, stream_t s) { check_gpu(cudaMemcpyAsync(dst, src, n, cudaMemcpyHostToDevice, s), "H2D"); }
 inline void gpu_memcpy_d2h(void* dst, const void* src, size_t n, stream_t s) { check_gpu(cudaMemcpyAsync(dst, src, n, cudaMemcpyDeviceToHost, s), "D2H"); }
 inline void gpu_memcpy_h2d_sync(void* dst, const void* src, size_t n)        { check_gpu(cudaMemcpy(dst, src, n, cudaMemcpyHostToDevice), "H2D_sync"); }
 inline void gpu_memcpy_d2d_sync(void* dst, const void* src, size_t n)        { check_gpu(cudaMemcpy(dst, src, n, cudaMemcpyDeviceToDevice), "D2D_sync"); }
 inline void stream_create(stream_t* s)                             { check_gpu(cudaStreamCreate(s), "cudaStreamCreate"); }
 inline void stream_destroy(stream_t s)                             { cudaStreamDestroy(s); }
 inline void stream_sync(stream_t s)                                { check_gpu(cudaStreamSynchronize(s), "cudaStreamSync"); }
@@ -194,7 +145,6 @@ inline void gpu_free(void* p)                                      { (void)hipFr
 inline void gpu_memcpy_h2d(void* dst, const void* src, size_t n, stream_t s) { check_gpu(hipMemcpyAsync(dst, src, n, hipMemcpyHostToDevice, s), "H2D"); }
 inline void gpu_memcpy_d2h(void* dst, const void* src, size_t n, stream_t s) { check_gpu(hipMemcpyAsync(dst, src, n, hipMemcpyDeviceToHost, s), "D2H"); }
 inline void gpu_memcpy_h2d_sync(void* dst, const void* src, size_t n)        { check_gpu(hipMemcpy(dst, src, n, hipMemcpyHostToDevice), "H2D_sync"); }
 inline void gpu_memcpy_d2d_sync(void* dst, const void* src, size_t n)        { check_gpu(hipMemcpy(dst, src, n, hipMemcpyDeviceToDevice), "D2D_sync"); }
 inline void stream_create(stream_t* s)                             { check_gpu(hipStreamCreate(s), "hipStreamCreate"); }
 inline void stream_destroy(stream_t s)                             { (void)hipStreamDestroy(s); }
 inline void stream_sync(stream_t s)                                { check_gpu(hipStreamSynchronize(s), "hipStreamSync"); }
@@ -219,15 +169,14 @@ public:
    SimilarityEngine(const float* gallery_row_major, int n_gallery, int max_faces)
        : n_gallery_(n_gallery), max_faces_(max_faces)
    {
        const size_t gallery_floats = static_cast<size_t>(n_gallery_) * kDim;
        gpu_malloc(reinterpret_cast<void**>(&d_gallery_), gallery_floats * sizeof(float));
        gpu_memcpy_h2d_sync(d_gallery_, gallery_row_major, gallery_floats * sizeof(float));
        gpu_malloc(reinterpret_cast<void**>(&d_query_),
                   static_cast<size_t>(max_faces_) * kDim * sizeof(float));
-
+        gpu_malloc(reinterpret_cast<void**>(&d_sims_),
-        // Allocates d_gallery_/d_sims_ at the initial row count; append_rows()
+                   static_cast<size_t>(max_faces_) * n_gallery_ * sizeof(float));
        // grows them geometrically from here.
        reserve_rows(std::max(n_gallery_, 1));
        const size_t gallery_floats = static_cast<size_t>(n_gallery_) * kDim;
        if (gallery_floats)
            gpu_memcpy_h2d_sync(d_gallery_, gallery_row_major, gallery_floats * sizeof(float));
        stream_create(&stream_);
        blas_create(&handle_);
@@ -251,24 +200,6 @@ public:
    SimilarityEngine& operator=(const SimilarityEngine&) = delete;
    int max_faces() const override { return max_faces_; }
    int n_gallery() const override { return n_gallery_; }
    /// TRACES: AR-026 | SR-001
    /// Promotions join the GPU-resident matrix, so the annex is scored by the
    /// same SGEMM as the baked references rather than by a host-side loop.
    /// Capacity doubles on overflow, so the gallery is re-uploaded O(log n)
    /// times over a film rather than once per promotion.
    void append_rows(const float* rows_row_major, int n_rows) override {
        if (n_rows <= 0) return;
        const int want = n_gallery_ + n_rows;
        if (want > capacity_) reserve_rows(std::max(want, capacity_ * 2));
        gpu_memcpy_h2d_sync(d_gallery_ + static_cast<size_t>(n_gallery_) * kDim,
                            rows_row_major,
                            static_cast<size_t>(n_rows) * kDim * sizeof(float));
        n_gallery_ = want;
        host_sims_.resize(static_cast<size_t>(max_faces_) * n_gallery_);
    }
    const float* compute(const float* query_row_major, int n_faces) override {
        if (n_faces <= 0) return host_sims_.data();
@@ -288,35 +219,7 @@ public:
    }
 private:
    // Grow the resident gallery (and the similarity output sized against it) to
    // `rows` capacity, preserving the n_gallery_ rows already there. The copy is
    // device-to-device, so a promotion never re-uploads the baked gallery across
    // the bus.
    void reserve_rows(int rows) {
        if (rows <= capacity_) return;
        float* d_new_gallery = nullptr;
        gpu_malloc(reinterpret_cast<void**>(&d_new_gallery),
                   static_cast<size_t>(rows) * kDim * sizeof(float));
        if (d_gallery_ && n_gallery_ > 0)
            gpu_memcpy_d2d_sync(d_new_gallery, d_gallery_,
                                static_cast<size_t>(n_gallery_) * kDim * sizeof(float));
        if (d_gallery_) gpu_free(d_gallery_);
        d_gallery_ = d_new_gallery;
        // S is (capacity × n_faces); its contents are rewritten by every
        // compute(), so this one is a plain reallocation with nothing to keep.
        float* d_new_sims = nullptr;
        gpu_malloc(reinterpret_cast<void**>(&d_new_sims),
                   static_cast<size_t>(max_faces_) * rows * sizeof(float));
        if (d_sims_) gpu_free(d_sims_);
        d_sims_ = d_new_sims;
        capacity_ = rows;
    }
    int     n_gallery_{0};
    int     capacity_{0};
    int     max_faces_{0};
    float*  d_gallery_{nullptr};
    float*  d_query_{nullptr};
@@ -124,21 +124,8 @@ inline OrtProvider apply_ort_provider(Ort::SessionOptions& opts,
        try {
            OrtROCMProviderOptions rocm{};
            rocm.device_id = 0;
            // Without these MIOpen runs convolutions on the no-workspace GEMM
            // fallback (the "GemmFwdRest, provided ptr: 0 size: 0" warnings), which
            // is the slow path — most visible on the conv-heavy TransNetV2 scene
            // detector. Exhaustive search lets MIOpen pick the fast conv kernel,
            // and TunableOp autotunes the GEMMs; both cache to the MIOpen user DB
            // (MIOPEN_USER_DB_PATH), so the tuning cost is paid once per shape.
            // Opt-out via SAE_ROCM_NOTUNE=1 for a quick no-warmup run.
            const bool tune = std::getenv("SAE_ROCM_NOTUNE") == nullptr;
            rocm.miopen_conv_exhaustive_search = tune ? 1 : 0;
            rocm.tunable_op_enable             = tune;
            rocm.tunable_op_tuning_enable      = tune;
            opts.AppendExecutionProvider_ROCM(rocm);
-            std::cerr << "[" << label << "] ROCm provider"
+            std::cerr << "[" << label << "] ROCm provider\n";
                      << (tune ? " (MIOpen exhaustive + TunableOp)" : " (untuned)")
                      << "\n";
            return OrtProvider::ROCm;
        } catch (const Ort::Exception& e) {
            std::cerr << "[" << label << "] ROCm unavailable ("
@@ -19,7 +19,6 @@
 #include <NvInfer.h>
 #include <cuda_runtime_api.h>
 #include <cstdlib>
 #include <opencv2/dnn.hpp>
 #include <opencv2/imgproc.hpp>
@@ -46,40 +45,6 @@ inline void check_cuda(cudaError_t e, const char* what) {
        throw CudaError(std::string(what) + ": " + cudaGetErrorString(e));
 }
 /// TRACES: VR-015 | PR-004
 /// Select how a thread waits for the GPU. Must run before the CUDA context is
 /// created, so every engine constructor calls it and the first one wins.
 ///
 /// The default (`cudaDeviceScheduleAuto`) spin-waits: `cudaStreamSynchronize`
 /// burns the calling thread's CPU for the whole of the device's work. Measured
 /// here, the embedder thread sat at 99.7% *user* time with 0.5 s of system time
 /// across 183 s — i.e. no blocking syscalls at all — while the GPU ran flat out.
 ///
 /// On this laptop that is not merely wasted CPU. `nvidia-powerd` arbitrates one
 /// power budget across CPU and GPU, and the GPU's ceiling was observed dropping
 /// from 20 W idle to 15 W under our load, with the SM clock *falling* from
 /// 1005 MHz to 210 MHz once work started. Spinning may therefore be buying
 /// watts away from the device the pipeline is actually waiting on.
 ///
 /// SAE_CUDA_BLOCKING_SYNC=1 switches to a blocking wait so the A/B needs no
 /// rebuild. Default is unchanged until the measurement says otherwise.
 inline void configure_cuda_sync_once() {
    static const bool done = [] {
        const char* env = std::getenv("SAE_CUDA_BLOCKING_SYNC");
        if (env && env[0] == '1') {
            cudaError_t e = cudaSetDeviceFlags(cudaDeviceScheduleBlockingSync);
            std::cerr << "[cuda] sync policy: BlockingSync"
                      << (e == cudaSuccess ? "" : " (FAILED — context already created)")
                      << "\n";
        } else {
            std::cerr << "[cuda] sync policy: default (spin) — "
                         "set SAE_CUDA_BLOCKING_SYNC=1 to compare\n";
        }
        return true;
    }();
    (void)done;
 }
 class TrtLogger : public nvinfer1::ILogger {
 public:
    void log(Severity sev, const char* msg) noexcept override {
@@ -144,7 +109,6 @@ public:
                                      (output_is_fp16_ ? 2 : 4);
        check_cuda(cudaMalloc(&d_input_,  in_bytes),  "cudaMalloc input");
        check_cuda(cudaMalloc(&d_output_, out_bytes), "cudaMalloc output");
        configure_cuda_sync_once();
        check_cuda(cudaStreamCreate(&stream_), "cudaStreamCreate");
        context_->setTensorAddress(input_name_.c_str(),  d_input_);
@@ -329,7 +293,6 @@ public:
            out_elem_counts_[oi] = count;
        }
        configure_cuda_sync_once();
        check_cuda(cudaStreamCreate(&stream_), "cudaStreamCreate");
        std::cerr << "[TrtScrfd] loaded: " << engine_path
@@ -499,7 +462,6 @@ public:
        const std::size_t out_count = static_cast<std::size_t>(kWindow);
        check_cuda(cudaMalloc(&d_input_,  in_count  * 4), "cudaMalloc input");
        check_cuda(cudaMalloc(&d_output_, out_count * 4), "cudaMalloc output");
        configure_cuda_sync_once();
        check_cuda(cudaStreamCreate(&stream_), "cudaStreamCreate");
        context_->setTensorAddress(input_name_.c_str(),  d_input_);
        context_->setTensorAddress(output_name_.c_str(), d_output_);
@@ -1,590 +0,0 @@
 #pragma once
 /// TRACES: VR-015 | PR-004
 ///
 /// Pipeline throughput benchmark — how much of a run is spent in each node.
 ///
 /// The KPN network already counts most of what an optimiser needs, and
 /// `print_diagnostics()` throws nearly all of it away: it prints frames and
 /// `ema` per node, and passes `elapsed_s = 0`, which zeroes throughput. Two
 /// things had to change before "time per node" could be answered honestly.
 ///
 /// **`ema` is not a total.** It is an exponentially weighted average, so
 /// `frames * ema` tracks the end of the run rather than the whole of it. On a
 /// film that is a real difference — a detector costs one thing in a crowd scene
 /// and another over a landscape. `NodeStats::total_exec_us` (added alongside
 /// this) is the true sum.
 ///
 /// **Wall time inside a node is not all work.** `PoolObjectNode::fire_once`
 /// times the functor *and* `push_outputs`, and `push_outputs` parks on a full
 /// downstream channel (AR-004). A node that is merely backpressured therefore
 /// bills the time it spent waiting to whoever is ahead of it: SuperHero's
 /// `frame_source` reported 141.9 ms/frame against a decoder logging 12-18 ms.
 /// Optimising against that number means optimising the fastest node in the
 /// graph.
 ///
 /// So each node is reported three ways, and the three together are what
 /// identify a cost:
 ///
 ///   - `exec_ms`  — cumulative wall time in the node, work *and* parked pushes
 ///   - `cpu_ms`   — thread CPU time (CLOCK_THREAD_CPUTIME_ID). Backpressure
 ///                  cannot inflate it, because a parked node holds no thread.
 ///   - `pressure` — mean fill of its input channels minus that of its outputs
 ///
 /// **`cpu_ms` cannot tell real work from a spinning GPU wait.** CUDA's default
 /// sync policy (`cudaDeviceScheduleAuto`) spin-waits before yielding, so
 /// `cudaStreamSynchronize` burns the calling thread's CPU while the GPU works.
 /// A node that is purely GPU-bound can therefore report a high `cpu_ms` and read
 /// as CPU-bound. `cudaSetDeviceFlags(cudaDeviceScheduleBlockingSync)` settles it
 /// in one line: if a node's `cpu_ms` collapses under blocking sync, that CPU was
 /// spin, not work.
 ///
 /// **`cpu_ms` counts one thread only.** `CLOCK_THREAD_CPUTIME_ID` is per-thread,
 /// and OpenCV here is built against TBB, so any node whose functor goes through
 /// `cv::parallel_for_` (histogram compare, `warpAffine`, colour conversion) has
 /// that work executed on TBB's arena — 19 workers on a 20-core box — and billed
 /// to those threads rather than to the node. Such a node reads *cheaper* than it
 /// is, and the difference shows up in `stall/f` instead, indistinguishable from a
 /// GPU wait. `exec_ms` does capture it, since the functor does not return until
 /// the parallel region joins: a node where `exec/f` greatly exceeds `cpu/f`
 /// while its output channel is empty is fanning out, not waiting.
 ///
 /// Work piles up *in front of* a bottleneck and starves everything *after* it,
 /// so `pressure` is maximal at the node setting the pace. `cpu_ms` then says
 /// which repair applies: high pressure with a saturated thread is CPU-bound and
 /// the work must get cheaper, while high pressure with an idle thread is
 /// waiting on a device, where batch size and engine precision are the knobs.
 ///
 /// Occupancy has to be sampled during the run. `current_fill` is instantaneous
 /// and every channel has drained by the time the network stops, so a single
 /// read at the end reports an idle pipeline however congested it was.
 ///
 /// Nothing here is specific to this pipeline's topology: the node graph is
 /// recovered from KPN's channel names, so it keeps working when the graph
 /// changes.
 #include <kpn/diagnostics.hpp>
 #include <nlohmann/json.hpp>
 #include <algorithm>
 #include <atomic>
 #include <chrono>
 #include <cstdint>
 #include <functional>
 #include <iomanip>
 #include <map>
 #include <ostream>
 #include <sstream>
 #include <string>
 #include <thread>
 #include <vector>
 namespace sae::bench {
 // ── Edge naming ──────────────────────────────────────────────────────────────
 /// TRACES: VR-015 | PR-004
 /// KPN names a channel "<src>:<idx> → <dst>:<idx>" (static_network.hpp).
 /// Recovering the two node names from it is what keeps attribution
 /// topology-agnostic: the graph is read back out of the channel names rather
 /// than hard-coded here, so a new node or a re-wired branch needs no change.
 /// Leaves both outputs untouched if the name does not carry an arrow.
 inline void split_edge_name(const std::string& name,
                            std::string& producer, std::string& consumer) {
    static const std::string kArrow = " \xe2\x86\x92 ";   // " → "
    const auto arrow = name.find(kArrow);
    if (arrow == std::string::npos) return;
    auto strip_port = [](std::string s) {
        const auto colon = s.rfind(':');
        return colon == std::string::npos ? s : s.substr(0, colon);
    };
    producer = strip_port(name.substr(0, arrow));
    consumer = strip_port(name.substr(arrow + kArrow.size()));
 }
 // ── Channel occupancy, time-averaged ─────────────────────────────────────────
 /// TRACES: VR-015 | PR-004
 /// One channel's fill level integrated over the run. `peak_fill` is already
 /// cumulative in `ChannelStats`, but a peak cannot distinguish "full once" from
 /// "full throughout", and those are opposite diagnoses. A mean can.
 struct ChannelOccupancy {
    std::string   name;            // "src:0 → dst:0", as KPN names it
    std::string   producer;        // node name left of the arrow
    std::string   consumer;        // node name right of the arrow
    std::size_t   capacity{0};
    std::uint64_t samples{0};
    double        fill_sum{0.0};
    std::uint64_t samples_full{0};
    std::uint64_t samples_empty{0};
    // Final-snapshot totals (monotonic counters, so the last read is the total).
    std::size_t   peak_fill{0};
    std::uint64_t pushes{0};
    std::uint64_t pops{0};
    std::uint64_t drops{0};
    std::uint64_t overflows{0};
    std::uint64_t bytes_pushed{0};
    double mean_fill()     const { return samples ? fill_sum / static_cast<double>(samples) : 0.0; }
    double mean_fill_pct() const { return capacity ? 100.0 * mean_fill() / static_cast<double>(capacity) : 0.0; }
    double peak_pct()      const { return capacity ? 100.0 * static_cast<double>(peak_fill) / static_cast<double>(capacity) : 0.0; }
    double full_pct()      const { return samples ? 100.0 * static_cast<double>(samples_full)  / static_cast<double>(samples) : 0.0; }
    double empty_pct()     const { return samples ? 100.0 * static_cast<double>(samples_empty) / static_cast<double>(samples) : 0.0; }
    double bandwidth_mbs(double wall_s) const {
        return wall_s > 0.0 ? static_cast<double>(bytes_pushed) / wall_s / 1e6 : 0.0;
    }
 };
 // ── Per-node attributed cost ─────────────────────────────────────────────────
 /// TRACES: VR-015 | PR-004
 struct NodeCost {
    std::string   name;
    std::uint64_t frames{0};
    // Cumulative wall time in the node — the answer to "where did the run go",
    // but only for a node that is not backpressured; it includes parked pushes.
    double exec_ms{0.0};
    double exec_ms_per_frame{0.0};   // true mean, not the EMA
    double exec_share{0.0};          // exec_ms / wall_ms, 0..1
    double ema_exec_ms{0.0};         // KPN's EMA, kept for continuity with the old report
    double max_exec_ms{0.0};
    // Thread CPU time: excludes sleeping, parking and waiting on a device, so it
    // is the one number backpressure cannot inflate.
    double cpu_ms{0.0};
    double cpu_ms_per_frame{0.0};
    double cpu_share{0.0};           // cpu_ms / wall_ms — thread saturation, 0..1
    double cpu_pct_of_pipeline{0.0}; // this node's share of all nodes' CPU time
    // Per frame, time inside the node not spent on its own CPU: parked on a
    // full output channel, or waiting on the GPU. `pressure` separates those —
    // a backpressured node has a full output, a device-bound one does not.
    double stall_ms_per_frame{0.0};
    // Queue occupancy either side of the node, in percent of capacity.
    double in_fill_pct{0.0};
    double out_fill_pct{0.0};
    double pressure{0.0};            // in − out; maximal at the pacing node
    bool   has_input{false};
    bool   has_output{false};
    double queue_wait_ms{0.0};
    bool   is_bottleneck{false};
    /// TRACES: VR-015 | AR-004 | PR-004
    /// Live scheduling state, so a wedged run says *why* it is wedged rather
    /// than only that it is. With `queued=0, wake=1` a wake was recorded and
    /// never consumed; with `queued=0, wake=0` and a full input, no wake was
    /// ever generated. Those are different bugs in different files.
    bool   queued{false};
    bool   wake_pending{false};
 };
 /// TRACES: VR-015 | PR-004
 /// Attribute cost to nodes from a KPN node snapshot plus sampled channel
 /// occupancy. Pure — no clocks, no threads, no network — so the ranking is
 /// unit-testable on CI hardware that can never run the pipeline itself.
 ///
 /// A node with several inputs takes the **minimum** input fill: it can only run
 /// once every input has data, so the emptiest one gates it, and a full sibling
 /// channel means that channel's producer is blocked rather than this node being
 /// slow. A node with several outputs takes the **maximum** output fill, since
 /// parking on any one branch stops the node.
 ///
 /// Terminals are the infinite-reservoir limit of the same rule: a source has
 /// unlimited work available (input treated as 100% full) and a sink unlimited
 /// drain (output treated as empty), so both stay rankable against the interior
 /// nodes instead of dropping out of the comparison.
 inline std::vector<NodeCost> attribute_cost(
    const std::vector<kpn::NodeSnapshot>&  nodes,
    const std::vector<ChannelOccupancy>&   channels,
    double                                 wall_sec)
 {
    const double wall_ms = wall_sec * 1000.0;
    double cpu_total = 0.0;
    for (const auto& n : nodes) cpu_total += n.total_cpu_ms;
    std::vector<NodeCost> out;
    out.reserve(nodes.size());
    for (const auto& n : nodes) {
        NodeCost c;
        c.name          = n.name;
        c.frames        = n.frames_processed;
        c.exec_ms       = n.total_exec_ms;
        c.ema_exec_ms   = n.ema_exec_ms;
        c.max_exec_ms   = n.max_exec_ms;
        c.cpu_ms        = n.total_cpu_ms;
        c.queue_wait_ms = n.queue_wait_ms;
        c.queued        = n.queued;
        c.wake_pending  = n.wake_pending;
        c.exec_ms_per_frame   = c.frames ? c.exec_ms / static_cast<double>(c.frames) : 0.0;
        c.cpu_ms_per_frame    = c.frames ? c.cpu_ms  / static_cast<double>(c.frames) : 0.0;
        c.exec_share          = wall_ms > 0.0 ? c.exec_ms / wall_ms : 0.0;
        c.cpu_share           = wall_ms > 0.0 ? c.cpu_ms  / wall_ms : 0.0;
        c.cpu_pct_of_pipeline = cpu_total > 0.0 ? 100.0 * c.cpu_ms / cpu_total : 0.0;
        c.stall_ms_per_frame  = c.exec_ms_per_frame - c.cpu_ms_per_frame;
        if (c.stall_ms_per_frame < 0.0) c.stall_ms_per_frame = 0.0;
        double in_min  = 0.0; bool have_in  = false;
        double out_max = 0.0; bool have_out = false;
        for (const auto& ch : channels) {
            if (ch.consumer == n.name) {
                const double f = ch.mean_fill_pct();
                if (!have_in || f < in_min) in_min = f;
                have_in = true;
            }
            if (ch.producer == n.name) {
                const double f = ch.mean_fill_pct();
                if (!have_out || f > out_max) out_max = f;
                have_out = true;
            }
        }
        c.has_input    = have_in;
        c.has_output   = have_out;
        c.in_fill_pct  = have_in  ? in_min  : 100.0;  // source: always has work
        c.out_fill_pct = have_out ? out_max :   0.0;  // sink: never blocks
        c.pressure     = c.in_fill_pct - c.out_fill_pct;
        out.push_back(std::move(c));
    }
    // Rank, but only among nodes that actually ran: a node with zero frames has
    // no cost to attribute and its neighbouring channels never moved.
    auto best = out.end();
    for (auto it = out.begin(); it != out.end(); ++it) {
        if (it->frames == 0) continue;
        if (best == out.end() || it->pressure > best->pressure) best = it;
    }
    if (best != out.end()) best->is_bottleneck = true;
    return out;
 }
 /// TRACES: VR-015 | PR-004
 /// One line of plain English about the winning node, since the point of the
 /// report is to say what to change next. A saturated thread means the node's
 /// own work is the limit; an idle thread under pressure means it is waiting on
 /// a device, and those are different repairs.
 inline std::string verdict(const std::vector<NodeCost>& costs) {
    for (const auto& c : costs) {
        if (!c.is_bottleneck) continue;
        std::ostringstream os;
        os << std::fixed << c.name << " sets the pace: ";
        // A source's 100% input is the infinite-reservoir convention, not a
        // measured queue — saying "work is backed up in front of it" would be
        // asserting something no counter observed.
        if (!c.has_input)
            os << "nothing downstream is waiting on it (output "
               << std::setprecision(1) << c.out_fill_pct
               << "% full), so the pipeline is running as fast as this node can feed it. ";
        else if (!c.has_output)
            os << std::setprecision(1) << c.in_fill_pct
               << "% full input and nothing to block on, so it is the drain. ";
        else
            os << std::setprecision(1) << c.in_fill_pct << "% full input, "
               << c.out_fill_pct << "% full output. ";
        os << std::setprecision(2) << c.cpu_ms_per_frame << " ms/frame on CPU. ";
        if (c.cpu_share >= 0.85)
            os << "CPU-bound — its thread is busy " << std::setprecision(0)
               << (100.0 * c.cpu_share) << "% of the run, so the work itself has to get"
                  " cheaper or be split across more threads.";
        else if (c.cpu_share <= 0.35 && c.stall_ms_per_frame > c.cpu_ms_per_frame)
            os << "Device-bound — its thread is busy only " << std::setprecision(0)
               << (100.0 * c.cpu_share) << "% of the run and it spends "
               << std::setprecision(2) << c.stall_ms_per_frame
               << " ms/frame off-CPU, so it is waiting on the GPU or the disk: batch size,"
                  " engine precision and the decode path are the knobs, not the C++.";
        else
            os << "Mixed — thread busy " << std::setprecision(0) << (100.0 * c.cpu_share)
               << "% of the run, " << std::setprecision(2) << c.stall_ms_per_frame
               << " ms/frame off-CPU.";
        return os.str();
    }
    return "no node processed a frame — nothing to attribute";
 }
 // ── Recorder ─────────────────────────────────────────────────────────────────
 /// TRACES: VR-015 | PR-004
 /// Samples the live network on a timer and emits the report at the end.
 ///
 /// The sampler only reads relaxed atomics, so it does not perturb what it
 /// measures — which matters, since this exists to be trusted as a timing
 /// measurement.
 class BenchmarkRecorder {
 public:
    using Sampler = std::function<kpn::NetworkSnapshot()>;
    explicit BenchmarkRecorder(int sample_interval_ms = 100)
        : interval_(std::chrono::milliseconds(sample_interval_ms)) {}
    ~BenchmarkRecorder() { stop(); }
    void start(Sampler sampler) {
        sampler_ = std::move(sampler);
        running_.store(true, std::memory_order_release);
        thread_ = std::thread([this] {
            while (running_.load(std::memory_order_acquire)) {
                accumulate(sampler_());
                std::this_thread::sleep_for(interval_);
            }
        });
    }
    /// Stops sampling and latches the final counter values. Call while the
    /// network object is still alive: the monotonic counters stay valid after
    /// `net.stop()`, but they die with the object.
    void stop() {
        if (!running_.exchange(false, std::memory_order_acq_rel)) return;
        if (thread_.joinable()) thread_.join();
        if (sampler_) {
            final_ = sampler_();
            // Occupancy is deliberately NOT accumulated from this last read:
            // the pipeline has drained by now, and folding an idle sample into
            // the mean biases every channel toward "never congested".
            for (const auto& ch : final_.channels) {
                auto& occ = occupancy_[ch.name];
                if (occ.name.empty()) {   // a channel that never moved
                    occ.name     = ch.name;
                    occ.capacity = ch.capacity;
                    split_edge_name(ch.name, occ.producer, occ.consumer);
                }
                occ.peak_fill    = ch.peak_fill;
                occ.pushes       = ch.pushes;
                occ.pops         = ch.pops;
                occ.drops        = ch.drops;
                occ.overflows    = ch.overflows;
                occ.bytes_pushed = ch.bytes_pushed;
            }
        }
        stopped_ = true;
    }
    bool   has_data() const { return stopped_ && !final_.nodes.empty(); }
    double wall_sec() const { return final_.elapsed_s; }
    std::vector<ChannelOccupancy> channels() const {
        std::vector<ChannelOccupancy> v;
        v.reserve(occupancy_.size());
        for (const auto& [_, occ] : occupancy_) v.push_back(occ);
        return v;
    }
    std::vector<NodeCost> costs() const {
        return attribute_cost(final_.nodes, channels(), final_.elapsed_s);
    }
    /// TRACES: VR-015 | PR-004
    /// Machine-readable report, for sweeping configurations and diffing runs.
    /// `film_sec` is the last timestamp the pipeline reached, so
    /// `realtime_factor` answers what the optimiser is really asking: seconds
    /// of film per second of wall clock. It is 0 for a topology with no result
    /// sink (the dump-only path), and the field is then omitted rather than
    /// reported as zero throughput.
    nlohmann::json to_json(const nlohmann::json& run_config, double film_sec) const {
        using nlohmann::json;
        const double wall  = final_.elapsed_s;
        const auto   chans = channels();
        const auto   cost  = attribute_cost(final_.nodes, chans, wall);
        json j;
        j["schema_version"] = 1;
        j["config"]         = run_config;
        json summary;
        summary["wall_sec"]           = wall;
        summary["sample_count"]       = sample_count_;
        summary["sample_interval_ms"] = interval_.count();
        if (film_sec > 0.0) {
            summary["film_sec"]        = film_sec;
            summary["realtime_factor"] = wall > 0.0 ? film_sec / wall : 0.0;
        }
        for (const auto& c : cost)
            if (c.is_bottleneck) { summary["bottleneck"] = c.name; break; }
        summary["verdict"] = verdict(cost);
        j["summary"] = summary;
        json jnodes = json::array();
        for (const auto& c : cost) {
            jnodes.push_back({
                {"name",                c.name},
                {"frames",              c.frames},
                {"fps",                 wall > 0.0 ? c.frames / wall : 0.0},
                {"exec_ms",             c.exec_ms},
                {"exec_ms_per_frame",   c.exec_ms_per_frame},
                {"exec_share",          c.exec_share},
                {"ema_exec_ms",         c.ema_exec_ms},
                {"max_exec_ms",         c.max_exec_ms},
                {"cpu_ms",              c.cpu_ms},
                {"cpu_ms_per_frame",    c.cpu_ms_per_frame},
                {"cpu_share",           c.cpu_share},
                {"cpu_pct_of_pipeline", c.cpu_pct_of_pipeline},
                {"stall_ms_per_frame",  c.stall_ms_per_frame},
                {"queue_wait_ms",       c.queue_wait_ms},
                {"in_fill_pct",         c.in_fill_pct},
                {"out_fill_pct",        c.out_fill_pct},
                {"pressure",            c.pressure},
                {"is_bottleneck",       c.is_bottleneck},
                {"queued",              c.queued},
                {"wake_pending",        c.wake_pending},
            });
        }
        j["nodes"] = std::move(jnodes);
        json jch = json::array();
        for (const auto& ch : chans) {
            jch.push_back({
                {"name",          ch.name},
                {"producer",      ch.producer},
                {"consumer",      ch.consumer},
                {"capacity",      ch.capacity},
                {"mean_fill",     ch.mean_fill()},
                {"mean_fill_pct", ch.mean_fill_pct()},
                {"peak_fill",     ch.peak_fill},
                {"peak_pct",      ch.peak_pct()},
                {"full_pct",      ch.full_pct()},
                {"empty_pct",     ch.empty_pct()},
                {"pushes",        ch.pushes},
                {"pops",          ch.pops},
                {"drops",         ch.drops},
                {"overflows",     ch.overflows},
                {"mb_per_sec",    ch.bandwidth_mbs(wall)},
            });
        }
        j["channels"] = std::move(jch);
        return j;
    }
    /// TRACES: VR-015 | PR-004
    /// Human-readable form of the same data, so a run is legible without
    /// opening the JSON.
    void print(std::ostream& os, double film_sec) const {
        print_impl(os, final_, film_sec);
    }
    /// TRACES: VR-015 | AR-004 | PR-004
    /// Dump the report from a LIVE snapshot, mid-run, without stopping anything.
    ///
    /// A report that only exists at shutdown is no use against the failure this
    /// pipeline actually has: a wedged run never reaches shutdown, so the one
    /// moment the numbers matter most is the one moment they were unavailable.
    /// Channel occupancy names the stalled node directly — it is the one whose
    /// input is full and whose output is empty — which is otherwise a debug-build
    /// and a gdb session away.
    ///
    /// Safe to call from the wait loop while the pipeline is running or hung: it
    /// takes the same lock-free snapshot the sampler does.
    void dump_live(std::ostream& os, double film_sec) const {
        if (!sampler_) { os << "[benchmark] no sampler — run with --benchmark\n"; return; }
        print_impl(os, sampler_(), film_sec);
    }
 private:
    void print_impl(std::ostream& os, const kpn::NetworkSnapshot& snap,
                    double film_sec) const {
        const double wall  = snap.elapsed_s;
        const auto   chans = channels();
        const auto   cost  = attribute_cost(snap.nodes, chans, wall);
        os << "\n┌─ Pipeline benchmark (VR-015) ──────────────────────────────────────────────\n";
        os << "│  wall " << std::fixed << std::setprecision(1) << wall << "s";
        if (film_sec > 0.0)
            os << "   film " << film_sec << "s   realtime x" << std::setprecision(2)
               << (wall > 0.0 ? film_sec / wall : 0.0);
        os << "   samples " << sample_count_ << "\n│\n";
        os << "│  node              frames     cpu_s  cpu%run  cpu%tot   cpu/f"
              "  exec/f  stall/f    in%   out%   press  q/w\n";
        for (const auto& c : cost) {
            os << "│  " << (c.is_bottleneck ? "▶ " : "  ") << std::left << std::setw(16)
               << c.name << std::right
               << std::setw(7) << c.frames
               << std::setw(10) << std::setprecision(1) << (c.cpu_ms / 1000.0)
               << std::setw(9)  << std::setprecision(0) << (100.0 * c.cpu_share)
               << std::setw(9)  << std::setprecision(0) << c.cpu_pct_of_pipeline
               << std::setw(8)  << std::setprecision(2) << c.cpu_ms_per_frame
               << std::setw(8)  << std::setprecision(2) << c.exec_ms_per_frame
               << std::setw(9)  << std::setprecision(2) << c.stall_ms_per_frame
               << std::setw(7)  << std::setprecision(0) << c.in_fill_pct
               << std::setw(7)  << std::setprecision(0) << c.out_fill_pct
               << std::setw(8)  << std::setprecision(1) << c.pressure
               << "  " << int(c.queued) << "/" << int(c.wake_pending)
               << "\n";
        }
        /// TRACES: VR-015 | AR-004 | PR-004
        // Fires only when the scheduling state is actually wrong, so a healthy
        // run stays quiet and a wedged one names the fault — instead of leaving
        // it to be reconstructed under a debugger that suppresses the bug.
        for (const auto& c : cost) {
            if (c.queued || !c.has_input) continue;
            if (c.wake_pending)
                os << "│  !! " << c.name << " idle with a wake outstanding"
                      " (queued=0 wake=1): the wake was recorded and never"
                      " consumed — submit/release handshake.\n";
            else if (c.in_fill_pct > 50.0)
                os << "│  !! " << c.name << " idle with a "
                   << std::setprecision(0) << c.in_fill_pct
                   << "% full input and no wake pending: the wake was never"
                      " generated — channel edge detection.\n";
        }
        os << "│\n│  channel                              cap  mean%  peak%  full%"
              " empty%     MB/s\n";
        for (const auto& ch : chans) {
            os << "│  " << std::left << std::setw(36) << ch.name << std::right
               << std::setw(5) << ch.capacity
               << std::setw(7) << std::setprecision(1) << ch.mean_fill_pct()
               << std::setw(7) << ch.peak_pct()
               << std::setw(7) << ch.full_pct()
               << std::setw(7) << ch.empty_pct()
               << std::setw(9) << std::setprecision(1) << ch.bandwidth_mbs(wall)
               << "\n";
        }
        os << "│\n│  " << verdict(cost) << "\n";
        os << "└────────────────────────────────────────────────────────────────────────────\n";
        os << "  cpu_s / cpu%tot is where the run's compute actually went. exec/f is wall\n"
              "  time in the node INCLUDING time parked on a full output channel, so it\n"
              "  overstates a backpressured node — compare it against cpu/f, which cannot\n"
              "  be inflated that way. press = input fill − output fill, and locates the\n"
              "  node that work is queueing up in front of.\n"
              "  cpu_s counts THIS node's thread only: work OpenCV fans out via TBB is\n"
              "  billed to the TBB arena, so a node using cv::parallel_for_ reads cheaper\n"
              "  than it is and the difference surfaces in stall/f.\n";
    }
 private:
    void accumulate(const kpn::NetworkSnapshot& snap) {
        ++sample_count_;
        for (const auto& ch : snap.channels) {
            auto& occ = occupancy_[ch.name];
            if (occ.name.empty()) {
                occ.name     = ch.name;
                occ.capacity = ch.capacity;
                split_edge_name(ch.name, occ.producer, occ.consumer);
            }
            occ.fill_sum += static_cast<double>(ch.current_fill);
            ++occ.samples;
            if (ch.capacity && ch.current_fill >= ch.capacity) ++occ.samples_full;
            if (ch.current_fill == 0)                          ++occ.samples_empty;
        }
    }
    std::chrono::milliseconds               interval_;
    Sampler                                 sampler_;
    std::thread                             thread_;
    std::atomic<bool>                       running_{false};
    bool                                    stopped_{false};
    std::uint64_t                           sample_count_{0};
    std::map<std::string, ChannelOccupancy> occupancy_;
    kpn::NetworkSnapshot                    final_{};
 };
 } // namespace sae::bench
@@ -18,8 +18,6 @@
 //   --nms <f>           NMS IoU threshold (default: 0.4)
 #include "gallery/gallery_builder.hpp"
 #include "gallery/gallery_report.hpp"
 #include "gallery/gallery_calibration.hpp"
 #include "gallery/gallery_store.hpp"
 #include "config.hpp"
@@ -34,7 +32,6 @@ int main(int argc, char** argv) {
    std::string arcface_model  = kDefaultArcfaceModel;
    float conf = 0.5f, nms_thr = 0.4f;
    int   max_side = 500;
    float min_face_px = 0.f;
    for (int i = 1; i < argc; ++i) {
        auto arg  = [&](const char* f) { return std::strcmp(argv[i], f) == 0; };
@@ -51,7 +48,6 @@ int main(int argc, char** argv) {
            else if (arg("--conf"))      conf           = std::stof(next());
            else if (arg("--nms"))       nms_thr        = std::stof(next());
            else if (arg("--max-side"))  max_side       = std::stoi(next());
            else if (arg("--min-face-px")) min_face_px = std::stof(next());
            else { std::cerr << "[warn] unknown flag: " << argv[i] << "\n"; }
        } catch (const std::exception& e) {
            std::cerr << "Error: " << e.what() << "\n";
@@ -61,8 +57,7 @@ int main(int argc, char** argv) {
    if (root_path.empty() || output_path.empty()) {
        std::cerr << "Usage: build_gallery --root <dir> --output <gallery.json> "
-                     "[--detector <path>] [--arcface <path>] [--max-side <N>]\n"
+                     "[--detector <path>] [--arcface <path>] [--max-side <N>]\n";
                     "       [--min-face-px <px>]\n";
        return 1;
    }
@@ -73,7 +68,6 @@ int main(int argc, char** argv) {
    cfg.detector_conf  = conf;
    cfg.detector_nms   = nms_thr;
    cfg.max_side       = max_side;
    cfg.min_face_px    = min_face_px;
    try {
        ActorGallery gallery = build_gallery(cfg);
@@ -83,30 +77,6 @@ int main(int argc, char** argv) {
        }
        save_gallery(output_path, gallery);
        std::cerr << "Gallery saved to: " << output_path << "\n";
        /// TRACES: GR-003 | SR-001
        // Fit the calibration here and persist what it learned. The matcher
        // fits the same sigmoid at analysis time, but that is the wrong place
        // to audit a gallery from: by then the answer is per-run and nobody is
        // looking. Build time is when the gallery's quality is decided, and a
        // gallery can be quietly bad — heavily overlapping intra/inter
        // distributions, actors with no usable image — while looking fine.
        std::vector<Embedding> flat;
        std::vector<int>       flat_actor;
        for (int ai = 0; ai < static_cast<int>(gallery.actors.size()); ++ai)
            for (const auto& e : gallery.actors[ai].embeddings) {
                flat.push_back(e);
                flat_actor.push_back(ai);
            }
        GalleryCalibrationStats stats;
        GalleryCalibration cal = calibrate_gallery(flat, flat_actor, &stats);
        const GalleryReport report =
            build_gallery_report(gallery, cal, stats, nullptr, output_path);
        const std::string report_path = gallery_report_path(output_path);
        save_gallery_report(report_path, report);
        std::cerr << "Gallery report saved to: " << report_path << "\n";
    } catch (const std::exception& e) {
        std::cerr << "Fatal: " << e.what() << "\n";
        return 1;
@@ -11,32 +11,12 @@ enum class Verbosity {
    standard,  // per-frame detail: bbox, similarity, unknowns logged
    xray,      // Jellyfin-Xray format: {"second": ["Actor", ...], ...}
 };
 // How a track's accepted frames become a reported presence window.
 enum class PresenceMode {
    // A claim IS its track's [first_seen, last_seen] (AR-012/AR-013). The
    // default and the only mode whose semantics the register validated.
    track_extent,
    // Flood-fill: snap each claim to the shot it sits in, so an actor seen once
    // anywhere in a scene is reported for the whole scene [prev_boundary,
    // next_boundary]. Trades precision for recall against X-Ray's per-scene cast
    // granularity. Snaps to TransNetV2 shot boundaries (is_scene_boundary) when a
    // scene detector populated them, else to the always-on histogram cuts
    // (is_cut). With no boundaries at all it degrades to track_extent per claim.
    flood,
 };
 // debug verbosity = compile with -DSAE_DEBUG → scene_analyze_debug binary
 struct Config {
    // ── Input ─────────────────────────────────────────────────────────────────
    std::string movie_path;
-    std::string gallery_path;
+    std::string gallery_path;    // gallery.json produced by build_gallery
    // TRACES: IR-002 | SR-003
    // "global" (matched against the whole library) or "limited" (this title's
    // credited cast only). The strongest single quality signal when two
    // manifests compete for the same cut: identical gallery_size can mean very
    // different recall depending on which was used.
    std::string gallery_scope{"global"};    // gallery.json produced by build_gallery
    // ── Output ───────────────────────────────────────────────────────────────
    std::string output_path;     // annotations.json
@@ -46,14 +26,6 @@ struct Config {
    // scripts/optimizer/SCHEMA.md) for offline threshold-sweep replay via sae_kpn.
    std::string dump_embeddings_path;
    /// TRACES: VR-015 | PR-004
    // When set, write a per-node timing and bottleneck report here (src/
    // benchmark.hpp) and print it at shutdown. Costs one background thread
    // reading relaxed atomics on a timer, so it is safe to leave on, but a
    // measurement run should still be isolated (nothing else on the GPU).
    std::string benchmark_path;
    int         benchmark_interval_ms{100};   // channel-occupancy sampling period
    // ── Sampling ─────────────────────────────────────────────────────────────
    float  sample_fps{1.0f};     // frames to analyse per second of movie
    float  max_decode_fps{0.f};  // wall-clock cap on source decode rate (0 = uncapped)
@@ -63,75 +35,25 @@ struct Config {
    // ── Detection (SCRFD-500MF via cv::dnn::Net) ──────────────────────────────
    std::string detector_model;
    std::string detector_engine;       // optional path to pre-built TRT engine; bypasses ORT
-    // TRACES: AR-003 | SR-002
+    int         max_faces{10};         // pipeline cap: keep only the N largest faces
    // 0 = no cap, the default. A fixed cap discards the SMALLEST faces first,
    // which are exactly the background cast X-Ray still credits with scene
    // membership. Per-frame cost is contained by backpressure (AR-004) rather
    // than by throwing work away. Set >0 only to bound a pathological source.
    int         max_faces{0};
    float       min_face_px{40.f};    // discard detections narrower or shorter than this
    float       detector_conf{0.5f};
    float       detector_nms{0.4f};
    /// TRACES: GR-004 | SR-001
    // Gallery ↔ embedder binding. A gallery built with a different model than the
    // one loaded here is a hard error, always. This flag additionally promotes
    // "cannot prove they match" (unstamped legacy gallery, or a name-only match
    // because the ONNX could not be hashed) from a loud warning to a hard error.
    // Also settable via SAE_REQUIRE_GALLERY_STAMP=1. Measurement runs want it on.
    bool require_gallery_stamp{false};   // --require-gallery-stamp
    // ── Recognition (ArcFace ONNX) ────────────────────────────────────────────
    std::string arcface_model;
    std::string arcface_engine;        // optional path to a pre-built TRT engine; bypasses ORT
    int         embed_batch_size{4};    // max faces per ORT Run() call — bounds per-call latency
    float       match_prior{0.5f};        // base-rate prior; 0.5 = use calibrated sigmoid directly
-    // Tuned by Differential Evolution against Amazon X-Ray per-second presence
+    // prob_threshold tuned by Differential Evolution against Amazon X-Ray per-scene
-    // over the 4-film rep4 matrix. Best model+mode: LVFace-B_Glint360K, full
+    // presence over 4 films, per-second metric (see docs/rep4-optimizer-results.md).
-    // gallery, expansion on. Supersedes an earlier 9-film scene-union tuning
+    // Best model+mode: LVFace-B_Glint360K, full gallery, expansion on. Supersedes the
-    // (0.76); that metric hid out-of-cast false positives.
+    // earlier 9-film scene-union-metric tuning (0.76) — that metric is now known to
-    //
+    // have hidden out-of-cast false positives (see docs/optimizer-experiments.md).
    // **Read the provenance before trusting the value.** Two things about it:
    //
    // 1. The document it came from no longer exists under that name. It was
    //    docs/rep4-optimizer-results.md, renamed to docs/model-bakeoff.md and
    //    then rewritten (0bd2747). This comment pointed at the dead path for
    //    long enough that the number looked unsourced. The original is still
    //    readable at `git show d340da7:docs/rep4-optimizer-results.md`, where
    //    the shipped triple appears as
    //    `prob_threshold=0.754, anneal_sec=35.5`.
    //
    // 2. **0.754 predates a scoring bug fix and was never re-derived.** That
    //    same rewrite reports finding "a real scoring bug in optimize.py: a
    //    candidate whose hardest film's replay timed out was averaged over
    //    survivors instead of penalized, silently rewarding partial coverage.
    //    Affected 3 of 16 training combos". The corrected sweep converged
    //    somewhere else — the surviving document records anneal_sec=59.2,
    //    extinction_sec=59.2 against the 35.5/57.4 shipped alongside this
    //    threshold — and no corrected prob_threshold is recorded anywhere.
    //    (The other two constants are now withdrawn outright, which is why
    //    only this one still matters.)
    //
    // The doc is also candid that the optimum "generalizes unevenly — strong on
    // 3 of 5 held-out films, badly broken on 2 (one with a 974-count misID
    // blowup)", and that it is shipped anyway because it still beats the old
    // defaults on average. That is a defensible call and not a settled,
    // film-agnostic optimum; it should be visible here rather than only in a
    // document this comment used to point at incorrectly.
    float       prob_threshold{0.754f};   // posterior P(match | sim, prior) threshold
-    // TRACES: AR-024 | SR-002
+    float       match_threshold{0.45f};   // cosine distance hard ceiling fallback (no calibration)
-    // match_threshold (0.45), match_ratio (0.80) and match_ratio_ceil (0.65) are
+    float       match_ratio{0.80f};       // ratio test fallback: accept if best/second < ratio
-    // RETIRED, joining track_max_embed_dist, cut_revive_sim, expand_novelty_sim
+    float       match_ratio_ceil{0.65f};  // ratio test only fires below this absolute distance
    // and expand_track_spread_max. All were raw cosine distances, and they were
    // the accept rule whenever the calibration fit failed — so the one situation
    // in which the pipeline knew its probabilities were untrustworthy was the
    // one in which it stopped using them. An unfitted sigmoid is now the
    // fallback everywhere, which is at least the same wrong number in every
    // stage. See identity_matcher_node.hpp.
    // ── Presence derivation ──────────────────────────────────────────────────
    // How accepted frames become a reported window. flood requires scene_detect.
    PresenceMode presence_mode{PresenceMode::track_extent};
    // ── Cut detection ────────────────────────────────────────────────────────
    float cut_threshold{0.70f};         // grayscale histogram correlation below this → hard cut
@@ -150,100 +72,47 @@ struct Config {
                                            //    at ~0.50; real boundaries spike to ~0.7+)
    int         scene_stride{50};           // frames advanced between windows (≤ kWindow)
-    // Dense-decode knobs (only active with scene_detect). Dense decode of every
+    // Dense-decode throughput knobs (only active with scene_detect). Dense decode
-    // native-rate frame is the pipeline's cost driver, which is what made the
+    // of every native-rate frame is the pipeline's cost driver; these trade a
-    // temporal shortcut below tempting.
+    // little boundary precision for a large speedup.
-    /// TRACES: AR-011 | SR-002
+    //   scene_decode_fps: rate the source decodes at in dense mode. Lower =
-    //   scene_decode_fps: rate the source decodes at in dense mode.
+    //     fewer frames decoded. TransNetV2 tolerates ~12fps; boundary timestamps
-    //     **0 = native, and native is the only correct setting.** kWindow is 100
+    //     stay correct (keyed off each frame's real timestamp). 0 = native fps.
    //     frames: at native 25 fps that window spans ~4 s, which is what
    //     TransNetV2 was trained on; at the 12 fps this used to default to it
    //     spans ~8.3 s, so the model saw half-speed motion over twice its
    //     temporal context. Boundary *timestamps* stay right either way — which
    //     is exactly why the degradation was invisible, and why the compressed
    //     separation it produced (~0.50 baseline against ~0.7+ peaks) was read
    //     as a property of the export rather than of the input. Lowering this
    //     buys decode time by running the model off-distribution; reach for
    //     dense_scale or scene_stride instead, which do not.
    //   dense_scale: downscale factor applied to decoded frames in dense mode
    //     (0<f≤1; e.g. 0.5 = half size). Cheaper sws_scale + smaller frames
-    //     through the fanout. A spatial reduction, and TransNetV2 downsamples to
+    //     through the fanout. NOTE: also shrinks what the face detector sees —
-    //     48×27 regardless, so unlike the above it is a documented, understood
+    //     keep ≥0.5 on 1080p sources so SCRFD still resolves small faces. 1 = off.
-    //     degradation. NOTE: also shrinks what the face detector sees — keep
+    float       scene_decode_fps{12.0f};    // dense decode rate (0 = native)
    //     ≥0.5 on 1080p sources so SCRFD still resolves small faces. 1 = off.
    float       scene_decode_fps{0.f};      // dense decode rate (0 = native)
    float       dense_scale{1.0f};          // dense-mode frame downscale (1 = off)
    // ── Face tracking (frame-to-frame) ───────────────────────────────────────
-    /// TRACES: AR-007, AR-008, AR-024 | SR-002
+    float track_alpha{0.4f};            // cost weight: 0=embedding only, 1=spatial only
    // track_alpha is the *base* weight, used on ordinary frames. It is
    // frame-dependent (AR-007): on is_cut / is_scene_boundary, and for any track
    // that is no longer on screen, it drops to 0 (embedding only), because
    // position carries no information across a viewpoint change or a gap.
    float track_alpha{0.4f};            // base cost weight: 0=embedding only, 1=spatial only
    float track_min_iou{0.1f};          // IoU below which spatial link alone is rejected
-    // Minimum P(same person) for an association to be admissible on appearance
+    float track_max_embed_dist{0.7f};   // cosine dist above which embedding link alone is rejected
-    // alone. This replaces track_max_embed_dist (a raw cosine distance, AR-024).
+    int   track_max_frames_missing{5};  // expire track after N consecutive missed frames
    // 0.5 is not a tuned constant: it is the decision boundary. Below it the pair
    // is more likely two people than one, and no amount of IoU makes that a link
    // worth asserting on identity grounds.
    float track_assoc_min_prob{0.5f};
    // How long a track that has gone off screen stays available for association
    // before the registry reaps it and emits its presence claim (AR-013).
    // Replaces track_max_frames_missing: a frame count silently changed meaning
    // with sample_fps, and the same number had to be guessed twice (once for an
    // ordinary miss, once for a cut). Seconds mean one thing at any sample rate.
    double track_extinction_sec{5.0};
-    // ── Ownership and evidence accumulation (AR-025) ──────────────────────────
+    // ── Cross-cut track re-association ────────────────────────────────────────
-    // TRACES: AR-025, AR-017 | SR-002
+    // A camera-angle change (Frame::is_cut) breaks spatial (IoU) continuity but
-    // These four decided how presence is claimed and were unreachable: they
+    // not identity: the same people are usually still on screen from a new angle.
-    // lived as in-class initialisers on TrackRegistry::Config and
+    // Instead of destroying tracks on a cut, the tracker parks them in an
-    // EvidenceDiscounter::Config, and main constructed the discounter with the
+    // inactive pool. A post-cut detection whose raw cosine similarity to a parked
-    // one-argument constructor, so nothing short of a recompile could move
+    // track's last-frame embedding is ≥ cut_revive_sim revives that track_id
-    // them. rho_max's own comment defers to "the sweep (VR-007)" for where it
+    // (identity continuity survives the cut); otherwise it starts a fresh track.
-    // belongs — a sweep that could not reach it.
+    // Parked tracks that go unrevived for cut_inactive_max_frames are dropped.
-    //
+    float cut_revive_sim{0.50f};        // min raw cosine sim (last-frame emb) to revive across a cut
-    // ownership_logodds is arguably the most consequential constant in the
+    int   cut_inactive_max_frames{5};   // drop a parked track after N frames without revival
    // pipeline after prob_threshold: below it a track produces no presence
    // claim at all, so it decides whether an actor is reported rather than how
    // confidently. 2.0 is a posterior of ~0.88. Unswept.
    float  ownership_logodds{2.0f};
    // How much a single observation may move a track's belief. n_eff =
    // n / (1 + (n-1)·rho), so rho_max caps what a repeated view can ever be
    // worth: 0.5 caps it at two independent observations however long the shot
    // runs. It is deliberately below 1 — a held pose still yields a fresh
    // detection, alignment and noise realisation, so a little independent
    // evidence survives. Setting it to 1 freezes belief after the first frame,
    // which is the bug this replaced.
    float  evidence_rho_max{0.5f};
    // P(same view) below this and the observation counts as a genuinely new
    // look, so it joins the per-track view set.
    float  evidence_admit_below{0.6f};
    // Distinct views remembered per track, which bounds the novelty comparison.
    int    evidence_max_views{8};
    // ── Scene tracking ────────────────────────────────────────────────────────
-    // TRACES: AR-012, AR-013 | SR-002
+    // extinction_sec re-tuned by DE against X-Ray per-second presence, 4-film rep4
-    // extinction_sec (57.4) and anneal_sec (35.5) are GONE, along with
+    // matrix (docs/rep4-optimizer-results.md). Reverses the earlier "short is better"
-    // SceneTrackerFunc, which is what read the first of them. docs/SPEC.md
+    // finding: with a stricter prob_threshold, a long extinction window bridges real
-    // specified this removal and ended it "grep for both names and expect no
+    // presence gaps (occlusion, turned face) instead of just smearing FPs — every
-    // survivors"; there were about forty, and the register meanwhile recorded
+    // model's best config pushed to ~90%+ of the search ceiling (tried up to 60s).
-    // both as Withdrawn and "deleted rather than retained at zero" on the
+    // The ceiling kept getting hit, so treat 60 as "good enough", not a proven optimum.
-    // grounds that a field naming a mechanism the pipeline no longer has is
+    double extinction_sec{57.4};  // keep actor active this many seconds after last detection
-    // actively misleading.
+    // anneal_sec: previously found INSENSITIVE at a 1–30s range; the wider rep4 sweep
-    //
+    // (1–60s) also pushed this to the ceiling alongside extinction_sec (see above).
-    // Both existed to bridge gaps between isolated accepted frames. A track
+    double anneal_sec{35.5};      // merge actor windows separated by less than this into one epoch
    // that survives its own gaps leaves them nothing to do: AR-012 makes a
    // window the extent of a track an actor owns, and AR-013 ends it at the
    // last sighting. The keep-alive answered the same question again and
    // answered it worse, by re-opening exactly the trailing cool-down AR-013
    // refuses.
    //
    // track_extinction_sec above is NOT the same knob under a new name. It
    // bounds how long a lost track stays available for re-association, which is
    // a tracking question; it never extends a presence claim.
    // ── Per-film gallery expansion ────────────────────────────────────────────
    // Within one uncut track every face is the same physical person — a free
@@ -252,26 +121,16 @@ struct Config {
    // new reference views; they are promoted into a per-film, in-memory annex so
    // later frames/tracks of that actor at similar poses recognise. See
    // gallery/track_gallery.hpp.
-    // Default ON: the rep4 matrix (docs/model-bakeoff.md, "Two effects in
+    // Default ON: rep4 matrix (docs/rep4-optimizer-results.md) found expansion helps
-    // isolation") found expansion helps recall on the full (unrestricted)
+    // recall on the full (unrestricted) gallery for the winning model/mode — the
-    // gallery for the winning model/mode — the opposite of the earlier
+    // opposite of the earlier assumption that it only helps restricted galleries.
    // assumption that it only helps restricted galleries. The same section is
    // explicit that on the full gallery it buys +2.1pp F1 and +3.9pp recall
    // "at a real cost" in misIDs, where in restricted mode it is a clean win.
    bool   expand_gallery{true};         // master switch
    int    expand_buffer_size{20};       // per-track diversity buffer capacity
-    // TRACES: AR-018, AR-024 | SR-005
+    float  expand_novelty_sim{0.55f};    // promote only embeddings whose best sim to the
-    // Banded admission for the per-subject store, in PROBABILITY space. An
+                                         //   actor's refs is below this (gallery-far / novel)
-    // embedding joins only if P(same person) against something already stored
+    float  expand_track_spread_max{0.60f}; // reject promotion if the retained buffer's
-    // lands inside [lo, hi]: above hi it is redundant, below lo it is evidence
+                                           //   internal spread (1 - min pairwise sim) exceeds
-    // the track is not one person. The same lo is re-applied to the whole store
+                                           //   this — guards track-ID collisions / two people
    // at promotion time — see track_gallery.hpp. This is the only threshold the
    // expansion path has: it replaces the raw-cosine expand_novelty_sim (0.55)
    // and expand_track_spread_max (0.60), which are retired (AR-024).
    // Working values pending VR-007; sweep both bounds, they fail in opposite
    // directions.
    float  expand_band_lo{0.90f};
    float  expand_band_hi{0.95f};
    int    expand_min_anchor_frames{3};  // require ≥N accepted frames naming the actor before
                                         //   the track is confirmed and its buffer promoted
    std::string expand_debug_dir;        // if set, dump promoted mugshots + embeddings here
@@ -8,12 +8,6 @@
 // gallery file needed. Purpose-built for the optimizer's replay corpus and the
 // embedding-model bake-off (dump each --arcface model over the film set).
 //
 // The camera-position (histogram) cut detector runs, so frames/is_cut is recorded
 // in the dump. Flood-fill presence snaps to those cuts. TransNetV2 scene detection
 // is NOT run here: on the ROCm build it needs MIGraphX, whose statically-linked
 // LLVM collides with the VAAPI decoder's system libLLVM and crashes at compile, so
 // the two cannot share a process. is_scene_boundary therefore stays 0 here.
 //
 // Usage:
 //   dump_embeddings --movie <path> --out <dump.h5> [--arcface <model.onnx>]
 //                   [--detector <model.onnx>] [--fps 1] [--start S] [--end S]
@@ -25,25 +25,11 @@
 // expected to contain exactly one subject).  A warning is printed to stderr
 // when more than one face is found.
 //
 // --all-faces emits every detection instead, which is what a caller analysing
 // a frame rather than a gallery portrait needs:
 //   [ { "image": "frame.png",
 //       "faces": [ {"bbox": [...], "landmarks": [[x,y] x5],
 //                   "confidence": 0.89, "embedding": [...]} , ... ] } ]
 //
 // --calibration <gallery> additionally emits the gallery's fitted Platt
 // sigmoid, so a non-Python client can turn a similarity into P(match) with the
 // same parameters the C++ matcher uses.  Output becomes
 // {"calibration": {...}, "images": [...]}.  Clients must score through it:
 // AR-024 requires the calibrated probability, never a bare cosine — a raw
 // threshold means something different for every model, gallery and face size.
 //
 // This binary is intentionally a thin wrapper around the same ONNX models
 // used by scene_analyze, so embeddings are guaranteed compatible.
 #include "config.hpp"
 #include "face_utils.hpp"
 #include "gallery/gallery_store.hpp"
 #include "inference/face_detector.hpp"
 #include "inference/face_embedder.hpp"
@@ -114,77 +100,6 @@ static void save_debug(const std::string& dir,
    cv::imwrite(dir + "/" + stem + "_aligned.jpg",   aligned);
 }
 // ── Process one image, keeping every detection ────────────────────────────────
 // The --all-faces path. Same detect → align → embed chain as process() below,
 // but without the highest-confidence reduction: a frame legitimately contains
 // several people, and dropping all but one is a gallery-portrait assumption.
 // Faces that fail alignment are reported with a null embedding rather than
 // silently dropped, so a caller can count what the detector found against what
 // survived the ArcFace warp.
 struct MultiFaceResult {
    std::string             image_path;
    std::string             error;      // set only when the image itself failed
    std::vector<FaceResult> faces;
 };
 static MultiFaceResult process_all(
    const std::string& path,
    const std::function<std::vector<DetectedFace>(const cv::Mat&)>& detect,
    const std::function<Embedding(const cv::Mat&)>& embed_one,
    int                max_side,
    const std::string& debug_dir = "") {
    MultiFaceResult out;
    out.image_path = path;
    cv::Mat img = cv::imread(path);
    if (img.empty()) {
        out.error = "cannot read image";
        return out;
    }
    if (max_side > 0) {
        const int big = std::max(img.cols, img.rows);
        if (big > max_side) {
            const double s = static_cast<double>(max_side) / big;
            cv::resize(img, img, {}, s, s, cv::INTER_AREA);
        }
    }
    std::vector<DetectedFace> faces = detect(img);
    if (faces.empty()) {
        cv::Mat enhanced = enhance_for_retry(img);
        faces = detect(enhanced);
        if (!faces.empty())
            img = enhanced;
    }
    if (faces.empty()) {
        out.error = "no face detected";
        return out;
    }
    for (const auto& face : faces) {
        FaceResult r;
        r.image_path = path;
        r.confidence = face.confidence;
        r.bbox[0] = face.bbox.x;      r.bbox[1] = face.bbox.y;
        r.bbox[2] = face.bbox.width;  r.bbox[3] = face.bbox.height;
        r.landmarks = face.landmarks;
        cv::Mat crop = align_face(img, face.landmarks);
        if (crop.empty()) {
            r.error = "alignment failed";
        } else {
            r.ok        = true;
            r.embedding = embed_one(crop);
            if (!debug_dir.empty())
                save_debug(debug_dir, path, img, face, crop);
        }
        out.faces.push_back(std::move(r));
    }
    return out;
 }
 // ── Process one image ─────────────────────────────────────────────────────────
 static FaceResult process(const std::string& path,
@@ -262,8 +177,6 @@ int main(int argc, char** argv) {
    std::string arcface_model  = kDefaultArcfaceModel;
    std::string arcface_engine;
    std::string debug_dir;
    std::string calibration_gallery;
    bool  all_faces = false;
    float conf = 0.5f, nms = 0.4f;
    int   max_side = 500;
    std::vector<std::string> images;
@@ -277,16 +190,13 @@ int main(int argc, char** argv) {
        else if (std::strcmp(argv[i], "--nms")        == 0 && i+1 < argc) { nms  = std::stof(argv[++i]); }
        else if (std::strcmp(argv[i], "--save-debug") == 0 && i+1 < argc) { debug_dir = argv[++i]; }
        else if (std::strcmp(argv[i], "--max-side")   == 0 && i+1 < argc) { max_side = std::stoi(argv[++i]); }
        else if (std::strcmp(argv[i], "--calibration")== 0 && i+1 < argc) { calibration_gallery = argv[++i]; }
        else if (std::strcmp(argv[i], "--all-faces")  == 0) { all_faces = true; }
        else if (argv[i][0] != '-') { images.push_back(argv[i]); }
        else { std::cerr << "[warn] unknown flag: " << argv[i] << "\n"; }
    }
    if (images.empty()) {
        std::cerr << "Usage: embed_faces [--detector <path>] [--arcface <path>] "
-                     "[--save-debug <dir>] [--max-side <N>] [--all-faces] "
+                     "[--save-debug <dir>] [--max-side <N>] image1.jpg ...\n";
                     "[--calibration <gallery>] image1.jpg ...\n";
        return 1;
    }
@@ -307,78 +217,31 @@ int main(int argc, char** argv) {
    std::function<Embedding(const cv::Mat&)> embed_one =
        [&](const cv::Mat& c) { return embedder->embed_one(c); };
    // One face's fields, shared by both output shapes.
    auto face_json = [](const FaceResult& r) {
        json f;
        f["confidence"] = r.confidence;
        f["bbox"]       = {r.bbox[0], r.bbox[1], r.bbox[2], r.bbox[3]};
        json lms = json::array();
        for (const auto& pt : r.landmarks) lms.push_back({pt.x, pt.y});
        f["landmarks"] = std::move(lms);
        if (r.ok) f["embedding"] = std::vector<float>(r.embedding.begin(),
                                                      r.embedding.end());
        else    { f["embedding"] = nullptr; f["error"] = r.error; }
        return f;
    };
    // Process images and build JSON output
-    json images_out = json::array();
+    json output = json::array();
    for (const auto& path : images) {
        std::cerr << "[embed_faces] " << path << "\n";
        FaceResult res = process(path, detect, embed_one, max_side, debug_dir);
        json entry;
-        entry["image"] = path;
+        entry["image"] = res.image_path;
        if (all_faces) {
            MultiFaceResult res = process_all(path, detect, embed_one, max_side, debug_dir);
            if (!res.error.empty()) {
                entry["faces"] = json::array();
                entry["error"] = res.error;
                std::cerr << "  [skip] " << res.error << "\n";
            } else {
                json faces = json::array();
                for (const auto& f : res.faces) faces.push_back(face_json(f));
                entry["faces"] = std::move(faces);
            }
        } else {
            FaceResult res = process(path, detect, embed_one, max_side, debug_dir);
        if (res.ok) {
-                entry.merge_patch(face_json(res));
+            entry["embedding"]  = std::vector<float>(res.embedding.begin(),
                                                     res.embedding.end());
            entry["confidence"] = res.confidence;
            entry["bbox"]       = {res.bbox[0], res.bbox[1], res.bbox[2], res.bbox[3]};
            json lms = json::array();
            for (const auto& pt : res.landmarks) lms.push_back({pt.x, pt.y});
            entry["landmarks"]  = std::move(lms);
        } else {
            entry["embedding"] = nullptr;
            entry["error"]     = res.error;
            std::cerr << "  [skip] " << res.error << "\n";
        }
-        }
+        output.push_back(std::move(entry));
        images_out.push_back(std::move(entry));
    }
-    // Without --calibration the output stays a bare array, unchanged, so
+    std::cout << output.dump() << "\n";
    // existing callers (build_gallery, fetch_missing_actors) are unaffected.
    if (calibration_gallery.empty()) {
        std::cout << images_out.dump() << "\n";
        return 0;
    }
    ActorGallery gallery = load_gallery(calibration_gallery);
    if (!gallery.calib_valid)
        std::cerr << "[warn] " << calibration_gallery
                  << " carries no valid calibration; a client cannot convert a "
                     "similarity to a probability from it (AR-024)\n";
    json out;
    out["calibration"] = {
        {"a",     gallery.calib_a},
        {"b",     gallery.calib_b},
        {"valid", gallery.calib_valid},
        {"form",  "P(match) = 1/(1+exp(-(a*similarity + b + log_prior_odds)))"},
        {"note",  "Score through this. AR-024: a bare cosine threshold means "
                  "something different for every model, gallery and face size. "
                  "log_prior_odds = log(p0/(1-p0)) for a base-rate prior p0; use "
                  "0 for association (are these two faces one person)."},
    };
    out["images"] = std::move(images_out);
    std::cout << out.dump() << "\n";
    return 0;
 }
@@ -1,131 +0,0 @@
 #pragma once
 /// TRACES: AR-024, AR-025 | SR-002
 ///
 /// EvidenceDiscounter — how much a single observation is allowed to move a
 /// track's belief.
 ///
 /// **The independence problem.** Per-frame identity evidence is accumulated as
 /// log-odds along a track (AR-025), which is only valid for *independent*
 /// observations. Consecutive frames of one track are nothing of the kind: near
 /// identical pose, lighting and expression. Treating them as independent drives
 /// the posterior to certainty on what is effectively one measurement — thirty
 /// frames of the same face at the same angle is not thirty pieces of evidence.
 ///
 /// The mitigation is to weight each observation by how much it *adds*: a view
 /// the track has already contributed is discounted toward zero, a genuinely new
 /// pose counts in full. This reuses the same judgement the diversity buffer
 /// makes for gallery expansion (AR-019) — which embeddings on a track are
 /// mutually distinct — rather than inventing a second notion of novelty.
 ///
 /// Owned by TrackRegistry rather than left to callers. A caller that forgot to
 /// discount, or applied it twice, would silently produce confident wrong
 /// answers, and the registry is the one place where all evidence converges.
 ///
 /// **Similarity enters as a calibrated probability, never a raw cosine**
 /// (AR-024): "is this the same view" is a decision, and a bare cosine threshold
 /// means something different for every model and every face size.
 #include "types.hpp"
 #include <algorithm>
 #include <cmath>
 #include <functional>
 #include <vector>
 class EvidenceDiscounter {
 public:
    /// cosine similarity → P(same view). Supplied by the caller so the
    /// calibration fitted for the active embedder is used (AR-023/AR-024).
    using Calibrate = std::function<float(float)>;
    struct Config {
        int   max_views{8};        ///< distinct views remembered per track
        float admit_below{0.6f};   ///< P(same view) under this ⇒ a new view
        /// Ceiling on the correlation between two observations of one track.
        ///
        /// This is what bounds the accumulation. `n_eff = n / (1 + (n-1)·rho)`
        /// tends to `1/rho` as `n` grows, so `rho_max` sets how much a single
        /// repeated view can ever be worth: 0.5 caps it at two observations,
        /// no matter how long the shot runs.
        ///
        /// 0.5 caps a repeated view at two independent observations' worth,
        /// which is what lets a track the matcher accepts on frame after frame
        /// actually become owned. Higher values starve ownership; the sweep
        /// (VR-007) decides where it belongs.
        ///
        /// It is capped below 1 deliberately. P(same view) near 1 says the two
        /// crops look alike; it does not say the second carries no information.
        /// A fresh frame is a fresh detection, a fresh alignment and a fresh
        /// noise realisation, so a little independent evidence survives even a
        /// perfectly held pose. Setting this to 1 recovers the original bug —
        /// belief frozen after the first frame.
        float rho_max{0.5f};
    };
    // Two constructors rather than a defaulted argument: `Config{}` as a default
    // argument would reference Config's own member initializers before the
    // enclosing class is complete, which is ill-formed.
    explicit EvidenceDiscounter(Calibrate cal)
        : cal_(std::move(cal)), cfg_() {}
    EvidenceDiscounter(Calibrate cal, Config cfg)
        : cal_(std::move(cal)), cfg_(cfg) {}
    /// The marginal evidence one observation adds, in units of independent
    /// observations.
    ///
    /// Each frame is a Bayesian update, so confidence must keep growing — but
    /// correlated observations must grow it less, and must not grow it without
    /// bound. The standard treatment is **effective sample size**:
    ///
    ///     n_eff(n) = n / (1 + (n-1)·rho)
    ///
    /// and this returns `n_eff(n) - n_eff(n-1)`, the gain from *this* frame.
    /// The shape is right at both ends: with rho = 0 every frame counts fully
    /// and the belief accumulates linearly, while as rho rises the series
    /// converges on `1/rho` and a held pose stops adding no matter how long it
    /// is held.
    ///
    /// The two failure modes it sits between are both real and both were hit:
    /// a weight of 0 for repeats froze the belief after one frame, so a track
    /// recognised on 318 frames was owned on none; a constant floor grew it
    /// linearly forever, so a long shot could out-argue genuinely varied
    /// evidence purely by lasting longer.
    ///
    /// `rho` is estimated from P(same view) against the closest stored view,
    /// capped by `rho_max`. The first observation has nothing to be redundant
    /// with and counts in full.
    /// `n_seen` is the count of observations already folded into THIS track.
    /// It is a parameter rather than discounter state because one discounter
    /// serves every track: holding the count internally would pool unrelated
    /// tracks into one effective sample, so a busy film would silently discount
    /// each track by how many others happened to be on screen.
    float weight(std::vector<Embedding>& views, int n_seen, const Embedding& e) const {
        if (views.empty()) {
            views.push_back(e);
            return 1.0f;
        }
        float p_same = 0.0f;
        for (const auto& v : views)
            p_same = std::max(p_same, cal_(cosine_similarity(v, e)));
        const float rho = std::min(cfg_.rho_max, std::max(0.0f, p_same));
        const float n_prev = static_cast<float>(std::max(1, n_seen));
        const float n_now  = n_prev + 1.0f;
        auto n_eff = [rho](float n) { return n / (1.0f + (n - 1.0f) * rho); };
        const float w = std::max(0.0f, n_eff(n_now) - n_eff(n_prev));
        if (p_same < cfg_.admit_below &&
            static_cast<int>(views.size()) < cfg_.max_views) {
            views.push_back(e);
        }
        return w;
    }
 private:
    Calibrate cal_;
    Config    cfg_;
 };
@@ -112,25 +112,6 @@ public:
        return res;
    }
    // ── Stage accessors ──────────────────────────────────────────────────────
    // embed_mat() above is the whole detect→align→embed chain, which is the
    // right entry point for embedding a gallery image. Studies that need to
    // intervene between the stages — swapping the landmark source, degrading a
    // crop before it reaches the embedder — drive these instead, so they still
    // exercise the shipped detector, alignment and embedder rather than a
    // re-implementation of them.
    std::vector<DetectedFace> detect(const cv::Mat& img) { return detector_->detect(img); }
    Embedding embed_crop(const cv::Mat& crop) { return embedder_->embed_one(crop); }
    // Batched form. A study embedding thousands of crops one at a time pays the
    // per-call overhead thousands of times over; the backend already batches.
    std::vector<Embedding> embed_crops(const std::vector<cv::Mat>& crops) {
        return embedder_->embed(crops);
    }
    int max_batch() const { return embedder_->max_batch(); }
 private:
    std::unique_ptr<IFaceDetector>   detector_;
    std::unique_ptr<IFaceEmbedder>   embedder_;
@@ -1,238 +1,29 @@
 #pragma once
 /// TRACES: AR-005, AR-029, AR-030 | SR-002
 #include "types.hpp"
-#include <opencv2/core.hpp>
+#include <opencv2/calib3d.hpp>
 #include <opencv2/imgproc.hpp>
 #include <cmath>
 // ── umeyama_similarity ────────────────────────────────────────────────────────
 // Closed-form least-squares similarity transform (rotation + uniform scale +
 // translation, 4 DoF) mapping `src` onto `dst`, by Umeyama's solution.
 //
 // This is the estimator InsightFace aligns with — skimage's SimilarityTransform
 // is `_umeyama(..., estimate_scale=True)` — and therefore the one that produced
 // the crops ArcFace and LVFace were *trained* on. The canonical warp is part of
 // the input distribution, not a free implementation choice (AR-011).
 //
 // Deliberately **not** `cv::estimateAffinePartial2D(..., cv::RANSAC)`:
 //
 //   - A robust estimator earns a small residual by discarding the points that
 //     disagree with the model. On a turned face those are precisely the
 //     foreshortened landmarks — the pose signal AR-030 exists to measure. RANSAC
 //     would suppress exactly the quantity we want to read.
 //   - With five points and a two-point minimal sample there is almost no
 //     redundancy, so it cannot distinguish a mis-detected landmark from honest
 //     out-of-plane rotation. The robustness is nominal.
 //   - It is RNG-driven (`cv::theRNG()` is thread-local); this is exact, so
 //     replay determinism stops depending on thread scheduling.
 //
 // Returns an empty Mat when the source points are degenerate (all coincident).
 inline cv::Mat umeyama_similarity(const std::array<cv::Point2f, 5>& src,
                                  const std::array<cv::Point2f, 5>& dst) {
    constexpr int N = 5;
    double mu_sx = 0, mu_sy = 0, mu_dx = 0, mu_dy = 0;
    for (int i = 0; i < N; ++i) {
        mu_sx += src[i].x; mu_sy += src[i].y;
        mu_dx += dst[i].x; mu_dy += dst[i].y;
    }
    mu_sx /= N; mu_sy /= N; mu_dx /= N; mu_dy /= N;
    // var_src and the cross-covariance Σ = (1/N) Σ (d - μ_d)(s - μ_s)ᵀ
    double var_s = 0;
    cv::Matx22d sigma = cv::Matx22d::zeros();
    for (int i = 0; i < N; ++i) {
        const double sx = src[i].x - mu_sx, sy = src[i].y - mu_sy;
        const double dx = dst[i].x - mu_dx, dy = dst[i].y - mu_dy;
        var_s += sx * sx + sy * sy;
        sigma(0, 0) += dx * sx; sigma(0, 1) += dx * sy;
        sigma(1, 0) += dy * sx; sigma(1, 1) += dy * sy;
    }
    var_s /= N;
    sigma *= 1.0 / N;
    if (var_s < 1e-12) return {};   // every source point coincides — no scale
    cv::Mat w, u, vt;
    cv::SVD::compute(cv::Mat(sigma), w, u, vt, cv::SVD::FULL_UV);
    const cv::Matx22d U (u.at<double>(0,0),  u.at<double>(0,1),
                         u.at<double>(1,0),  u.at<double>(1,1));
    const cv::Matx22d Vt(vt.at<double>(0,0), vt.at<double>(0,1),
                         vt.at<double>(1,0), vt.at<double>(1,1));
    // A similarity may rotate but never mirror: if the fit came out
    // orientation-reversing, flip the least-significant singular direction.
    cv::Matx22d S = cv::Matx22d::eye();
    if (cv::determinant(U) * cv::determinant(Vt) < 0) S(1, 1) = -1;
    const cv::Matx22d R = U * S * Vt;
    const double c = (w.at<double>(0) * S(0,0) + w.at<double>(1) * S(1,1)) / var_s;
    cv::Mat M(2, 3, CV_64F);
    M.at<double>(0,0) = c * R(0,0); M.at<double>(0,1) = c * R(0,1);
    M.at<double>(1,0) = c * R(1,0); M.at<double>(1,1) = c * R(1,1);
    M.at<double>(0,2) = mu_dx - c * (R(0,0) * mu_sx + R(0,1) * mu_sy);
    M.at<double>(1,2) = mu_dy - c * (R(1,0) * mu_sx + R(1,1) * mu_sy);
    return M;
 }
 // ── Alignment ─────────────────────────────────────────────────────────────────
 // The 5-point fit, plus what it could not explain.
 //
 // `residual` is the RMS landmark error in **canonical 112×112 pixels** after the
 // best similarity fit. Two properties make it the AR-030 visibility measure:
 //
 //   - The similarity transform absorbs rotation, uniform scale and translation
 //     exactly, so the residual is by construction the part of the deformation a
 //     similarity *cannot* explain — out-of-plane rotation and foreshortening,
 //     plus landmark noise. In-plane roll contributes nothing. The "roll must not
 //     read as yaw" failure is excluded structurally rather than by tuning.
 //   - The destination frame is fixed, so a 40 px face and a 400 px face are both
 //     measured in the same canonical space. The measure cannot silently
 //     re-express face size (already AR-002's job) the way a raw-pixel one would.
 //
 // It also responds to occlusion and to plainly broken landmark sets, which a
 // yaw-angle estimator by construction does not.
 struct Alignment {
    cv::Mat M;               ///< 2×3 CV_64F: source pixels → canonical 112×112
    float   residual{0.f};   ///< RMS canonical-pixel error; 0 ⇒ a perfect fit
    bool    ok{false};       ///< false ⇒ degenerate landmarks, no transform
 };
 /// Fit the canonical ArcFace template to `landmarks` and report the misfit.
 inline Alignment estimate_alignment(const std::array<cv::Point2f, 5>& landmarks) {
    std::array<cv::Point2f, 5> dst;
    for (int i = 0; i < 5; ++i) dst[i] = {kArcFaceRef[i][0], kArcFaceRef[i][1]};
    Alignment a;
    a.M = umeyama_similarity(landmarks, dst);
    if (a.M.empty()) return a;
    double sq = 0;
    for (int i = 0; i < 5; ++i) {
        const double x = a.M.at<double>(0,0) * landmarks[i].x
                       + a.M.at<double>(0,1) * landmarks[i].y + a.M.at<double>(0,2);
        const double y = a.M.at<double>(1,0) * landmarks[i].x
                       + a.M.at<double>(1,1) * landmarks[i].y + a.M.at<double>(1,2);
        const double ex = x - dst[i].x, ey = y - dst[i].y;
        sq += ex * ex + ey * ey;
    }
    a.residual = static_cast<float>(std::sqrt(sq / 5.0));
    a.ok = true;
    return a;
 }
 // ── align_face ────────────────────────────────────────────────────────────────
 // Produces a 112×112 BGR crop using the ArcFace 5-point similarity transform.
-// Returns an empty Mat if the fit fails (degenerate detection). When
+// Returns an empty Mat if the affine fit fails (degenerate detection).
 // `residual_out` is non-null it receives the AR-030 misfit for the same fit —
 // free, since the transform has already been computed.
 inline cv::Mat align_face(const cv::Mat& img,
-                          const std::array<cv::Point2f, 5>& landmarks,
+                           const std::array<cv::Point2f, 5>& landmarks) {
-                          float* residual_out = nullptr) {
+    std::vector<cv::Point2f> src(landmarks.begin(), landmarks.end());
-    const Alignment a = estimate_alignment(landmarks);
+    std::vector<cv::Point2f> dst(5);
-    if (!a.ok) return {};
+    for (int i = 0; i < 5; ++i) dst[i] = {kArcFaceRef[i][0], kArcFaceRef[i][1]};
-    if (residual_out) *residual_out = a.residual;
+
    cv::Mat M = cv::estimateAffinePartial2D(src, dst, cv::noArray(), cv::RANSAC, 3.0);
    if (M.empty()) return {};
    cv::Mat crop;
-    cv::warpAffine(img, crop, a.M, {112, 112},
+    cv::warpAffine(img, crop, M, {112, 112},
                   cv::INTER_LINEAR, cv::BORDER_CONSTANT, {0, 0, 0});
    return crop;
 }
 // ── crop_sharpness ────────────────────────────────────────────────────────────
 /// TRACES: AR-029 | SR-002
 //
 // Normalised variance of the Laplacian over the aligned 112×112 crop: the AR-029
 // sharpness axis. Returns -1 for an empty crop (unscored), matching the
 // DetectedFace sentinel.
 //
 //     sharpness = Var(∇²I) / Var(I)
 //
 // Two normalisations, each removing a quantity that would otherwise be read as
 // blur:
 //
 //   - **Divided by the image variance, so contrast cannot leak in.** Scaling
 //     intensity by α scales the Laplacian by α too, so both variances scale by α²
 //     and the ratio is unchanged. A raw Var(∇²I) — the textbook measure — instead
 //     falls with exposure, so a dim scene reads as soft and a graded-up one as
 //     sharp. VR-012 has to locate one knee across films whose grading differs by
 //     more than their focus does; an uncalibrated measure would put the knee in a
 //     different place per film, which is the AR-024 failure in another metric.
 //   - **Measured on the aligned crop, so size cannot leak in.** The destination
 //     frame is fixed at 112×112 (AR-002 owns size, and double-counting it here
 //     would make every small face read as blurred). What the ratio reports is the
 //     detail actually present in the embedder's input — so a small sharp face can
 //     and does outscore a large soft one. That is the claim; it is *not* a claim
 //     of invariance to source resolution, because a 40 px face warped up to 112
 //     genuinely carries less detail, and hiding that would defeat the point.
 //
 // Frequency-domain reading of why the blur ladder is monotone: with
 // Var(∇²I) = ∫|ω|⁴|F(ω)|² and Var(I) = ∫|F(ω)|², the ratio is E[|ω|⁴] under the
 // image's own spectral measure. Gaussian blur multiplies that measure by
 // e^{-σ²|ω|²}, concentrating it at low |ω|, so the expectation falls strictly
 // with σ. It is a property of the construction, not a fitted behaviour.
 //
 // **Three known hazards, for VR-012 to check rather than for a threshold to
 // absorb.** All are recorded here because they are properties of the measure,
 // visible in the dumped distribution, and neither should be papered over by a
 // correction chosen before that distribution has been looked at.
 //
 //   1. **Border fill.** `align_face` warps with BORDER_CONSTANT, so a face
 //      crossing the frame edge brings a hard black step into the crop, and a
 //      step edge is high-frequency. The normalisation blunts it — the fill
 //      inflates Var(I) as well as Var(∇²I) — but does not remove it, so
 //      heavily-cropped faces may read sharper than they are. The fix is either a
 //      validity mask or a different border mode, and the second changes what the
 //      embedder is fed (AR-011).
 //
 //   2. **The contrast invariance is exact in the algebra and approximate in
 //      8 bits.** Scaling I by α cancels exactly; what does not cancel is the
 //      quantisation floor of a stored crop, which is broadband and so lands in
 //      the numerator. It matters only where there is little signal left to
 //      compete with it: on the AR-029 test texture a half-contrast copy reads
 //      0.9% high when sharp, 24% high at sigma 1.2 and 148% high at sigma 2.5.
 //      A crop that is both **dim and soft therefore reads sharper than it is** —
 //      the low corner of the axis, and the corner VR-012 must put a knee in.
 //
 //   3. **It reports where the energy sits, not how much there is.** A crop whose
 //      energy is *already* concentrated at high frequency — dense film grain,
 //      a face against foliage — loses numerator and denominator together under
 //      blur, so the ratio moves less than the damage does. Measured on a
 //      flat-spectrum synthetic, an anisotropic (motion) smear even makes it rise,
 //      because the surviving perpendicular detail really is as fine as before.
 //      Natural crops have the low-frequency mass that keeps the denominator
 //      steady, and on those both ladders fall (see the AR-029 tests, which use a
 //      1/f texture for exactly this reason). The same property means the axis
 //      conflates focus with intrinsic texture — a bearded face outscores a smooth
 //      one at equal focus — which is true of every no-reference sharpness measure
 //      and is why AR-028 carries the number instead of thresholding on it.
 inline float crop_sharpness(const cv::Mat& crop) {
    if (crop.empty()) return -1.f;
    cv::Mat gray;
    if (crop.channels() == 3) cv::cvtColor(crop, gray, cv::COLOR_BGR2GRAY);
    else                      gray = crop;
    cv::Mat lap;
    cv::Laplacian(gray, lap, CV_32F, 3);
    cv::Scalar mean_i, sd_i, mean_l, sd_l;
    cv::meanStdDev(gray, mean_i, sd_i);
    cv::meanStdDev(lap,  mean_l, sd_l);
    const double var_i = sd_i[0] * sd_i[0];
    // A flat crop has no detail to be sharp or soft about, and the ratio is 0/0.
    // Zero is the honest answer and keeps the axis finite; -1 would claim the
    // face was never scored, which is a different fact.
    if (var_i < 1e-6) return 0.f;
    return static_cast<float>((sd_l[0] * sd_l[0]) / var_i);
 }
 // ── enhance_for_retry ────────────────────────────────────────────────────────
 // Used when initial face detection finds nothing. Pads the image by 50%
 // (border-replicated, so the detector doesn't see a hard edge) and applies
@@ -1,326 +0,0 @@
 /// TRACES: GR-004 | SR-001
 #include "embedder_stamp.hpp"
 #include "types.hpp"
 #include <algorithm>
 #include <cstdlib>
 #include <cstring>
 #include <filesystem>
 #include <fstream>
 #include <iostream>
 #include <map>
 #include <mutex>
 #include <sstream>
 #include <stdexcept>
 #include <vector>
 namespace fs = std::filesystem;
 // ── SHA-256 (FIPS 180-4) ──────────────────────────────────────────────────────
 // Self-contained rather than pulled from OpenSSL: the gallery library already
 // links OpenCV, HDF5, FFmpeg and a GPU backend, and the unit tests deliberately
 // link none of those crypto stacks. ~80 lines of table-driven code is cheaper
 // than another find_package that CI has to satisfy on an Intel N100.
 namespace {
 struct Sha256 {
    uint32_t h[8] = {0x6a09e667u, 0xbb67ae85u, 0x3c6ef372u, 0xa54ff53au,
                     0x510e527fu, 0x9b05688cu, 0x1f83d9abu, 0x5be0cd19u};
    uint64_t len = 0;
    uint8_t  buf[64]{};
    size_t   buf_n = 0;
    static uint32_t ror(uint32_t x, int n) { return (x >> n) | (x << (32 - n)); }
    void block(const uint8_t* p) {
        static const uint32_t k[64] = {
            0x428a2f98u,0x71374491u,0xb5c0fbcfu,0xe9b5dba5u,0x3956c25bu,0x59f111f1u,
            0x923f82a4u,0xab1c5ed5u,0xd807aa98u,0x12835b01u,0x243185beu,0x550c7dc3u,
            0x72be5d74u,0x80deb1feu,0x9bdc06a7u,0xc19bf174u,0xe49b69c1u,0xefbe4786u,
            0x0fc19dc6u,0x240ca1ccu,0x2de92c6fu,0x4a7484aau,0x5cb0a9dcu,0x76f988dau,
            0x983e5152u,0xa831c66du,0xb00327c8u,0xbf597fc7u,0xc6e00bf3u,0xd5a79147u,
            0x06ca6351u,0x14292967u,0x27b70a85u,0x2e1b2138u,0x4d2c6dfcu,0x53380d13u,
            0x650a7354u,0x766a0abbu,0x81c2c92eu,0x92722c85u,0xa2bfe8a1u,0xa81a664bu,
            0xc24b8b70u,0xc76c51a3u,0xd192e819u,0xd6990624u,0xf40e3585u,0x106aa070u,
            0x19a4c116u,0x1e376c08u,0x2748774cu,0x34b0bcb5u,0x391c0cb3u,0x4ed8aa4au,
            0x5b9cca4fu,0x682e6ff3u,0x748f82eeu,0x78a5636fu,0x84c87814u,0x8cc70208u,
            0x90befffau,0xa4506cebu,0xbef9a3f7u,0xc67178f2u};
        uint32_t w[64];
        for (int i = 0; i < 16; ++i)
            w[i] = (uint32_t(p[i * 4]) << 24) | (uint32_t(p[i * 4 + 1]) << 16) |
                   (uint32_t(p[i * 4 + 2]) << 8) | uint32_t(p[i * 4 + 3]);
        for (int i = 16; i < 64; ++i) {
            uint32_t s0 = ror(w[i - 15], 7) ^ ror(w[i - 15], 18) ^ (w[i - 15] >> 3);
            uint32_t s1 = ror(w[i - 2], 17) ^ ror(w[i - 2], 19) ^ (w[i - 2] >> 10);
            w[i] = w[i - 16] + s0 + w[i - 7] + s1;
        }
        uint32_t a = h[0], b = h[1], c = h[2], d = h[3];
        uint32_t e = h[4], f = h[5], g = h[6], hh = h[7];
        for (int i = 0; i < 64; ++i) {
            uint32_t S1 = ror(e, 6) ^ ror(e, 11) ^ ror(e, 25);
            uint32_t ch = (e & f) ^ (~e & g);
            uint32_t t1 = hh + S1 + ch + k[i] + w[i];
            uint32_t S0 = ror(a, 2) ^ ror(a, 13) ^ ror(a, 22);
            uint32_t mj = (a & b) ^ (a & c) ^ (b & c);
            uint32_t t2 = S0 + mj;
            hh = g; g = f; f = e; e = d + t1;
            d = c; c = b; b = a; a = t1 + t2;
        }
        h[0] += a; h[1] += b; h[2] += c; h[3] += d;
        h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
    }
    void update(const uint8_t* p, size_t n) {
        len += n;
        while (n) {
            size_t take = std::min(n, size_t(64) - buf_n);
            std::memcpy(buf + buf_n, p, take);
            buf_n += take; p += take; n -= take;
            if (buf_n == 64) { block(buf); buf_n = 0; }
        }
    }
    std::string hex() {
        uint64_t bits = len * 8;
        uint8_t pad = 0x80;
        update(&pad, 1);
        uint8_t zero = 0;
        while (buf_n != 56) update(&zero, 1);
        uint8_t tail[8];
        for (int i = 0; i < 8; ++i) tail[i] = uint8_t(bits >> (56 - i * 8));
        // update() would re-count these into len, but len is already frozen in bits.
        std::memcpy(buf + buf_n, tail, 8);
        block(buf);
        buf_n = 0;
        static const char* d = "0123456789abcdef";
        std::string out;
        out.reserve(64);
        for (int i = 0; i < 8; ++i)
            for (int s = 28; s >= 0; s -= 4)
                out += d[(h[i] >> s) & 0xF];
        return out;
    }
 };
 // (path, mtime, size) → digest. Hashing a 250 MB ONNX is cheap but not free, and
 // the optimizer constructs many networks in one process against the same model.
 std::mutex                                  g_hash_mu;
 std::map<std::string, std::string>          g_hash_cache;
 std::string short_hash(const std::string& hex) {
    return hex.size() > 12 ? hex.substr(0, 12) + "…" : hex;
 }
 }  // namespace
 std::string sha256_hex(const std::string& bytes) {
    Sha256 s;
    s.update(reinterpret_cast<const uint8_t*>(bytes.data()), bytes.size());
    return s.hex();
 }
 std::string sha256_file_hex(const std::string& path) {
    if (path.empty()) return "";
    std::error_code ec;
    auto size  = fs::file_size(path, ec);
    if (ec) return "";
    auto mtime = fs::last_write_time(path, ec);
    if (ec) return "";
    std::ostringstream key;
    key << path << '|' << size << '|'
        << mtime.time_since_epoch().count();
    {
        std::lock_guard<std::mutex> lk(g_hash_mu);
        auto it = g_hash_cache.find(key.str());
        if (it != g_hash_cache.end()) return it->second;
    }
    std::ifstream f(path, std::ios::binary);
    if (!f) return "";
    Sha256 s;
    std::vector<char> chunk(1 << 20);
    while (f) {
        f.read(chunk.data(), static_cast<std::streamsize>(chunk.size()));
        std::streamsize got = f.gcount();
        if (got > 0) s.update(reinterpret_cast<const uint8_t*>(chunk.data()),
                              static_cast<size_t>(got));
    }
    std::string hex = s.hex();
    std::lock_guard<std::mutex> lk(g_hash_mu);
    g_hash_cache[key.str()] = hex;
    return hex;
 }
 // ── EmbedderStamp ─────────────────────────────────────────────────────────────
 std::string EmbedderStamp::describe() const {
    std::string name = model_name.empty() ? "<unnamed model>" : model_name;
    if (model_sha256.empty())
        return name + " (sha256 unavailable)";
    return name + " (sha256 " + short_hash(model_sha256) + ")";
 }
 EmbedderStamp make_embedder_stamp(const std::string& model_path) {
    EmbedderStamp s;
    if (model_path.empty()) return s;
    s.model_name   = fs::path(model_path).filename().string();
    s.model_sha256 = sha256_file_hex(model_path);
    if (s.model_sha256.empty())
        std::cerr << "[gallery] cannot hash embedder model " << model_path
                  << " — model binding falls back to filename only (GR-004)\n";
    return s;
 }
 bool require_gallery_stamp_from_env() {
    const char* v = std::getenv("SAE_REQUIRE_GALLERY_STAMP");
    return v && *v && std::strcmp(v, "0") != 0;
 }
 // ── Comparison ────────────────────────────────────────────────────────────────
 StampCheck compare_embedder_stamps(const EmbedderStamp& built_with,
                                   const EmbedderStamp& loading_with,
                                   const std::string&   gallery_desc,
                                   const std::string&   embedder_desc) {
    StampCheck out;
    std::ostringstream m;
    // The gallery predates GR-004 (or was written by a tool that does not stamp).
    if (built_with.empty()) {
        out.verdict = StampVerdict::unstamped;
        m << "gallery '" << gallery_desc << "' carries no embedder stamp (GR-004).\n"
          << "  gallery was built with : UNKNOWN — this file predates model binding\n"
          << "  embedder now loaded    : " << loading_with.describe()
          << "  [" << embedder_desc << "]\n"
          << "  If these are not the same model every similarity from this run is\n"
          << "  meaningless but will look plausible. Rebuild or re-stamp the gallery\n"
          << "  (scripts/stamp_gallery.py), or run with SAE_REQUIRE_GALLERY_STAMP=1 to\n"
          << "  make this a hard error.";
        out.message = m.str();
        return out;
    }
    // Gallery is stamped but we cannot say what is about to embed.
    if (loading_with.empty()) {
        out.verdict = StampVerdict::unknown_embedder;
        m << "cannot identify the embedder being used against gallery '"
          << gallery_desc << "' (GR-004).\n"
          << "  gallery was built with : " << built_with.describe() << "\n"
          << "  embedder now loaded    : UNKNOWN [" << embedder_desc << "]\n"
          << "  The binding cannot be checked, so it is not being checked.";
        out.message = m.str();
        return out;
    }
    const bool have_both_hashes =
        !built_with.model_sha256.empty() && !loading_with.model_sha256.empty();
    // Embedding width disagreeing is a mismatch on its own terms — different
    // spaces entirely, and it will not even be caught by a cosine that "looks fine".
    if (built_with.embed_dim != loading_with.embed_dim) {
        out.verdict = StampVerdict::mismatch;
        m << "gallery/embedder MODEL MISMATCH — refusing to run (GR-004).\n"
          << "  gallery was built with : " << built_with.describe()
          << ", dim=" << built_with.embed_dim << "  [" << gallery_desc << "]\n"
          << "  embedder now loaded    : " << loading_with.describe()
          << ", dim=" << loading_with.embed_dim << "  [" << embedder_desc << "]\n"
          << "  Embedding dimensions differ; these are not the same space.";
        out.message = m.str();
        return out;
    }
    if (have_both_hashes) {
        if (built_with.model_sha256 == loading_with.model_sha256) {
            out.verdict = StampVerdict::match;
            m << "embedder binding verified: " << built_with.describe();
            if (built_with.model_name != loading_with.model_name)
                m << " (gallery recorded it as '" << built_with.model_name
                  << "', loaded from '" << loading_with.model_name
                  << "' — same bytes, renamed file)";
            out.message = m.str();
            return out;
        }
        out.verdict = StampVerdict::mismatch;
        m << "gallery/embedder MODEL MISMATCH — refusing to run (GR-004).\n"
          << "  gallery was built with : " << built_with.model_name
          << "  sha256=" << built_with.model_sha256 << "\n"
          << "                           [" << gallery_desc << "]\n"
          << "  embedder now loaded    : " << loading_with.model_name
          << "  sha256=" << loading_with.model_sha256 << "\n"
          << "                           [" << embedder_desc << "]\n"
          << "  Cosine similarities between embeddings from different models are\n"
          << "  meaningless but look plausible. Rebuild the gallery with the loaded\n"
          << "  model, or point the embedder at the model the gallery was built with.";
        out.message = m.str();
        return out;
    }
    // One side has no hash (e.g. a TRT deployment with the .onnx absent). Names
    // are all we have; agreeing on them is evidence, not proof.
    if (!built_with.model_name.empty() &&
        built_with.model_name == loading_with.model_name) {
        out.verdict = StampVerdict::weak_match;
        m << "embedder binding UNPROVEN for gallery '" << gallery_desc << "' (GR-004).\n"
          << "  gallery was built with : " << built_with.describe() << "\n"
          << "  embedder now loaded    : " << loading_with.describe()
          << "  [" << embedder_desc << "]\n"
          << "  Filenames agree but at least one SHA-256 is unavailable, so an\n"
          << "  in-place re-export under the same name would not be detected.";
        out.message = m.str();
        return out;
    }
    out.verdict = StampVerdict::mismatch;
    m << "gallery/embedder MODEL MISMATCH — refusing to run (GR-004).\n"
      << "  gallery was built with : " << built_with.describe()
      << "  [" << gallery_desc << "]\n"
      << "  embedder now loaded    : " << loading_with.describe()
      << "  [" << embedder_desc << "]\n"
      << "  Cosine similarities between embeddings from different models are\n"
      << "  meaningless but look plausible. Rebuild the gallery with the loaded\n"
      << "  model, or point the embedder at the model the gallery was built with.";
    out.message = m.str();
    return out;
 }
 void enforce_embedder_stamp(const EmbedderStamp& built_with,
                            const EmbedderStamp& loading_with,
                            const std::string&   gallery_desc,
                            const std::string&   embedder_desc,
                            bool                 require_stamp) {
    const bool strict = require_stamp || require_gallery_stamp_from_env();
    StampCheck chk = compare_embedder_stamps(built_with, loading_with,
                                             gallery_desc, embedder_desc);
    if (chk.fatal(strict)) {
        if (chk.verdict != StampVerdict::mismatch)
            throw std::runtime_error(chk.message +
                "\n  (fatal because SAE_REQUIRE_GALLERY_STAMP / --require-gallery-stamp is set)");
        throw std::runtime_error(chk.message);
    }
    if (chk.verdict == StampVerdict::match) {
        std::cerr << "[gallery] " << chk.message << "\n";
    } else {
        std::cerr << "\n[gallery] ***** WARNING (GR-004) *****\n"
                  << chk.message << "\n"
                  << "[gallery] ****************************\n\n";
    }
 }
 void verify_gallery_embedder(const ActorGallery& gallery,
                             const std::string&  gallery_path,
                             const std::string&  arcface_model_path,
                             bool                require_stamp) {
    enforce_embedder_stamp(gallery.embedder,
                           make_embedder_stamp(arcface_model_path),
                           gallery_path,
                           arcface_model_path.empty() ? "no --arcface given"
                                                      : arcface_model_path,
                           require_stamp);
 }
@@ -1,115 +0,0 @@
 #pragma once
 /// TRACES: GR-004 | SR-001
 //
 // Gallery ↔ embedder binding.
 //
 // A gallery is only valid for the embedder that built it. Cosine similarities
 // between embeddings from two different models are meaningless but *look*
 // plausible — nothing crashes, nothing is obviously wrong, and every number
 // measured downstream is quietly garbage. So the embedder's identity is stamped
 // into the gallery at build time and checked by every consumer at load time.
 //
 // ── What identifies an embedder ───────────────────────────────────────────────
 // Two fields, carried together:
 //
 //   model_name    basename of the model file, e.g. "LVFace-B_Glint360K.onnx"
 //   model_sha256  hex SHA-256 of that file's bytes
 //
 // The hash is what *decides*; the name is what a human *reads*. Neither alone is
 // enough:
 //
 //   • A name alone is a promise, not a fact. Models get re-exported, re-quantised
 //     and overwritten in place under an unchanged filename — which is precisely
 //     the case where the weights differ and nothing else does. A name-only stamp
 //     is blind to exactly the failure it exists to catch.
 //   • A hash alone is correct but unreadable: "expected 3f2a… got 9c1b…" tells an
 //     operator nothing about what to do next.
 //
 // SHA-256 over the file bytes is derived from the artefact rather than asserted
 // about it, is stable across machines and filesystems, and needs no registry to
 // be kept up to date. Cost is ~0.1 s for a 250 MB ONNX, paid once per process
 // (results are memoised on path+mtime+size), which is noise next to model load.
 //
 // ── Degraded and legacy cases ─────────────────────────────────────────────────
 // A TRT-backend deployment may run from a prebuilt .engine with the source .onnx
 // absent, so the hash cannot be computed. Then the name is compared alone and the
 // result is reported as a *weak* match — believed, not proven.
 //
 // Galleries built before GR-004 carry no stamp at all. They warn loudly rather
 // than fail, because the state is unknown rather than known-bad, and because
 // hard-failing every pre-existing gallery would make the check something people
 // route around rather than trust. Set require_stamp (or SAE_REQUIRE_GALLERY_STAMP=1)
 // to promote "unknown" to a hard error — that is the mode measurement work runs in.
 //
 // A *mismatch* is always fatal, in every mode, with no bypass.
 #include <cstdint>
 #include <string>
 struct EmbedderStamp {
    std::string model_name;      // basename of the model file
    std::string model_sha256;    // lowercase hex SHA-256 of the file's bytes ("" = unavailable)
    int32_t     embed_dim{512};
    bool empty() const { return model_name.empty() && model_sha256.empty(); }
    // "LVFace-B_Glint360K.onnx (sha256 3f2a1c4d…)" — for error messages.
    std::string describe() const;
 };
 // Identify the model at `model_path`. Missing/unreadable file → name filled from
 // the path, hash left empty (the weak-match path). Empty path → empty stamp.
 EmbedderStamp make_embedder_stamp(const std::string& model_path);
 enum class StampVerdict {
    match,             // hashes agree — binding proven
    weak_match,        // names agree, no hash on one side — believed, unproven
    unstamped,         // gallery predates GR-004 / was written without a stamp
    unknown_embedder,  // gallery is stamped but the loaded embedder can't be identified
    mismatch,          // proven different models — always fatal
 };
 struct StampCheck {
    StampVerdict verdict{StampVerdict::match};
    std::string  message;      // human-readable, names BOTH sides
    // A mismatch is fatal unconditionally. The three "cannot prove it" verdicts
    // are fatal only in strict mode.
    bool fatal(bool require_stamp) const {
        return verdict == StampVerdict::mismatch ||
               (require_stamp && verdict != StampVerdict::match);
    }
 };
 // Pure comparison — no file I/O, no model loading. This is the unit under test.
 // `gallery_desc`/`embedder_desc` are only used to make the message locatable
 // (a gallery path, a dump path, "the embedder being loaded", …).
 StampCheck compare_embedder_stamps(const EmbedderStamp& built_with,
                                   const EmbedderStamp& loading_with,
                                   const std::string&   gallery_desc  = "gallery",
                                   const std::string&   embedder_desc = "embedder");
 // Apply the comparison: throw std::runtime_error on a fatal verdict, otherwise
 // log to stderr. `require_stamp` is OR-ed with SAE_REQUIRE_GALLERY_STAMP.
 void enforce_embedder_stamp(const EmbedderStamp& built_with,
                            const EmbedderStamp& loading_with,
                            const std::string&   gallery_desc,
                            const std::string&   embedder_desc,
                            bool                 require_stamp);
 // Convenience for the common consumer shape: "I loaded this gallery and I am
 // about to embed with this model file." Hashes the model, then enforces.
 struct ActorGallery;
 void verify_gallery_embedder(const ActorGallery& gallery,
                             const std::string&  gallery_path,
                             const std::string&  arcface_model_path,
                             bool                require_stamp);
 // SAE_REQUIRE_GALLERY_STAMP=1 → treat an unprovable binding as fatal.
 bool require_gallery_stamp_from_env();
 // Lowercase hex SHA-256. Exposed so a test can pin the digest against the
 // published vectors, which is what guarantees the C++ and Python (hashlib)
 // stamps of the same file agree.
 std::string sha256_hex(const std::string& bytes);
 std::string sha256_file_hex(const std::string& path);   // "" if unreadable
@@ -1,6 +1,5 @@
 #include "gallery_builder.hpp"
 #include "config.hpp"
 #include "embedder_stamp.hpp"
 #include "face_utils.hpp"
 #include "inference/face_detector.hpp"
 #include "inference/face_embedder.hpp"
@@ -42,12 +41,6 @@ ActorGallery build_gallery(const BuildConfig& cfg) {
    ActorGallery gallery;
    /// TRACES: GR-004 | SR-001
    // Stamp before the first embedding exists, so there is no window in which a
    // gallery holds vectors without recording what produced them.
    gallery.embedder = make_embedder_stamp(cfg.arcface_model);
    std::cerr << "[build_gallery] embedder: " << gallery.embedder.describe() << "\n";
    for (const auto& actor_dir : fs::directory_iterator(cfg.gallery_root)) {
        if (!actor_dir.is_directory()) continue;
@@ -96,27 +89,6 @@ ActorGallery build_gallery(const BuildConfig& cfg) {
                    return a.confidence < b.confidence;
                });
            // Reject faces too small to embed honestly.
            //
            // The reference images are crops cut from the film, not mugshots, so
            // the detected face can be a small fraction of the image. Upscaling a
            // 30 px face to ArcFace's 112x112 feeds the model an input it was
            // never trained for, and it answers with a confident, plausible,
            // wrong embedding.
            //
            // At inference that costs one frame. Here it is permanent: a poisoned
            // reference sits in the gallery and corrupts every future match
            // against that character, which is exactly the kind of error that is
            // invisible without a study that should not have been needed.
            if (cfg.min_face_px > 0.f) {
                const float side = std::min(best.bbox.width, best.bbox.height);
                if (side < cfg.min_face_px) {
                    std::cerr << "  [skip] face " << side << "px < " << cfg.min_face_px
                              << "px: " << img_file.path().filename() << "\n";
                    continue;
                }
            }
            cv::Mat crop = align_face(img, best.landmarks);
            if (crop.empty()) {
                std::cerr << "  [skip] alignment failed: " << img_file.path().filename() << "\n";
@@ -1,5 +1,4 @@
 #pragma once
 #include "gallery/gallery_report.hpp"
 #include "types.hpp"
 #include <string>
@@ -29,16 +28,6 @@ struct BuildConfig {
    float       detector_conf{0.5f};
    float       detector_nms{0.4f};
    int         max_side{500};  // downscale source images to this max dimension
    /// Minimum detected-face side, in pixels of the (possibly downscaled)
    /// source image. 0 disables the check.
    ///
    /// References below this are dropped rather than upscaled: a face smaller
    /// than the embedder's input is off-distribution, and a bad reference
    /// poisons every match against that identity for the life of the gallery.
    /// Mirrors the inference-side --min-face-px so the gallery is built from
    /// the same face scales it will be matched against.
    float       min_face_px{0.f};
                                // before detection — TMDB portraits are ~2k px,
                                // SCRFD trains on smaller faces and detection
                                // confidence drops on huge inputs. 0 = disabled.
@@ -1,5 +1,4 @@
 #pragma once
 /// TRACES: AR-023 | SR-002
 #include "types.hpp"
 #include <algorithm>
@@ -9,7 +8,6 @@
 #include <cstdlib>
 #include <cstring>
 #include <fstream>
 #include <functional>
 #include <iostream>
 #include <stdexcept>
 #include <string>
@@ -50,75 +48,14 @@ struct GalleryCalibration {
    }
 };
 /// TRACES: AR-023, AR-024 | SR-002
 ///
 /// cosine → P(same person). The one probability space the pipeline reasons in.
 ///
 /// Handed to every stage that has to decide whether two embeddings are the same
 /// person — track association (AR-007), evidence discounting (AR-025), identity
 /// matching — so a threshold of 0.5 means the same thing in all of them. A stage
 /// that thresholded a raw cosine instead would be using a number that means
 /// something different for every model, gallery and face size (AR-024).
 ///
 /// **No prior term.** `log_prior_odds` adjusts for the gallery's base rate, which
 /// is a question about *which of N actors*; association asks whether two faces
 /// are one person, where the balanced fit is the right answer. Passing the
 /// matcher's prior here would silently bias tracking by the size of the cast.
 inline std::function<float(float)> same_person_probability(const GalleryCalibration& cal) {
    if (!cal.valid) {
        // Loud, because the failure mode is invisible: an untuned sigmoid still
        // returns plausible probabilities, and every threshold downstream of it
        // is then a guess wearing a calibrated number's clothes.
        std::cerr << "[calibration] WARNING: no fitted calibration — association and "
                     "evidence weighting fall back to the untuned default sigmoid "
                     "(a=" << cal.a << ", b=" << cal.b << "). Probabilities are "
                     "not meaningful for this embedder.\n";
    }
    return [cal](float similarity) { return cal.probability(similarity); };
 }
 /// TRACES: GR-003 | SR-001
 ///
 /// Everything the fit learns about the gallery on its way to two numbers.
 ///
 /// The fit computes per-actor dedup counts, which actors can supply positive
 /// pairs at all, and the two similarity distributions the sigmoid is derived
 /// from — and then returns only (a, b, valid). GR-003 exists because that is the
 /// evidence for whether the calibration, and so every threshold expressed in its
 /// probability space (AR-024), rests on anything. Filling this struct costs
 /// nothing: the values already exist at the point they are copied out.
 ///
 /// Per-actor vectors are indexed by the actor index used in `flat_actor`.
 struct GalleryCalibrationStats {
    int   n_actors                    = 0;
    int   min_embeddings_for_positive = 0;
    float dedup_sim_threshold         = 0.f;
    std::vector<int>  distinct_per_actor;           // after near-duplicate removal
    std::vector<int>  duplicates_removed_per_actor;
    std::vector<char> eligible;                     // 1 = supplies positive pairs
    int                 hist_bins = 0;              // over sim ∈ [-1, 1]
    std::vector<double> intra_hist;
    std::vector<double> inter_hist;
    double              n_intra_pairs = 0.0;
    double              n_inter_pairs = 0.0;
    double train_accuracy_pct = 0.0;
 };
 // Fit a logistic sigmoid to gallery pair similarities.
 // Positive pairs: same actor, different reference images.
 // Negative pairs: different actors (all cross-actor embedding pairs).
 // Class weights balance the (typically skewed) pos/neg ratio.
 // Requires ≥2 positive pairs and ≥1 negative pair.
 //
 // `stats` is optional (GR-003): pass one to receive the dedup, eligibility and
 // distribution detail the fit would otherwise discard.
 inline GalleryCalibration calibrate_gallery(
    const std::vector<Embedding>& flat_emb,
-    const std::vector<int>&       flat_actor,
+    const std::vector<int>&       flat_actor)
    GalleryCalibrationStats*      stats = nullptr)
 {
    constexpr int   kMinEmbeddingsForPositive = 5;
    constexpr float kDedupSimThreshold        = 1.f - 1e-7f; // sim above this = duplicate
@@ -142,39 +79,11 @@ inline GalleryCalibration calibrate_gallery(
    std::vector<bool>      actor_eligible(n_actors, false);
    int                    n_eligible = 0;
    /// TRACES: GR-003 | SR-001
    // Record what the filter did, per actor, while the counts still exist.
    if (stats) {
        *stats = GalleryCalibrationStats{};
        stats->n_actors                    = n_actors;
        stats->min_embeddings_for_positive = kMinEmbeddingsForPositive;
        stats->dedup_sim_threshold         = kDedupSimThreshold;
        stats->distinct_per_actor.assign(n_actors, 0);
        stats->duplicates_removed_per_actor.assign(n_actors, 0);
        stats->eligible.assign(n_actors, 0);
        stats->hist_bins = kHistBins;
        stats->intra_hist.assign(kHistBins, 0.0);
        stats->inter_hist.assign(kHistBins, 0.0);
    }
    for (int ai = 0; ai < n_actors; ++ai) {
        std::vector<Embedding> kept;
        for (const auto& e : by_actor[ai]) {
            bool dup = false;
            for (const auto& k : kept) {
                // EXCEPTION: AR-024 this asks whether two vectors are THE SAME
                // VECTOR, not whether two faces are the same person.
                //
                // Two independent reasons, either sufficient. First, at
                // 1 - 1e-7 the threshold is a floating-point identity test: it
                // catches one source image embedded twice, and no genuine pair
                // of distinct photographs lands there. Nothing about it is a
                // decision, so there is nothing for a probability to mean.
                //
                // Second, and structurally: this IS the calibration fit. The
                // dedup runs on its input, before (a, b) exist. A calibrated
                // comparison here would have to be calibrated by the fit it is
                // feeding, which is not a thing that can be arranged.
                if (cosine_similarity(e, k) > kDedupSimThreshold) { dup = true; break; }
            }
            if (!dup) kept.push_back(e);
@@ -183,12 +92,6 @@ inline GalleryCalibration calibrate_gallery(
            actor_eligible[ai] = true;
            ++n_eligible;
        }
        if (stats) {
            stats->distinct_per_actor[ai] = static_cast<int>(kept.size());
            stats->duplicates_removed_per_actor[ai] =
                static_cast<int>(by_actor[ai].size() - kept.size());
            stats->eligible[ai] = actor_eligible[ai] ? 1 : 0;
        }
        for (auto& e : kept) {
            flat_emb_dedup.push_back(e);
            flat_actor_dedup.push_back(ai);
@@ -196,14 +99,6 @@ inline GalleryCalibration calibrate_gallery(
    }
    const int n = static_cast<int>(flat_emb_dedup.size());
    // Nothing to fit and nothing to multiply. Returning here keeps the report
    // buildable for a degenerate gallery instead of handing cv::gemm an empty
    // matrix; the per-actor stats above are already filled and still useful.
    if (n == 0) {
        std::cerr << "[calibration] no embeddings — calibration skipped\n";
        return {};
    }
    std::cerr << "[calibration] dedup: " << flat_emb.size() << " -> " << n
              << " embeddings  (" << n_eligible << "/" << n_actors
              << " actors have >= " << kMinEmbeddingsForPositive
@@ -304,17 +199,6 @@ inline GalleryCalibration calibrate_gallery(
    double n_pos = 0.0, n_neg = 0.0;
    for (int b = 0; b < kHistBins; ++b) { n_pos += pos_hist[b]; n_neg += neg_hist[b]; }
    /// TRACES: GR-003 | SR-001
    // The two distributions the sigmoid is about to be fitted from. Emitted
    // whether or not the fit succeeds — a failed fit is exactly the case where
    // someone needs to see why.
    if (stats) {
        stats->intra_hist    = pos_hist;
        stats->inter_hist    = neg_hist;
        stats->n_intra_pairs = n_pos;
        stats->n_inter_pairs = n_neg;
    }
    if (n_pos < 2 || n_neg < 1) {
        std::cerr << "[calibration] insufficient pairs (+" << n_pos
                  << "/-" << n_neg << ") — calibration skipped\n";
@@ -369,7 +253,6 @@ inline GalleryCalibration calibrate_gallery(
        correct += (sig > 0.5f) ? pos_hist[b] : neg_hist[b];
    }
    double acc = 100.0 * correct / total;
    if (stats) stats->train_accuracy_pct = acc;
    GalleryCalibration cal{a, bias, true};
    std::cerr << "[calibration] sigmoid fitted:"
@@ -1,495 +0,0 @@
 #pragma once
 /// TRACES: GR-003 | SR-001
 ///
 /// The gallery build report — what the gallery *is*, written next to it.
 ///
 /// A gallery is a silent artefact: it loads, it scores, it never complains. The
 /// two ways it fails are both invisible from the outside.
 ///
 ///  1. **An actor with zero usable images can never be recognised.** They are
 ///     dropped at build time (`gallery_builder.cpp` skips a directory whose
 ///     images all fail detection or alignment), so afterwards nothing in the
 ///     file records that they were ever meant to be there. Every scene they
 ///     appear in is a guaranteed miss, and recall is capped at a number nobody
 ///     computed. This is the single most useful line in the report.
 ///  2. **A gallery can be quietly bad and look fine.** The Platt sigmoid
 ///     (AR-023) is fitted from two distributions — intra-class (same actor,
 ///     different reference) and inter-class (different actors) similarity — and
 ///     *every* threshold in the pipeline is expressed in the probability space
 ///     that fit defines (AR-024): identity acceptance, track association,
 ///     expansion admission, cluster merging. If those two distributions overlap
 ///     heavily the fit is weak, and every downstream decision silently inherits
 ///     that weakness while still reporting confident-looking probabilities. The
 ///     fit already computes the distributions and throws them away; emitting
 ///     them is what makes the quality of the whole probability space auditable
 ///     instead of assumed.
 ///
 /// The report is therefore a build artefact, not a debug aid: it is the only
 /// place the recall ceiling and the calibration's conditioning are written down.
 ///
 /// **On the histograms being in cosine space.** They bin raw similarity, and
 /// that is not an AR-024 violation: no decision is taken here. These two
 /// distributions are the *input* the calibration is fitted from — they cannot be
 /// expressed in the probability space the calibration defines, because that
 /// space is their output. GR-003 asks for exactly this ("the intra/inter
 /// distributions behind it"), for the same reason GR-008 characterises an
 /// actor's reference spread in the metric space: shape is a property of the
 /// metric, decisions are a property of the probability.
 #include "gallery/gallery_calibration.hpp"
 #include "gallery/embedder_stamp.hpp"
 #include "types.hpp"
 #include <nlohmann/json.hpp>
 #include <algorithm>
 #include <cmath>
 #include <cstdint>
 #include <fstream>
 #include <stdexcept>
 #include <string>
 #include <vector>
 /// TRACES: GR-003 | SR-001
 ///
 /// Per-actor image accounting from the build pass, including the actors that
 /// produced nothing and were therefore dropped from the gallery.
 ///
 /// Filled by `build_gallery()`. It has to be collected there and cannot be
 /// recovered later: by the time a gallery exists, an actor with no usable image
 /// is indistinguishable from an actor who was never requested.
 struct GalleryBuildAudit {
    struct ActorImages {
        std::string imdb_id;
        std::string name;
        int images_seen   = 0;  // candidate image files in the actor's directory
        int images_used   = 0;  // ...that yielded an embedding
        int unreadable    = 0;  // cv::imread failed
        int no_face       = 0;  // detector found nothing
        int align_failed  = 0;  // 5-point warp failed
    };
    std::vector<ActorImages> actors;  // every directory seen, in build order
 };
 /// TRACES: GR-003 | SR-001
 struct GalleryReport {
    // One row per actor the build considered. Actors with references == 0 are
    // the zero-usable-image case: present in the source tree, absent from the
    // gallery, unrecognisable for the life of the file.
    struct Actor {
        std::string imdb_id;
        std::string name;
        int  images_seen         = -1;  // -1 = unknown (report built without a build audit)
        int  references          = 0;   // embeddings stored in the gallery
        int  distinct_references = 0;   // ...after near-duplicate removal
        int  duplicates_removed  = 0;
        bool eligible_for_positive_pairs = false;
    };
    // The two distributions the sigmoid is fitted from, as the fit itself saw
    // them: counts per similarity bin over [sim_min, sim_max].
    struct Distributions {
        int    bins    = 0;
        float  sim_min = -1.f;
        float  sim_max =  1.f;
        std::vector<double> intra;  // same actor, different reference image
        std::vector<double> inter;  // different actors
        double intra_pairs = 0.0;
        double inter_pairs = 0.0;
        double intra_mean  = 0.0;
        double inter_mean  = 0.0;
        // Normalised histogram intersection, Σ_b min(p_intra[b], p_inter[b]).
        // 0 = perfectly separated, 1 = indistinguishable. This is the number
        // that says whether the calibration — and so every threshold expressed
        // in its probability space — rests on anything.
        double overlap     = 0.0;
    };
    // GR-003 / AR-023 open question, reported but NOT applied. The spec asks for
    // a gallery-derived prior of intra/(intra+inter); the shipped default is
    // 0.5. Persisting the distributions makes the real value computable, so the
    // decision can be taken on evidence rather than left implicit. Behaviour is
    // unchanged: `applied` is always false here.
    struct Prior {
        double      derived           = 0.0;  // intra_pairs / (intra_pairs + inter_pairs)
        double      derived_log_odds  = 0.0;  // log(p/(1-p)), the term AR-023 would add
        float       configured_default = 0.5f;
        bool        applied           = false;
        std::string note;
    };
    std::string   schema{"sae.gallery_report/1"};
    std::string   gallery_path;
    EmbedderStamp embedder;
    // ── Summary ──────────────────────────────────────────────────────────────
    int     actors_total                   = 0;  // considered (gallery + zero-usable)
    int     actors_in_gallery              = 0;
    int     actors_zero_usable             = 0;
    int     actors_below_positive_threshold = 0;
    int64_t embeddings_total               = 0;
    int64_t distinct_embeddings_total      = 0;
    int64_t duplicates_removed_total       = 0;
    double  mean_embeddings_per_actor      = 0.0;  // over actors in the gallery
    int     min_embeddings_for_positive_pairs = 0;
    float   dedup_similarity_threshold     = 0.f;
    // ── Calibration ──────────────────────────────────────────────────────────
    float    calib_a     = 10.f;
    float    calib_b     = -5.f;
    bool     calib_valid = false;
    uint64_t calib_hash  = 0;
    double   calib_train_accuracy_pct = 0.0;
    float    calib_boundary_p50       = 0.f;  // similarity at which P(match) = 0.5
    Distributions distributions;
    Prior         prior;
    std::vector<Actor>       actors;
    // Names duplicated out of `actors` so the two failure modes are greppable
    // without a JSON query. These are the lines a human reads first.
    std::vector<std::string> zero_usable;
    std::vector<std::string> below_positive_threshold;
 };
 /// TRACES: GR-003 | SR-001
 ///
 /// Assembles the report from the three things that know a piece of the answer:
 /// the gallery itself (who is in it, with how many references), the calibration
 /// stats (dedup, eligibility, the two distributions), and the build audit (who
 /// was considered and produced nothing). The audit is optional — a report built
 /// from a stored gallery simply cannot know about the actors that never made it.
 ///
 /// `stats` is indexed by actor index, so the flat arrays handed to
 /// `calibrate_gallery()` must have used the gallery's own actor ordering.
 inline GalleryReport build_gallery_report(const ActorGallery&            gallery,
                                          const GalleryCalibration&      cal,
                                          const GalleryCalibrationStats& stats,
                                          const GalleryBuildAudit*       audit = nullptr,
                                          const std::string&             gallery_path = "",
                                          float                          configured_prior = 0.5f)
 {
    GalleryReport r;
    r.gallery_path = gallery_path;
    r.embedder     = gallery.embedder;
    r.calib_a     = cal.a;
    r.calib_b     = cal.b;
    r.calib_valid = cal.valid;
    r.calib_hash  = gallery.calib_hash;
    r.calib_train_accuracy_pct = stats.train_accuracy_pct;
    r.calib_boundary_p50       = cal.boundary_at(0.5f);
    r.min_embeddings_for_positive_pairs = stats.min_embeddings_for_positive;
    r.dedup_similarity_threshold        = stats.dedup_sim_threshold;
    auto audit_for = [&](const ActorGallery::Actor& a) -> const GalleryBuildAudit::ActorImages* {
        if (!audit) return nullptr;
        for (const auto& e : audit->actors) {
            if (!a.imdb_id.empty() && e.imdb_id == a.imdb_id) return &e;
            if (a.imdb_id.empty() && e.name == a.name)        return &e;
        }
        return nullptr;
    };
    for (size_t i = 0; i < gallery.actors.size(); ++i) {
        const auto& ga = gallery.actors[i];
        GalleryReport::Actor row;
        row.imdb_id    = ga.imdb_id;
        row.name       = ga.name;
        row.references = static_cast<int>(ga.embeddings.size());
        if (const auto* au = audit_for(ga)) row.images_seen = au->images_seen;
        if (i < stats.distinct_per_actor.size()) {
            row.distinct_references = stats.distinct_per_actor[i];
            row.duplicates_removed  = stats.duplicates_removed_per_actor[i];
            row.eligible_for_positive_pairs = stats.eligible[i] != 0;
        } else {
            // No calibration stats for this actor (the fit never saw them).
            // Report the raw count rather than a fabricated distinct count.
            row.distinct_references = row.references;
        }
        r.embeddings_total          += row.references;
        r.distinct_embeddings_total += row.distinct_references;
        r.duplicates_removed_total  += row.duplicates_removed;
        if (!row.eligible_for_positive_pairs) {
            ++r.actors_below_positive_threshold;
            r.below_positive_threshold.push_back(row.name);
        }
        r.actors.push_back(std::move(row));
    }
    r.actors_in_gallery = static_cast<int>(gallery.actors.size());
    // Actors the build considered and could not use at all. They are not in the
    // gallery, so this is the only record that they exist.
    if (audit) {
        for (const auto& e : audit->actors) {
            if (e.images_used > 0) continue;
            GalleryReport::Actor row;
            row.imdb_id     = e.imdb_id;
            row.name        = e.name;
            row.images_seen = e.images_seen;
            row.references  = 0;
            r.zero_usable.push_back(e.name);
            r.actors.push_back(std::move(row));
        }
    }
    r.actors_zero_usable = static_cast<int>(r.zero_usable.size());
    r.actors_total       = r.actors_in_gallery + r.actors_zero_usable;
    r.mean_embeddings_per_actor =
        r.actors_in_gallery > 0
            ? static_cast<double>(r.embeddings_total) / r.actors_in_gallery
            : 0.0;
    // ── The two distributions, straight out of the fit ───────────────────────
    auto& d  = r.distributions;
    d.bins    = stats.hist_bins;
    d.sim_min = -1.f;
    d.sim_max =  1.f;
    d.intra   = stats.intra_hist;
    d.inter   = stats.inter_hist;
    d.intra_pairs = stats.n_intra_pairs;
    d.inter_pairs = stats.n_inter_pairs;
    if (d.bins > 0) {
        const double bin_w = (d.sim_max - d.sim_min) / d.bins;
        double si = 0.0, se = 0.0;
        for (int b = 0; b < d.bins; ++b) {
            const double centre = d.sim_min + (b + 0.5) * bin_w;
            si += d.intra[b] * centre;
            se += d.inter[b] * centre;
        }
        if (d.intra_pairs > 0.0) d.intra_mean = si / d.intra_pairs;
        if (d.inter_pairs > 0.0) d.inter_mean = se / d.inter_pairs;
        if (d.intra_pairs > 0.0 && d.inter_pairs > 0.0) {
            double ov = 0.0;
            for (int b = 0; b < d.bins; ++b)
                ov += std::min(d.intra[b] / d.intra_pairs, d.inter[b] / d.inter_pairs);
            d.overlap = ov;
        }
    }
    // ── The prior AR-023 leaves open — computed, reported, not applied ────────
    r.prior.configured_default = configured_prior;
    r.prior.applied            = false;
    const double pair_total = d.intra_pairs + d.inter_pairs;
    if (pair_total > 0.0) {
        r.prior.derived = d.intra_pairs / pair_total;
        const double p  = std::clamp(r.prior.derived, 1e-12, 1.0 - 1e-12);
        r.prior.derived_log_odds = std::log(p / (1.0 - p));
    }
    r.prior.note =
        "AR-023 specifies a gallery-derived prior of intra/(intra+inter); the shipped "
        "match_prior default is 0.5 (calibrated sigmoid used directly). The derived value "
        "is the base rate of same-actor pairs among ALL enumerated gallery pairs, so it "
        "falls as the cast grows (roughly (k-1)/((k-1)+(A-1)k) for A actors with k "
        "references each) — it is a property of gallery size as much as of the embedder. "
        "Reported here as evidence; NOT applied. Behaviour is unchanged until the choice "
        "is recorded in the spec.";
    return r;
 }
 // ── JSON ─────────────────────────────────────────────────────────────────────
 /// TRACES: GR-003 | SR-001
 inline nlohmann::json gallery_report_to_json(const GalleryReport& r) {
    nlohmann::json j;
    j["schema"]       = r.schema;
    j["gallery_path"] = r.gallery_path;
    j["embedder"] = {{"model_name",   r.embedder.model_name},
                     {"model_sha256", r.embedder.model_sha256},
                     {"embed_dim",    r.embedder.embed_dim}};
    j["summary"] = {
        {"actors_total",                    r.actors_total},
        {"actors_in_gallery",               r.actors_in_gallery},
        {"actors_zero_usable",              r.actors_zero_usable},
        {"actors_below_positive_threshold", r.actors_below_positive_threshold},
        {"embeddings_total",                r.embeddings_total},
        {"distinct_embeddings_total",       r.distinct_embeddings_total},
        {"duplicates_removed_total",        r.duplicates_removed_total},
        {"mean_embeddings_per_actor",       r.mean_embeddings_per_actor},
        {"min_embeddings_for_positive_pairs", r.min_embeddings_for_positive_pairs},
        {"dedup_similarity_threshold",      r.dedup_similarity_threshold}};
    j["calibration"] = {
        {"a",                  r.calib_a},
        {"b",                  r.calib_b},
        {"valid",              r.calib_valid},
        {"hash",               r.calib_hash},
        {"train_accuracy_pct", r.calib_train_accuracy_pct},
        {"boundary_p50",       r.calib_boundary_p50}};
    const auto& d = r.distributions;
    j["distributions"] = {
        {"bins",        d.bins},
        {"sim_min",     d.sim_min},
        {"sim_max",     d.sim_max},
        {"intra",       d.intra},
        {"inter",       d.inter},
        {"intra_pairs", d.intra_pairs},
        {"inter_pairs", d.inter_pairs},
        {"intra_mean",  d.intra_mean},
        {"inter_mean",  d.inter_mean},
        {"overlap",     d.overlap}};
    j["prior"] = {
        {"derived",            r.prior.derived},
        {"derived_log_odds",   r.prior.derived_log_odds},
        {"configured_default", r.prior.configured_default},
        {"applied",            r.prior.applied},
        {"note",               r.prior.note}};
    j["zero_usable"]              = r.zero_usable;
    j["below_positive_threshold"] = r.below_positive_threshold;
    j["actors"] = nlohmann::json::array();
    for (const auto& a : r.actors) {
        j["actors"].push_back({
            {"imdb_id",             a.imdb_id},
            {"name",                a.name},
            {"images_seen",         a.images_seen},
            {"references",          a.references},
            {"distinct_references", a.distinct_references},
            {"duplicates_removed",  a.duplicates_removed},
            {"eligible_for_positive_pairs", a.eligible_for_positive_pairs}});
    }
    return j;
 }
 /// TRACES: GR-003 | SR-001
 inline GalleryReport gallery_report_from_json(const nlohmann::json& j) {
    GalleryReport r;
    r.schema       = j.value("schema", std::string{});
    r.gallery_path = j.value("gallery_path", std::string{});
    if (j.contains("embedder")) {
        const auto& je = j.at("embedder");
        r.embedder.model_name   = je.value("model_name", "");
        r.embedder.model_sha256 = je.value("model_sha256", "");
        r.embedder.embed_dim    = je.value("embed_dim", 512);
    }
    if (j.contains("summary")) {
        const auto& s = j.at("summary");
        r.actors_total                    = s.value("actors_total", 0);
        r.actors_in_gallery               = s.value("actors_in_gallery", 0);
        r.actors_zero_usable              = s.value("actors_zero_usable", 0);
        r.actors_below_positive_threshold = s.value("actors_below_positive_threshold", 0);
        r.embeddings_total                = s.value("embeddings_total", int64_t{0});
        r.distinct_embeddings_total       = s.value("distinct_embeddings_total", int64_t{0});
        r.duplicates_removed_total        = s.value("duplicates_removed_total", int64_t{0});
        r.mean_embeddings_per_actor       = s.value("mean_embeddings_per_actor", 0.0);
        r.min_embeddings_for_positive_pairs = s.value("min_embeddings_for_positive_pairs", 0);
        r.dedup_similarity_threshold      = s.value("dedup_similarity_threshold", 0.f);
    }
    if (j.contains("calibration")) {
        const auto& c = j.at("calibration");
        r.calib_a     = c.value("a", 10.f);
        r.calib_b     = c.value("b", -5.f);
        r.calib_valid = c.value("valid", false);
        r.calib_hash  = c.value("hash", uint64_t{0});
        r.calib_train_accuracy_pct = c.value("train_accuracy_pct", 0.0);
        r.calib_boundary_p50       = c.value("boundary_p50", 0.f);
    }
    if (j.contains("distributions")) {
        const auto& d = j.at("distributions");
        r.distributions.bins        = d.value("bins", 0);
        r.distributions.sim_min     = d.value("sim_min", -1.f);
        r.distributions.sim_max     = d.value("sim_max", 1.f);
        r.distributions.intra       = d.value("intra", std::vector<double>{});
        r.distributions.inter       = d.value("inter", std::vector<double>{});
        r.distributions.intra_pairs = d.value("intra_pairs", 0.0);
        r.distributions.inter_pairs = d.value("inter_pairs", 0.0);
        r.distributions.intra_mean  = d.value("intra_mean", 0.0);
        r.distributions.inter_mean  = d.value("inter_mean", 0.0);
        r.distributions.overlap     = d.value("overlap", 0.0);
    }
    if (j.contains("prior")) {
        const auto& p = j.at("prior");
        r.prior.derived            = p.value("derived", 0.0);
        r.prior.derived_log_odds   = p.value("derived_log_odds", 0.0);
        r.prior.configured_default = p.value("configured_default", 0.5f);
        r.prior.applied            = p.value("applied", false);
        r.prior.note               = p.value("note", "");
    }
    r.zero_usable              = j.value("zero_usable", std::vector<std::string>{});
    r.below_positive_threshold = j.value("below_positive_threshold", std::vector<std::string>{});
    if (j.contains("actors")) {
        for (const auto& ja : j.at("actors")) {
            GalleryReport::Actor a;
            a.imdb_id             = ja.value("imdb_id", "");
            a.name                = ja.value("name", "");
            a.images_seen         = ja.value("images_seen", -1);
            a.references          = ja.value("references", 0);
            a.distinct_references = ja.value("distinct_references", 0);
            a.duplicates_removed  = ja.value("duplicates_removed", 0);
            a.eligible_for_positive_pairs = ja.value("eligible_for_positive_pairs", false);
            r.actors.push_back(std::move(a));
        }
    }
    return r;
 }
 // "<dir>/cast.h5" → "<dir>/cast.report.json". A known gallery extension is
 // replaced rather than appended to, so the report sits beside the gallery under
 // the same stem.
 inline std::string gallery_report_path(const std::string& gallery_path) {
    auto slash = gallery_path.find_last_of("/\\");
    auto dot   = gallery_path.find_last_of('.');
    std::string stem =
        (dot != std::string::npos && (slash == std::string::npos || dot > slash))
            ? gallery_path.substr(0, dot)
            : gallery_path;
    return stem + ".report.json";
 }
 /// TRACES: GR-003 | SR-001
 inline void save_gallery_report(const std::string& path, const GalleryReport& r) {
    std::ofstream out(path);
    if (!out.is_open())
        throw std::runtime_error("save_gallery_report: cannot write " + path);
    out << gallery_report_to_json(r).dump(2) << "\n";
 }
 /// TRACES: GR-003 | SR-001
 inline GalleryReport load_gallery_report(const std::string& path) {
    std::ifstream in(path);
    if (!in.is_open())
        throw std::runtime_error("load_gallery_report: cannot open " + path);
    nlohmann::json j;
    in >> j;
    return gallery_report_from_json(j);
 }
 /// TRACES: GR-003 | SR-001
 ///
 /// The report's headline, on stderr, at build time. The file is the audit trail;
 /// this is what stops a bad gallery from being shipped without anyone noticing.
 inline void log_gallery_report(const GalleryReport& r) {
    std::cerr << "[gallery-report] " << r.actors_in_gallery << " actors / "
              << r.embeddings_total << " embeddings"
              << "  (mean " << r.mean_embeddings_per_actor << " per actor)\n";
    if (r.actors_zero_usable > 0) {
        std::cerr << "[gallery-report] WARNING: " << r.actors_zero_usable
                  << " actor(s) have NO usable image — they can never be recognised:\n";
        for (const auto& n : r.zero_usable) std::cerr << "    - " << n << "\n";
    }
    if (r.actors_below_positive_threshold > 0) {
        std::cerr << "[gallery-report] " << r.actors_below_positive_threshold
                  << " actor(s) below " << r.min_embeddings_for_positive_pairs
                  << " distinct references — they contribute no positive pairs and "
                     "weaken the calibration\n";
    }
    if (r.duplicates_removed_total > 0)
        std::cerr << "[gallery-report] " << r.duplicates_removed_total
                  << " near-duplicate reference(s) removed\n";
    std::cerr << "[gallery-report] calibration valid=" << r.calib_valid
              << "  a=" << r.calib_a << "  b=" << r.calib_b
              << "  intra/inter overlap=" << r.distributions.overlap
              << "  (intra mean=" << r.distributions.intra_mean
              << ", inter mean=" << r.distributions.inter_mean << ")\n";
    std::cerr << "[gallery-report] gallery-derived prior would be "
              << r.prior.derived << " (log-odds " << r.prior.derived_log_odds
              << "); shipped default " << r.prior.configured_default
              << " is in force — reported, not applied\n";
 }
@@ -79,21 +79,6 @@ static ActorGallery load_gallery_hdf5(const std::string& path) {
        gallery.actors.push_back(std::move(actor));
    }
    /// TRACES: GR-004 | SR-001
    // Absent /embedder group == a gallery written before model binding existed.
    // It stays readable; verify_gallery_embedder() decides what that means.
    if (file.nameExists("embedder")) {
        H5::Group eg = file.openGroup("embedder");
        H5::StrType str(H5::PredType::C_S1, H5T_VARIABLE);
        if (eg.attrExists("model_name"))
            eg.openAttribute("model_name").read(str, gallery.embedder.model_name);
        if (eg.attrExists("model_sha256"))
            eg.openAttribute("model_sha256").read(str, gallery.embedder.model_sha256);
        if (eg.attrExists("embed_dim"))
            eg.openAttribute("embed_dim").read(H5::PredType::NATIVE_INT32,
                                               &gallery.embedder.embed_dim);
    }
    if (file.nameExists("calibration")) {
        H5::Group cal = file.openGroup("calibration");
        cal.openAttribute("a").read(H5::PredType::NATIVE_FLOAT, &gallery.calib_a);
@@ -164,20 +149,6 @@ static void save_gallery_hdf5(const std::string& path, const ActorGallery& galle
    write_str_dataset(file, "name", name);
    write_str_dataset(file, "source_images", src_images);
    /// TRACES: GR-004 | SR-001
    // Bind the file to the embedder that produced its vectors. Written only when
    // known — an empty stamp must round-trip as "unstamped", not as a stamp
    // claiming an unnamed model.
    if (!gallery.embedder.empty()) {
        H5::Group eg = file.createGroup("embedder");
        H5::DataSpace scalar(H5S_SCALAR);
        H5::StrType str(H5::PredType::C_S1, H5T_VARIABLE);
        eg.createAttribute("model_name", str, scalar).write(str, gallery.embedder.model_name);
        eg.createAttribute("model_sha256", str, scalar).write(str, gallery.embedder.model_sha256);
        eg.createAttribute("embed_dim", H5::PredType::NATIVE_INT32, scalar)
          .write(H5::PredType::NATIVE_INT32, &gallery.embedder.embed_dim);
    }
    if (gallery.calib_hash != 0) {
        H5::Group cal = file.createGroup("calibration");
        H5::DataSpace scalar(H5S_SCALAR);
@@ -215,17 +186,6 @@ ActorGallery load_gallery(const std::string& path) {
              << std::chrono::duration<double>(t1 - t0).count() << "s\n";
    ActorGallery gallery;
    /// TRACES: GR-004 | SR-001
    // Optional top-level "embedder" object, matching the HDF5 /embedder group.
    // Written by the JSON-era helper scripts; absent in anything older.
    if (j.contains("embedder") && j.at("embedder").is_object()) {
        const auto& je = j.at("embedder");
        gallery.embedder.model_name   = je.value("model_name", "");
        gallery.embedder.model_sha256 = je.value("model_sha256", "");
        gallery.embedder.embed_dim    = je.value("embed_dim", 512);
    }
    for (const auto& ja : j.at("actors")) {
        ActorGallery::Actor actor;
        actor.imdb_id     = ja.value("imdb_id", "");
@@ -6,25 +6,12 @@
 // legacy gallery.json files are still readable for backward compatibility but
 // save_gallery always writes HDF5 regardless of the requested extension.
 //
 // GR-005 is preserved here by absence: this is the only path that serialises a
 // gallery, and it reads and writes the local filesystem only. There is no
 // upload, no client, and no encoder that could put an embedding on a wire — the
 // public server refuses to carry one (SR-004/UR-012), and the prohibition holds
 // on this side by there being nothing that would try.
 //
 /// TRACES: GR-005 | SR-005
 //
 // HDF5 layout:
 //   /embeddings   float32 [N, 512]   all actors' refs concatenated, row-major
 //   /offset       int64   [A]        first row of actor a in /embeddings
 //   /count        int32   [A]        number of refs for actor a
 //   /imdb_id /tmdb_id /jellyfin_id /name : variable-length string [A]
 //   /source_images : variable-length string [N], parallel to /embeddings rows
 //   /embedder/model_name   : scalar var-len string attr — embedder file basename
 //   /embedder/model_sha256 : scalar var-len string attr — SHA-256 of that file
 //   /embedder/embed_dim    : scalar int32 attr
 //                        The GR-004 model binding. Absent group == unstamped
 //                        (pre-GR-004 file); see gallery/embedder_stamp.hpp.
 //   /calibration/a, /b : scalar float32 attrs — Platt-sigmoid P(match|sim) fit
 //   /calibration/valid : scalar int8 attr (0/1)
 //   /calibration/hash  : scalar uint64 attr — hash of the embeddings the fit
@@ -32,7 +19,6 @@
 //
 // Legacy JSON format (read-only):
 // {
 //   "embedder": {"model_name": "...", "model_sha256": "...", "embed_dim": 512},
 //   "actors": [
 //     {
 //       "imdb_id":      "nm0000093",         // optional, "" if unknown
@@ -2,14 +2,11 @@
 #include "types.hpp"
 #include "config.hpp"
 #include <functional>
 #include <cmath>
 #include <cstdio>
 #include <iostream>
 #include <limits>
 #include <map>
 #include <stdexcept>
 #include <string>
 #include <vector>
@@ -37,41 +34,39 @@
 //   2. Promotion (on confirmation). A track is "owned" by actor A once ≥N frames
 //      have been accepted (by the matcher's calibrated posterior) as A. On
 //      confirmation the retained buffer — the hard, gallery-far poses — is
-//      promoted into A's per-film annex, subject to one safety gate: the band's
+//      promoted into A's per-film annex, after two safety gates:
-//      lower bound, re-applied across the whole store (see `store_coherence`).
+//        • novelty: only embeddings whose best sim to A's refs is below
 //          expand_novelty_sim are added (skip poses already covered);
 //        • spread: if the retained buffer's internal spread (1 − min pairwise
 //          cosine sim) exceeds expand_track_spread_max the whole track is
 //          rejected — such spread signals a track-ID collision merging two
 //          people, whose embeddings must never enter A's annex.
 //
-// There is exactly one threshold here, the AR-018 band, and it is a calibrated
+// The annex is CPU-side and in-memory: it is small (tens of embeddings) so the
-// probability. Novelty is no longer a threshold at all — the eviction policy
+// matcher scans it with a scalar loop, and it is discarded when the process
-// above *orders* by gallery similarity rather than cutting at a constant, and
+// exits. Promoted embeddings only help SUBSEQUENT frames and later tracks of A —
-// the band's upper bound refuses the redundant views at the door. The raw
+// the pipeline stays streaming, no emitted output is buffered or relabelled.
 // cosines this replaces, expand_novelty_sim and expand_track_spread_max, are
 // retired under AR-024.
 //
 // TRACES: AR-026 | SR-001
 // The annex is in-memory and discarded when the process exits, but it is NOT
 // small: every owned track contributes, so it grows with cast size and film
 // length. It is therefore held as a contiguous row-major matrix with a parallel
 // actor index — the same flat_emb_/flat_actor_ shape the baked gallery uses —
 // and the matcher hands promoted rows to the similarity engine rather than
 // scanning them with a host-side loop. The deferred pass (AR-020) needs the same
 // contiguous operand to score the TBI queue against in one multiply.
 //
 // Promoted embeddings only help SUBSEQUENT frames and later tracks of A — the
 // pipeline stays streaming, no emitted output is buffered or relabelled.
 struct TrackGallery {
    // One promoted reference view held in the per-actor annex.
    struct AnnexEntry {
        Embedding emb;
        int       actor_idx{-1};
    };
    explicit TrackGallery(const Config& cfg)
        : enabled_(cfg.expand_gallery)
        , buffer_size_(std::max(1, cfg.expand_buffer_size))
-        , band_lo_(cfg.expand_band_lo)
+        , novelty_sim_(cfg.expand_novelty_sim)
-        , band_hi_(cfg.expand_band_hi)
+        , spread_max_(cfg.expand_track_spread_max)
        , min_anchor_frames_(std::max(1, cfg.expand_min_anchor_frames))
        , debug_dir_(cfg.expand_debug_dir)
    {
        if (!enabled_) return;
        std::cerr << "[track_gallery] per-film expansion ON"
                  << "  buffer=" << buffer_size_
-                  << "  band=[" << band_lo_ << ", " << band_hi_ << "]"
+                  << "  novelty_sim<" << novelty_sim_
                  << "  spread_max=" << spread_max_
                  << "  min_anchor_frames=" << min_anchor_frames_;
        if (!debug_dir_.empty()) {
            std::filesystem::create_directories(debug_dir_);
@@ -82,47 +77,16 @@ struct TrackGallery {
    bool enabled() const { return enabled_; }
-    /// TRACES: AR-026 | SR-001
+    // Current annex contents (empty when disabled). The matcher scans these
-    /// The annex as a contiguous row-major matrix (annex_size() × 512) plus the
+    // alongside the baked gallery so a promoted view can win best-of-N for its
-    /// parallel actor index. Only ever grows, never reordered, so a row index is
+    // actor. Returned by const-ref; only grows, never reordered.
-    /// stable for the life of the film — which is what lets the similarity
+    const std::vector<AnnexEntry>& annex() const { return annex_; }
    /// engine hold the same rows and the actor mapping stay a plain vector.
    int annex_size() const { return static_cast<int>(annex_actor_.size()); }
    const float* annex_data() const { return annex_emb_.data(); }
    const std::vector<int>& annex_actors() const { return annex_actor_; }
    /// One annex row (512 floats). The deferred pass (AR-020) scores the whole
    /// matrix at once via annex_data(); this is for inspecting a single view.
    const float* annex_row(int i) const {
        return annex_emb_.data() + static_cast<size_t>(i) * kEmbDim;
    }
    /// TRACES: AR-026 | SR-001
    /// Hand the caller every row promoted since the previous call, appending to
    /// its buffers, and return how many. The matcher pushes these into the
    /// similarity engine so the next frame's single GEMM covers the annex —
    /// draining rather than re-reading the whole matrix keeps that O(promoted),
    /// not O(annex), per frame.
    int drain_promotions(std::vector<float>& emb_out, std::vector<int>& actor_out) {
        const int pending = annex_size() - drained_;
        if (pending <= 0) return 0;
        emb_out.insert(emb_out.end(),
                       annex_emb_.begin() + static_cast<size_t>(drained_) * kEmbDim,
                       annex_emb_.end());
        actor_out.insert(actor_out.end(),
                         annex_actor_.begin() + drained_, annex_actor_.end());
        drained_ = annex_size();
        return pending;
    }
    // Offer one observed face to its track's diversity buffer.
    //   track_id     : face_tracker track (−1 = untracked, ignored)
    //   emb          : this frame's raw embedding
    //   best_actor   : actor with the highest gallery similarity for this face
-    //   best_gal_sim : that similarity (best sim to best_actor's baked+annex
+    //   best_gal_sim : that similarity (best sim to best_actor's baked+annex refs)
    //                  refs) — a raw cosine, the last one in this class: it is
    //                  calibrated on entry and only the probability is stored
    //   accepted     : true if the matcher accepted this face as best_actor
    //   crop         : aligned crop, retained only when debug dumping is on
    void observe(int track_id, const Embedding& emb,
@@ -133,82 +97,25 @@ struct TrackGallery {
        TrackState& ts = tracks_[track_id];
-        /// TRACES: AR-019 | SR-005
+        // Vote toward ownership: only accepted frames name an actor, and a track
-        // accepted_frames is an EVIDENCE FLOOR, not an identity decision: it
+        // that flip-flops between actors is ambiguous, so we tally per actor and
-        // asks "has this track been recognised often enough to be worth
+        // pick the plurality winner at confirmation time.
-        // promoting", never "who is it". Who it is comes from the registry.
+        if (accepted && best_actor >= 0) {
-        //
+            ts.actor_votes[best_actor]++;
-        // There used to be a per-actor tally here too, and promote() fell back
+            ts.accepted_frames++;
-        // to its plurality winner. That made two answers to "who is this track"
+        }
        // able to coexist, and the local one ignored the Bayesian accumulation
        // entirely -- weighting thirty near-identical looks the same as thirty
        // distinct ones, which is exactly what AR-025's discounting exists to
        // stop. Since promotion only fired on the local count, the fallback was
        // reachable in the live pipeline and not merely in tests: three
        // accepted frames arrive well before a posterior crosses ownership.
        if (accepted && best_actor >= 0) ts.accepted_frames++;
        insert_into_buffer(ts, emb, best_gal_sim, crop);
-        // Confirm and promote once BOTH hold: the registry owns this track, and
+        // Confirm and promote as soon as the anchor threshold is met, once.
-        // enough frames have been accepted to be worth the slots. Ownership is
+        if (!ts.promoted && ts.accepted_frames >= min_anchor_frames_)
        // the necessary one -- without it there is no actor to promote into.
        if (!ts.promoted && ts.registry_owner >= 0 &&
            ts.accepted_frames >= min_anchor_frames_)
            promote(track_id, ts);
    }
-    /// TRACES: AR-019 | SR-005
+    // Drop a track's buffer when the face_tracker expires it or on a scene cut,
-    /// Drop the buffers of tracks the registry no longer has.
+    // so stale/cross-cut embeddings can never be promoted later. Called by the
-    ///
+    // matcher when it observes a cut or track disappearance.
-    /// `alive` is the registry's own liveness test, so this annotates the track
+    void forget(int track_id) { tracks_.erase(track_id); }
    /// pool rather than duplicating it — the same shape as FaceTrackerFunc's
    /// prune_boxes, and for the same reason: a second opinion about which
    /// tracks exist is a second thing that can be wrong.
    ///
    /// This replaces a `forget(int)` that had NO callers, under a comment
    /// asserting "called by the matcher when it observes a cut or track
    /// disappearance". The cut half was true by another route (clear_tracks);
    /// the disappearance half was not, so a track that died quietly kept its
    /// buffer until the next cut cleared everything.
    template <typename AlivePredicate>
    void prune_dead(const AlivePredicate& alive) {
        if (!enabled_) return;
        for (auto it = tracks_.begin(); it != tracks_.end(); ) {
            if (alive(it->first)) ++it;
            else                  it = tracks_.erase(it);
        }
    }
    /// TRACES: AR-019 | SR-005
    /// The registry's verdict on who this track is. Authoritative: it comes from
    /// the Bayesian accumulation (AR-025), where the local tally counted raw
    /// accepted frames and so weighted thirty near-identical looks the same as
    /// thirty distinct ones.
    void set_owner(int track_id, int actor_idx) {
        if (track_id < 0 || actor_idx < 0) return;
        tracks_[track_id].registry_owner = actor_idx;
    }
    /// TRACES: AR-024 | SR-005
    /// Supply the calibration belonging to the active embedder.
    ///
    /// Required, not optional. The default used to be `max(0, cosine)` — a raw
    /// cosine worn as a probability, which made `expand_band_lo = 0.90` mean
    /// "cosine above 0.9" in a test and "P(same person) above 0.9" in
    /// production. Those are wildly different gates, and nothing announced the
    /// switch. `FaceTrackerFunc` already refuses to construct without a
    /// calibration for the same reason; this now matches it.
    void set_calibration(std::function<float(float)> c) {
        if (!c) throw std::invalid_argument(
            "track_gallery: a calibration is required — the admission band is "
            "expressed in probability space (AR-024)");
        calibrate_ = std::move(c);
    }
    /// Embeddings the band refused. A store that admits nothing is as wrong as
    /// one that admits everything, and neither is visible without this.
    std::size_t band_rejected() const { return rejected_; }
    // Drop every track buffer (scene cut / EOF). Mirrors face_tracker's clear.
    void clear_tracks() { tracks_.clear(); }
@@ -216,57 +123,23 @@ struct TrackGallery {
 private:
    struct BufEntry {
        Embedding emb;
-        /// P(same person) against the owning actor's refs when observed —
+        float     gal_sim{0.f};   // best sim to owning actor's refs when observed
        /// calibrated at the door (AR-024), so the eviction ordering below is a
        /// comparison of probabilities and the struct holds no bare cosine.
        float     gal_p{0.f};
        cv::Mat   crop;           // populated only when debug_dir_ set
    };
    struct TrackState {
        std::vector<BufEntry> buf;
        std::map<int, int>    actor_votes;   // actor_idx → accepted-frame count
        int                   accepted_frames{0};
        bool                  promoted{false};
        int                   registry_owner{-1};   ///< AR-019: authoritative
    };
    /// TRACES: AR-018, AR-024 | SR-005
    /// Banded admission: an embedding joins the store only if its similarity to
    /// something already there falls **inside a band**.
    ///
    ///   above the upper bound → redundant. It is another look at a pose the
    ///     store already covers, and adding it teaches the annex nothing while
    ///     costing a slot that a novel view could have used.
    ///   below the lower bound → suspect. Within one track every face is the
    ///     same person by construction, so an embedding unlike everything else
    ///     on the track is evidence the construction failed — a track-ID
    ///     collision or a bad detection. Admitting it is how an actor's annex
    ///     gets poisoned with someone else's face.
    ///
    /// Both bounds are calibrated probabilities, never raw cosines (AR-024): a
    /// bare similarity threshold means something different for every model and
    /// every face size, and this gate has to hold across both.
    ///
    /// The first embedding is always admitted — there is nothing for it to be
    /// redundant with, and nothing to contradict it.
    bool admit(const TrackState& ts, const Embedding& emb) const {
        if (ts.buf.empty()) return true;
        float p_max = 0.f;
        for (const auto& b : ts.buf)
            p_max = std::max(p_max, calibrate_(cosine_similarity(b.emb, emb)));
        return p_max >= band_lo_ && p_max <= band_hi_;
    }
    void insert_into_buffer(TrackState& ts, const Embedding& emb,
                            float gal_sim, const cv::Mat& crop)
    {
        if (!admit(ts, emb)) { ++rejected_; return; }
        BufEntry e;
        e.emb     = emb;
-        e.gal_p = calibrate_(gal_sim);
+        e.gal_sim = gal_sim;
        if (!debug_dir_.empty() && !crop.empty()) e.crop = crop.clone();
        if (static_cast<int>(ts.buf.size()) < buffer_size_) {
@@ -275,17 +148,13 @@ private:
        }
        // Buffer full: evict the member the gallery recognises best (highest
-        // gal_p) — least informative — but only if the newcomer is at least as
+        // gal_sim) — least informative — but only if the newcomer is at least as
        // novel. Keeping the most gallery-far views is the whole point.
        //
        // This is an *ordering*, not a threshold: there is no constant to tune,
        // and novelty-seeking lives here rather than in a cutoff. It ranks
        // probabilities, so it says the same thing across models (AR-024).
        int   worst_i   = -1;
-        float worst_p = e.gal_p;   // newcomer's probability is the bar to beat
+        float worst_sim = e.gal_sim;   // newcomer's sim is the bar to beat
        for (int i = 0; i < static_cast<int>(ts.buf.size()); ++i) {
-            if (ts.buf[i].gal_p > worst_p) {
+            if (ts.buf[i].gal_sim > worst_sim) {
-                worst_p = ts.buf[i].gal_p;
+                worst_sim = ts.buf[i].gal_sim;
                worst_i   = i;
            }
        }
@@ -297,25 +166,29 @@ private:
    void promote(int track_id, TrackState& ts) {
        ts.promoted = true;   // idempotent: never promote a track twice
-        const int actor = ts.registry_owner;
+        int actor = plurality_actor(ts);
-        if (actor < 0) return;   // unreachable: observe() gates on this
+        if (actor < 0) return;
-        // ── Safety gate: the band's lower bound, across the whole store ──────
+        // ── Safety gate: internal spread ─────────────────────────────────────
-        float worst = store_coherence(ts.buf);
+        // A legitimate single-person track varies in pose but stays reasonably
-        if (worst < band_lo_) {
+        // self-similar. Large spread signals two people merged under one track
        // ID — reject the whole track rather than poison the actor's annex.
        float spread = buffer_spread(ts.buf);
        if (spread > spread_max_) {
            std::cerr << "[track_gallery] track " << track_id
                      << " → actor " << actor
-                      << " REJECTED (worst pairwise P=" << worst
+                      << " REJECTED (spread " << spread
-                      << " < " << band_lo_ << ", likely ID collision)\n";
+                      << " > " << spread_max_ << ", likely ID collision)\n";
            return;
        }
        int added = 0;
        for (const auto& be : ts.buf) {
-            // Row-major append: the matrix stays contiguous so the matcher can
+            // ── Safety gate: novelty ─────────────────────────────────────────
-            // hand whole blocks of new rows to the GEMM path (AR-026).
+            // Skip poses the gallery already covers; only gallery-far views are
-            annex_emb_.insert(annex_emb_.end(), be.emb.begin(), be.emb.end());
+            // worth the annex slot (and the extra per-frame scan cost).
-            annex_actor_.push_back(actor);
+            if (be.gal_sim >= novelty_sim_) continue;
            annex_.push_back({be.emb, actor});
            if (!debug_dir_.empty() && !be.crop.empty())
                dump_mugshot(track_id, actor, added, be);
            ++added;
@@ -323,65 +196,48 @@ private:
        std::cerr << "[track_gallery] track " << track_id
                  << " confirmed actor " << actor
-                  << " (" << ts.accepted_frames << " accepted frames, worst "
+                  << " (" << ts.accepted_frames << " accepted frames, spread "
-                  << "pairwise P=" << worst << ") — promoted " << added
+                  << spread << ") — promoted " << added << "/"
-                  << " views; annex now " << annex_size() << "\n";
+                  << ts.buf.size() << " views; annex now "
                  << annex_.size() << "\n";
    }
-    /// TRACES: AR-018, AR-024 | SR-005
+    static int plurality_actor(const TrackState& ts) {
-    /// The store's weakest pairwise P(same person) — the band's lower bound
+        int best = -1, best_votes = 0;
-    /// asked of every pair, not just of the best match at the door.
+        for (const auto& [ai, v] : ts.actor_votes) {
-    ///
+            if (v > best_votes) { best_votes = v; best = ai; }
-    /// `admit` compares a newcomer against its *closest* existing member, so a
+        }
-    /// track that drifts gradually can chain A→B→C with every step inside the
+        return best;
-    /// band while A and C are strangers. That is precisely the shape a track-ID
+    }
-    /// collision takes when two people are merged over a slow pan, so the bound
+
-    /// is re-asked here across all pairs before anything reaches an actor's
+    // Spread = 1 − min pairwise cosine similarity over the buffer (0 when <2).
-    /// annex. Same bound, same probability space — not a second constant.
+    static float buffer_spread(const std::vector<BufEntry>& buf) {
-    ///
+        float min_sim = std::numeric_limits<float>::max();
    /// A store of one has no pair to disagree; it is coherent by construction,
    /// hence 1.
    float store_coherence(const std::vector<BufEntry>& buf) const {
        float worst = std::numeric_limits<float>::max();
        for (size_t i = 0; i < buf.size(); ++i)
            for (size_t j = i + 1; j < buf.size(); ++j)
-                worst = std::min(worst,
+                min_sim = std::min(min_sim, cosine_similarity(buf[i].emb, buf[j].emb));
-                                 calibrate_(cosine_similarity(buf[i].emb, buf[j].emb)));
+        if (min_sim == std::numeric_limits<float>::max()) return 0.f;
-        if (worst == std::numeric_limits<float>::max()) return 1.f;
+        return 1.f - min_sim;
        return worst;
    }
    void dump_mugshot(int track_id, int actor, int idx, const BufEntry& be) {
 #ifdef SAE_DEBUG
        char name[64];
-        std::snprintf(name, sizeof(name), "trk%d_actor%d_%d_p%.3f.jpg",
+        std::snprintf(name, sizeof(name), "trk%d_actor%d_%d_sim%.3f.jpg",
-                      track_id, actor, idx, be.gal_p);
+                      track_id, actor, idx, be.gal_sim);
        cv::imwrite((std::filesystem::path(debug_dir_) / name).string(), be.crop);
 #else
        (void)track_id; (void)actor; (void)idx; (void)be;
 #endif
    }
    /// cosine → P(same person). The one probability space the pipeline reasons
    /// in; see gallery_calibration.hpp's same_person_probability. Never default
    /// constructed to an identity-ish stand-in — see set_calibration.
    std::function<float(float)> calibrate_;
    std::size_t             rejected_{0};   ///< admissions refused by the band
    bool                    enabled_;
    int                     buffer_size_;
-    float                   band_lo_;       ///< AR-018, from cfg.expand_band_lo
+    float                   novelty_sim_;
-    float                   band_hi_;       ///< AR-018, from cfg.expand_band_hi
+    float                   spread_max_;
    int                     min_anchor_frames_;
    std::string             debug_dir_;
    std::map<int, TrackState> tracks_;
-
+    std::vector<AnnexEntry>   annex_;
    /// TRACES: AR-026 | SR-001
    /// Contiguous annex matrix and its parallel actor index. `drained_` marks
    /// how much of it the similarity engine already holds.
    static constexpr int kEmbDim = 512;
    std::vector<float>        annex_emb_;     ///< annex_size() × 512, row-major
    std::vector<int>          annex_actor_;   ///< actor index per annex row
    int                       drained_{0};
 };
@@ -15,15 +15,6 @@
 // by CMake (SAE_GEMM_BACKEND); backends/gemm_backend.cpp provides
 // make_similarity_engine(). The core matcher node sees only this interface and
 // holds no CUDA/HIP/BLAS headers.
 //
 // TRACES: AR-026 | SR-001
 // The resident matrix GROWS. Per-film expansion (AR-018/AR-019) promotes new
 // reference views mid-film, and those have to be scored by the same multiply as
 // the baked references rather than by a side loop — "this set is small" is not
 // an exception, because the annex grows with cast size and film length. Rows are
 // therefore appended to the resident matrix and the next compute() covers baked
 // and promoted references alike, in one GEMM. The deferred pass (AR-020) then
 // inherits a single contiguous operand to score the TBI queue against.
 struct ISimilarityEngine {
    virtual ~ISimilarityEngine() = default;
@@ -31,23 +22,11 @@ struct ISimilarityEngine {
    // Largest n_faces accepted by compute() per call (bounds GPU buffer sizes).
    virtual int max_faces() const = 0;
    // Rows currently resident: the baked gallery plus every appended promotion.
    // This is compute()'s column stride, and it changes as rows are appended —
    // read it per call rather than caching it across frames.
    virtual int n_gallery() const = 0;
    /// TRACES: AR-026 | SR-001
    /// Append n_rows unit-norm embeddings (row-major, 512 floats each) to the
    /// resident matrix. Amortised O(1) per row: capacity grows geometrically, so
    /// a promotion does not re-upload the gallery. Invalidates any pointer
    /// previously returned by compute().
    virtual void append_rows(const float* rows_row_major, int n_rows) = 0;
    // Compute similarities for n_faces query embeddings.
    // query_row_major: n_faces × 512, row fi at query + fi*512.
    // Returns a pointer to host memory holding S column-major: the gallery
-    // similarities for face fi start at result + fi*n_gallery(). The pointer is
+    // similarities for face fi start at result + fi*n_gallery. The pointer is
-    // owned by the engine and valid until the next compute() or append_rows().
+    // owned by the engine and valid until the next compute() call.
    virtual const float* compute(const float* query_row_major, int n_faces) = 0;
 };
@@ -1,38 +1,11 @@
-// sae_kpn — run the real downstream pipeline inside a Python-assembled KPN
+// sae_kpn — run the real downstream pipeline nodes (face_tracker, identity_matcher,
-// network, fed by a Python HDF5 replay source. Lets a parameter sweep re-run the
+// scene_tracker) inside a Python-assembled KPN network, fed by a Python HDF5 replay
-// exact C++ tracking/matching/presence logic over dumped embeddings — no video
+// source. Lets a parameter sweep re-run the exact C++ matching/tracking logic over
-// decode, no GPU — with different Config knobs each run.
+// dumped embeddings — no video decode, no GPU — with different Config knobs each run.
 //
 /// TRACES: VR-011, VR-002 | PR-002
 //
 // **The whole chain is C++, including the sink.** That is the VR-011 change and
 // it is the point of the requirement: replay must drive the real nodes, not a
 // reimplementation. Two things were wrong before.
 //
 //   1. It did not compile. `add_face_tracker` built `FaceTrackerFunc` from a
 //      Config alone, and the tracker has required a TrackRegistry and a
 //      calibration since AR-007/AR-008 moved association into probability
 //      space. Any .so in a stale build/ predates that.
 //
 //   2. 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 now builds a window from a
 //      TrackRegistry claim: 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 had the same root cause, which is why this is one binding and not three.
 // 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 a factory-per-node API cannot express
 // it. `add_pipeline` mirrors main.cpp exactly and is the only way to build the
 // chain, so the ordering cannot be got wrong again from Python.
 //
 // Boundary types (cross the Python seam):
 //   EmbeddedSceneFrame  IN   (built by the Python replay source from HDF5 arrays)
-//   SceneAnnotation     OUT  (optional tee for per-frame debug rendering only —
+//   SceneAnnotation     OUT  (read by the Python sink → presence JSON)
 //                             the presence output is written by the C++ sink)
 // Intermediate types (TrackedSceneFrame, MatchedSceneFrame) flow C++→C++ only, but
 // still need channel factories + converters registered so PyNetwork can wire them.
@@ -42,14 +15,10 @@
 #include "types.hpp"
 #include "config.hpp"
 #include "gallery/embedder_stamp.hpp"
 #include "gallery/gallery_store.hpp"
 #include "nodes/face_tracker_node.hpp"
 #include "nodes/identity_matcher_node.hpp"
-#include "nodes/frame_annotation_node.hpp"
+#include "nodes/scene_tracker_node.hpp"
 #include "nodes/result_sink_node.hpp"
 #include "track_registry.hpp"
 #include "evidence_discount.hpp"
 #include <nanobind/nanobind.h>
 #include <nanobind/ndarray.h>
@@ -57,61 +26,16 @@
 #include <nanobind/stl/vector.h>
 #include <nanobind/stl/map.h>
 #include <atomic>
 #include <map>
 #include <memory>
 #include <optional>
 #include <variant>
 namespace nb = nanobind;
 using namespace nb::literals;
 // ── ReplaySession ─────────────────────────────────────────────────────────────
 /// TRACES: VR-011 | PR-002
 /// State the network's nodes reference but do not own.
 ///
 /// ResultSinkFunc holds `std::atomic<bool>&`, exactly as it does under main(),
 /// where it is a stack local in a function that outlives the pipeline. There is
 /// no such frame here -- the network is built and torn down from Python -- so
 /// the flag lives in a session held for the network's lifetime and released
 /// explicitly. The registry is here for the same reason: the sink's claim
 /// callback captures it.
 struct ReplaySession {
    /// Owns the Config, and must. ResultSinkFunc holds `const Config&` -- under
    /// main() that is a stack local in a frame which outlives the pipeline, so
    /// the reference is fine there. There is no such frame here: the network is
    /// built inside a binding call and torn down from Python, so a Config local
    /// to add_pipeline dies the moment it returns and the sink is left reading
    /// freed memory. It presented as an empty output_path -- the sink announced
    /// `[result_sink] writing ` and wrote nothing.
    Config                         cfg;
    std::atomic<bool>              done{false};
    std::shared_ptr<TrackRegistry> registry;
 };
 // Function-local static so ordering against other translation units cannot bite.
 inline std::map<void*, std::shared_ptr<ReplaySession>>& sessions() {
    static std::map<void*, std::shared_ptr<ReplaySession>> s;
    return s;
 }
 // The variant spanning every type that flows on a channel in the replay chain.
 using SaeVariant = std::variant<EmbeddedSceneFrame, TrackedSceneFrame,
                                MatchedSceneFrame, SceneAnnotation>;
 // ── Node wrapper aliases ──────────────────────────────────────────────────────
 // Named once so add_pipeline and the runtime setters cannot disagree about a
 // node's port names: a mismatch there is a dynamic_cast that returns null, i.e.
 // a runtime setter that silently does nothing.
 using MatcherWrap = kpn::ObjectVariantNodeWrapper<
    IdentityMatcherFunc, SaeVariant, kpn::in<"tracked">,  kpn::out<"matched">>;
 using TrackerWrap = kpn::ObjectVariantNodeWrapper<
    FaceTrackerFunc,     SaeVariant, kpn::in<"embedded">, kpn::out<"tracked">>;
 using AnnotWrap   = kpn::ObjectVariantNodeWrapper<
    FrameAnnotationFunc, SaeVariant, kpn::in<"matched">,  kpn::out<"annotation">>;
 using SinkWrap    = kpn::ObjectVariantNodeWrapper<
    ResultSinkFunc,      SaeVariant, kpn::in<"annotation">, kpn::out<>>;
 // ── Converters ─────────────────────────────────────────────────────────────────
 // Only EmbeddedSceneFrame (in) and SceneAnnotation (out) actually cross the seam;
 // the two intermediates get identity-ish stubs (never converted in practice) so the
@@ -136,8 +60,6 @@ template<> struct PythonConverter<EmbeddedSceneFrame> {
        ef.source.frame_idx     = d.contains("frame_idx") ? nb::cast<int64_t>(d["frame_idx"]) : -1;
        ef.source.eof           = d.contains("eof") ? nb::cast<bool>(d["eof"]) : false;
        ef.source.is_cut        = d.contains("is_cut") ? nb::cast<bool>(d["is_cut"]) : false;
        ef.source.is_scene_boundary = d.contains("is_scene_boundary")
                                    ? nb::cast<bool>(d["is_scene_boundary"]) : false;
        if (ef.source.eof) return ef;
        // faces: (N,4) bbox, (N,10) landmarks, (N,) confidence, (N,512) embeddings
@@ -146,22 +68,6 @@ template<> struct PythonConverter<EmbeddedSceneFrame> {
        auto conf = nb::cast<nb::ndarray<float, nb::shape<-1>, nb::c_contig>>(d["confidence"]);
        auto emb  = nb::cast<nb::ndarray<float, nb::shape<-1, 512>, nb::c_contig>>(d["embeddings"]);
        // AR-028 quality vector. Optional because a v1 dump predates it — absent
        // leaves the DetectedFace sentinels at -1, which reads as *unscored*, not
        // as a bad face. There is no live aligner on this path to recompute it:
        // the replay starts at the embedded-frame channel, so what the dump does
        // not carry is genuinely gone.
        //
        // Held in named locals, like the four above, because the ndarray owns the
        // reference that keeps the buffer alive — reading .data() off a temporary
        // would leave the pointer dangling at the end of the statement.
        using FloatCol = nb::ndarray<float, nb::shape<-1>, nb::c_contig>;
        std::optional<FloatCol> sharp_col, resid_col;
        if (d.contains("sharpness"))          sharp_col = nb::cast<FloatCol>(d["sharpness"]);
        if (d.contains("alignment_residual")) resid_col = nb::cast<FloatCol>(d["alignment_residual"]);
        const float* sp = sharp_col ? sharp_col->data() : nullptr;
        const float* rp = resid_col ? resid_col->data() : nullptr;
        const size_t n = bbox.shape(0);
        ef.faces.reserve(n);
        ef.embeddings.reserve(n);
@@ -175,8 +81,6 @@ template<> struct PythonConverter<EmbeddedSceneFrame> {
            for (int k = 0; k < 5; ++k)
                f.landmarks[k] = cv::Point2f(lp[i*10 + k*2], lp[i*10 + k*2 + 1]);
            f.confidence = cp[i];
            if (sp) f.sharpness          = sp[i];
            if (rp) f.alignment_residual = rp[i];
            ef.faces.push_back(f);
            Embedding e;
@@ -244,67 +148,28 @@ static Config config_from_dict(nb::dict d) {
    // identity matcher
    getf("match_prior",       cfg.match_prior);
    getf("prob_threshold",    cfg.prob_threshold);
    getf("match_threshold",   cfg.match_threshold);
    getf("match_ratio",       cfg.match_ratio);
    getf("match_ratio_ceil",  cfg.match_ratio_ceil);
    // face tracker
    getf("track_alpha",           cfg.track_alpha);
    getf("track_min_iou",         cfg.track_min_iou);
-    getf("track_assoc_min_prob",  cfg.track_assoc_min_prob);
+    getf("track_max_embed_dist",  cfg.track_max_embed_dist);
-    getd("track_extinction_sec",  cfg.track_extinction_sec);
+    geti("track_max_frames_missing", cfg.track_max_frames_missing);
-    // AR-025: swept knobs, previously unreachable from any config.
+    getf("cut_revive_sim",        cfg.cut_revive_sim);
-    getf("ownership_logodds",     cfg.ownership_logodds);
+    geti("cut_inactive_max_frames", cfg.cut_inactive_max_frames);
-    getf("evidence_rho_max",      cfg.evidence_rho_max);
+    // scene tracker
-    getf("evidence_admit_below",  cfg.evidence_admit_below);
+    getd("extinction_sec", cfg.extinction_sec);
-    geti("evidence_max_views",    cfg.evidence_max_views);
+    getd("anneal_sec",     cfg.anneal_sec);
    // gallery expansion (usually off for sweeps; expose so it can be toggled)
    if (d.contains("expand_gallery")) cfg.expand_gallery = nb::cast<bool>(d["expand_gallery"]);
    // AR-018: banded admission bounds for the per-film annex, in probability
    // space. Reachable from a sweep — the config comment asks for both to be
    // swept, and they are ignored unless expand_gallery is on. See track_gallery.hpp.
    getf("expand_band_lo",        cfg.expand_band_lo);
    getf("expand_band_hi",        cfg.expand_band_hi);
    // Presence derivation. Accepts a string ("flood"/"track_extent") or a
    // number (DE only produces floats: >=0.5 → flood) so the sweep can toggle
    // it as a sixth knob. flood snaps to boundaries in the replayed frames
    // (is_scene_boundary if present, else is_cut).
    if (d.contains("presence_mode")) {
        const auto& pm = d["presence_mode"];
        bool flood = false;
        if (nb::isinstance<nb::str>(pm)) flood = (nb::cast<std::string>(pm) == "flood");
        else                             flood = (nb::cast<double>(pm) >= 0.5);
        cfg.presence_mode = flood ? PresenceMode::flood : PresenceMode::track_extent;
    }
    /// TRACES: GR-004 | SR-001
    if (d.contains("require_gallery_stamp"))
        cfg.require_gallery_stamp = nb::cast<bool>(d["require_gallery_stamp"]);
    /// TRACES: VR-011 | IR-001 | PR-002 | SR-003
    // The sink is a real node in this network now, so it needs the two things
    // that decide what it writes and where. Both used to be irrelevant here
    // because the replay never had a sink -- Python rebuilt presence instead,
    // which is the reimplementation VR-002 forbids and VR-011 removes.
    if (d.contains("output_path"))
        cfg.output_path = nb::cast<std::string>(d["output_path"]);
    if (d.contains("verbosity")) {
        const int v = nb::cast<int>(d["verbosity"]);
        cfg.verbosity = v == 2 ? Verbosity::xray
                      : v == 1 ? Verbosity::standard
                               : Verbosity::minimal;
    }
    // Reported verbatim in the truth file's extraction block, so a replayed
    // manifest says which gallery scope produced it (IR-002).
    if (d.contains("gallery_scope"))
        cfg.gallery_scope = nb::cast<std::string>(d["gallery_scope"]);
    if (d.contains("sample_fps"))
        cfg.sample_fps = nb::cast<float>(d["sample_fps"]);
    if (d.contains("movie_path"))
        cfg.movie_path = nb::cast<std::string>(d["movie_path"]);
    return cfg;
 }
 using Net = kpn::python::PyNetwork<SaeVariant>;
 NB_MODULE(sae_kpn, m) {
-    m.doc() = "Real KPN downstream nodes (tracker/matcher/frame_annotation) for Python replay sweeps";
+    m.doc() = "Real KPN downstream nodes (tracker/matcher/scene_tracker) for Python replay sweeps";
    kpn::python::register_py_network<SaeVariant>(m, "Network");
@@ -337,158 +202,56 @@ NB_MODULE(sae_kpn, m) {
                            std::move(outs), cap);
    }, "net"_a, "name"_a, "callable"_a, "inputs"_a, "outputs"_a, "capacity"_a = 5);
-    // ── The pipeline ────────────────────────────────────────────────────────────
+    // ── Real node factories ─────────────────────────────────────────────────────
-    /// TRACES: VR-011, VR-002 | DP-001 | PR-002, PR-004
+    m.def("add_face_tracker", [](Net& net, std::string name, nb::dict cfg_dict, std::size_t cap) {
    ///
    /// One call builds the whole downstream chain, in the one order that works:
    ///
    ///     matcher (fits the calibration)
    ///       -> registry (needs a discounter built from it)
    ///         -> tracker (needs both)
    ///           -> frame_annotation
    ///             -> result_sink (needs the registry's claims)
    ///
    /// This replaces add_face_tracker / add_identity_matcher / add_frame_annotation.
    /// They were separate because the network is assembled node by node from
    /// Python -- and that is exactly how the seam broke: the tracker's dependency
    /// on a calibration that only exists once the matcher is built cannot be
    /// expressed as three independent factories, so the tracker factory kept
    /// constructing FaceTrackerFunc{cfg} against a signature that no longer
    /// existed. A binding that cannot represent the order will eventually be
    /// called in the wrong one.
    ///
    /// DP-001 -- "modes are front-ends and must not fork pipeline logic" -- is
    /// the requirement this serves. The replay harness is a front-end. Its job is
    /// to supply frames and read the result, not to re-derive presence.
    m.def("add_pipeline", [](Net& net, std::string gallery_path, nb::dict cfg_dict,
                             std::size_t cap, std::string embedder_model,
                             std::string embedder_sha256) {
        Config cfg = config_from_dict(cfg_dict);
-        cfg.gallery_path = gallery_path;  // so a refreshed calibration persists back
+        auto node = std::make_shared<kpn::ObjectVariantNodeWrapper<
            FaceTrackerFunc, SaeVariant, kpn::in<"embedded">, kpn::out<"tracked">>>(cap, cfg);
        net.add(std::move(name), std::move(node));
    }, "net"_a, "name"_a, "config"_a, "capacity"_a = 16);
    m.def("add_identity_matcher", [](Net& net, std::string name, std::string gallery_path,
                                     nb::dict cfg_dict, std::size_t cap) {
        Config cfg = config_from_dict(cfg_dict);
        cfg.gallery_path = gallery_path;  // needed to persist refreshed calibration back
        // Cache loaded galleries by path so a threshold sweep (many networks, same
-        // gallery) pays the parse once. The matcher holds a const ref; the cache
+        // gallery) pays the ~24s JSON parse only once. The matcher holds a const
-        // keeps the gallery alive for the process lifetime.
+        // ref; the cache keeps the gallery alive for the process lifetime.
        static std::map<std::string, std::shared_ptr<ActorGallery>> cache;
        auto it = cache.find(gallery_path);
        if (it == cache.end())
            it = cache.emplace(gallery_path,
                     std::make_shared<ActorGallery>(load_gallery(gallery_path))).first;
        auto node = std::make_shared<kpn::ObjectVariantNodeWrapper<
            IdentityMatcherFunc, SaeVariant, kpn::in<"tracked">, kpn::out<"matched">>>(
            cap, *it->second, cfg);
        net.add(std::move(name), std::move(node));
    }, "net"_a, "name"_a, "gallery"_a, "config"_a, "capacity"_a = 16);
-        /// TRACES: GR-004 | SR-001
+    m.def("add_scene_tracker", [](Net& net, std::string name, nb::dict cfg_dict, std::size_t cap) {
-        // embedder_model / embedder_sha256 identify whatever produced the
+        Config cfg = config_from_dict(cfg_dict);
-        // embeddings that will be fed in. In a replay those come from the dump's
+        auto node = std::make_shared<kpn::ObjectVariantNodeWrapper<
-        // own stamp: there is no live embedder here, so the dump *is* the
+            SceneTrackerFunc, SaeVariant, kpn::in<"matched">, kpn::out<"annotation">>>(cap, cfg);
-        // embedder as far as this gallery is concerned. Checked on every
+        net.add(std::move(name), std::move(node));
-        // construction, not only on a cache miss -- one process may replay
+    }, "net"_a, "name"_a, "config"_a, "capacity"_a = 16);
        // several dumps against one cached gallery.
        EmbedderStamp feeding;
        feeding.model_name   = std::move(embedder_model);
        feeding.model_sha256 = std::move(embedder_sha256);
        enforce_embedder_stamp(it->second->embedder, feeding, gallery_path,
                               feeding.model_name.empty()
                                   ? "embeddings fed into this network"
                                   : feeding.model_name,
                               cfg.require_gallery_stamp);
        // 1. Matcher first: its constructor fits (or loads) the calibration.
        auto matcher = std::make_shared<MatcherWrap>(cap, *it->second, cfg);
        // 2. The calibration every other stage must decide in (AR-024).
        auto same_person = same_person_probability(matcher->functor().calibration());
        // 3. Registry + discounter, from Config (AR-025).
        TrackRegistry::Config reg_cfg;
        reg_cfg.track_extinction_sec = cfg.track_extinction_sec;
        reg_cfg.ownership_logodds    = cfg.ownership_logodds;
        EvidenceDiscounter::Config disc_cfg;
        disc_cfg.max_views   = cfg.evidence_max_views;
        disc_cfg.admit_below = cfg.evidence_admit_below;
        disc_cfg.rho_max     = cfg.evidence_rho_max;
        auto registry = std::make_shared<TrackRegistry>(
            reg_cfg, EvidenceDiscounter(same_person, disc_cfg));
        matcher->functor().set_registry(registry);
        // 4. Tracker, which needs both.
        auto tracker = std::make_shared<TrackerWrap>(cap, cfg, registry, same_person);
        // 5. Projection, stateless.
        auto annot = std::make_shared<AnnotWrap>(cap);
        // 6. The real sink. `done` outlives the network via the session below;
        //    ResultSinkFunc holds it by reference, as it does in main.cpp.
        auto session = std::make_shared<ReplaySession>();
        session->cfg      = cfg;          // the sink holds this by reference
        session->registry = registry;
        auto sink = std::make_shared<SinkWrap>(cap, session->cfg, session->done);
        /// TRACES: AR-012, AR-016 | IR-003 | SR-002
        // The claim path, identical to main.cpp's. Without the flush hook every
        // track still live at EOF is silently dropped -- which in a replay is
        // most of the closing scene, and reads as a recognition miss rather than
        // as a missing wire.
        ResultSinkFunc& sink_fn = sink->functor();
        registry->on_track_dead([&sink_fn](const DeadTrack& d) { sink_fn.add_claim(d); });
        sink_fn.set_pre_write_hook([registry](double last_ts) { registry->flush(last_ts); });
        net.add("tracker", tracker);
        net.add("matcher", matcher);
        net.add("annotation", annot);
        net.add("sink", sink);
        // Keyed by network so release_pipeline can free it. Not a leak-by-design:
        // a sweep builds one network per replay, and the sink accumulates every
        // annotation, so holding these forever would grow with films x configs.
        sessions()[&net] = session;
    }, "net"_a, "gallery"_a, "config"_a, "capacity"_a = 16,
       "embedder_model"_a = "", "embedder_sha256"_a = "");
    /// Drop the session for a network. Idempotent. Call after net.stop(); not
    /// calling it holds one registry and one sink's accumulated frames per
    /// replay, which a long sweep will notice.
    m.def("release_pipeline", [](Net& net) { sessions().erase(&net); }, "net"_a);
    /// TRACES: VR-011 | AR-025 | PR-002
    /// The registry's own count of how often it was wrong, exposed so a replay
    /// can fail on it instead of returning a plausible-looking empty answer.
    ///
    /// `dropped_votes` is the one that matters here and it earned its keep
    /// immediately. A vote lands on a track the registry has already reaped when
    /// the matcher lags the tracker by more than track_extinction_sec of film.
    /// In scene_analyze that cannot happen -- channels are 16-64 deep, so
    /// backpressure pins the two nodes within a few frames of each other. This
    /// harness sized every channel to the whole film to avoid a PyNode overflow
    /// drop, which removed the backpressure entirely: the tracker ran the film
    /// to the end while the matcher was still in its first minute, every vote
    /// arrived after its track was gone, no track was ever owned, and the run
    /// produced zero presence windows while cheerfully reporting 1647 frames
    /// with an identified face.
    m.def("pipeline_diagnostics", [](Net& net) {
        nb::dict d;
        auto it = sessions().find(&net);
        if (it == sessions().end() || !it->second->registry) return d;
        const auto& r = *it->second->registry;
        d["dropped_votes"]   = r.dropped_votes();
        d["belief_swaps"]    = r.belief_swaps();
        d["actor_conflicts"] = r.actor_conflicts();
        d["live_tracks"]     = static_cast<int>(r.live());
        return d;
    }, "net"_a);
    /// True once the sink has written its output. The sink flushes on the EOF
    /// annotation, so a caller that reads the file before this is racing it.
    m.def("pipeline_done", [](Net& net) {
        auto it = sessions().find(&net);
        return it != sessions().end()
            && it->second->done.load(std::memory_order_acquire);
    }, "net"_a);
    // ── Runtime setters (persistent-pipeline reuse across a threshold sweep) ─────
    // Build the network once, then change thresholds between replays — no rebuild,
    // no teardown (which is where the ROCm deadlock lives), no gallery reload.
    using MatcherWrap = kpn::ObjectVariantNodeWrapper<
        IdentityMatcherFunc, SaeVariant, kpn::in<"tracked">, kpn::out<"matched">>;
    using SceneWrap = kpn::ObjectVariantNodeWrapper<
        SceneTrackerFunc, SaeVariant, kpn::in<"matched">, kpn::out<"annotation">>;
    m.def("set_prob_threshold", [](Net& net, std::string name, float t) {
        auto* w = dynamic_cast<MatcherWrap*>(net.node_ptr(name));
        if (!w) throw std::runtime_error("set_prob_threshold: '" + name + "' is not an identity_matcher");
        w->functor().set_prob_threshold(t);
    }, "net"_a, "name"_a, "value"_a);
    m.def("set_extinction_sec", [](Net& net, std::string name, double s) {
        auto* w = dynamic_cast<SceneWrap*>(net.node_ptr(name));
        if (!w) throw std::runtime_error("set_extinction_sec: '" + name + "' is not a scene_tracker");
        w->functor().set_extinction_sec(s);
    }, "net"_a, "name"_a, "value"_a);
 }
@@ -1,18 +1,14 @@
 // scene_analyze — identify actors in a movie using a KPN pipeline
 //
 // TRACES: DP-001, DP-002 | PR-004
 // One analysis core; the CLI is a front-end over it and must not fork pipeline
 // logic. Other deployment modes (DP-003, DP-004) wrap this same core.
 //
 // KPN topology (release build):
 //
 //   [frame_source] ──Frame──► [face_detector] ──SceneFrame──► [face_aligner]
 //          ──AlignedSceneFrame──► [embedder] ──EmbeddedSceneFrame──►
-//          [identity_matcher] ──MatchedSceneFrame──► [frame_annotation]
+//          [identity_matcher] ──MatchedSceneFrame──► [scene_tracker]
 //          ──SceneAnnotation──► [result_sink]
 //
 // Debug build (SAE_DEBUG=1):
-//   [identity_matcher] output fans out to both [frame_annotation] AND [debug_renderer].
+//   [identity_matcher] output fans out to both [scene_tracker] AND [debug_renderer].
 //   FanoutNode<MatchedSceneFrame, 2> is auto-inserted by make_network().
 //
 // Usage:
@@ -22,7 +18,8 @@
 //   --output <path>         output JSON (default: annotations.json)
 //   --fps <N>               sample rate in frames/sec (default: 1.0)
 //   --verbosity <0|1|2>     0=minimal, 1=standard, 2=jellyfin-xray (default: 0)
-//   --prob-threshold <f>    posterior P(match) to accept (default: 0.754)
+//   --match-threshold <f>   cosine dist threshold (default: 0.45)
 //   --extinction <f>        actor extinction window in seconds (default: 5.0)
 //   --detector <path>       override SCRFD detector model path
 //   --arcface <path>        override ArcFace model path
 //   --scene-detect          enable TransNetV2 shot-boundary detection (dense decode;
@@ -31,37 +28,23 @@
 //   --scene-detector-engine <path> pre-built TransNetV2 TRT engine (TRT backend)
 //   --scene-threshold <f>   boundary sigmoid prob above this → cut (default: 0.60)
 //   --scene-stride <N>      frames between TransNetV2 windows (default: 50, ≤100)
-//   --scene-decode-fps <f>  dense decode rate in scene-detect mode (default: 0 =
+//   --scene-decode-fps <f>  dense decode rate in scene-detect mode (default: 12;
-//                           native, the only rate TransNetV2 is calibrated for;
+//                           0 = native fps). Lower = faster, coarser boundaries.
 //                           AR-011). Lowering it runs the model off-distribution.
 //   --dense-scale <f>       downscale decoded frames in scene-detect mode (0<f≤1,
 //                           default 1=off). Speeds decode; keep ≥0.5 on 1080p.
-//   --max-faces <N>         max faces kept per frame (default: 0 = uncapped)
+//   --max-faces <N>         max faces kept per frame (default: 10)
 //   --ownership-logodds <f> belief needed to own a track (default: 2.0 ≈ P 0.88).
 //                           Below it a track makes no presence claim at all.
 //   --evidence-rho-max <f>  ceiling on correlation between two observations of
 //                           one track (default: 0.5 = a repeated view is worth
 //                           at most two independent ones). AR-025.
 //   --evidence-admit-below <p>  P(same view) under this counts as a new look
 //   --evidence-max-views <N>    distinct views remembered per track
 //   --expand-gallery        enable per-film gallery expansion from track continuity
 //   --expand-buffer <N>     per-track diversity buffer size (default: 20)
-//   --expand-band-lo <p>    store admission floor, P(same person) (default: 0.90)
+//   --expand-novelty-sim <f>  promote only views with best sim < f (default: 0.55)
-//   --expand-band-hi <p>    store admission ceiling, P(same person) (default: 0.95)
+//   --expand-spread-max <f>   reject track if buffer spread > f (default: 0.60)
 //   --expand-min-anchor <N>   accepted frames before a track confirms (default: 3)
 //   --expand-debug-dir <p>  dump promoted mugshots + embeddings here (SAE_DEBUG)
 //   --benchmark <path>      write a per-node timing + bottleneck report (JSON) and
 //                           print it at shutdown. Says where the run's time went
 //                           and which node is pacing it. See src/benchmark.hpp.
 //   --benchmark-interval-ms <N>  channel-occupancy sampling period (default: 100)
 //   (SAE_DEBUG only)
 //   --debug-dir <path>      debug frames output dir (default: debug_frames)
 //   --crop-context <f>      bbox expansion factor for context crops (default: 1.5)
 #include "benchmark.hpp"
 #include "config.hpp"
 #include "types.hpp"
 #include "gallery/embedder_stamp.hpp"
 #include "gallery/gallery_store.hpp"
 #include "nodes/frame_source_node.hpp"
 #include "nodes/camera_position_change_detector_node.hpp"
@@ -70,11 +53,8 @@
 #include "nodes/embedder_node.hpp"
 #include "nodes/face_tracker_node.hpp"
 #include "nodes/identity_matcher_node.hpp"
-#include "nodes/frame_annotation_node.hpp"
+#include "nodes/scene_tracker_node.hpp"
 #include "inference/scene_detector.hpp"   // ISceneDetector::kWindow, for the join-depth derivation
 #include "nodes/scene_detector_node.hpp"
 #include "scene_boundaries.hpp"
 #include "nodes/scene_boundary_annotator_node.hpp"
 #include "nodes/result_sink_node.hpp"
 #include "nodes/embedding_dump_node.hpp"
 #ifdef SAE_DEBUG
@@ -83,16 +63,9 @@
 #include <kpn/kpn.hpp>
 #include <opencv2/core/utility.hpp>   // cv::setNumThreads (SAE_CV_THREADS)
 #include <algorithm>
 #include <atomic>
 #include <chrono>
 #include <cmath>
 #include <csignal>
 #include <cstdlib>
 #include <cstring>
 #include <fstream>
 #include <iostream>
 #include <map>
 #include <mutex>
@@ -103,86 +76,6 @@
 // ── CLI parsing ───────────────────────────────────────────────────────────────
 /// TRACES: AR-010, AR-004 | SR-002
 /// Depth of the dense branch's own input queue. Part of how far behind the
 /// fanout head TransNetV2 can be, and therefore an input to the join depth.
 static constexpr std::size_t kSceneInputDepth = 128;
 /// TRACES: AR-010, AR-004 | SR-002
 /// How far the sampled branch must trail the dense one, in seconds of film.
 ///
 /// TransNetV2 needs kWindow (100) dense frames before it can score any of
 /// them, and its input queue can hold kSceneInputDepth more, so in the worst
 /// case it has scored only up to (kSceneInputDepth + kWindow) frames behind
 /// whatever the fanout has just delivered. The face branch must be at least
 /// that far behind, or `scene_annotate` asks about frames nobody has looked at
 /// yet. Backpressure turns depth into lag: the fanout blocks on the slower
 /// branch rather than dropping, so the dense branch simply runs ahead.
 ///
 /// Divided by a *lower bound* on native frame rate, because a slower source
 /// makes the same frame count span more film — 24 fps is the floor for the
 /// material this runs on, so it is the conservative choice.
 static constexpr double kMinNativeFps    = 24.0;
 static constexpr double kSceneJoinLagSec =
    (kSceneInputDepth + ISceneDetector::kWindow) / kMinNativeFps;   // ~9.5 s
 /// Margin over that minimum, for jitter in TransNetV2's inference time.
 static constexpr double kSceneJoinSafety = 2.0;
 /// TRACES: AR-004 | SR-002
 /// Slots the sampled branch needs to hold `kSceneJoinLagSec` of film.
 ///
 /// This used to be a constant 256, which is the whole bug: the requirement is a
 /// span of *film*, and the slots needed to hold it depend on `sample_fps`.
 /// Pinned at 256 it was ~256 s of lag at 1 fps — 27x what the join needs — and
 /// nothing recomputed it if `sample_fps` changed, so the one number the join's
 /// correctness rests on drifted silently with an unrelated knob.
 ///
 /// It is also the largest single memory item in the pipeline. Every message
 /// embeds `Frame source`, so a slot on this branch holds a full decoded image:
 /// 256 of them is ~1.5 GB at 1080p, against ~110 MB for the derived depth at
 /// 1 fps. See AR-004 — capacity is counted in items, and only the byte figure
 /// (now correct, see types.hpp) shows what a slot really costs.
 static std::size_t scene_join_depth(float sample_fps) {
    const double slots = kSceneJoinSafety * kSceneJoinLagSec * sample_fps;
    // Floor of 16: below that the queue stops absorbing ordinary jitter and
    // starts throttling the fanout, which would slow the dense branch it
    // exists to let run ahead.
    return std::max<std::size_t>(16, static_cast<std::size_t>(std::ceil(slots)));
 }
 /// TRACES: AR-004 | SR-002
 /// The decimator's input, on the *full-rate* stream.
 ///
 /// This was also kSceneJoinDepth, which put a 256-slot buffer of full-rate
 /// frames in front of the decimator — and at 1 fps against 24 fps native, 23 of
 /// every 24 of those frames exist only to be discarded a moment later. Holding
 /// ~1.5 GB of decoded images for frames the very next node throws away is the
 /// worst available use of the memory budget.
 ///
 /// A filter is a pass-through, not a reservoir: the lag belongs *after*
 /// decimation, where a slot buys `1/sample_fps` seconds of film instead of
 /// `1/native_fps`. Sized only to keep the decimator fed.
 static constexpr std::size_t kDecimatorInputDepth = 16;
 /// Set when the scene branch is built, so shutdown can report whether the join
 /// actually worked.
 static std::shared_ptr<SceneBoundaries> scene_stats;
 /// TRACES: VR-015 | AR-004 | PR-004
 /// Set by SIGUSR1, serviced by the wait loop. `kill -USR1 <pid>` on a running
 /// or WEDGED run prints the benchmark table immediately — channel occupancy
 /// names the stalled node (full input, empty output) without a debug build or a
 /// debugger, which is the difference between diagnosing the AR-004 hang in
 /// seconds and reproducing it under gdb.
 ///
 /// The handler only stores a flag; all printing happens on the main thread,
 /// since nothing in the report is async-signal-safe.
 static std::atomic<bool> g_dump_request{false};
 extern "C" void sae_on_dump_signal(int) {
    g_dump_request.store(true, std::memory_order_relaxed);
 }
 static Config parse_args(int argc, char** argv) {
    Config cfg;
    cfg.detector_model = kDefaultDetectorModel;
@@ -201,14 +94,11 @@ static Config parse_args(int argc, char** argv) {
        else if (arg("--gallery"))         cfg.gallery_path     = next();
        else if (arg("--output"))          cfg.output_path      = next();
        else if (arg("--dump-embeddings")) cfg.dump_embeddings_path = next();
        else if (arg("--benchmark"))       cfg.benchmark_path    = next();
        else if (arg("--benchmark-interval-ms")) cfg.benchmark_interval_ms = std::stoi(next());
        else if (arg("--fps"))             cfg.sample_fps       = std::stof(next());
        else if (arg("--max-decode-fps"))  cfg.max_decode_fps   = std::stof(next());
        else if (arg("--start"))           cfg.start_sec        = std::stod(next());
        else if (arg("--end"))             cfg.end_sec          = std::stod(next());
        else if (arg("--cut-threshold"))   cfg.cut_threshold    = std::stof(next());
        else if (arg("--presence-mode"))   { std::string m = next(); cfg.presence_mode = (m == "flood") ? PresenceMode::flood : PresenceMode::track_extent; }
        else if (arg("--scene-detect"))         cfg.scene_detect     = true;
        else if (arg("--scene-detector"))       cfg.scene_model      = next();
        else if (arg("--scene-detector-engine")) cfg.scene_engine    = next();
@@ -219,26 +109,28 @@ static Config parse_args(int argc, char** argv) {
        else if (arg("--verbosity"))       { int v = std::stoi(next()); cfg.verbosity = v == 2 ? Verbosity::xray : v == 1 ? Verbosity::standard : Verbosity::minimal; }
        else if (arg("--prior"))           cfg.match_prior      = std::stof(next());
        else if (arg("--prob-threshold"))  cfg.prob_threshold   = std::stof(next());
        else if (arg("--match-threshold")) cfg.match_threshold  = std::stof(next());
        else if (arg("--extinction"))      cfg.extinction_sec   = std::stod(next());
        else if (arg("--detector"))        cfg.detector_model   = next();
        else if (arg("--detector-engine")) cfg.detector_engine  = next();
        else if (arg("--arcface"))         cfg.arcface_model    = next();
        else if (arg("--require-gallery-stamp")) cfg.require_gallery_stamp = true;
        else if (arg("--arcface-engine"))  cfg.arcface_engine   = next();
        else if (arg("--conf"))            cfg.detector_conf    = std::stof(next());
        else if (arg("--max-faces"))       cfg.max_faces        = std::stoi(next());
        else if (arg("--min-face-px"))     cfg.min_face_px      = std::stof(next());
        else if (arg("--ratio"))               cfg.match_ratio            = std::stof(next());
        else if (arg("--ratio-ceil"))          cfg.match_ratio_ceil       = std::stof(next());
        else if (arg("--track-alpha"))         cfg.track_alpha            = std::stof(next());
        else if (arg("--track-min-iou"))       cfg.track_min_iou          = std::stof(next());
-        else if (arg("--track-min-prob"))      cfg.track_assoc_min_prob   = std::stof(next());
+        else if (arg("--track-max-embed"))     cfg.track_max_embed_dist   = std::stof(next());
-        else if (arg("--track-extinction"))    cfg.track_extinction_sec   = std::stod(next());
+        else if (arg("--track-max-missing"))   cfg.track_max_frames_missing = std::stoi(next());
-        else if (arg("--ownership-logodds"))   cfg.ownership_logodds      = std::stof(next());
+        else if (arg("--cut-revive-sim"))      cfg.cut_revive_sim         = std::stof(next());
-        else if (arg("--evidence-rho-max"))    cfg.evidence_rho_max       = std::stof(next());
+        else if (arg("--cut-inactive-max"))    cfg.cut_inactive_max_frames = std::stoi(next());
-        else if (arg("--evidence-admit-below")) cfg.evidence_admit_below  = std::stof(next());
+        else if (arg("--anneal"))              cfg.anneal_sec             = std::stod(next());
        else if (arg("--evidence-max-views"))  cfg.evidence_max_views     = std::stoi(next());
        else if (arg("--expand-gallery"))      cfg.expand_gallery         = true;
        else if (arg("--expand-buffer"))       cfg.expand_buffer_size     = std::stoi(next());
-        else if (arg("--expand-band-lo"))      cfg.expand_band_lo         = std::stof(next());
+        else if (arg("--expand-novelty-sim"))  cfg.expand_novelty_sim     = std::stof(next());
-        else if (arg("--expand-band-hi"))      cfg.expand_band_hi         = std::stof(next());
+        else if (arg("--expand-spread-max"))   cfg.expand_track_spread_max = std::stof(next());
        else if (arg("--expand-min-anchor"))   cfg.expand_min_anchor_frames = std::stoi(next());
        else if (arg("--expand-debug-dir"))    cfg.expand_debug_dir       = next();
        else if (arg("--trt-cache"))           cfg.trt.cache_dir          = next();
@@ -263,21 +155,6 @@ static Config parse_args(int argc, char** argv) {
 // ── Main ──────────────────────────────────────────────────────────────────────
 int main(int argc, char** argv) {
    /// TRACES: VR-015 | PR-004
    // OpenCV here is built against TBB, so cv::parallel_for_ opens an arena of
    // nproc-1 workers (19 on a 20-core box) *on top of* KPN's one thread per
    // node. Two schedulers, neither aware of the other, on the same cores.
    //
    // SAE_CV_THREADS=1 hands concurrency entirely to KPN, which is where this
    // pipeline's parallelism is supposed to come from. Worth measuring rather
    // than assuming: TBB fan-out inside warpAffine is free speed when the
    // pipeline is otherwise idle, so this can cut either way. Unset = default.
    if (const char* t = std::getenv("SAE_CV_THREADS")) {
        const int n = std::atoi(t);
        cv::setNumThreads(n);
        std::cerr << "[opencv] cv::setNumThreads(" << n << ")\n";
    }
    Config cfg;
    try {
        cfg = parse_args(argc, argv);
@@ -290,11 +167,6 @@ int main(int argc, char** argv) {
    ActorGallery gallery;
    try {
        gallery = load_gallery(cfg.gallery_path);
        /// TRACES: GR-004 | SR-001
        // Hard startup error before a single frame is decoded: a gallery built
        // with another embedder yields plausible-looking, meaningless matches.
        verify_gallery_embedder(gallery, cfg.gallery_path, cfg.arcface_model,
                                cfg.require_gallery_stamp);
    } catch (const std::exception& e) {
        std::cerr << "Gallery error: " << e.what() << "\n";
        return 1;
@@ -311,53 +183,10 @@ int main(int argc, char** argv) {
    FaceDetectorFunc                  detector_fn{cfg};
    FaceAlignerFunc                   aligner_fn;
    EmbedderFunc                      embedder_fn{cfg};
-    // Constructed before the tracker: it fits (or loads) the calibration, and
+    FaceTrackerFunc                   ftracker_fn{cfg};
    // the tracker must decide in that same probability space (AR-024).
    IdentityMatcherFunc               matcher_fn {gallery, cfg};
-
+    SceneTrackerFunc                  tracker_fn {cfg};
    /// TRACES: AR-007, AR-008, AR-012, AR-024 | SR-002
    // The registry is created here and shared, not owned by a node: track state
    // is not a stage in the stream, it is state several stages read and write,
    // and its final answer is only known when a track dies.
    auto same_person = same_person_probability(matcher_fn.calibration());
    TrackRegistry::Config reg_cfg;
    reg_cfg.track_extinction_sec = cfg.track_extinction_sec;
    reg_cfg.ownership_logodds    = cfg.ownership_logodds;
    /// TRACES: AR-025 | SR-002
    // The discounter's parameters come from Config now. They used to be
    // in-class defaults reached through the one-argument constructor, so the
    // VR-007 sweep that rho_max's own comment defers to could not vary it.
    EvidenceDiscounter::Config disc_cfg;
    disc_cfg.max_views   = cfg.evidence_max_views;
    disc_cfg.admit_below = cfg.evidence_admit_below;
    disc_cfg.rho_max     = cfg.evidence_rho_max;
    auto registry = std::make_shared<TrackRegistry>(
        reg_cfg, EvidenceDiscounter(same_person, disc_cfg));
    matcher_fn.set_registry(registry);
    FaceTrackerFunc                   ftracker_fn{cfg, registry, same_person};
    FrameAnnotationFunc               tracker_fn {};
    ResultSinkFunc                    sink_fn    {cfg, done};
    /// TRACES: AR-012, AR-016 | IR-002, IR-003 | SR-002
    // A reaped track goes straight to the aggregator, so the registry holds only
    // live tracks and its size is bounded by concurrent on-screen faces rather
    // than growing with the film.
    registry->on_track_dead([&sink_fn](const DeadTrack& d) { sink_fn.add_claim(d); });
    // AR-016: a film ends with faces on screen and those tracks have not timed
    // out. Without this flush the closing scene's cast is silently never
    // emitted — a loss that reads as a recognition miss, not a bookkeeping bug.
    /// TRACES: VR-015 | PR-004
    // Last timestamp the pipeline reached, latched on the way out. It is what
    // turns wall-clock seconds into the number that matters — seconds of film
    // per second of run — and the sink is the only node that knows it.
    std::atomic<double> film_sec{0.0};
    sink_fn.set_pre_write_hook([registry, &film_sec](double last_ts) {
        film_sec.store(last_ts, std::memory_order_release);
        registry->flush(last_ts);
    });
 #ifdef SAE_DEBUG
    DebugRendererFunc   debug_fn   {cfg};
 #endif
@@ -374,7 +203,7 @@ int main(int argc, char** argv) {
    kpn::ObjectNode<EmbedderFunc,        kpn::in<"aligned">,   kpn::out<"embedded">,   "embedder",         0> embedder (embedder_fn,  32);
    kpn::ObjectNode<FaceTrackerFunc,     kpn::in<"embedded">,  kpn::out<"tracked">,    "face_tracker",     0> ftracker (ftracker_fn,  16);
    kpn::ObjectNode<IdentityMatcherFunc, kpn::in<"tracked">,   kpn::out<"matched">,    "identity_matcher", 0> matcher  (matcher_fn,   16);
-    kpn::ObjectNode<FrameAnnotationFunc, kpn::in<"matched">,   kpn::out<"annotation">, "frame_annotation", 0> tracker  (tracker_fn,   16);
+    kpn::ObjectNode<SceneTrackerFunc,    kpn::in<"matched">,   kpn::out<"annotation">, "scene_tracker",    0> tracker  (tracker_fn,   16);
    kpn::ObjectNode<ResultSinkFunc,      kpn::in<"annotation">,kpn::out<>,             "result_sink",      0> sink     (sink_fn,      16);
    // ── Pipeline observability + run loop (topology-agnostic) ──────────────────
@@ -403,43 +232,8 @@ int main(int argc, char** argv) {
                }
            });
        // Report *why* a node died. A Closed event alone says only that one
        // stopped; the exception it carried is what identifies the fault, and
        // without this listener it is discarded at the node boundary. Returning
        // false keeps the existing semantics — the node still stops and the
        // Closed handler above still aborts the run — but the run now names the
        // cause instead of leaving it to be reconstructed from a debugger.
        net.set_error_handler(
            [&](std::string_view node_name, std::exception_ptr eptr) {
                std::string what = "unknown exception";
                try {
                    if (eptr) std::rethrow_exception(eptr);
                } catch (const std::exception& e) {
                    what = e.what();
                } catch (...) {
                }
                std::lock_guard<std::mutex> lk(event_mtx);
                std::cerr << "[main] node '" << node_name << "' threw: " << what << "\n";
                return false;
            });
        /// TRACES: VR-015 | PR-004
        // Sampling must start with the network and stop before it is destroyed:
        // channel fill is instantaneous, and by the time a run ends everything
        // has drained, so a single read at shutdown reports an idle pipeline no
        // matter how congested it was.
        sae::bench::BenchmarkRecorder bench{cfg.benchmark_interval_ms};
        const bool benchmarking = !cfg.benchmark_path.empty();
        std::cerr << "[main] starting pipeline…\n";
        net.start();
        if (benchmarking) {
            bench.start([&net] { return net.network_snapshot(); });
            std::signal(SIGUSR1, sae_on_dump_signal);
            std::cerr << "[benchmark] sampling every " << cfg.benchmark_interval_ms
                      << "ms — `kill -USR1 " << getpid()
                      << "` to dump the table now (works while hung)\n";
        }
        // Wait until BOTH terminal branches finish: result_sink (face pipeline)
        // and, when enabled, scene_detector (the dense TransNetV2 branch, which
@@ -447,129 +241,21 @@ int main(int argc, char** argv) {
        // pre-set true when scene detection is disabled.
        while ((!done.load(std::memory_order_acquire) ||
                !scene_done.load(std::memory_order_acquire)) &&
-               !node_crashed.load(std::memory_order_acquire)) {
+               !node_crashed.load(std::memory_order_acquire))
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
            /// TRACES: VR-015 | AR-004 | PR-004
            if (g_dump_request.exchange(false, std::memory_order_relaxed))
                bench.dump_live(std::cerr, film_sec.load(std::memory_order_acquire));
        }
        // Latch the counters before stop(): they stay readable afterwards, but
        // only while the network object is alive, and this keeps the numbers
        // describing the run rather than the teardown.
        if (benchmarking) bench.stop();
        net.stop();
        net.print_diagnostics();
        /// TRACES: VR-015 | PR-004
        if (benchmarking && bench.has_data()) {
            const double film = film_sec.load(std::memory_order_acquire);
            bench.print(std::cerr, film);
            nlohmann::json run_cfg{
                {"movie",           cfg.movie_path},
                {"gallery",         cfg.gallery_path},
                {"gallery_actors",  gallery.actors.size()},
                {"sample_fps",      cfg.sample_fps},
                {"min_face_px",     cfg.min_face_px},
                {"max_faces",       cfg.max_faces},
                {"embed_batch",     cfg.embed_batch_size},
                {"expand_gallery",  cfg.expand_gallery},
                {"scene_detect",    cfg.scene_detect},
                {"detector_engine", cfg.detector_engine},
                {"arcface_engine",  cfg.arcface_engine},
                {"detector_model",  cfg.detector_model},
                {"arcface_model",   cfg.arcface_model},
            };
            std::ofstream bf(cfg.benchmark_path);
            if (bf) {
                bf << bench.to_json(run_cfg, film).dump(2) << "\n";
                std::cerr << "[benchmark] wrote " << cfg.benchmark_path << "\n";
            } else {
                std::cerr << "[benchmark] ERROR: could not write "
                          << cfg.benchmark_path << "\n";
            }
        }
        /// TRACES: AR-004 | SR-002
        // A dropped frame does not degrade a result, it silently changes one —
        // the output is a claim about footage that was never analysed, and
        // nothing in the file says so. Since AR-004 made data pushes block, a
        // drop can no longer happen on the data path, so any drop here means
        // either that fix regressed (it lives in the KPN submodule, one line,
        // easy to lose in an update) or a channel was disabled mid-run.
        //
        // Reporting it in a footer and exiting 0 made both invisible: the run
        // "succeeded" and the truth file looked complete. Fail instead.
        /// TRACES: AR-010 | SR-002
        if (scene_stats) {
            std::cerr << "[scene_annotate] boundaries=" << scene_stats->count()
                      << "  scored_through=" << scene_stats->scored_through() << "s";
            // The tail is expected: frames after the detector's last full
            // window are never covered, and no amount of buffering changes
            // that. They are counted rather than silently treated as
            // boundary-free, which is the distinction that matters.
            if (scene_stats->outran() > 0)
                std::cerr << "  unscored=" << scene_stats->outran()
                          << " frame(s) past the detector's last window — treated as"
                             " boundary-free, which is unverified rather than known";
            std::cerr << "\n";
        }
        /// TRACES: AR-025, AR-012 | SR-002
        // How often the registry was asked about a track it had already reaped.
        //
        // A vote is dropped when the matcher lags the tracker by more than
        // track_extinction_sec of FILM time. The two are adjacent nodes with a
        // 16-deep channel between them, and the matcher is much the slower of
        // the pair (a GEMM over the whole gallery against a Hungarian solve over
        // a handful of boxes), so that channel runs full and the lag is close to
        // its depth. In frames:
        //
        //     lag_sec  ~=  channel_depth / sample_fps
        //
        // At the default sample_fps of 1.0 that is ~16 s against a 5 s window,
        // so votes CAN be dropped here, and each one is identity evidence that
        // never reached the track it belonged to -- presence under-reported, in
        // a way that reads as a recognition miss.
        //
        // Reported rather than fatal, deliberately, and the distinction from the
        // dropped-frame case below is real: a dropped frame means the output
        // describes footage nobody analysed, which is always wrong. A dropped
        // vote means one observation of a track went missing, which degrades a
        // claim without falsifying it. There is also no measurement yet of how
        // often it happens on real content -- so this prints the number that
        // would justify a harder line rather than presuming it. See VR-017.
        if (registry) {
            const int dv = registry->dropped_votes();
            if (dv > 0) {
                std::cerr << "[registry] WARNING: " << dv << " identity vote(s) "
                             "arrived for already-reaped tracks. The matcher is "
                             "lagging the tracker by more than track_extinction_sec ("
                          << cfg.track_extinction_sec << "s) of film; presence is "
                             "under-reported. Raise --track-extinction or reduce the "
                             "face_tracker/identity_matcher channel depth.\n";
            }
            std::cerr << "[registry] belief_swaps=" << registry->belief_swaps()
                      << "  actor_conflicts=" << registry->actor_conflicts()
                      << "  dropped_votes=" << dv << "\n";
        }
        bool dropped = false;
        {
            std::lock_guard<std::mutex> lk(event_mtx);
            if (!overflow_counts.empty()) {
-                dropped = true;
+                std::cerr << "[main] dropped frames (channel overflow):\n";
                std::cerr << "[main] ERROR: frames were dropped (channel overflow):\n";
                for (const auto& [name, count] : overflow_counts)
                    std::cerr << "  " << name << ": " << count << "\n";
                std::cerr << "[main] The output would describe footage that was never "
                             "analysed. Refusing to report success.\n";
            }
        }
-        if (node_crashed.load(std::memory_order_acquire)) return 1;
+        return node_crashed.load(std::memory_order_acquire) ? 1 : 0;
        return dropped ? 2 : 0;
    };
    // ── Build static network and run ──────────────────────────────────────────
@@ -610,23 +296,8 @@ int main(int argc, char** argv) {
    if (cfg.scene_detect) {
        scene_done.store(false, std::memory_order_release);  // now a real terminal branch
        SceneDetectorFunc scene_fn{cfg, scene_done};
        /// TRACES: AR-010 | SR-002
        // The join of the decode butterfly. source fans out to the dense
        // TransNetV2 branch and the sampled face branch; boundaries found on the
        // first have to reach the second, and cannot ride the frames because the
        // branches run in parallel.
        //
        // TransNetV2 buffers kWindow frames before it can score any of them, so
        // the face branch must lag by at least that much or it will ask about
        // frames nobody has looked at yet. Channel depth is what creates the lag:
        // with backpressure (AR-004) the fanout blocks on the slower branch, so
        // a deep face-branch channel lets the detector run ahead by its window
        // rather than dropping anything.
        auto boundaries = std::make_shared<SceneBoundaries>();
        scene_fn.set_boundaries(boundaries);
        kpn::ObjectNode<SceneDetectorFunc, kpn::in<"dense">, kpn::out<>, "scene_detector", 0>
-            scene_node(scene_fn, kSceneInputDepth);
+            scene_node(scene_fn, 128);
        // Decimator: keep frames on the sample_fps cadence, drop the rest.
        // eof always passes so downstream shuts down cleanly. Stateful — one
@@ -641,34 +312,13 @@ int main(int argc, char** argv) {
                    return true;
                }
                return false;
-            }, kDecimatorInputDepth);
+            }, 32);
        /// TRACES: AR-010 | SR-002
        // Stamp is_scene_boundary from the detector's published verdict. tol is
        // half a sample interval: the two branches sample at different rates, so
        // a boundary found on a dense frame rarely lands exactly on a sampled
        // one, and half an interval attributes it to the nearest sampled frame
        // and no further.
        //
        // outran() counts frames that arrived before the detector had scored
        // them. Nonzero means the join depth is too shallow for the window, and
        // those frames were annotated from an incomplete verdict — which would
        // otherwise look exactly like "no boundary here".
        SceneBoundaryAnnotatorFunc annotate_fn{boundaries, 0.5 / cfg.sample_fps};
        kpn::ObjectNode<SceneBoundaryAnnotatorFunc, kpn::in<"frame">, kpn::out<"frame">,
                        "scene_annotate", 0> annotate(annotate_fn, scene_join_depth(cfg.sample_fps));
        // Reported at shutdown: without this the join is unverifiable, and an
        // annotator that never fired looks identical to footage with no
        // boundaries.
        scene_stats = boundaries;
        auto net = kpn::make_network(
            kpn::edge(source.output<"raw">(),          campos.input<"raw">()),
            kpn::edge(source.output<"raw">(),          scene_node.input<"dense">()),
            kpn::edge(campos.output<"frame">(),        decimate.input<0>()),
-            kpn::edge(decimate.output<0>(),            annotate.input<"frame">()),
+            kpn::edge(decimate.output<0>(),            detector.input<"frame">()),
            kpn::edge(annotate.output<"frame">(),      detector.input<"frame">()),
            kpn::edge(detector.output<"scene">(),      aligner.input<"scene">()),
            kpn::edge(aligner.output<"aligned">(),     embedder.input<"aligned">()),
            kpn::edge(embedder.output<"embedded">(),   ftracker.input<"embedded">()),
@@ -26,8 +26,7 @@
 // The node is a pure pass-through: it forwards the Frame unchanged except for
 // is_cut, so it slots between frame_source and face_detector without altering the
 // downstream contract. eof frames are forwarded immediately without processing.
-//
+
 /// TRACES: AR-009 | SR-002
 struct CameraPositionChangeDetectorFunc {
    static constexpr std::string_view label() { return "camera_position_change_detector"; }
@@ -17,8 +17,7 @@
 // All crops in one frame are batched into a single forward pass (capped at
 // embed_batch_size). The backend serialises itself; we only call it from the
 // single embedder thread.
-//
+
 /// TRACES: AR-006 | SR-002
 struct EmbedderFunc {
    static constexpr std::string_view label() { return "embedder"; }
@@ -1,113 +1,14 @@
 #pragma once
 /// TRACES: AR-028 | VR-001, VR-010 | PR-002
 #include "types.hpp"
 #include "config.hpp"
 #include "gallery/embedder_stamp.hpp"
 #include <H5Cpp.h>
 #include <atomic>
 #include <cstdint>
 #include <iostream>
 #include <optional>
 #include <string>
 #include <type_traits>
 #include <vector>
 // ── DumpProvenance ────────────────────────────────────────────────────────────
 /// TRACES: VR-010 | PR-002
 // Everything that determined a dump's *content*, read back tolerantly.
 //
 // Two dumps of the same film with different detector thresholds, a different
 // `dense_scale`, or scene detection on versus off are different measurements of
 // different things — but they are byte-shaped identically, so a consumer that
 // mixes them gets a plausible number from an incoherent input. GR-004 closed the
 // worst case (a cross-model replay, where every cosine is meaningless); this
 // closes the rest.
 //
 // Every field is optional because dumps written before VR-010 lack the
 // attributes. A missing field reads as *unknown*, never as a default — a
 // silently-defaulted `detector_conf` is exactly the fabricated provenance the
 // requirement exists to prevent ("a fixture whose provenance is unknown is worse
 // than no fixture, because it will be trusted").
 struct DumpProvenance {
    // Model identity
    std::optional<std::string> embedder_model;    // GR-004
    std::optional<std::string> embedder_sha256;   // GR-004
    std::optional<std::string> detector_model;
    // Sampling
    std::optional<std::string> movie;
    std::optional<float>       sample_fps;
    std::optional<double>      start_sec;
    std::optional<double>      end_sec;           // -1 = to end of file
    // Detection — what the run admitted into the dump
    std::optional<float>       detector_conf;
    std::optional<float>       detector_nms;
    std::optional<float>       min_face_px;
    std::optional<int>         max_faces;         // 0 = uncapped (AR-003)
    // Frame geometry
    std::optional<float>       dense_scale;
    std::optional<float>       bbox_upscale;      // faces/bbox × this = original-resolution px
    std::optional<float>       cut_threshold;
    // Scene detection. The reason this flag exists: `is_scene_boundary` is
    // all-zero both when TransNetV2 found no boundaries and when it never ran,
    // and no amount of staring at the array distinguishes them.
    std::optional<bool>        scene_detect;
    // Downstream knob that shaped nothing in the dump but everything a replay is
    // compared against — recorded so a sweep can be told apart from the baseline.
    std::optional<float>       track_assoc_min_prob;
 };
 // Read whatever provenance a dump carries. Never throws on a missing attribute;
 // an old dump simply yields a DumpProvenance full of empty optionals.
 inline DumpProvenance read_dump_provenance(const H5::H5File& f) {
    DumpProvenance p;
    auto str = [&](const char* n, std::optional<std::string>& out) {
        if (!f.attrExists(n)) return;
        // Written as a variable-length string, so the read must name the same
        // type explicitly — the default would truncate to a fixed length.
        H5::StrType vlen(H5::PredType::C_S1, H5T_VARIABLE);
        std::string v;
        f.openAttribute(n).read(vlen, v);
        out = v;
    };
    auto num = [&](const char* n, const H5::PredType& dt, auto& out) {
        if (!f.attrExists(n)) return;
        typename std::decay_t<decltype(out)>::value_type v{};
        f.openAttribute(n).read(dt, &v);
        out = v;
    };
    str("embedder_model",  p.embedder_model);
    str("embedder_sha256", p.embedder_sha256);
    str("detector_model",  p.detector_model);
    str("movie",           p.movie);
    num("sample_fps",           H5::PredType::NATIVE_FLOAT,  p.sample_fps);
    num("start_sec",            H5::PredType::NATIVE_DOUBLE, p.start_sec);
    num("end_sec",              H5::PredType::NATIVE_DOUBLE, p.end_sec);
    num("detector_conf",        H5::PredType::NATIVE_FLOAT,  p.detector_conf);
    num("detector_nms",         H5::PredType::NATIVE_FLOAT,  p.detector_nms);
    num("min_face_px",          H5::PredType::NATIVE_FLOAT,  p.min_face_px);
    num("max_faces",            H5::PredType::NATIVE_INT,    p.max_faces);
    num("dense_scale",          H5::PredType::NATIVE_FLOAT,  p.dense_scale);
    num("bbox_upscale",         H5::PredType::NATIVE_FLOAT,  p.bbox_upscale);
    num("cut_threshold",        H5::PredType::NATIVE_FLOAT,  p.cut_threshold);
    num("track_assoc_min_prob", H5::PredType::NATIVE_FLOAT,  p.track_assoc_min_prob);
    if (f.attrExists("scene_detect")) {
        uint8_t v = 0;
        f.openAttribute("scene_detect").read(H5::PredType::NATIVE_UINT8, &v);
        p.scene_detect = (v != 0);
    }
    return p;
 }
 // ── EmbeddingDumpFunc ─────────────────────────────────────────────────────────
 // KPN sink that taps the EmbeddedSceneFrame channel and writes the per-frame face
 // metadata + embeddings to one HDF5 file (schema: scripts/optimizer/SCHEMA.md).
@@ -124,44 +25,12 @@ struct EmbeddingDumpFunc {
        : path_(cfg.dump_embeddings_path), movie_(cfg.movie_path),
          sample_fps_(cfg.sample_fps), done_(done)
    {
-        /// TRACES: GR-004 | SR-001
+        std::cerr << "[embedding_dump] writing " << path_ << "\n";
        // A dump is a bag of embeddings with no model attached, replayed against a
        // gallery hours or weeks later — the same silent cross-model hazard as the
        // gallery itself, so it carries the same stamp.
        stamp_ = make_embedder_stamp(cfg.arcface_model);
        /// TRACES: VR-010 | PR-002
        // The rest of what determined this file's content. Captured from the live
        // Config at construction, so it describes the run that is being written
        // rather than whatever config happens to be lying around at read time.
        prov_.detector_model       = basename_of(cfg.detector_model);
        prov_.detector_conf        = cfg.detector_conf;
        prov_.detector_nms         = cfg.detector_nms;
        prov_.min_face_px          = cfg.min_face_px;
        prov_.max_faces            = cfg.max_faces;
        prov_.cut_threshold        = cfg.cut_threshold;
        prov_.dense_scale          = cfg.dense_scale;
        prov_.start_sec            = cfg.start_sec;
        prov_.end_sec              = cfg.end_sec;
        prov_.scene_detect         = cfg.scene_detect;
        prov_.track_assoc_min_prob = cfg.track_assoc_min_prob;
        std::cerr << "[embedding_dump] writing " << path_
                  << "  embedder: " << stamp_.describe()
                  << "  detector: " << *prov_.detector_model
                  << " @conf " << cfg.detector_conf
                  << "  scene_detect=" << (cfg.scene_detect ? "on" : "off") << "\n";
    }
    void operator()(EmbeddedSceneFrame ef) {
        if (ef.source.eof) { flush(); return; }
        /// TRACES: VR-010 | PR-002
        // Taken from the frames themselves, not recomputed from dense_scale — the
        // factor the source actually stamped on them is the one that maps
        // faces/bbox back to original resolution, whatever rule produced it.
        if (!prov_.bbox_upscale) prov_.bbox_upscale = ef.source.bbox_upscale;
        const int32_t n = static_cast<int32_t>(ef.faces.size());
        ts_.push_back(ef.source.timestamp_sec);
        fidx_.push_back(ef.source.frame_idx);
@@ -178,16 +47,6 @@ struct EmbeddingDumpFunc {
                lmk_.push_back(f.landmarks[k].y);
            }
            conf_.push_back(f.confidence);
            /// TRACES: AR-028 | SR-002
            // The quality vector, carried rather than consumed: written beside
            // the embedding it describes so VR-012 can locate its knees against
            // recorded data instead of by re-running video. Size is the third
            // axis and is already here as bbox + the bbox_upscale attribute.
            // Both are -1 only if a face reached the dump unscored, which the
            // aligner does not allow — the sentinel is preserved rather than
            // clamped so that a future path which did would be visible.
            sharp_.push_back(f.sharpness);
            resid_.push_back(f.alignment_residual);
            const auto& e = ef.embeddings[i];
            emb_.insert(emb_.end(), e.begin(), e.end());
        }
@@ -204,27 +63,9 @@ struct EmbeddingDumpFunc {
    }
 private:
-    // Root attributes are additive: schema_version stayed 1 across VR-010, because
+    static constexpr int kSchemaVersion = 1;
    // every reader takes attributes by name with a default (replay.py) or an
    // existence check (read_dump_provenance), so an old dump loses nothing and a
    // new dump breaks nothing. A bump is for a change to the *datasets*.
    //
    // v2 is that change: AR-028 adds faces/sharpness and faces/alignment_residual.
    // The bump is not about readers — those check for the datasets by name, and a
    // v1 dump still replays. It is so a *consumer of the quality vector* can tell
    // "this film's faces were never scored" from "this film's faces scored zero",
    // which is the same distinction scene_detect exists to make and is likewise
    // not recoverable from the arrays. A v1 dump reports the vector as unknown;
    // re-dump to acquire it, since nobody can assert after the fact how sharp a
    // face was.
    static constexpr int kSchemaVersion = 2;
    static constexpr int kEmbedDim = 512;
    static std::string basename_of(const std::string& path) {
        const auto slash = path.find_last_of("/\\");
        return slash == std::string::npos ? path : path.substr(slash + 1);
    }
    template<typename T>
    void write_vec(H5::Group& g, const char* name, const std::vector<T>& v,
                   const H5::PredType& dtype, hsize_t cols = 0) {
@@ -236,49 +77,20 @@ private:
        if (!v.empty()) ds.write(v.data(), dtype);
    }
    static void attr_str(H5::H5File& f, const char* name, const std::string& v) {
        H5::StrType str(H5::PredType::C_S1, H5T_VARIABLE);
        f.createAttribute(name, str, H5::DataSpace(H5S_SCALAR)).write(str, v);
    }
    template<typename T>
    static void attr_num(H5::H5File& f, const char* name, const H5::PredType& dt, T v) {
        f.createAttribute(name, dt, H5::DataSpace(H5S_SCALAR)).write(dt, &v);
    }
    void write_hdf5() {
        H5::H5File file(path_, H5F_ACC_TRUNC);
        // root attrs
-        attr_num(file, "schema_version", H5::PredType::NATIVE_INT,   kSchemaVersion);
+        auto scalar = H5::DataSpace(H5S_SCALAR);
-        attr_num(file, "embed_dim",      H5::PredType::NATIVE_INT,   kEmbedDim);
+        auto ver = file.createAttribute("schema_version", H5::PredType::NATIVE_INT, scalar);
-        attr_num(file, "sample_fps",     H5::PredType::NATIVE_FLOAT, sample_fps_);
+        int sv = kSchemaVersion; ver.write(H5::PredType::NATIVE_INT, &sv);
-        attr_str(file, "movie", movie_);
+        auto ed = file.createAttribute("embed_dim", H5::PredType::NATIVE_INT, scalar);
-        /// TRACES: GR-004 | SR-001
+        int dim = kEmbedDim; ed.write(H5::PredType::NATIVE_INT, &dim);
-        attr_str(file, "embedder_model",  stamp_.model_name);
+        auto fps = file.createAttribute("sample_fps", H5::PredType::NATIVE_FLOAT, scalar);
-        attr_str(file, "embedder_sha256", stamp_.model_sha256);
+        fps.write(H5::PredType::NATIVE_FLOAT, &sample_fps_);
-
+        H5::StrType str(H5::PredType::C_S1, H5T_VARIABLE);
-        /// TRACES: VR-010 | PR-002
+        auto mv = file.createAttribute("movie", str, scalar);
-        attr_str(file, "detector_model", prov_.detector_model.value_or(""));
+        mv.write(str, movie_);
        attr_num(file, "detector_conf",  H5::PredType::NATIVE_FLOAT,  *prov_.detector_conf);
        attr_num(file, "detector_nms",   H5::PredType::NATIVE_FLOAT,  *prov_.detector_nms);
        attr_num(file, "min_face_px",    H5::PredType::NATIVE_FLOAT,  *prov_.min_face_px);
        attr_num(file, "max_faces",      H5::PredType::NATIVE_INT,    *prov_.max_faces);
        attr_num(file, "cut_threshold",  H5::PredType::NATIVE_FLOAT,  *prov_.cut_threshold);
        attr_num(file, "dense_scale",    H5::PredType::NATIVE_FLOAT,  *prov_.dense_scale);
        // Recorded, NOT applied — faces/bbox stays in the detector's own frame
        // space so a replay feeds the tracker exactly what the live run fed it.
        attr_num(file, "bbox_upscale",   H5::PredType::NATIVE_FLOAT,
                 prov_.bbox_upscale.value_or(1.f));
        attr_num(file, "start_sec",      H5::PredType::NATIVE_DOUBLE, *prov_.start_sec);
        attr_num(file, "end_sec",        H5::PredType::NATIVE_DOUBLE, *prov_.end_sec);
        attr_num(file, "track_assoc_min_prob", H5::PredType::NATIVE_FLOAT,
                 *prov_.track_assoc_min_prob);
        // 0/1, matching the uint8 booleans in frames/. Tells "TransNetV2 found no
        // boundaries" apart from "TransNetV2 never ran", which is/was the same
        // all-zero is_scene_boundary array either way.
        attr_num(file, "scene_detect",   H5::PredType::NATIVE_UINT8,
                 static_cast<uint8_t>(*prov_.scene_detect ? 1 : 0));
        H5::Group frames = file.createGroup("frames");
        write_vec(frames, "timestamp_sec", ts_,      H5::PredType::NATIVE_DOUBLE);
@@ -293,17 +105,12 @@ private:
        write_vec(faces, "bbox",       bbox_, H5::PredType::NATIVE_FLOAT, 4);
        write_vec(faces, "landmarks",  lmk_,  H5::PredType::NATIVE_FLOAT, 10);
        write_vec(faces, "confidence", conf_, H5::PredType::NATIVE_FLOAT);
        /// TRACES: AR-028 | SR-002
        write_vec(faces, "sharpness",          sharp_, H5::PredType::NATIVE_FLOAT);
        write_vec(faces, "alignment_residual", resid_, H5::PredType::NATIVE_FLOAT);
        std::cerr << "[embedding_dump] wrote " << ts_.size() << " frames, "
                  << conf_.size() << " faces → " << path_ << "\n";
    }
    std::string path_, movie_;
    EmbedderStamp stamp_;
    DumpProvenance prov_;
    float sample_fps_;
    std::atomic<bool>& done_;
    std::atomic<bool>  written_{false};
@@ -314,5 +121,4 @@ private:
    std::vector<int64_t> face_off_;
    std::vector<int32_t> face_cnt_;
    std::vector<float>   emb_, bbox_, lmk_, conf_;
    std::vector<float>   sharp_, resid_;   // AR-028 quality vector, parallel to conf_
 };
@@ -1,55 +1,21 @@
 #pragma once
 #include "face_utils.hpp"
 #include <cstdint>
 #include <iostream>
 // ── FaceAlignerFunc ───────────────────────────────────────────────────────────
 /// TRACES: AR-005, AR-028, AR-029, AR-030 | SR-002
 ///
 // KPN node: applies a 5-point similarity transform to each detected face,
 // producing a 112×112 BGR crop suitable for ArcFace inference.
 //
-// Alignment is an Umeyama least-squares fit over all five landmarks (AR-005),
+// Alignment uses cv::estimateAffinePartial2D (RANSAC) to fit the detected
-// not a robust one: a RANSAC fit discards the very landmarks AR-030 reads.
+// landmarks to ArcFace canonical positions.  Degenerate detections (where the
-//
+// affine fit fails) are silently dropped from the output vectors.
 // This is also where the AR-028 quality vector is filled in, because this is
 // where the inputs to it already exist:
 //
 //   - **Visibility** (AR-030) is the fit's residual, and is genuinely free — the
 //     transform is computed for the warp regardless, and the residual is what
 //     that fit could not explain.
 //   - **Sharpness** (AR-029) is measured on the crop this node just produced,
 //     which is the only place it *can* be measured: the aligned canvas is what
 //     makes the number scale-normalised, and downstream of the embedder the crop
 //     is only forwarded for debug rendering. It is not free — 33 us per face
 //     single-threaded (cvtColor, one Laplacian, two meanStdDev over 112x112) —
 //     but it is two orders below the embedder inference it qualifies, and it
 //     runs per face rather than per frame, so a landscape shot costs nothing.
 //
 // Size, the third axis, is `bbox` and needs no work here.
 //
 // No face is admitted unscored: every face in the output carries both numbers,
 // so a negative value downstream is a bug rather than a poor-quality face.
 // Nothing is dropped or discounted on quality — that is AR-030's discount and
 // VR-012's knee, both still open.
 //
 // Degenerate detections (where the fit fails) cannot be scored, since there is
 // no crop and no residual to score, and are therefore dropped — but they are
 // **counted**, not silently discarded. A nonzero tally means the detector is
 // emitting landmark sets the aligner cannot use, which is a fact about the
 // detector; losing it leaves a hole in the dump that looks like footage with
 // no faces in it.
 struct FaceAlignerFunc {
    static constexpr std::string_view label() { return "face_aligner"; }
    AlignedSceneFrame operator()(SceneFrame sf) {
-        if (sf.source.eof) {
+        if (sf.source.eof || sf.faces.empty())
            report();
            return {std::move(sf.source), {}, {}};
        }
        if (sf.faces.empty())
            return {std::move(sf.source), {}, {}};
        std::vector<DetectedFace> good_faces;
@@ -58,43 +24,16 @@ struct FaceAlignerFunc {
        crops.reserve(sf.faces.size());
        for (auto& face : sf.faces) {
-            // The AR-030 misfit comes from the transform the warp already needs,
+            cv::Mat crop = align_face(sf.source.image, face.landmarks);
            // so visibility costs no extra fit.
            float residual = -1.f;
            cv::Mat crop = align_face(sf.source.image, face.landmarks, &residual);
            if (crop.empty()) {
-                ++degenerate_;
+                std::cerr << "[face_aligner] degenerate detection skipped\n";
                continue;
            }
            face.alignment_residual = residual;
            face.sharpness          = crop_sharpness(crop);
            good_faces.push_back(face);
            crops.push_back(std::move(crop));
            ++scored_;
        }
        return {std::move(sf.source), std::move(good_faces), std::move(crops)};
    }
    /// Faces that carry a full quality vector, and faces the fit could not use.
    uint64_t scored()     const { return scored_; }
    uint64_t degenerate() const { return degenerate_; }
 private:
    // Reported once at EOF rather than per occurrence: a run with a systematic
    // landmark problem would otherwise emit one line per face for the length of
    // a film, which is how the count came to be ignored.
    void report() {
        if (reported_) return;
        reported_ = true;
        if (degenerate_)
            std::cerr << "[face_aligner] " << degenerate_ << " of "
                      << (degenerate_ + scored_)
                      << " detections had a degenerate landmark fit and were dropped"
                         " (no crop, so no embedding and no quality vector)\n";
    }
    uint64_t scored_{0};
    uint64_t degenerate_{0};
    bool     reported_{false};
 };
@@ -1,12 +1,10 @@
 #pragma once
 /// TRACES: AR-001 | SR-002
 #include "config.hpp"
 #include "inference/face_detector.hpp"
 #include <algorithm>
 #include <memory>
 #include <string>
 #include <vector>
 // ── FaceDetectorFunc ──────────────────────────────────────────────────────────
 // KPN node: runs SCRFD-500MF to detect ALL faces in a frame.
@@ -23,49 +21,29 @@ struct FaceDetectorFunc {
        , min_face_px_(cfg.min_face_px)
    {}
    /// TRACES: AR-002 | SR-002
    // Drop faces below the minimum size — too small for reliable ArcFace
    // alignment, and below the resolution where identification still holds
    // (VR-013 measured the knee end to end).
    //
    // The minimum is expressed in ORIGINAL video resolution, which is what makes
    // it a property of the footage rather than of a throughput knob. When
    // dense_scale downscaled the frame the detector's boxes are in downscaled
    // space, and `bbox_upscale` is what maps them back; dividing the threshold by
    // it rather than multiplying every box keeps the comparison on the detector's
    // own numbers and the physical cutoff constant across scales.
    //
    // Strictly less-than: a face exactly at the minimum is admissible, which is
    // what a "minimum of 40x40" means.
    static void drop_undersized(std::vector<DetectedFace>& faces,
                                float min_face_px,
                                float bbox_upscale) {
        const float min_px = (bbox_upscale > 0.f) ? min_face_px / bbox_upscale
                                                  : min_face_px;
        faces.erase(
            std::remove_if(faces.begin(), faces.end(), [&](const DetectedFace& d) {
                return d.bbox.width < min_px || d.bbox.height < min_px;
            }),
            faces.end());
    }
    SceneFrame operator()(Frame f) {
        if (f.eof) return {std::move(f), {}};
        auto faces = detector_->detect(f.image);
-        drop_undersized(faces, min_face_px_, f.bbox_upscale);
+        // Drop faces below minimum pixel size (too small for reliable ArcFace
        // alignment). Note: when dense_scale downscaled the frame, both the
        // detection coords and min_face_px are in downscaled space — so scale
        // the threshold down to match, keeping the physical size cutoff constant.
        const float min_px = (f.bbox_upscale != 1.f)
                           ? min_face_px_ / f.bbox_upscale : min_face_px_;
        faces.erase(
            std::remove_if(faces.begin(), faces.end(), [&](const DetectedFace& d) {
                return d.bbox.width < min_px || d.bbox.height < min_px;
            }),
            faces.end());
        // Sort largest-first so max_faces_ keeps the most informative detections
        std::sort(faces.begin(), faces.end(),
                  [](const DetectedFace& a, const DetectedFace& b) {
                      return a.bbox.area() > b.bbox.area();
                  });
-        // TRACES: AR-003 | SR-002
+        if (static_cast<int>(faces.size()) > max_faces_)
        // Largest-first ordering is kept regardless: it is load-bearing for
        // deterministic association, since the Hungarian solver tie-breaks on
        // index order (see the replay determinism test).
        if (max_faces_ > 0 && static_cast<int>(faces.size()) > max_faces_)
            faces.resize(max_faces_);
        return {std::move(f), std::move(faces)};
@@ -1,124 +1,102 @@
 #pragma once
 /// TRACES: AR-007, AR-008, AR-024 | SR-002
 ///
 /// FaceTrackerFunc — KPN node that links face detections into tracks.
 ///
 /// **The registry is the tracker's state.** The node owns no track map of its
 /// own: it drives `TrackRegistry` through a `FrameScope` and reads the same
 /// `Track` objects everything else reads. Two parallel copies could disagree,
 /// and every divergence would surface as a wrong presence window rather than as
 /// a crash — silently, and only in the output.
 ///
 /// **One candidate pool** (AR-008). `last_seen` alone distinguishes a track that
 /// is on screen from one that is dormant, and it only affects whether IoU means
 /// anything. There is no parked pool and no revival branch: re-associating a
 /// track whose face was lost — across a cut or not — is ordinary inter-frame
 /// association, and it falls out of the embedding comparison already being done.
 ///
 /// Assignment cost (track i, detection j):
 ///
 ///   p     = P(same person | cosine(track mean, detection))   ← calibrated
 ///   alpha = base weight, or 0 when position carries no information
 ///   cost  = alpha·(1 − IoU) + (1 − alpha)·(1 − p)
 ///
 /// gated to INF unless the pair is admissible on position *or* on identity.
 ///
 /// **alpha is frame- and track-dependent** (AR-007). It falls to 0 —
 /// embedding only — when either:
 ///   - the frame is flagged `is_cut` / `is_scene_boundary`: the viewpoint
 ///     changed, so the same person is at a new position; or
 ///   - the track is dormant (`last_seen` set): time has passed since its box was
 ///     last observed, so that box is stale regardless of cuts.
 /// Both are the same statement — spatial continuity is broken — arrived at from
 /// two directions, which is why they collapse into one rule rather than two
 /// branches.
 ///
 /// **Everything is thresholded in probability space** (AR-024). The cosine goes
 /// through the calibration before it is compared to anything; the raw-cosine
 /// constants `track_max_embed_dist` and `cut_revive_sim` are retired.
 #include "types.hpp"
 #include "config.hpp"
 #include "track_registry.hpp"
 #include <algorithm>
 #include <cmath>
 #include <functional>
 #include <iostream>
 #include <limits>
 #include <map>
 #include <memory>
 #include <stdexcept>
 #include <string_view>
 #include <vector>
 // ── FaceTrackerFunc ───────────────────────────────────────────────────────────
 // KPN node: links face detections across consecutive frames using the Hungarian
 // algorithm on a combined spatial (IoU) + embedding (cosine distance) cost.
 //
 // Each track accumulates a running directional mean of its ArcFace embeddings
 // (averaged then re-normalised to the unit sphere), used as the embedding side
 // of the assignment cost below for more stable track continuity.
 //
 // Assignment cost (track i, detection j):
 //   cost = alpha * (1 - IoU)  +  (1-alpha) * min(cosine_dist/2, 1)
 //   Gated to INF when IoU < min_iou AND cosine_dist > max_embed_dist.
 //
 // Unmatched tracks have their frames_missing counter incremented; they are
 // expired once frames_missing > max_frames_missing.
 //
 // Cross-cut re-association. A camera-angle change (Frame::is_cut, set by
 // camera_position_change_detector) destroys spatial (IoU) continuity — the same
 // person reappears at a new position — but not identity. On a cut the tracker
 // does NOT discard its tracks; it parks them in an inactive pool keyed by their
 // last-frame raw embedding. A post-cut detection whose raw cosine similarity to
 // a parked track's last-frame embedding is ≥ cut_revive_sim revives that track:
 // the original track_id, mean embedding and n_frames are restored (only the bbox
 // jumps to the new detection), so identity continuity survives the cut. Parked
 // tracks left unrevived for cut_inactive_max_frames are finally dropped.
 struct FaceTrackerFunc {
    static constexpr std::string_view label() { return "face_tracker"; }
-    /// cosine similarity → P(same person). Supplied by the caller so the fit
+    struct TrackState {
-    /// belonging to the active embedder is used (AR-023/AR-024) — the same
+        cv::Rect2f bbox;
-    /// pattern, and normally the same function object, as
+        Embedding  mean_emb{};
-    /// `EvidenceDiscounter::Calibrate`.
+        Embedding  last_emb{};        // raw embedding of the most recent matched frame
-    using Calibrate = std::function<float(float)>;
+        int        n_frames{0};
        int        frames_missing{0};
    };
-    /// The registry is a constructor argument, not an option: a tracker without
+    explicit FaceTrackerFunc(const Config& cfg)
-    /// one would have to keep its own tracks, which is the defect this replaces.
+        : alpha_(cfg.track_alpha)
    FaceTrackerFunc(const Config& cfg,
                    std::shared_ptr<TrackRegistry> registry,
                    Calibrate calibrate)
        : registry_(std::move(registry))
        , calibrate_(std::move(calibrate))
        , alpha_base_(cfg.track_alpha)
        , min_iou_(cfg.track_min_iou)
-        , min_assoc_prob_(cfg.track_assoc_min_prob)
+        , max_embed_dist_(cfg.track_max_embed_dist)
        , max_missing_(cfg.track_max_frames_missing)
        , revive_sim_(cfg.cut_revive_sim)
        , inactive_max_(cfg.cut_inactive_max_frames)
    {
-        if (!registry_)
+        std::cerr << "[face_tracker] alpha=" << alpha_
            throw std::invalid_argument("face_tracker: registry must not be null");
        if (!calibrate_)
            throw std::invalid_argument("face_tracker: a calibration is required — "
                                        "association is decided in probability space");
        std::cerr << "[face_tracker] alpha_base=" << alpha_base_
                  << "  min_iou=" << min_iou_
-                  << "  min_assoc_prob=" << min_assoc_prob_ << "\n";
+                  << "  max_embed_dist=" << max_embed_dist_
                  << "  max_missing=" << max_missing_
                  << "  cut_revive_sim=" << revive_sim_
                  << "  cut_inactive_max=" << inactive_max_ << "\n";
    }
    TrackedSceneFrame operator()(EmbeddedSceneFrame ef) {
        if (ef.source.eof) {
-            // Deliberately does *not* flush the registry. The identity matcher
+            tracks_.clear();
-            // runs downstream and its votes for the final frames are still in
+            inactive_.clear();
            // flight; reaping here would drop them (they would land on ids that
            // no longer exist and show up as dropped_votes). AR-016's flush
            // belongs at the pipeline's termination point, after the last vote.
            boxes_.clear();
            TrackedSceneFrame out;
            out.source = std::move(ef.source);
            return out;
        }
        const double t     = ef.source.timestamp_sec;
        const int n_det = static_cast<int>(ef.embeddings.size());
-        // Unconditional: the clock must advance on frames with no detections
+        // Camera-angle change: park active tracks instead of destroying them so
-        // too, or a track only dies when some unrelated face happens to appear
+        // they can be revived by identity (raw last-frame embedding cosine) once
-        // and a film that ends mid-track never closes it (AR-013).
+        // the same people reappear from the new angle.
-        auto scope = registry_->begin_frame(t);
+        if (ef.source.is_cut && !tracks_.empty()) {
            std::cerr << "[face_tracker] cut — parking " << tracks_.size()
                      << " track(s) into inactive pool\n";
            for (auto& [tid, ts] : tracks_) {
                ts.frames_missing = 0;   // repurpose as time-since-parked counter
                inactive_[tid]    = std::move(ts);
            }
            tracks_.clear();
        }
-        // One pool (AR-008) — on-screen and dormant tracks compete together.
+        // Age the inactive pool every frame and drop tracks parked too long.
-        std::vector<Track*> cands = scope.candidates();
+        for (auto it = inactive_.begin(); it != inactive_.end(); ) {
-        const int n_trk = static_cast<int>(cands.size());
+            it->second.frames_missing++;
            it = (it->second.frames_missing > inactive_max_)
                 ? inactive_.erase(it) : std::next(it);
        }
-        prune_boxes(cands);
+        // Snapshot active track IDs so the map can be modified safely below
-        std::vector<Spatial*> sp(n_trk);
+        std::vector<int> tids;
-        for (int ti = 0; ti < n_trk; ++ti)
+        tids.reserve(tracks_.size());
-            sp[ti] = &boxes_.try_emplace(cands[ti]->id, Spatial{{}, t, false})
+        for (auto& [tid, _] : tracks_) tids.push_back(tid);
-                            .first->second;
+        const int n_trk = static_cast<int>(tids.size());
        // AR-007 — the frame half of the frame-dependent weighting. Both flags
        // say the same thing to the tracker: whatever was at that position is
        // not there any more.
        const bool viewpoint_change =
            ef.source.is_cut || ef.source.is_scene_boundary;
        // ── Cost matrix [n_trk × n_det] ──────────────────────────────────────
        constexpr float INF_COST = 1e6f;
@@ -126,39 +104,25 @@ struct FaceTrackerFunc {
            std::vector<float>(n_det, INF_COST));
        for (int ti = 0; ti < n_trk; ++ti) {
-            // Spatial continuity holds only for a track that was on screen, whose
+            const TrackState& ts = tracks_[tids[ti]];
            // box we have actually observed, on a frame that did not change the
            // viewpoint. Otherwise the box is stale and IoU is noise.
            const bool spatial_meaningful =
                sp[ti]->observed && cands[ti]->on_screen() && !viewpoint_change;
            const float alpha = spatial_meaningful ? alpha_base_ : 0.f;
            for (int di = 0; di < n_det; ++di) {
-                // AR-024 — the cosine is converted before it is used for
+                float iou_v = iou(ts.bbox, ef.faces[di].bbox);
-                // anything, including the gate below.
+                float emb_d = (ts.n_frames > 0)
-                const float p = calibrate_(
+                              ? 1.f - cosine_similarity(ts.mean_emb, ef.embeddings[di])
-                    cosine_similarity(cands[ti]->mean, ef.embeddings[di]));
+                              : 1.f;
-                const float iou_v = spatial_meaningful
+                if (iou_v < min_iou_ && emb_d > max_embed_dist_) continue;
-                                    ? iou(sp[ti]->bbox, ef.faces[di].bbox) : 0.f;
+                float s = 1.f - iou_v;
-
+                float e = std::min(emb_d * 0.5f, 1.f);
-                // Either signal on its own can admit a link: a face that moved a
+                cost[ti][di] = alpha_ * s + (1.f - alpha_) * e;
                // little but whose embedding degraded (blur, profile turn) is
                // still linkable on position, and a face that jumped across the
                // frame is still linkable on identity. Neither ⇒ no link.
                const bool spatial_ok  = spatial_meaningful && iou_v >= min_iou_;
                const bool identity_ok = p >= min_assoc_prob_;
                if (!spatial_ok && !identity_ok) continue;
                cost[ti][di] = alpha * (1.f - iou_v) + (1.f - alpha) * (1.f - p);
            }
        }
-        // ── Hungarian assignment ─────────────────────────────────────────────
+        // ── Hungarian assignment ──────────────────────────────────────────────
        std::vector<int> assign(n_trk, -1);
        if (n_trk > 0 && n_det > 0)
            assign = hungarian(cost, n_trk, n_det);
-        // ── Build output frame ───────────────────────────────────────────────
+        // ── Build output frame ────────────────────────────────────────────────
        TrackedSceneFrame out;
        out.source           = ef.source;
        out.faces            = ef.faces;
@@ -168,66 +132,81 @@ struct FaceTrackerFunc {
        std::vector<bool> det_matched(n_det, false);
        // Update matched tracks
        for (int ti = 0; ti < n_trk; ++ti) {
-            const int di = assign[ti];
+            int di = assign[ti];
-            const int id = cands[ti]->id;
+            bool valid = (di >= 0 && di < n_det && cost[ti][di] < INF_COST * 0.5f);
-            const bool valid =
+            TrackState& ts = tracks_[tids[ti]];
                (di >= 0 && di < n_det && cost[ti][di] < INF_COST * 0.5f);
            if (!valid) {
-                // Only a track that *was* on screen can become lost, and it
+                ts.frames_missing++;
-                // becomes lost as of its last sighting, never as of now — the
+                continue;
-                // gap after the final sighting is never claimed (AR-013). A
+            }
-                // track already dormant is left alone so its extinction clock
+            update_mean(ts.mean_emb, ts.n_frames, ef.embeddings[di]);
-                // keeps running from the right instant.
+            ts.last_emb = ef.embeddings[di];
-                if (cands[ti]->on_screen()) scope.mark_lost(id, sp[ti]->last_ts);
+            ts.bbox = ef.faces[di].bbox;
            ts.n_frames++;
            ts.frames_missing = 0;
            det_matched[di] = true;
            out.track_ids[di] = tids[ti];
        }
        // Handle unmatched detections: first try to revive a parked track by
        // identity (raw last-frame embedding cosine), else start a fresh track.
        for (int di = 0; di < n_det; ++di) {
            if (det_matched[di]) continue;
            int tid = revive_from_inactive(ef.embeddings[di]);
            if (tid >= 0) {
                // Restore the parked track: keep its identity statistics
                // (mean_emb, n_frames), jump the bbox to the new detection.
                TrackState ts   = std::move(inactive_[tid]);
                inactive_.erase(tid);
                update_mean(ts.mean_emb, ts.n_frames, ef.embeddings[di]);
                ts.last_emb       = ef.embeddings[di];
                ts.bbox           = ef.faces[di].bbox;
                ts.n_frames++;
                ts.frames_missing = 0;
                tracks_[tid]      = std::move(ts);
                out.track_ids[di] = tid;
                std::cerr << "[face_tracker] revived track " << tid
                          << " across cut\n";
                continue;
            }
-            scope.mark_seen(id, t, ef.embeddings[di]);
+            tid = next_id_++;
-            sp[ti]->bbox     = ef.faces[di].bbox;
+            TrackState ts;
-            sp[ti]->last_ts  = t;
+            ts.bbox     = ef.faces[di].bbox;
-            sp[ti]->observed = true;
+            ts.mean_emb = ef.embeddings[di];
-            det_matched[di]  = true;
+            ts.last_emb = ef.embeddings[di];
-            out.track_ids[di] = id;
+            ts.n_frames = 1;
            tracks_[tid] = ts;
            out.track_ids[di] = tid;
        }
-        for (int di = 0; di < n_det; ++di) {
+        // Expire stale tracks
-            if (det_matched[di]) continue;
+        for (auto it = tracks_.begin(); it != tracks_.end(); ) {
-            const int id = scope.create(t, ef.embeddings[di]);
+            it = (it->second.frames_missing > max_missing_)
-            boxes_[id] = Spatial{ef.faces[di].bbox, t, true};
+                 ? tracks_.erase(it) : std::next(it);
            out.track_ids[di] = id;
        }
        // No reaping here: begin_frame's tick owns the extinction sweep, so
        // there is exactly one place a track can die.
        return out;
    }
 private:
-    // ── Spatial annotation ───────────────────────────────────────────────────
+    // Pick the parked track whose last-frame embedding is most similar to emb,
-    // The one piece of per-track state the registry does not hold, because it is
+    // returning its id if that raw cosine similarity clears revive_sim_, else -1.
-    // not about presence: where the face was, and when it was last seen there.
+    // The caller removes the returned track from the pool, so a later detection in
-    // Keyed by registry track id and pruned against `candidates()` every frame,
+    // the same frame cannot claim it again.
-    // so it cannot outlive or contradict the registry — it annotates the pool
+    int revive_from_inactive(const Embedding& emb) const {
-    // rather than duplicating it.
+        int   best_tid = -1;
-    struct Spatial {
+        float best_sim = revive_sim_;   // threshold is the bar to beat (inclusive)
-        cv::Rect2f bbox{};
+        for (const auto& [tid, ts] : inactive_) {
-        double     last_ts{0.0};     ///< timestamp of the last frame this track matched
+            float sim = cosine_similarity(ts.last_emb, emb);
-        bool       observed{false};  ///< false until a detection has been assigned
+            if (sim >= best_sim) { best_sim = sim; best_tid = tid; }
-    };
+            // subsequent ties keep the later id; harmless, all clear the threshold
    // Drop boxes for ids the registry no longer has. `candidates()` is the
    // authority on what exists; anything else is a leak (and, for a reused id,
    // would be a stale box attached to a different person).
    void prune_boxes(const std::vector<Track*>& cands) {
        if (boxes_.size() == cands.size()) return;   // common case: nothing died
        std::map<int, Spatial> kept;
        for (const Track* t : cands) {
            auto it = boxes_.find(t->id);
            if (it != boxes_.end()) kept.emplace(t->id, it->second);
        }
-        boxes_.swap(kept);
+        return best_tid;
    }
    // IoU of two axis-aligned bounding boxes
@@ -241,6 +220,17 @@ private:
        return inter / (a.width * a.height + b.width * b.height - inter);
    }
    // Online directional mean: average then re-normalise to unit sphere
    static void update_mean(Embedding& mean, int n_prev, const Embedding& emb) {
        float norm_sq = 0.f;
        for (int k = 0; k < 512; ++k) {
            mean[k] = (mean[k] * n_prev + emb[k]) / (n_prev + 1);
            norm_sq += mean[k] * mean[k];
        }
        float inv = 1.f / std::sqrt(norm_sq);
        for (int k = 0; k < 512; ++k) mean[k] *= inv;
    }
    // O(n³) potential-based Hungarian algorithm (Jonker-Volgenant / Kuhn-Munkres).
    // Returns assign[row] = col (0-indexed), or -1 when row is matched to a
    // padded virtual column (i.e., unmatched).  Rectangular matrices are padded
@@ -302,10 +292,13 @@ private:
        return ans;
    }
-    std::shared_ptr<TrackRegistry> registry_;
+    std::map<int, TrackState> tracks_;
-    Calibrate                      calibrate_;
+    std::map<int, TrackState> inactive_;   // parked across a cut, keyed by track id
-    std::map<int, Spatial>         boxes_;   ///< track id → where it was, when
+    int   next_id_{0};
-    float alpha_base_;
+    float alpha_;
    float min_iou_;
-    float min_assoc_prob_;
+    float max_embed_dist_;
    int   max_missing_;
    float revive_sim_;
    int   inactive_max_;
 };
@@ -1,48 +0,0 @@
 #pragma once
 /// TRACES: AR-012, AR-013 | SR-002
 ///
 /// FrameAnnotationFunc — project a matched frame into a per-frame annotation.
 ///
 /// Stateless, and that is the entire point of it.
 ///
 /// It replaces `SceneTrackerFunc`, which kept an extinction timer per actor and
 /// reported an actor as visible for `extinction_sec` (57.4 s) after their last
 /// detection. docs/SPEC.md specified that node's deletion -- "anneal_sec and
 /// extinction_sec are deleted, not re-tuned ... SceneTrackerFunc goes with
 /// them", with a removal list ending "grep for both names and expect no
 /// survivors" -- and docs/requirements.md recorded both constants as Withdrawn,
 /// deleted "rather than retained at zero", on the grounds that a field naming a
 /// mechanism the pipeline no longer has is actively misleading. None of that
 /// removal had happened. The node was still wired into both shipped pipelines
 /// and still printed its timeout at every startup.
 ///
 /// **Presence is not this node's business.** AR-012 moved it to TrackRegistry,
 /// where a window is `[first_seen, last_seen]` of a track an actor owns, and
 /// AR-013 ends that window at the last sighting rather than after it. A
 /// keep-alive here answered the same question a second time and answered it
 /// worse: it re-opened the trailing cool-down the registry exists to refuse.
 ///
 /// What a consumer sees change: `--verbosity standard`'s `frames[].identified`
 /// used to list every actor still inside the keep-alive, including ones absent
 /// from the frame. It now lists what was actually matched in that frame. The
 /// minimal and xray outputs are unaffected -- they were already built from
 /// registry claims and never consulted this node.
 #include "types.hpp"
 #include <string_view>
 #include <utility>
 struct FrameAnnotationFunc {
    static constexpr std::string_view label() { return "frame_annotation"; }
    SceneAnnotation operator()(MatchedSceneFrame mf) {
        if (mf.source.eof) return {0.0, {}, /*eof=*/true};
        SceneAnnotation sa;
        sa.timestamp_sec     = mf.source.timestamp_sec;
        sa.visible_actors    = std::move(mf.actors);
        sa.is_cut            = mf.source.is_cut;
        sa.is_scene_boundary = mf.source.is_scene_boundary;
        return sa;
    }
 };
@@ -5,7 +5,6 @@
 #include "gallery/gallery_store.hpp"
 #include "gallery/gallery_calibration.hpp"
 #include "gallery/track_gallery.hpp"
 #include "track_registry.hpp"
 #include <cstdint>
 #include <cstring>
@@ -19,36 +18,19 @@
 // KPN node: compares each embedding against every reference embedding in the
 // actor gallery using cosine similarity.
 //
-// Matching strategy — one mode, always.
+// Matching strategy — two modes selected at construction time:
 //
-//   Gallery calibration fits a sigmoid P(match) = σ(a·similarity + b) from
+//   Calibrated (preferred): gallery calibration fits a sigmoid
-//   intra/inter-class pairs. A face is accepted if P(match | best_actor) >
+//     P(match) = σ(a·similarity + b) from intra/inter-class pairs.
-//   prob_threshold. Per-actor best similarity is the closest reference
+//     A face is accepted if P(match | best_actor) > prob_threshold.
 //   embedding (best-of-N).
 //
-/// TRACES: AR-024 | SR-002
+//   Fallback (no calibration): dual-criterion accept —
-// **There is no raw-cosine fallback.** There used to be: when the fit was
+//     (a) best cosine distance < match_threshold, OR
-// invalid this node switched to a cosine-distance ceiling plus a ratio test
+//     (b) ratio test: best_dist/second_best_dist < match_ratio
-// (`match_threshold`, `match_ratio`, `match_ratio_ceil`). Three things were
+//         AND best_dist < match_ratio_ceil.
 // wrong with it, and the third is the one that mattered.
 //
-//   1. It violated AR-024 outright, untagged — a bare cosine threshold means
+// In both modes, per-actor best similarity is determined by scanning
-//      something different for every model, gallery and face size.
+// reference embeddings and taking the closest (best-of-N).
 //   2. It disagreed with the rest of the pipeline about what "calibration
 //      failed" means. `same_person_probability` answers that question by
 //      falling back to the untuned default sigmoid and saying so loudly, so
 //      tracking and evidence weighting stayed in probability space while
 //      matching alone left it. One run, two policies.
 //   3. Its accepted faces were still fed to `TrackRegistry::observe`, whose
 //      contract reads "posterior is a calibrated probability, never a raw
 //      cosine (AR-024) ... so the accumulation cannot be fed an uncalibrated
 //      number by a careless caller". It could. `max(0, cosine)` went straight
 //      into the log-odds accumulation as though it were a probability.
 //
 // An invalid fit now behaves exactly as everywhere else: the default sigmoid,
 // with a warning that says the probabilities are not meaningful. That is a
 // worse answer than a fitted calibration and a better one than a number whose
 // units nothing else in the pipeline shares.
 //
 // Gallery scan: the full reference set (tens of thousands of 512-dim
 // embeddings) is uploaded to the GPU once at construction time and stays
@@ -56,13 +38,6 @@
 // uploaded and a single SGEMM computes the full similarity matrix in well under
 // a millisecond. The GPU math backend (cuBLAS or rocBLAS) lives behind
 // ISimilarityEngine (backends/gemm_backend.cpp) and is selected at compile time.
 //
 // TRACES: AR-026 | SR-001
 // That resident matrix grows during a film: per-film expansion (AR-019) promotes
 // pose-varied views, and they are APPENDED to it rather than scored separately,
 // so one multiply covers baked and promoted references alike and best-of-N is a
 // single pass over one similarity column. There is no second similarity path in
 // this node to fall out of step with the first.
 struct IdentityMatcherFunc {
    static constexpr std::string_view label() { return "identity_matcher"; }
@@ -74,6 +49,9 @@ struct IdentityMatcherFunc {
        : gallery_(gallery)
        , prob_threshold_(cfg.prob_threshold)
        , log_prior_odds_(std::log(cfg.match_prior / (1.f - cfg.match_prior)))
        , threshold_(cfg.match_threshold)
        , ratio_(cfg.match_ratio)
        , ratio_ceil_(cfg.match_ratio_ceil)
        , track_gallery_(cfg)
    {
        std::cerr << "[identity_matcher] flattening gallery embeddings...\n";
@@ -106,21 +84,16 @@ struct IdentityMatcherFunc {
                      << cfg.gallery_path << "\n";
        }
-        /// TRACES: AR-024 | SR-002
+        if (cal_.valid) {
        // Same sentence either way, because it is the same decision rule; only
        // the provenance of (a, b) differs. An unfitted sigmoid still returns
        // plausible-looking probabilities, so the warning has to be the thing
        // that distinguishes them — nothing downstream can.
            std::cerr << "[identity_matcher] calibrated Bayesian matching"
                      << "  prior=" << cfg.match_prior
                      << "  P_threshold=" << prob_threshold_
                      << "  effective_sim_boundary="
                      << cal_.boundary_at(prob_threshold_, log_prior_odds_) << "\n";
-        if (!cal_.valid) {
+        } else {
-            std::cerr << "[identity_matcher] WARNING: the calibration is NOT fitted "
+            std::cerr << "[identity_matcher] threshold matching (calibration skipped)"
-                         "(a=" << cal_.a << ", b=" << cal_.b << ") — matching runs "
+                      << "  threshold=" << threshold_
-                         "on the untuned default sigmoid, so prob_threshold is not "
+                      << "  ratio=" << ratio_ << "  ratio_ceil=" << ratio_ceil_ << "\n";
                         "comparable to a tuned run's.\n";
        }
        std::cerr << "[identity_matcher] gallery: "
                  << gallery_.actors.size() << " actors, "
@@ -132,31 +105,6 @@ struct IdentityMatcherFunc {
                        flat_emb_[i].data(), 512 * sizeof(float));
        sim_engine_ = make_similarity_engine(host_gallery.data(), n_gallery_, kMaxFaces);
        /// TRACES: AR-018, AR-024 | SR-005
        // The expansion store thresholds in the same probability space as
        // association and evidence weighting, so a "0.9" means one thing
        // pipeline-wide rather than three.
        track_gallery_.set_calibration(same_person_probability(cal_));
    }
    /// TRACES: AR-023, AR-024 | SR-002
    /// The fitted sigmoid. Exposed because the matcher is where it gets fitted
    /// (and cached back to the gallery), but it is not the matcher's private
    /// property: track association and evidence weighting must threshold in the
    /// *same* probability space, or a "0.5" in one stage and a "0.5" in another
    /// mean different things. See `same_person_probability`.
    const GalleryCalibration& calibration() const { return cal_; }
    /// TRACES: AR-012, AR-025 | SR-002
    /// 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);
        // 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
@@ -170,111 +118,82 @@ 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
        // every diversity buffer here — a revived track simply re-accumulates its
        // buffer from post-cut frames. Stale cross-cut embeddings are never promoted.
-        /// TRACES: AR-019 | SR-005
+        if (tf.source.is_cut) track_gallery_.clear_tracks();
        // Promotion may only borrow same-identity evidence from a span where
        // identity is certain, so ALL THREE discontinuity signals clear the
        // buffers, not just the histogram cut:
        //   is_cut            — camera-angle change
        //   is_scene_boundary — different scene (AR-010; previously never set,
        //                       so this half of the gate was dead)
        // The third, an identity contradiction (AR-015), is enforced by the
        // registry: a track whose belief swapped is closed outright, so it can
        // no longer promote anything.
        if (tf.source.is_cut || tf.source.is_scene_boundary)
            track_gallery_.clear_tracks();
        const int n_faces = static_cast<int>(tf.embeddings.size());
        std::vector<IdentifiedActor> actors;
        actors.reserve(n_faces);
        if (n_faces == 0) return {std::move(tf.source), {}};
        if (n_faces > kMaxFaces)
            throw std::runtime_error("identity_matcher: n_faces exceeds kMaxFaces");
-        /// TRACES: AR-003, AR-004 | SR-002
+        std::vector<float> host_query(static_cast<size_t>(n_faces) * 512);
-        // kMaxFaces sizes the similarity engine's preallocated buffer, so it
+        for (int fi = 0; fi < n_faces; ++fi) {
-        // bounds MEMORY, not how many faces a frame may contain. It used to
+            std::memcpy(host_query.data() + static_cast<size_t>(fi) * 512,
-        // throw above the bound, which made it a hard cap on crowd scenes by
+                        tf.embeddings[fi].data(), 512 * sizeof(float));
        // accident; now the frame is scored in batches of that size.
        //
        // Faces per frame are unbounded (AR-003) because X-Ray credits scene
        // membership to background cast too, and a fixed cap discards exactly
        // those — the smallest faces are dropped first. Cost is contained by
        // backpressure (AR-004), which slows the producer, rather than by
        // silently throwing work away.
        std::vector<float> host_query(static_cast<size_t>(kMaxFaces) * 512);
        for (int base = 0; base < n_faces; base += kMaxFaces) {
        const int chunk = std::min(kMaxFaces, n_faces - base);
        for (int k = 0; k < chunk; ++k) {
            std::memcpy(host_query.data() + static_cast<size_t>(k) * 512,
                        tf.embeddings[base + k].data(), 512 * sizeof(float));
        }
-        /// TRACES: AR-026 | SR-001
+        // S (N_gallery × n_faces) col-major: face fi's gallery sims at sims + fi*n_gallery.
-        // One GEMM now covers baked references AND the per-film annex: promoted
+        const float* host_sims = sim_engine_->compute(host_query.data(), n_faces);
        // rows were appended to the engine's resident matrix, so they are just
        // more gallery rows with an entry in flat_actor_. The annex used to be
        // folded in afterwards by a host-side cosine loop, justified by "tens of
        // embeddings" — an assumption AR-018/AR-019 retired, since every owned
        // track promotes and the annex grows with cast size and film length.
        //
        // n_gallery() is read per frame, not cached: it grows as promotions land.
        const int    n_gal     = sim_engine_->n_gallery();
        const float* host_sims = sim_engine_->compute(host_query.data(), chunk);
-        for (int ci = 0; ci < chunk; ++ci) {
+        for (int fi = 0; fi < n_faces; ++fi) {
-            const int fi = base + ci;
+            const float* sims = host_sims + static_cast<size_t>(fi) * n_gallery_;
            const float* sims = host_sims + static_cast<size_t>(ci) * n_gal;
            std::vector<float> best_sim(gallery_.actors.size(),
                                        -std::numeric_limits<float>::max());
-            for (int ei = 0; ei < n_gal; ++ei) {
+            for (int ei = 0; ei < n_gallery_; ++ei) {
                float sim = sims[ei];
                int   ai  = flat_actor_[ei];
                if (sim > best_sim[ai]) best_sim[ai] = sim;
            }
-            // Only the best matters now. The runner-up was tracked solely for
+            // Fold in the per-film annex (CPU-side, tens of embeddings). Promoted
-            // the retired ratio test, which asked whether the best cosine stood
+            // pose-varied views compete for best-of-N exactly like baked refs, so
-            // out from the second — a question the calibrated posterior does
+            // a face at a pose the gallery lacked can now win its true actor.
-            // not need, since it already says how likely the best match is to
+            for (const auto& ae : track_gallery_.annex()) {
-            // be right rather than how much it beat its neighbour by.
+                float sim = cosine_similarity(tf.embeddings[fi], ae.emb);
-            int   best_actor = -1;
+                if (sim > best_sim[ae.actor_idx]) best_sim[ae.actor_idx] = sim;
            float best_s     = -std::numeric_limits<float>::max();
            for (int ai = 0; ai < static_cast<int>(best_sim.size()); ++ai) {
                if (best_sim[ai] > best_s) {
                    best_s     = best_sim[ai];
                    best_actor = ai;
                }
            }
-            /// TRACES: AR-024 | SR-002
+            int   best_actor   = -1;
-            // One rule, whatever the fit's provenance. The cosine reaches a
+            int   second_actor = -1;
-            // comparison only through cal_.probability().
+            float best_s       = -std::numeric_limits<float>::max();
-            const float best_p = best_actor >= 0
+            float second_s     = -std::numeric_limits<float>::max();
-                               ? cal_.probability(best_s, log_prior_odds_)
+            for (int ai = 0; ai < static_cast<int>(best_sim.size()); ++ai) {
-                               : 0.f;
+                if (best_sim[ai] > best_s) {
-            const bool accept = best_actor >= 0 && best_p > prob_threshold_;
+                    second_s     = best_s;
                    second_actor = best_actor;
                    best_s       = best_sim[ai];
                    best_actor   = ai;
                } else if (best_sim[ai] > second_s) {
                    second_s     = best_sim[ai];
                    second_actor = ai;
                }
            }
            (void)second_actor;
            bool accept = false;
            if (best_actor >= 0) {
                if (cal_.valid) {
                    accept = cal_.probability(best_s, log_prior_odds_) > prob_threshold_;
                } else {
                    float best_d   = 1.f - best_s;
                    float second_d = (second_s > -std::numeric_limits<float>::max())
                                     ? 1.f - second_s
                                     : std::numeric_limits<float>::max();
                    bool absolute = best_d < threshold_;
                    bool ratio    = (best_d < ratio_ceil_) &&
                                    (second_d == std::numeric_limits<float>::max() ||
                                     best_d / second_d < ratio_);
                    accept = absolute || ratio;
                }
            }
            IdentifiedActor ia;
            // Map bbox back to original video resolution when dense_scale
@@ -295,7 +214,9 @@ struct IdentityMatcherFunc {
                ia.imdb_id     = gallery_.actors[best_actor].imdb_id;
                ia.tmdb_id     = gallery_.actors[best_actor].tmdb_id;
                ia.jellyfin_id = gallery_.actors[best_actor].jellyfin_id;
-                ia.similarity = best_p;
+                ia.similarity = cal_.valid
                                ? cal_.probability(best_s, log_prior_odds_)
                                : best_s;
            }
            // Feed this face into per-film gallery expansion. best_actor/best_s
@@ -303,88 +224,27 @@ struct IdentityMatcherFunc {
            // face (annex already folded in above); the track's diversity buffer
            // keeps the gallery-far views and promotes them once the track is
            // confirmed. No-op unless --expand-gallery is set.
            // TRACES: AR-012, AR-025 | SR-002
            // Every scored face is evidence, not only the accepted ones: a run of
            // near-misses for one actor is itself informative, and discarding it
            // would make ownership depend on a per-frame threshold the redesign
            // exists to stop relying on. The registry discounts for correlation
            // and decides ownership from the accumulated posterior (AR-025).
            if (registry_ && best_actor >= 0 && tf.track_ids[fi] >= 0)
                registry_->observe(tf.track_ids[fi], best_actor, best_p,
                                   tf.embeddings[fi]);
            // TRACES: AR-019 | SR-005
            // Ownership is the registry's, computed once. TrackGallery used to
            // tally its own plurality vote over accepted frames, which meant two
            // different answers to "who is this track" could coexist — and the
            // expansion one ignored the Bayesian accumulation entirely.
            if (registry_ && tf.track_ids[fi] >= 0) {
                if (auto owner = registry_->owner(tf.track_ids[fi]))
                    track_gallery_.set_owner(tf.track_ids[fi], *owner);
            }
            track_gallery_.observe(tf.track_ids[fi], tf.embeddings[fi],
                                   best_actor, best_s, accept, tf.crops[fi]);
            actors.push_back(std::move(ia));
        }
        }   // chunk loop
        absorb_promotions();
        /// TRACES: AR-019 | SR-005
        // Drop buffers for tracks the registry has reaped. Without this a track
        // that simply went off screen kept its diversity buffer until the next
        // cut, so the store grew with the film rather than with what is on
        // screen — and a buffer that outlives its track is evidence about a
        // person nobody is looking at any more.
        if (registry_)
            track_gallery_.prune_dead(
                [this](int id) { return registry_->is_live(id); });
        return {std::move(tf.source), std::move(actors)};
    }
 private:
    /// TRACES: AR-026 | SR-001
    /// Move rows promoted during this frame into the resident gallery matrix,
    /// extending the actor mapping in lockstep so row i keeps naming the actor
    /// at flat_actor_[i]. Runs once per frame, after every face has been scored:
    /// appending mid-frame would invalidate the similarity pointer the chunk
    /// loop is still reading, and it is also the semantics the expansion store
    /// documents — a promotion helps SUBSEQUENT frames, never the one that
    /// produced it, so identification cannot depend on face order within a frame.
    void absorb_promotions() {
        if (!track_gallery_.enabled()) return;
        pending_emb_.clear();
        pending_actor_.clear();
        const int n = track_gallery_.drain_promotions(pending_emb_, pending_actor_);
        if (n == 0) return;
        sim_engine_->append_rows(pending_emb_.data(), n);
        flat_actor_.insert(flat_actor_.end(),
                           pending_actor_.begin(), pending_actor_.end());
        n_gallery_ = sim_engine_->n_gallery();
    }
    ActorGallery           gallery_;
    GalleryCalibration     cal_;
    float                  prob_threshold_;
    float                  log_prior_odds_;
-    /// flat_emb_ is the BAKED reference set only — it is the calibration fit's
+    float                  threshold_;
-    /// input (AR-023) and is not touched again after construction. flat_actor_,
+    float                  ratio_;
-    /// by contrast, is the actor mapping parallel to the *engine's* rows, so it
+    float                  ratio_ceil_;
    /// grows with every promotion absorbed (AR-026) and is the longer of the two.
    std::vector<Embedding> flat_emb_;
    std::vector<int>       flat_actor_;
    int                    n_gallery_{0};
    // Reused across frames so absorbing a promotion allocates nothing.
    std::vector<float>     pending_emb_;
    std::vector<int>       pending_actor_;
    std::unique_ptr<ISimilarityEngine> sim_engine_;
    TrackGallery                       track_gallery_;
    std::shared_ptr<TrackRegistry>     registry_;
 };
@@ -1,8 +1,6 @@
 #pragma once
 /// TRACES: IR-001 | SR-003
 #include "types.hpp"
 #include "config.hpp"
 #include "track_registry.hpp"
 #include <nlohmann/json.hpp>
 #include <algorithm>
@@ -11,8 +9,6 @@
 #include <fstream>
 #include <iostream>
 #include <map>
 #include <mutex>
 #include <functional>
 #include <string>
 #include <vector>
@@ -23,8 +19,7 @@ using json = nlohmann::json;
 //
 // Verbosity::minimal  — merges per-frame presence into contiguous time windows.
 //   Output: {
-//     "schema_version": 2, "movie": "...",
+//     "schema_version": 1, "movie": "...", "sample_fps": ..., "anneal_sec": ...,
 //     "extraction": { "sample_fps": ..., "extinction_sec": ..., "gallery_scope": ... },
 //     "actors": [{ "name", "imdb_id", "tmdb_id", "jellyfin_id", "scenes": [[t0,t1], ...] }]
 //   }
 //   An optional top-level "jellyfin_item_id" (the analysed title's Jellyfin item
@@ -47,26 +42,10 @@ using json = nlohmann::json;
 struct ResultSinkFunc {
    static constexpr std::string_view label() { return "result_sink"; }
    /// TRACES: AR-012, AR-017 | IR-002 | SR-002, SR-003
    /// A finished presence claim from the registry. Called from inside the
    /// registry's reap while it holds its own lock, so this must stay a cheap
    /// push and must never re-enter the registry.
    void add_claim(const DeadTrack& d) {
        if (d.actor_idx < 0) return;              // never owned: nothing to claim
        std::lock_guard<std::mutex> g(claims_mu_);
        claims_.push_back(d);
    }
    ResultSinkFunc(const Config& cfg, std::atomic<bool>& done)
        : cfg_(cfg), done_(done)
    {}
    /// TRACES: AR-016 | SR-002
    /// Runs immediately before the output is written, with the last timestamp
    /// seen. Used to flush tracks still live at EOF, which have not timed out
    /// and would otherwise never be emitted.
    void set_pre_write_hook(std::function<void(double)> fn) { pre_write_ = std::move(fn); }
    void operator()(SceneAnnotation sa) {
        if (sa.eof) {
            flush();
@@ -79,20 +58,12 @@ struct ResultSinkFunc {
                  << "  unknowns=" << count_unknown(sa.visible_actors)
                  << std::flush;
        for (const auto& ia : sa.visible_actors) {
            if (ia.actor_idx < 0) continue;
            auto& m = actor_meta_[ia.actor_idx];
            if (m.name.empty())
                m = {ia.name, ia.imdb_id, ia.tmdb_id, ia.jellyfin_id};
        }
        last_ts_ = sa.timestamp_sec;
        frames_.push_back(std::move(sa));
    }
    // Write accumulated results and signal done. Safe to call more than once.
    void flush() {
        if (written_.exchange(true)) return;
        if (pre_write_) pre_write_(last_ts_);
        write_output();
        done_.store(true, std::memory_order_release);
    }
@@ -100,7 +71,7 @@ struct ResultSinkFunc {
 private:
    // Bump when the minimal/standard output JSON structure changes in a way
    // the Jellyfin plugin needs to detect.
-    static constexpr int kSchemaVersion = 2;   // SR-003 coordinated bump
+    static constexpr int kSchemaVersion = 1;
    static int count_known(const std::vector<IdentifiedActor>& v) {
        int n = 0;
@@ -120,20 +91,10 @@ private:
        if (cfg_.verbosity == Verbosity::xray) {
            root = build_xray();
        } else {
            /// TRACES: IR-002 | SR-003
            /// schema_version 2, per jRay/SPEC.md JR-002. anneal_sec is REMOVED
            /// rather than zeroed: a field naming a mechanism the pipeline no
            /// longer has is actively misleading, and would outlive everyone who
            /// remembers why it reads 0. The extraction block reports
            /// track_extinction_sec, which bounds re-association -- not the
            /// withdrawn actor keep-alive that shared its name.
            root["schema_version"] = kSchemaVersion;
            root["movie"]      = cfg_.movie_path;
-            root["extraction"] = {
+            root["sample_fps"] = cfg_.sample_fps;
-                {"sample_fps",     cfg_.sample_fps},
+            root["anneal_sec"] = cfg_.anneal_sec;
                {"extinction_sec", cfg_.track_extinction_sec},
                {"gallery_scope",  cfg_.gallery_scope},
            };
            root["actors"]     = build_epochs();
            if (cfg_.verbosity == Verbosity::standard)
                root["frames"] = build_standard();
@@ -148,117 +109,53 @@ private:
        std::cerr << "[result_sink] done.\n";
    }
    struct Window {
        double start{0.0};
        double end{0.0};
        float  belief{0.f};   ///< the posterior that justified the claim (AR-017)
        Route  route{Route::live};   ///< how it was identified (AR-017)
    };
    struct ActorWindow {
        std::string name, imdb_id, tmdb_id, jellyfin_id;
-        std::vector<Window> scenes;
+        std::vector<std::pair<double, double>> scenes;  // [start_sec, end_sec]
    };
    struct ActorMeta { std::string name, imdb_id, tmdb_id, jellyfin_id; };
    // Core logic: merge per-frame detections into annealed [start, end] windows.
    /// TRACES: AR-012 | IR-002 | SR-002
    /// A claim already IS a window — `[first_seen, last_seen]` of a track the
    /// actor owned. There is no annealing pass: `anneal_sec` existed to bridge
    /// gaps between isolated accepted frames, and a track that survives its own
    /// gaps leaves it nothing to do (see the AR-012 withdrawal note).
    std::vector<ActorWindow> build_actor_windows() {
-        std::lock_guard<std::mutex> g(claims_mu_);
+        struct Info { std::string name, imdb_id, tmdb_id, jellyfin_id; };
        std::map<int, Info>                actor_info;
        std::map<int, std::vector<double>> timestamps;
-        std::map<int, ActorWindow> by_actor;
+        for (const auto& frame : frames_) {
-        for (const auto& c : claims_) {
+            for (const auto& ia : frame.visible_actors) {
-            auto& aw = by_actor[c.actor_idx];
+                if (ia.actor_idx < 0) continue;
-            if (aw.name.empty()) {
+                actor_info[ia.actor_idx] = {ia.name, ia.imdb_id, ia.tmdb_id, ia.jellyfin_id};
-                auto it = actor_meta_.find(c.actor_idx);
+                timestamps[ia.actor_idx].push_back(frame.timestamp_sec);
                if (it != actor_meta_.end()) {
                    aw.name        = it->second.name;
                    aw.imdb_id     = it->second.imdb_id;
                    aw.tmdb_id     = it->second.tmdb_id;
                    aw.jellyfin_id = it->second.jellyfin_id;
                }
            }
            aw.scenes.push_back({c.first_seen, c.last_seen, c.belief, c.route});
        }
        // Flood-fill: snap each claim to the shot it sits in, so an actor seen
        // once in a scene is reported across the whole scene. Bounded by real
        // TransNetV2 boundaries — a window never crosses one — and a no-op when
        // scene detection found no boundaries (nothing to snap to).
        if (cfg_.presence_mode == PresenceMode::flood) {
            const std::vector<double> bounds = scene_boundaries();
            if (!bounds.empty())
                for (auto& [idx, aw] : by_actor)
                    for (auto& w : aw.scenes) {
                        w.start = boundary_at_or_before(bounds, w.start);
                        w.end   = boundary_after(bounds, w.end);
            }
        }
        std::vector<ActorWindow> result;
-        for (auto& [idx, aw] : by_actor) {
+        for (auto& [idx, ts_vec] : timestamps) {
-            std::sort(aw.scenes.begin(), aw.scenes.end(),
+            ActorWindow aw;
-                      [](const Window& a, const Window& b) { return a.start < b.start; });
+            aw.name        = actor_info[idx].name;
            aw.imdb_id     = actor_info[idx].imdb_id;
            aw.tmdb_id     = actor_info[idx].tmdb_id;
            aw.jellyfin_id = actor_info[idx].jellyfin_id;
            double win_start = ts_vec[0], win_end = ts_vec[0];
            for (size_t i = 1; i < ts_vec.size(); ++i) {
                if (ts_vec[i] - win_end > cfg_.anneal_sec) {
                    aw.scenes.push_back({win_start, win_end});
                    win_start = ts_vec[i];
                }
                win_end = ts_vec[i];
            }
            aw.scenes.push_back({win_start, win_end});
            result.push_back(std::move(aw));
        }
        return result;
    }
    // Sorted, de-duplicated boundary timestamps seen this run, framed by the
    // film's own extent so the first and last shots are closed intervals. Derived
    // from frames_ rather than a separate accumulator: the frames are already
    // retained and this runs once.
    //
    // Prefers TransNetV2 shot boundaries (is_scene_boundary) when a scene detector
    // populated them; otherwise falls back to the always-on histogram cuts
    // (is_cut, camera_position_change_detector). On this ROCm box the scene
    // detector cannot run in-process (see the dumper note), so is_cut is what
    // flood-fill actually snaps to — coarser than true shot boundaries (cuts also
    // fire on in-shot angle changes) but present with no extra pass.
    std::vector<double> scene_boundaries() const {
        bool have_scene = false;
        for (const auto& sa : frames_)
            if (sa.is_scene_boundary) { have_scene = true; break; }
        std::vector<double> b;
        b.push_back(0.0);
        for (const auto& sa : frames_) {
            const bool boundary = have_scene ? sa.is_scene_boundary : sa.is_cut;
            if (boundary) b.push_back(sa.timestamp_sec);
        }
        b.push_back(last_ts_ + 1.0);   // a right edge past the final sample
        std::sort(b.begin(), b.end());
        b.erase(std::unique(b.begin(), b.end()), b.end());
        return b;
    }
    // The boundary opening the shot that contains t (largest boundary ≤ t).
    static double boundary_at_or_before(const std::vector<double>& b, double t) {
        auto it = std::upper_bound(b.begin(), b.end(), t);
        return (it == b.begin()) ? b.front() : *(it - 1);
    }
    // The boundary closing the shot that contains t (smallest boundary > t).
    static double boundary_after(const std::vector<double>& b, double t) {
        auto it = std::upper_bound(b.begin(), b.end(), t);
        return (it == b.end()) ? b.back() : *it;
    }
    json build_epochs() {
        json actors = json::array();
        for (const auto& aw : build_actor_windows()) {
            // Objects, not float pairs: a window carries the belief that
            // justified it and the route by which it was identified (AR-017),
            // so a consumer can caveat or filter rather than treating every
            // window as equally certain.
            json windows = json::array();
-            for (const auto& w : aw.scenes)
+            for (const auto& [s, e] : aw.scenes)
-                windows.push_back({{"start", w.start},
+                windows.push_back({s, e});
                                   {"end",   w.end},
                                   {"belief", w.belief},
                                   {"route", route_name(w.route)}});
            json ja;
            ja["name"]        = aw.name;
            ja["imdb_id"]     = aw.imdb_id;
@@ -276,9 +173,9 @@ private:
    json build_xray() {
        std::map<int, std::vector<std::string>> xray;
        for (const auto& aw : build_actor_windows()) {
-            for (const auto& w : aw.scenes) {
+            for (const auto& [start, end] : aw.scenes) {
-                int t0 = static_cast<int>(std::floor(w.start));
+                int t0 = static_cast<int>(std::floor(start));
-                int t1 = static_cast<int>(std::ceil(w.end));
+                int t1 = static_cast<int>(std::ceil(end));
                for (int t = t0; t <= t1; ++t)
                    xray[t].push_back(aw.name);
            }
@@ -329,9 +226,4 @@ private:
    std::atomic<bool>&           done_;
    std::atomic<bool>            written_{false};
    std::vector<SceneAnnotation> frames_;
    std::function<void(double)>  pre_write_;
    double                       last_ts_{0.0};
    std::mutex                   claims_mu_;
    std::vector<DeadTrack>       claims_;
    std::map<int, ActorMeta>     actor_meta_;   ///< actor_idx → identity keys
 };
@@ -1,75 +0,0 @@
 #pragma once
 /// TRACES: AR-010 | SR-002
 ///
 /// SceneBoundaryAnnotatorFunc — the join of the decode butterfly.
 ///
 /// `source` fans out to two branches: dense frames to TransNetV2, sampled frames
 /// to face detection. A boundary found on the first has to reach the second, and
 /// cannot ride along in the frame because the branches run in parallel.
 ///
 /// This node sits on the sampled branch and stamps `Frame::is_scene_boundary`
 /// from the detector's published verdict.
 ///
 /// **It only works because the sampled branch lags.** TransNetV2 buffers
 /// `kWindow` frames before it can score any of them, so this node must not reach
 /// a frame before the detector has an opinion about it. Channel depth creates
 /// that lag: with backpressure (AR-004) the fanout blocks on the slower branch,
 /// so a deep channel here lets the detector run ahead by its window instead of
 /// anything being dropped.
 ///
 /// When the lag is insufficient the node **counts it** rather than guessing.
 /// Annotating an unscored frame as boundary-free is indistinguishable from a
 /// genuine "no boundary here", and that is the failure that makes a downstream
 /// test pass while verifying nothing.
 #include "scene_boundaries.hpp"
 #include "types.hpp"
 #include <memory>
 #include <string_view>
 #include <utility>
 struct SceneBoundaryAnnotatorFunc {
    static constexpr std::string_view label() { return "scene_annotate"; }
    /// `tol` is half a sample interval. The branches sample at different rates,
    /// so a boundary found on a dense frame rarely lands exactly on a sampled
    /// one; half an interval attributes it to the nearest sampled frame and no
    /// further.
    SceneBoundaryAnnotatorFunc(std::shared_ptr<SceneBoundaries> b, double tol)
        : bounds_(std::move(b)), tol_(tol) {}
    Frame operator()(Frame f) {
        if (f.eof || !bounds_) return f;
        // Wait for the detector's verdict to cover this frame. Channel depth
        // alone cannot provide the lag: it holds frames back only when the
        // consumer is slower, and this branch is orders of magnitude faster per
        // frame than TransNetV2. Blocking here is what makes the join real.
        //
        // 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
            // pass for "no boundary here".
            bounds_->note_outran();
            return f;
        }
        f.is_scene_boundary = bounds_->is_boundary(f.timestamp_sec, tol_);
        return f;
    }
 private:
    std::shared_ptr<SceneBoundaries> bounds_;
    double                           tol_{0.0};
 };
@@ -1,13 +1,8 @@
 #pragma once
 #include "types.hpp"
 #include "config.hpp"
 #include "scene_boundaries.hpp"
 #include <memory>
 #include "inference/scene_detector.hpp"
 #include <opencv2/imgproc.hpp>   // cv::resize, for to_model_input
 #include <nlohmann/json.hpp>
 #include <algorithm>
 #include <atomic>
@@ -35,11 +30,6 @@
 struct SceneDetectorFunc {
    static constexpr std::string_view label() { return "scene_detector"; }
    /// TRACES: AR-010 | SR-002
    /// Publish each window's verdict as it is scored, so the face branch — held
    /// back by channel depth — can consult it for frames it has not reached yet.
    void set_boundaries(std::shared_ptr<SceneBoundaries> b) { shared_ = std::move(b); }
    SceneDetectorFunc(const Config& cfg, std::atomic<bool>& done)
        : detector_(make_scene_detector(cfg))
        , threshold_(cfg.scene_threshold)
@@ -61,24 +51,12 @@ struct SceneDetectorFunc {
    void operator()(Frame f) {
        if (f.eof) {
            flush_remaining();
            // Release anyone waiting on the join: the tail frames after the last
            // full window will never be covered, so waiting for them would hang.
            if (shared_) shared_->finish();
            write_output();
            done_.store(true, std::memory_order_release);
            return;
        }
-        /// TRACES: AR-011 | SR-002
+        images_.push_back(f.image);
        // Learn the cadence of the stream from the stream itself, rather than
        // assuming one. See dedup_window_sec().
        if (prev_ts_ >= 0.0 && intervals_.size() < kCadenceSamples) {
            const double dt = f.timestamp_sec - prev_ts_;
            if (dt > 0.0) intervals_.push_back(dt);
        }
        prev_ts_ = f.timestamp_sec;
        images_.push_back(to_model_input(f.image));
        times_.push_back(f.timestamp_sec);
        // Once we have a full window, score it and slide forward by `stride`.
@@ -92,76 +70,6 @@ struct SceneDetectorFunc {
        }
    }
    /// TRACES: AR-004, AR-010 | SR-002
    /// Reduce a decoded frame to exactly what TransNetV2 consumes, once.
    ///
    /// The window used to hold the frames as decoded — full resolution — and
    /// leave the downscale to the backend. But the model's input is 48x27
    /// (`ISceneDetector::kFrameW/H`; the config note for `dense_scale` says so
    /// outright: "TransNetV2 downsamples to 48x27 regardless"), so the buffer
    /// held ~590 MB at 1080p to feed something that needs ~380 KB. That is not
    /// a channel capacity, so no amount of tuning channel depths would ever
    /// have found it.
    ///
    /// It is also redundant work. Windows overlap by `kWindow - stride`, so a
    /// frame appears in several of them and was re-downscaled once per window;
    /// now it is downscaled once, when it arrives.
    ///
    /// **This must reproduce the backends' preprocessing exactly**, because the
    /// project invariant is that every model gets the input it was trained for
    /// — a model run off-distribution returns confident, plausible, wrong
    /// output, and here that means fabricated shot boundaries. Both
    /// ort_backend.cpp and trt_backend.cpp guard mis-sized input with, in this
    /// order, `convertTo(CV_8UC3)` then
    /// `cv::resize(..., {kFrameW, kFrameH}, 0, 0, cv::INTER_AREA)`. The same
    /// two operations are done here, so the tensor the model receives is
    /// unchanged; the backend guard then sees a correctly-sized frame and does
    /// nothing. The interface has always specified this shape as the caller's
    /// job ("Each frame must already be kFrameW x kFrameH, BGR, CV_8UC3"), so
    /// this makes the node meet a contract it was already given.
    static cv::Mat to_model_input(const cv::Mat& src) {
        cv::Mat typed;
        if (src.type() != CV_8UC3) src.convertTo(typed, CV_8UC3);
        else                       typed = src;
        if (typed.cols == ISceneDetector::kFrameW &&
            typed.rows == ISceneDetector::kFrameH)
            return typed;
        cv::Mat small;
        cv::resize(typed, small, {ISceneDetector::kFrameW, ISceneDetector::kFrameH},
                   0, 0, cv::INTER_AREA);
        return small;
    }
    /// TRACES: AR-011 | SR-002
    // How close two boundaries have to be before they are the same boundary,
    // derived from the cadence the detector was actually fed.
    //
    // What this replaces is a literal 0.04 s — one frame at 25 fps, and silently
    // wrong at any other rate. On a 30 fps source it spans more than a frame, so
    // two cuts on consecutive frames merge into one and a real boundary is lost;
    // the output does not show this, it simply contains fewer cuts. Assuming a
    // frame rate is the same class of mistake as feeding a model the wrong rate,
    // which is why this belongs to AR-011 and not to a tidy-up.
    //
    // Half a frame, not a whole one, because the only thing being deduplicated is
    // one frame scored by two overlapping windows — a gap of zero. Two distinct
    // frames are a full interval apart and must both survive. Half an interval
    // separates those two cases without putting the decision on the knife-edge
    // where floating-point error settles it.
    //
    // Median, not mean: a seek, or a gap where the decoder dropped a frame,
    // contributes one long interval that would drag a mean and cannot move a
    // median.
    static double dedup_window_sec(std::vector<double> intervals) {
        if (intervals.empty()) return 0.0;   // <2 frames: nothing to deduplicate
        const std::size_t mid = intervals.size() / 2;
        std::nth_element(intervals.begin(), intervals.begin() + mid,
                         intervals.end());
        return intervals[mid] * 0.5;
    }
 private:
    // Run TransNetV2 on the leading kWindow frames of the buffer and record any
    // boundaries found within the trusted centre region.
@@ -174,7 +82,6 @@ private:
        // otherwise skip the leading guard already covered by the previous window.
        const int lo = (window_base_ == 0) ? 0 : guard_;
        const int hi = ISceneDetector::kWindow - guard_;
        std::vector<double> fresh;
        for (int i = lo; i < hi; ++i) {
            if (probs[i] <= threshold_) continue;
            // Local maximum → the boundary frame (avoid a run of high scores
@@ -182,25 +89,8 @@ private:
            const bool peak =
                (i == 0        || probs[i] >= probs[i-1]) &&
                (i == kLast_() || probs[i] >= probs[i+1]);
-            if (peak) {
+            if (peak)
                boundaries_.push_back({times_[i], probs[i]});
                fresh.push_back(times_[i]);
            }
        }
        /// TRACES: AR-010 | SR-002
        // Publish with a watermark: everything up to times_[hi-1] now has a
        // final verdict. The face branch consults this for frames it has not
        // reached yet, and the watermark is what lets it tell "no boundary
        // here" from "not scored yet".
        /// TRACES: AR-011 | SR-002
        // Hand the join the same dedup window scenes.json uses, derived from the
        // observed cadence rather than assumed. Set on every window because the
        // median refines as intervals accumulate; it converges within the first
        // window and costs a double assignment thereafter.
        if (shared_) {
            shared_->set_merge_window(dedup_window_sec(intervals_));
            if (hi > lo) shared_->publish(fresh, times_[hi - 1]);
        }
    }
@@ -217,26 +107,13 @@ private:
        std::vector<float> probs = detector_->detect_window(win);
        const int lo = (window_base_ == 0) ? 0 : guard_;
        std::vector<double> fresh;
        for (int i = lo; i < n; ++i) {   // only real (non-padded) frames
            if (probs[i] <= threshold_) continue;
            const bool peak =
                (i == 0     || probs[i] >= probs[i-1]) &&
                (i == n - 1 || probs[i] >= probs[i+1]);
-            if (peak) {
+            if (peak)
                boundaries_.push_back({times_[i], probs[i]});
                fresh.push_back(times_[i]);
            }
        }
        /// TRACES: AR-010 | SR-002
        // Publish the tail too. Without this the final frames — everything after
        // the last full window — reach the join with no verdict and are treated
        // as boundary-free without evidence, which is precisely the ambiguity
        // the watermark exists to prevent.
        if (shared_ && n > 0) {
            shared_->set_merge_window(dedup_window_sec(intervals_));
            shared_->publish(fresh, times_[n - 1]);
        }
    }
@@ -245,8 +122,6 @@ private:
        written_ = true;
        // Merge boundaries closer than one frame apart (dedup across window seams).
        const double dedup_sec = dedup_window_sec(intervals_);
        std::sort(boundaries_.begin(), boundaries_.end(),
                  [](const Boundary& a, const Boundary& b) {
                      return a.t < b.t;
@@ -260,7 +135,7 @@ private:
        nlohmann::json cuts = nlohmann::json::array();
        double last_t = -1e9;
        for (const auto& b : boundaries_) {
-            if (b.t - last_t < dedup_sec) continue;
+            if (b.t - last_t < 0.04) continue;   // ~1 frame @25fps dedup
            cuts.push_back({{"t", b.t}, {"probability", b.prob}});
            last_t = b.t;
        }
@@ -273,12 +148,8 @@ private:
            return;
        }
        f << root.dump(2) << "\n";
        // Report the derived cadence: VR-006 re-tunes scene_threshold against it,
        // and a rate that is not the source's is the first thing to suspect.
        std::cerr << "\n[scene_detector] wrote " << root["cuts"].size()
-                  << " boundaries → " << output_path_
+                  << " boundaries → " << output_path_ << "\n";
                  << "  (dedup=" << dedup_sec << "s from "
                  << (dedup_sec > 0.0 ? 0.5 / dedup_sec : 0.0) << " fps)\n";
    }
    static int kLast_() { return ISceneDetector::kWindow - 1; }
@@ -292,10 +163,6 @@ private:
    struct Boundary { double t; float prob; };
    // Enough to establish a rate; bounded so a feature-length film does not
    // accumulate one double per frame for a number that stops moving early.
    static constexpr std::size_t kCadenceSamples = 512;
    std::unique_ptr<ISceneDetector> detector_;
    float                 threshold_;
    int                   stride_;
@@ -308,8 +175,5 @@ private:
    std::deque<double>    times_;
    int64_t               window_base_{0};   // frame index of images_.front()
    std::vector<Boundary> boundaries_;
    double                prev_ts_{-1.0};    // AR-011: cadence, learned not assumed
    std::vector<double>   intervals_;
    bool                  written_{false};
    std::shared_ptr<SceneBoundaries> shared_;   ///< AR-010 join point
 };
@@ -0,0 +1,102 @@
 #pragma once
 #include "types.hpp"
 #include "config.hpp"
 #include <map>
 #include <iostream>
 // ── SceneTrackerFunc ──────────────────────────────────────────────────────────
 // KPN node: maintains an extinction-timer state machine per identified actor.
 //
 // On each MatchedSceneFrame:
 //   1. Update last_seen for every matched known actor.
 //   2. Expire actors whose last_seen is older than extinction_sec.
 //   3. Emit SceneAnnotation with all currently active (non-expired) actors,
 //      including their most recently seen bbox and best similarity score.
 //
 // Unknown faces (actor_idx == -1) are passed through per-frame but are NOT
 // tracked across frames — each frame reports its own unknowns independently.
 struct SceneTrackerFunc {
    static constexpr std::string_view label() { return "scene_tracker"; }
    explicit SceneTrackerFunc(const Config& cfg)
        : extinction_sec_(cfg.extinction_sec)
    {
        std::cerr << "[scene_tracker] extinction_sec=" << extinction_sec_ << "\n";
    }
    // Runtime setter for pipeline reuse across a sweep. Also clears the active-actor
    // state so a re-run starts clean (no carry-over from the previous config's film).
    void set_extinction_sec(double s) { extinction_sec_ = s; active_.clear(); }
    SceneAnnotation operator()(MatchedSceneFrame mf) {
        if (mf.source.eof) return {0.0, {}, /*eof=*/true};
        double now = mf.source.timestamp_sec;
        // Update known actors
        for (const auto& ia : mf.actors) {
            if (ia.actor_idx < 0) continue;  // skip unknowns
            auto& slot = active_[ia.actor_idx];
            slot.last_seen   = now;
            slot.last_bbox   = ia.bbox;
            slot.last_crop   = ia.crop;
            slot.name        = ia.name;
            slot.imdb_id     = ia.imdb_id;
            slot.tmdb_id     = ia.tmdb_id;
            slot.jellyfin_id = ia.jellyfin_id;
            // Keep the best (highest) similarity seen in this window
            if (ia.similarity > slot.best_similarity)
                slot.best_similarity = ia.similarity;
        }
        // Expire stale actors
        for (auto it = active_.begin(); it != active_.end(); ) {
            if ((now - it->second.last_seen) > extinction_sec_)
                it = active_.erase(it);
            else
                ++it;
        }
        // Build annotation: active known actors
        std::vector<IdentifiedActor> visible;
        visible.reserve(active_.size() + mf.actors.size());
        for (const auto& [actor_idx, slot] : active_) {
            IdentifiedActor ia;
            ia.actor_idx   = actor_idx;
            ia.name        = slot.name;
            ia.imdb_id     = slot.imdb_id;
            ia.tmdb_id     = slot.tmdb_id;
            ia.jellyfin_id = slot.jellyfin_id;
            ia.similarity = slot.best_similarity;
            ia.bbox       = slot.last_bbox;
            ia.crop       = slot.last_crop;
            visible.push_back(ia);
        }
        // Append per-frame unknowns (actor_idx == -1) directly
        for (const auto& ia : mf.actors) {
            if (ia.actor_idx < 0) visible.push_back(ia);
        }
        return {now, std::move(visible)};
    }
 private:
    struct Slot {
        double      last_seen{0.0};
        float       best_similarity{0.f};
        cv::Rect2f  last_bbox;
        cv::Mat     last_crop;
        std::string name;
        std::string imdb_id;
        std::string tmdb_id;
        std::string jellyfin_id;
    };
    double               extinction_sec_;
    std::map<int, Slot>  active_;   // actor_idx → state
 };
--- a/Show More
+++ b/Show More