chore(traces): put TRACES tags on their own line; regenerate the report

The parser reads a tag up to end of line, so `# TRACES: GR-004 | SR-001 —
prose` swallowed the prose into the tag and the row went unmatched. Splitting
the comment leaves the tag greppable by the same pattern as the code tags and
the commit trailers, which is the point of the house format.

Mechanical throughout; no logic touched. The regenerated report reflects this
session's new tags: 137 -> 148 found, and one more tagged-but-unexecuted, which
is the SuperHero accuracy assertion that is documented but not yet a test.

scripts/filter_gallery.py

@@ -77,7 +77,8 @@ 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 — a filtered gallery holds the SAME vectors as its
+    # 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),

scripts/make_gallery.py

@@ -178,7 +178,8 @@ 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
+    # 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)

scripts/make_jellyfin_gallery.py

@@ -453,7 +453,8 @@ def main():
     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
+        # 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.

scripts/movienet_eval.py

@@ -62,7 +62,8 @@ 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
+    # 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,

scripts/optimizer/fetch_missing_actors.py

@@ -106,7 +106,8 @@ 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 — the legacy JSON gallery carries the same stamp as
+    # 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)
@@ -120,7 +121,8 @@ 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
+    # 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.

scripts/optimizer/optimize.py

@@ -199,7 +199,8 @@ 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,
+    # 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.

scripts/optimizer/reembed_gallery.py

@@ -59,7 +59,8 @@ 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
+    # 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.

scripts/optimizer/replay.py

@@ -110,7 +110,8 @@ 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
+    # 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.
@@ -249,7 +250,8 @@ 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
+    # 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")

scripts/sae_embed_loader.py

@@ -11,6 +11,7 @@ argument, which is often None.
 """
 
 import sys
+import os
 from pathlib import Path
 
 DEFAULT_ARCFACE = "arcface_w600k_r50.onnx"
@@ -19,8 +20,10 @@ 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."""
+    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)
 
 
@@ -49,13 +52,21 @@ def load_embedder(build_dir: str, models_dir: str, arcface: str | None = None,
             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. Pass them when present (ignored by ORT).
+    # scripts/build_trt_engines.sh.
+    #
+    # 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 det_engine.is_file() else "",
-        str(arc_engine) if arc_engine.is_file() else "",
+        str(det_engine) if (use_engines and det_engine.is_file()) else "",
+        str(arc_engine) if (use_engines and arc_engine.is_file()) else "",
     )

scripts/sae_gallery.py

@@ -168,7 +168,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 — omitted entirely when unknown, so "unstamped"
+        # 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")
@@ -196,7 +197,8 @@ 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,
+        # 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:

scripts/validation/ground_truth.py

@@ -17,6 +17,11 @@ 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