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

@@ -35,7 +35,9 @@ 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_gallery import download_images, wikidata_image_urls   # noqa: E402
+from sae_embed_loader import resolve_arcface                   # 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
 
 
@@ -57,6 +59,7 @@ 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 = []
@@ -103,7 +106,9 @@ 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)
 
-    Path(out_path).write_text(json.dumps({"actors": actors}, indent=2))
+    # TRACES: GR-004 | SR-001 — 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}",
@@ -115,6 +120,12 @@ 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)