GR-004: bind galleries to the embedder that built them

A gallery is only valid for the embedder that produced its vectors. Cosine
similarities across models are meaningless but *look* plausible, so the mistake
is silent and every measurement taken afterwards is suspect. Stamp the embedder
identity into the gallery at build; verify it at every load.

The stamp is the model file's basename plus the SHA-256 of its bytes (plus
embed_dim). The hash decides, the name explains. A name alone is a promise
rather than a fact — models get re-exported and overwritten in place under an
unchanged filename, which is exactly the case where the weights differ and
nothing else does. A hash alone is correct but unactionable in an error message.
SHA-256 is derived from the artefact, needs no registry kept current, and costs
~0.1s for a 250MB ONNX, memoised per process.

Mismatch is a hard error in every mode, with no bypass, naming both sides.

Unstamped legacy galleries warn loudly and proceed: unknown is not known-bad,
and hard-failing every pre-existing gallery would turn the check into something
people disable rather than trust. --require-gallery-stamp (or
SAE_REQUIRE_GALLERY_STAMP=1, which propagates to subprocesses) promotes that to
a hard error — the mode measurement work should run in. scripts/stamp_gallery.py
re-binds an existing gallery with no re-embedding, so "warn" is a cheap state to
leave rather than a permanent one.

Embedding dumps carry the same stamp: a replay has no live embedder, so the dump
is the embedder as far as the gallery is concerned. Derived galleries inherit
their source's stamp; --merge and the JSON gallery merge check before writing,
since one file holding two embedding spaces cannot be untangled afterwards.

Verified in: scene_analyze, scene_preview, the sae_kpn matcher binding,
replay.py, optimize.py (once per film at startup, before the first evaluation),
movienet_eval.py and both merge paths.

Stamp logic lives in src/gallery/embedder_stamp.{hpp,cpp} and its Python twin
scripts/sae_stamp.py, kept dependency-light so replay subprocesses do not pay
sae_gallery's requests/Pillow import to ask whether two models match.

Tests: 12 new cases in test_gallery_store.cpp covering the comparison logic,
both round trips, and the SHA-256 vectors that guarantee the C++ and hashlib
stamps agree. No ONNX or GPU required.

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

scripts/optimizer/replay.py

@@ -25,6 +25,22 @@ 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):
@@ -92,6 +108,15 @@ def replay(dump_path: str, gallery: str, cfg: dict, build_dir: str, stop: bool =
     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()
@@ -122,7 +147,8 @@ def replay(dump_path: str, gallery: str, cfg: dict, build_dir: str, stop: bool =
     cap = len(frames) * 2 + 64
     sae_kpn.add_node_python(net, "replay", source, [], ["EmbeddedSceneFrame"], cap)
     sae_kpn.add_face_tracker(net, "tracker", cfg, cap)
-    sae_kpn.add_identity_matcher(net, "matcher", gallery, cfg, cap)
+    sae_kpn.add_identity_matcher(net, "matcher", gallery, cfg, cap,
+                                 stamp["model_name"], stamp["model_sha256"])
     sae_kpn.add_scene_tracker(net, "scene", cfg, cap)
     net.connect("replay", 0, "tracker", 0)
     net.connect("tracker", 0, "matcher", 0)
@@ -221,11 +247,17 @@ 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")
+    # 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.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