feat(gemm): the annex is a matrix, not a list — scored by the same GEMM

The per-film annex was folded in after the gallery multiply by a host-side
cosine loop over a vector of {embedding, actor} structs, justified in-comment
by "tens of embeddings". AR-018/AR-019 retired that assumption: every owned
track promotes, so the annex grows with cast size and film length.

TrackGallery now holds it as a contiguous row-major matrix with a parallel
actor index — the flat_emb_/flat_actor_ shape the baked gallery already uses —
and hands newly promoted rows to the matcher once per frame. The matcher pushes
them into the similarity engine's resident matrix through a new
ISimilarityEngine::append_rows, so one SGEMM covers baked and promoted
references alike and best-of-N is a single pass over one similarity column.
Capacity doubles on overflow, and the GPU backends grow device-to-device, so a
promotion never re-uploads the gallery across the bus.

Absorbing promotions runs once per frame, after every face has been scored.
Appending mid-frame would invalidate the similarity pointer the chunk loop is
still reading, and it also removes an incidental dependence on face order
within a frame — a promotion helps subsequent frames, never the one that
produced it, which is the semantics the expansion store already documented.

OpenBLAS becomes a requirement of the CPU GEMM backend rather than an
opportunistic upgrade. That path is what CI and the cpu builder image run, so
falling back to the scalar loop in silence meant AR-027 could be measured — or
believed — on a kernel no release uses. The loop survives as the correctness
oracle the BLAS backends are diffed against, behind SAE_ALLOW_SCALAR_GEMM.

Call site 3, the deferred TBI pass, is untouched: it does not exist until
AR-020, so AR-026 stays In Progress.

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

TRACES: AR-026 | UT-004, UT-005 | SR-001

docs/SPEC.md

@@ -958,21 +958,45 @@ is the only viable formulation — a per-pair loop is orders of magnitude off.
 **All similarity computation goes through the GEMM path**, with no exception
 justified by "this set is small". Three call sites:
 
-1. **Baked gallery** — already GEMM (`sim_engine_->compute()`,
-   `identity_matcher_node.hpp:143`, backend from `SAE_GEMM_BACKEND`). ✓
-2. **Per-film annex** — currently a **CPU loop**
-   (`identity_matcher_node.hpp:159-162`), justified in-comment by "tens of
-   embeddings". AR-018…AR-021 invalidates that assumption: every owned track now
-   contributes, so the annex grows with cast size and film length. It must move
-   into the GEMM path — appended to the gallery matrix, or a second multiply.
+1. **Baked gallery** — GEMM (`sim_engine_->compute()`, backend from
+   `SAE_GEMM_BACKEND`). ✓
+2. **Per-film annex** — was a **CPU loop**, justified in-comment by "tens of
+   embeddings". AR-018…AR-021 invalidated that assumption: every owned track
+   contributes, so the annex grows with cast size and film length. Now appended
+   to the gallery matrix rather than scored separately — promotions are pushed
+   into the engine's resident matrix (`ISimilarityEngine::append_rows`,
+   capacity doubling, device-to-device on the GPU backends) and `flat_actor_`
+   grows in lockstep, so one multiply covers baked and promoted references and
+   best-of-N is a single pass over one similarity column. ✓
 3. **Deferred TBI pass (AR-020)** — the most GEMM-friendly operation in the
    pipeline: all TBI embeddings against the full gallery-plus-annex, offline,
    operands resident, no streaming. One large multiply, not a loop over entries.
+   Not yet built; AR-020 owns it.
+
+**Current:** 1 and 2 done. `TrackGallery` holds the annex as a contiguous
+row-major matrix plus a parallel actor index, and hands newly promoted rows to
+the matcher once per frame (`drain_promotions`), which is what call site 3 will
+score against.
+
+**Gap:** call site 3, gated on AR-020 existing at all.
 
 This constrains AR-018…AR-021's implementation: the annex must be a **contiguous matrix**
 with promotions appended, plus a parallel actor-index mapping — exactly the
 `flat_emb_`/`flat_actor_` arrangement the baked gallery already uses.
 
+**Ordering note.** Absorbing promotions is a once-per-frame step that runs after
+every face in the frame has been scored, not mid-frame. Appending mid-frame would
+invalidate the similarity pointer the matcher is still reading, and it also
+removes an accidental dependence on face order within a frame: a promotion helps
+subsequent frames, never the one that produced it, which is the semantics the
+expansion store already documents.
+
+**The CPU GEMM path requires OpenBLAS.** It is what CI and the cpu builder image
+run, so a silent fall back to the scalar loop would mean AR-027 is measured — or
+believed — on a path no release uses. Absence is a configure error; the scalar
+loop survives as the correctness oracle, reachable only via
+`-DSAE_ALLOW_SCALAR_GEMM=ON`.
+
 ### Scaling characteristics that must be known, not assumed
 
 - **Throughput versus gallery size must be measured** (VR-008) and published. The

docs/plan.md

@@ -255,8 +255,11 @@ Context crops opt-in behind `--dump-unidentified-crops`.
 
 ## AR-026, AR-027 — GEMM and scale
 
-**Depends on:** nothing to start. The annex CPU loop
-(`identity_matcher_node.hpp:159-162`) moves into the GEMM path.
+**Depends on:** nothing to start. The annex CPU loop has moved into the GEMM
+path: the annex is a contiguous matrix, promotions are appended to the engine's
+resident gallery, and the CPU backend now requires OpenBLAS. What is left of
+AR-026 is call site 3, the deferred pass — so the rest of AR-026 lands *with*
+AR-020 rather than before it.
 
 ---
 

docs/requirements.md

@@ -53,7 +53,7 @@ Status: `Done` · `In Progress` · `Planned` · `TBD` · `Withdrawn`
 | AR-023 | Fit sigmoid calibration from intra/inter similarity distributions | SR-002 | High | Done |
 | AR-024 | **Always the calibrated probability, never a raw cosine** — exceptions recorded | SR-002 | High | **Done** — association, accumulation and expansion all in probability space; `track_max_embed_dist`, `cut_revive_sim`, `expand_novelty_sim`, `expand_track_spread_max` retired |
 | AR-025 | Per-track Bayesian accumulation in log-odds, with correlated-observation discounting | SR-002 | High | **Done** — log-odds accumulation with correlation discounting owned by the registry, `src/evidence_discount.hpp` |
-| AR-026 | All similarity computed as GEMM, including annex and deferred pass | SR-001 | High | In Progress |
+| AR-026 | All similarity computed as GEMM, including annex and deferred pass | SR-001 | High | **In Progress** — two of the three call sites done. Baked gallery was already GEMM; the annex now is too — it is a contiguous row-major matrix (`track_gallery.hpp`) whose promoted rows are appended to the engine's resident matrix (`ISimilarityEngine::append_rows`), so one multiply covers baked and promoted references and the host-side cosine loop is gone. CPU path requires OpenBLAS (scalar fallback now opt-in behind `SAE_ALLOW_SCALAR_GEMM`). Remaining: the deferred pass, which does not exist until AR-020 |
 | AR-027 | Throughput acceptable for **arbitrary** gallery size | SR-001 | High | Planned |
 | AR-028 | **Embedding input quality assessed and carried** — every face scored on size, sharpness and visibility before its embedding is used as identity evidence; the vector travels with the face and reaches the VR-001 dump | SR-002 | High | Planned |
 | AR-029 | Sharpness measure on the **aligned crop** (scale-normalised, so it cannot re-measure size) | SR-002 | Medium | Planned |