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/make_jellyfin_gallery.py

@@ -51,8 +51,9 @@ 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
-from sae_gallery import (download_image, download_images, load_gallery_hdf5,
+from sae_embed_loader import load_embedder, resolve_arcface
+from sae_gallery import (download_image, download_images, embedder_stamp,
+                        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 (
@@ -442,11 +443,20 @@ 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:
@@ -475,7 +485,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)
+    save_gallery(gallery, missing, output, embedder=stamp)
 
 
 if __name__ == "__main__":