feat: bind galleries to the embedder that built them

GR-004 — a gallery built with one embedding model is meaningless with another.
Cosine similarities across models are garbage but look entirely plausible, so
this fails silently and expensively; every measurement taken against a
mismatched pair would have been quietly wrong.

The stamp is the model basename plus a SHA-256 of its bytes, with embed_dim as
a cheap extra guard. The hash decides and the name explains, because neither
works alone: a name is a promise rather than a fact — models get re-exported in
place under an unchanged filename, which is exactly the case where the weights
differ and nothing else does — while a bare hash mismatch tells an operator
nothing actionable.

Mismatch is fatal in every mode with no bypass. Unstamped only warns, because
unstamped is unknown rather than known-bad, and an error firing on every legacy
gallery trains people to reach for the bypass reflexively. scripts/stamp_gallery.py
binds an existing gallery in place with no re-embedding, so the warning is a
migration step rather than a permanent state; --require-gallery-stamp promotes
it to an error once a site has migrated.

Two gaps found that would have defeated the requirement outright:

- Embedding dumps carried no stamp, so a replay — which has no live embedder —
  had nothing to check the gallery against. Dumps now carry embedder_model and
  embedder_sha256 as root attributes. Additive; schema_version stays 1. This is
  the same gap the dump audit identified independently.
- --merge produced one file holding two embedding spaces, which no later check
  can untangle. Merge paths now verify before writing.

The stamp also survives identity_matcher's calibration write-back, which would
otherwise have stripped it on the first analysis run — the check would have
worked exactly once.

Conflicts resolved additively: both branches appended a source to sae_gallery
and to the test target, and both edited the GR-004 register row.

Merged suite: 64 cases, 3199 assertions, passing on CPU with no GPU.

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

TRACES: GR-004, VR-001 | SR-001

scripts/filter_gallery.py

@@ -77,7 +77,11 @@ def main():
     if missing > 0:
         print(f"[warn] {missing} cast member(s) not present in gallery (not yet embedded)", file=sys.stderr)
 
-    save_gallery_hdf5({"actors": actors}, Path(args.output))
+    # TRACES: GR-004 | SR-001 — 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)
 
 

scripts/make_gallery.py

@@ -36,8 +36,9 @@ import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from sae_embed_loader import load_embedder
-from sae_gallery import download_images, save_gallery, wikidata_image_urls
+from sae_embed_loader import load_embedder, resolve_arcface
+from sae_gallery import (download_images, embedder_stamp, save_gallery,
+                         wikidata_image_urls)
 from sae_tmdb import TMDB_IMG, tmdb_get, tmdb_id_from_imdb
 
 
@@ -177,7 +178,11 @@ 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
@@ -203,7 +208,7 @@ def main():
     if n_actors == 0:
         sys.exit("No actors could be processed — check models and images.")
 
-    save_gallery(gallery, missing, output)
+    save_gallery(gallery, missing, output, embedder=stamp)
 
 
 if __name__ == "__main__":

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__":

scripts/movienet_eval.py

@@ -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
-from sae_gallery import load_gallery_hdf5
+from sae_embed_loader import load_embedder, resolve_arcface
+from sae_gallery import load_gallery_hdf5, verify_gallery_stamp
 
 
 def load_gallery(path: str) -> dict[str, dict]:
@@ -62,6 +62,11 @@ 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)

scripts/optimizer/SCHEMA.md

@@ -22,6 +22,8 @@ variable-length HDF5 types and reads straight into numpy.
     movie          : str   (source video path)
     sample_fps     : float
     embed_dim      : int   = 512
+    embedder_model : str   basename of the embedding model (GR-004)
+    embedder_sha256: str   SHA-256 of that model file (GR-004)
 
   frames/                             group — one row per sampled frame
     timestamp_sec  : float64 [F]
@@ -41,6 +43,20 @@ variable-length HDF5 types and reads straight into numpy.
 `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] ]`.
 
+## 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.
+
 ## 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]`.

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)

scripts/optimizer/optimize.py

@@ -34,6 +34,7 @@ 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
@@ -56,6 +57,8 @@ 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
@@ -180,7 +183,15 @@ 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:
@@ -188,6 +199,18 @@ 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:

scripts/optimizer/reembed_gallery.py

@@ -27,8 +27,9 @@ 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  # noqa: E402
-from sae_gallery import load_gallery_hdf5, save_gallery_hdf5  # noqa: E402
+from sae_embed_loader import load_embedder, resolve_arcface  # noqa: E402
+from sae_gallery import (embedder_stamp, load_gallery_hdf5,  # noqa: E402
+                         save_gallery_hdf5)
 
 
 def find_dir(images_root: Path, jellyfin_id: str, name: str) -> Path | None:
@@ -58,6 +59,11 @@ 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
@@ -84,7 +90,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))
+    save_gallery_hdf5({"actors": out_actors}, Path(args.out), stamp)
     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)

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

scripts/sae_embed_loader.py

@@ -3,11 +3,26 @@
 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
 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):
@@ -28,7 +43,7 @@ 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 = arcface if arcface else str(models_path / "arcface_w600k_r50.onnx")
+    arcface_path = resolve_arcface(models_dir, arcface)
     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")

scripts/sae_gallery.py

@@ -6,9 +6,13 @@ 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, and a
-per-embedding-row source_images array. calibration is left absent (calib_hash=0);
-the C++ identity_matcher fits and writes it back into the file on first use.
+offset/count, parallel imdb_id/tmdb_id/jellyfin_id/name string arrays, a
+per-embedding-row source_images array, and an /embedder group carrying the
+GR-004 model binding. calibration is left absent (calib_hash=0); the C++
+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
@@ -101,11 +105,36 @@ def download_images(urls: list[str], dest_dir: Path, n: int,
     return paths
 
 
-def save_gallery_hdf5(gallery: dict, output: Path) -> None:
+# ── GR-004: gallery ↔ embedder binding ───────────────────────────────────────
+# 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 = [], [], [], [], []
@@ -139,8 +168,17 @@ def save_gallery_hdf5(gallery: dict, output: Path) -> 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)
-    print(f"Saved: {output} ({len(actors)} actors, {emb_arr.shape[0]} embeddings)",
-          file=sys.stderr)
+        # TRACES: GR-004 | SR-001 — omitted entirely when unknown, so "unstamped"
+        # 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:
@@ -158,6 +196,14 @@ 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)):
@@ -167,15 +213,19 @@ 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)
-    return {"actors": actors}
+    out = {"actors": actors}
+    if stamp is not None:
+        out["embedder"] = stamp
+    return out
 
 
-def save_gallery(gallery: dict, missing: list[dict], output: Path) -> None:
+def save_gallery(gallery: dict, missing: list[dict], output: Path,
+                 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)
+    save_gallery_hdf5(gallery, output, embedder)
 
     if missing:
         missing_path = output.with_name(output.stem + ".missing_images.json")

scripts/sae_stamp.py

@@ -0,0 +1,217 @@
+"""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))

scripts/stamp_gallery.py

@@ -0,0 +1,86 @@
+#!/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())