ElideDB query by example: no text, no model at query time

.dockerignore

@@ -0,0 +1,9 @@
+# Only what the image needs enters the build context. The lake and
+# datasets are tens of GB; the demo store ships from deploy/demo.
+*
+!python
+!scripts/get_iv2.py
+!deploy
+deploy/demo/lake/bench/tables/*/_cache
+!.dockerignore
+python/**/__pycache__

.gitattributes

@@ -0,0 +1,4 @@
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.h264 filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,34 @@
+# ElideDB query-by-example service. Build from the REPO ROOT:
+#   docker build -f deploy/Dockerfile.qbe -t elidedb-qbe .
+#   docker run -p 7860:7860 -v $PWD/lake:/app/lake elidedb-qbe
+#
+# Deliberately not the text image. That one carries torch and five text
+# towers because a sentence has to be encoded before it can be matched.
+# Query by example matches vectors the store already holds, so this image
+# has no model in it at all - it boots as fast as the store downloads.
+FROM python:3.11-slim
+
+# ffmpeg muxes the clips the results play; every frame is decoded from the
+# stored video's own bytes, so there is no image or preview cache anywhere.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY deploy/requirements-qbe.txt /app/deploy/requirements-qbe.txt
+RUN pip install --no-cache-dir -r deploy/requirements-qbe.txt
+
+COPY python /app/python
+COPY deploy/entrypoint-qbe.sh /app/deploy/entrypoint-qbe.sh
+COPY deploy/qbe_serve.py /app/deploy/qbe_serve.py
+COPY deploy/qbe_ui.html /app/deploy/qbe_ui.html
+RUN chmod +x /app/deploy/entrypoint-qbe.sh
+
+ENV PYTHONPATH=/app/python \
+    ELIDEDB_DEVICE=cpu \
+    DEMO_STORE_DATASET=SudharshanR/elidedb-demo-store \
+    ELIDEDB_LAKE=lake \
+    PORT=7860 \
+    HF_HOME=/app/hf_cache
+
+EXPOSE 7860
+CMD ["/app/deploy/entrypoint-qbe.sh"]

README.md

@@ -0,0 +1,38 @@
+---
+title: ElideDB Query by Example
+emoji: 🎬
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# ElideDB — query by example
+
+1,122 robot episodes, and not one word of text. Pick a few clips that show
+the same kind of moment; the archive returns its own kind.
+
+**Why this exists.** A text encoder scores *"open the drawer"* against
+*"close the drawer"* at cosine 0.977, and a pooled video embedding scores a
+clip against its own reversal at 1.000000. Description destroys the
+distinction before search begins. A clip needs no description: it is an
+instance of what it shows.
+
+**What runs when you click.** Nothing loads. Every vector was computed when
+the video was written, so a query is arithmetic over parquet columns —
+about 250 ms over the whole archive. Six channels vote, weighted by how
+tightly each one pulls *your* picks together relative to how it holds the
+archive: a statistic taken from the query itself, with no labels and no
+training. The panel shows those weights, because which model recognised
+your pick is the interesting part of the answer.
+
+**How many come back.** The count is a ceiling, not a target. Each pick is
+held out in turn to see how deep its own kind ranks, and the set stops
+where that evidence stops — returned means believed.
+
+Thumbnails and clips are decoded from the stored video's own byte ranges on
+demand. There is no preview cache anywhere in the store.
+
+The text-query demo of the same engine is at
+[SudharshanR/elidedb-demo](https://huggingface.co/spaces/SudharshanR/elidedb-demo).

deploy/entrypoint-qbe.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# First start fetches the demo store (Space repos cap at 1 GB, so it ships
+# as a public dataset). Nothing else is downloaded: this service loads no
+# model, which is the point of it.
+set -e
+cd /app
+if [ -n "$DEMO_STORE_DATASET" ] && [ ! -d /app/lake/bench ]; then
+  python - <<'PY'
+import os
+from huggingface_hub import snapshot_download
+snapshot_download(os.environ["DEMO_STORE_DATASET"],
+                  repo_type="dataset", local_dir="/app/lake")
+print("demo store downloaded", flush=True)
+PY
+fi
+exec python deploy/qbe_serve.py

deploy/qbe_serve.py

@@ -0,0 +1,189 @@
+"""The query-by-example Space: point at a moment, get its kind back.
+
+WHY A SECOND DEPLOYMENT. The text Space answers "describe what you want"
+and pays for it: five text towers, model weights on first boot, minutes
+before the first query. This one answers the question a text encoder
+provably cannot - direction - and costs no model at all. Everything it
+ranks was computed at ingest; serving is numpy over parquet columns.
+That is the whole argument for the storage layer, and it deserves to be
+demonstrable in seconds rather than after a fifteen minute warm.
+
+The read path is elidedb.qbe.search_like verbatim - multi-seed centroid,
+per-channel seed-coherence weighting, z-fusion, and a return cut
+calibrated from the query's own held-out seeds. Nothing here re-tunes it;
+this file is a surface, not a second implementation.
+
+Media (thumbnails, clips) reuses elidedb.desk's byte-range decode path,
+which is the same one the text Space serves from - one media path, not a
+copy that can drift.
+
+    python deploy/qbe_serve.py [--port 7860] [--root lake]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+sys.path.insert(0, "python")
+
+import numpy as np  # noqa: E402
+
+from elidedb import desk as D  # noqa: E402  (media + store discovery)
+from elidedb import qbe  # noqa: E402
+
+HERE = Path(__file__).resolve().parent
+UI = HERE / "qbe_ui.html"
+_EPISODES: dict = {}
+_SPACES: dict = {}
+
+
+def episodes(key):
+    """[(stream, ts, label)] for one store, ordered. The label is shown
+    AFTER retrieval so a visitor can check the answer; it is never read
+    by the ranker - search_like sees vectors and nothing else."""
+    if key in _EPISODES:
+        return _EPISODES[key]
+    db = D.STORES[key]
+    ep = db.table("episodes").scan()
+    cols = ep.column_names
+    lab = next((c for c in ("text", "task", "instruction", "label", "name")
+                if c in cols), None)
+    rows = list(zip(ep.column("stream").to_pylist(),
+                    ep.column("ts").to_pylist(),
+                    ep.column(lab).to_pylist() if lab
+                    else [""] * ep.num_rows))
+    rows = [(str(s), int(t), (str(x) if x else "")) for s, t, x in rows]
+    rows.sort(key=lambda r: (r[0], r[1]))
+    _EPISODES[key] = rows
+    return rows
+
+
+def warm(key):
+    """Build the channel matrices once, at boot.
+
+    spaces() reads every per-episode vector table and pools it. On the
+    demo store that is a couple of seconds and a few hundred megabytes
+    of parquet; paying it per query would make the first click look
+    broken for no reason, and paying it at import means the platform
+    reports RUNNING only when queries are genuinely warm - the same
+    lesson the text Space learned the expensive way.
+    """
+    t0 = time.time()
+    keys, M = qbe.spaces(D.STORES[key])
+    _SPACES[key] = (keys, M)
+    print(f"warm {key}: {len(keys)} episodes, "
+          f"{len(M)} channels ({', '.join(sorted(M))}), "
+          f"{time.time() - t0:.1f}s", flush=True)
+
+
+def like(key, seeds, k_max):
+    db = D.STORES[key]
+    t0 = time.time()
+    out = qbe.search_like(db, [(s, int(t)) for s, t in seeds], k_max=k_max)
+    lab = {(s, t): x for s, t, x in episodes(key)}
+    return dict(
+        clips=[dict(stream=s, ts=t, label=lab.get((s, int(t)), ""))
+               for s, t in out["clips"]],
+        weights={c: round(float(w), 3)
+                 for c, w in sorted(out.get("weights", {}).items(),
+                                    key=lambda kv: -kv[1])},
+        note=out.get("note", ""), ms=int((time.time() - t0) * 1000))
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def _send(self, code, body, ctype, cache=False):
+        b = body if isinstance(body, bytes) else json.dumps(body).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(b)))
+        if cache:
+            self.send_header("Cache-Control", "public, max-age=86400")
+        self.end_headers()
+        self.wfile.write(b)
+
+    def _json(self, obj, code=200):
+        self._send(code, obj, "application/json")
+
+    def do_GET(self):
+        u = urlparse(self.path)
+        q = {k: v[0] for k, v in parse_qs(u.query).items()}
+        try:
+            if u.path in ("/", "/index.html"):
+                return self._send(200, UI.read_bytes(),
+                                  "text/html; charset=utf-8")
+            if u.path == "/api/archive":
+                key = q.get("store") or next(iter(D.STORES))
+                rows = episodes(key)
+                return self._json(dict(
+                    store=key, stores=sorted(D.STORES),
+                    channels=sorted(_SPACES.get(key, ([], {}))[1]),
+                    episodes=[dict(stream=s, ts=t, label=x)
+                              for s, t, x in rows]))
+            if u.path == "/api/thumb":
+                jpg = D.api_thumb(q.get("store") or next(iter(D.STORES)),
+                                  q.get("stream", ""), int(q["t"]),
+                                  int(q.get("w", "260")))
+                if jpg is None:
+                    return self._json({"error": "no frame"}, 404)
+                return self._send(200, jpg, "image/jpeg", cache=True)
+            if u.path == "/api/clip":
+                mp4 = D.api_clip(q.get("store") or next(iter(D.STORES)),
+                                 q.get("stream", ""), int(q["t0"]),
+                                 int(q["t1"]), int(q.get("w", "480")))
+                if isinstance(mp4, dict):
+                    return self._json(mp4, 422)
+                if mp4 is None:
+                    return self._json({"error": "no frames"}, 404)
+                return self._send(200, mp4, "video/mp4", cache=True)
+            return self._json({"error": "not found"}, 404)
+        except Exception as e:
+            return self._json({"error": f"{type(e).__name__}: {e}"}, 500)
+
+    def do_POST(self):
+        u = urlparse(self.path)
+        try:
+            n = int(self.headers.get("Content-Length", 0))
+            body = json.loads(self.rfile.read(n) or b"{}")
+            if u.path == "/api/like":
+                seeds = body.get("seeds", [])
+                if not seeds:
+                    return self._json({"error": "pick at least one clip"},
+                                      400)
+                key = body.get("store") or next(iter(D.STORES))
+                return self._json(like(key, seeds,
+                                       int(body.get("k", 24))))
+            return self._json({"error": "not found"}, 404)
+        except Exception as e:
+            return self._json({"error": f"{type(e).__name__}: {e}"}, 500)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--port", type=int,
+                    default=int(os.environ.get("PORT", "7860")))
+    ap.add_argument("--host", default="0.0.0.0")
+    ap.add_argument("--root", default=os.environ.get("ELIDEDB_LAKE", "lake"))
+    a = ap.parse_args()
+    D.ROOT = Path.cwd()
+    D.LAKE = Path(a.root)
+    D.discover()
+    if not D.STORES:
+        raise SystemExit(f"no store under {a.root}/ - set ELIDEDB_LAKE or "
+                         f"download the demo store first")
+    for key in D.STORES:
+        warm(key)
+    print(f"query by example on http://{a.host}:{a.port}", flush=True)
+    ThreadingHTTPServer((a.host, a.port), Handler).serve_forever()
+
+
+if __name__ == "__main__":
+    main()

deploy/qbe_ui.html

@@ -0,0 +1,198 @@
+<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ElideDB · Query by Example</title>
+<style>
+  :root{
+    --bg:#0b0e10; --panel:#131719; --line:#232a2e; --ink:#e2e8ea;
+    --dim:#8a969c; --accent:#6ee7a8; --accent-dim:#1d3a2e; --warn:#e3b341;
+    --mono:ui-monospace,SFMono-Regular,"SF Mono",Menlo,monospace;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);
+       font:14px/1.55 var(--mono)}
+  header{padding:16px 22px;border-bottom:1px solid var(--line)}
+  h1{margin:0;font-size:15px;font-weight:600;letter-spacing:.01em}
+  header p{margin:5px 0 0;color:var(--dim);font-size:12px;max-width:76ch}
+  header b{color:var(--ink);font-weight:600}
+  main{padding:16px 22px 40px}
+  .bar{position:sticky;top:0;z-index:5;background:var(--bg);
+       border-bottom:1px solid var(--line);padding:11px 0;margin-bottom:14px;
+       display:flex;gap:12px;align-items:center;flex-wrap:wrap}
+  .bar .count{color:var(--dim);font-size:12px}
+  .bar .count b{color:var(--accent)}
+  button{background:var(--accent-dim);border:1px solid #2f5c48;
+    color:var(--accent);padding:8px 16px;border-radius:6px;
+    font:13px var(--mono);cursor:pointer}
+  button:disabled{opacity:.35;cursor:default}
+  button.ghost{background:transparent;border-color:var(--line);
+    color:var(--dim)}
+  h2{font-size:11px;letter-spacing:.08em;text-transform:uppercase;
+     color:var(--dim);margin:22px 0 9px;font-weight:600}
+  .grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(150px,1fr));
+        gap:9px}
+  .c{position:relative;border:1px solid var(--line);border-radius:6px;
+     overflow:hidden;background:var(--panel);cursor:pointer;aspect-ratio:4/3}
+  .c img,.c video{width:100%;height:100%;object-fit:cover;display:block}
+  .c .ph{width:100%;height:100%;background:#0f1315}
+  .c.on{border-color:var(--accent);box-shadow:0 0 0 1px var(--accent)}
+  .c .t{position:absolute;left:0;bottom:0;right:0;padding:3px 6px;
+        background:linear-gradient(transparent,rgba(0,0,0,.82));
+        font-size:10px;color:#c7d0d4}
+  .c .n{position:absolute;top:5px;left:6px;font-size:10px;color:var(--accent);
+        background:rgba(0,0,0,.6);padding:1px 5px;border-radius:3px}
+  #results .c{cursor:default}
+  .why{border:1px solid var(--line);border-radius:8px;background:var(--panel);
+       padding:12px 14px;margin:10px 0 4px}
+  .why .h{font-size:11px;letter-spacing:.06em;text-transform:uppercase;
+          color:var(--dim);margin-bottom:9px}
+  .w{display:flex;align-items:center;gap:9px;margin:4px 0;font-size:12px}
+  .w .nm{width:62px;color:var(--ink)}
+  .w .track{flex:1;height:7px;background:#0f1315;border-radius:4px;
+            overflow:hidden}
+  .w .fill{height:100%;background:var(--accent)}
+  .w .v{width:44px;text-align:right;color:var(--dim)}
+  .note{color:var(--dim);font-size:11.5px;margin-top:9px;line-height:1.5}
+  .note b{color:var(--ink);font-weight:600}
+  .err{color:var(--warn)}
+  .tray{display:flex;gap:6px;flex-wrap:wrap;margin-bottom:10px}
+  .tray .chip{width:62px;height:47px;object-fit:cover;border-radius:4px;
+    border:1px solid var(--accent);cursor:pointer}
+  .pager{display:flex;gap:10px;align-items:center;margin:6px 0 10px}
+</style>
+<header>
+  <h1>ElideDB · query by example</h1>
+  <p><b>1,122 robot episodes, and not one word of text.</b> Pick clips that
+  show the same kind of moment; the archive returns its own kind. Nothing is
+  described, nothing is labelled, and no model runs to answer you — every
+  vector was computed when the video was written, so a query is arithmetic
+  over columns.</p>
+</header>
+<main>
+  <div class="bar">
+    <span class="count"><b id="nsel">0</b> picked <span id="hint">·
+      8–10 of the same kind works best</span></span>
+    <button id="go" disabled>find more like these</button>
+    <button id="clear" class="ghost">clear</button>
+    <span class="count" id="stat"></span>
+  </div>
+  <div id="seltray" class="tray"></div>
+  <div id="out"></div>
+  <h2 id="archhead">the archive</h2>
+  <div class="pager" id="pager"></div>
+  <div class="grid" id="archive"></div>
+  <div class="pager" id="pager2"></div>
+</main>
+<script>
+const $=s=>document.querySelector(s);
+const esc=t=>String(t).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+let EPS=[], STORE='', sel=[];
+
+const thumb=(e,w)=>`/api/thumb?store=${encodeURIComponent(STORE)}&stream=${encodeURIComponent(e.stream)}&t=${e.ts}&w=${w||220}`;
+const clip =e=>`/api/clip?store=${encodeURIComponent(STORE)}&stream=${encodeURIComponent(e.stream)}&t0=${e.ts}&t1=${e.ts+6000000000}&w=420`;
+const shortName=e=>e.stream.split('/').pop()+' · '+new Date(e.ts/1e6).toISOString().slice(11,19);
+
+// Thumbnails are decoded on demand from the video's own bytes - there is no
+// pre-baked image anywhere in the store. A page at a time is what makes that
+// affordable: 120 decodes at ~50 ms, not 1,122. They load eagerly on purpose.
+// Both deferred approaches - IntersectionObserver and loading="lazy" - left
+// the grid blank in verification, and an archive you cannot see is not an
+// archive you can pick from. A bounded page costs less than a clever one.
+const PAGE=120; let page=0;
+
+function card(e,i){
+  return `<div class="c${sel.includes(i)?' on':''}" data-i="${i}">
+    <img decoding="async" src="${thumb(e)}" alt="">
+    <div class="t">${esc(shortName(e))}</div></div>`;
+}
+
+function paintArchive(){
+  const n=Math.ceil(EPS.length/PAGE);
+  page=Math.max(0,Math.min(page,n-1));
+  const a=page*PAGE, b=Math.min(a+PAGE,EPS.length);
+  $('#archive').innerHTML=EPS.slice(a,b).map((e,k)=>card(e,a+k)).join('');
+  $('#pager').innerHTML=`<button class="ghost" id="prev" ${page?'':'disabled'}>&larr;</button>
+    <span class="count">${a+1}–${b} of ${EPS.length}</span>
+    <button class="ghost" id="next" ${page<n-1?'':'disabled'}>&rarr;</button>`;
+  const pv=$('#prev'), nx=$('#next');
+  if(pv)pv.onclick=()=>{page--;paintArchive();};
+  if(nx)nx.onclick=()=>{page++;paintArchive();};
+}
+
+function refreshSel(){
+  $('#nsel').textContent=sel.length;
+  $('#go').disabled=sel.length===0;
+  $('#hint').textContent=sel.length>=8?'· good sample size':(sel.length?'· add a few more of the same kind':'· 8–10 of the same kind works best');
+  [...$('#archive').children].forEach(d=>{
+    d.classList.toggle('on', sel.includes(+d.dataset.i));
+  });
+  const t=$('#seltray');
+  t.innerHTML=sel.length?sel.map(i=>
+    `<img class="chip" src="${thumb(EPS[i],120)}" data-i="${i}" title="click to drop">`).join(''):'';
+}
+
+$('#archive').addEventListener('click',ev=>{
+  const c=ev.target.closest('.c'); if(!c)return;
+  const i=+c.dataset.i, k=sel.indexOf(i);
+  if(k>=0) sel.splice(k,1); else sel.push(i);
+  refreshSel();
+});
+$('#seltray').addEventListener('click',ev=>{
+  if(ev.target.dataset.i===undefined)return;
+  const k=sel.indexOf(+ev.target.dataset.i);
+  if(k>=0){sel.splice(k,1);refreshSel();}
+});
+$('#clear').onclick=()=>{sel=[];refreshSel();$('#out').innerHTML='';$('#stat').textContent='';};
+
+$('#go').onclick=async()=>{
+  $('#go').disabled=true; $('#stat').textContent='ranking…';
+  const body={store:STORE,k:24,seeds:sel.map(i=>[EPS[i].stream,EPS[i].ts])};
+  let d;
+  try{ d=await (await fetch('/api/like',{method:'POST',body:JSON.stringify(body)})).json(); }
+  catch(e){ d={error:String(e)}; }
+  $('#go').disabled=false;
+  if(d.error){ $('#stat').innerHTML=`<span class="err">${esc(d.error)}</span>`; return; }
+  $('#stat').textContent=`${d.ms} ms`;
+  const ws=Object.entries(d.weights||{});
+  const mx=Math.max(...ws.map(x=>x[1]),1e-9);
+  $('#out').innerHTML=`
+    <h2>what came back — ${d.clips.length} moments</h2>
+    <div class="grid" id="results">${d.clips.map((e,i)=>
+      `<div class="c" data-r="${i}">
+         <img decoding="async" src="${thumb(e)}" alt="">
+         <span class="n">${i+1}</span>
+         <div class="t">${esc(shortName(e))}</div></div>`).join('')}
+    </div>
+    <div class="why">
+      <div class="h">which model recognised your pick</div>
+      ${ws.map(([c,w])=>`<div class="w"><span class="nm">${esc(c)}</span>
+        <span class="track"><span class="fill" style="width:${(100*w/mx).toFixed(1)}%"></span></span>
+        <span class="v">${w.toFixed(2)}</span></div>`).join('')}
+      <div class="note">Every channel votes, but not equally. The weight is
+      how tightly that model pulls <b>your</b> picks together relative to how
+      it holds the whole archive — computed from the query itself, with no
+      labels and no training. ${d.note?`<br><b>${esc(d.note)}</b>`:''}
+      <br>The number returned is a <b>ceiling, not a target</b>: each pick is
+      held out in turn to see how deep its own kind ranks, and the set stops
+      where that evidence stops. Returned means believed.</div>
+    </div>`;
+  const g=$('#results');
+  [...g.children].forEach((div,i)=>{
+    const e=d.clips[i];
+    div.onclick=()=>{
+      if(div.querySelector('video'))return;
+      const v=document.createElement('video');
+      v.src=clip(e); v.controls=true; v.autoplay=true; v.loop=true; v.muted=true;
+      div.querySelector('img').replaceWith(v);
+    };
+  });
+  window.scrollTo({top:0,behavior:'smooth'});
+};
+
+(async()=>{
+  const d=await (await fetch('/api/archive')).json();
+  EPS=d.episodes; STORE=d.store;
+  $('#archhead').textContent=`the archive — ${EPS.length} episodes, ${d.channels.length} channels (${d.channels.join(', ')})`;
+  paintArchive();
+})();
+</script>

deploy/requirements-qbe.txt

@@ -0,0 +1,13 @@
+# The query-by-example service. NO MODEL RUNS AT QUERY TIME: every vector
+# was computed at ingest, so serving is numpy over parquet columns and the
+# torch stack that the text service needs is simply absent. That is the
+# difference between a fifteen minute first boot and a fifteen second one,
+# and it is the storage argument made concrete rather than asserted.
+numpy<2.1
+pyarrow>=17
+pillow>=10
+huggingface_hub>=0.26
+# the frame decoder behind every thumbnail and clip: frames are decoded
+# from the stored video's own byte ranges on demand, never pre-baked, so
+# the decoder is not optional even though no model is.
+opencv-python-headless>=4.10

python/elidedb.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: elidedb
+Version: 2.0.0
+Summary: Parquet-native, timestamp-first multimodal database — the best read is the read elided
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyarrow>=15
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: duckdb
+Requires-Dist: pillow
+Requires-Dist: opencv-python
+Requires-Dist: mlx-embeddings
+Requires-Dist: scikit-learn
+Requires-Dist: hdbscan
+Requires-Dist: umap-learn
+Requires-Dist: matplotlib
+Requires-Dist: jupyter
+Provides-Extra: ml
+Requires-Dist: mlx-embeddings; extra == "ml"
+Requires-Dist: scikit-learn; extra == "ml"
+Requires-Dist: hdbscan; extra == "ml"
+Requires-Dist: umap-learn; extra == "ml"
+
+# ElideDB
+
+**A Parquet-native, timestamp-first database for multimodal data.** Put any
+timestamped data in — sensor rows, video, GPS, audio, logs — and get back
+time-window reads, SQL, and semantic search, while the engine reads as few
+bytes as physically possible. *The best read is the read elided.*
+
+- **Everything is Parquet.** Every table is plain Parquet files under a
+  Delta-Lake-style transaction log. No custom formats; DuckDB, Spark, pandas —
+  anything that reads Parquet reads your database.
+- **Timestamps are the law.** Every table has a `ts` column (int64
+  nanoseconds). That one rule is what makes cross-modal queries, alignment,
+  and pruning work.
+- **Media is indexed, never copied.** Video files stay exactly where they
+  are; ElideDB stores byte ranges into them and decodes only the frames a
+  query touches.
+- **Search by meaning.** Local SigLIP embeddings (no cloud) turn video into
+  searchable windows: `"a person crossing the street"` → playable clips.
+
+## Install
+
+```bash
+pip install -e ".[ml]"     # from the repo root; [ml] adds semantic search
+brew install ffmpeg        # clip playback + video indexing
+```
+
+## 60 seconds to your first database
+
+```bash
+elidedb create lake/mydb --name "my project"
+
+# any timestamped rows: CSV/Parquet, ISO dates or epoch s/ms/us/ns (auto-detected)
+elidedb add lake/mydb readings sensor_log.csv --ts-col time
+
+# any video (the file is indexed in place, not copied)
+elidedb video lake/mydb dashcam.mp4 --stream front
+
+elidedb ls lake/mydb                                   # what's inside
+elidedb sql lake/mydb "SELECT count(*) FROM readings"  # SQL via DuckDB
+elidedb embed lake/mydb                                # local ML, one command
+elidedb search lake/mydb "a cyclist passing a bus"     # → time windows
+elidedb desk                                           # browse it
+```
+
+The same five verbs in Python:
+
+```python
+from elidedb import Store
+db = Store.create("lake/mydb", "my project")
+db.ingest_rows("readings", df, ts_column="time")     # DataFrame/CSV/Parquet
+db.ingest_video("frames", "dashcam.mp4", stream="front")
+db.embed_windows(); import elidedb; elidedb.cluster(db)
+hits, _ = db.search_text("a cyclist passing a bus")  # → (stream, t0, t1)
+window, stats = db.window(hits[0]["t0"], hits[0]["t1"])
+print(stats)                                          # bytes touched vs corpus
+```
+
+## Documentation
+
+| doc | what it covers |
+|---|---|
+| [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) | step-by-step: install → create → add your data → query → browse |
+| [docs/API.md](docs/API.md) | every class, method, and CLI verb |
+| [DESIGN.md](DESIGN.md) | architecture + which idea came from which system (Delta, Spark, C-Store, warehouses) |
+| [notebooks/elidedb_demo.ipynb](notebooks/elidedb_demo.ipynb) | every query style, executed on real data with outputs baked in |
+| [BENCHMARKS.md](BENCHMARKS.md) | measured numbers on 28.5 GB of real captures |
+
+## ElideDB Desk
+
+`elidedb desk` (or double-click `desk/ElideDB Desk.app` on macOS) opens the
+database browser: every store's tables and timelines, a semantic map where
+hovering any point decodes its frame live, click-to-play clips (with the
+sensor's audio track when the store has one), and a query console for
+SQL / semantic / window queries.
+
+## The numbers that matter (measured, [BENCHMARKS.md](BENCHMARKS.md))
+
+- 2 s window over a **14.16 M-row** audio table: touches **4 MB of 286 MB
+  (98.6 % elided)**, 165 ms.
+- Multimodal 2 s window across 15 tables: 10/56 files touched, **98.9 %
+  elided, 13.8 ms** (sensor-only).
+- Semantic search: ranking is **microseconds** at thousands of windows;
+  end-to-end text query ≈ 2.8 s (model load dominates, then it stays warm).
+- Store is *smaller* than the raw input in both real corpora, while adding
+  random access, SQL, and search.
+
+## Repository layout
+
+```
+python/elidedb/     the database (store, log, video, embeddings, cli, desk)
+notebooks/          executed demo notebook
+desk/               macOS app bundle (thin launcher for elidedb.desk)
+src/, tests/        v1: the original C++20 engine with hand-built formats
+                    (SDX/SFI) — the mechanisms ElideDB now hosts on Parquet
+scripts/            dataset ETL adapters (REIP, Oxford RobotCar) + tooling
+```
+
+Raw data (`data/`), generated databases (`lake/`, `store*/`), and build
+output are git-ignored — the repo carries code and docs only.

python/elidedb.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+python/elidedb/__init__.py
+python/elidedb/ann.py
+python/elidedb/bptree.py
+python/elidedb/cli.py
+python/elidedb/desk.py
+python/elidedb/desk_ui.html
+python/elidedb/embeddings.py
+python/elidedb/fftools.py
+python/elidedb/log.py
+python/elidedb/migrate.py
+python/elidedb/store.py
+python/elidedb/video.py
+python/elidedb.egg-info/PKG-INFO
+python/elidedb.egg-info/SOURCES.txt
+python/elidedb.egg-info/dependency_links.txt
+python/elidedb.egg-info/entry_points.txt
+python/elidedb.egg-info/requires.txt
+python/elidedb.egg-info/top_level.txt

python/elidedb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python/elidedb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+elidedb = elidedb.cli:main

python/elidedb.egg-info/requires.txt

@@ -0,0 +1,18 @@
+pyarrow>=15
+numpy
+pandas
+duckdb
+pillow
+opencv-python
+mlx-embeddings
+scikit-learn
+hdbscan
+umap-learn
+matplotlib
+jupyter
+
+[ml]
+mlx-embeddings
+scikit-learn
+hdbscan
+umap-learn

python/elidedb.egg-info/top_level.txt

@@ -0,0 +1 @@
+elidedb

python/elidedb/__init__.py

@@ -0,0 +1,14 @@
+"""ElideDB — a Parquet-only, timestamp-first multimodal store.
+
+>>> from elidedb import Store
+>>> db = Store.open("lake/oxford")
+>>> db.describe()
+>>> data, stats = db.window(t0, t1)
+>>> db.sql("SELECT count(*) FROM gps")
+>>> db.search_text("pedestrians crossing")
+"""
+from .store import Store, Table, QueryStats
+from .embeddings import cluster, embed_text
+
+__version__ = "2.0.0"
+__all__ = ["Store", "Table", "QueryStats", "cluster", "embed_text"]

python/elidedb/action_channel.py

@@ -0,0 +1,77 @@
+"""The `act` channel: SSv2 action posteriors as an INDEX-ONLY ranking
+signal. Ingested once per episode (scripts/action_ingest.py: V-JEPA 2
+ViT-L + Meta's released attentive probe, 174 classes); a query costs a
+cached text-vector pass over the 174 class names plus one 174-d dot per
+episode.
+
+Adoption measurement (2026-07-24, labeled episodes, zero fitting):
+put-in vs take-out AUC 0.889 with the literal class pair — the exact
+containment direction the green-drawer failure exposed and no other
+channel measures. Directional queries score a CONTRAST of class
+weights, w(text) − w(swap), mirroring the swap-contrast law used
+everywhere else in this system.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+_IDX = {}
+
+
+def _index(store):
+    ver = store.table("action_probs").state().version
+    key = (str(store.dir), ver)
+    if key not in _IDX:
+        from .embeddings import _vec_table
+        tbl, _ = _vec_table(store, "action_probs")
+        ss = tbl.column("stream").to_pylist()
+        sa = [int(v) for v in tbl.column("ts").to_pylist()]
+        sb = [int(v) for v in tbl.column("t1").to_pylist()]
+        idx = {}
+        for r, (s, a, b) in enumerate(zip(ss, sa, sb)):
+            idx.setdefault(str(s), []).append((a, b, r))
+        for s in idx:
+            idx[s].sort()
+        if len(_IDX) > 8:
+            _IDX.clear()
+        _IDX[key] = idx
+    return _IDX[key]
+
+
+def act_lookup(store, text, contrast=None):
+    """(lookup(stream, t0, t1) -> weighted posterior | nan,
+    candidates top-64). Rows in action_probs are one per episode.
+    `contrast`: an explicit 174-d weight vector (canonical_contrast)
+    overrides the text-mapped weights."""
+    from .action_probe import query_class_weights
+    from .embeddings import _vec_table
+    from .rerank import directional_swap
+
+    idx = _index(store)
+    _, probs = _vec_table(store, "action_probs")
+
+    if contrast is not None:
+        w = contrast
+    else:
+        w = query_class_weights(text)
+        sq = directional_swap(text, store)
+        if sq is not None:
+            w = w - query_class_weights(sq)
+    sc = np.asarray(probs) @ w
+
+    def lookup(s, a, b):
+        lst = idx.get(str(s))
+        if not lst:
+            return float("nan")
+        starts = [x[0] for x in lst]
+        j = int(np.searchsorted(starts, a, side="right")) - 1
+        if j >= 0 and b <= lst[j][1] + 1:
+            return float(sc[lst[j][2]])
+        return float("nan")
+
+    cands = []
+    for s, lst in idx.items():
+        for a, b, r in lst:
+            cands.append((s, a, b, float(sc[r])))
+    cands.sort(key=lambda x: -x[3])
+    return lookup, cands[:64]

python/elidedb/action_probe.py

@@ -0,0 +1,190 @@
+"""ACTION PROBE — video-native verb grounding, zero LLM/VLM anywhere.
+
+The calibration that forced this: both VLM judge tiers overclaim scene
+matches (7B est 1.0 on visually ~10%-pure sets) — a language model shown
+frames cannot bind actions. User directive: no LLM/VLM judges, ever.
+
+Replacement: Meta's released SSv2 attentive probe on the V-JEPA 2 ViT-L
+encoder ALREADY in the stack (291 ms/16-frame clip on MPS, measured).
+Something-Something-v2's 174 classes are literally the failing query
+taxonomy of this database — "Closing something", "Opening something",
+"Picking something up", "Putting something into something", "Taking
+something out of something", "Covering something with something" (= lid
+on vessel), "Folding something". The probe is 174-way evidence about
+WHAT HAPPENED in the clip, produced by a video model trained on motion,
+not a text model guessing from two frames.
+
+Faithful port of vjepa2/src/models/attentive_pooler.py (MIT): 3
+self-attn blocks over ALL encoder tokens -> 1-query cross-attn pool ->
+linear(1024 -> 174). Class list vendored as data/ssv2_classes.txt —
+this is the MODEL's output vocabulary (like a tokenizer), not dataset
+metadata; the no-metadata rule stays intact.
+
+Query -> class mapping rides the PE text tower already cached: cosine
+between the query and the 174 class names, softmaxed over the top few.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+_STATE = {}
+
+PROBE_CKPT = Path(__file__).resolve().parents[2] / \
+    "models/ssv2-vitl-16x2x3.pt"
+ENCODER_ID = "facebook/vjepa2-vitl-fpc64-256"
+N_CLASSES = 174
+
+
+def ssv2_classes():
+    if "classes" not in _STATE:
+        p = Path(__file__).parent / "data/ssv2_classes.txt"
+        _STATE["classes"] = [ln.strip() for ln in
+                             p.read_text().splitlines() if ln.strip()]
+        assert len(_STATE["classes"]) == N_CLASSES
+    return _STATE["classes"]
+
+
+def _build_probe():
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+
+    dim, heads = 1024, 16
+
+    class MLP(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.fc1 = nn.Linear(dim, dim * 4)
+            self.act = nn.GELU()
+            self.fc2 = nn.Linear(dim * 4, dim)
+
+        def forward(self, x):
+            return self.fc2(self.act(self.fc1(x)))
+
+    class Attention(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.qkv = nn.Linear(dim, dim * 3, bias=True)
+            self.proj = nn.Linear(dim, dim)
+
+        def forward(self, x):
+            B, N, C = x.shape
+            qkv = self.qkv(x).reshape(B, N, 3, heads, C // heads) \
+                .permute(2, 0, 3, 1, 4)
+            y = F.scaled_dot_product_attention(qkv[0], qkv[1], qkv[2])
+            return self.proj(y.transpose(1, 2).reshape(B, N, C))
+
+    class Block(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.norm1 = nn.LayerNorm(dim)
+            self.attn = Attention()
+            self.norm2 = nn.LayerNorm(dim)
+            self.mlp = MLP()
+
+        def forward(self, x):
+            x = x + self.attn(self.norm1(x))
+            return x + self.mlp(self.norm2(x))
+
+    class CrossAttention(nn.Module):
+        # NOTE: Meta's probe CrossAttention has NO output projection
+        def __init__(self):
+            super().__init__()
+            self.q = nn.Linear(dim, dim, bias=True)
+            self.kv = nn.Linear(dim, dim * 2, bias=True)
+
+        def forward(self, q, x):
+            B, n, C = q.shape
+            qh = self.q(q).reshape(B, n, heads, C // heads) \
+                .transpose(1, 2)
+            N = x.shape[1]
+            kv = self.kv(x).reshape(B, N, 2, heads, C // heads) \
+                .permute(2, 0, 3, 1, 4)
+            y = F.scaled_dot_product_attention(qh, kv[0], kv[1])
+            return y.transpose(1, 2).reshape(B, n, C)
+
+    class CrossAttentionBlock(nn.Module):
+        # norm1 normalizes the CONTEXT tokens, not the query (Meta)
+        def __init__(self):
+            super().__init__()
+            self.norm1 = nn.LayerNorm(dim)
+            self.xattn = CrossAttention()
+            self.norm2 = nn.LayerNorm(dim)
+            self.mlp = MLP()
+
+        def forward(self, q, x):
+            q = q + self.xattn(q, self.norm1(x))
+            return q + self.mlp(self.norm2(q))
+
+    class AttentivePooler(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.query_tokens = nn.Parameter(torch.zeros(1, 1, dim))
+            self.cross_attention_block = CrossAttentionBlock()
+            self.blocks = nn.ModuleList([Block() for _ in range(3)])
+
+        def forward(self, x):
+            for blk in self.blocks:
+                x = blk(x)
+            q = self.query_tokens.repeat(len(x), 1, 1)
+            return self.cross_attention_block(q, x)
+
+    class AttentiveClassifier(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.pooler = AttentivePooler()
+            self.linear = nn.Linear(dim, N_CLASSES)
+
+        def forward(self, x):
+            return self.linear(self.pooler(x).squeeze(1))
+
+    return AttentiveClassifier()
+
+
+def _load():
+    if "model" in _STATE:
+        return _STATE
+    import torch
+    from transformers import AutoModel, AutoVideoProcessor
+    from .device import pick
+    dev, dtype = pick()
+    enc = AutoModel.from_pretrained(ENCODER_ID, dtype=dtype) \
+        .to(dev).eval()
+    probe = _build_probe()
+    sd = torch.load(PROBE_CKPT, map_location="cpu",
+                    weights_only=False)["classifiers"][0]
+    sd = {k.replace("module.", ""): v for k, v in sd.items()}
+    probe.load_state_dict(sd, strict=True)
+    probe = probe.to(dev).float().eval()
+    _STATE.update(model=enc, probe=probe, dev=dev, dtype=dtype,
+                  proc=AutoVideoProcessor.from_pretrained(ENCODER_ID))
+    return _STATE
+
+
+def clip_action_probs(frames_u8):
+    """16 HWC uint8 frames -> softmax over 174 SSv2 classes."""
+    import torch
+    st = _load()
+    px = st["proc"](videos=[list(frames_u8)], return_tensors="pt")[
+        "pixel_values_videos"].to(st["dev"], st["dtype"])
+    with torch.no_grad():
+        feats = st["model"](pixel_values_videos=px).last_hidden_state
+        logits = st["probe"](feats.float())
+    return torch.softmax(logits[0], -1).cpu().numpy()
+
+
+def query_class_weights(text, top=5):
+    """Query text -> sparse weights over SSv2 classes via the PE text
+    tower (cached). Softmax over the top matches; everything else 0."""
+    from .pe import _text_vec
+    if "clsvec" not in _STATE:
+        _STATE["clsvec"] = np.stack(
+            [_text_vec(c.lower()) for c in ssv2_classes()])
+    sims = _STATE["clsvec"] @ _text_vec(text)
+    w = np.zeros(N_CLASSES)
+    ix = np.argsort(-sims)[:top]
+    e = np.exp((sims[ix] - sims[ix].max()) / 0.05)
+    w[ix] = e / e.sum()
+    return w

python/elidedb/ann.py

@@ -0,0 +1,154 @@
+"""ANN tiers over the embeddings table. Three mechanisms, one contract:
+
+- exact       one matmul; correct by definition; right up to ~10^6 vectors
+- IVF         learned cells (HDBSCAN centroids, embeddings.py) — prune cells,
+              scan survivors exactly; noise always scanned
+- HNSW        graph ANN (hnswlib) for sub-ms search past the matmul crossover
+- IVF-PQ      product quantization: vectors compressed ~48x into subspace
+              codes; asymmetric-distance scan + EXACT rerank of the top pool
+              (the SCANN/Faiss recipe: approximate to shortlist, never to
+              answer)
+
+Artifacts are version-suffixed sidecars under tables/embeddings/_index/,
+rebuilt like any derived state, and recorded in the table log. Search picks
+the best available tier automatically; every path supports HYBRID
+retrieval — time-range and stream predicates pushed into candidate
+selection so vector search composes with the store's core dimension, time.
+"""
+from __future__ import annotations
+
+import json
+
+import numpy as np
+
+
+def _run_dir(store):
+    d = store.dir / "tables" / "embeddings" / "_index"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _emb(store):
+    from .embeddings import _vec_table
+    return _vec_table(store)
+
+
+def build_hnsw(store, M: int = 16, ef_construction: int = 200) -> dict:
+    """Hierarchical navigable small world graph over unit vectors
+    (inner-product space == cosine). O(log n) expected search hops."""
+    import hnswlib
+    t, vecs = _emb(store)
+    v = store.table("embeddings").state().version
+    ix = hnswlib.Index(space="ip", dim=vecs.shape[1])
+    ix.init_index(max_elements=len(vecs), M=M,
+                  ef_construction=ef_construction, random_seed=7)
+    ix.add_items(vecs, np.arange(len(vecs)))
+    path = _run_dir(store) / f"hnsw.v{v}.bin"
+    ix.save_index(str(path))
+    (path.with_suffix(".json")).write_text(json.dumps(
+        {"dim": int(vecs.shape[1]), "n": len(vecs), "M": M}))
+    # An ANN index is a derived sidecar keyed to the embeddings DATA version,
+    # not a new data version — building it must NOT advance the log (doing so
+    # would invalidate the artifact we just named .v{v} against the bumped
+    # current version). The .v{v} filename IS the binding.
+    return {"n": len(vecs), "bytes": path.stat().st_size, "version": v}
+
+
+def load_hnsw(store):
+    # Look for the artifact BEFORE importing. hnswlib is an optional
+    # accelerator; when it is absent the planner must fall back to the exact
+    # scan, not raise ModuleNotFoundError out of the middle of a query and
+    # take down search entirely.
+    cands = sorted(_run_dir(store).glob("hnsw.v*.bin"), reverse=True)
+    if not cands:
+        return None
+    try:
+        import hnswlib
+    except ImportError:
+        return None
+    v = store.table("embeddings").state().version
+    for cand in cands:
+        if int(cand.stem.split(".v")[-1]) != v:
+            continue  # stale: embeddings changed since this was built
+        meta = json.loads(cand.with_suffix(".json").read_text())
+        ix = hnswlib.Index(space="ip", dim=meta["dim"])
+        ix.load_index(str(cand), max_elements=meta["n"])
+        return ix
+    return None
+
+
+def build_ivfpq(store, nlist: int | None = None, m: int = 8,
+                nbits: int = 8) -> dict:
+    """Coarse k-means cells + per-subspace codebooks. A d=1152 float32
+    vector becomes `m` uint8 codes (m=8 → 576x… realistically 4608B → 8B =
+    576x raw, ~48x vs the parquet-compressed vectors). Scans read codes, not
+    vectors; the exact rerank reads only the shortlist's true vectors."""
+    from sklearn.cluster import KMeans
+    t, vecs = _emb(store)
+    n, d = vecs.shape
+    v = store.table("embeddings").state().version
+    nlist = nlist or max(1, int(np.sqrt(n)))
+    coarse = KMeans(n_clusters=min(nlist, n), n_init=4,
+                    random_state=0).fit(vecs)
+    resid = vecs - coarse.cluster_centers_[coarse.labels_]
+    assert d % m == 0, f"dim {d} not divisible by m={m}"
+    sub = d // m
+    codebooks = np.zeros((m, 2 ** nbits, sub), np.float32)
+    codes = np.zeros((n, m), np.uint8)
+    for j in range(m):
+        block = resid[:, j * sub:(j + 1) * sub]
+        km = KMeans(n_clusters=min(2 ** nbits, n), n_init=2,
+                    random_state=j).fit(block)
+        k = km.cluster_centers_.shape[0]
+        codebooks[j, :k] = km.cluster_centers_
+        codes[:, j] = km.labels_.astype(np.uint8)
+    path = _run_dir(store) / f"ivfpq.v{v}.npz"
+    np.savez_compressed(path, centers=coarse.cluster_centers_,
+                        labels=coarse.labels_.astype(np.int32),
+                        codebooks=codebooks, codes=codes)
+    # derived sidecar keyed to the embeddings data version; no log bump (see
+    # build_hnsw) — the .v{v} filename binds it to the current vectors.
+    return {"n": n, "nlist": int(nlist), "m": m,
+            "bytes": path.stat().st_size,
+            "code_bytes_per_vec": m, "version": v}
+
+
+def load_ivfpq(store):
+    v = store.table("embeddings").state().version
+    for cand in sorted(_run_dir(store).glob("ivfpq.v*.npz"), reverse=True):
+        if int(cand.stem.split(".v")[-1]) == v:
+            return np.load(cand)
+    return None
+
+
+def search_ivfpq(store, q: np.ndarray, k: int, nprobe: int = 8,
+                 rerank: int = 4, mask: np.ndarray | None = None):
+    """ADC scan: distance ≈ coarse-center dot + sum of per-subspace code
+    dots (table lookups, no vector reads), then exact rerank of the top
+    `rerank*k` shortlist. Approximation shortlists; it never answers."""
+    art = load_ivfpq(store)
+    if art is None:
+        return None
+    t, vecs = _emb(store)
+    centers, labels = art["centers"], art["labels"]
+    codebooks, codes = art["codebooks"], art["codes"]
+    m, ksub, sub = codebooks.shape
+    probe = np.argsort(centers @ q)[::-1][:nprobe]
+    cand = np.isin(labels, probe)
+    if mask is not None:
+        cand &= mask
+    idx = np.where(cand)[0]
+    if len(idx) == 0:
+        return [], {"scanned": 0, "total": len(vecs)}
+    # lookup tables: q-subvector · every codeword, per subspace
+    lut = np.stack([codebooks[j] @ q[j * sub:(j + 1) * sub]
+                    for j in range(m)])                      # [m, ksub]
+    approx = centers[labels[idx]] @ q + \
+        lut[np.arange(m)[None, :], codes[idx]].sum(axis=1)
+    short = idx[np.argsort(approx)[::-1][:max(k * rerank, k)]]
+    exact = vecs[short] @ q
+    order = np.argsort(exact)[::-1][:k]
+    return ([(int(short[i]), float(exact[i])) for i in order],
+            {"scanned": int(len(idx)), "total": len(vecs),
+             "code_bytes": int(len(idx) * m),
+             "reranked": int(len(short))})

python/elidedb/answer.py

@@ -0,0 +1,338 @@
+"""ANSWER: the join of scene, agent, participants and events. No text.
+
+The user's definition, verbatim: "answer is just a join... everything is
+just logical." So this module contains no text tower, no fitted weight,
+no learned combiner - only the element tables and three logical
+operations:
+
+    AND   min over percentile ranks (scale-free conjunction)
+    OR    max over a candidate episode's objects
+    BIND  the AND is evaluated PER CANDIDATE OBJECT - "an object that
+          looks like X and moves like X" must be satisfied by one
+          object, not by one object that looks right and a different
+          one that moves right. This binding is the entire difference
+          between a join and a channel soup, and it is what "object1
+          (and similar) undergoing action1 (and similar)" means.
+
+Percentile ranks, not raw cosines, because the terms live on different
+scales (DINOv3 identity cosine, path-delta cosine, V-JEPA cosine) and a
+min over raw scales lets the tightest-distributed term govern
+everything. Rank-normalising is order statistics, not a weight.
+
+Element terms per query participant, each one a table:
+
+    looks   object_vectors   DINOv3 track descriptor cosine
+    moves   trajectories     signed, speed-normalised (dx,dy,dz) path
+                             deltas resampled to N steps - direction
+                             survives, which is the thing text erases
+    acts    vjepa_part       physics tubelet cosine, where both sides
+                             have one
+
+Episode-level terms:
+
+    scene   scene_vectors    pooled window cosine, one more rank in the
+                             conjunction
+    events  kind overlap     a PARTITION, not a score: episodes sharing
+                             at least one event kind with the query rank
+                             ahead of episodes sharing none. Logical
+                             precedence, no number invented.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+_C = {}
+
+NPATH = 16          # path resample steps; 15 deltas x 3 dims
+
+
+def _ranks(x):
+    """Percentile rank in [0,1] per entry; NaN stays NaN (missing)."""
+    x = np.asarray(x, np.float64)
+    out = np.full(len(x), np.nan)
+    ok = np.isfinite(x)
+    if ok.sum() > 1:
+        r = x[ok].argsort().argsort()
+        out[ok] = r / (ok.sum() - 1)
+    elif ok.sum() == 1:
+        out[ok] = 1.0
+    return out
+
+
+def _path_desc(ts, px, py, pz, diag):
+    """Signed, speed-normalised path deltas. Translation-invariant by
+    construction (deltas), scale-normalised by the object's own box
+    diagonal, direction preserved (open vs close differ by SIGN, the
+    one thing appearance embeddings collapse - cos 0.957 measured)."""
+    if len(ts) < 3:
+        return None
+    o = np.argsort(ts)
+    t = np.linspace(0, len(o) - 1, NPATH).round().astype(int)
+    x, y, z = (np.asarray(v, np.float64)[o][t] for v in (px, py, pz))
+    d = np.stack([np.diff(x) / max(diag, 1.0),
+                  np.diff(y) / max(diag, 1.0),
+                  np.diff(z) * 4.0], 1).ravel()
+    n = np.linalg.norm(d)
+    return (d / n).astype(np.float32) if n > 1e-6 else None
+
+
+def _elements(store):
+    """Every element table, loaded once per store version, joined on
+    the track key (stream, track_ts, t1, object_id)."""
+    ver = store.table("trajectories").state().version
+    key = (str(store.dir), ver)
+    if key in _C:
+        return _C[key]
+    E = {}
+    tr = store.table("trajectories").scan().to_pydict()
+    by = {}
+    for i in range(len(tr["ts"])):
+        k = (str(tr["stream"][i]), int(tr["track_ts"][i]),
+             int(tr["t1"][i]), int(tr["object_id"][i]))
+        by.setdefault(k, []).append(i)
+    paths, agents = {}, {}
+    for k, idx in by.items():
+        bx = [(tr["x1"][i] - tr["x0"][i], tr["y1"][i] - tr["y0"][i])
+              for i in idx]
+        diag = float(np.median([np.hypot(w, h) for w, h in bx]))
+        d = _path_desc([tr["ts"][i] for i in idx],
+                       [tr["px"][i] for i in idx],
+                       [tr["py"][i] for i in idx],
+                       [tr["pz"][i] for i in idx], diag)
+        if d is not None:
+            paths[k] = d
+        if any(tr["is_agent"][i] for i in idx):
+            agents[k] = True
+    E["paths"] = paths
+
+    # key -> ROW index; double-detection twins share a key, so the
+    # dict is smaller than the table and the reshape must use the ROW
+    # count - keying by len(dict) sheared the matrix off by 2,086 rows
+    ov = store.table("object_vectors").scan().to_pydict()
+    E["obj"] = {(str(s), int(a), int(b), int(o)): i for i, (s, a, b, o)
+                in enumerate(zip(ov["stream"], ov["ts"], ov["t1"],
+                                 ov["object_id"]))}
+    V = np.asarray(ov["vector"], np.float32).reshape(len(ov["ts"]), -1)
+    E["objV"] = V / np.maximum(
+        np.linalg.norm(V, axis=1, keepdims=True), 1e-8)
+
+    vp = store.table("vjepa_part_vectors").scan().to_pydict()
+    E["phys"] = {(str(s), int(a), int(b), int(o)): i for i, (s, a, b, o)
+                 in enumerate(zip(vp["stream"], vp["ts"], vp["t1"],
+                                  vp["object_id"]))}
+    Vp = np.asarray(vp["vector"], np.float32).reshape(len(vp["ts"]), -1)
+    E["physV"] = Vp / np.maximum(
+        np.linalg.norm(Vp, axis=1, keepdims=True), 1e-8)
+
+    sc = store.table("scene_vectors").scan().to_pydict()
+    E["scene"] = (sc["stream"], np.asarray(sc["ts"], np.int64),
+                  np.asarray(sc["vector"], np.float32)
+                  .reshape(len(sc["ts"]), -1))
+
+    ev = store.table("events").scan().to_pydict()
+    E["events"] = ev
+    E["agents"] = agents
+
+    # EVENT-LEVEL join arrays: each event row -> its motion vector, its
+    # bound object's DINOv3 descriptor row, its physics row, its
+    # episode. The image-plane path descriptor above measured 0.08
+    # yield on the direction queries - 2D geometry does not survive a
+    # camera change, and the supports span four cameras. The per-event
+    # delta-appearance vector does (it is appearance change, not
+    # coordinates), so it is the join's moves-term; geometry remains
+    # the fallback where a window has no bound events.
+    mv = store.table("motion_vectors").scan().to_pydict()
+    mrow = {(str(s), int(a), int(b)): i for i, (s, a, b) in
+            enumerate(zip(mv["stream"], mv["ts"], mv["t1"]))}
+    MV = np.asarray(mv["vector"], np.float32).reshape(len(mv["ts"]), -1)
+    MV /= np.maximum(np.linalg.norm(MV, axis=1, keepdims=True), 1e-8)
+    tracks_of = {}
+    for k in paths:
+        tracks_of.setdefault((k[0], k[3]), []).append(k)
+    n_ev = len(ev["ts"])
+    e_m = np.full(n_ev, -1)
+    e_obj = np.full(n_ev, -1)
+    e_phys = np.full(n_ev, -1)
+    for i in range(n_ev):
+        s, a, b = str(ev["stream"][i]), int(ev["ts"][i]), int(ev["t1"][i])
+        e_m[i] = mrow.get((s, a, b), -1)
+        oid = int(ev["object_id"][i])
+        if oid >= 0:
+            for k in tracks_of.get((s, oid), ()):
+                if k[1] <= b and a <= k[2]:
+                    e_obj[i] = E["obj"].get(k, -1)
+                    e_phys[i] = E["phys"].get(k, -1)
+                    break
+        # THE AGENT HAS NO LOOKS-TERM. Its identity is the ROLE - the
+        # self-moving thing - not an appearance. Measured: agent-track
+        # descriptors cosine 0.477 median against each other, barely
+        # above random non-agent pairs at 0.437, because an articulated
+        # arm deforms; only 0.2% of same-arm pairs clear the identity
+        # cut, which is where 1,517 ids for ~4 arms came from. No
+        # threshold merges what does not separate, so an agent event
+        # matches by moves and physics alone, and its appearance rank -
+        # noise by measurement - never enters the conjunction.
+        if (ev["role"][i] == "agent"
+                or (oid >= 0 and oid == int(ev["agent_object_id"][i]))):
+            e_obj[i] = -1
+    E["e_m"], E["e_obj"], E["e_phys"], E["MV"] = e_m, e_obj, e_phys, MV
+
+    ep = store.table("episodes").scan().to_pydict()
+    E["episodes"] = [(str(s), int(a), int(b)) for s, a, b in
+                     zip(ep["stream"], ep["ts"], ep["t1"])]
+    if len(_C) > 4:
+        _C.clear()
+    _C[key] = E
+    return E
+
+
+def _tracks_in(E, stream, t0, t1):
+    return [k for k in E["paths"]
+            if k[0] == stream and k[1] <= t1 and t0 <= k[2]]
+
+
+def _scene_vec(E, stream, t0, t1):
+    ss, ts, V = E["scene"]
+    m = np.array([s == stream and t0 <= t <= t1
+                  for s, t in zip(ss, ts)])
+    if not m.any():
+        return None
+    v = V[m].mean(0)
+    return v / (np.linalg.norm(v) + 1e-8)
+
+
+def answer_like(store, stream, t0, t1):
+    """Episodes telling the same story as the query window.
+
+    Returns (keys, score, shared_kind) - score is the conjunction rank
+    (higher = better), shared_kind marks the event-kind partition.
+    """
+    E = _elements(store)
+    eps = E["episodes"]
+    n = len(eps)
+
+    # ---- the query's elements -----------------------------------
+    q_tracks = _tracks_in(E, stream, t0, t1)
+    ev = E["events"]
+    q_kinds = {ev["kind"][i] for i in range(len(ev["ts"]))
+               if str(ev["stream"][i]) == stream
+               and int(ev["ts"][i]) >= t0 and int(ev["t1"][i]) <= t1
+               and ev["kind"][i]}
+    ep_of = {}
+    for i, (s, a, b) in enumerate(eps):
+        ep_of.setdefault(s, []).append((a, b, i))
+
+    # events of the query window, and each event's episode index
+    q_ev = [i for i in range(len(ev["ts"]))
+            if str(ev["stream"][i]) == stream
+            and int(ev["ts"][i]) >= t0 and int(ev["t1"][i]) <= t1]
+    n_ev = len(ev["ts"])
+    ev_ep = np.full(n_ev, -1)
+    for i in range(n_ev):
+        s, a = str(ev["stream"][i]), int(ev["ts"][i])
+        for ea, eb, j in ep_of.get(s, ()):
+            if a >= ea and a <= eb:
+                ev_ep[i] = j
+                break
+
+    # ---- EVENT-LEVEL join (primary) -----------------------------
+    # "the same transition happening to the same kind of thing": per
+    # query event, every candidate event is scored on moves (delta-
+    # appearance of the transition - the view-tolerant motion term;
+    # image-plane geometry measured 0.08 on the direction queries
+    # because the supports span four cameras) AND looks (DINOv3 of the
+    # object each event BINDS to) AND acts (its physics tubelet). One
+    # candidate event must satisfy all of it - that is the join.
+    # conjunction granularity is the KIND, not the event instance: a
+    # window holding five t3 relocations and one t7 asks for "t3-like
+    # AND t7-like", not six independent demands. OR (max) within a
+    # kind's query events, AND (min) across kinds - the story's clauses
+    # are its distinct transitions.
+    q_bound = [i for i in q_ev if E["e_m"][i] >= 0]
+    by_kind = {}
+    for qi in q_bound:
+        by_kind.setdefault(ev["kind"][qi] or "", []).append(qi)
+    per_kind = []
+    for kind, members in by_kind.items():
+        rows = []
+        for qi in members:
+            terms = []
+            terms.append(_ranks(E["MV"] @ E["MV"][E["e_m"][qi]]))
+            if E["e_obj"][qi] >= 0:
+                qv = E["objV"][E["e_obj"][qi]]
+                sims = np.full(n_ev, np.nan)
+                has = E["e_obj"] >= 0
+                sims[has] = E["objV"][E["e_obj"][has]] @ qv
+                terms.append(_ranks(sims))
+            if E["e_phys"][qi] >= 0:
+                qv = E["physV"][E["e_phys"][qi]]
+                sims = np.full(n_ev, np.nan)
+                has = E["e_phys"] >= 0
+                sims[has] = E["physV"][E["e_phys"][has]] @ qv
+                terms.append(_ranks(sims))
+            with np.errstate(invalid="ignore"):
+                bound = np.nanmin(np.stack(terms), 0)
+            row = np.full(n, np.nan)
+            for i in range(n_ev):
+                e = ev_ep[i]
+                if e >= 0 and np.isfinite(bound[i]):
+                    row[e] = bound[i] if np.isnan(row[e]) \
+                        else max(row[e], bound[i])
+            rows.append(row)
+        with np.errstate(invalid="ignore"):
+            per_kind.append(np.nanmax(np.stack(rows), 0))
+
+    if per_kind:
+        with np.errstate(invalid="ignore"):
+            score = np.nanmin(np.stack(per_kind), 0)  # AND across kinds
+        score = np.where(np.isnan(score), 0.0, score)
+    else:
+        # ---- track-path fallback: a window with no bound events ----
+        all_keys = list(E["paths"].keys())
+        P = np.stack([E["paths"][k] for k in all_keys])
+        track_ep = np.full(len(all_keys), -1)
+        for i, k in enumerate(all_keys):
+            for a, b, j in ep_of.get(k[0], ()):
+                if k[1] >= a and k[1] <= b:
+                    track_ep[i] = j
+                    break
+        q_parts = [k for k in q_tracks if E["agents"].get(k)] or q_tracks
+        if not q_parts:
+            return eps, np.zeros(n, np.float32), np.zeros(n, bool)
+        per = []
+        for qk in q_parts:
+            bound = _ranks(P @ E["paths"][qk])
+            row = np.full(n, np.nan)
+            for i, e in enumerate(track_ep):
+                if e >= 0 and np.isfinite(bound[i]):
+                    row[e] = bound[i] if np.isnan(row[e]) \
+                        else max(row[e], bound[i])
+            per.append(row)
+        with np.errstate(invalid="ignore"):
+            score = np.nanmin(np.stack(per), 0)
+        score = np.where(np.isnan(score), 0.0, score)
+
+    qs = _scene_vec(E, stream, t0, t1)
+    if qs is not None:
+        ssims = np.full(n, np.nan)
+        for i, (s, a, b) in enumerate(eps):
+            v = _scene_vec(E, s, a, b)
+            if v is not None:
+                ssims[i] = float(v @ qs)
+        sr = _ranks(ssims)
+        with np.errstate(invalid="ignore"):
+            score = np.fmin(score, np.where(np.isnan(sr), score, sr))
+
+    # ---- event-kind PARTITION -----------------------------------
+    shared = np.zeros(n, bool)
+    if q_kinds:
+        for i in range(len(ev["ts"])):
+            k = ev["kind"][i]
+            if k and k in q_kinds:
+                s = str(ev["stream"][i])
+                a = int(ev["ts"][i])
+                for ea, eb, j in ep_of.get(s, ()):
+                    if a >= ea and a <= eb:
+                        shared[j] = True
+                        break
+    return eps, score.astype(np.float32), shared

python/elidedb/bptree.py

@@ -0,0 +1,123 @@
+"""BPT1 — immutable, bulk-loaded B+ tree (numpy twin of the C++20 reader in
+src/streetdex/index/bptree.{hpp,cpp}; identical bytes on disk).
+
+Why a B+ tree here at all: zone maps prune brilliantly on `ts` because files
+are time-sorted, and prune *nothing* on an unsorted column (every row group
+spans nearly the whole domain). A secondary index re-sorts (key → location)
+once, so point/range predicates on ANY numeric column become a descent plus
+a contiguous leaf scan instead of a full-table read. Immutability makes the
+classic hard parts vanish: bulk load at 100% fill, no splits, no
+rebalancing, rebuilt per table version like every other derived artifact.
+
+Values are opaque u64s; the store packs (file_idx << 40) | row_in_file, so a
+leaf hit maps straight to one Parquet row group — the index prunes I/O, not
+just rows.
+"""
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+import numpy as np
+
+MAGIC = b"BPT1"
+DEFAULT_ORDER = 256  # 256 × 8B keys = one 4 KiB page per node touch
+
+
+def encode_key(values: np.ndarray) -> np.ndarray:
+    """Order-preserving i64 encoding: ints pass through; IEEE-754 doubles use
+    the sign-flip trick (identical to bpt_encode_f64 in C++)."""
+    if np.issubdtype(values.dtype, np.integer):
+        return values.astype("<i8")
+    if np.issubdtype(values.dtype, np.floating):
+        u = values.astype("<f8").view("<u8").copy()
+        neg = (u & 0x8000000000000000) != 0
+        u[neg] = ~u[neg]
+        u[~neg] |= 0x8000000000000000
+        return (u ^ 0x8000000000000000).view("<i8")
+    raise TypeError(f"unindexable dtype {values.dtype}")
+
+
+def encode_scalar(v) -> int:
+    return int(encode_key(np.array([v]))[0])
+
+
+def build(keys: np.ndarray, values: np.ndarray,
+          order: int = DEFAULT_ORDER) -> bytes:
+    order_idx = np.argsort(keys, kind="stable")
+    k = np.ascontiguousarray(keys[order_idx], dtype="<i8")
+    v = np.ascontiguousarray(values[order_idx], dtype="<u8")
+    n = len(k)
+
+    levels = []  # bottom-up internal levels: first key of each child node
+    below = k
+    while len(below) > order:
+        firsts = below[::order].copy()
+        levels.append(firsts)
+        below = firsts
+    levels.reverse()  # root first, as the C++ builder writes them
+
+    out = bytearray()
+    out += MAGIC
+    out += struct.pack("<IQII", order, n, len(levels), 0)
+    dir_pos = len(out)
+    out += b"\0" * (16 * (len(levels) + 1))
+    directory = []
+    for lv in levels:
+        while len(out) % 8:
+            out += b"\0"
+        directory.append((len(out), len(lv)))
+        out += lv.astype("<i8").tobytes()
+    while len(out) % 8:
+        out += b"\0"
+    directory.append((len(out), n))
+    leaf = np.empty(n, dtype=[("k", "<i8"), ("v", "<u8")])
+    leaf["k"] = k
+    leaf["v"] = v
+    out += leaf.tobytes()
+    for i, (off, cnt) in enumerate(directory):
+        struct.pack_into("<QQ", out, dir_pos + 16 * i, off, cnt)
+    return bytes(out)
+
+
+class Reader:
+    def __init__(self, data: bytes | np.memmap):
+        buf = np.frombuffer(data, dtype=np.uint8) if isinstance(data, bytes) \
+            else data
+        if bytes(buf[:4]) != MAGIC:
+            raise ValueError("not a BPT1 index")
+        self.order, self.n, nlevels, _ = struct.unpack_from(
+            "<IQII", buf.tobytes()[:24] if isinstance(buf, np.memmap)
+            else data, 4)
+        raw = buf.tobytes() if isinstance(buf, np.memmap) else data
+        dirs = [struct.unpack_from("<QQ", raw, 24 + 16 * i)
+                for i in range(nlevels + 1)]
+        self.levels = [np.frombuffer(raw, "<i8", cnt, off)
+                       for off, cnt in dirs[:-1]]
+        loff, lcnt = dirs[-1]
+        leaf = np.frombuffer(raw, dtype=[("k", "<i8"), ("v", "<u8")],
+                             count=lcnt, offset=loff)
+        self.keys = leaf["k"]
+        self.vals = leaf["v"]
+
+    @classmethod
+    def open(cls, path: str | Path):
+        return cls(np.memmap(path, dtype=np.uint8, mode="r"))
+
+    def lower_bound(self, k: int) -> int:
+        node = 0
+        for lv in self.levels:
+            begin = node * self.order
+            end = min(begin + self.order, len(lv))
+            # lower_bound + step-back (see C++ twin): duplicates of k may
+            # start in the child before the first child whose first-key == k
+            pos = int(np.searchsorted(lv[begin:end], k, side="left")) + begin
+            node = pos - 1 if pos > begin else begin
+        begin = node * self.order
+        end = min(begin + self.order, self.n)
+        return int(np.searchsorted(self.keys[begin:end], k, side="left")) + begin
+
+    def range(self, lo: int, hi: int) -> np.ndarray:
+        a = self.lower_bound(lo)
+        b = int(np.searchsorted(self.keys, hi, side="right"))
+        return self.vals[a:b]

python/elidedb/chanbench.py

@@ -0,0 +1,221 @@
+"""How to judge a channel — teacher or student, same yardstick.
+
+Params and ms/clip say nothing about whether a representation works.
+Neither does agreement with the teacher: the V-JEPA2 run made that
+concrete, where the teacher's own clips sat at 0.977 mean cosine to
+their centroid, so a student agreeing with it perfectly would inherit a
+representation that cannot rank anything. Fidelity to a broken teacher
+is a broken student with extra steps.
+
+Three layers, and a channel has to pass them IN ORDER. Each one is a
+different question, and a failure at any level makes the levels below
+it unreadable.
+
+  1 SEPARABILITY   does the representation distinguish anything at all?
+                   mean pairwise cosine and effective rank. Catches the
+                   collapse that both FDNN-V (0.978) and mean-pooled
+                   V-JEPA2 (0.977) were hiding behind respectable
+                   cosine numbers. Costs nothing, run it FIRST, on the
+                   teacher, before training any student against it.
+
+  2 TASK AUC       is it the RIGHT signal? A linear probe over labels
+                   the WRITE PATH already produced - event kinds from
+                   geometry, object ids from the identity store - so
+                   this measures usefulness without ever touching the
+                   truthset. That matters: the truthset is eval-only,
+                   and a per-iteration metric that reads it would make
+                   every later evaluation meaningless.
+
+  3 FIDELITY       does the student rank like the teacher? Only worth
+                   asking once 1 and 2 say the teacher is worth
+                   matching.
+
+THE SHIPPING GATE is layer 2, not layer 3: a student ships when its task
+AUC is within tolerance of its teacher's, at a fraction of the cost. A
+student can legitimately disagree with its teacher clip-by-clip and
+still be as useful, and that is a pass, not a failure.
+
+The product metric - yield and precision on the truthset at
+k = ceil(1.5 x support) - stays the integration test, run once channels
+are assembled. It is too coarse and too slow to steer a per-channel
+loop, and it is the thing these layers exist to protect.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def _l2(x):
+    return x / (np.linalg.norm(x, axis=-1, keepdims=True) + 1e-8)
+
+
+def separability(V, sample=2000):
+    """Layer 1. Does the space have room to rank anything?
+
+    effective_rank is the participation ratio of the covariance
+    eigenvalues - how many dimensions the data actually uses. A 1024-d
+    embedding with an effective rank of 3 is a 3-d embedding that costs
+    1024 floats to store and cannot support a nearest-neighbour query.
+    """
+    V = _l2(np.asarray(V, np.float32))
+    n = min(len(V), sample)
+    S = V[:n] @ V[:n].T
+    iu = np.triu_indices(n, 1)
+    mu = _l2(V.mean(0))
+    ev = np.linalg.eigvalsh(np.cov(V[:n].T))[::-1]
+    ev = np.clip(ev, 0, None)
+    p = ev / (ev.sum() + 1e-12)
+    eff = float(np.exp(-(p * np.log(p + 1e-12)).sum()))
+    return {"mean_pairwise_cos": round(float(S[iu].mean()), 4),
+            "p95_pairwise_cos": round(float(np.percentile(S[iu], 95)), 4),
+            "mean_baseline": round(float(np.mean(V @ mu)), 4),
+            "effective_rank": round(eff, 1),
+            "dims": int(V.shape[1])}
+
+
+def probe_auc(V, y, folds=5, seed=0):
+    """Layer 2. Linear-probe AUC for one binary label.
+
+    A LINEAR probe on purpose: it asks whether the information is
+    present and readable, not whether a big enough head can dig it out.
+    That is the property a retrieval channel needs, because the thing
+    consuming it downstream is a dot product.
+    """
+    from sklearn.linear_model import LogisticRegression
+    from sklearn.metrics import roc_auc_score
+    V, y = _l2(np.asarray(V, np.float32)), np.asarray(y).astype(int)
+    if y.sum() < folds or (1 - y).sum() < folds:
+        return None                      # too few of one class to score
+    rng = np.random.default_rng(seed)
+    idx = rng.permutation(len(V))
+    V, y = V[idx], y[idx]
+    out = []
+    for f in range(folds):
+        te = np.zeros(len(V), bool)
+        te[f::folds] = True
+        if y[~te].sum() == 0 or y[~te].sum() == (~te).sum():
+            continue
+        if len(set(y[te])) < 2:
+            continue
+        m = LogisticRegression(max_iter=2000, C=1.0)
+        m.fit(V[~te], y[~te])
+        out.append(roc_auc_score(y[te], m.decision_function(V[te])))
+    return round(float(np.mean(out)), 4) if out else None
+
+
+def retrieval_map(V, groups):
+    """Layer 2, the ranking form. Mean average precision when the query
+    is a clip and the relevant set is everything sharing its group.
+
+    AUC says the information is linearly readable; mAP says it survives
+    being turned into a ranking, which is what the channel is for.
+    """
+    V = _l2(np.asarray(V, np.float32))
+    g = np.asarray(groups)
+    S = V @ V.T
+    np.fill_diagonal(S, -9)
+    aps = []
+    for i in range(len(V)):
+        rel = (g == g[i])
+        rel[i] = False
+        if not rel.any():
+            continue
+        order = np.argsort(-S[i])
+        hit = rel[order]
+        cum = np.cumsum(hit)
+        prec = cum / (np.arange(len(hit)) + 1)
+        aps.append(float((prec * hit).sum() / hit.sum()))
+    return round(float(np.mean(aps)), 4) if aps else None
+
+
+def fidelity(P, Y, k=10):
+    """Layer 3. Does the student rank like the teacher?"""
+    P, Y = _l2(np.asarray(P, np.float32)), _l2(np.asarray(Y, np.float32))
+    n = min(len(P), 400)
+    Sp, St = P[:n] @ P[:n].T, Y[:n] @ Y[:n].T
+    np.fill_diagonal(Sp, -9); np.fill_diagonal(St, -9)
+    kk = min(k, n - 1)
+    rp, rt = np.argsort(-Sp, 1)[:, :kk], np.argsort(-St, 1)[:, :kk]
+    return {"cosine_to_teacher": round(float(np.mean(np.sum(P * Y, 1))), 4),
+            "nn_top1": round(float(np.mean(Sp.argmax(1) == St.argmax(1))), 4),
+            f"nn_recall@{kk}": round(float(np.mean(
+                [len(set(a) & set(b)) / kk for a, b in zip(rp, rt)])), 4)}
+
+
+def code_agreement(student, teacher, C, min_frac=0.05):
+    """Layer 3b: does the student land in the TEACHER'S codebook cell?
+
+    This metric exists because of how this store prunes. `code` is a
+    clustered column and the planner reads only the row groups a query's
+    probe selects, so a student that produces a beautiful vector in the
+    WRONG cell puts its row in a row group the planner never opens. The
+    row is then unreachable at any k. Cosine cannot see that failure and
+    neither can nn_recall.
+
+    Two numbers, and the second is the one that decides:
+
+      code@1        student cell == teacher cell. Informative, but a
+                    miss here is survivable - probe() widens.
+      code_recall   the teacher's cell is INSIDE the probe set the
+                    student's own vector selects. A miss here is
+                    permanent data loss: nothing the reader does at
+                    query time recovers that row.
+
+    A student at code@1 0.70 with code_recall 0.99 ships. One at code@1
+    0.95 with code_recall 0.95 silently loses 5% of the corpus.
+    """
+    from .teacher import assign, probe as _probe
+    C = np.asarray(C, np.float32)
+    ts_code, _ = assign(np.asarray(teacher, np.float32), C)
+    st_code, _ = assign(np.asarray(student, np.float32), C)
+    top1 = float(np.mean(st_code == ts_code))
+    hit, widths = 0, []
+    for i, v in enumerate(_l2(np.asarray(student, np.float32))):
+        cells = _probe(v, C, min_frac=min_frac)
+        widths.append(len(cells))
+        if int(ts_code[i]) in cells:
+            hit += 1
+    return {"code@1": round(top1, 4),
+            "code_recall": round(hit / max(len(student), 1), 4),
+            "mean_probe_cells": round(float(np.mean(widths)), 2),
+            "cells": int(len(C))}
+
+
+def report(V, labels=None, groups=None, teacher=None, codebook=None):
+    """One channel, all three layers. `labels` is {name: bool array}."""
+    out = {"separability": separability(V)}
+    if labels:
+        out["task_auc"] = {k: probe_auc(V, y) for k, y in labels.items()}
+        vals = [v for v in out["task_auc"].values() if v is not None]
+        out["task_auc_mean"] = round(float(np.mean(vals)), 4) if vals else None
+    if groups is not None:
+        out["retrieval_map"] = retrieval_map(V, groups)
+    if teacher is not None:
+        out["fidelity"] = fidelity(V, teacher)
+        if codebook is not None:
+            out["code"] = code_agreement(V, teacher, codebook)
+    return out
+
+
+def verdict(student, teacher, tol=0.03, code_recall_min=0.98):
+    """The shipping gate: task AUC within `tol` of the teacher's.
+
+    Deliberately NOT fidelity. A student that disagrees with its teacher
+    clip by clip while carrying the same usable signal has done its job;
+    holding it to agreement would reject it for the wrong reason.
+    """
+    s, t = student.get("task_auc_mean"), teacher.get("task_auc_mean")
+    if s is None or t is None:
+        return {"ship": False, "reason": "no task labels to score on"}
+    if t < 0.55:
+        return {"ship": False,
+                "reason": f"teacher itself is uninformative (AUC {t}) - "
+                          "fix the teacher target before distilling"}
+    cr = (student.get("code") or {}).get("code_recall")
+    if cr is not None and cr < code_recall_min:
+        return {"ship": False, "student_auc": s, "teacher_auc": t,
+                "reason": f"code_recall {cr} < {code_recall_min}: rows "
+                          "whose teacher cell falls outside the student's "
+                          "probe are unreachable at any k"}
+    return {"ship": bool(s >= t - tol), "student_auc": s, "teacher_auc": t,
+            "gap": round(s - t, 4), "tolerance": tol, "code_recall": cr}

python/elidedb/cli.py

@@ -0,0 +1,293 @@
+"""elidedb — the command line. One verb per lifecycle step:
+
+  elidedb create  lake/mydb --name "my dataset"
+  elidedb add     lake/mydb readings data.csv --ts-col time
+  elidedb video   lake/mydb cam.mp4 --stream cam0
+  elidedb ls      lake/mydb
+  elidedb embed   lake/mydb
+  elidedb search  lake/mydb "a person crossing the street"
+  elidedb sql     lake/mydb "SELECT count(*) FROM readings"
+  elidedb desk
+
+Times print as +SECONDS relative to the store's start; pass the same +N form
+back into `window`.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .store import Store
+
+
+def _rel(store, ns):
+    lo = min((d["min_ts"] for d in store.describe()
+              if d["rows"] and d["table"] != "centroids"), default=0)
+    return (ns - lo) / 1e9, lo
+
+
+def _parse_t(store, s: str) -> int:
+    if s.startswith("+"):
+        lo = min((d["min_ts"] for d in store.describe()
+                  if d["rows"] and d["table"] != "centroids"), default=0)
+        return lo + int(float(s[1:]) * 1e9)
+    return int(s)
+
+
+def cmd_create(a):
+    Store.create(a.store, a.name or a.store.rstrip("/").split("/")[-1])
+    print(f"created database at {a.store}")
+
+
+def cmd_ls(a):
+    db = Store.open(a.store)
+    print(f"{db.name}  ({db.dir})")
+    rows = db.describe()
+    if not rows:
+        print("  (empty — add data with `elidedb add` or `elidedb video`)")
+        return
+    w = max(len(r["table"]) for r in rows)
+    for r in rows:
+        span = ""
+        if r["rows"] and r["table"] != "centroids":
+            lo, base = _rel(db, r["min_ts"])
+            hi, _ = _rel(db, r["max_ts"])
+            span = f"  [+{lo:.1f} .. +{hi:.1f}]s"
+        print(f"  {r['table']:<{w}}  {r['kind']:<12} {r['rows']:>12,} rows "
+              f"{r['bytes'] / 1e6:9.1f} MB  v{r['version']}{span}")
+
+
+def cmd_add(a):
+    db = Store.open(a.store)
+    v = db.ingest_rows(a.table, a.file, ts_column=a.ts_col, ts_unit=a.ts_unit)
+    st = db.table(a.table).state()
+    print(f"{a.table}: +{st.files[-1].rows:,} rows -> version {v}")
+
+
+def cmd_video(a):
+    db = Store.open(a.store)
+    ts = None
+    if a.timestamps:
+        ts = [int(line) for line in open(a.timestamps)]
+    v = db.ingest_video(a.table, a.file, timestamps_ns=ts, stream=a.stream,
+                        transcode=a.transcode, gop_s=a.gop_s, crf=a.crf)
+    print(f"{a.table}: indexed {a.file} as stream "
+          f"'{a.stream or a.file}' -> version {v}")
+
+
+def cmd_adopt(a):
+    db = Store.open(a.store)
+    for d in db.describe():
+        if d["kind"] == "frame_index":
+            r = db.adopt_media(d["table"])
+            print(f"{d['table']}: adopted {r['adopted']} media files "
+                  f"({r['bytes'] / 1e6:.1f} MB) into {a.store}/media/")
+
+
+def cmd_vacuum(a):
+    db = Store.open(a.store)
+    r = db.vacuum(retain_versions=a.retain, dry_run=a.dry_run)
+    verb = "would free" if a.dry_run else "freed"
+    print(f"{r['files_removed']} files, {verb} {r['bytes_freed']/1e6:.1f} MB")
+
+
+def cmd_index(a):
+    db = Store.open(a.store)
+    if a.ann:
+        from . import ann
+        r = (ann.build_hnsw(db) if a.ann == "hnsw"
+             else ann.build_ivfpq(db))
+        print(f"{a.ann} index: {r['n']:,} vectors, "
+              f"{r['bytes']/1e6:.1f} MB (embeddings v{r['version']})")
+    else:
+        r = db.table(a.table).create_index(a.column)
+        print(f"B+ index on {a.table}.{a.column}: {r['keys']:,} keys, "
+              f"{r['bytes']/1e3:.0f} KB (v{r['version']})")
+
+
+def cmd_optimize(a):
+    db = Store.open(a.store)
+    for d in db.describe():
+        if a.table and d["table"] != a.table:
+            continue
+        r = db.table(d["table"]).compact()
+        if r.get("bytes_before"):
+            print(f"  {d['table']}: {r['files_before']}->{r['files_after']} files, "
+                  f"{r['bytes_before']/1e6:.1f}->{r['bytes_after']/1e6:.1f} MB "
+                  f"({r['ratio']}x)")
+
+
+def cmd_embed(a):
+    db = Store.open(a.store)
+    print(db.embed_windows(window_s=a.window_s,
+                           frames_per_window=a.frames_per_window))
+    if not a.no_cluster:
+        from .embeddings import cluster
+        print(cluster(db, min_cluster_size=a.min_cluster_size))
+
+
+def cmd_search(a):
+    db = Store.open(a.store)
+    hits, stats = db.search_text(a.text, k=a.k)
+    print(f"scanned {stats['scanned']}/{stats['total']} vectors, "
+          f"probed {stats['clusters_probed']}/{stats['clusters_total']} clusters")
+    for h in hits:
+        lo, _ = _rel(db, h["t0"])
+        hi, _ = _rel(db, h["t1"])
+        print(f"  {h['score']:.4f}  {h['stream']:<24} [+{lo:.2f} .. +{hi:.2f}]s"
+              f"   (elidedb window {a.store} +{lo:.2f} +{hi:.2f})")
+
+
+def cmd_sql(a):
+    db = Store.open(a.store)
+    df = db.sql(a.query)
+    print(df.to_string(index=False, max_rows=50))
+
+
+def cmd_window(a):
+    db = Store.open(a.store)
+    t0, t1 = _parse_t(db, a.t0), _parse_t(db, a.t1)
+    w, stats = db.window(t0, t1)
+    print(stats)
+    from .video import FrameSet
+    for name, v in w.items():
+        if isinstance(v, FrameSet):
+            print(f"  {name}: {len(v)} frames, streams {v.streams()}")
+            if a.dump:
+                from PIL import Image
+                import pathlib
+                out = pathlib.Path(a.dump)
+                out.mkdir(parents=True, exist_ok=True)
+                n = 0
+                for s in v.streams():
+                    for ts, img in v.decode(stream=s, width=a.width):
+                        lo, _ = _rel(db, ts)
+                        safe = s.replace("/", "_").replace(" ", "_")
+                        Image.fromarray(img).save(out / f"{safe}_{lo:.3f}s.jpg")
+                        n += 1
+                print(f"  wrote {n} frames to {a.dump}")
+        elif len(v):
+            print(f"  {name}: {len(v):,} rows x {len(v.column_names)} cols")
+
+
+def cmd_desk(a):
+    from . import desk
+    sys.argv = ["elidedb-desk", "--root", a.root, "--port", str(a.port)] + \
+        (["--open"] if not a.no_open else [])
+    desk.main()
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="elidedb",
+        description="ElideDB — Parquet-native, timestamp-first multimodal "
+                    "database. The best read is the read elided.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("create", help="create an empty database")
+    p.add_argument("store")
+    p.add_argument("--name")
+    p.set_defaults(f=cmd_create)
+
+    p = sub.add_parser("ls", help="list a database's tables")
+    p.add_argument("store")
+    p.set_defaults(f=cmd_ls)
+
+    p = sub.add_parser("add", help="add timestamped rows (CSV/Parquet)")
+    p.add_argument("store")
+    p.add_argument("table")
+    p.add_argument("file")
+    p.add_argument("--ts-col", default="ts",
+                   help="timestamp column name (default: ts)")
+    p.add_argument("--ts-unit", default="auto",
+                   choices=["auto", "s", "ms", "us", "ns"],
+                   help="timestamp unit (default: auto-detect)")
+    p.set_defaults(f=cmd_add)
+
+    p = sub.add_parser("video", help="index a video file (media stays put)")
+    p.add_argument("store")
+    p.add_argument("file")
+    p.add_argument("--table", default="frames")
+    p.add_argument("--stream", help="stream name (default: file stem)")
+    p.add_argument("--timestamps",
+                   help="file with one ns timestamp per frame; omitted = "
+                        "container timestamps")
+    p.add_argument("--transcode", choices=["hevc", "h264"],
+                   help="re-encode the managed copy (~10-25x smaller; "
+                        "random access becomes GOP-granular)")
+    p.add_argument("--gop-s", type=float, default=1.0,
+                   help="keyframe interval in seconds (the seekability-vs-"
+                        "compression dial)")
+    p.add_argument("--crf", type=int, default=26)
+    p.set_defaults(f=cmd_video)
+
+    p = sub.add_parser("adopt", help="copy referenced media into the store "
+                                     "(makes it standalone)")
+    p.add_argument("store")
+    p.set_defaults(f=cmd_adopt)
+
+    p = sub.add_parser("optimize", help="compact tables (fewer, larger, "
+                                        "delta-encoded files)")
+    p.add_argument("store")
+    p.add_argument("--table")
+    p.set_defaults(f=cmd_optimize)
+
+    p = sub.add_parser("vacuum", help="garbage-collect unreachable files "
+                                      "(keeps last N versions readable)")
+    p.add_argument("store")
+    p.add_argument("--retain", type=int, default=3)
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(f=cmd_vacuum)
+
+    p = sub.add_parser("index", help="build a B+ tree on a column, or an "
+                                     "ANN index (hnsw/ivfpq) on embeddings")
+    p.add_argument("store")
+    p.add_argument("--table", default="frames")
+    p.add_argument("--column", help="numeric column for a B+ secondary index")
+    p.add_argument("--ann", choices=["hnsw", "ivfpq"],
+                   help="build a vector index over the embeddings table")
+    p.set_defaults(f=cmd_index)
+
+    p = sub.add_parser("embed", help="embed video windows + cluster (local ML)")
+    p.add_argument("store")
+    p.add_argument("--window-s", type=float, default=2.0)
+    p.add_argument("--frames-per-window", type=int, default=2)
+    p.add_argument("--min-cluster-size", type=int, default=8)
+    p.add_argument("--no-cluster", action="store_true")
+    p.set_defaults(f=cmd_embed)
+
+    p = sub.add_parser("search", help="semantic text search")
+    p.add_argument("store")
+    p.add_argument("text")
+    p.add_argument("-k", type=int, default=8)
+    p.set_defaults(f=cmd_search)
+
+    p = sub.add_parser("sql", help="run SQL (DuckDB) over the database")
+    p.add_argument("store")
+    p.add_argument("query")
+    p.set_defaults(f=cmd_sql)
+
+    p = sub.add_parser("window", help="read a time window (+SECS or raw ns)")
+    p.add_argument("store")
+    p.add_argument("t0")
+    p.add_argument("t1")
+    p.add_argument("--dump", help="write frames as JPEGs to this directory")
+    p.add_argument("--width", type=int, default=640)
+    p.set_defaults(f=cmd_window)
+
+    p = sub.add_parser("desk", help="open the browser UI")
+    p.add_argument("--root", default="lake")
+    p.add_argument("--port", type=int, default=8787)
+    p.add_argument("--no-open", action="store_true")
+    p.set_defaults(f=cmd_desk)
+
+    a = ap.parse_args()
+    try:
+        a.f(a)
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

python/elidedb/context.py

@@ -0,0 +1,1112 @@
+"""Context retrieval: the ingest-side half.
+
+WHY THIS EXISTS
+---------------
+`embeddings` holds one mean-pooled SigLIP vector per window. Mean pooling is
+order-blind: reverse the frames and the vector is identical. So the index can
+answer "is there a car and a person here" but never "is the person walking
+*toward* the car" — appearance, not context. Reranking with a VLM fixes the
+ranking but costs seconds per query, which is the wrong place to spend time in
+a database.
+
+The fix is the oldest trick a database has: precompute the expensive operator
+into an index and make the query a lookup. Concretely,
+
+    ingest (once, offline)      query (every time, hot)
+    ------------------------    -----------------------
+    VLM reads 3 frames of the   text -> SigLIP text vector
+    window and writes a
+    relational caption          ONE matmul against ctx vectors
+        |
+    SigLIP text tower           (no VLM in the loop, ever)
+        |
+    target vector  -----------> train a small temporal tower to
+                                predict it from cheap frame vectors
+
+The VLM only ever labels a subset. The tower generalises the label to every
+window, including windows ingested later, so a new day of footage costs a
+forward pass over frame vectors instead of a day of VLM time. This is
+pseudo-labelling in the sense of "Distilling Vision-Language Models on
+Millions of Videos" (arXiv 2401.06129), applied at ingest instead of at
+pretraining scale.
+
+Three tables come out of this module, all ordinary Parquet:
+
+    frame_vectors     ts, stream, vector[d]              one row per FRAME
+    context_captions  ts, t1, stream, caption, vector[d] teacher labels
+    context           ts, t1, stream, vector[d]          student output
+"""
+from __future__ import annotations
+
+import re
+import time
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.compute as pc
+
+from .embeddings import (DEFAULT_MODEL, MODELS, _embed_images,
+                         _load_model, resolve_model)
+
+# The teacher is asked for RELATIONS and CHANGE, not for a list of objects.
+# An object list is exactly what SigLIP already encodes, so a caption that
+# reads "a car, a road, a building" teaches the student nothing it does not
+# already know. Everything interesting is in the verbs.
+CAPTION_PROMPT = (
+    "These frames are in time order from one short video clip. "
+    "Reply with ONE sentence of at most 25 words describing what is "
+    "happening: who or what is present, what each is doing, how they are "
+    "positioned relative to each other, and how the scene moves or changes. "
+    "Be concrete and literal. Do not say 'frame', 'image', or 'video'."
+)
+
+# The caption is the index. If it does not use the words a user would use, the
+# lexical ranker can never fire and the caption-LSA space is built around the
+# wrong distinctions. Measured on BridgeData2: the generic prompt above
+# produced "a robot arm interacts with a wooden box", while the human label
+# for the same clip was "put red object in the drawer" — different noun,
+# different granularity, no overlap for retrieval to work with.
+#
+# So the prompt is a per-domain parameter. This one asks for the ACTION and
+# the OBJECT MOVED, which is how manipulation data is described. It stays
+# deliberately generic: it never names objects that appear in the labels
+# (that would be leaking the eval set into the index), only the SHAPE of the
+# description — what moved, and where it ended up.
+# The caption IS the index: whatever verbs the prompt teaches are the only
+# verbs lexical recall can ever match. The first version of this prompt said
+# "which object the arm picks up or moves, and where it puts it" — and the
+# resulting 2,348 captions contained picks x2371, puts x1673 and ZERO
+# instances of close/open/wipe/push, so "close the drawer" was unfindable by
+# construction. The prompt must be VERB-OPEN: describe the action in its own
+# words, and always report state changes.
+# S0 VIOLATION, FIXED. The previous MANIPULATION_PROMPT enumerated the
+# task vocabulary - "picking up, putting, opening, closing, pushing,
+# pouring, wiping, pressing" - and this file's own comment stated the
+# consequence: "The caption IS the index: whatever verbs the prompt
+# teaches are the only verbs lexical recall can ever match." A verb
+# outside that list was unfindable by construction, and a non-
+# manipulation corpus was unfindable entirely.
+#
+# It was also TUNED AGAINST THE EVAL LABELS. The removed comment
+# recorded the generic prompt producing "a robot arm interacts with a
+# wooden box" where "the human label for the same clip was 'put red
+# object in the drawer'", and the prompt being rewritten to close that
+# gap. bridge_ingest.py deliberately keeps the task strings out of the
+# store; this prompt let them back in through the side door.
+#
+# The replacement names no verb, no object class and no domain. It asks
+# for what MOVED and what CHANGED, which is answerable for a kitchen, a
+# road, a warehouse or a surgical table, and lets the corpus supply its
+# own words.
+MANIPULATION_PROMPT = (
+    "These frames are in time order from one short clip. "
+    "Reply with ONE short sentence in plain English: what moved, what it "
+    "did, and what was different at the end. Use whatever words fit; do "
+    "not choose from a list. If anything changed state, say so. "
+    "Do not say 'frame', 'image', or 'video'."
+)
+
+PROMPTS = {"scene": CAPTION_PROMPT, "manipulation": MANIPULATION_PROMPT}
+
+# SigLIP's text tower truncates at 64 tokens, so a rambling caption is
+# silently cut mid-clause and the tail is lost anyway. Trim deliberately
+# instead: drop the VLM's framing preamble, keep whole sentences.
+#
+# The preamble pattern is deliberately narrow — a leading PREPOSITIONAL
+# phrase only ("In the first frame,", "Across this sequence,"). An earlier
+# looser version also matched "The video shows a street with cars," and
+# amputated the subject, leaving captions that began "and various buildings".
+# Requiring a leading preposition and at most two filler words makes that
+# impossible.
+_PREAMBLE = re.compile(
+    r"^(?:in|across|throughout|over|during)\s+(?:the|this|these)\s+"
+    r"(?:[\w-]+\s+){0,2}?(?:frames?|images?|pictures?|sequence|clip|video)\s*,\s*",
+    re.I)
+
+# Prompt-echo: asking for "the action verb in plain English" made the VLM
+# write 'The action verb is "picking up" as the arm picks up...' — meta-
+# language that pollutes the lexical index. Strip the frame, keep the deed.
+_VERB_ECHO = re.compile(
+    r"^the action(?:\s+verb)?\s+is\s+['\"]?[\w-]+(?:\s+[\w-]+){0,2}?"
+    r"['\"]?[,.]?\s+(?:as|because|where|since|:)\s+", re.I)
+
+
+def tidy_caption(text: str, max_words: int = 32) -> str:
+    t = " ".join(text.strip().split())
+    t = _PREAMBLE.sub("", t)
+    t = _VERB_ECHO.sub("", t)
+    parts = re.split(r"(?<=[.!?])\s+", t)
+    # A generation cut off at max_tokens ends mid-clause. Keep only sentences
+    # that actually terminate, unless that would leave nothing at all.
+    whole = [p for p in parts if p.rstrip().endswith((".", "!", "?"))]
+    parts = whole or parts[:1]
+    out = []
+    for p in parts:
+        if out and len(" ".join(out + [p]).split()) > max_words:
+            break
+        out.append(p)
+    t = " ".join(out).strip()
+    return (t[:1].upper() + t[1:]) if t else " ".join(text.split())[:200]
+
+
+# ---------------------------------------------------------------------------
+# 1. Per-frame vectors — the sequence a temporal model needs
+# ---------------------------------------------------------------------------
+def embed_frames(store, frame_table="frames", model=None, width=512,
+                 batch=32, incremental=True, verbose=True, stride=1,
+                 streams=None, engine="siglip"):
+    """One SigLIP vector per frame → `frame_vectors`.
+
+    Deliberately NOT pooled. Pooling is the student's job, and pooling here
+    would throw away the only signal that distinguishes context from
+    appearance. Decode goes through the same byte-range path queries use, so
+    this costs the frames it reads and nothing else.
+    """
+    from PIL import Image
+
+    from .video import FrameSet
+    # engine="fdnnv": the distilled streaming encoder — every frame, no
+    # stride, state carried per stream. Same output space as the teacher, so
+    # everything downstream (pooling, search, context) is unchanged.
+    if engine == "fdnnv":
+        return _embed_frames_fdnnv(store, frame_table, incremental, verbose,
+                                   streams)
+    model = resolve_model(model)
+    frames = store.table(frame_table).scan()
+    allst = sorted(set(frames.column("stream").to_pylist()))
+    streams = [s for s in allst if s in streams] if streams else allst
+
+    done = {}
+    if incremental:
+        try:
+            prev = store.table("frame_vectors").scan()
+            for s_, t_ in zip(prev.column("stream").to_pylist(),
+                              prev.column("ts").to_pylist()):
+                done[s_] = max(done.get(s_, -1), t_)
+        except Exception:
+            pass
+
+    t_start = time.time()
+    rows_ts, rows_stream, rows_vec = [], [], []
+    for s in streams:
+        sel = frames.filter(pc.equal(frames.column("stream"), s))
+        if s in done:
+            sel = sel.filter(pc.greater(sel.column("ts"), done[s]))
+        if len(sel) == 0:
+            continue
+        # `stride` subsamples the frame index before decoding. A 5 Hz robot
+        # camera does not need every frame embedded for a 4 s window to be
+        # well described, and the cost here is linear in frames decoded, so
+        # this is the dial between ingest time and temporal resolution.
+        decoded = FrameSet(store, frame_table, sel).decode(width=width,
+                                                           stride=stride)
+        if verbose:
+            print(f"  {s}: {len(decoded)} frames decoded", flush=True)
+        for i in range(0, len(decoded), batch):
+            chunk = decoded[i:i + batch]
+            vecs = _embed_images([Image.fromarray(a) for _, a in chunk], model)
+            for (ts, _), v in zip(chunk, vecs):
+                rows_ts.append(int(ts))
+                rows_stream.append(s)
+                rows_vec.append(v)
+    if not rows_ts:
+        return {"frames": 0, "note": "nothing new (incremental)"}
+
+    dim = len(rows_vec[0])
+    tbl = pa.table({
+        "ts": pa.array(rows_ts, pa.int64()),
+        "stream": pa.array(rows_stream),
+        "vector": pa.array([v.tolist() for v in rows_vec],
+                           pa.list_(pa.float32(), dim)),
+    })
+    version = store.table("frame_vectors").append(
+        tbl, kind="embeddings",
+        meta={"model": model, "dim": dim, "decode_width": width,
+              "source_table": frame_table})
+    return {"frames": len(tbl), "dim": dim, "version": version,
+            "seconds": round(time.time() - t_start, 1)}
+
+
+# ---------------------------------------------------------------------------
+# 2. Window plan — shared by teacher and student so labels line up exactly
+# ---------------------------------------------------------------------------
+def plan_windows(store, window_s=2.0, stride_s=0.5, table="frame_vectors",
+                 min_frames=4):
+    """Sliding windows over each stream's timeline.
+
+    Stride < window on purpose: overlapping windows are how a *sliding* index
+    avoids the boundary problem where an event straddles two tumbling windows
+    and lands strongly in neither. Merging overlaps back into one answer is
+    already handled downstream by the segment merger.
+    """
+    fv = store.table(table).scan()
+    win = int(window_s * 1e9)
+    stride = int(stride_s * 1e9)
+    out = []
+    for s in sorted(set(fv.column("stream").to_pylist())):
+        rows = fv.filter(pc.equal(fv.column("stream"), s))
+        ts = np.sort(rows.column("ts").to_numpy())
+        if len(ts) == 0:
+            continue
+        t = int(ts[0])
+        end = int(ts[-1])
+        while t <= end - win // 2:
+            lo, hi = np.searchsorted(ts, [t, t + win])
+            if hi - lo >= min_frames:
+                out.append((s, t, t + win - 1))
+            t += stride
+    return out
+
+
+def window_sequences(store, windows, table="frame_vectors", max_len=32):
+    """(stream, t0, t1) → (T, d) float32 stack of that window's frame vectors.
+
+    Subsampled to `max_len` evenly. A 2 s window at 16 Hz is 32 frames; the
+    cap keeps the tower's cost independent of frame rate, which is what makes
+    the same model valid across a 10 Hz LiDAR-synced camera and a 60 Hz one.
+    """
+    fv = store.table(table).scan()
+    by_stream = {}
+    for s in sorted(set(fv.column("stream").to_pylist())):
+        rows = fv.filter(pc.equal(fv.column("stream"), s))
+        ts = rows.column("ts").to_numpy()
+        order = np.argsort(ts)
+        vecs = np.asarray(rows.column("vector").to_pylist(), dtype=np.float32)
+        by_stream[s] = (ts[order], vecs[order])
+    seqs = []
+    for (s, t0, t1) in windows:
+        ts, vecs = by_stream[s]
+        lo, hi = np.searchsorted(ts, [t0, t1 + 1])
+        idx = np.arange(lo, hi)
+        if len(idx) > max_len:
+            idx = idx[np.linspace(0, len(idx) - 1, max_len).round().astype(int)]
+        seqs.append(vecs[idx])
+    return seqs
+
+
+# ---------------------------------------------------------------------------
+# 3. The teacher — a VLM that actually reads the pixels, run ONCE per window
+# ---------------------------------------------------------------------------
+def caption_windows(store, windows, frames_per_window=3, model_id=None,
+                    max_tokens=64, width=448, verbose=True, limit=None,
+                    every=1, prompt="scene"):
+    """VLM captions for `windows` → `context_captions` table.
+
+    The VLM is shown several frames of the SAME window in order, so the
+    caption can describe motion. A single-frame caption would be another
+    appearance label and the student would learn nothing a mean-pool cannot
+    already produce.
+    """
+    import tempfile
+    from pathlib import Path
+
+    from PIL import Image
+
+    from .rerank import DEFAULT_VLM, _load
+    from .video import FrameSet
+    model_id = model_id or DEFAULT_VLM
+    from mlx_vlm import generate
+    from mlx_vlm.prompt_utils import apply_chat_template
+
+    vlm, processor, cfg, _, _ = _load(model_id)
+    rot = store.meta.get("display", {}).get("rotate", 0)
+    frames = store.table("frames").scan()
+    tmpdir = Path(tempfile.mkdtemp(prefix="elidedb_ctx_"))
+
+    # `every` samples the window list uniformly instead of taking a prefix.
+    # On a corpus too large to caption in full this matters: a prefix would
+    # confine the caption vocabulary to whatever happens early in the
+    # timeline, so query terms for anything later would be out of vocabulary
+    # and the lexical ranker would abstain on the entire tail.
+    if every > 1:
+        windows = windows[::every]
+    if limit:
+        windows = windows[:limit]
+    text = PROMPTS.get(prompt, prompt)          # preset name or raw prompt
+    prompt = apply_chat_template(processor, cfg, text,
+                                 num_images=frames_per_window)
+
+    recs = {"ts": [], "t1": [], "stream": [], "caption": []}
+    t_start = time.time()
+    for n, (s, t0, t1) in enumerate(windows):
+        sel = frames.filter(pc.and_(
+            pc.equal(frames.column("stream"), s),
+            pc.and_(pc.greater_equal(frames.column("ts"), t0),
+                    pc.less_equal(frames.column("ts"), t1))))
+        fs = FrameSet(store, "frames", sel)
+        dec = fs.decode(width=width)
+        if len(dec) < 1:
+            continue
+        picks = np.linspace(0, len(dec) - 1,
+                            min(frames_per_window, len(dec))).round().astype(int)
+        paths = []
+        for j, p in enumerate(picks):
+            im = Image.fromarray(dec[p][1])
+            if rot:
+                im = im.rotate(rot, expand=True)
+            fp = tmpdir / f"w{n}_{j}.jpg"
+            im.save(fp, "JPEG", quality=85)
+            paths.append(str(fp))
+        while len(paths) < frames_per_window:      # pad short windows
+            paths.append(paths[-1])
+        r = generate(vlm, processor, prompt, image=paths,
+                     max_tokens=max_tokens, verbose=False)
+        cap = tidy_caption(r.text if hasattr(r, "text") else str(r))
+        recs["ts"].append(t0)
+        recs["t1"].append(t1)
+        recs["stream"].append(s)
+        recs["caption"].append(cap)
+        if verbose and n % 10 == 0:
+            el = time.time() - t_start
+            print(f"  [{n + 1}/{len(windows)}] {el:.0f}s  {s} +"
+                  f"{(t0 - int(frames.column('ts')[0].as_py())) / 1e9:.1f}s :: "
+                  f"{cap[:90]}", flush=True)
+    if not recs["ts"]:
+        return {"captions": 0}
+
+    # Caption → frozen SigLIP TEXT tower. This is the whole point of using
+    # SigLIP as the teacher's codec: the target lands in the SAME space a
+    # user's query lands in, so the student is learning to be the image side
+    # of a dual encoder — not to regress an arbitrary embedding.
+    vecs = embed_texts(recs["caption"])
+    dim = vecs.shape[1]
+    tbl = pa.table({
+        "ts": pa.array(recs["ts"], pa.int64()),
+        "t1": pa.array(recs["t1"], pa.int64()),
+        "stream": pa.array(recs["stream"]),
+        "caption": pa.array(recs["caption"]),
+        "vector": pa.array([v.tolist() for v in vecs],
+                           pa.list_(pa.float32(), dim)),
+    })
+    version = store.table("context_captions").append(
+        tbl, kind="embeddings",
+        meta={"teacher": model_id, "text_model": DEFAULT_MODEL, "dim": dim,
+              "frames_per_window": frames_per_window, "prompt": text[:200],
+              "seconds": round(time.time() - t_start, 1)})
+    return {"captions": len(tbl), "version": version,
+            "seconds": round(time.time() - t_start, 1)}
+
+
+def embed_texts(texts, model_id=DEFAULT_MODEL, batch=32):
+    """Batched SigLIP text tower. Same normalisation as image vectors so the
+    two are directly comparable by dot product. Delegates to the
+    portable single-text path when mlx is not on this machine."""
+    from .embeddings import _backend, embed_text
+    if _backend() != "mlx":
+        return np.stack([embed_text(t if t.strip() else "a scene",
+                                    model_id) for t in texts])
+    import mlx.core as mx
+    model, processor = _load_model(model_id)
+    out = []
+    for i in range(0, len(texts), batch):
+        chunk = [t if t.strip() else "a scene" for t in texts[i:i + batch]]
+        ti = processor(text=chunk, padding="max_length", max_length=64,
+                       truncation=True, return_tensors="np")
+        v = np.array(model.get_text_features(mx.array(ti["input_ids"])),
+                     dtype=np.float32)
+        out.append(v / np.linalg.norm(v, axis=1, keepdims=True))
+    return np.concatenate(out, axis=0)
+
+
+# ---------------------------------------------------------------------------
+# 4. CaptionSpace — the output space, chosen by measurement
+# ---------------------------------------------------------------------------
+# Three candidate spaces were benchmarked against a VLM judge on windows the
+# tower never trained on (mean yes/no logprob margin over each method's top-5,
+# six relational queries, higher is better):
+#
+#     appearance only  (SigLIP image-text)                +0.276
+#     caption EMBEDDING (SigLIP text tower, oracle)       +0.218   <- worse
+#     VLM rerank at query time (2.1 s/query)              +0.314
+#     caption TEXT, LSA-48                                +0.339   <- winner
+#     caption TEXT, raw TF-IDF, fused with appearance     +0.345
+#
+# The embedding route loses because SigLIP's text tower is trained to sit
+# near IMAGES, not near other text; comparing a query embedding to a caption
+# embedding uses a geometry the model was never optimised for. Matching the
+# caption as TEXT sidesteps that entirely.
+#
+# LSA-48 is chosen over raw TF-IDF despite scoring 0.006 lower: it is dense
+# and fixed-width, so (a) it is a target a small tower can actually regress,
+# which is what lets unlabelled windows get a context vector at all, and
+# (b) it is one more fixed_size_list column, so every index already in the
+# store consumes it unchanged.
+
+
+class CaptionSpace:
+    """TF-IDF + LSA over the caption corpus. Queries and captions share it.
+
+    Not persisted as a pickle. The captions themselves are the durable
+    artifact — they live in `context_captions` as ordinary Parquet — and the
+    lexical index is refit from them on load (a few ms for this corpus) and
+    cached. That keeps the index unconditionally consistent with the data and
+    free of any sklearn version pinning. At corpus sizes where refitting
+    stops being free, persist the vocabulary and the SVD basis; the interface
+    does not change.
+    """
+
+    def __init__(self, vec, svd):
+        self.vec, self.svd = vec, svd
+        self.dim = svd.n_components
+
+    @staticmethod
+    def fit(texts, dim=48):
+        from sklearn.decomposition import TruncatedSVD
+        from sklearn.feature_extraction.text import TfidfVectorizer
+        vec = TfidfVectorizer(stop_words="english", ngram_range=(1, 2),
+                              sublinear_tf=True).fit(texts)
+        X = vec.transform(texts)
+        dim = int(min(dim, X.shape[1] - 1, len(texts) - 1))
+        svd = TruncatedSVD(n_components=dim, random_state=0).fit(X)
+        return CaptionSpace(vec, svd)
+
+    def transform(self, texts):
+        v = self.svd.transform(self.vec.transform(list(texts)))
+        v = np.asarray(v, dtype=np.float32)
+        return v / (np.linalg.norm(v, axis=1, keepdims=True) + 1e-8)
+
+
+_SPACE_CACHE: dict = {}
+
+
+def caption_space(store, dim=48):
+    t = store.table("context_captions")
+    key = (str(store.dir), t.state().version, dim)
+    if key not in _SPACE_CACHE:
+        _SPACE_CACHE.clear()
+        _SPACE_CACHE[key] = CaptionSpace.fit(
+            t.scan().column("caption").to_pylist(), dim=dim)
+    return _SPACE_CACHE[key]
+
+
+# ---------------------------------------------------------------------------
+# 5. The student — train the tower, then materialise context vectors
+# ---------------------------------------------------------------------------
+def _labelled(store, windows):
+    """Join the caption table onto the window plan by (stream, ts)."""
+    caps = store.table("context_captions").scan()
+    key = {(s, t): i for i, (s, t) in enumerate(
+        zip(caps.column("stream").to_pylist(), caps.column("ts").to_pylist()))}
+    vecs = np.asarray(caps.column("vector").to_pylist(), dtype=np.float32)
+    texts = caps.column("caption").to_pylist()
+    keep, tv, tt = [], [], []
+    for w in windows:
+        i = key.get((w[0], w[1]))
+        if i is not None:
+            keep.append(w)
+            tv.append(vecs[i])
+            tt.append(texts[i])
+    return keep, np.asarray(tv, dtype=np.float32), tt
+
+
+def train_context(store, window_s=2.0, stride_s=0.5, val_frac=0.3,
+                  d_in=48, d_out=48, epochs=400, cfg=None, verbose=True,
+                  seed=0):
+    """Fit the input PCA + tower to predict caption-LSA coordinates.
+
+    The validation split is by TIME, never at random: windows slide with 75%
+    overlap, so a random split puts near-duplicate windows on both sides and
+    reports a score that measures nothing.
+    """
+    from .ctxtower import ContextCodec, retrieval_r1, save_tower, train_tower
+
+    windows = plan_windows(store, window_s, stride_s)
+    windows, _, cap_text = _labelled(store, windows)
+    if len(windows) < 16:
+        raise RuntimeError(f"only {len(windows)} captioned windows — run "
+                           "caption_windows() first")
+
+    fv = store.table("frame_vectors").scan()
+    frame_mat = np.asarray(fv.column("vector").to_pylist(), dtype=np.float32)
+    codec = ContextCodec.fit(frame_mat, d_in=d_in)
+    space = caption_space(store, dim=d_out)
+
+    seqs = [codec.encode(s) for s in window_sequences(store, windows)]
+    targets = space.transform(cap_text)
+
+    t0s = np.array([w[1] for w in windows])
+    cut = np.quantile(t0s, 1.0 - val_frac)
+    val_idx = np.where(t0s >= cut)[0]
+    if verbose:
+        print(f"  {len(windows)} labelled windows | train "
+              f"{len(windows) - len(val_idx)} | val {len(val_idx)} "
+              f"(time split at +{(cut - t0s.min()) / 1e9:.1f}s) | "
+              f"target dim {space.dim}", flush=True)
+
+    cfg = {**dict(d_in=codec.P_in.shape[0], d_out=space.dim), **(cfg or {})}
+    model, info = train_tower(seqs, targets, windows, val_idx, cfg=cfg,
+                              epochs=epochs, verbose=verbose, seed=seed)
+
+    import mlx.core as mx
+    val = np.zeros(len(seqs), bool)
+    val[val_idx] = True
+    Xva = _pad_stack([s for s, m in zip(seqs, val) if m])
+    pred = np.array(model(mx.array(Xva)))
+    pred /= np.linalg.norm(pred, axis=1, keepdims=True) + 1e-8
+    tgt_va = targets[val]
+
+    # Baseline: predict the TRAIN-set mean target for every window. That is
+    # the best a model can do while knowing nothing about the specific window,
+    # so any lift over it is genuine per-window information and not the corpus
+    # prior leaking through.
+    prior = targets[~val].mean(axis=0)
+    prior /= np.linalg.norm(prior) + 1e-8
+    prior = np.repeat(prior[None, :], len(tgt_va), axis=0)
+
+    metrics = {
+        "labelled_windows": len(windows),
+        "train": int((~val).sum()), "val": int(val.sum()),
+        "target_dim": space.dim,
+        "val_R@1_tower": retrieval_r1(pred, tgt_va),
+        "val_cos_tower": float((pred * tgt_va).sum(1).mean()),
+        "val_cos_prior": float((prior * tgt_va).sum(1).mean()),
+        "params": int(sum(v.size for v in _flat(model).values())),
+        **{k: v for k, v in info.items() if k != "history"},
+    }
+    save_tower(model, codec,
+               {"window_s": window_s, "stride_s": stride_s, "d_out": space.dim,
+                "metrics": metrics, "history": info["history"]},
+               store.dir / "models" / "context")
+    return model, codec, metrics
+
+
+def _flat(model):
+    from mlx.utils import tree_flatten
+    return {k: np.array(v) for k, v in tree_flatten(model.parameters())}
+
+
+def _pad_stack(seqs):
+    T = max(s.shape[0] for s in seqs)
+    X = np.zeros((len(seqs), T, seqs[0].shape[1]), dtype=np.float32)
+    for i, s in enumerate(seqs):
+        X[i, :len(s)] = s
+        if len(s) < T:
+            X[i, len(s):] = s[-1]
+    return X
+
+
+def build_context(store, window_s=None, stride_s=None, batch=64, verbose=True):
+    """Materialise the `context` table: one context vector per window.
+
+    Where a window has a teacher caption, its EXACT caption-LSA vector is
+    stored. Where it does not, the tower's prediction is stored and the row is
+    flagged `estimated`. This is the ordinary database distinction between a
+    materialised value and an estimated one, and it is the point of having a
+    student at all: the VLM labels what you can afford, the tower covers the
+    rest, and the query does not care which it got.
+    """
+    import time
+
+    import mlx.core as mx
+
+    from .ctxtower import load_tower
+    model, codec, meta = load_tower(store.dir / "models" / "context")
+    window_s = window_s or meta.get("window_s", 2.0)
+    stride_s = stride_s or meta.get("stride_s", 0.5)
+    space = caption_space(store, dim=meta.get("d_out", 48))
+
+    windows = plan_windows(store, window_s, stride_s)
+    raw = window_sequences(store, windows)
+    seqs = [codec.encode(s) for s in raw]
+    # The mean-pooled appearance vector for the SAME window, stored alongside.
+    # Fusing appearance with context otherwise needs a join between two tables
+    # built on different window plans; keeping both columns in one row makes
+    # the fused query two matmuls over one Parquet scan and no join at all.
+    appear = np.stack([s.mean(axis=0) for s in raw])
+    appear /= np.linalg.norm(appear, axis=1, keepdims=True) + 1e-8
+
+    t_start = time.time()
+    out = []
+    for i in range(0, len(seqs), batch):
+        out.append(np.array(model(mx.array(_pad_stack(seqs[i:i + batch])))))
+    z = np.concatenate(out, axis=0)
+    z /= np.linalg.norm(z, axis=1, keepdims=True) + 1e-8
+    infer_s = time.time() - t_start
+
+    caps = store.table("context_captions").scan()
+    known = {(a, b): c for a, b, c in zip(caps.column("stream").to_pylist(),
+                                          caps.column("ts").to_pylist(),
+                                          caps.column("caption").to_pylist())}
+    have = [(i, known[(w[0], w[1])]) for i, w in enumerate(windows)
+            if (w[0], w[1]) in known]
+    estimated = np.ones(len(windows), bool)
+    if have:
+        exact = space.transform([c for _, c in have])
+        for (i, _), v in zip(have, exact):
+            z[i] = v
+            estimated[i] = False
+
+    dim, adim = z.shape[1], appear.shape[1]
+    tbl = pa.table({
+        "ts": pa.array([w[1] for w in windows], pa.int64()),
+        "t1": pa.array([w[2] for w in windows], pa.int64()),
+        "stream": pa.array([w[0] for w in windows]),
+        "vector": pa.array([v.tolist() for v in z],
+                           pa.list_(pa.float32(), dim)),
+        "appearance": pa.array([v.tolist() for v in appear],
+                               pa.list_(pa.float32(), adim)),
+        "estimated": pa.array(estimated.tolist(), pa.bool_()),
+    })
+    st = store.table("context").state()
+    meta_out = {"dim": dim, "window_s": window_s, "stride_s": stride_s,
+                "estimated_rows": int(estimated.sum()),
+                "exact_rows": int((~estimated).sum())}
+    if st.files:                                 # replace: one atomic commit
+        import uuid as _uuid
+
+        from .log import FileEntry
+        from .store import write_parquet
+        fname = f"part-{_uuid.uuid4().hex[:12]}.parquet"
+        p = store.dir / "tables" / "context" / fname
+        tbl = tbl.take(pc.sort_indices(tbl.column("ts")))
+        write_parquet(tbl, p)
+        tsv = tbl.column("ts").to_numpy()
+        version = store.table("context").log.commit(
+            op="replace", kind="embeddings", schema=str(tbl.schema),
+            add=[FileEntry(fname, len(tbl), p.stat().st_size,
+                           int(tsv.min()), int(tsv.max()))],
+            remove=[f.path for f in st.files], meta=meta_out)
+    else:
+        version = store.table("context").append(tbl, kind="embeddings",
+                                                meta=meta_out)
+    if verbose:
+        print(f"  {len(tbl)} context vectors ({int((~estimated).sum())} exact, "
+              f"{int(estimated.sum())} estimated) | tower inference "
+              f"{infer_s * 1000:.0f} ms "
+              f"({infer_s / len(tbl) * 1e6:.0f} us/window)")
+    return {"windows": len(tbl), "dim": dim, "version": version,
+            "inference_s": round(infer_s, 3),
+            "us_per_window": round(infer_s / len(tbl) * 1e6, 1), **meta_out}
+
+
+# ---------------------------------------------------------------------------
+# 6. Post-training cellular turnover — capacity the data cannot support is
+#    both latency and overfitting, so apoptosis pays twice.
+# ---------------------------------------------------------------------------
+def _prepare(store, window_s, stride_s, codec, val_frac, d_out):
+    windows, _, texts = _labelled(store, plan_windows(store, window_s,
+                                                      stride_s))
+    seqs = [codec.encode(s) for s in window_sequences(store, windows)]
+    targets = caption_space(store, dim=d_out).transform(texts)
+    t0s = np.array([w[1] for w in windows])
+    val = t0s >= np.quantile(t0s, 1.0 - val_frac)
+    return windows, seqs, targets, val
+
+
+def prune_context(store, val_frac=0.3, ppo_iters=40, sparsity_coef=0.15,
+                  finetune_epochs=300, rebirth_fraction=0.5,
+                  select_tolerance=0.03, verbose=True, seed=0):
+    """apoptosis → re-settle → neurogenesis → re-settle, then COMPACT so the
+    surviving channels are the only ones that cost anything."""
+    import time
+
+    import mlx.core as mx
+    import mlx.nn as nn
+
+    from .ctxprune import compact, get_channel_mask, run_pruning_cycle
+    from .ctxtower import (load_tower, overlap_mask, retrieval_r1,
+                           save_tower, siglip_loss)
+
+    model, codec, meta = load_tower(store.dir / "models" / "context")
+    windows, seqs, targets, val = _prepare(
+        store, meta["window_s"], meta["stride_s"], codec, val_frac,
+        meta.get("d_out", 48))
+
+    Xtr = mx.array(_pad_stack([s for s, m in zip(seqs, ~val) if m]))
+    Xva = mx.array(_pad_stack([s for s, m in zip(seqs, val) if m]))
+    Ytr, Yva = mx.array(targets[~val]), mx.array(targets[val])
+    ig_tr = mx.array(overlap_mask([w for w, m in zip(windows, ~val) if m]))
+    ig_va = mx.array(overlap_mask([w for w, m in zip(windows, val) if m]))
+    log_t = mx.array(np.float32(meta["metrics"]["log_t"]))
+    bias = mx.array(np.float32(meta["metrics"]["bias"]))
+
+    def _norm(a):
+        return a * mx.rsqrt(mx.sum(a * a, axis=-1, keepdims=True) + 1e-8)
+
+    def _loss(m, x, y, ig):
+        v = _norm(m(x))
+        u = _norm(y)
+        return siglip_loss(v, u, ignore=ig, log_t=log_t, bias=bias) \
+            + 0.3 * mx.mean(1.0 - mx.sum(v * u, axis=-1))
+
+    def loss_of(m):
+        """The number PPO is scored against: VALIDATION retrieval loss. Using
+        train loss here would reward a policy for keeping memorisers."""
+        m.set_training(False)
+        return float(_loss(m, Xva, Yva, ig_va).item())
+
+    lg = nn.value_and_grad(model, lambda m: _loss(m, Xtr, Ytr, ig_tr))
+
+    def r1(m):
+        m.set_training(False)
+        return retrieval_r1(np.array(_norm(m(Xva))), np.array(_norm(Yva)))
+
+    def latency(m, reps=20):
+        m.set_training(False)
+        mx.eval(m(Xva))
+        t = time.perf_counter()
+        for _ in range(reps):
+            mx.eval(m(Xva))
+        return (time.perf_counter() - t) / reps / Xva.shape[0] * 1e6
+
+    before = {"channels": int(get_channel_mask(model).sum()),
+              "val_loss": loss_of(model), "val_R@1": r1(model),
+              "us_per_window": latency(model),
+              "params": int(sum(v.size for v in _flat(model).values()))}
+
+    rec = run_pruning_cycle(model, np.array(Xtr), loss_of, lg,
+                            ppo_iters=ppo_iters, sparsity_coef=sparsity_coef,
+                            finetune_epochs=finetune_epochs,
+                            rebirth_fraction=rebirth_fraction,
+                            select_tolerance=select_tolerance, seed=seed,
+                            verbose=verbose)
+
+    # Compaction must be a no-op numerically — it only deletes channels the
+    # mask already zeroed. Measure both sides and say so if they disagree,
+    # rather than quietly shipping a tower that differs from the one the
+    # search selected.
+    restored = loss_of(model)
+    model, kept = compact(model)
+    after = {"channels": int(len(kept)), "val_loss": loss_of(model),
+             "loss_before_compaction": restored, "val_R@1": r1(model),
+             "us_per_window": latency(model),
+             "params": int(sum(v.size for v in _flat(model).values()))}
+    rec["before"], rec["after"] = before, after
+    drift = abs(after["val_loss"] - restored)
+    if drift > 1e-3:
+        print(f"  WARNING: compaction changed val loss by {drift:.4f} "
+              f"({restored:.4f} -> {after['val_loss']:.4f}) — expected ~0")
+    if verbose:
+        print(f"\n  channels {before['channels']} -> {after['channels']} | "
+              f"params {before['params']:,} -> {after['params']:,} | "
+              f"{before['us_per_window']:.1f} -> {after['us_per_window']:.1f} "
+              f"us/window | val loss {before['val_loss']:.4f} -> "
+              f"{after['val_loss']:.4f}")
+    save_tower(model, codec,
+               {**{k: v for k, v in meta.items() if k != "history"},
+                "pruned": {"before": before, "after": after,
+                           "ppo_history": rec.get("ppo_history"),
+                           "keep_probs": rec.get("keep_probs"),
+                           "reverse_attention": rec.get("reverse_attention"),
+                           "selected": rec.get("selected"),
+                           "stages": [{k: v for k, v in s.items()
+                                       if k != "mask"} for s in rec["stages"]]}},
+               store.dir / "models" / "context")
+    return model, rec
+
+
+# ---------------------------------------------------------------------------
+# 7. The query path — two matmuls, no VLM, no decode
+# ---------------------------------------------------------------------------
+_CTX_CACHE: dict = {}
+
+
+def _ctx_matrix(store):
+    t = store.table("context")
+    key = (str(store.dir), t.state().version)
+    if key not in _CTX_CACHE:
+        _CTX_CACHE[key] = np.stack([
+            np.asarray(v, dtype=np.float32)
+            for v in t.scan().column("vector").to_pylist()])
+    return _CTX_CACHE[key]
+
+
+def _lexical(store):
+    """(vectorizer, matrix, has_caption) aligned to the `context` table rows.
+
+    Windows the VLM never captioned have no text, so they are marked as
+    abstentions rather than as empty documents — an empty document would score
+    0 on every query and be ranked last by the lexical ranker, which is a veto
+    dressed up as evidence.
+    """
+    t = store.table("context")
+    key = (str(store.dir), t.state().version, "lex")
+    if key in _CTX_CACHE:
+        return _CTX_CACHE[key]
+    ctx = t.scan()
+    rows = list(zip(ctx.column("stream").to_pylist(),
+                    ctx.column("ts").to_pylist()))
+    caps = store.table("context_captions").scan()
+    known = dict(zip(zip(caps.column("stream").to_pylist(),
+                         caps.column("ts").to_pylist()),
+                     caps.column("caption").to_pylist()))
+    texts = [known.get(r, "") for r in rows]
+    has = np.array([bool(x) for x in texts])
+    space = caption_space(store)
+    X = space.vec.transform(texts)
+    nrm = np.sqrt(np.asarray(X.multiply(X).sum(1))).ravel() + 1e-8
+    _CTX_CACHE[key] = (space, X, nrm, has)
+    return _CTX_CACHE[key]
+
+
+DEFAULT_WEIGHTS = {"appearance": 1.0, "context": 1.0, "lexical": 1.0}
+
+
+def search(store, text, k=10, merge=True, t0=None, t1=None, streams=None,
+           weights=None, rrf_k=60.0, neg_weight=0.5, min_score=None,
+           percentile=None, rerank=False, rerank_top=12, rerank_alpha=0.7,
+           explain_top=0):
+    """Hybrid contextual search: three rankers fused by reciprocal rank.
+
+        appearance  SigLIP image-text cosine over the window's frames.
+                    Knows what OBJECTS are present. Order-blind.
+        context     caption-LSA cosine. Knows what is HAPPENING, because the
+                    caption was written by a VLM that watched three frames.
+        lexical     TF-IDF over the caption text. Exact term evidence — the
+                    ranker that actually knows what "red" means.
+
+    Fusing by RRF rather than by a weighted score sum is the fix for
+    "crossing red car" returning any clip of someone crossing: RRF rewards
+    agreement across rankers, so a candidate that satisfies one strong signal
+    alone can no longer win. See elidedb.fusion.
+
+    `rerank=True` adds a final VLM pass over the top `rerank_top` — the
+    expensive operator, last, on an already-pruned set.
+    """
+    from .embeddings import _parse_query, _score_windows, embed_text
+    from .fusion import explain_fusion, rrf
+    # Fail with a sentence, not a KeyError from three frames down. An empty
+    # table has no schema, so the first column access explodes with
+    # 'Field "t1" does not exist' — true, useless, and it names the wrong
+    # problem.
+    if not store.table("context").state().files:
+        raise RuntimeError(
+            f"store '{store.name}' has no context index. Build it with "
+            "store.index_context() (frames -> per-frame vectors -> VLM "
+            "captions -> context table), or use store.search_text() for "
+            "appearance-only search.")
+    pos, neg = _parse_query(text)
+    ctx_tbl = store.table("context").scan()
+    all_t0 = ctx_tbl.column("ts").to_numpy()
+    all_t1 = ctx_tbl.column("t1").to_numpy()
+    all_s = ctx_tbl.column("stream").to_numpy(zero_copy_only=False)
+
+    # hybrid retrieval: time and stream predicates are pushed INTO candidate
+    # selection, not applied to a global top-k afterwards
+    pred = np.ones(len(all_t0), bool)
+    if t0 is not None:
+        pred &= all_t1 >= t0
+    if t1 is not None:
+        pred &= all_t0 <= t1
+    if streams:
+        pred &= np.isin(all_s, list(streams))
+    idx = np.where(pred)[0]
+    if len(idx) == 0:
+        return [], {"index": "context", "total": len(all_t0), "scanned": 0,
+                    "segments": 0}
+
+    APP = _appearance_matrix(store)
+    CTX = _ctx_matrix(store)
+    space, X, nrm, has_cap = _lexical(store)
+
+    pos_app = np.stack([embed_text(p) for p in pos])
+    neg_app = np.stack([embed_text(n) for n in neg]) if neg else None
+    app = _score_windows(APP, idx, pos_app, neg_app, neg_weight)
+
+    q_join = " ".join(pos)
+    ctx_sc = CTX[idx] @ space.transform([q_join])[0]
+
+    qv = space.vec.transform([q_join])
+    lex = np.asarray((X[idx] @ qv.T).todense()).ravel() / nrm[idx]
+    lex = np.where(has_cap[idx], lex, np.nan)      # abstain, do not veto
+
+    rankings = {"appearance": app, "context": ctx_sc, "lexical": lex}
+    w = {**DEFAULT_WEIGHTS, **(weights or {})}
+    scores = rrf(rankings, w, rrf_k)
+
+    stats = {"index": "context", "total": len(all_t0), "scanned": len(idx),
+             "method": "rrf", "rrf_k": rrf_k, "weights": w,
+             "predicate_candidates": int(pred.sum()),
+             "captioned_candidates": int(has_cap[idx].sum()),
+             "positive_terms": pos, "negative_terms": neg}
+    if explain_top:
+        stats["why"] = explain_fusion(rankings, w, rrf_k, top=explain_top)
+
+    keep = np.ones(len(idx), bool)
+    if percentile is not None:
+        keep &= scores >= np.percentile(scores, percentile)
+    if min_score is not None:
+        keep &= scores >= min_score
+    idx, scores = idx[keep], scores[keep]
+    stats["after_floor"] = int(len(idx))
+
+    hits = _segments(idx, scores, all_s, all_t0, all_t1, k, merge, stats)
+    if rerank and hits:
+        from .rerank import rerank_hits
+        hits, info = rerank_hits(store, hits, text, top_n=rerank_top,
+                                 alpha=rerank_alpha)
+        stats["rerank"] = info
+    return hits, stats
+
+
+def _segments(idx, scores, all_s, all_t0, all_t1, k, merge, stats):
+    """Merge qualifying windows into maximal runs per stream.
+
+    Fixed windows are an INDEXING granularity, not an answer granularity: a
+    20 s event should come back as one 20 s hit, and a query matching only 2 s
+    of it should come back as that 2 s.
+    """
+    streams_sel, w_t0, w_t1 = all_s[idx], all_t0[idx], all_t1[idx]
+    if len(idx) == 0:
+        stats["segments"] = 0
+        return []
+    if not merge:
+        order = np.argsort(scores)[::-1][:k]
+        return [{"stream": str(streams_sel[i]), "t0": int(w_t0[i]),
+                 "t1": int(w_t1[i]), "score": float(scores[i]),
+                 "windows": 1} for i in order]
+    med, top = float(np.median(scores)), float(scores.max())
+    thr = med + 0.55 * (top - med)
+    stats["threshold"] = round(thr, 6)
+    qual = np.where(scores >= thr)[0]
+    order = np.lexsort((w_t0[qual], streams_sel[qual]))
+    qual = qual[order]
+    gap = int(np.median(w_t1[qual] - w_t0[qual])) + 1 if len(qual) else 0
+    segs = []
+    for i in qual:
+        s_, a, b, sc = (str(streams_sel[i]), int(w_t0[i]), int(w_t1[i]),
+                        float(scores[i]))
+        last = segs[-1] if segs else None
+        if last and last["stream"] == s_ and a - last["t1"] <= gap:
+            last["t1"] = max(last["t1"], b)
+            last["score"] = max(last["score"], sc)
+            last["mean"] = (last["mean"] * last["windows"] + sc) / (last["windows"] + 1)
+            last["windows"] += 1
+        else:
+            segs.append({"stream": s_, "t0": a, "t1": b, "score": sc,
+                         "mean": sc, "windows": 1})
+    segs.sort(key=lambda g: -g["score"])
+    stats["qualifying_windows"] = len(qual)
+    stats["segments"] = len(segs)
+    return segs[:k]
+
+
+def _appearance_matrix(store):
+    t = store.table("context")
+    key = (str(store.dir), t.state().version, "app")
+    if key not in _CTX_CACHE:
+        _CTX_CACHE[key] = np.stack([
+            np.asarray(v, dtype=np.float32)
+            for v in t.scan().column("appearance").to_pylist()])
+    return _CTX_CACHE[key]
+
+
+def explain(store, t0, t1, stream=None):
+    """What the database believes is happening in a window — the teacher's own
+    words. Lets a result be checked rather than trusted."""
+    caps = store.table("context_captions").scan()
+    out = []
+    if len(caps) == 0 or "stream" not in caps.column_names:
+        return out          # store has no captions (yet) — nothing to explain
+    for s, a, b, c in zip(caps.column("stream").to_pylist(),
+                          caps.column("ts").to_pylist(),
+                          caps.column("t1").to_pylist(),
+                          caps.column("caption").to_pylist()):
+        if stream and s != stream:
+            continue
+        if b >= t0 and a <= t1:
+            out.append({"stream": s, "t0": a, "t1": b, "caption": c})
+    return out
+
+
+def _embed_frames_fdnnv(store, frame_table, incremental, verbose, streams):
+    """Every frame through the FDNN-V streaming encoder -> frame_vectors."""
+    import pyarrow as pa
+
+    from .fdnnvideo import embed_stream, load_encoder
+    mdir = store.dir / "models" / "fdnnv"
+    if not (mdir / "encoder.json").exists():
+        # a NEW store has no encoder yet — adopt one from a sibling store
+        # and COPY it in, so the store stays self-contained and the exact
+        # weights that wrote its vectors are pinned with its data
+        import shutil
+        donors = sorted(store.dir.parent.glob("*/models/fdnnv/encoder.json"),
+                        key=lambda p: p.stat().st_mtime, reverse=True)
+        if not donors:
+            raise RuntimeError(
+                "no FDNN-V encoder found in this store or any sibling — "
+                "train one first (scripts/fdnnv_train.py)")
+        shutil.copytree(donors[0].parent, mdir)
+        if verbose:
+            print(f"  adopted encoder from {donors[0].parent}", flush=True)
+    model, meta = load_encoder(mdir)
+    # FRESH-DATA FIDELITY GATE: the fast student was distilled on one
+    # style of footage; on an arbitrary upload its fidelity to the teacher
+    # is unknown. 32 of THIS store's frames go through both encoders; if
+    # mean cosine < 0.90 the store gets the TEACHER (slower ingest, right
+    # space) instead of a fast-but-wrong index. Automatic — a fresh
+    # customer never has to know this exists.
+    try:
+        from PIL import Image
+        from .embeddings import DEFAULT_MODEL, _embed_images
+        from .video import FrameSet
+        frames_all = store.table(frame_table).scan()
+        pick = np.linspace(0, len(frames_all) - 1,
+                           min(32, len(frames_all))).round().astype(int)
+        rows = frames_all.take(pick)
+        ts_s, sv, _, _ = embed_stream(store, model, rows)
+        dec = FrameSet(store, frame_table, rows).decode(width=448)
+        imgs = [Image.fromarray(d[1]) for d in sorted(dec)]
+        tv = _embed_images(imgs, DEFAULT_MODEL)
+        n = min(len(sv), len(tv))
+        svn = sv[:n] / (np.linalg.norm(sv[:n], axis=1,
+                                       keepdims=True) + 1e-8)
+        fid = float((svn * tv[:n]).sum(1).mean())
+        if verbose:
+            print(f"  student fidelity on this corpus: {fid:.3f}",
+                  flush=True)
+        if fid < 0.90:
+            print(f"  fidelity {fid:.3f} < 0.90 — falling back to the "
+                  f"TEACHER encoder for this store", flush=True)
+            return embed_frames(store, frame_table, model="fast",
+                                incremental=incremental, verbose=verbose,
+                                streams=streams, engine="siglip")
+    except Exception as e:
+        if verbose:
+            print(f"  fidelity gate skipped ({type(e).__name__})",
+                  flush=True)
+    frames = store.table(frame_table).scan()
+    allst = sorted(set(frames.column("stream").to_pylist()))
+    use = [s for s in allst if s in streams] if streams else allst
+    done = {}
+    if incremental:
+        try:
+            prev = store.table("frame_vectors").scan()
+            for s_, t_ in zip(prev.column("stream").to_pylist(),
+                              prev.column("ts").to_pylist()):
+                done[s_] = max(done.get(s_, -1), t_)
+        except Exception:
+            pass
+    t_start = time.time()
+    rows_ts, rows_stream, rows_vec = [], [], []
+    for s in use:
+        sel = frames.filter(pc.equal(frames.column("stream"), s))
+        if s in done:
+            sel = sel.filter(pc.greater(sel.column("ts"), done[s]))
+        if len(sel) == 0:
+            continue
+        sel = sel.take(pc.sort_indices(sel.column("ts")))
+        ts, vecs, dec_s, emb_s = embed_stream(store, model, sel)
+        if verbose:
+            print(f"  {s}: {len(ts):,} frames (decode {dec_s:.1f}s, "
+                  f"embed {emb_s:.1f}s)", flush=True)
+        rows_ts.extend(int(t) for t in ts)
+        rows_stream.extend([s] * len(ts))
+        rows_vec.extend(vecs)
+    if not rows_ts:
+        return {"frames": 0, "note": "nothing new (incremental)"}
+    dim = len(rows_vec[0])
+    tbl = pa.table({
+        "ts": pa.array(rows_ts, pa.int64()),
+        "stream": pa.array(rows_stream),
+        "vector": pa.array([v.tolist() for v in rows_vec],
+                           pa.list_(pa.float32(), dim)),
+    })
+    version = store.table("frame_vectors").append(
+        tbl, kind="embeddings",
+        meta={"model": "fdnnv", "teacher": meta.get("teacher"),
+              "dim": dim, "every_frame": True,
+              "source_table": frame_table})
+    return {"frames": len(tbl), "dim": dim, "version": version,
+            "engine": "fdnnv",
+            "seconds": round(time.time() - t_start, 1)}

python/elidedb/corpus.py

@@ -0,0 +1,96 @@
+"""S5: dataset LAYOUT as configuration, not as constants in six scripts.
+
+`CAM = "observation.images.image_0"`, `EPOCH_NS`, `FILE_STRIDE_NS` and
+`FPS = 5.0` were copied into bridge_ingest, bridge4h, bridge_full,
+rebuild_bench and full_write. None of them is a task prior - they
+describe where the bytes are, not what the bytes mean - but six copies
+of a dataset's shape is still the dataset hardwired into the engine, and
+pointing ElideDB at a driving log meant editing six files.
+
+A corpus descriptor is data. It lives beside the raw files, it is read,
+and the engine has no opinion about its contents.
+
+    {
+      "name": "bridge",
+      "root": "data/bridge",
+      "streams": [{"id": "observation.images.image_0",
+                   "path": "videos/{id}/chunk-000/file-{file:03d}.mp4",
+                   "fps": 5.0}],
+      "epoch_ns": 1704067200000000000,
+      "file_stride_ns": 20000000000000,
+      "episodes": {"table": "meta/episodes/chunk-000/file-000.parquet",
+                   "index": "episode_index", "length": "length"},
+      "exclude": ["tasks"]
+    }
+
+`exclude` is the important field and the reason this is not merely
+tidiness: it is where a corpus declares which of its own columns are
+ANNOTATION rather than observation. Bridge's `tasks` column says what
+each clip is about, which is precisely what the database is supposed to
+work out from pixels; ingesting it would turn every retrieval number
+into a join against a label. bridge_ingest.py enforced that by hand, in
+a docstring. Here it is a field the ingest path honours for any corpus,
+so the next dataset cannot forget.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+# Fields every corpus must supply. No defaults for the ones that encode
+# the dataset's shape: guessing an epoch or a frame rate silently
+# misaligns every timestamp in the store, and a loud failure is cheaper.
+REQUIRED = ("name", "root", "streams")
+
+
+class Corpus:
+    """A dataset's shape, read from disk. Never inferred, never guessed."""
+
+    def __init__(self, d: dict, path=None):
+        missing = [k for k in REQUIRED if k not in d]
+        if missing:
+            raise ValueError(f"corpus descriptor missing {missing}")
+        self.d, self.path = d, path
+        self.name = d["name"]
+        self.root = Path(d["root"])
+        self.streams = d["streams"]
+        self.epoch_ns = int(d.get("epoch_ns", 0))
+        self.file_stride_ns = int(d.get("file_stride_ns", 0))
+        # columns the corpus declares as ANNOTATION - never ingested
+        self.exclude = set(d.get("exclude", ()))
+
+    @staticmethod
+    def load(path):
+        p = Path(path)
+        if p.is_dir():
+            p = p / "corpus.json"
+        return Corpus(json.loads(p.read_text()), p)
+
+    def stream(self, sid=None):
+        if sid is None:
+            return self.streams[0]
+        for s in self.streams:
+            if s["id"] == sid:
+                return s
+        raise KeyError(f"no stream {sid} in corpus {self.name}")
+
+    def fps(self, sid=None):
+        return float(self.stream(sid).get("fps", 0)) or None
+
+    def media(self, file_index, sid=None):
+        s = self.stream(sid)
+        return self.root / s["path"].format(id=s["id"], file=int(file_index))
+
+    def base_ns(self, file_index):
+        """Timeline origin for a file. 0/0 means the corpus carries real
+        timestamps and no synthetic clock is being imposed."""
+        return self.epoch_ns + int(file_index) * self.file_stride_ns
+
+    def is_annotation(self, column: str) -> bool:
+        """True for columns the corpus declares as annotation.
+
+        The ingest path must refuse these. A column that says what a clip
+        is ABOUT is the answer to the question the database exists to
+        answer, and ingesting it makes every later number a lookup.
+        """
+        return column in self.exclude

python/elidedb/cracked.py

@@ -0,0 +1,133 @@
+"""Sharp text search: student shortlist, teacher verdict, cracked cache.
+
+THE PROBLEM THIS SOLVES
+-----------------------
+Student (FDNN-V) embeddings rank the whole corpus in ~1 ms but their text
+ranking is measurably weak (top-10 agreement 0.5/10 vs the 4.3/10
+teacher-self ceiling). The teacher ranks text pristinely but costs 27.7 ms
+per frame — unaffordable corpus-wide, affordable on a SHORTLIST.
+
+So the query plan is the database's oldest shape, applied to models:
+
+    cheap operator over everything  ->  expensive operator over survivors
+    student ranks all windows (~1ms)    teacher re-scores top-N (~30ms each)
+
+THE CRACKING PART
+-----------------
+Every teacher vector computed for a query is WRITTEN BACK to the
+`teacher_windows` table. The next query that touches those windows pays
+nothing. Like database cracking (Idreos et al., CIDR 2007), the index
+materialises as a side effect of the workload: hot regions of the corpus
+become pristine after their first visit, cold regions never cost a cent.
+Cost scales with what users ask, not with what they store.
+
+The teacher here is SigLIP-224 ("fast") — measured within the teacher-self
+agreement band of the 384 model at a third of the price — and the query text
+is embedded with the SAME checkpoint, so the rerank compares like with like.
+"""
+from __future__ import annotations
+
+import time
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.compute as pc
+
+TEACHER = "fast"                    # resolved by embeddings.resolve_model
+_CACHE: dict = {}                   # (store, version) -> {key: vec}
+
+
+def _cache_map(store):
+    t = store.table("teacher_windows")
+    st = t.state()
+    key = (str(store.dir), st.version)
+    if key not in _CACHE:
+        m = {}
+        if st.files:
+            tb = t.scan()
+            for s, a, v in zip(tb.column("stream").to_pylist(),
+                               tb.column("ts").to_pylist(),
+                               tb.column("vector").to_pylist()):
+                m[(s, int(a))] = np.asarray(v, np.float32)
+        _CACHE.clear()
+        _CACHE[key] = m
+    return _CACHE[key]
+
+
+def _teacher_embed_windows(store, wins):
+    """Decode ONE centre frame per window through the byte-range path and
+    embed with the teacher. `wins` = [(stream, t0, t1)]."""
+    from PIL import Image
+
+    from .embeddings import _embed_images
+    frames = store.table("frames").scan()
+    imgs, keys = [], []
+    for (s, a, b) in wins:
+        mid = (a + b) // 2
+        sel = frames.filter(pc.and_(
+            pc.equal(frames.column("stream"), s),
+            pc.and_(pc.greater_equal(frames.column("ts"),
+                                     mid - 2_000_000_000),
+                    pc.less_equal(frames.column("ts"),
+                                  mid + 2_000_000_000))))
+        from .video import FrameSet
+        dec = FrameSet(store, "frames", sel).decode(stream=s, width=448,
+                                                    limit=1)
+        if dec:
+            imgs.append(Image.fromarray(dec[0][1]))
+            keys.append((s, a, b))
+    if not imgs:
+        return {}
+    vecs = _embed_images(imgs, TEACHER)
+    return {k: v for k, v in zip(keys, vecs)}
+
+
+def search_sharp(store, text, k=10, shortlist=48):
+    """Student ranks everything; the teacher re-scores the shortlist; misses
+    are cached into the store. Returns (hits, stats)."""
+    from .embeddings import _vec_table, embed_text
+    t_start = time.perf_counter()
+    tbl, vecs = _vec_table(store, "embeddings")
+    a_t0 = tbl.column("ts").to_numpy()
+    a_t1 = tbl.column("t1").to_numpy()
+    a_s = tbl.column("stream").to_numpy(zero_copy_only=False)
+
+    q_student = embed_text(text)                       # 384-space (student's)
+    order = np.argsort(-(vecs @ q_student))[:shortlist]
+    wins = [(str(a_s[i]), int(a_t0[i]), int(a_t1[i])) for i in order]
+
+    cache = _cache_map(store)
+    missing = [w for w in wins if (w[0], w[1]) not in cache]
+    t_miss = time.perf_counter()
+    if missing:
+        fresh = _teacher_embed_windows(store, missing)
+        if fresh:
+            ft = pa.table({
+                "ts": pa.array([a for (_, a, _b) in fresh], pa.int64()),
+                "t1": pa.array([b for (_, _a, b) in fresh], pa.int64()),
+                "stream": pa.array([s for (s, _a, _b) in fresh]),
+                "vector": pa.array([v.tolist() for v in fresh.values()],
+                                   pa.list_(pa.float32(), 1152)),
+            })
+            store.table("teacher_windows").append(
+                ft, kind="embeddings",
+                meta={"model": TEACHER, "written_by": "query cracking"})
+            for (s, a, _b), v in fresh.items():
+                cache[(s, a)] = v
+    miss_ms = (time.perf_counter() - t_miss) * 1e3
+
+    q_teacher = embed_text(text, model_id=TEACHER)     # same checkpoint as
+    hits = []                                          # the cached vectors
+    for (s, a, b) in wins:
+        tv = cache.get((s, a))
+        if tv is None:
+            continue
+        hits.append({"stream": s, "t0": a, "t1": b,
+                     "score": float(tv @ q_teacher), "teacher": True})
+    hits.sort(key=lambda h: -h["score"])
+    stats = {"method": "sharp", "shortlist": len(wins),
+             "cache_misses": len(missing),
+             "teacher_ms": round(miss_ms, 1),
+             "cache_size": len(cache),
+             "ms": round((time.perf_counter() - t_start) * 1e3, 1)}
+    return hits[:k], stats

python/elidedb/ctxprune.py

@@ -0,0 +1,516 @@
+"""Post-training cellular turnover for the context tower — PPO + reverse
+attention, ported from FDNN_BrainModel/models/pruning.py.
+
+WHY PRUNE AT ALL
+----------------
+Because the only thing this index is for is answering fast. Every channel the
+tower carries is multiplied over T timesteps, for every window, at every
+rebuild. Capacity that is not earning its keep is latency the user pays for
+forever. And with a few hundred labelled windows, an over-provisioned tower
+is also memorising — so apoptosis buys accuracy and speed at the same time,
+which is exactly the regime cellular turnover was designed for.
+
+WHAT CHANGED FROM FDNN, AND WHY
+-------------------------------
+FDNN prunes per (layer, neuron): every layer has its own aliveness mask. That
+is right for a plain stack. This tower is a RESIDUAL stack, and in a residual
+stack channel j is a wire that runs the whole depth — masking it in layer 2
+alone does not remove it, because the skip connection keeps carrying it. So
+the prune unit here is the residual-stream CHANNEL, decided once and applied
+to every block.
+
+That is not a weakening of the idea, it is the correct form of it for this
+topology (the same structured channel pruning people apply to ResNets), and
+it has a property per-layer masking does not: a dead channel can be
+physically deleted. `compact()` rebuilds the tower without it, so the mask
+turns into real wall-clock speed instead of a multiply by zero. Pruning that
+does not shrink the matmul is not pruning, it is decoration.
+
+THE THREE MEASURES (unchanged in spirit from FDNN)
+--------------------------------------------------
+  utilization      Δ validation RETRIEVAL loss when the channel is silenced.
+                   Not weight magnitude — the thing we actually care about.
+  reverse attention softmax(-utilization): mass on the channels the network
+                   attends AWAY from, i.e. the prune candidates.
+  PPO              a clipped-PPO contextual bandit over per-channel features
+                   that samples masks, scores them by
+                   -(loss ratio) - λ·kept_fraction, and learns which channels
+                   can actually go.
+"""
+from __future__ import annotations
+
+import mlx.core as mx
+import mlx.nn as nn
+import mlx.optimizers as optim
+import numpy as np
+
+
+# ===========================================================================
+# 0. Channel mask plumbing
+# ===========================================================================
+def n_channels(model):
+    return model.blocks[0].max_out_d
+
+
+def get_channel_mask(model):
+    return np.array(model.blocks[0].mask).copy()
+
+
+def set_channel_mask(model, mask):
+    """One decision, applied to every block — see module docstring."""
+    m = np.asarray(mask, dtype=np.float32)
+    for b in model.turnover_layers():
+        b.set_active_mask(m)
+
+
+# ===========================================================================
+# 1. Utilization ("consumption")
+# ===========================================================================
+def measure_utilization(model, loss_of, verbose=False):
+    """Per-channel ablation importance + the cheap descriptive stats.
+
+    `loss_of(model)` must return the validation retrieval loss as a float.
+    Ablation is the increase in that loss when a single channel is silenced
+    everywhere — the most directly interpretable notion of how much the tower
+    relies on it.
+    """
+    model.set_training(False)
+    base = loss_of(model)
+    mask = get_channel_mask(model)
+    n = len(mask)
+
+    abl = np.zeros(n, dtype=np.float32)
+    for c in np.where(mask == 1.0)[0]:
+        probe = mask.copy()
+        probe[c] = 0.0
+        set_channel_mask(model, probe)
+        abl[c] = max(loss_of(model) - base, 0.0)
+    set_channel_mask(model, mask)
+    return {"mask": mask, "ablation": abl, "base_loss": base}
+
+
+def descriptive_stats(model, X):
+    """Activation magnitude per channel (averaged over blocks) and the
+    downstream weight norm each channel feeds."""
+    model.set_training(False)
+    outs = []
+    h = mx.array(X)
+    for b in model.turnover_layers():
+        outs.append(np.array(mx.mean(mx.abs(b.neuron_outputs(h)), axis=(0, 1))))
+        h = b(h)
+    act = np.mean(np.stack(outs), axis=0)
+
+    n = n_channels(model)
+    wf = np.array(model.gru_f.Wx)          # (3*hidden, n_hidden)
+    wb = np.array(model.gru_b.Wx)
+    hw = np.array(model.head.weight)       # (d_out, n_hidden + 2*gru_hidden)
+    pw = np.array(model.pool.proj.weight)
+    down = (np.linalg.norm(wf, axis=0) + np.linalg.norm(wb, axis=0)
+            + np.linalg.norm(hw[:, :n], axis=0)
+            + np.linalg.norm(pw[:, :n], axis=0))
+    return act.astype(np.float32), down.astype(np.float32)
+
+
+# ===========================================================================
+# 2. Reverse attention
+# ===========================================================================
+def reverse_attention(importance, mask, temperature=1.0):
+    """Forward attention concentrates on useful units; reverse attention
+    inverts it so the LEAST useful surface as prune candidates. Dead channels
+    score 0; scores over the live set sum to 1."""
+    importance = np.asarray(importance, dtype=np.float64)
+    alive = mask == 1.0
+    r = np.zeros_like(importance)
+    if alive.sum() == 0:
+        return r.astype(np.float32)
+    imp = importance[alive]
+    imp = (imp - imp.mean()) / (imp.std() + 1e-8)
+    logits = -imp / max(temperature, 1e-6)
+    logits -= logits.max()
+    e = np.exp(logits)
+    r[alive] = e / (e.sum() + 1e-12)
+    return r.astype(np.float32)
+
+
+# ===========================================================================
+# 3. PPO agent
+# ===========================================================================
+class PrunePolicy(nn.Module):
+    def __init__(self, feat_dim, hidden=32):
+        super().__init__()
+        self.fc1 = nn.Linear(feat_dim, hidden)
+        self.fc2 = nn.Linear(hidden, hidden)
+        self.pi_head = nn.Linear(hidden, 1)
+        self.v_head = nn.Linear(hidden, 1)
+
+    def __call__(self, feats):
+        h = nn.relu(self.fc1(feats))
+        h = nn.relu(self.fc2(h))
+        return self.pi_head(h)[:, 0], self.v_head(h)[:, 0]
+
+
+def _bernoulli_logp(actions, logits):
+    return actions * logits - mx.logaddexp(mx.zeros_like(logits), logits)
+
+
+def _entropy(logits):
+    p = mx.sigmoid(logits)
+    return nn.softplus(logits) - p * logits
+
+
+class PPOPruner:
+    """Contextual bandit over prune masks of the residual stream.
+
+    One step per episode: observe a fixed per-channel feature matrix from the
+    frozen tower, emit a keep-probability per channel, sample a binary mask,
+    receive one scalar reward. Maximising it means "prune as much as possible
+    without inflating retrieval loss".
+    """
+
+    def __init__(self, model, X, loss_of, sparsity_coef=0.35,
+                 loss_tolerance=1.0, hidden=32, lr=3e-3, clip_eps=0.2,
+                 entropy_coef=0.01, value_coef=0.5, seed=0):
+        self.model, self.loss_of = model, loss_of
+        self.sparsity_coef = sparsity_coef
+        self.loss_tolerance = loss_tolerance
+        self.clip_eps, self.entropy_coef = clip_eps, entropy_coef
+        self.value_coef = value_coef
+        np.random.seed(seed)
+        mx.random.seed(seed)
+
+        self.base_mask = get_channel_mask(model)
+        util = measure_utilization(model, loss_of)
+        self.base_loss = util["base_loss"]
+        self.ablation = util["ablation"]
+        act, down = descriptive_stats(model, X)
+        ra = reverse_attention(self.ablation, self.base_mask)
+        omega = model.blocks[0].omegas_per_neuron
+
+        self.candidates = np.where(self.base_mask == 1.0)[0]
+        f = np.stack([self.ablation[self.candidates], act[self.candidates],
+                      down[self.candidates], ra[self.candidates],
+                      omega[self.candidates]], axis=1).astype(np.float32)
+        mu, sd = f.mean(0, keepdims=True), f.std(0, keepdims=True) + 1e-6
+        f[:, :4] = (f[:, :4] - mu[:, :4]) / sd[:, :4]
+        self.feats = mx.array(f)
+        self.reverse_attn = ra
+        self.policy = PrunePolicy(f.shape[1], hidden=hidden)
+        self.opt = optim.Adam(learning_rate=lr)
+        self.history = {"iter": [], "reward": [], "kept_frac": [],
+                        "loss_ratio": [], "entropy": []}
+
+    def _apply(self, action):
+        m = self.base_mask.copy()
+        m[self.candidates] = action
+        set_channel_mask(self.model, m)
+
+    def _reward(self, action):
+        self._apply(action)
+        loss = self.loss_of(self.model)
+        set_channel_mask(self.model, self.base_mask)
+        kept = float(action.mean()) if len(action) else 0.0
+        ratio = loss / (self.base_loss + 1e-12)
+        return (-self.loss_tolerance * ratio - self.sparsity_coef * kept,
+                kept, ratio)
+
+    def train(self, n_iters=40, episodes_per_iter=12, ppo_epochs=4,
+              verbose=True):
+        for it in range(n_iters):
+            logits, _ = self.policy(self.feats)
+            probs = np.array(mx.sigmoid(logits))
+            acts, rews, kfs, lrs = [], [], [], []
+            for _ in range(episodes_per_iter):
+                a = (np.random.uniform(size=probs.shape) < probs).astype(np.float32)
+                r, kf, lr_ = self._reward(a)
+                acts.append(a); rews.append(r); kfs.append(kf); lrs.append(lr_)
+            acts = np.array(acts, np.float32)
+            rews = np.array(rews, np.float32)
+            adv = (rews - rews.mean()) / (rews.std() + 1e-6)
+
+            acts_mx, adv_mx, rews_mx = mx.array(acts), mx.array(adv), mx.array(rews)
+            old_logits, _ = self.policy(self.feats)
+            old_logp = mx.array(np.array(
+                mx.sum(_bernoulli_logp(acts_mx, old_logits[None, :]), axis=1)))
+            for _ in range(ppo_epochs):
+                _, grads = self._loss_and_grad(acts_mx, old_logp, adv_mx, rews_mx)
+                self.opt.update(self.policy, grads)
+                mx.eval(self.policy.parameters(), self.opt.state)
+
+            ent = float(mx.mean(_entropy(logits)).item())
+            self.history["iter"].append(it)
+            self.history["reward"].append(float(rews.mean()))
+            self.history["kept_frac"].append(float(np.mean(kfs)))
+            self.history["loss_ratio"].append(float(np.mean(lrs)))
+            self.history["entropy"].append(ent)
+            if verbose and (it % 5 == 0 or it == n_iters - 1):
+                print(f"  PPO {it:3d} | reward {rews.mean():+.3f} | kept "
+                      f"{np.mean(kfs):.2f} | loss x{np.mean(lrs):.3f} | "
+                      f"H {ent:.3f}", flush=True)
+        return self.history
+
+    def _loss_and_grad(self, actions, old_logp, adv, rewards):
+        def loss_fn(policy):
+            logits, values = policy(self.feats)
+            v = mx.mean(values)
+            logp = mx.sum(_bernoulli_logp(actions, logits[None, :]), axis=1)
+            ratio = mx.exp(logp - old_logp)
+            pl = -mx.mean(mx.minimum(ratio * adv,
+                                     mx.clip(ratio, 1 - self.clip_eps,
+                                             1 + self.clip_eps) * adv))
+            vl = mx.mean(mx.square(v - rewards))
+            return pl + self.value_coef * vl \
+                - self.entropy_coef * mx.mean(_entropy(logits))
+        return nn.value_and_grad(self.policy, loss_fn)(self.policy)
+
+    def apply_greedy(self, keep_threshold=0.5):
+        logits, _ = self.policy(self.feats)
+        probs = np.array(mx.sigmoid(logits))
+        m = self.base_mask.copy()
+        m[self.candidates] = (probs >= keep_threshold).astype(np.float32)
+        set_channel_mask(self.model, m)
+        return m, probs
+
+
+# ===========================================================================
+# 4. Neurogenesis — revive dead channels with fresh, spectrally diverse ones
+# ===========================================================================
+def neurogenesis(model, n_revive, seed=0):
+    """Rebirth. New channels start near-silent (tiny w2) so they cannot shock
+    the forward pass, and are re-initialised with FINER's WIDE bias range —
+    without that they spawn as low-frequency clones and the population slowly
+    loses the spectral diversity that made the KAN basis worth having."""
+    rng = np.random.default_rng(seed)
+    mask = get_channel_mask(model)
+    dead = np.where(mask == 0.0)[0]
+    if len(dead) == 0 or n_revive <= 0:
+        return 0
+    revive = dead[:min(n_revive, len(dead))]
+
+    for b in model.turnover_layers():
+        w1 = np.array(b.w1)          # (kernel, in_d, out*k)
+        b1 = np.array(b.b1)
+        w2 = np.array(b.w2)
+        ph = np.array(b.phases)
+        gs = np.array(b.gabor_s)
+        la = np.array(b.log_alpha)
+        om_full = np.repeat(b.omegas_per_neuron, b.k)
+        mean_om = float(b.omegas_per_neuron.mean())
+        lim = float(np.sqrt(6.0 / (b.kernel * b.in_d)) / mean_om)
+        for c in revive:
+            s, e = c * b.k, (c + 1) * b.k
+            w1[:, :, s:e] = rng.uniform(-lim, lim, (b.kernel, b.in_d, b.k))
+            b1[s:e] = rng.uniform(-b.bias_range, b.bias_range, b.k)
+            ph[s:e] = rng.uniform(0, 2 * np.pi, b.k)
+            gs[s:e] = rng.uniform(0.3, 1.5, b.k)
+            lw = np.log(np.clip(om_full[s:e], 1e-3, None))
+            la[s:e] = rng.uniform(np.zeros_like(lw), lw)
+            w2[c, :] = rng.standard_normal(b.k) * 1e-6
+        b.w1 = mx.array(w1.astype(np.float32))
+        b.b1 = mx.array(b1.astype(np.float32))
+        b.w2 = mx.array(w2.astype(np.float32))
+        b.phases = mx.array(ph.astype(np.float32))
+        b.gabor_s = mx.array(gs.astype(np.float32))
+        b.log_alpha = mx.array(la.astype(np.float32))
+    mask[revive] = 1.0
+    set_channel_mask(model, mask)
+    return len(revive)
+
+
+# ===========================================================================
+# 5. Compaction — where the mask becomes actual speed
+# ===========================================================================
+def compact(model):
+    """Physically delete dead channels: return a smaller, equivalent tower.
+
+    Every dead channel is removed from each block's output slots, from every
+    consumer's input slots (both GRUs, the attention pool, the head), and from
+    the residual stream itself. Output is numerically equivalent to the masked
+    model but the matmuls are genuinely smaller.
+    """
+    from .ctxtower import ContextTower
+    keep = np.where(get_channel_mask(model) == 1.0)[0]
+    n_new = len(keep)
+    if n_new == 0:
+        raise RuntimeError("every channel was pruned")
+    if n_new == n_channels(model):
+        return model, keep
+
+    cfg = dict(model.cfg)
+    cfg["n_hidden"] = int(n_new)
+    new = ContextTower(**cfg)
+    k = model.blocks[0].k
+    sub = np.concatenate([np.arange(c * k, (c + 1) * k) for c in keep])
+
+    for ob, nb in zip(model.blocks, new.blocks):
+        w1 = np.array(ob.w1)
+        if not ob.use_residual:                  # first block: in_d is d_in
+            nb.w1 = mx.array(w1[:, :, sub])
+        else:                                    # in_d is the stream: slice both
+            nb.w1 = mx.array(w1[:, keep][:, :, sub])
+        nb.b1 = mx.array(np.array(ob.b1)[sub])
+        nb.phases = mx.array(np.array(ob.phases)[sub])
+        nb.gabor_s = mx.array(np.array(ob.gabor_s)[sub])
+        nb.log_alpha = mx.array(np.array(ob.log_alpha)[sub])
+        nb.w2 = mx.array(np.array(ob.w2)[keep])
+        # omegas is TRAINED, so it must be sliced from the live array — not
+        # rebuilt from omegas_per_neuron, which is the frozen design band and
+        # is stale the moment training starts. Rebuilding it silently reverted
+        # every learned frequency and moved val loss by 0.015.
+        nb.omegas = mx.array(np.array(ob.omegas)[sub])
+        nb.omegas_per_neuron = ob.omegas_per_neuron[keep]   # design band only
+        nb.basis_types = mx.array(np.array(ob.basis_types)[sub])
+        nb.freeze(keys=["basis_types"], recurse=False)
+        nb.set_active_mask(np.ones(n_new, np.float32))
+
+    n_old = n_channels(model)
+    g = model.cfg["gru_hidden"]
+    for og, ng in ((model.gru_f, new.gru_f), (model.gru_b, new.gru_b)):
+        ng.Wx = mx.array(np.array(og.Wx)[:, keep])
+        ng.Wh = mx.array(np.array(og.Wh))
+        ng.b = mx.array(np.array(og.b))
+        ng.bhn = mx.array(np.array(og.bhn))
+    # consumers of `cat` = [stream | gru_f | gru_b]: keep the stream slice,
+    # carry the two GRU slices through untouched.
+    tail = np.arange(n_old, n_old + 2 * g)
+    cols = np.concatenate([keep, tail])
+    new.pool.proj.weight = mx.array(np.array(model.pool.proj.weight)[:, cols])
+    new.pool.proj.bias = mx.array(np.array(model.pool.proj.bias))
+    new.pool.score.weight = mx.array(np.array(model.pool.score.weight))
+    new.pool.score.bias = mx.array(np.array(model.pool.score.bias))
+    new.head.weight = mx.array(np.array(model.head.weight)[:, cols])
+    new.head.bias = mx.array(np.array(model.head.bias))
+    new.log_gamma = mx.array(np.array(model.log_gamma))
+    new.set_training(False)
+    return new, keep
+
+
+# ===========================================================================
+# 6. Re-settle
+# ===========================================================================
+def finetune(model, loss_and_grad_fn, epochs=150, lr=5e-4,
+             weight_decay=1e-3, loss_of=None, patience=40):
+    """Short re-settling pass with aliveness frozen (see the mask gotcha).
+
+    Validation-aware on purpose. Survivors re-settle on the TRAIN set, and
+    with a couple of hundred windows an unguarded 400-epoch re-settle simply
+    re-memorises: measured, it took a pruned tower from 0.311 val back up to
+    0.357, undoing everything apoptosis had just gained. Keeping the best
+    validation state means re-settling can only help, never hurt.
+    """
+    from .ctxtower import _clone_params, _load_params
+    opt = optim.AdamW(learning_rate=lr, weight_decay=weight_decay)
+    frozen = get_channel_mask(model)
+    best, best_w, since = float("inf"), None, 0
+    if loss_of is not None:
+        best, best_w = loss_of(model), _clone_params(model)
+    for _ in range(epochs):
+        model.set_training(True)
+        loss, grads = loss_and_grad_fn(model)
+        opt.update(model, grads)
+        set_channel_mask(model, frozen)
+        mx.eval(model.parameters(), opt.state)
+        if loss_of is None:
+            continue
+        v = loss_of(model)
+        if v < best - 1e-5:
+            best, best_w, since = v, _clone_params(model), 0
+        else:
+            since += 1
+            if since >= patience:
+                break
+    if best_w is not None:
+        _load_params(model, best_w)
+        set_channel_mask(model, frozen)
+        mx.eval(model.parameters())
+    model.set_training(False)
+    return best
+
+
+# ===========================================================================
+# 7. The full cycle
+# ===========================================================================
+def run_pruning_cycle(model, X, loss_of, loss_and_grad_fn, ppo_iters=40,
+                      episodes_per_iter=12, sparsity_coef=0.35,
+                      keep_threshold=0.5, finetune_epochs=150,
+                      rebirth_fraction=0.5, select_tolerance=0.02,
+                      seed=0, verbose=True):
+    """apoptosis → re-settle → neurogenesis → re-settle, on a frozen tower.
+
+    The cycle is a SEARCH, so it returns the best point it visited, not the
+    last one. Rebirth is a bet that the data can support more capacity; on a
+    small corpus that bet often loses, and silently shipping the final state
+    would hand back a tower worse than the one we started from.
+    """
+    from .ctxtower import _clone_params, _load_params
+    rec = {"stages": []}
+    saved = []          # (stage, loss, alive, params, mask) for every stage
+
+    def snap(stage):
+        u = measure_utilization(model, loss_of)
+        alive = int(u["mask"].sum())
+        if verbose:
+            print(f"[{stage}] val loss {u['base_loss']:.4f} | "
+                  f"alive {alive}/{len(u['mask'])}", flush=True)
+        rec["stages"].append({"stage": stage, "loss": u["base_loss"],
+                              "alive": alive,
+                              "ablation": u["ablation"].tolist(),
+                              "mask": u["mask"].tolist()})
+        saved.append((stage, u["base_loss"], alive,
+                      _clone_params(model), u["mask"].copy()))
+        return u
+
+    snap("before")
+    if verbose:
+        print("\n== PPO reverse-attention pruning search ==", flush=True)
+    pruner = PPOPruner(model, X, loss_of, sparsity_coef=sparsity_coef, seed=seed)
+    rec["ppo_history"] = pruner.train(n_iters=ppo_iters,
+                                      episodes_per_iter=episodes_per_iter,
+                                      verbose=verbose)
+    _, probs = pruner.apply_greedy(keep_threshold)
+    rec["keep_probs"] = probs.tolist()
+    rec["reverse_attention"] = pruner.reverse_attn.tolist()
+    snap("after_apoptosis")
+
+    if finetune_epochs:
+        if verbose:
+            print("\n== re-settling survivors ==", flush=True)
+        finetune(model, loss_and_grad_fn, epochs=finetune_epochs,
+                 loss_of=loss_of)
+        snap("after_finetune")
+
+    if rebirth_fraction > 0:
+        dead = int((get_channel_mask(model) == 0.0).sum())
+        born = neurogenesis(model, int(round(rebirth_fraction * dead)), seed=seed)
+        if verbose:
+            print(f"\n== neurogenesis: {born} channels reborn ==", flush=True)
+        if born:
+            snap("after_rebirth")
+            if finetune_epochs:
+                finetune(model, loss_and_grad_fn,
+                         epochs=finetune_epochs, loss_of=loss_of)
+                snap("after_rebirth_finetune")
+
+    # ---- operating-point selection ----------------------------------------
+    # Not "lowest loss" — that rule can never prune, because the unpruned
+    # tower is usually the most accurate one and the whole exercise then
+    # returns its own input. The question a database actually asks is: what
+    # is the CHEAPEST tower I can serve without giving up measurable quality?
+    # So: take the best loss seen, allow `select_tolerance` relative slack,
+    # and among everything inside that band keep the fewest channels.
+    floor = min(s[1] for s in saved)
+    budget = floor * (1.0 + select_tolerance)
+    eligible = [s for s in saved if s[1] <= budget]
+    stage, loss, alive, params, mask = min(eligible, key=lambda s: (s[2], s[1]))
+    _load_params(model, params)
+    set_channel_mask(model, mask)
+    mx.eval(model.parameters())
+    if verbose:
+        print(f"\n== operating point: {stage} — {alive} channels, val loss "
+              f"{loss:.4f} (best seen {floor:.4f}, "
+              f"budget +{select_tolerance:.0%}) ==", flush=True)
+    rec["selected"] = {"stage": stage, "loss": loss, "channels": alive,
+                       "best_loss_seen": floor,
+                       "tolerance": select_tolerance,
+                       "candidates": [{"stage": s[0], "loss": s[1],
+                                       "channels": s[2]} for s in saved]}
+    return rec

python/elidedb/ctxtower.py

@@ -0,0 +1,554 @@
+"""The context tower — a custom SigLIP video tower over frozen frame features.
+
+WHAT IT IS
+----------
+SigLIP's image tower is a frozen spatial encoder. This module supplies the
+*other* half of an R(2+1)D-style factorisation: a learned TEMPORAL tower that
+consumes the sequence of per-frame SigLIP vectors in a window and emits one
+vector aligned with SigLIP TEXT embeddings.
+
+    frame vectors (T, 1152)          [frozen SigLIP image tower — the "2D"]
+        |  PCA  (frozen, no params)
+    (T, d)
+        |  dilated temporal conv, taps learned      ← the CNN
+        |  each output neuron = KAN sum over k
+        |  heterogeneous bases (FINER/Gabor/poly)   ← FDNN thesis 1
+    (T, n)
+        |  bi-GRU                                    ← the RNN
+    (T, 2h)
+        |  attention pooling over time
+    (2h,)
+        |  head -> PCA^T of the caption space
+    (1152,)  ~ a SigLIP text embedding
+
+WHY A CONV *AND* A GRU
+----------------------
+They fail differently, which is the only good reason to have both. The dilated
+conv is order-aware but translation-equivariant: it detects "a thing moved
+left-to-right" wherever in the window it happens, with a fixed receptive
+field. The GRU is order-aware and unbounded: it can carry "the car was
+stationary the whole time, then braked" across the window, which no
+fixed-width kernel expresses. CLIP4Clip (arXiv 2104.08860) measured exactly
+this axis on frozen CLIP features — meanP vs seqLSTM vs seqTransf — and found
+learned temporal aggregation helps once the target actually depends on order.
+Mean pooling, what `embeddings` does today, is the degenerate case of both.
+
+TSM (Lin et al., ICCV 2019) was the alternative for the conv slot: shifting
+channels along time is free. It was not used because its shift is a fixed
+±1 tap; here the whole point is that the taps are *frequency-selective*, and
+a fixed shift cannot express that.
+
+WHY THE BASES ARE THE FDNN BASES
+--------------------------------
+A window's feature trajectory is a signal, and these bases were built for
+signals. Applied after a temporal convolution:
+  - a Gabor sub-function is a temporal wavelet — a burst detector, localised
+    in time (a door opening, a brake light);
+  - a FINER sub-function is a variable-period oscillator — periodic motion
+    (gait, wipers, a turning wheel);
+  - a polynomial-phase sub-function is a chirp — monotonic acceleration
+    (a vehicle pulling away, a zoom).
+The frequency bands then partition the TEMPORAL spectrum instead of every
+neuron competing for it: slow = scene identity, mid = object motion, fast =
+transitions. Each neuron being a sum over k of these is FDNN thesis 1, and
+here it buys genuine expressiveness rather than decoration.
+
+IDENTITY-SAFE INIT
+------------------
+The head is initialised so the tower emits the mean caption vector for every
+window. That is "I know nothing" — a legal, centred prediction — so training
+can only add information, and a half-trained tower can never be worse than
+the corpus prior. Same discipline as FDNN's identity-init residual.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import mlx.core as mx
+import mlx.nn as nn
+import numpy as np
+
+
+# ===========================================================================
+# Temporal hybrid layer — FDNN's HybridBiomimeticLayer with a time axis
+# ===========================================================================
+class TemporalHybridLayer(nn.Module):
+    """Dilated temporal conv whose output channels are KAN sub-network neurons.
+
+    Shapes: (B, T, in_d) -> (B, T, max_out_d).
+
+    The convolution and the sub-function bank are fused: the conv produces
+    `max_out_d * k` pre-activations per timestep, the bases are applied
+    elementwise, and the k sub-functions of each neuron are summed (KAN).
+    So one neuron is not "a channel" — it is a little ensemble of temporal
+    filters that disagree about what shape of motion to look for.
+
+    `omega_bands` are TEMPORAL frequencies here. They are an order of
+    magnitude smaller than FDNN's coordinate-network defaults on purpose: the
+    input is a PCA of unit-norm embeddings, so |h| is O(1) rather than O(100),
+    and reusing omega=200 would put every neuron in the chaotic regime where
+    gradients are noise.
+    """
+
+    def __init__(self, in_d, max_out_d, initial_active=None, k_width=4,
+                 kernel=3, dilation=1, omega_bands=(2.0, 6.0, 18.0),
+                 band_fractions=(0.34, 0.33, 0.33), bias_range=2.0,
+                 use_residual=True, dropout_p=0.0, seed=0):
+        super().__init__()
+        rng = np.random.default_rng(seed)
+        self.in_d = in_d
+        self.max_out_d = max_out_d
+        self.k = k_width
+        self.kernel = kernel
+        self.dilation = dilation
+        self.bias_range = bias_range
+        self.use_residual = use_residual and (in_d == max_out_d)
+        self.dropout_p = dropout_p
+        self._training = True
+
+        # ---- frequency-banded omega per neuron (temporal spectrum split) ----
+        omegas = []
+        for om, fr in zip(omega_bands, band_fractions):
+            omegas.extend([om] * int(round(fr * max_out_d)))
+        omegas = (omegas + [omega_bands[-1]] * max_out_d)[:max_out_d]
+        self.omegas_per_neuron = np.array(omegas, dtype=np.float32)
+        om_exp = np.repeat(self.omegas_per_neuron, k_width)
+        self.omegas = mx.array(om_exp)
+
+        # ---- heterogeneous basis assignment: 50% FINER, 25% Gabor, 25% poly
+        half, quarter = max(k_width // 2, 1), max(k_width // 4, 1)
+        per = np.array([0] * half + [1] * quarter
+                       + [3] * max(k_width - half - quarter, 0),
+                       dtype=np.int32)[:k_width]
+        if per.size < k_width:
+            per = np.concatenate([per, np.zeros(k_width - per.size, np.int32)])
+        self.basis_types = mx.array(np.tile(per, max_out_d).astype(np.int32))
+
+        # ---- the temporal convolution: (kernel, in_d, max_out_d*k) ----------
+        # Fan-in is kernel*in_d, and the SIREN convention divides by omega so
+        # the pre-activation lands in the basis's useful range at init.
+        mean_om = float(self.omegas_per_neuron.mean())
+        limit = float(np.sqrt(6.0 / (kernel * in_d)) / mean_om)
+        self.w1 = mx.array(rng.uniform(
+            -limit, limit, (kernel, in_d, max_out_d * k_width)).astype(np.float32))
+        self.b1 = mx.array(rng.uniform(
+            -bias_range, bias_range, (max_out_d * k_width,)).astype(np.float32))
+        self.phases = mx.array(rng.uniform(
+            0, 2 * np.pi, (max_out_d * k_width,)).astype(np.float32))
+        self.gabor_s = mx.array(rng.uniform(
+            0.3, 1.5, (max_out_d * k_width,)).astype(np.float32))
+        log_om = np.log(np.clip(om_exp, 1e-3, None))
+        self.log_alpha = mx.array(
+            rng.uniform(0.0, log_om).astype(np.float32))
+
+        w2s = float(np.sqrt(6.0 / (max_out_d * k_width)))
+        self.w2 = mx.array(rng.uniform(
+            -w2s, w2s, (max_out_d, k_width)).astype(np.float32))
+
+        m = np.zeros((max_out_d,), dtype=np.float32)
+        m[:(initial_active or max_out_d)] = 1.0
+        self.mask = mx.array(m)
+
+        # basis_types is a CATEGORICAL SELECTOR, not a weight. Every mx.array
+        # attribute joins the parameter tree, so without this the optimizer
+        # takes gradient steps on it: int32 gets promoted to float32 and the
+        # values drift (measured: 1.0 -> 0.9992). Dispatch is
+        # `where(basis_types == 1, gabor, ...)`, so a drifted selector matches
+        # nothing and every Gabor neuron silently falls through to the poly
+        # branch — the heterogeneous basis quietly stops being heterogeneous.
+        # Freezing keeps it out of trainable_parameters() entirely.
+        self.freeze(keys=["basis_types"], recurse=False)
+
+    # -- temporal gather: centred taps so the window is read bidirectionally --
+    def _conv(self, x):
+        """x: (B, T, in_d) -> (B, T, max_out_d*k)."""
+        T = x.shape[1]
+        off0 = (self.kernel - 1) // 2
+        acc = None
+        for t_i in range(self.kernel):
+            shift = (t_i - off0) * self.dilation
+            if shift == 0:
+                xs = x
+            elif shift > 0:                       # look forward, edge-pad tail
+                xs = mx.concatenate(
+                    [x[:, shift:, :],
+                     mx.repeat(x[:, -1:, :], shift, axis=1)], axis=1)
+            else:                                  # look back, edge-pad head
+                s = -shift
+                xs = mx.concatenate(
+                    [mx.repeat(x[:, :1, :], s, axis=1),
+                     x[:, :T - s, :]], axis=1)
+            term = xs @ self.w1[t_i]
+            acc = term if acc is None else acc + term
+        return acc + self.b1
+
+    def _bases(self, h):
+        omega_h = self.omegas * h
+        h_sq = h * h
+        alpha = mx.exp(self.log_alpha)
+        finer = mx.sin(self.omegas * (mx.abs(h) + 1.0) * h + self.phases)
+        gabor = mx.exp(-(self.gabor_s ** 2) * h_sq) * mx.sin(omega_h + self.phases)
+        sine = mx.sin(omega_h + self.phases)
+        poly = mx.sin(alpha * h_sq + omega_h + self.phases)
+        return mx.where(self.basis_types == 0, finer,
+                        mx.where(self.basis_types == 1, gabor,
+                                 mx.where(self.basis_types == 2, sine, poly)))
+
+    def neuron_outputs(self, x):
+        """(B, T, max_out_d) per-neuron signal BEFORE mask and residual.
+        Deterministic regardless of mode — every pruning metric reads this."""
+        acts = self._bases(self._conv(x))
+        acts = acts.reshape(acts.shape[0], acts.shape[1], self.max_out_d, self.k)
+        return mx.sum(acts * self.w2, axis=-1)
+
+    def set_active_mask(self, mask_np):
+        self.mask = mx.array(np.asarray(mask_np, dtype=np.float32))
+
+    def __call__(self, x):
+        acts = self._bases(self._conv(x))
+        acts = acts.reshape(acts.shape[0], acts.shape[1], self.max_out_d, self.k)
+        if self._training and self.dropout_p > 0.0:
+            keep = 1.0 - self.dropout_p
+            drop = (mx.random.uniform(0.0, 1.0, acts.shape) < keep).astype(acts.dtype)
+            acts = acts * drop / keep
+        out = mx.sum(acts * self.w2, axis=-1) * self.mask
+        return out + x if self.use_residual else out
+
+
+# ===========================================================================
+# Attention pooling over time
+# ===========================================================================
+class AttnPool(nn.Module):
+    """Learned soft-argmax over the window.
+
+    Mean pooling says every instant matters equally, which is wrong for a
+    driving clip where 1.8 s is empty road and 0.2 s is the pedestrian
+    stepping off the kerb. Attention lets the tower spend its output on the
+    part of the window that carries the event.
+    """
+
+    def __init__(self, d, hidden=32):
+        super().__init__()
+        self.proj = nn.Linear(d, hidden)
+        self.score = nn.Linear(hidden, 1)
+
+    def __call__(self, h):                       # (B, T, d) -> (B, d)
+        a = self.score(mx.tanh(self.proj(h)))    # (B, T, 1)
+        w = mx.softmax(a, axis=1)
+        return mx.sum(h * w, axis=1), w[..., 0]
+
+
+# ===========================================================================
+# The tower
+# ===========================================================================
+class ContextTower(nn.Module):
+    def __init__(self, d_in=48, n_hidden=48, k_width=4, gru_hidden=32,
+                 d_out=32, kernel=3, dilations=(1, 2), dropout_p=0.1,
+                 input_noise_std=0.02, omega_bands=(2.0, 6.0, 18.0), seed=0):
+        super().__init__()
+        self.cfg = dict(d_in=d_in, n_hidden=n_hidden, k_width=k_width,
+                        gru_hidden=gru_hidden, d_out=d_out, kernel=kernel,
+                        dilations=list(dilations), dropout_p=dropout_p,
+                        input_noise_std=input_noise_std,
+                        omega_bands=list(omega_bands), seed=seed)
+        self.input_noise_std = input_noise_std
+        self._training = True
+
+        self.blocks = []
+        for i, dil in enumerate(dilations):
+            self.blocks.append(TemporalHybridLayer(
+                in_d=d_in if i == 0 else n_hidden,
+                max_out_d=n_hidden, k_width=k_width, kernel=kernel,
+                dilation=dil, omega_bands=omega_bands,
+                use_residual=(i > 0), dropout_p=dropout_p, seed=seed + i))
+        self.gru_f = nn.GRU(n_hidden, gru_hidden)
+        self.gru_b = nn.GRU(n_hidden, gru_hidden)
+        self.pool = AttnPool(n_hidden + 2 * gru_hidden)
+        self.head = nn.Linear(n_hidden + 2 * gru_hidden, d_out)
+        # Head starts at exactly zero: the tower's first prediction is the
+        # corpus prior (see module docstring). Bias is zero too — the prior
+        # itself is added outside, in the frozen decode basis.
+        self.head.weight = mx.zeros(self.head.weight.shape)
+        self.head.bias = mx.zeros((d_out,))
+        self.log_gamma = mx.array(np.float32(np.log(0.5)))
+
+    def set_training(self, mode: bool):
+        self._training = mode
+        for b in self.blocks:
+            b._training = mode
+        return self
+
+    def turnover_layers(self):
+        return list(self.blocks)
+
+    def trunk(self, x):
+        """(B, T, d_in) -> (B, n_hidden + 2*gru_hidden) pooled features."""
+        if self._training and self.input_noise_std > 0:
+            x = x + mx.random.normal(x.shape) * self.input_noise_std
+        h = x
+        for b in self.blocks:
+            h = b(h)
+        f = self.gru_f(h)
+        b_rev = self.gru_b(h[:, ::-1, :])[:, ::-1, :]
+        cat = mx.concatenate([h, f, b_rev], axis=-1)
+        pooled, attn = self.pool(cat)
+        # NOTE: deliberately not stashed on `self`. An mx.array assigned to a
+        # Module attribute joins the parameter tree, and the optimizer then
+        # tries to take a step on it (KeyError: 'last_attn'). Use
+        # `attention_weights()` when you want to inspect it.
+        return pooled
+
+    def attention_weights(self, x):
+        """(B, T) softmax weights — which instants the tower spent itself on."""
+        h = x
+        for b in self.blocks:
+            h = b(h)
+        f = self.gru_f(h)
+        b_rev = self.gru_b(h[:, ::-1, :])[:, ::-1, :]
+        return self.pool(mx.concatenate([h, f, b_rev], axis=-1))[1]
+
+    def __call__(self, x):
+        """-> (B, d_out) latent coordinates in the caption PCA basis."""
+        return self.head(self.trunk(x)) * mx.exp(self.log_gamma)
+
+
+# ===========================================================================
+# Codec: frozen PCA in, frozen PCA out. Zero learned parameters either side.
+# ===========================================================================
+class ContextCodec:
+    """Frozen PCA on the INPUT side of the tower.
+
+    We have a few hundred labelled windows. A learned 1152->d encoder would be
+    ~150k parameters fitted from ~150 examples, which is not learning, it is
+    memorising. PCA is the optimal linear compressor under reconstruction
+    error and costs zero training examples, so all the sample budget goes to
+    the temporal dynamics — the only part mean pooling cannot already do.
+
+    The OUTPUT side is not a PCA of SigLIP text embeddings. That was measured
+    and it lost: ranking a query against a predicted caption *embedding*
+    scored +0.218 against the VLM judge, below plain appearance search at
+    +0.276, because SigLIP is trained for image-text similarity and its text
+    tower is not calibrated for text-to-text comparison. The output space is
+    now `CaptionSpace` — LSA over the caption text itself — which measured
+    +0.339. See docs/CONTEXT.md.
+    """
+
+    def __init__(self, P_in, mu_in):
+        self.P_in, self.mu_in = P_in, mu_in       # (d_in, D), (D,)
+
+    @staticmethod
+    def fit(frame_vecs, d_in=48):
+        from sklearn.decomposition import PCA
+        d_in = min(d_in, *frame_vecs.shape)
+        pi = PCA(n_components=d_in, random_state=0).fit(frame_vecs)
+        return ContextCodec(pi.components_.astype(np.float32),
+                            pi.mean_.astype(np.float32))
+
+    def encode(self, seq):                        # (T, D) -> (T, d_in)
+        return (seq - self.mu_in) @ self.P_in.T
+
+    def save(self, path):
+        np.savez(path, P_in=self.P_in, mu_in=self.mu_in)
+
+    @staticmethod
+    def load(path):
+        z = np.load(path)
+        return ContextCodec(z["P_in"], z["mu_in"])
+
+
+# ===========================================================================
+# SigLIP's own loss
+# ===========================================================================
+def siglip_loss(v, u, ignore=None, log_t=None, bias=None):
+    """Pairwise sigmoid loss (Zhai et al., ICCV 2023, arXiv 2303.15343).
+
+    Chosen over softmax-InfoNCE for one concrete reason: the paper's own
+    ablation shows sigmoid wins below ~16k batch, and our batch is the whole
+    labelled set — a couple of hundred. Softmax normalises over the batch, so
+    at this size the partition function is estimated from almost nothing.
+    Sigmoid treats every pair as an independent binary problem and never
+    needs that global view.
+
+    `ignore` masks pairs that must not be counted as negatives. Windows slide
+    with 75% overlap, so window i+1 genuinely depicts the same moment as
+    window i; calling it a negative would teach the tower to separate
+    identical content. Those pairs are dropped, not down-weighted.
+    """
+    t = mx.exp(log_t)
+    logits = t * (v @ u.T) + bias
+    n = v.shape[0]
+    y = 2.0 * mx.eye(n) - 1.0                     # +1 diagonal, -1 elsewhere
+    z = y * logits
+    # -log sigmoid(z) == softplus(-z), stable for both signs
+    per_pair = nn.softplus(-z)
+    if ignore is not None:
+        keep = 1.0 - ignore
+        return mx.sum(per_pair * keep) / mx.maximum(mx.sum(keep), 1.0)
+    return mx.mean(per_pair)
+
+
+def overlap_mask(windows):
+    """1.0 where two windows are the same stream and overlap in time."""
+    n = len(windows)
+    m = np.zeros((n, n), dtype=np.float32)
+    st = [w[0] for w in windows]
+    t0 = np.array([w[1] for w in windows], dtype=np.int64)
+    t1 = np.array([w[2] for w in windows], dtype=np.int64)
+    for i in range(n):
+        same = np.array([s == st[i] for s in st])
+        ov = same & (t0 < t1[i]) & (t1 > t0[i])
+        m[i] = ov.astype(np.float32)
+    np.fill_diagonal(m, 0.0)                      # the positive stays a positive
+    return m
+
+
+# ===========================================================================
+# Training
+# ===========================================================================
+def train_tower(seqs, targets, windows, val_idx, cfg=None, epochs=400,
+                lr=3e-3, weight_decay=1e-3, align_w=0.3, verbose=True,
+                seed=0):
+    """Fit the tower. `seqs` are (T, d_in) encoded sequences, `targets` are
+    (d_out,) caption coordinates in the output basis, both already codec-mapped.
+
+    Returns (model, history). Validation is a TIME split supplied by the
+    caller — never a random split, because 75%-overlapping windows would put
+    near-duplicates on both sides and report a fantasy score.
+    """
+    import mlx.optimizers as optim
+    cfg = cfg or {}
+    mx.random.seed(seed)
+    model = ContextTower(**cfg)
+
+    T = max(s.shape[0] for s in seqs)
+    X = np.zeros((len(seqs), T, seqs[0].shape[1]), dtype=np.float32)
+    for i, s in enumerate(seqs):                  # edge-pad short windows
+        X[i, :len(s)] = s
+        if len(s) < T:
+            X[i, len(s):] = s[-1]
+    Y = np.asarray(targets, dtype=np.float32)
+
+    val = np.zeros(len(seqs), dtype=bool)
+    val[val_idx] = True
+    tr = ~val
+    Xtr, Ytr = mx.array(X[tr]), mx.array(Y[tr])
+    Xva, Yva = mx.array(X[val]), mx.array(Y[val])
+    ig_tr = mx.array(overlap_mask([w for w, m in zip(windows, tr) if m]))
+    ig_va = mx.array(overlap_mask([w for w, m in zip(windows, val) if m]))
+
+    # logit scale/bias are learned, initialised as in the SigLIP paper
+    state = {"log_t": mx.array(np.float32(np.log(10.0))),
+             "bias": mx.array(np.float32(-10.0))}
+
+    def _norm(a):
+        # eps INSIDE the sqrt, not added to the norm afterwards. The head is
+        # zero-initialised on purpose, so the very first forward pass produces
+        # an exactly-zero vector — and d||x||/dx = x/||x|| is 0/0 = NaN there.
+        # Smoothing the radicand keeps the gradient finite at the origin.
+        return a * mx.rsqrt(mx.sum(a * a, axis=-1, keepdims=True) + 1e-8)
+
+    def loss_fn(m, x, y, ig):
+        v = _norm(m(x))
+        u = _norm(y)
+        # alignment term: pull each prediction onto its own caption. The
+        # contrastive term only fixes ORDER; this one fixes absolute position,
+        # which is what makes the vectors usable against unseen query text.
+        align = mx.mean(1.0 - mx.sum(v * u, axis=-1))
+        return siglip_loss(v, u, ignore=ig, log_t=state["log_t"],
+                           bias=state["bias"]) + align_w * align
+
+    opt = optim.AdamW(learning_rate=lr, weight_decay=weight_decay)
+    lg = nn.value_and_grad(model, loss_fn)
+    sopt = optim.Adam(learning_rate=lr)
+
+    def state_loss(s):
+        model.set_training(False)
+        v = _norm(model(Xtr))
+        return siglip_loss(v, _norm(Ytr), ignore=ig_tr,
+                           log_t=s["log_t"], bias=s["bias"])
+
+    # The aliveness masks are mx.array attributes, so they live in
+    # model.parameters() and AdamW would happily weight-decay them off their
+    # 0/1 values — silently rescaling every neuron and breaking the
+    # `mask == 1.0` alive-check the pruner depends on. Snapshot and restore
+    # after every step. (FDNN hit exactly this; it is not hypothetical.)
+    frozen_masks = [np.array(l.mask).copy() for l in model.turnover_layers()]
+
+    hist = {"train": [], "val": [], "val_r1": []}
+    best, best_w, best_state = 1e9, None, None
+    for ep in range(epochs):
+        model.set_training(True)
+        loss, grads = lg(model, Xtr, Ytr, ig_tr)
+        opt.update(model, grads)
+        for lyr, fm in zip(model.turnover_layers(), frozen_masks):
+            lyr.mask = mx.array(fm)
+        sl, sg = mx.value_and_grad(state_loss)(state)
+        state = sopt.apply_gradients(sg, state)   # plain dict, not a Module
+        mx.eval(model.parameters(), opt.state, state)
+
+        model.set_training(False)
+        vl = float(loss_fn(model, Xva, Yva, ig_va).item())
+        r1 = retrieval_r1(np.array(_norm(model(Xva))), np.array(_norm(Yva)))
+        hist["train"].append(float(loss.item()))
+        hist["val"].append(vl)
+        hist["val_r1"].append(r1)
+        if vl < best:
+            best, best_w = vl, _clone_params(model)
+            best_state = {k: mx.array(np.array(v)) for k, v in state.items()}
+        if verbose and (ep % 50 == 0 or ep == epochs - 1):
+            print(f"  ep {ep:4d} train {float(loss.item()):.4f} "
+                  f"val {vl:.4f} val_R@1 {r1:.3f}", flush=True)
+    if best_w is not None:
+        _load_params(model, best_w)
+        state = best_state
+    model.set_training(False)
+    return model, {"history": hist, "best_val": best,
+                   "log_t": float(state["log_t"].item()),
+                   "bias": float(state["bias"].item())}
+
+
+def retrieval_r1(v, u):
+    """Fraction of windows whose own caption is its nearest caption.
+
+    This is the metric that matters: not "is the vector close to the target"
+    but "does the vector RANK the right target first" — the same question the
+    query path asks.
+    """
+    if len(v) < 2:
+        return float("nan")
+    s = v @ u.T
+    return float((s.argmax(axis=1) == np.arange(len(v))).mean())
+
+
+def _clone_params(model):
+    from mlx.utils import tree_flatten
+    return {k: np.array(v) for k, v in tree_flatten(model.parameters())}
+
+
+def _load_params(model, flat):
+    from mlx.utils import tree_unflatten
+    model.update(tree_unflatten([(k, mx.array(v)) for k, v in flat.items()]))
+
+
+def save_tower(model, codec, meta, path):
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    np.savez(path / "tower.npz", **_clone_params(model))
+    codec.save(path / "codec.npz")
+    # model.cfg goes LAST and wins. `meta` is often a carried-forward copy of
+    # a previous tower.json and still holds that tower's cfg; letting it
+    # override would save compacted weights under the pre-compaction shape,
+    # and the next load would reshape-crash.
+    (path / "tower.json").write_text(json.dumps(
+        {**meta, "cfg": model.cfg}, indent=2))
+
+
+def load_tower(path):
+    path = Path(path)
+    meta = json.loads((path / "tower.json").read_text())
+    model = ContextTower(**meta["cfg"])
+    z = np.load(path / "tower.npz")
+    _load_params(model, {k: z[k] for k in z.files})
+    model.set_training(False)
+    return model, ContextCodec.load(path / "codec.npz"), meta

python/elidedb/data/ssv2_classes.txt

@@ -0,0 +1,174 @@
+Approaching something with your camera
+Attaching something to something
+Bending something so that it deforms
+Bending something until it breaks
+Burying something in something
+Closing something
+Covering something with something
+Digging something out of something
+Dropping something behind something
+Dropping something in front of something
+Dropping something into something
+Dropping something next to something
+Dropping something onto something
+Failing to put something into something because something does not fit
+Folding something
+Hitting something with something
+Holding something
+Holding something behind something
+Holding something in front of something
+Holding something next to something
+Holding something over something
+Laying something on the table on its side, not upright
+Letting something roll along a flat surface
+Letting something roll down a slanted surface
+Letting something roll up a slanted surface, so it rolls back down
+Lifting a surface with something on it but not enough for it to slide down
+Lifting a surface with something on it until it starts sliding down
+Lifting something up completely without letting it drop down
+Lifting something up completely, then letting it drop down
+Lifting something with something on it
+Lifting up one end of something without letting it drop down
+Lifting up one end of something, then letting it drop down
+Moving away from something with your camera
+Moving part of something
+Moving something across a surface until it falls down
+Moving something across a surface without it falling down
+Moving something and something away from each other
+Moving something and something closer to each other
+Moving something and something so they collide with each other
+Moving something and something so they pass each other
+Moving something away from something
+Moving something away from the camera
+Moving something closer to something
+Moving something down
+Moving something towards the camera
+Moving something up
+Opening something
+Picking something up
+Piling something up
+Plugging something into something
+Plugging something into something but pulling it right out as you remove your hand
+Poking a hole into some substance
+Poking a hole into something soft
+Poking a stack of something so the stack collapses
+Poking a stack of something without the stack collapsing
+Poking something so it slightly moves
+Poking something so lightly that it doesn't or almost doesn't move
+Poking something so that it falls over
+Poking something so that it spins around
+Pouring something into something
+Pouring something into something until it overflows
+Pouring something onto something
+Pouring something out of something
+Pretending or failing to wipe something off of something
+Pretending or trying and failing to twist something
+Pretending to be tearing something that is not tearable
+Pretending to close something without actually closing it
+Pretending to open something without actually opening it
+Pretending to pick something up
+Pretending to poke something
+Pretending to pour something out of something, but something is empty
+Pretending to put something behind something
+Pretending to put something into something
+Pretending to put something next to something
+Pretending to put something on a surface
+Pretending to put something onto something
+Pretending to put something underneath something
+Pretending to scoop something up with something
+Pretending to spread air onto something
+Pretending to sprinkle air onto something
+Pretending to squeeze something
+Pretending to take something from somewhere
+Pretending to take something out of something
+Pretending to throw something
+Pretending to turn something upside down
+Pulling something from behind of something
+Pulling something from left to right
+Pulling something from right to left
+Pulling something onto something
+Pulling something out of something
+Pulling two ends of something but nothing happens
+Pulling two ends of something so that it gets stretched
+Pulling two ends of something so that it separates into two pieces
+Pushing something from left to right
+Pushing something from right to left
+Pushing something off of something
+Pushing something onto something
+Pushing something so it spins
+Pushing something so that it almost falls off but doesn't
+Pushing something so that it falls off the table
+Pushing something so that it slightly moves
+Pushing something with something
+Putting number of something onto something
+Putting something and something on the table
+Putting something behind something
+Putting something in front of something
+Putting something into something
+Putting something next to something
+Putting something on a flat surface without letting it roll
+Putting something on a surface
+Putting something on the edge of something so it is not supported and falls down
+Putting something onto a slanted surface but it doesn't glide down
+Putting something onto something
+Putting something onto something else that cannot support it so it falls down
+Putting something similar to other things that are already on the table
+Putting something that can't roll onto a slanted surface, so it slides down
+Putting something that can't roll onto a slanted surface, so it stays where it is
+Putting something that cannot actually stand upright upright on the table, so it falls on its side
+Putting something underneath something
+Putting something upright on the table
+Putting something, something and something on the table
+Removing something, revealing something behind
+Rolling something on a flat surface
+Scooping something up with something
+Showing a photo of something to the camera
+Showing something behind something
+Showing something next to something
+Showing something on top of something
+Showing something to the camera
+Showing that something is empty
+Showing that something is inside something
+Something being deflected from something
+Something colliding with something and both are being deflected
+Something colliding with something and both come to a halt
+Something falling like a feather or paper
+Something falling like a rock
+Spilling something behind something
+Spilling something next to something
+Spilling something onto something
+Spinning something so it continues spinning
+Spinning something that quickly stops spinning
+Spreading something onto something
+Sprinkling something onto something
+Squeezing something
+Stacking number of something
+Stuffing something into something
+Taking one of many similar things on the table
+Taking something from somewhere
+Taking something out of something
+Tearing something into two pieces
+Tearing something just a little bit
+Throwing something
+Throwing something against something
+Throwing something in the air and catching it
+Throwing something in the air and letting it fall
+Throwing something onto a surface
+Tilting something with something on it slightly so it doesn't fall down
+Tilting something with something on it until it falls off
+Tipping something over
+Tipping something with something in it over, so something in it falls out
+Touching (without moving) part of something
+Trying but failing to attach something to something because it doesn't stick
+Trying to bend something unbendable so nothing happens
+Trying to pour something into something, but missing so it spills next to it
+Turning something upside down
+Turning the camera downwards while filming something
+Turning the camera left while filming something
+Turning the camera right while filming something
+Turning the camera upwards while filming something
+Twisting (wringing) something wet until water comes out
+Twisting something
+Uncovering something
+Unfolding something
+Wiping something off of something

python/elidedb/derive.py

@@ -0,0 +1,148 @@
+"""Corpus-derived replacements for hand-authored constants.
+
+Every function here answers a question the code used to answer with a
+literal. The rule they serve: nothing in code may encode what the data
+CONTAINS or what the task IS. A constant is legitimate when it is a
+tuning dial measured on the corpus or a property of a model; it is a
+violation when it is a fact about the domain, because then the system is
+being told the answer rather than recognising it.
+
+The replacements have to work for any physical-AI corpus, not just this
+one. A table-top manipulation set, a driving log and a warehouse camera
+have nothing in common at the level of "open" or "put_into" - but they
+all have objects that move, appear, vanish, approach and separate, and
+those are measurable without naming anything.
+
+WHAT WAS REPLACED
+-----------------
+    MIN_BLOB = 120 (and 40, 60, 60, 30 elsewhere)  -> fit_cut on the
+        observed blob-area distribution, in frame fractions so the
+        number transfers across resolutions.
+    REL_MIN / CAV_MIN thresholds                    -> fit_cut, or gone
+        entirely where the quantity feeds clustering instead of an
+        if/else.
+    hand-listed vocabularies                        -> attested(), words
+        the corpus actually produced.
+    hand-listed antonym pairs                       -> opposite_pairs(),
+        found by reflection in an embedding space.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def fit_cut(values, q=None, mode="knee"):
+    """A threshold from the data instead of from a keyboard.
+
+    mode="knee"     the largest gap in the sorted values - where the
+                    distribution itself separates, if it does.
+    mode="quantile" the q-th percentile, for "tighter than all but q% of
+                    what I can prove is background".
+    mode="otsu"     the between-class variance maximiser, for a
+                    distribution with two modes and no prior on where
+                    the split sits.
+
+    Returns (cut, diagnostics). The diagnostics matter: a knee found in
+    a unimodal distribution is an artefact, and `separation` says so, so
+    a caller can refuse to threshold a quantity that has no structure.
+    """
+    v = np.asarray(values, np.float64)
+    v = v[np.isfinite(v)]
+    if len(v) < 8:
+        return None, {"reason": "too few samples", "n": int(len(v))}
+    s = np.sort(v)
+    if mode == "quantile":
+        cut = float(np.percentile(s, q if q is not None else 99.0))
+    elif mode == "otsu":
+        hist, edges = np.histogram(s, bins=min(256, max(16, len(s) // 8)))
+        p = hist / hist.sum()
+        c = np.cumsum(p)
+        m = np.cumsum(p * np.arange(len(p)))
+        mt = m[-1]
+        with np.errstate(invalid="ignore", divide="ignore"):
+            var = (mt * c - m) ** 2 / (c * (1 - c))
+        i = int(np.nanargmax(var))
+        cut = float(edges[i + 1])
+    else:
+        # knee: the widest gap between consecutive order statistics,
+        # ignoring the extreme tails where single outliers dominate
+        lo, hi = int(0.05 * len(s)), int(0.95 * len(s))
+        seg = s[lo:hi]
+        if len(seg) < 4:
+            return float(np.median(s)), {"reason": "degenerate", "n": len(s)}
+        gaps = np.diff(seg)
+        i = int(np.argmax(gaps))
+        cut = float((seg[i] + seg[i + 1]) / 2)
+    below, above = s[s <= cut], s[s > cut]
+    sep = 0.0
+    if len(below) and len(above):
+        spread = s.std() + 1e-12
+        sep = float((above.mean() - below.mean()) / spread)
+    return cut, {"n": int(len(s)), "cut": cut, "separation": round(sep, 3),
+                 "frac_below": round(float(len(below) / len(s)), 3),
+                 "mode": mode}
+
+
+def attested(texts, min_count=2, max_frac=0.5):
+    """Vocabulary the CORPUS produced, not a list someone typed.
+
+    Drops words too rare to be a category and words so common they
+    cannot discriminate. No stopword list: "the" is excluded because it
+    appears in most documents, which is a measurement, not an opinion
+    about English.
+    """
+    from collections import Counter
+    docs = [str(t).lower().split() for t in texts if t]
+    if not docs:
+        return []
+    df = Counter()
+    for d in docs:
+        df.update(set(d))
+    n = len(docs)
+    return sorted(w for w, c in df.items()
+                  if c >= min_count and c / n <= max_frac and w.isalpha())
+
+
+def opposite_pairs(words, vec, top=1, min_sim=0.25):
+    """Antonyms by REFLECTION, not by a table of 81 hand-written pairs.
+
+    In an embedding space trained on natural text, an antonym pair tends
+    to be the two ends of one axis: a and b are close in topic and
+    opposed in direction once their shared component is removed. So for
+    each word, remove the corpus mean, and look for the word whose
+    residual points most nearly the other way.
+
+    This finds whatever oppositions the corpus has. On a driving log it
+    would find accelerate/brake without anyone having thought of them;
+    on this one it finds open/close. That is the whole point - the
+    system stops depending on someone having anticipated the domain.
+    """
+    W = [w for w in words if w]
+    if len(W) < 4:
+        return []
+    V = np.stack([vec(w) for w in W]).astype(np.float32)
+    V = V - V.mean(0)                       # the shared component is topic
+    V /= np.linalg.norm(V, axis=1, keepdims=True) + 1e-8
+    S = V @ V.T
+    np.fill_diagonal(S, 0.0)
+    out, seen = [], set()
+    for i, w in enumerate(W):
+        j = int(np.argmin(S[i]))            # most opposed residual
+        if S[i, j] > -min_sim:
+            continue
+        key = tuple(sorted((i, j)))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append((w, W[j], round(float(-S[i, j]), 3)))
+    return sorted(out, key=lambda r: -r[2])[:max(top * len(W), 1)]
+
+
+def frame_fraction(px, width, height):
+    """Pixel counts are resolution-specific; fractions are not.
+
+    MIN_BLOB=120 meant one thing at 640x480 and something else at
+    256x256, which is why five files carried five different values for
+    the same idea.
+    """
+    return float(px) / float(max(width * height, 1))

python/elidedb/desk.py

@@ -0,0 +1,1723 @@
+#!/usr/bin/env python3
+"""ElideDB Desk — local database browser (the Atlas/Compass role).
+
+Zero-dependency server: stdlib http.server + the elidedb package. All state
+lives in the stores themselves; Desk only reads. Thumbnails are decoded on
+demand through the same byte-range path queries use — nothing is pre-baked,
+so every embedded window can always show its frame.
+
+  elidedb desk [--root lake] [--port 8787] [--open]
+"""
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import os
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+ROOT = Path.cwd()
+
+import numpy as np  # noqa: E402
+from elidedb import Store  # noqa: E402
+
+STORES: dict[str, Store] = {}
+LAKE = ROOT / "lake"
+_CACHE: dict = {}
+import os  # noqa: E402
+READONLY = os.environ.get("DESK_READONLY", "") == "1"
+
+
+def discover():
+    STORES.clear()
+    if LAKE.is_dir():
+        for p in sorted(LAKE.iterdir()):
+            if (p / "_store.json").exists():
+                try:
+                    STORES[p.name] = Store.open(p)
+                except Exception:
+                    pass
+
+
+def _covered_seconds(db, desc):
+    """Recorded CONTENT time: the union of row-group ts ranges of the
+    frame tables, from parquet footers only. Extent (max minus min) lies
+    on sparse stores; a store holding three hours of episodes spread
+    over three days of wall clock covers three hours, not three days."""
+    import pyarrow.parquet as pq
+    frame_tabs = [d["table"] for d in desc
+                  if d["kind"] == "frame_index" and d["rows"]]
+    if not frame_tabs:
+        frame_tabs = [d["table"] for d in desc
+                      if d["table"] == "frames" and d["rows"]]
+    # exact when available: every ingest commit recorded its fps, and
+    # frame count over fps is the recorded duration regardless of how
+    # the rows pack into row groups
+    total_s = 0.0
+    exact = False
+    for name in frame_tabs:
+        try:
+            for c in db.table(name).history():
+                m = c.get("meta") or {}
+                fps = m.get("fps")
+                if fps and c.get("added_rows"):
+                    total_s += c["added_rows"] / float(fps)
+                    exact = True
+        except Exception:
+            continue
+    if exact:
+        return total_s
+    # episode-organized stores: the episodes table IS the content list
+    if any(d["table"] == "episodes" and d["rows"] for d in desc):
+        try:
+            t = db.table("episodes").scan(columns=["ts", "t1"])
+            a = t.column("ts").to_numpy()
+            b = t.column("t1").to_numpy()
+            return float((b - a).sum() / 1e9)
+        except Exception:
+            pass
+    spans = []
+    for name in frame_tabs:
+        try:
+            st = db.table(name).state()
+            for f in st.files:
+                pf = pq.ParquetFile(db.dir / "tables" / name / f.path)
+                md = pf.metadata
+                names = md.schema.names
+                if "ts" not in names:
+                    continue
+                ti = names.index("ts")
+                for g in range(md.num_row_groups):
+                    s = md.row_group(g).column(ti).statistics
+                    if s and s.min is not None:
+                        spans.append((int(s.min), int(s.max)))
+        except Exception:
+            continue
+    if not spans:
+        return None
+    spans.sort()
+    total, cur_a, cur_b = 0, spans[0][0], spans[0][1]
+    for a, b in spans[1:]:
+        if a > cur_b:
+            total += cur_b - cur_a
+            cur_a, cur_b = a, b
+        else:
+            cur_b = max(cur_b, b)
+    total += cur_b - cur_a
+    return total / 1e9
+
+
+def _raw_source_bytes(db, desc):
+    """Bytes of the ORIGINAL ingested sources, from the ingest metadata
+    each append recorded. This is the honest numerator of the
+    compression story; a missing original is reported as unknown, not
+    guessed."""
+    originals = set()
+    for d in desc:
+        if d["kind"] != "frame_index" and d["table"] != "frames":
+            continue
+        try:
+            for c in db.table(d["table"]).history():
+                o = (c.get("meta") or {}).get("original")
+                if o:
+                    originals.add(o)
+        except Exception:
+            continue
+    known = missing = 0
+    total = 0
+    for o in originals:
+        p = Path(o)
+        if p.exists():
+            total += p.stat().st_size
+            known += 1
+        else:
+            missing += 1
+    return {"bytes": total, "files": known, "missing": missing}
+
+
+def store_summary(key: str):
+    db = STORES[key]
+    desc = db.describe()
+    ck = ("summary", key,
+          tuple(sorted((d["table"], d["version"]) for d in desc)))
+    if ck in _CACHE:
+        return _CACHE[ck]
+    total_rows = sum(d["rows"] for d in desc)
+    total_bytes = sum(d["bytes"] for d in desc)
+    span_tabs = [d for d in desc if d["rows"] and d["table"] != "centroids"]
+    lo = min((d["min_ts"] for d in span_tabs), default=0)
+    hi = max((d["max_ts"] for d in span_tabs), default=0)
+    emb = next((d for d in desc if d["table"] == "embeddings"), None)
+    # PHYSICAL directory bytes (lstat): a symlink is a path entry, not
+    # the target's bytes. Media reached through symlinks is counted as
+    # linked_bytes instead, because the store STOPS WORKING if those
+    # targets go away, and the standalone claim must be earned.
+    media_bytes = linked_bytes = 0
+    mdir = db.dir / "media"
+    if mdir.is_dir():
+        for p in mdir.glob("*"):
+            if p.is_symlink():
+                try:
+                    linked_bytes += p.stat().st_size
+                except OSError:
+                    pass
+            elif p.is_file():
+                media_bytes += p.lstat().st_size
+    db_bytes = sum(p.lstat().st_size for p in db.dir.rglob("*")
+                   if p.is_file() and not p.is_symlink())
+    external_bytes = 0
+    for d in desc:
+        if d["kind"] != "frame_index":
+            continue
+        t = db.table(d["table"]).scan(columns=["source"])
+        for s in set(t.column("source").to_pylist()):
+            if not s.startswith("@") and Path(s).exists():
+                external_bytes += Path(s).stat().st_size
+    raw = _raw_source_bytes(db, desc)
+    vec_rows = sum(d["rows"] for d in desc if d["kind"] == "embeddings")
+    vec_tables = sum(1 for d in desc
+                     if d["kind"] == "embeddings" and d["rows"])
+    out = {
+        "key": key, "name": db.name, "path": str(db.dir),
+        "tables": desc, "rows": total_rows, "bytes": total_bytes,
+        "db_bytes": db_bytes, "media_bytes": media_bytes,
+        "emb_bytes": emb["bytes"] if emb else 0,
+        "external_bytes": external_bytes,
+        "linked_bytes": linked_bytes,
+        "standalone": external_bytes == 0 and linked_bytes == 0,
+        "raw_bytes": raw["bytes"], "raw_files": raw["files"],
+        "raw_missing": raw["missing"],
+        "covered_s": _covered_seconds(db, desc),
+        "min_ts": lo, "max_ts": hi,
+        "windows": emb["rows"] if emb else 0,
+        "vec_rows": vec_rows, "vec_tables": vec_tables,
+        "model": (emb or {}).get("meta", {}).get("model", ""),
+        "display": db.meta.get("display", {}),
+    }
+    if len(_CACHE) > 32:
+        _CACHE.clear()
+    _CACHE[ck] = out
+    return out
+
+
+def api_storage(key: str, table: str):
+    """The Parquet format, made visible: this table's commit log plus every
+    active file's row-group layout straight from the Parquet footers."""
+    import pyarrow.parquet as pq
+    db = STORES[key]
+    tab = db.table(table)
+    st = tab.state()
+    files = []
+    for f in st.files:
+        pf = pq.ParquetFile(db.dir / "tables" / table / f.path)
+        md = pf.metadata
+        names = md.schema.names
+        ts_i = names.index("ts") if "ts" in names else 0
+        rgs = []
+        for g in range(md.num_row_groups):
+            rg = md.row_group(g)
+            s = rg.column(ts_i).statistics
+            rgs.append({"rows": rg.num_rows,
+                        "bytes": sum(rg.column(c).total_compressed_size
+                                     for c in range(rg.num_columns)),
+                        "min_ts": s.min if s else None,
+                        "max_ts": s.max if s else None})
+        files.append({"name": f.path, "bytes": f.bytes, "rows": f.rows,
+                      "min_ts": f.min_ts, "max_ts": f.max_ts,
+                      "footer_bytes": md.serialized_size,
+                      "columns": names, "row_groups": rgs})
+    return {"table": table, "kind": st.kind, "version": st.version,
+            "schema": st.schema, "history": tab.history(), "files": files}
+
+
+MAP_MAX_POINTS = 6000
+
+
+def api_map(key: str):
+    """2D layout of the embeddings table. UMAP over a bounded SAMPLE,
+    cached beside the log (a derived view; never used for retrieval).
+
+    The unsampled version killed the app at pilot scale, three ways at
+    once (measured on the 100 h store): to_pylist() over 180k x 1152
+    vectors is ~25 GB of Python floats (4 -> 28 GB RSS), UMAP over 180k
+    points runs for minutes, and a 180k-point JSON payload crushes the
+    WebView. A map is an OVERVIEW: an even time-stride sample of a few
+    thousand windows shows the same structure, reads from the mmap
+    sidecar, and stays bounded no matter how large the corpus grows."""
+    ck = ("map", key)
+    if ck in _CACHE:
+        return _CACHE[ck]
+    db = STORES[key]
+    from elidedb.embeddings import _vec_table
+    try:
+        t, vecs = _vec_table(db, "embeddings")
+    except Exception:
+        return {"points": []}
+    n = len(t)
+    if n == 0:
+        return {"points": []}
+    stride = max(1, n // MAP_MAX_POINTS)
+    idx = np.arange(0, n, stride)
+    sample = np.asarray(vecs[idx], np.float32)
+
+    cache_file = db.dir / "tables" / "embeddings" / "_desk_umap.json"
+    st = db.table("embeddings").state()
+    xy = None
+    if cache_file.exists():
+        c = json.loads(cache_file.read_text())
+        if c.get("version") == st.version and len(c["xy"]) == len(idx):
+            xy = np.array(c["xy"], np.float32)
+    if xy is None:
+        try:
+            import umap
+            from sklearn.decomposition import PCA
+            red = PCA(n_components=min(50, len(sample), sample.shape[1]),
+                      random_state=0).fit_transform(sample)
+            xy = umap.UMAP(n_components=2, random_state=0,
+                           low_memory=True).fit_transform(red)
+        except Exception:
+            from sklearn.decomposition import PCA
+            xy = PCA(n_components=2, random_state=0).fit_transform(sample)
+        cache_file.write_text(json.dumps(
+            {"version": st.version, "xy": np.round(xy, 3).tolist()}))
+    labels = (t.column("cluster").to_pylist()
+              if "cluster" in t.column_names else None)
+    # NO cluster column: every point got c=0 and the map was one flat
+    # colour with a legend reading "cluster 0 · 3891" - information-free.
+    # Cluster the 2D LAYOUT for display, cached beside the UMAP cache.
+    # DISPLAY ONLY, and the UI says so: UMAP preserves neighbourhoods,
+    # not distances, so these coordinates never touch a retrieval
+    # decision - that rule is why the store has no cluster column in the
+    # first place.
+    kmeans_display = False
+    if labels is None and len(xy) >= 24:
+        kc = db.dir / "tables" / "embeddings" / "_desk_kmeans.json"
+        got = None
+        if kc.exists():
+            try:
+                j = json.loads(kc.read_text())
+                if j.get("version") == st.version and len(j["lab"]) == n:
+                    got = j["lab"]
+            except Exception:
+                got = None
+        if got is None:
+            P = np.asarray(xy, np.float32)
+            K = min(10, max(2, len(P) // 40))
+            rng = np.random.default_rng(0)
+            C = P[rng.choice(len(P), K, replace=False)]
+            for _ in range(25):                     # Lloyd, few rounds
+                d2 = ((P[:, None, :] - C[None]) ** 2).sum(-1)
+                a = d2.argmin(1)
+                for k in range(K):
+                    m = a == k
+                    if m.any():
+                        C[k] = P[m].mean(0)
+            sub = a.astype(int).tolist()
+            got = [0] * n
+            for j, i in enumerate(idx):
+                got[i] = sub[j]
+            try:
+                kc.write_text(json.dumps({"version": st.version,
+                                          "lab": got}))
+            except Exception:
+                pass
+        labels = got
+        kmeans_display = True
+    ss = t.column("stream").to_pylist()
+    ta = t.column("ts").to_pylist()
+    tb = t.column("t1").to_pylist()
+    out = {"points": [
+        {"x": float(xy[j][0]), "y": float(xy[j][1]),
+         "c": int(labels[i]) if labels else 0,
+         "s": ss[i], "t0": ta[i], "t1": tb[i]}
+        for j, i in enumerate(idx)],
+        "sampled_of": n, "stride": int(stride),
+        "cluster_source": ("stored cluster column" if not kmeans_display
+                           else "k-means over the 2D layout — DISPLAY "
+                                "ONLY, never a retrieval decision")}
+    _CACHE[ck] = out
+    return out
+
+
+def api_architecture(key: str):
+    """The store as a living schematic: every node and edge derived from
+    what is ACTUALLY on disk — parquet footers for schemas, _meta.json for
+    state, table meta for lineage, _cache for mmap sidecars. Nothing here
+    is drawn from documentation; a table that vanished vanishes from the
+    drawing, a channel appears the moment its table exists."""
+    import pyarrow.parquet as _pq
+    db = STORES[key]
+    nodes, edges = [], []
+
+    def table_node(name):
+        tab = db.table(name)
+        try:
+            st = tab.state()
+        except Exception:
+            return None
+        if not st.files:
+            return None
+        meta_json = {}
+        mf = tab.dir / "_meta.json"
+        if mf.exists():
+            try:
+                meta_json = json.loads(mf.read_text())
+            except Exception:
+                pass
+        fields = []
+        try:
+            sch = _pq.ParquetFile(tab.dir / st.files[0].path).schema_arrow
+            for f in sch:
+                t = str(f.type)
+                t = t.replace("fixed_size_list<item: float>", "f32vec")
+                fields.append({"name": f.name, "type": t})
+        except Exception:
+            pass
+        sidecars = sorted(p.name for p in (tab.dir / "_cache").glob("*.npy")) \
+            if (tab.dir / "_cache").is_dir() else []
+        rows = sum(f.rows for f in st.files)
+        return {"id": name, "kind": st.kind, "rows": rows,
+                "bytes": sum(f.bytes for f in st.files),
+                "files": len(st.files), "version": st.version,
+                "min_ts": min((f.min_ts for f in st.files), default=None),
+                "max_ts": max((f.max_ts for f in st.files), default=None),
+                "fields": fields, "meta": st.meta or {},
+                "meta_json": bool(meta_json), "sidecars": sidecars}
+
+    names = db.tables()
+    for n in names:
+        nd = table_node(n)
+        if nd:
+            nodes.append(nd)
+    have = {n["id"] for n in nodes}
+
+    # media + models are first-class citizens of the drawing
+    mdir = db.dir / "media"
+    if mdir.is_dir():
+        fs = list(mdir.glob("*"))
+        nodes.append({"id": "media", "kind": "media",
+                      "rows": len(fs),
+                      "bytes": sum(f.stat().st_size for f in fs
+                                   if f.is_file()),
+                      "files": len(fs), "fields": [], "meta": {},
+                      "note": "transcoded H.264, byte-range decoded"})
+    for m in sorted((db.dir / "models").glob("*")) \
+            if (db.dir / "models").is_dir() else []:
+        if m.is_dir():
+            nodes.append({"id": f"model:{m.name}", "kind": "model",
+                          "bytes": sum(f.stat().st_size
+                                       for f in m.rglob("*") if f.is_file()),
+                          "fields": [], "meta": {},
+                          "rows": None, "files": None})
+
+    # lineage: explicit table meta first, then structural conventions
+    def edge(a, b, label):
+        if a in have or a in ("media", "SOURCE", "QUERIES") or \
+                a.startswith("model:"):
+            edges.append({"from": a, "to": b, "label": label})
+    for n in nodes:
+        meta, nid = n.get("meta", {}), n["id"]
+        if meta.get("source_table"):
+            edge(meta["source_table"], nid,
+                 meta.get("built_by", "derived"))
+        if meta.get("events_table"):
+            edge(meta["events_table"], nid, "spans")
+        if meta.get("teacher"):
+            edge("frames", nid, meta.get("model", "encoder"))
+    conventions = {
+        "frame_vectors": ("frames", "encoder, every frame"),
+        "object_vectors": ("frames", "FastSAM regions + crops"),
+        "context_captions": ("frames", "VLM captions"),
+        "context_events": ("frames", "gate segmentation"),
+        "vlm_verdicts": ("frames", "2B/7B judgments"),
+        "frames": ("media", "frame index"),
+    }
+    done = {(e["from"], e["to"]) for e in edges}
+    for nid, (src, lab) in conventions.items():
+        if nid in have and (src, nid) not in done and \
+                (src in have or src == "media"):
+            edges.append({"from": src, "to": nid, "label": lab})
+
+    # query channels: present iff their table exists on disk. This list
+    # is the CURRENT set path, nothing else; a channel appears the
+    # moment its vectors are ingested and vanishes with them.
+    channels = []
+    def chan(cid, label, need, note):
+        ok = need() if callable(need) else need in have
+        if ok:
+            channels.append({"id": cid, "label": label, "note": note})
+    chan("app", "appearance", "embeddings", "window vectors, exact scan")
+    chan("pe", "perception", "pe_vectors", "PE-Core text to frame")
+    chan("sig2", "fine-grained", "sig2_vectors", "SigLIP 2 frame space")
+    chan("conj", "conjunction", "sig2_vectors",
+         "every noun phrase must find its own frame")
+    chan("iv2", "video-text", "iv2_vectors",
+         "InternVideo2, 4 frames encoded together")
+    chan("act", "action", "action_probs", "V-JEPA 2 verb posteriors")
+    chan("vid", "clip-text", "xclip_vectors", "X-CLIP pooled clips")
+    chan("obj", "objects", "object_vectors", "region crops, conjunctive")
+    chan("mot", "motion", "motion_vectors",
+         "delta appearance against the antonym")
+    chan("prf", "feedback", "vjepa_vectors",
+         "Rocchio anchors mined from this corpus")
+    chan("itm", "cross-encoder", lambda: (
+        os.environ.get("ELIDEDB_ITM") == "1"
+        and (db.dir / "_cache/itm_tokens").exists()),
+        "InternVideo2 1B, rerank STAGE over the top-N - never a channel "
+        "(as a weighted voter it cost 0.38 -> 0.27, RRF discards the "
+        "margin's scale). Cost-gated: 0.4s/episode")
+    chan("anchor", "transition anchor", "motion_vectors",
+         "the query names a transition, the corpus defines its DIRECTION "
+         "in motion space. Text cannot ask for it: cos(opens, closes) = "
+         "0.957. Motion separates them 0.983 held-out")
+
+    # selection pipeline: the fitted stages every result passes
+    # through, in order. Fitted values come from the per-store
+    # artifact; stages render even unfitted (neutral defaults).
+    fitted = {}
+    swp = db.dir / "_set_weights.json"
+    if swp.exists():
+        try:
+            fitted = json.loads(swp.read_text())
+        except Exception:
+            pass
+    pipeline = [
+        {"id": "fuse", "label": "Fitted fusion",
+         "note": "weighted rank consensus, per-store weights"},
+        {"id": "prf", "label": "Pseudo-relevance",
+         "note": "the head of pass 1 re-queries the corpus"},
+        {"id": "itm", "label": "Cross-encoder cascade",
+         "note": "distribution-preserving: it PERMUTES the candidates "
+                 "and returns the same sorted scores in the new order, "
+                 "because the cut downstream is fitted to RRF's scale"},
+        {"id": "anchor", "label": "Transition anchor",
+         "note": "direction from the corpus, weighted by a reliability "
+                 "each kind earns unsupervised (close 0.52, open 0.35, "
+                 "put_on 0.00 - so it cannot damage what it cannot help)"},
+        {"id": "evk", "label": "Event corroboration",
+         "note": "does this demo carry the asked-for transition at all"},
+        {"id": "dens", "label": "Motion density",
+         "note": "15-NN agreement in motion space"},
+        {"id": "gate", "label": "No-match gate",
+         "note": "abstains when the corpus lacks the action"},
+        {"id": "filter", "label": "Contrast filter",
+         "note": "direction evidence, fitted quantile"},
+        {"id": "nms", "label": "Event dedup",
+         "note": "one clip per event, fitted radius"},
+        {"id": "cut", "label": "Confidence cut",
+         "note": "the set ends where confidence does"},
+        {"id": "audit", "label": "Geometry audit",
+         "note": "SAM 3 tracker verification, opt-in tier"},
+    ]
+
+    # THE FIVE ELEMENTS — what a clip is decomposed into. Each renders
+    # only if the table that carries it exists in THIS store, so an
+    # un-elemented store shows an empty list rather than a promise.
+    def _rows(t):
+        try:
+            return db.table(t).scan().num_rows if t in have else 0
+        except Exception:
+            return 0
+
+    ev_t = "events" if "events" in have else (
+        "events_s" if "events_s" in have else None)
+    elements = []
+    if ev_t:
+        import collections as _c
+        kinds = _c.Counter(db.table(ev_t).scan().column("kind").to_pylist())
+        elements = [
+            {"id": "scene", "label": "scene", "note": "demo gist vector",
+             "n": _rows("answers2")},
+            {"id": "agent", "label": "agent",
+             "note": "the self-moving thing, from flow",
+             "n": kinds.get("agent", 0)},
+            {"id": "participants", "label": "participants",
+             "note": "what the agent contacts, in order - by CAUSALITY "
+                     "(motion onset adjacent to the agent), not pixel "
+                     "change", "n": kinds.get("contact", 0)},
+            {"id": "events", "label": "events",
+             "note": "typed, TIMESTAMPED transitions: " + ", ".join(
+                 f"{k} {v}" for k, v in kinds.most_common()
+                 if k not in ("agent", "contact", "release")),
+             "n": sum(v for k, v in kinds.items()
+                      if k not in ("agent", "contact", "release"))},
+            {"id": "answer", "label": "answer",
+             "note": "initial -> final diff, attributed to the agent",
+             "n": _rows("answers2")},
+        ]
+
+    # MODELS — the manifest is the authority, and it records the env
+    # needed to reproduce its own numbers (see teacher_v2.json).
+    models = []
+    for tag in ("teacher_v2", "teacher_v1"):
+        p = Path(__file__).resolve().parents[2] / f"models/{tag}.json"
+        if p.exists():
+            try:
+                m = json.loads(p.read_text())
+                models.append({
+                    "id": tag, "kind": "teacher",
+                    "yield": m["metric"].get("mean_yield"),
+                    "prec": m["metric"].get("mean_prec"),
+                    "env": m.get("env", {}),
+                    "reproduce": m.get("reproduce", ""),
+                    "note": "cosine channels -> RRF -> PRF -> ITM cascade "
+                            "-> anchor + event gate + density -> cut"})
+                break
+            except Exception:
+                pass
+    sp = Path(__file__).resolve().parents[2] / "models/student_v1/meta.json"
+    if sp.exists():
+        try:
+            sm = json.loads(sp.read_text())
+            models.append({
+                "id": "student_v1", "kind": "student",
+                "params_M": round(sm.get("params", 0) / 1e6, 2),
+                "read_ms": 27, "write_s_per_demo": 0.85,
+                "note": "two-tower bi-encoder + listwise rerank head. "
+                        "Produces the five elements ITSELF; stage order "
+                        "PRF -> gate -> cascade was measured, not "
+                        "inherited (the teacher's order scored worse)"})
+        except Exception:
+            pass
+
+    # ARTIFACTS lane: the model files and fitted state this store's query
+    # path actually loads. It was empty because nothing ever emitted a
+    # node of kind "model" - the lane existed with nothing to put in it.
+    RT = Path(__file__).resolve().parents[2]
+
+    def _sz(p):
+        p = Path(p)
+        if p.is_dir():
+            return sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
+        return p.stat().st_size if p.exists() else 0
+
+    for path, label, note in (
+        ("models/teacher_v2.json", "teacher_v2", "manifest: tables, "
+         "digests, stages, env, measured yield/prec"),
+        ("models/student_v1", "student_v1", "student.pt (two-tower + "
+         "rerank head), episode_emb.npz, namer.pt"),
+        ("models/iv2_stage2_1b", "iv2_stage2_1b", "InternVideo2-Stage2 "
+         "1B — the ITM cross-encoder, cost-gated"),
+        ("models/fdnnv", "fdnnv", "FDNN-V encoder — embeds every frame "
+         "at ingest, 1,109 fps"),
+        ("artifacts/verbs_v2.json", "verbs_v2", "geometry verb partition"),
+        ("artifacts/cavity.json", "cavity", "cavity/articulation thresholds"),
+    ):
+        b = _sz(RT / path)
+        if b:
+            nodes.append({"id": label, "kind": "model", "rows": None,
+                          "bytes": b, "note": note, "path": path})
+    for a, note in (("_set_weights.json", "fitted selection weights "
+                     "(+ .prev rotation, .loqo holdout)"),
+                    ("_channel_weights.json", "per-channel fusion weights"),
+                    ("_vocab.json", "corpus-attested vocabulary cache")):
+        b = _sz(db.dir / a)
+        if b:
+            nodes.append({"id": a, "kind": "model", "rows": None,
+                          "bytes": b, "note": note, "path": a})
+
+    # THE TRAINING / RETRAINING LOOP — how more data becomes a better
+    # model. This is a closed loop and the store is inside it.
+    training = [
+        {"id": "ingest", "label": "1 · INGEST",
+         "note": "raw video → frames (byte-range index) + FDNN-V vectors "
+                 "for EVERY frame. 63.5 s for 3.91 h, 1,109 fps. No "
+                 "labels, no metadata: the store never ingests task "
+                 "strings."},
+        {"id": "elements", "label": "2 · WRITE-PATH ELEMENTS",
+         "note": "geometry over the frames produces the five elements "
+                 "per demo — agent from flow, participants by causality, "
+                 "events from cavity + displacement, answer rollup. The "
+                 "student's Namer head predicts the participant NAME "
+                 "VECTOR the 7B VLM would have produced."},
+        {"id": "teacher", "label": "3 · TEACHER RANKS",
+         "note": "the expensive path (channels → RRF → PRF → ITM 1B "
+                 "cross-encoder → anchor + gate) ranks the corpus for "
+                 "generated queries. 2–75 s/query, so it is never the "
+                 "serving path — it exists to produce labels."},
+        {"id": "distill", "label": "4 · DISTILL",
+         "note": "teacher rankings over 200 corpus-vocabulary queries "
+                 "become listwise targets for the student's two-tower "
+                 "+ rerank head. 645 s to label, 8 s to train, 3.28M "
+                 "params. The eval truthset is NEVER trained on."},
+        {"id": "serve", "label": "5 · SERVE",
+         "note": "student answers in 27 ms: one text forward + one "
+                 "matmul over precomputed episode vectors, then the "
+                 "structural gate reads columns the write path already "
+                 "produced."},
+        {"id": "grow", "label": "6 · MORE DATA → BETTER MODEL",
+         "note": "adding episodes widens every corpus statistic the "
+                 "system is built on: the transition anchors get more "
+                 "attesting episodes so their earned reliability rises, "
+                 "PRF anchors sharpen, the attested vocabulary grows, "
+                 "and the teacher has more to label. Re-running step 3–4 "
+                 "is the retrain; nothing here needs human annotation."},
+    ]
+
+    total_rows = sum(n.get("rows") or 0 for n in nodes)
+    total_bytes = sum(n.get("bytes") or 0 for n in nodes)
+    return {"store": db.name, "key": key, "nodes": nodes, "edges": edges,
+            "channels": channels, "pipeline": pipeline,
+            "elements": elements, "models": models, "training": training,
+            "fitted": {k: fitted[k] for k in
+                       ("set_weights_dir", "set_weights", "cut_alpha_dir",
+                        "cut_alpha", "nms_r_dir", "nms_r", "loqo_mean")
+                       if k in fitted},
+            "totals": {"rows": total_rows, "bytes": total_bytes,
+                       "tables": len([n for n in nodes
+                                      if n["kind"] not in
+                                      ("media", "model")])}}
+
+
+def api_bytes(key: str):
+    """WHERE THE BYTES ACTUALLY ARE, and how much compression bought.
+
+    `du` on this store says 3.9 GB while the tables hold 249 MB, and the
+    gap is not a compression failure - it is three different things that
+    a single directory size silently adds together:
+
+      live      the parquet the LOG currently points at. The database.
+      orphaned  parquet superseded by a replace/compact commit. Removed
+                from the active set, still on disk until vacuum.
+      media     managed video renditions, byte-range decoded.
+      cache     _cache/ - the ITM cross-encoder's vision tokens, 3 GB
+                of it. DISPOSABLE: deleting it costs recompute time and
+                never correctness, and it is not the database.
+
+    Models are NOT in the store. They live in models/ at the repo root
+    (iv2_stage2_1b alone is 2.8 GB), which is why "the store" and "what
+    this system needs on disk" are different questions.
+    """
+    import pyarrow.parquet as pq
+    db = STORES[key]
+    live = orphan = on_disk = 0
+    rows = []
+    for t in sorted(db.tables()):
+        st = db.table(t).state()
+        keep = {f.path for f in st.files}
+        c = u = 0
+        encs = set()
+        comp = set()
+        d = db.dir / "tables" / t
+        for f in d.glob("*.parquet"):
+            b = f.stat().st_size
+            on_disk += b
+            if f.name not in keep:
+                orphan += b
+                continue
+            try:
+                md = pq.ParquetFile(f).metadata
+                for g in range(md.num_row_groups):
+                    rg = md.row_group(g)
+                    for j in range(rg.num_columns):
+                        col = rg.column(j)
+                        c += col.total_compressed_size
+                        u += col.total_uncompressed_size
+                        for e in (col.encodings or ()):
+                            encs.add(str(e))
+                        if col.compression:
+                            comp.add(str(col.compression))
+            except Exception:
+                pass
+        live += st.bytes
+        rows.append({"table": t, "rows": st.rows, "compressed": c,
+                     "uncompressed": u,
+                     "ratio": round(u / max(c, 1), 2),
+                     "encodings": sorted(encs), "codec": sorted(comp),
+                     "files": len(st.files), "version": st.version})
+    rows.sort(key=lambda r: -r["compressed"])
+    media = sum(p.lstat().st_size for p in (db.dir / "media").glob("*")
+                if p.is_file()) if (db.dir / "media").is_dir() else 0
+    cdir = db.dir / "_cache"
+    cache = sum(f.stat().st_size for f in cdir.rglob("*")
+                if f.is_file()) if cdir.is_dir() else 0
+    cparts = ([{"name": p.name,
+                "bytes": sum(f.stat().st_size for f in p.rglob("*")
+                             if f.is_file())}
+               for p in cdir.iterdir() if p.is_dir()] if cdir.is_dir()
+              else [])
+    tc = sum(r["compressed"] for r in rows)
+    tu = sum(r["uncompressed"] for r in rows)
+    raw = _raw_source_bytes(db, db.describe())
+    return {"store": db.name, "key": key, "tables": rows,
+            "live": live, "orphaned": orphan, "on_disk": on_disk,
+            "media": media, "cache": cache, "cache_parts": cparts,
+            "total": on_disk + media + cache,
+            "compressed": tc, "uncompressed": tu,
+            "ratio": round(tu / max(tc, 1), 2),
+            "raw_source": raw["bytes"], "raw_files": raw["files"]}
+
+
+def api_dbinternals(key: str, table: str | None = None):
+    """The storage engine, as it actually is on disk.
+
+    Not a diagram: every number here is read from the transaction log
+    and the Parquet footers of this store, right now. Four things a
+    storage engine has to be able to show:
+
+      1. the LOG   — the table is the fold of an append-only list of
+                     JSON commits, each carrying its own file list
+      2. FILES     — with the zone map (min_ts/max_ts) that lets a
+                     query drop a whole file without opening it
+      3. PAGES     — row groups inside a file, each with its own ts
+                     statistics and per-column chunk sizes
+      4. PRUNING   — what a real window query touches, in bytes,
+                     across both layers
+    """
+    import pyarrow.parquet as pq
+    db = STORES[key]
+    names = sorted(db.tables())
+    table = table if table in names else (
+        "frames" if "frames" in names else names[0])
+    t = db.table(table)
+    st = t.state()
+
+    # ---- 1. the log: manifest commits, newest last
+    # read the RAW commit files: Table.history() summarises and drops the
+    # removal count, which is the whole point of an op=replace entry.
+    log = []
+    ldir = db.dir / "tables" / table / "_log"
+    for f in sorted(ldir.glob("*.json")) if ldir.is_dir() else []:
+        try:
+            e = json.loads(f.read_text())
+        except Exception:
+            continue
+        add = e.get("add") or []
+        log.append({
+            "version": int(f.stem), "op": e.get("op"), "kind": e.get("kind"),
+            "added": len(add),
+            "removed": len(e.get("remove") or []),
+            "added_rows": sum(a.get("rows", 0) for a in add),
+            "added_bytes": sum(a.get("bytes", 0) for a in add),
+            "ts": e.get("ts_utc"),
+            "meta": {k: v for k, v in (e.get("meta") or {}).items()
+                     if not isinstance(v, (list, dict))},
+        })
+
+    # ---- 2/3. files and their row groups (pages)
+    files, pages = [], []
+    total_rg = 0
+    for f in st.files:
+        p = db.dir / "tables" / table / f.path
+        row = {"path": f.path, "rows": f.rows, "bytes": f.bytes,
+               "min_ts": f.min_ts, "max_ts": f.max_ts, "row_groups": None,
+               "footer_bytes": None}
+        try:
+            pf = pq.ParquetFile(p)
+            md = pf.metadata
+            row["row_groups"] = md.num_row_groups
+            row["footer_bytes"] = md.serialized_size
+            total_rg += md.num_row_groups
+            ts_i = (md.schema.names.index("ts")
+                    if "ts" in md.schema.names else 0)
+            if len(pages) < 24:            # a readable sample, not all
+                for g in range(min(md.num_row_groups, 8)):
+                    rg = md.row_group(g)
+                    s = rg.column(ts_i).statistics
+                    cols = []
+                    for c in range(rg.num_columns):
+                        col = rg.column(c)
+                        cols.append({
+                            "name": (md.schema.names[c]
+                                     if c < len(md.schema.names) else "?"),
+                            "compressed": col.total_compressed_size,
+                            "uncompressed": col.total_uncompressed_size,
+                            "encodings": [str(e) for e in
+                                          (col.encodings or [])][:3],
+                        })
+                    cols.sort(key=lambda x: -x["compressed"])
+                    pages.append({
+                        "file": f.path[:18], "group": g,
+                        "rows": rg.num_rows, "bytes": rg.total_byte_size,
+                        "min_ts": getattr(s, "min", None),
+                        "max_ts": getattr(s, "max", None),
+                        "columns": cols[:6],
+                        "n_columns": rg.num_columns})
+        except Exception:
+            pass
+        files.append(row)
+
+    # ---- 4. pruning, executed for real on a 2% slice of the span
+    prune = None
+    if st.files and st.min_ts is not None:
+        # ANCHOR THE WINDOW ON REAL DATA. Taking the midpoint of
+        # min_ts..max_ts lands in one of the 60 s gaps this store puts
+        # between demos and returns zero rows, which measures nothing.
+        # A row group's own ts statistics are, by construction, a range
+        # that contains rows - so the demo window is the middle row
+        # group of the middle file.
+        t0, t1 = st.min_ts, st.min_ts + max(
+            (st.max_ts - st.min_ts) // 50, 1)
+        try:
+            mid = st.files[len(st.files) // 2]
+            pf = pq.ParquetFile(db.dir / "tables" / table / mid.path)
+            md = pf.metadata
+            ts_i = (md.schema.names.index("ts")
+                    if "ts" in md.schema.names else 0)
+            g = md.row_group(md.num_row_groups // 2)
+            s = g.column(ts_i).statistics
+            if s is not None and s.min is not None:
+                t0, t1 = int(s.min), int(s.max)
+        except Exception:
+            pass
+        from .store import QueryStats
+        qs = QueryStats()
+        try:
+            got = t.scan(t0, t1, stats=qs)
+            prune = {
+                "window_ns": int(t1 - t0),
+                "files_total": qs.files_total,
+                "files_touched": qs.files_touched,
+                "corpus_bytes": qs.corpus_bytes,
+                "bytes_touched": qs.bytes_touched,
+                "rows_returned": len(got),
+                "elided_pct": (round(100.0 * (qs.corpus_bytes
+                                              - qs.bytes_touched)
+                                     / max(qs.corpus_bytes, 1), 2)),
+            }
+        except Exception as e:
+            prune = {"error": f"{type(e).__name__}: {e}"[:120]}
+
+    # ---- THE LADDER: the containment hierarchy, one rung per level,
+    # with this store's real numbers on each. Ordered smallest first.
+    lake_dir = db.dir.parent
+    n_stores = sum(1 for p in lake_dir.iterdir()
+                   if p.is_dir() and (p / "_store.json").exists())
+    f0 = files[0] if files else None    # the dict built above
+    rg0 = pages[0] if pages else None
+    ch0 = (rg0 or {}).get("columns", [{}])[0] if rg0 else {}
+    PAGE_TARGET = 1 << 20                       # parquet default 1 MiB
+    est_pages = max(1, round((ch0.get("compressed") or 0) / PAGE_TARGET)) \
+        if ch0 else None
+    ladder = [
+        {"id": "value", "label": "VALUE / ROW",
+         "n": f"{st.rows:,} rows",
+         "sub": f"{(rg0 or {}).get('n_columns', 0)} columns",
+         "meta": "—",
+         "why": "One cell. Rows are never stored contiguously: inside a "
+                "row group the data is laid out COLUMN BY COLUMN, which "
+                "is what lets a query read one column and skip the rest."},
+        {"id": "page", "label": "PAGE",
+         "n": (f"~{est_pages} per column chunk" if est_pages else "—"),
+         "sub": "~1 MiB target",
+         "meta": "page header: encoding, value count, (optional) stats",
+         "why": "The atomic unit of compression and decode. You cannot "
+                "read half a page - it is decompressed whole - so page "
+                "size is the floor on random-access cost."},
+        {"id": "chunk", "label": "COLUMN CHUNK",
+         "n": f"{(rg0 or {}).get('n_columns', 0)} per row group",
+         "sub": (f"{ch0.get('name','')} "
+                 f"{(ch0.get('encodings') or [None])[0] or ''}"),
+         "meta": "offset, size, encodings, compression, min/max/nulls",
+         "why": "All the pages of ONE column within ONE row group, "
+                "contiguous on disk. This is the unit PROJECTION "
+                "pushdown skips: ask for 2 of 11 columns and the other "
+                "9 chunks are never read."},
+        {"id": "rowgroup", "label": "ROW GROUP",
+         "n": f"{total_rg} in this table",
+         "sub": (f"{rg0['rows']:,} rows · {rg0['bytes']:,} B"
+                 if rg0 else "—"),
+         "meta": "per-column statistics: min, max, null_count",
+         "why": "A horizontal slice of rows holding every column's "
+                "chunk. Its ts statistics are what PREDICATE pushdown "
+                "tests, so a non-overlapping group is never "
+                "decompressed. Sized by BYTES (8 MB target), not rows."},
+        {"id": "footer", "label": "FOOTER  (FileMetaData)",
+         "n": (f"{f0.get('footer_bytes') or 0:,} B" if f0 else "—"),
+         "sub": "at the END of the file",
+         "meta": "THE schema + every row group's metadata + offsets",
+         "why": "Written last so the file streams out in one pass, read "
+                "first so one seek reveals the whole layout. NOTE: row "
+                "group metadata lives HERE, inside the same file - not "
+                "in a separate meta file. Separate meta files start one "
+                "level up."},
+        {"id": "file", "label": "PARQUET FILE",
+         "n": f"{len(st.files)} in this table",
+         "sub": (f"{f0['rows']:,} rows · {f0['bytes']:,} B" if f0 else "—"),
+         "meta": "immutable; never edited in place",
+         "why": "The unit of atomic addition and removal. Rewriting is "
+                "how you 'edit', which is what makes snapshots cheap."},
+        {"id": "commit", "label": "COMMIT  (manifest file)",
+         "n": f"{len(log)} in tables/{table}/_log/",
+         "sub": (f"latest: v{log[-1]['version']} {log[-1]['op']} "
+                 f"+{log[-1]['added']}"
+                 f"{' −' + str(log[-1]['removed']) if log[-1]['removed'] else ''}"
+                 if log else "—"),
+         "meta": "op, schema, file list WITH zone maps (min_ts/max_ts)",
+         "why": "THE separate meta file. One JSON per commit, listing "
+                "the files this version contains and each file's time "
+                "range - so a window query drops whole files here, "
+                "before opening a single footer. Iceberg calls this a "
+                "manifest; Delta calls it a log entry."},
+        {"id": "log", "label": "LOG  →  TABLE STATE",
+         "n": f"version {st.version}",
+         "sub": f"state = fold of {len(log)} commits",
+         "meta": "the fold: adds minus removes, in order",
+         "why": "A table is NOT the files in its directory - it is the "
+                "result of replaying this log. That is what buys "
+                "snapshot isolation (v{N} is immutable forever), atomic "
+                "multi-file commits, and time travel."},
+        {"id": "table", "label": "TABLE  (+ schema)",
+         "n": f"{len(names)} in this store",
+         "sub": f"{table}: {st.rows:,} rows · {st.bytes:,} B",
+         "meta": "schema travels with each commit (schema-on-log)",
+         "why": "Schema evolution is an append, never a rewrite. Every "
+                "table must carry ts (int64 ns) sorted within a file - "
+                "the one schema law, and why time is the primary axis."},
+        {"id": "store", "label": "STORE",
+         "n": f"{len(names)} tables",
+         "sub": f"{db.name} · {sum((db.table(x).state().bytes) for x in names):,} B",
+         "meta": "_store.json + fitted artifacts + caches + media/",
+         "why": "A directory of tables plus sidecar state. Sidecars are "
+                "graded: authoritative (_store.json), fitted "
+                "(_set_weights.json), cache (_vocab.json), disposable "
+                "(_cache/). Raw media is referenced in place, never "
+                "copied in."},
+        {"id": "lake", "label": "LAKE",
+         "n": f"{n_stores} store{'' if n_stores == 1 else 's'}",
+         "sub": "lake/  (" + lake_dir.name + ")",
+         "meta": "plain directories — no catalog service",
+         "why": "Many stores side by side. Nothing above this is "
+                "needed: the format is open, so any engine (DuckDB, "
+                "Spark, pandas) reads these files directly without "
+                "going through us."},
+    ]
+
+    return {
+        "store": db.name, "key": key, "table": table, "tables": names,
+        "version": st.version, "kind": st.kind, "rows": st.rows,
+        "bytes": st.bytes, "n_files": len(st.files),
+        "n_row_groups": total_rg, "ladder": ladder,
+        "schema": [str(x) for x in str(st.schema).split("\n") if x][:24],
+        "log": log[-12:], "log_total": len(log),
+        "files": files[:12], "pages": pages, "prune": prune,
+        "log_dir": f"tables/{table}/_log/",
+        "store_files": sorted(
+            p.name for p in db.dir.glob("*")
+            if p.is_file())[:20],
+    }
+
+
+def api_analytics(key: str):
+    """Operational analytics, general to ANY store: everything here is
+    derived from transaction logs, parquet footers, and table meta.
+    No data pages are read and nothing is dataset-specific; a store of
+    factory video, dashcam runs, or plain sensor CSVs renders the same
+    panels."""
+    import pyarrow.parquet as pq
+    ck = ("analytics", key,
+          tuple(sorted((d["table"], d["version"])
+                       for d in STORES[key].describe())))
+    if ck in _CACHE:
+        return _CACHE[ck]
+    db = STORES[key]
+    desc = db.describe()
+    lo = min((d["min_ts"] for d in desc
+              if d["rows"] and d.get("min_ts")), default=0)
+    hi = max((d["max_ts"] for d in desc
+              if d["rows"] and d.get("max_ts")), default=lo + 1)
+    span = max(hi - lo, 1)
+
+    # write history straight off the transaction logs
+    commits = []
+    for d in desc:
+        try:
+            for c in db.table(d["table"]).history():
+                commits.append({"table": d["table"],
+                                "version": c.get("version"),
+                                "op": c.get("op", ""),
+                                "rows": c.get("added_rows", 0),
+                                "ts_utc": c.get("ts_utc", "")})
+        except Exception:
+            pass
+    commits.sort(key=lambda c: c["ts_utc"])
+
+    # temporal density from ROW-GROUP footer stats only: rows per time
+    # bucket per table. The row group is the pruning unit, so this is
+    # literally the elision map a range query sees.
+    buckets_n = 64
+    density = {}
+    for d in desc:
+        if not d["rows"] or not d.get("min_ts"):
+            continue
+        st = db.table(d["table"]).state()
+        buckets = [0.0] * buckets_n
+        try:
+            for f in st.files:
+                pf = pq.ParquetFile(db.dir / "tables" / d["table"]
+                                    / f.path)
+                md = pf.metadata
+                names = md.schema.names
+                if "ts" not in names:
+                    continue
+                ti = names.index("ts")
+                for g in range(md.num_row_groups):
+                    rg = md.row_group(g)
+                    s = rg.column(ti).statistics
+                    if not s or s.min is None:
+                        continue
+                    a = int((s.min - lo) * buckets_n // span)
+                    b = int((s.max - lo) * buckets_n // span)
+                    a = min(max(a, 0), buckets_n - 1)
+                    b = min(max(b, a), buckets_n - 1)
+                    per = rg.num_rows / (b - a + 1)
+                    for i in range(a, b + 1):
+                        buckets[i] += per
+        except Exception:
+            continue
+        if sum(buckets) > 0:
+            density[d["table"]] = [int(round(x)) for x in buckets]
+
+    # vector inventory: every embeddings-kind table, with coverage
+    # against the store's episode base when one exists
+    base_rows = next((d["rows"] for d in desc
+                      if d["table"] == "episodes" and d["rows"]), None)
+    vectors = []
+    for d in desc:
+        if d["kind"] != "embeddings" or not d["rows"]:
+            continue
+        meta = d.get("meta") or {}
+        vectors.append({
+            "table": d["table"], "rows": d["rows"], "bytes": d["bytes"],
+            "dim": meta.get("dim"),
+            "model": str(meta.get("model", ""))[:60],
+            "per_base": (round(d["rows"] / base_rows, 2)
+                         if base_rows else None)})
+
+    fitted = None
+    swp = db.dir / "_set_weights.json"
+    if swp.exists():
+        try:
+            fitted = json.loads(swp.read_text())
+        except Exception:
+            pass
+
+    ix = api_indexes(key)
+    out = {
+        "span": {"lo": lo, "hi": hi},
+        "tables": [{"table": d["table"], "kind": d["kind"],
+                    "rows": d["rows"], "bytes": d["bytes"],
+                    "files": d["files"], "version": d["version"],
+                    "bpr": (round(d["bytes"] / d["rows"], 1)
+                            if d["rows"] else None)} for d in desc],
+        "commits": commits[-48:],
+        "commit_total": len(commits),
+        "density": density, "buckets": buckets_n,
+        "vectors": vectors, "base_rows": base_rows,
+        "fitted": fitted,
+        "indexes": {"bptree": ix["bptree"], "ann": ix["ann"]},
+    }
+    if len(_CACHE) > 32:
+        _CACHE.clear()
+    _CACHE[ck] = out
+    return out
+
+
+def api_geo(key: str):
+    """Generic geo panel: any timeseries table with latitude+longitude."""
+    db = STORES[key]
+    for d in db.describe():
+        if d["kind"] != "timeseries":
+            continue
+        cols = db.table(d["table"]).scan(columns=None)
+        if {"latitude", "longitude"} <= set(cols.column_names):
+            la = cols.column("latitude").to_numpy()
+            lo = cols.column("longitude").to_numpy()
+            ts = cols.column("ts").to_numpy()
+            step = max(1, len(la) // 2500)
+            return {"table": d["table"],
+                    "points": [{"la": float(la[i]), "lo": float(lo[i]),
+                                "t": int(ts[i])}
+                               for i in range(0, len(la), step)]}
+    return {"points": []}
+
+
+def _as_frameset(db, fs):
+    """Tolerate frame tables whose registered kind is not frame_index
+    (seen on stores assembled by filtering another store): window()
+    then returns a plain Arrow table, which still carries the frame
+    index columns and decodes fine once wrapped."""
+    if fs is None or hasattr(fs, "decode"):
+        return fs
+    try:
+        from .video import FrameSet
+        return FrameSet(db, "frames", fs)
+    except Exception:
+        return None
+
+
+def api_thumb(key: str, stream: str, t: int, width: int = 360):
+    from PIL import Image
+    db = STORES[key]
+    win, _ = db.window(t - 2_000_000_000, t + 2_000_000_000, tables=["frames"])
+    fs = _as_frameset(db, win.get("frames"))
+    if fs is None or len(fs) == 0:
+        return None
+    decoded = fs.decode(stream=stream or None, width=width, limit=1)
+    if not decoded:
+        return None
+    img = Image.fromarray(decoded[0][1])
+    rot = db.meta.get("display", {}).get("rotate", 0)
+    if rot:
+        img = img.rotate(rot, expand=True)
+    buf = io.BytesIO()
+    img.save(buf, "JPEG", quality=80)
+    return buf.getvalue()
+
+
+def _audio_for_stream(db, stream: str, t0: int, t1: int):
+    """Find the sensor's audio table (e.g. 'Sensor 108/cam0' →
+    sensor_108_audio), return mono WAV bytes for the window, or None."""
+    import struct as _struct
+    prefix = stream.split("/")[0].replace("/", "_").replace(" ", "_").lower()
+    cand = f"{prefix}_audio"
+    if cand not in db.tables():
+        return None
+    t = db.table(cand).scan(t0, t1, columns=["ts", "ch0"])
+    if len(t) < 100:
+        return None
+    ts = t.column("ts").to_numpy()
+    rate = int(round((len(ts) - 1) * 1e9 / max(int(ts[-1] - ts[0]), 1)))
+    pcm = t.column("ch0").to_numpy().astype("<i2").tobytes()
+    hdr = b"RIFF" + _struct.pack("<I", 36 + len(pcm)) + b"WAVEfmt " + \
+        _struct.pack("<IHHIIHH", 16, 1, 1, rate, rate * 2, 2, 16) + \
+        b"data" + _struct.pack("<I", len(pcm))
+    return hdr + pcm
+
+
+def api_clip(key: str, stream: str, t0: int, t1: int, width: int = 640):
+    """Playable clip: byte-range decode of the window's frames → H.264 MP4
+    (plus the sensor's microphone track when the store has one). Cached by
+    parameters; the source media is only ever read, never touched."""
+    import hashlib
+    import subprocess
+    import tempfile
+    # Merged segments can be minutes long; the player previews the first 30 s
+    # rather than refusing (full-range export belongs to the Python API).
+    t1 = min(t1, t0 + 30_000_000_000)
+    cache_dir = Path(tempfile.gettempdir()) / "elidedb_clips"
+    cache_dir.mkdir(exist_ok=True)
+    ck = hashlib.sha1(f"{key}|{stream}|{t0}|{t1}|{width}".encode()).hexdigest()
+    out_path = cache_dir / f"{ck}.mp4"
+    if out_path.exists():
+        return out_path.read_bytes()
+
+    from PIL import Image
+    db = STORES[key]
+    win, _ = db.window(t0, t1, tables=["frames"])
+    fs = _as_frameset(db, win.get("frames"))
+    # Every failure below names itself. A <video> element cannot render an
+    # error body, so the player fetches the clip and shows these strings —
+    # "could not build a clip" with no reason is not a diagnosis.
+    if fs is None or len(fs) == 0:
+        return {"error": "no frames indexed in this window",
+                "detail": f"{stream or 'all streams'} "
+                          f"{(t1 - t0) / 1e9:.2f}s window"}
+    have = fs.streams()
+    if stream and stream not in have:
+        return {"error": f"stream '{stream}' has no frames here",
+                "detail": f"streams present in this window: "
+                          f"{', '.join(have) or 'none'}"}
+    try:
+        decoded = fs.decode(stream=stream or None, width=width)
+    except Exception as e:
+        return {"error": f"decode failed: {type(e).__name__}", "detail": str(e)}
+    if len(decoded) < 2:
+        return {"error": "not enough decodable frames for a clip",
+                "detail": f"{len(decoded)} frame(s) decoded from "
+                          f"{len(fs)} indexed"}
+    rot = db.meta.get("display", {}).get("rotate", 0)
+    span_s = max((decoded[-1][0] - decoded[0][0]) / 1e9, 0.1)
+    fps = max(round((len(decoded) - 1) / span_s, 2), 1)
+
+    wav = _audio_for_stream(db, stream, decoded[0][0], decoded[-1][0])
+    wav_path = None
+    if wav:
+        wav_path = cache_dir / f"{ck}.wav"
+        wav_path.write_bytes(wav)
+    from .fftools import find
+    cmd = [find("ffmpeg"), "-v", "error", "-y",
+           "-f", "image2pipe", "-framerate", str(fps), "-i", "-"]
+    if wav_path:
+        cmd += ["-i", str(wav_path)]
+    cmd += ["-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
+            "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+    if wav_path:
+        cmd += ["-c:a", "aac", "-b:a", "96k", "-shortest"]
+    cmd += [str(out_path)]
+    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE,
+                            stderr=subprocess.PIPE)
+    try:
+        for (_ts, arr) in decoded:
+            img = Image.fromarray(arr)
+            if rot:
+                img = img.rotate(rot, expand=True)
+            # libx264 yuv420 needs even dimensions
+            if img.width % 2 or img.height % 2:
+                img = img.crop((0, 0, img.width & ~1, img.height & ~1))
+            img.save(proc.stdin, "JPEG", quality=90)
+        proc.stdin.close()
+    except BrokenPipeError:
+        pass  # ffmpeg died early; the stderr below explains why
+    err = proc.stderr.read().decode(errors="replace").strip()
+    proc.wait()
+    if wav_path:
+        wav_path.unlink(missing_ok=True)
+    if proc.returncode != 0 or not out_path.exists():
+        return {"error": "ffmpeg could not mux the clip",
+                "detail": err or "no output produced"}
+    return out_path.read_bytes()
+
+
+def build_id() -> str:
+    """Identity of the code this server is actually running.
+
+    The launcher reuses whatever already listens on the port, so a server
+    started from an older checkout keeps serving stale code forever — Python
+    caches modules at import, so editing files changes nothing until restart.
+    That is invisible from the browser and produces bug reports about
+    behaviour that no longer exists in the source. The launcher now compares
+    this against the on-disk files and restarts on a mismatch.
+    """
+    import hashlib
+    h = hashlib.sha1()
+    for f in sorted(Path(__file__).parent.glob("*.py")) + \
+            [Path(__file__).parent / "desk_ui.html"]:
+        if f.exists():
+            st = f.stat()
+            h.update(f"{f.name}:{st.st_size}:{int(st.st_mtime)}".encode())
+    return h.hexdigest()[:12]
+
+
+def api_schema(key: str, table: str | None = None):
+    """What the data actually IS: columns, types, and real sample rows.
+    The first thing anyone opening a database wants to see."""
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+    db = STORES[key]
+    names = [table] if table else db.tables()
+    out = []
+    for name in names:
+        st = db.table(name).state()
+        if not st.files:
+            continue
+        pf = pq.ParquetFile(db.dir / "tables" / name / st.files[0].path)
+        schema = pf.schema_arrow
+        cols = []
+        for f in schema:
+            t = str(f.type)
+            if pa.types.is_fixed_size_list(f.type):
+                t = f"vector[{f.type.list_size}]"
+            cols.append({"name": f.name, "type": t})
+        sample = []
+        if table:  # only materialise rows for the focused table
+            head = db.table(name).scan(columns=[c["name"] for c in cols
+                                                if not c["type"].startswith("vector")]
+                                       ).slice(0, 8).to_pylist()
+            for row in head:
+                sample.append({k: (round(v, 6) if isinstance(v, float) else v)
+                               for k, v in row.items()})
+        out.append({"table": name, "kind": st.kind, "rows": st.rows,
+                    "bytes": st.bytes, "version": st.version,
+                    "min_ts": st.min_ts, "max_ts": st.max_ts,
+                    "columns": cols, "sample": sample})
+    return out
+
+
+def api_indexes(key: str):
+    """Every index in the store: B+ trees per table + ANN tiers on
+    embeddings, with size and the data version each was built for."""
+    db = STORES[key]
+    out = {"bptree": [], "ann": []}
+    for name in db.tables():
+        ixdir = db.dir / "tables" / name / "_index"
+        if not ixdir.is_dir():
+            continue
+        for p in ixdir.glob("*.bpt"):
+            col, ver = p.stem.rsplit(".v", 1)
+            out["bptree"].append({"table": name, "column": col,
+                                  "version": int(ver),
+                                  "bytes": p.stat().st_size})
+        for p in list(ixdir.glob("hnsw.v*.bin")) + list(ixdir.glob("ivfpq.v*.npz")):
+            kind = "hnsw" if p.name.startswith("hnsw") else "ivfpq"
+            ver = int(p.name.split(".v")[1].split(".")[0])
+            cur = db.table("embeddings").state().version
+            out["ann"].append({"kind": kind, "version": ver,
+                               "current": cur, "stale": ver != cur,
+                               "bytes": p.stat().st_size})
+    # candidate numeric columns for B+ indexing
+    out["indexable"] = {}
+    for name in db.tables():
+        st = db.table(name).state()
+        if st.kind != "timeseries" or not st.files:
+            continue
+        import pyarrow.parquet as pq
+        schema = pq.ParquetFile(db.dir / "tables" / name / st.files[0].path) \
+            .schema_arrow
+        import pyarrow as pa
+        cols = [f.name for f in schema
+                if f.name != "ts" and (pa.types.is_integer(f.type)
+                                       or pa.types.is_floating(f.type))]
+        if cols:
+            out["indexable"][name] = cols
+    out["has_embeddings"] = "embeddings" in db.tables() and \
+        db.table("embeddings").state().rows > 0
+    return out
+
+
+def api_build_index(key: str, body: dict):
+    db = STORES[key]
+    t0 = time.perf_counter()
+    if body.get("ann"):
+        from . import ann
+        r = (ann.build_hnsw(db) if body["ann"] == "hnsw"
+             else ann.build_ivfpq(db))
+        r["ms"] = round((time.perf_counter() - t0) * 1e3)
+        return r
+    r = db.table(body["table"]).create_index(body["column"])
+    r["ms"] = round((time.perf_counter() - t0) * 1e3)
+    return r
+
+
+def api_maintenance(key: str, body: dict):
+    db = STORES[key]
+    op = body["op"]
+    t0 = time.perf_counter()
+    if op == "compact":
+        r = db.table(body["table"]).compact()
+    elif op == "vacuum":
+        r = db.vacuum(retain_versions=int(body.get("retain", 3)),
+                      dry_run=bool(body.get("dry_run", False)))
+    elif op == "delete_range":
+        r = db.table(body["table"]).delete_range(int(body["t0"]),
+                                                 int(body["t1"]))
+    else:
+        raise ValueError(f"unknown maintenance op {op!r}")
+    r["ms"] = round((time.perf_counter() - t0) * 1e3)
+    return r
+
+
+def api_query(key: str, body: dict):
+    db = STORES[key]
+    kind = body.get("type")
+    t_start = time.perf_counter()
+    if kind == "sql":
+        df = db.sql(body["sql"]).head(200)
+        return {"columns": list(df.columns),
+                "rows": json.loads(df.to_json(orient="values")),
+                "ms": round((time.perf_counter() - t_start) * 1e3, 1)}
+    if kind == "text":
+        floor = body.get("floor")
+        kw = {}
+        if body.get("floor_mode") == "percentile" and floor is not None:
+            kw["percentile"] = float(floor)
+        elif body.get("floor_mode") == "min_score" and floor is not None:
+            kw["min_score"] = float(floor)
+        hits, stats = db.search(
+            body["text"], k=int(body.get("k", 8)),
+            nprobe=int(body.get("nprobe", 3)),
+            method=body.get("method", "auto"),
+            neg_weight=float(body.get("neg_weight", 0.5)),
+            t0=body.get("t0"), t1=body.get("t1"),
+            streams=body.get("streams") or None,
+            rerank=bool(body.get("rerank")),
+            rerank_top=int(body.get("rerank_top", 10)), **kw)
+        return {"hits": hits, "stats": stats,
+                "ms": round((time.perf_counter() - t_start) * 1e3, 1)}
+    if kind == "context":
+        # PRODUCT SURFACE = MEASURED SURFACE: this is the exact
+        # search_set the ledger benchmarks (stable-benchmark
+        # directive — the old captioned search_context served here
+        # while acceptance was measured elsewhere; never again).
+        from elidedb.scenario import search_set
+        want = int(body.get("k", 10))
+        scoped = bool(body.get("streams") or body.get("t0") is not None
+                      or body.get("t1") is not None)
+        # scoped queries must rank a large pool BEFORE the scope
+        # filters below — filtering the unscoped top-k starves the
+        # result. Cap sizing differs by tier: audit_n (search_set's
+        # "stratified sample" doc) is DEAD — never passed to
+        # _binding_audit, which loops the SAM-3.1 tracker over every
+        # element of `chosen` (scenario.py:390-392, 509-512), so audit
+        # cost grows with k_max, not a fixed sample. A scoped+audited
+        # query therefore gets a small pool; scoped+fast can afford 400.
+        pool = (400 if not body.get("rerank") else max(4 * want, 40)) \
+            if scoped else want
+        # ENGINE. The Desk called search_set unconditionally, which is
+        # the TEACHER: 59 s cold, 8.4 s for a warm NEW query, because it
+        # loads PE + SigLIP2 + IV2 + V-JEPA + X-CLIP and runs every
+        # channel over the corpus. The teacher is a LABELLER, not a
+        # serving path. The student answers the same question in ~27 ms
+        # from precomputed columns and is now the default.
+        from .student import available as _st_ok, search_student
+        engine = body.get("engine") or ("student" if _st_ok()
+                                        else "teacher")
+        if engine == "student" and _st_ok() and not body.get("rerank"):
+            r = search_student(db, body["text"], k_max=pool)
+        else:
+            engine = "teacher"
+            r = search_set(db, body["text"],
+                           purity="audited" if body.get("rerank") else "fast",
+                           k_max=pool)
+        hits = [{"stream": c["stream"], "t0": c["t0"], "t1": c["t1"],
+                 "score": c["score"]} for c in r["clips"]]
+        if body.get("streams"):
+            hits = [h for h in hits if h["stream"] in body["streams"]]
+        lo, hi = body.get("t0"), body.get("t1")
+        if lo is not None:
+            hits = [h for h in hits if h["t1"] >= int(lo)]
+        if hi is not None:
+            hits = [h for h in hits if h["t0"] <= int(hi)]
+        hits = hits[:want]
+        stats = {"channels": r.get("channels", []),
+                 "scored": r.get("scored", 0),
+                 "direction_filtered": r.get("direction_filtered", 0),
+                 "no_match": bool(r.get("no_match")),
+                 "engine": engine,
+                 "set_ms": r.get("ms")}
+        return {"hits": hits, "stats": stats,
+                "ms": round((time.perf_counter() - t_start) * 1e3, 1)}
+    if kind == "predicate":
+        from elidedb.store import QueryStats
+        qs = QueryStats()
+        tab = db.table(body["table"])
+        vals = [float(body["value"])] if body.get("value2") in (None, "") \
+            else [float(body["value"]), float(body["value2"])]
+        out = tab.where(body["column"], body["op"], *vals, stats=qs).to_pandas()
+        return {"columns": list(out.columns[:8]),
+                "rows": json.loads(out.head(50).iloc[:, :8].to_json(
+                    orient="values")),
+                "count": len(out),
+                "stats": {"files": f"{qs.files_touched}/{qs.files_total}",
+                          "bytes_touched": qs.bytes_touched,
+                          "corpus_bytes": qs.corpus_bytes,
+                          "elided_pct": round(qs.elided_pct, 3)},
+                "ms": round((time.perf_counter() - t_start) * 1e3, 1)}
+    if kind == "clip":
+        hits, stats = db.search_clip(body["stream"], int(body["t0"]),
+                                     int(body["t1"]), k=int(body.get("k", 8)),
+                                     method=body.get("method", "auto"))
+        return {"hits": hits, "stats": stats,
+                "ms": round((time.perf_counter() - t_start) * 1e3, 1)}
+    if kind == "window":
+        w, stats = db.window(int(body["t0"]), int(body["t1"]),
+                             tables=body.get("tables") or None)
+        out = {"tables": {}, "ms": round(stats.wall_ms, 1),
+               "stats": {"files": f"{stats.files_touched}/{stats.files_total}",
+                         "bytes_touched": stats.bytes_touched,
+                         "corpus_bytes": stats.corpus_bytes,
+                         "elided_pct": round(stats.elided_pct, 3),
+                         "rows": stats.rows_returned}}
+        from elidedb.video import FrameSet
+        for name, v in w.items():
+            if isinstance(v, FrameSet):
+                out["tables"][name] = {"kind": "frames", "count": len(v),
+                                       "streams": v.streams()}
+            else:
+                df = v.to_pandas().head(6)
+                out["tables"][name] = {
+                    "kind": "rows", "count": len(v),
+                    "columns": list(df.columns),
+                    "head": json.loads(df.to_json(orient="values"))}
+        return out
+    raise ValueError(f"unknown query type {kind!r}")
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *a):  # quiet
+        pass
+
+    def _send(self, code, body, ctype="application/json", cache=False):
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        if READONLY:
+            # the public demo is pinged cross-origin by the landing
+            # page to tell "awake" from "cold starting"
+            self.send_header("Access-Control-Allow-Origin", "*")
+        if cache:
+            self.send_header("Cache-Control", "max-age=3600")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_media(self, body, ctype):
+        """Range-aware send: <video> elements (Safari especially) seek via
+        byte-range requests; a byte-range database ought to honor them."""
+        rng = self.headers.get("Range")
+        total = len(body)
+        if rng and rng.startswith("bytes="):
+            spec = rng[6:].split("-")
+            a = int(spec[0]) if spec[0] else 0
+            b = int(spec[1]) if len(spec) > 1 and spec[1] else total - 1
+            b = min(b, total - 1)
+            chunk = body[a:b + 1]
+            self.send_response(206)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Range", f"bytes {a}-{b}/{total}")
+            self.send_header("Accept-Ranges", "bytes")
+            self.send_header("Content-Length", str(len(chunk)))
+            self.send_header("Cache-Control", "max-age=3600")
+            self.end_headers()
+            self.wfile.write(chunk)
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Accept-Ranges", "bytes")
+        self.send_header("Content-Length", str(total))
+        self.send_header("Cache-Control", "max-age=3600")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _json(self, obj, code=200):
+        self._send(code, json.dumps(obj).encode())
+
+    def do_GET(self):
+        u = urlparse(self.path)
+        q = {k: v[0] for k, v in parse_qs(u.query).items()}
+        try:
+            if u.path == "/" or u.path == "/index.html":
+                html = (Path(__file__).parent / "desk_ui.html").read_bytes()
+                return self._send(200, html, "text/html; charset=utf-8")
+            if u.path == "/api/stores":
+                discover()
+                return self._json([store_summary(k) for k in STORES])
+            if u.path == "/api/architecture":
+                return self._json(api_architecture(q["store"]))
+            if u.path == "/api/bytes":
+                return self._json(api_bytes(q["store"]))
+            if u.path == "/api/dbinternals":
+                return self._json(api_dbinternals(q["store"],
+                                                  q.get("table")))
+            if u.path == "/api/map":
+                return self._json(api_map(q["store"]))
+            if u.path == "/api/geo":
+                return self._json(api_geo(q["store"]))
+            if u.path == "/api/analytics":
+                return self._json(api_analytics(q["store"]))
+            if u.path == "/api/history":
+                db = STORES[q["store"]]
+                return self._json(db.table(q["table"]).history())
+            if u.path == "/api/storage":
+                return self._json(api_storage(q["store"], q["table"]))
+            if u.path == "/api/indexes":
+                return self._json(api_indexes(q["store"]))
+            if u.path == "/api/schema":
+                return self._json(api_schema(q["store"], q.get("table")))
+            if u.path == "/api/thumb":
+                jpg = api_thumb(q["store"], q.get("stream", ""),
+                                int(q["t"]), int(q.get("w", "360")))
+                if jpg is None:
+                    return self._json({"error": "no frame"}, 404)
+                return self._send(200, jpg, "image/jpeg", cache=True)
+            if u.path == "/api/version":
+                return self._json({"build": build_id(),
+                                   "readonly": READONLY})
+            if u.path == "/api/clip":
+                mp4 = api_clip(q["store"], q.get("stream", ""),
+                               int(q["t0"]), int(q["t1"]),
+                               int(q.get("w", "640")))
+                if isinstance(mp4, dict):        # structured failure
+                    return self._json(mp4, 422)
+                if mp4 is None:
+                    return self._json({"error": "no frames in window"}, 404)
+                return self._send_media(mp4, "video/mp4")
+            return self._json({"error": "not found"}, 404)
+        except Exception as e:  # surface, don't die
+            return self._json({"error": f"{type(e).__name__}: {e}"}, 500)
+
+    def do_POST(self):
+        u = urlparse(self.path)
+        try:
+            n = int(self.headers.get("Content-Length", 0))
+            body = json.loads(self.rfile.read(n) or b"{}")
+            if u.path == "/api/query":
+                return self._json(api_query(body["store"], body))
+            # mutating operations: refused in the public demo. Queries
+            # stay open; the stores stay exactly as shipped.
+            if READONLY and u.path in ("/api/build_index",
+                                       "/api/maintenance"):
+                return self._json(
+                    {"error": "this deployment is read only"}, 403)
+            if u.path == "/api/build_index":
+                return self._json(api_build_index(body["store"], body))
+            if u.path == "/api/maintenance":
+                return self._json(api_maintenance(body["store"], body))
+            return self._json({"error": "not found"}, 404)
+        except Exception as e:
+            return self._json({"error": f"{type(e).__name__}: {e}"}, 500)
+
+
+def _warm():
+    """Pre-build the per-store matrix caches AND load the text tower so the
+    FIRST query of a session is as fast as the hundredth. Off the request
+    path; measured: an unwarmed first query pays ~1 s of model load."""
+    try:
+        from elidedb.embeddings import embed_text
+        embed_text("warmup")
+    except Exception:
+        pass
+    # the STUDENT is the serving path, so warm what it needs: the PE
+    # text tower and its own weights. Measured cold 10.2 s (almost all
+    # of it the text encoder), warm 25-41 ms - so this thread is the
+    # difference between the first UI query feeling broken and feeling
+    # instant.
+    try:
+        from elidedb.student import available, search_student
+        if available():
+            for _k, _db in list(STORES.items()):
+                search_student(_db, "the robot opens the drawer", k_max=5)
+                break
+    except Exception:
+        pass
+    for key, db in list(STORES.items()):
+        try:
+            from elidedb.embeddings import _vec_table
+            _vec_table(db, "embeddings")
+            from elidedb.verified import _recording_spans, _verdict_map
+            _verdict_map(db)
+            _recording_spans(db)
+        except Exception:
+            pass
+        try:
+            _vec_table(db, "motion_vectors")   # builds the mmap sidecar
+        except Exception:
+            pass
+        try:
+            from elidedb.subjects import subject_prefixes
+            subject_prefixes(db)               # mines on first run, cached
+        except Exception:
+            pass
+
+
+def main():
+    global LAKE
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", default=os.environ.get("DESK_ROOT",
+                                                     str(LAKE)))
+    ap.add_argument("--port", type=int,
+                    default=int(os.environ.get("PORT", "8787")))
+    ap.add_argument("--host", default=os.environ.get("DESK_HOST",
+                                                     "127.0.0.1"))
+    ap.add_argument("--open", action="store_true")
+    args = ap.parse_args()
+    LAKE = Path(args.root).resolve()
+    discover()
+    threading.Thread(target=_warm, daemon=True).start()
+    srv = ThreadingHTTPServer((args.host, args.port), Handler)
+    print(f"ElideDB Desk: http://{args.host}:{args.port}  "
+          f"({len(STORES)} stores under {LAKE})"
+          f"{'  [read only]' if READONLY else ''}")
+    if args.open:
+        import subprocess
+        threading.Timer(0.4, lambda: subprocess.run(
+            ["open", f"http://localhost:{args.port}"])).start()
+    srv.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

python/elidedb/device.py

@@ -0,0 +1,56 @@
+"""One device policy for every model loader.
+
+The store format is portable; the model loaders must be too. Every
+loader asks this module instead of probing torch itself, so a cloud
+CPU box, an Apple laptop, and a CUDA node run the same code with the
+right placement:
+
+  ELIDEDB_DEVICE  force a device ("cpu", "mps", "cuda"); default is
+                  mps when available, else cuda, else cpu
+  ELIDEDB_DTYPE   force a torch dtype name; default float16 on
+                  mps/cuda and bfloat16 on cpu (halves resident
+                  memory against fp32, and fp16 matmuls are not a
+                  real CPU option)
+"""
+from __future__ import annotations
+
+import os
+
+
+def text_only():
+    """Serving deployments set ELIDEDB_TEXT_ONLY=1: the query path
+    encodes TEXT only (every frame vector is precomputed at ingest),
+    so the loaders drop their vision towers after load and roughly
+    halve resident memory. Ingest machines leave it unset."""
+    return os.environ.get("ELIDEDB_TEXT_ONLY", "") == "1"
+
+
+def strip_vision(model, *attrs):
+    """Release the named submodules when serving text-only."""
+    if not text_only():
+        return model
+    import gc
+    for a in attrs:
+        if hasattr(model, a):
+            setattr(model, a, None)
+    gc.collect()
+    return model
+
+
+def pick():
+    import torch
+    dev = os.environ.get("ELIDEDB_DEVICE", "").strip()
+    if not dev:
+        if torch.backends.mps.is_available():
+            dev = "mps"
+        elif torch.cuda.is_available():
+            dev = "cuda"
+        else:
+            dev = "cpu"
+    name = os.environ.get("ELIDEDB_DTYPE", "").strip()
+    if name:
+        dtype = getattr(torch, name)
+    else:
+        dtype = torch.float16 if dev in ("mps", "cuda") \
+            else torch.bfloat16
+    return dev, dtype

python/elidedb/dinov3.py

@@ -0,0 +1,91 @@
+"""DINOv3 — the teacher's substrate. One backbone, three granularities.
+
+Frames (every frame -> scene series), track crops (identity descriptors)
+and, later, whatever the FDNN student distills from. Chosen over the
+CLIP family for everything appearance-shaped because it has NO text
+tower: it was never trained to collapse instances into nameable
+categories, which is precisely the failure that made a red and a green
+pepper the same object under text-aligned encoders. The instance-level
+numbers agree (+10.9 GAP retrieval over DINOv2, which already beat CLIP
+at instance top-1).
+
+Gated weights: the user accepted Meta's license on HF (2026-08-01).
+
+No resizing cleverness: everything goes to IMG px square through the
+processor, because identity compares crops to crops and frames to
+frames — never one to the other — so a shared canonical size keeps
+each comparison internally consistent.
+"""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+_M = {}
+
+# ConvNeXt-Tiny, not ViT-S, and the reason is numerical, not taste:
+# the DINOv3 ViT variants OVERFLOW FP16 on MPS - every embedding NaN,
+# and a NaN loses every >= comparison silently, so the failure mode was
+# not an error but "12,583 tracks, 12,583 objects, zero recurrence".
+# ViT-S works in fp32 at ~2x its fp16 time, which makes it slower than
+# ConvNeXt-Tiny in fp16 - and ConvNeXt measured AUC 0.9994 on the
+# corpus's proven pairs (vs yolo26n-reid 0.9047). Faster AND stronger,
+# so the 768-d (vs 384) table cost is accepted.
+MID = os.environ.get("ELIDEDB_DINOV3",
+                     "facebook/dinov3-convnext-tiny-pretrain-lvd1689m")
+IMG = int(os.environ.get("ELIDEDB_DINOV3_SZ", "224"))
+BATCH = int(os.environ.get("ELIDEDB_DINOV3_BATCH", "64"))
+
+
+def _load(mid=None):
+    mid = mid or MID
+    if _M.get("mid") == mid:
+        return _M
+    import torch
+    from transformers import AutoImageProcessor, AutoModel
+    from .device import pick
+    dev, dtype = pick()
+    if "vit" in mid.rsplit("/", 1)[-1]:
+        dtype = torch.float32          # fp16 overflow, see above
+    _M.clear()
+    _M["proc"] = AutoImageProcessor.from_pretrained(mid)
+    _M["model"] = AutoModel.from_pretrained(
+        mid, dtype=dtype, low_cpu_mem_usage=True).to(dev).eval()
+    _M["dev"], _M["dtype"], _M["mid"] = dev, dtype, mid
+    _M["torch"] = torch
+    return _M
+
+
+def embed(images, batch=None, mid=None):
+    """(N, D) unit-norm float32 embeddings for a list of HWC uint8 arrays.
+
+    Pooled (CLS) output — the global instance/scene vector, the thing
+    retrieval compares. Patch tokens exist but are a different product
+    for a different consumer; nothing here should quietly average them.
+    """
+    m = _load(mid)
+    torch = m["torch"]
+    out = []
+    batch = batch or BATCH
+    for i in range(0, len(images), batch):
+        chunk = [np.ascontiguousarray(x[..., :3]) for x in
+                 images[i:i + batch]]
+        px = m["proc"](images=chunk, return_tensors="pt",
+                       size={"height": IMG, "width": IMG})
+        px = px["pixel_values"].to(m["dev"], m["dtype"])
+        with torch.no_grad():
+            r = m["model"](pixel_values=px)
+        v = r.pooler_output.float()
+        v = v / v.norm(dim=-1, keepdim=True).clamp_min(1e-8)
+        v = v.cpu().numpy().astype(np.float32)
+        # FAIL LOUD. The ViT fp16 overflow produced NaN vectors that
+        # scored 0.0 AUC without a single exception - every comparison
+        # quietly False. Garbage must stop the run, not grade it.
+        if np.isnan(v).any():
+            raise FloatingPointError(
+                f"{_M['mid']}: NaN embeddings (dtype {_M['dtype']}) - "
+                "use fp32 for ViT variants")
+        out.append(v)
+    return (np.concatenate(out) if out
+            else np.zeros((0, 384), np.float32))

python/elidedb/distill.py

@@ -0,0 +1,176 @@
+"""CHANNEL STUDENTS: an FDNN head per teacher, over vectors already computed.
+
+The teachers - PE, SigLIP2 so400m, InternVideo2-1B, XCLIP, V-JEPA2 -
+were built for accuracy and they are not deployable. Measured per
+episode at write time: pe 1.17 s, sig2 0.70, iv2 1.14, xclip 0.49,
+before V-JEPA2 runs twice more. That is the retrieval path costing an
+order of magnitude more than the entire rest of the write, which makes
+the teachers part of the product instead of part of the training.
+
+A teacher's job is to be RIGHT. A student's job is to be THERE.
+
+THE INPUT IS ALREADY PAID FOR. The write path streams every frame
+through FDNN-V and stores a 1152-d vector per frame, at 0.020 s per
+episode. Every channel output is a function of the same pixels, so
+every channel can be a small head over those vectors instead of a
+second pass over the video. The teacher is run ONCE, offline, to make
+training pairs; after that it never touches an ingest again.
+
+SKELETON, not a bag of layers. Each teacher pools a SPAN of frames into
+one vector - a window for PE and SigLIP2, a whole clip for IV2, XCLIP
+and V-JEPA2 - so the student mirrors that shape:
+
+    attention pool over the span's frame vectors   (one learned query,
+                                                    the teacher's own
+                                                    aggregation step)
+    pre-norm residual MLP -> the teacher's dimension
+    L2 normalise                                   (every consumer
+                                                    compares by cosine,
+                                                    so the norm is not
+                                                    part of the signal)
+
+Mean pooling was the obvious first choice and it is wrong for the same
+reason it is wrong in the teachers: a window's meaning is carried by a
+few frames, and averaging buries them under the static ones.
+
+Inference is deliberately NUMPY. The head is two small matmuls; running
+them under a training framework costs more in dispatch than the
+arithmetic, and the write path should not have to import one.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+# teacher output dimensions, by channel
+DIMS = {"pe": 1024, "sig2": 1152, "iv2": 512, "xclip": 768,
+        "vjepa": 1024, "act": 174}
+FDNNV_D = 1152
+
+
+def _l2(x, axis=-1):
+    return x / (np.linalg.norm(x, axis=axis, keepdims=True) + 1e-8)
+
+
+class Head:
+    """A distilled channel. Loads from .npz, runs in numpy."""
+
+    def __init__(self, w: dict):
+        self.q = w["q"]                 # (d_in,)      pooling query
+        self.W1, self.b1 = w["W1"], w["b1"]
+        self.W2, self.b2 = w["W2"], w["b2"]
+        self.Wp, self.bp = w["Wp"], w["bp"]
+        self.g, self.beta = w["g"], w["beta"]
+
+    @staticmethod
+    def load(path):
+        z = np.load(path)
+        return Head({k: z[k] for k in z.files})
+
+    def pool(self, X):
+        """Attention-pool (n_frames, d) -> (d,) with one learned query."""
+        if len(X) == 0:
+            return np.zeros(self.q.shape[0], np.float32)
+        s = X @ self.q
+        s -= s.max()
+        a = np.exp(s)
+        a /= a.sum() + 1e-8
+        return (a[:, None] * X).sum(0)
+
+    def __call__(self, X):
+        """(n_frames, 1152) frame vectors of one span -> teacher vector."""
+        h = self.pool(np.asarray(X, np.float32))
+        # pre-norm: the pooled vector's scale varies with span length
+        h = self.g * (h - h.mean()) / (h.std() + 1e-6) + self.beta
+        z = np.maximum(h @ self.W1 + self.b1, 0)          # ReLU
+        h = h + z @ self.W2 + self.b2                     # residual
+        return _l2(h @ self.Wp + self.bp)
+
+    def batch(self, spans):
+        """Many spans at once - the write path's actual call shape."""
+        return np.stack([self(X) for X in spans]) if spans else \
+            np.zeros((0, self.Wp.shape[1]), np.float32)
+
+
+def pairs(store, channel, frames_table="frame_vectors"):
+    """(list of frame-vector spans, teacher matrix) for one channel.
+
+    A teacher row carries ts..t1; the student sees exactly the frame
+    vectors inside that span, which is the same evidence the teacher
+    had and no more. Spans with no frames are dropped rather than
+    zero-filled - a student taught to map emptiness to a real vector
+    learns to hallucinate.
+    """
+    import pyarrow.compute as pc
+    tv = store.table(f"{channel}_vectors").scan()
+    fv = store.table(frames_table).scan()
+    fts = np.asarray(fv.column("ts").to_pylist(), np.int64)
+    fst = np.asarray([str(s) for s in fv.column("stream").to_pylist()])
+    F = np.asarray(fv.column("vector").to_pylist(), np.float32)
+
+    order = np.argsort(fts, kind="stable")
+    fts, fst, F = fts[order], fst[order], F[order]
+
+    t0 = np.asarray(tv.column("ts").to_pylist(), np.int64)
+    t1 = np.asarray(tv.column("t1").to_pylist(), np.int64)
+    tst = np.asarray([str(s) for s in tv.column("stream").to_pylist()])
+    T = _l2(np.asarray(tv.column("vector").to_pylist(), np.float32))
+
+    X, Y, keys = [], [], []
+    for i in range(len(t0)):
+        lo = np.searchsorted(fts, t0[i], "left")
+        hi = np.searchsorted(fts, t1[i], "right")
+        if hi <= lo:
+            continue
+        sel = slice(lo, hi)
+        m = fst[sel] == tst[i]
+        if not m.any():
+            continue
+        X.append(F[sel][m])
+        Y.append(T[i])
+        keys.append((tst[i], int(t0[i])))
+    return X, (np.stack(Y) if Y else np.zeros((0, 1), np.float32)), keys
+
+
+def init(d_in=FDNNV_D, d_out=1024, hidden=512, seed=0):
+    r = np.random.default_rng(seed)
+    def n(*s):
+        return (r.normal(size=s) / np.sqrt(s[0])).astype(np.float32)
+    return {"q": n(d_in), "W1": n(d_in, hidden), "b1": np.zeros(hidden, np.float32),
+            "W2": n(hidden, d_in), "b2": np.zeros(d_in, np.float32),
+            "Wp": n(d_in, d_out), "bp": np.zeros(d_out, np.float32),
+            "g": np.ones(d_in, np.float32), "beta": np.zeros(d_in, np.float32)}
+
+
+def fidelity(head, X, Y):
+    """Cosine to the teacher, ITS TRIVIAL BASELINE, and rank agreement.
+
+    Cosine alone is not weak, it is actively misleading here, and the
+    first PE student proved it: 0.9168 test cosine, which reads like a
+    working student until you compute what a CONSTANT prediction of the
+    corpus mean scores - 0.8629. The teacher's space is anisotropic
+    (mean pairwise cosine 0.885), so almost all of that 0.92 is the
+    shared mean and almost none of it is the episode. Nearest-neighbour
+    agreement was 0.005.
+
+    So every report carries `mean_baseline` next to `cosine`, and the
+    number that decides whether a student ships is rank agreement -
+    ranking is the only thing a retrieval channel is ever used for.
+    """
+    P = head.batch(X)
+    cos = float(np.mean(np.sum(P * Y, 1)))
+    mu = _l2(Y.mean(0))
+    base = float(np.mean(Y @ mu))
+    n = min(len(P), 400)
+    Sp, St = P[:n] @ P[:n].T, Y[:n] @ Y[:n].T
+    np.fill_diagonal(Sp, -9); np.fill_diagonal(St, -9)
+    top1 = float(np.mean(Sp.argmax(1) == St.argmax(1)))
+    k = min(10, n - 1)
+    rp = np.argsort(-Sp, 1)[:, :k]
+    rt = np.argsort(-St, 1)[:, :k]
+    rec = float(np.mean([len(set(a) & set(b)) / k for a, b in zip(rp, rt)]))
+    return {"cosine": round(cos, 4), "mean_baseline": round(base, 4),
+            "lift_over_mean": round(cos - base, 4),
+            "nn_top1": round(top1, 4), "nn_recall@10": round(rec, 4)}

python/elidedb/embeddings.py

@@ -0,0 +1,744 @@
+"""Semantic layer over Parquet: embeddings and centroids are tables like
+everything else — versioned by the log, readable by DuckDB, no sidecar
+binary formats. Vectors are fixed_size_list<float32>[d] columns.
+
+Retrieval is two-stage (learned-cell IVF): rank cluster centroids, scan the
+top nprobe cells exactly in full space; HDBSCAN noise is always scanned so
+the prune can cost recall nothing. All ranking is one numpy matmul — exact,
+simple, and fast far past 100k windows."""
+from __future__ import annotations
+
+import time
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.compute as pc
+import pyarrow.parquet as pq
+
+_MODEL_CACHE = {}
+DEFAULT_MODEL = "mlx-community/siglip-so400m-patch14-384"
+
+# Ingest cost is ALL model, not storage: measured on an M-series machine,
+# byte-range decode runs at 2.7 ms/frame while the 384px tower runs at
+# 90.3 ms/frame — 97% of ingest is the encoder. So the encoder is a choice,
+# not a constant.
+#
+#   quality  siglip-so400m-patch14-384   90.3 ms/frame   1152-d   (default)
+#   fast     siglip-so400m-patch14-224   27.7 ms/frame   1152-d   3.3x faster
+#
+# `fast` is the SAME model and the same output space, fed 224px instead of
+# 384px, so it is 256 patches per image instead of 729. Vectors from the two
+# are NOT interchangeable — an index must be built and queried with one of
+# them, which is why the model id is recorded in the table's metadata and the
+# query path reads it back.
+MODELS = {
+    "quality": "mlx-community/siglip-so400m-patch14-384",
+    "fast": "mlx-community/siglip-so400m-patch14-224",
+}
+
+
+def resolve_model(name):
+    """Accept a preset name ('fast'/'quality') or a raw HF model id."""
+    return MODELS.get(name, name) if name else DEFAULT_MODEL
+
+
+# PORTABILITY: the mlx build of siglip-so400m is a straight conversion
+# of the google checkpoint, so the SAME weights run through
+# transformers on any machine and land in the same embedding space.
+# Backend is auto-detected (mlx where it imports, torch elsewhere) and
+# can be forced with ELIDEDB_TEXT_BACKEND=torch for parity testing.
+_HF_EQUIV = {
+    "mlx-community/siglip-so400m-patch14-384":
+        "google/siglip-so400m-patch14-384",
+    "mlx-community/siglip-so400m-patch14-224":
+        "google/siglip-so400m-patch14-224",
+}
+
+
+def _backend():
+    if "backend" not in _MODEL_CACHE:
+        import os
+        forced = os.environ.get("ELIDEDB_TEXT_BACKEND", "").strip()
+        if forced:
+            _MODEL_CACHE["backend"] = forced
+        else:
+            try:
+                import mlx_embeddings  # noqa: F401
+                _MODEL_CACHE["backend"] = "mlx"
+            except ImportError:
+                _MODEL_CACHE["backend"] = "torch"
+    return _MODEL_CACHE["backend"]
+
+
+def _load_model(model_id):
+    if model_id not in _MODEL_CACHE:
+        from mlx_embeddings.utils import load
+        _MODEL_CACHE[model_id] = load(model_id)
+    return _MODEL_CACHE[model_id]
+
+
+def _load_torch(model_id):
+    key = ("torch", model_id)
+    if key not in _MODEL_CACHE:
+        from transformers import AutoModel, AutoProcessor
+
+        from .device import pick, strip_vision
+        dev, dtype = pick()
+        hf = _HF_EQUIV.get(model_id, model_id)
+        m = AutoModel.from_pretrained(
+            hf, dtype=dtype, low_cpu_mem_usage=True).to(dev).eval()
+        m = strip_vision(m, "vision_model")
+        _MODEL_CACHE[key] = (m, AutoProcessor.from_pretrained(hf), dev)
+    return _MODEL_CACHE[key]
+
+
+def _embed_images(images, model_id):
+    if _backend() == "torch":
+        import torch
+        model, processor, dev = _load_torch(resolve_model(model_id))
+        iv = processor(images=images, return_tensors="pt")
+        with torch.no_grad():
+            out = model.get_image_features(
+                pixel_values=iv["pixel_values"].to(
+                    dev, model.dtype))
+        out = out.float().cpu().numpy().astype(np.float32)
+        return out / np.linalg.norm(out, axis=1, keepdims=True)
+    import mlx.core as mx
+    model, processor = _load_model(resolve_model(model_id))
+    iv = processor(images=images, return_tensors="np")
+    out = np.array(model.get_image_features(mx.array(iv["pixel_values"])),
+                   dtype=np.float32)
+    return out / np.linalg.norm(out, axis=1, keepdims=True)
+
+
+def embed_text(text, model_id=DEFAULT_MODEL):
+    if _backend() == "torch":
+        import torch
+        model, processor, dev = _load_torch(resolve_model(model_id))
+        try:
+            max_len = int(
+                model.config.text_config.max_position_embeddings)
+        except AttributeError:
+            max_len = 64
+        ti = processor(text=[text], padding="max_length",
+                       max_length=max_len, truncation=True,
+                       return_tensors="pt")
+        with torch.no_grad():
+            v = model.get_text_features(
+                input_ids=ti["input_ids"].to(dev))
+        v = v[0].float().cpu().numpy().astype(np.float32)
+        return v / np.linalg.norm(v)
+    import mlx.core as mx
+    model, processor = _load_model(resolve_model(model_id))
+    # Each checkpoint has its own text context (so400m-384: 64 tokens,
+    # so400m-224: 16). Ask the model rather than assuming.
+    try:
+        max_len = int(model.config.text_config.max_position_embeddings)
+    except AttributeError:
+        max_len = 64
+    ti = processor(text=[text], padding="max_length", max_length=max_len,
+                   truncation=True, return_tensors="np")
+    v = np.array(model.get_text_features(mx.array(ti["input_ids"])),
+                 dtype=np.float32)[0]
+    return v / np.linalg.norm(v)
+
+
+_MAT_CACHE: dict = {}
+
+
+def _vec_table(store, name="embeddings", version=None, column="vector"):
+    """Vector table + MEMORY-MAPPED matrix, cached per log version.
+
+    Two generations of this function materialized the matrix in RAM. At
+    pilot scale that broke: bridge-full's 180k x 1152 embeddings are 0.83 GB
+    of data but cost +4.3 GB peak RSS to load (parquet decode + Arrow
+    chunks + combine copy + the cache holding table AND matrix), and the
+    desk warms every store — 7 GB before the first query. The fix is the
+    store's own law applied to vectors: mmap for reads. The matrix is
+    materialized ONCE per (table, version) into a raw .npy sidecar, then
+    every process maps it — RSS is only the pages a query touches, startup
+    costs a file open, and the OS page cache decides residency.
+
+    Row alignment: the sidecar is written from the same scan() that serves
+    the meta columns; scan's ts sort is stable over a deterministic file
+    order, so a later projected scan yields the identical permutation. A
+    length mismatch (e.g. sidecar from a dead version) forces a rebuild.
+    The parquet remains the source of truth — a sidecar is disposable.
+    """
+    import os
+    import uuid as _uuid
+    ver = store.table(name).state().version if version is None else version
+    key = (str(store.dir), name, column, ver)
+    if key in _MAT_CACHE:
+        return _MAT_CACHE[key]
+
+    tab = store.table(name)
+    cache_dir = tab.dir / "_cache"
+    npy = cache_dir / f"{column}-v{ver}.npy"
+
+    t = vecs = None
+    if npy.exists():
+        st = tab.state(version)
+        if st.files:
+            names = pq.ParquetFile(
+                tab.dir / st.files[0].path).schema_arrow.names
+            meta_cols = [c for c in names if c != column]
+            t = tab.scan(version=version, columns=meta_cols)
+            vecs = np.load(npy, mmap_mode="r")
+            if len(vecs) != len(t):
+                t = vecs = None                    # stale sidecar: rebuild
+
+    if vecs is None:
+        t_full = tab.scan(version=version)
+        if len(t_full) == 0:
+            extra = ""
+            try:
+                if store.table("frame_vectors").state().files:
+                    extra = (" Per-frame vectors already exist, so this "
+                             "costs a numpy mean, not a GPU pass.")
+            except Exception:
+                pass
+            raise RuntimeError(
+                f"store '{store.name}' has no '{name}' table — run "
+                f"store.embed_windows() first.{extra}")
+        col = t_full.column(column)
+        if isinstance(col, pa.ChunkedArray):
+            col = col.combine_chunks()
+        try:                               # FixedSizeList: flat buffer reshape
+            mat = col.values.to_numpy(zero_copy_only=False) \
+                .astype(np.float32, copy=False).reshape(len(t_full), -1)
+        except Exception:                  # any other layout: the slow road
+            mat = np.stack([np.asarray(v, dtype=np.float32)
+                            for v in col.to_pylist()])
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        tmp = cache_dir / f".{_uuid.uuid4().hex[:8]}.npy"
+        np.save(tmp, np.ascontiguousarray(mat))
+        os.replace(tmp, npy)               # atomic: readers see whole files
+        t = t_full.drop_columns([column])  # meta only — no double storage
+        del t_full, mat, col
+        vecs = np.load(npy, mmap_mode="r")
+
+    if len(_MAT_CACHE) > 8:
+        _MAT_CACHE.clear()
+    _MAT_CACHE[key] = (t, vecs)
+    return t, vecs
+
+
+def pool_windows(store, window_s=2.0, stride_s=None, table="frame_vectors"):
+    """Build the `embeddings` table by POOLING existing per-frame vectors.
+
+    A window embedding is the mean of its frame embeddings. If `frame_vectors`
+    already exists there is nothing to compute with a model: decoding every
+    frame again and re-running SigLIP to reach the same answer is pure waste —
+    on the Bridge store that was 25 minutes of GPU to reproduce a number a
+    numpy mean gives in under a second.
+
+    This is the ordinary database move: two indexes over one scan, not two
+    scans.
+    """
+    fv = store.table(table).scan()
+    if len(fv) == 0:
+        raise RuntimeError(f"'{table}' is empty — run embed_frames() first")
+    win = int(window_s * 1e9)
+    stride = int((stride_s or window_s) * 1e9)
+    t_start = time.time()
+    rows = {"ts": [], "t1": [], "stream": [], "vector": []}
+    for s in sorted(set(fv.column("stream").to_pylist())):
+        sub = fv.filter(pc.equal(fv.column("stream"), s))
+        ts = sub.column("ts").to_numpy()
+        order = np.argsort(ts)
+        ts = ts[order]
+        # zero-copy reshape, NOT to_pylist(): at 1.6M frames the Python-list
+        # road needs ~50 GB; the FixedSizeList buffer is already the matrix
+        col = sub.column("vector")
+        if isinstance(col, pa.ChunkedArray):
+            col = col.combine_chunks()
+        try:
+            vecs = col.values.to_numpy(zero_copy_only=False) \
+                .astype(np.float32, copy=False).reshape(len(sub), -1)[order]
+        except Exception:
+            vecs = np.asarray(col.to_pylist(), dtype=np.float32)[order]
+        t = int(ts[0])
+        while t <= int(ts[-1]):
+            lo, hi = np.searchsorted(ts, [t, t + win])
+            if hi > lo:
+                v = vecs[lo:hi].mean(axis=0)
+                v /= np.linalg.norm(v) + 1e-8
+                rows["ts"].append(t)
+                rows["t1"].append(min(t + win - 1, int(ts[-1])))
+                rows["stream"].append(s)
+                rows["vector"].append(v)
+            t += stride
+    dim = len(rows["vector"][0])
+    # FixedSizeListArray straight from the flat float32 buffer. The
+    # tolist() road materialises n*dim PYTHON floats — at 1.8M frames /
+    # 180k windows that was tens of GB and the process died by jetsam
+    # (exit 137) on the very last stage of a 100 h load.
+    flat = np.ascontiguousarray(
+        np.stack(rows["vector"]).astype(np.float32)).reshape(-1)
+    vec_arr = pa.FixedSizeListArray.from_arrays(pa.array(flat), dim)
+    tbl = pa.table({
+        "ts": pa.array(rows["ts"], pa.int64()),
+        "t1": pa.array(rows["t1"], pa.int64()),
+        "stream": pa.array(rows["stream"]),
+        "vector": vec_arr,
+    })
+    st = store.table("embeddings").state()
+    # `model` must be the id of the model that defines the SPACE — the query
+    # path loads it as the text tower. Student-produced vectors live in the
+    # TEACHER's space, so when the source was written by an engine (model
+    # "fdnnv"), the space id is its `teacher` field. Writing the engine name
+    # here sent "fdnnv" to the HF loader as a repo id.
+    src = store.table(table).state().meta or {}
+    src_model = src.get("model", DEFAULT_MODEL)
+    if src_model in (None, "fdnnv"):
+        src_model = src.get("teacher", DEFAULT_MODEL)
+    meta = {"model": src_model, "built_by": "pooled from frame_vectors",
+            "dim": dim, "window_s": window_s, "source_table": table,
+            "seconds": round(time.time() - t_start, 2)}
+    if st.files:
+        import uuid as _uuid
+
+        from .log import FileEntry
+        from .store import write_parquet
+        fn = f"part-{_uuid.uuid4().hex[:12]}.parquet"
+        p = store.dir / "tables" / "embeddings" / fn
+        write_parquet(tbl, p)
+        tsv = tbl.column("ts").to_numpy()
+        version = store.table("embeddings").log.commit(
+            op="replace", kind="embeddings", schema=str(tbl.schema),
+            add=[FileEntry(fn, len(tbl), p.stat().st_size,
+                           int(tsv.min()), int(tsv.max()))],
+            remove=[f.path for f in st.files], meta=meta)
+    else:
+        version = store.table("embeddings").append(tbl, kind="embeddings",
+                                                   meta=meta)
+    return {"windows": len(tbl), "dim": dim, "version": version,
+            "seconds": meta["seconds"], "source": table}
+
+
+def embed_windows(store, frame_table="frames", window_s=2.0,
+                  frames_per_window=2, model=None, batch=16, stride_s=None,
+                  incremental=True, reuse_frame_vectors=True):
+    """Tumbling windows over every video stream → mean-pooled SigLIP vectors
+    → one commit to the `embeddings` table. Frames come through the same
+    byte-range path queries use.
+
+    If per-frame vectors already exist, they are pooled instead of re-running
+    the model (see `pool_windows`) — same result, no GPU.
+    """
+    if reuse_frame_vectors:
+        try:
+            if store.table("frame_vectors").state().files:
+                return pool_windows(store, window_s, stride_s)
+        except Exception:
+            pass
+    from PIL import Image  # noqa: F401 (decode happens in FrameSet)
+    model = model or DEFAULT_MODEL
+    tab = store.table(frame_table)
+    st = tab.state()
+    win_ns = int(window_s * 1e9)
+    stride_ns = int((stride_s or window_s) * 1e9)
+    frames = tab.scan()
+    streams = sorted(set(frames.column("stream").to_pylist()))
+    # Incremental: only embed windows past what the embeddings table already
+    # covers per stream — adding a new day of footage costs a new day of
+    # embedding, not a re-run of history.
+    done_until = {}
+    if incremental:
+        try:
+            prev = store.table("embeddings").scan()
+            if len(prev):
+                s_arr = prev.column("stream").to_pylist()
+                t1_arr = prev.column("t1").to_pylist()
+                for s_, e_ in zip(s_arr, t1_arr):
+                    done_until[s_] = max(done_until.get(s_, 0), e_)
+        except Exception:
+            pass
+    jobs = []  # (stream, t0, t1)
+    for s in streams:
+        rows = frames.filter(pc.equal(frames.column("stream"), s))
+        ts = rows.column("ts").to_numpy()
+        t = (int(ts[0]) // win_ns) * win_ns
+        while t <= ts[-1]:
+            lo, hi = np.searchsorted(ts, [t, t + win_ns])
+            if hi > lo and t >= done_until.get(s, -1):
+                jobs.append((s, max(t, int(ts[0])),
+                             min(t + win_ns - 1, int(ts[-1]))))
+            t += stride_ns
+    from .video import FrameSet
+    t_start = time.time()
+    if not jobs:
+        return {"windows": 0, "dim": None, "version": None, "seconds": 0.0,
+                "note": "nothing new to embed (incremental)"}
+    recs = {"ts": [], "t1": [], "stream": [], "vector": []}
+    imgs, owners = [], []
+
+    def flush():
+        nonlocal imgs, owners
+        if not imgs:
+            return
+        vecs = _embed_images(imgs, model)
+        for (key, v) in zip(owners, vecs):
+            pooled.setdefault(key, []).append(v)
+        imgs, owners = [], []
+
+    pooled = {}
+    for (s, t0, t1) in jobs:
+        fs = FrameSet(store, frame_table,
+                      frames.filter(pc.and_(
+                          pc.equal(frames.column("stream"), s),
+                          pc.and_(pc.greater_equal(frames.column("ts"), t0),
+                                  pc.less_equal(frames.column("ts"), t1)))))
+        n = len(fs)
+        picks = np.linspace(0, n - 1, min(frames_per_window, n)).round().astype(int)
+        decoded = fs.decode(width=512)
+        for p in picks:
+            if p < len(decoded):
+                from PIL import Image as PILImage
+                imgs.append(PILImage.fromarray(decoded[p][1]))
+                owners.append((s, t0, t1))
+        if len(imgs) >= batch:
+            flush()
+    flush()
+    for (s, t0, t1), vs in pooled.items():
+        v = np.mean(vs, axis=0)
+        v /= np.linalg.norm(v)
+        recs["stream"].append(s)
+        recs["ts"].append(t0)
+        recs["t1"].append(t1)
+        recs["vector"].append(v)
+    dim = len(recs["vector"][0])
+    t = pa.table({
+        "ts": pa.array(recs["ts"], pa.int64()),
+        "t1": pa.array(recs["t1"], pa.int64()),
+        "stream": pa.array(recs["stream"]),
+        "vector": pa.array([v.tolist() for v in recs["vector"]],
+                           pa.list_(pa.float32(), dim)),
+    })
+    version = store.table("embeddings").append(
+        t, kind="embeddings",
+        meta={"model": model, "dim": dim, "window_s": window_s,
+              "source_table": frame_table,
+              "embedded_in_s": round(time.time() - t_start, 1)})
+    return {"windows": len(t), "dim": dim, "version": version,
+            "seconds": round(time.time() - t_start, 1)}
+
+
+def cluster(store, pca_dims=50, min_cluster_size=8):
+    """PCA → HDBSCAN over the embeddings table → cluster ids written back as
+    a new embeddings version + a `centroids` table (full-space, normalized:
+    the coarse stage must rank in the space the fine stage scores in)."""
+    t, vecs = _vec_table(store)
+    from sklearn.decomposition import PCA
+    import hdbscan
+    red = PCA(n_components=min(pca_dims, len(vecs), vecs.shape[1]),
+              random_state=0).fit_transform(vecs)
+    labels = hdbscan.HDBSCAN(min_cluster_size=min_cluster_size).fit_predict(red)
+    out = t.drop_columns(["cluster"]) if "cluster" in t.column_names else t
+    out = out.append_column("cluster", pa.array(labels.astype("int32")))
+    # replace = remove old files + add the re-clustered ones, one commit
+    st = store.table("embeddings").state()
+    log = store.table("embeddings").log
+    import pyarrow.parquet as pq
+    import uuid as _uuid
+    fname = f"part-{_uuid.uuid4().hex[:12]}.parquet"
+    from .store import write_parquet
+    write_parquet(out, store.dir / "tables" / "embeddings" / fname)
+    from .log import FileEntry
+    p = store.dir / "tables" / "embeddings" / fname
+    tsv = out.column("ts").to_numpy()
+    log.commit(op="recluster", kind="embeddings", schema=str(out.schema),
+               add=[FileEntry(fname, len(out), p.stat().st_size,
+                              int(tsv.min()), int(tsv.max()))],
+               remove=[f.path for f in st.files],
+               meta={**st.meta, "clusters": int(labels.max() + 1),
+                     "noise": int((labels < 0).sum())})
+    cents = []
+    for c in range(labels.max() + 1):
+        m = vecs[labels == c].mean(axis=0)
+        cents.append(m / np.linalg.norm(m))
+    if cents:
+        ct = pa.table({
+            "ts": pa.array([0] * len(cents), pa.int64()),
+            "cluster": pa.array(range(len(cents)), pa.int32()),
+            "vector": pa.array([c.tolist() for c in cents],
+                               pa.list_(pa.float32(), vecs.shape[1])),
+        })
+        cst = store.table("centroids").state()
+        store.table("centroids").log.commit(
+            op="replace", kind="centroids", schema=str(ct.schema),
+            add=[], remove=[f.path for f in cst.files])
+        store.table("centroids").append(ct, kind="centroids")
+    return {"clusters": int(labels.max() + 1),
+            "noise": int((labels < 0).sum()), "windows": len(out)}
+
+
+def _score_windows(vecs, idx, pos_vecs, neg_vecs, neg_weight):
+    """Compositional scoring over a candidate set.
+
+    - ONE positive term  → plain cosine (classic semantic search).
+    - MANY positive terms → the window's score is the WORST of its per-term
+      cosines (min-pool). This is the compositional AND: 'two people' AND
+      'a laptop' means a clip of two people with NO laptop scores low on the
+      laptop term and is therefore rejected — the fix for 'it returns every
+      clip with two people'.
+    - negative terms      → each subtracts its cosine (weighted), so
+      '... NOT a phone' pushes phone-heavy frames down.
+    """
+    cand = vecs[idx]                          # [m, d]
+    pos = cand @ pos_vecs.T                    # [m, n_pos]
+    score = pos.min(axis=1)                    # min-pool = AND
+    if neg_vecs is not None and len(neg_vecs):
+        score = score - neg_weight * (cand @ neg_vecs.T).max(axis=1)
+    return score
+
+
+def _rank(store, q, k, nprobe, merge=True, t0=None, t1=None, streams=None,
+          method="auto", pos_vecs=None, neg_vecs=None, neg_weight=0.5,
+          min_score=None, percentile=None, table="embeddings", ctx=None,
+          column="vector"):
+    t, vecs = _vec_table(store, table, column=column)
+    if table != "embeddings":
+        # The ANN artifacts (HNSW graph, IVF-PQ codes, HDBSCAN centroids) are
+        # built over `embeddings` and index THOSE row ids. Reusing them here
+        # would return neighbours of the wrong table — silently, with
+        # plausible-looking scores. Any other table scans exactly.
+        method = "exact"
+    all_t0 = t.column("ts").to_numpy()
+    all_t1 = t.column("t1").to_numpy()
+    all_s = t.column("stream").to_numpy(zero_copy_only=False)
+    # `q` (the coarse retrieval direction) is the mean of positive terms;
+    # `pos_vecs` carries the individual terms for compositional scoring.
+    if pos_vecs is None:
+        pos_vecs = q[None, :]
+
+    # ---- hybrid retrieval: predicates pushed INTO candidate selection ------
+    # Time and stream are first-class dimensions of this database; vector
+    # search composes with them instead of post-filtering a global top-k
+    # (which silently starves filtered queries of results).
+    pred = np.ones(len(vecs), bool)
+    if t0 is not None:
+        pred &= all_t1 >= t0
+    if t1 is not None:
+        pred &= all_t0 <= t1
+    if streams:
+        pred &= np.isin(all_s, list(streams))
+
+    labels = (t.column("cluster").to_numpy()
+              if "cluster" in t.column_names else None)
+    probed = total_clusters = 0
+    used = "exact"
+
+    idx = scores = None
+    if method in ("auto", "hnsw"):
+        from . import ann
+        hx = ann.load_hnsw(store)
+        if hx is not None:
+            # overfetch beyond k so predicate filtering and segment merging
+            # still see the event's neighborhood, then score exactly
+            fetch = int(min(len(vecs), max(k * 8, 64)))
+            hx.set_ef(max(fetch, 64))
+            cand, _ = hx.knn_query(q, k=fetch)
+            cand = cand[0]
+            cand = cand[pred[cand]]
+            if len(cand) >= min(k, pred.sum()):
+                idx = np.asarray(cand)
+                scores = vecs[idx] @ q
+                used = "hnsw"
+    if idx is None and method in ("auto", "ivfpq"):
+        from . import ann
+        r = ann.search_ivfpq(store, q, k=max(k * 4, 32), nprobe=max(nprobe, 8),
+                             mask=pred) if method == "ivfpq" else None
+        if r is not None and r[0]:
+            idx = np.array([i for i, _ in r[0]])
+            scores = np.array([s for _, s in r[0]])
+            used = "ivfpq"
+    if idx is None:
+        mask = pred.copy()
+        if labels is not None and nprobe > 0:
+            try:
+                _, cents = _vec_table(store, "centroids")
+                total_clusters = len(cents)
+                order = np.argsort(cents @ q)[::-1][:nprobe]
+                probed = len(order)
+                mask &= np.isin(labels, order) | (labels < 0)  # noise stays
+                used = "ivf"
+            except RuntimeError:
+                pass
+        idx = np.where(mask)[0]
+        scores = None
+    scanned = len(idx)
+    # Final score is ALWAYS the compositional/exact function over the
+    # candidate set (the coarse tier only shortlists; it never answers).
+    scores = _score_windows(vecs, idx, pos_vecs, neg_vecs, neg_weight)
+
+    # ---- optional fusion with the context index ----------------------------
+    # Appearance cosines and context cosines live on different scales (SigLIP
+    # image-text similarity is squashed by the modality gap into ~0.01-0.15,
+    # while context vectors are mean-free and spread over most of [-1,1]).
+    # A raw weighted sum would therefore be governed entirely by the context
+    # term regardless of alpha. Standardising each over the CANDIDATE SET
+    # first makes alpha mean what it says.
+    if ctx is not None and len(idx):
+        def _z(a):
+            return (a - a.mean()) / (a.std() + 1e-8)
+        a = float(ctx["alpha"])
+        scores = (1.0 - a) * _z(scores) + a * _z(ctx["vecs"][idx] @ ctx["q"])
+    streams_sel = all_s[idx]
+    w_t0 = all_t0[idx]
+    w_t1 = all_t1[idx]
+
+    # ---- precision floor: an ABSOLUTE cut the user controls ----------------
+    # A percentile keeps only the strongest fraction; min_score is a hard
+    # cosine floor. Either turns "top-k of everything" into "only real hits",
+    # so a query with 6 true matches returns 6, not 50.
+    keep = np.ones(len(idx), bool)
+    if percentile is not None and len(scores):
+        keep &= scores >= np.percentile(scores, percentile)
+    if min_score is not None:
+        keep &= scores >= min_score
+    if not keep.all():
+        idx, scores = idx[keep], scores[keep]
+        streams_sel, w_t0, w_t1 = streams_sel[keep], w_t0[keep], w_t1[keep]
+
+    stats = {"scanned": scanned, "total": len(vecs), "method": used,
+             "clusters_probed": probed, "clusters_total": total_clusters,
+             "predicate_candidates": int(pred.sum()),
+             "after_floor": int(len(idx))}
+
+    if not merge:
+        order = np.argsort(scores)[::-1][:k]
+        hits = [{"stream": str(streams_sel[i]), "t0": int(w_t0[i]),
+                 "t1": int(w_t1[i]), "score": float(scores[i]),
+                 "windows": 1} for i in order]
+        return hits, stats
+    if len(idx) == 0:
+        stats["qualifying_windows"] = 0
+        stats["segments"] = 0
+        return [], stats
+
+    # ---- dynamic segments: merge, don't chunk -------------------------------
+    # Fixed embedding windows are an INDEXING granularity, not an answer
+    # granularity. A result is the maximal run of consecutive qualifying
+    # windows on one stream: a 20 s event comes back as ONE 20 s hit (its
+    # sub-windows are never returned separately), while a query that only
+    # matches 2 s of it comes back as that tight 2 s. "Qualifying" is decided
+    # per query from the score distribution — an absolute cutoff cannot work
+    # because SigLIP cosines live on different scales per query.
+    med = float(np.median(scores))
+    top = float(scores.max())
+    thr = med + 0.55 * (top - med)
+    stats["threshold"] = round(thr, 4)
+    qual = np.where(scores >= thr)[0]
+    order = np.lexsort((w_t0[qual], streams_sel[qual]))
+    qual = qual[order]
+
+    gap_ns = int(np.median(w_t1[qual] - w_t0[qual])) + 1 if len(qual) else 0
+    segs = []
+    for i in qual:
+        s, a, b, sc = (str(streams_sel[i]), int(w_t0[i]), int(w_t1[i]),
+                       float(scores[i]))
+        last = segs[-1] if segs else None
+        if last and last["stream"] == s and a - last["t1"] <= gap_ns:
+            last["t1"] = max(last["t1"], b)
+            last["score"] = max(last["score"], sc)   # peak represents the segment
+            last["mean"] = (last["mean"] * last["windows"] + sc) / (last["windows"] + 1)
+            last["windows"] += 1
+        else:
+            segs.append({"stream": s, "t0": a, "t1": b, "score": sc,
+                         "mean": sc, "windows": 1})
+    segs.sort(key=lambda g: -g["score"])
+    stats["qualifying_windows"] = len(qual)
+    stats["segments"] = len(segs)
+    return segs[:k], stats
+
+
+def _parse_query(text):
+    """Parse a compositional query string into (positive terms, negatives).
+
+    Grammar (all optional, combinable):
+      'a AND b'      — every term must match (compositional AND)
+      'a NOT b'      — exclude b   (also '-b' or 'a -b')
+      'a; b'         — same as AND
+    Plain text with none of these is a single positive term (classic search).
+    """
+    import re
+    neg = []
+    # split on NOT / leading-minus tokens
+    parts = re.split(r'\bNOT\b', text)
+    head = parts[0]
+    for extra in parts[1:]:
+        neg.append(extra.strip())
+    pos_raw = re.split(r'\bAND\b|;', head)
+    pos = []
+    for term in pos_raw:
+        term = term.strip()
+        # pull out inline -word exclusions
+        toks = term.split()
+        keep = []
+        for tk in toks:
+            if tk.startswith("-") and len(tk) > 1:
+                neg.append(tk[1:])
+            else:
+                keep.append(tk)
+        if keep:
+            pos.append(" ".join(keep))
+    pos = [p for p in pos if p]
+    neg = [n for n in neg if n]
+    return (pos or [text]), neg
+
+
+def search(store, text, k=10, nprobe=3, merge=True, t0=None, t1=None,
+           streams=None, method="auto", neg_weight=0.5, min_score=None,
+           percentile=None, rerank=False, rerank_top=12, rerank_alpha=0.7):
+    """Compositional text search. `text` may use AND / NOT / -term:
+        'two people AND a laptop NOT a phone'
+    `min_score` (absolute cosine floor) or `percentile` (keep top X%) turn
+    ranked-everything into precise retrieval."""
+    st = store.table("embeddings").state()
+    model = st.meta.get("model", DEFAULT_MODEL)
+    pos_terms, neg_terms = _parse_query(text)
+    pos_vecs = np.stack([embed_text(p, model) for p in pos_terms])
+    neg_vecs = (np.stack([embed_text(n, model) for n in neg_terms])
+                if neg_terms else None)
+    q = pos_vecs.mean(axis=0)
+    q /= np.linalg.norm(q)  # coarse retrieval direction
+    hits, stats = _rank(store, q, k, nprobe, merge=merge, t0=t0, t1=t1,
+                        streams=streams, method=method, pos_vecs=pos_vecs,
+                        neg_vecs=neg_vecs, neg_weight=neg_weight,
+                        min_score=min_score, percentile=percentile)
+    stats["positive_terms"] = pos_terms
+    stats["negative_terms"] = neg_terms
+    if rerank and hits:
+        # relational stage: the expensive operator runs LAST, on the pruned set
+        from .rerank import rerank_hits
+        hits, info = rerank_hits(store, hits, text, top_n=rerank_top,
+                                 alpha=rerank_alpha)
+        stats["rerank"] = info
+    return hits, stats
+
+
+def search_text(store, text, k=10, nprobe=3, merge=True, t0=None, t1=None,
+                streams=None, method="auto", **kw):
+    # backward-compatible alias; forwards compositional kwargs too
+    return search(store, text, k=k, nprobe=nprobe, merge=merge, t0=t0, t1=t1,
+                  streams=streams, method=method, **kw)
+
+
+def search_clip(store, stream, t0, t1, k=10, nprobe=3, merge=True,
+                pt0=None, pt1=None, pstreams=None, method="auto"):
+    t, vecs = _vec_table(store)
+    s = t.column("stream").to_numpy(zero_copy_only=False)
+    a = t.column("ts").to_numpy()
+    b = t.column("t1").to_numpy()
+    sel = (s == stream) & (a <= t1) & (b >= t0)
+    if not sel.any():
+        raise ValueError(f"no embedded windows overlap {stream} [{t0},{t1}]")
+    q = vecs[sel].mean(axis=0)
+    q /= np.linalg.norm(q)
+    hits, stats = _rank(store, q, k + 8, nprobe, merge=merge,
+                        t0=pt0, t1=pt1, streams=pstreams, method=method)
+    hits = [h for h in hits
+            if not (h["stream"] == stream and h["t0"] <= t1 and h["t1"] >= t0)]
+    return hits[:k], stats

python/elidedb/encprune.py

@@ -0,0 +1,307 @@
+"""FDNN cellular turnover applied to the SigLIP ENCODER — where the time is.
+
+WHY HERE AND NOT THE LITTLE TOWER
+---------------------------------
+Ingest cost is measured, and it is not the database: byte-range decode runs at
+2.7 ms/frame while the SigLIP vision tower runs at 27.7-90.3 ms/frame. So 97%
+of ingest is one frozen 428M-parameter ViT. Pruning the 80k-parameter temporal
+tower — which is what was done first — optimises 0.001% of the bill. The
+encoder is the neuron population that matters.
+
+THE NEURON, HERE
+----------------
+Each encoder layer is `fc1 (1152 -> 4304) -> gelu -> fc2 (4304 -> 1152)`.
+Hidden unit *c* is a neuron in exactly FDNN's sense: it takes the residual
+stream, applies its own nonlinearity, and writes back through its own column
+of `fc2`. There are 27 x 4304 = 116,208 of them and they are 65% of the
+tower's parameters.
+
+Silencing one is `fc1.weight[c] = 0, fc1.bias[c] = 0` — gelu(0) = 0, so the
+channel contributes nothing through fc2. Removing one for real is slicing
+`fc1.weight[keep]`, `fc1.bias[keep]`, `fc2.weight[:, keep]`, which is a
+genuine FLOP reduction, not a multiply by zero.
+
+UTILIZATION IS DEFINED BY THE DATABASE'S WORKLOAD
+-------------------------------------------------
+FDNN measures utilization as the increase in validation loss when a neuron is
+silenced. The equivalent here is NOT ImageNet accuracy — this encoder exists
+to produce vectors that a retrieval index ranks with. So utilization is the
+loss of EMBEDDING FIDELITY on frames from the actual corpus:
+
+    fidelity = mean cosine( pruned_embedding, unpruned_embedding )
+
+i.e. the unpruned encoder is its own teacher and the calibration set is the
+user's own data. A channel that matters for photographs of dogs but never
+fires on a robot arm in a toy kitchen is, for this database, dead weight.
+
+Ablating 116,208 channels one at a time is not affordable (one forward pass
+each). FDNN's own PPO feature vector already contains the cheap surrogates —
+activation magnitude and downstream weight norm — and their product is the
+standard structured-pruning saliency:
+
+    saliency(c) = E_frames |act_c| * || fc2[:, c] ||
+
+which is exactly "how much signal this neuron actually injects". Ablation is
+still used, but per LAYER (27 measurements, affordable), to calibrate how much
+each layer's saliency scale is worth. PPO then chooses keep-probabilities from
+the same five features FDNN used, and the reward is the same shape:
+
+    reward = -(fidelity loss ratio) - lambda * kept_fraction
+"""
+from __future__ import annotations
+
+import time
+
+import mlx.core as mx
+import numpy as np
+
+
+# ===========================================================================
+# 0. Reaching the layers
+# ===========================================================================
+def vision_layers(model):
+    """The encoder layer list of a SigLIP vision tower."""
+    vm = model.vision_model
+    vm = getattr(vm, "vision_model", vm)
+    return list(vm.encoder.layers)
+
+
+def mlp_width(layer):
+    return np.array(layer.mlp.fc1.bias).shape[0]
+
+
+class _Tap:
+    """Wraps an nn.Linear so the mean |output| per channel is recorded.
+
+    MLX calls `self.fc1(x)` by attribute, so swapping the attribute is enough
+    to observe it — no hooks, no forked forward pass that could drift from the
+    real one.
+    """
+
+    def __init__(self, inner):
+        self.inner = inner
+        self.acc = None
+        self.n = 0
+
+    def __call__(self, x):
+        out = self.inner(x)
+        a = mx.mean(mx.abs(out).reshape(-1, out.shape[-1]), axis=0)
+        self.acc = a if self.acc is None else self.acc + a
+        self.n += 1
+        return out
+
+
+# ===========================================================================
+# 1. Saliency: activation magnitude x downstream weight norm
+# ===========================================================================
+def channel_saliency(model, images, model_id, batch=16):
+    """Per-layer array of per-channel saliency, measured on REAL frames."""
+    from .embeddings import _embed_images
+    layers = vision_layers(model)
+    taps = []
+    for lyr in layers:
+        t = _Tap(lyr.mlp.fc1)
+        lyr.mlp.fc1 = t
+        taps.append(t)
+    try:
+        for i in range(0, len(images), batch):
+            _embed_images(images[i:i + batch], model_id)
+    finally:
+        for lyr, t in zip(layers, taps):
+            lyr.mlp.fc1 = t.inner
+
+    out = []
+    for lyr, t in zip(layers, taps):
+        act = np.array(t.acc) / max(t.n, 1)
+        down = np.linalg.norm(np.array(lyr.mlp.fc2.weight), axis=0)
+        out.append({"act": act.astype(np.float32),
+                    "down": down.astype(np.float32),
+                    "saliency": (act * down).astype(np.float32)})
+    return out
+
+
+# ===========================================================================
+# 2. Masking and compaction
+# ===========================================================================
+def _snapshot(layers):
+    return [(np.array(l.mlp.fc1.weight), np.array(l.mlp.fc1.bias))
+            for l in layers]
+
+
+def _restore(layers, snap):
+    for l, (w, b) in zip(layers, snap):
+        l.mlp.fc1.weight = mx.array(w)
+        l.mlp.fc1.bias = mx.array(b)
+
+
+def apply_masks(layers, snap, masks):
+    """Silence channels: zeroing the fc1 row makes gelu(0)=0 downstream."""
+    for l, (w, b), m in zip(layers, snap, masks):
+        keep = m.astype(np.float32)[:, None]
+        l.mlp.fc1.weight = mx.array(w * keep)
+        l.mlp.fc1.bias = mx.array(b * keep[:, 0])
+
+
+def compact_mlps(model, masks):
+    """Physically delete the dead channels. This is where speed comes from."""
+    layers = vision_layers(model)
+    removed = 0
+    for l, m in zip(layers, masks):
+        keep = np.where(m > 0.5)[0]
+        if len(keep) == mlp_width(l):
+            continue
+        removed += mlp_width(l) - len(keep)
+        l.mlp.fc1.weight = mx.array(np.array(l.mlp.fc1.weight)[keep])
+        l.mlp.fc1.bias = mx.array(np.array(l.mlp.fc1.bias)[keep])
+        l.mlp.fc2.weight = mx.array(np.array(l.mlp.fc2.weight)[:, keep])
+    mx.eval(model.parameters())
+    return removed
+
+
+# ===========================================================================
+# 3. Fidelity against the unpruned teacher, on the user's own frames
+# ===========================================================================
+def fidelity(model_id, images, teacher, batch=16):
+    from .embeddings import _embed_images
+    out = []
+    for i in range(0, len(images), batch):
+        out.append(_embed_images(images[i:i + batch], model_id))
+    v = np.concatenate(out, axis=0)
+    return float((v * teacher).sum(axis=1).mean())
+
+
+# ===========================================================================
+# 4. Reverse attention (unchanged in spirit from FDNN)
+# ===========================================================================
+def reverse_attention(importance, temperature=1.0):
+    imp = np.asarray(importance, dtype=np.float64)
+    imp = (imp - imp.mean()) / (imp.std() + 1e-8)
+    logits = -imp / max(temperature, 1e-6)
+    logits -= logits.max()
+    e = np.exp(logits)
+    return (e / (e.sum() + 1e-12)).astype(np.float32)
+
+
+# ===========================================================================
+# 5. The cycle
+# ===========================================================================
+def prune_encoder(model_id, images, keep=0.5, layer_probe=True, iters=12,
+                  lam=0.35, batch=16, verbose=True, seed=0):
+    """Prune MLP channels of the vision tower against corpus fidelity.
+
+    `keep` is the global target fraction of MLP channels to retain. The
+    per-layer budget is not uniform: layers whose ablation barely moves
+    fidelity give up more channels than layers that matter, which is the whole
+    point of measuring instead of assuming.
+
+    Returns (model, report). The returned model is COMPACTED — smaller
+    matmuls, not masked ones.
+    """
+    from .embeddings import _embed_images, _load_model
+    rng = np.random.default_rng(seed)
+    model, _ = _load_model(model_id)
+    layers = vision_layers(model)
+    widths = [mlp_width(l) for l in layers]
+    snap = _snapshot(layers)
+
+    teacher = np.concatenate(
+        [_embed_images(images[i:i + batch], model_id)
+         for i in range(0, len(images), batch)], axis=0)
+
+    t0 = time.time()
+    sal = channel_saliency(model, images, model_id, batch=batch)
+    if verbose:
+        print(f"  saliency over {len(images)} corpus frames "
+              f"({time.time() - t0:.1f}s)", flush=True)
+
+    # ---- per-layer ablation: how much does this layer matter at all? -------
+    layer_cost = np.ones(len(layers), dtype=np.float64)
+    if layer_probe:
+        for li in range(len(layers)):
+            masks = [np.ones(w, np.float32) for w in widths]
+            masks[li][:] = 0.0
+            apply_masks(layers, snap, masks)
+            layer_cost[li] = max(1.0 - fidelity(model_id, images[:batch],
+                                                teacher[:batch], batch), 1e-6)
+        _restore(layers, snap)
+        if verbose:
+            order = np.argsort(layer_cost)
+            print(f"  layer ablation: cheapest {order[:4].tolist()} "
+                  f"costliest {order[-4:].tolist()}", flush=True)
+
+    # ---- allocate the budget across layers by measured importance ---------
+    # A layer that costs little when removed entirely can afford to lose more
+    # of its channels. Normalised so the global kept fraction hits `keep`.
+    w = layer_cost / layer_cost.sum()
+    share = w / w.mean()                       # 1.0 == average importance
+    per_layer_keep = np.clip(keep * share, 0.05, 1.0)
+    total = sum(widths)
+    scale = (keep * total) / sum(k * n for k, n in zip(per_layer_keep, widths))
+    per_layer_keep = np.clip(per_layer_keep * scale, 0.05, 1.0)
+
+    masks = []
+    for li, (s, wdt) in enumerate(zip(sal, widths)):
+        n_keep = max(int(round(per_layer_keep[li] * wdt)), 1)
+        idx = np.argsort(-s["saliency"])[:n_keep]
+        m = np.zeros(wdt, np.float32)
+        m[idx] = 1.0
+        masks.append(m)
+
+    apply_masks(layers, snap, masks)
+    fid = fidelity(model_id, images, teacher, batch)
+    kept = sum(m.sum() for m in masks) / total
+    if verbose:
+        print(f"  saliency prune: kept {kept:.1%}, fidelity {fid:.4f}",
+              flush=True)
+
+    # ---- PPO refinement over the per-layer budget --------------------------
+    # The candidate set is the 27 per-layer keep fractions rather than 116,208
+    # independent channels: one forward pass per sampled mask makes per-channel
+    # sampling unaffordable, and the per-layer budget is where the leverage
+    # actually is (saliency already orders channels within a layer).
+    best = (fid, [m.copy() for m in masks], kept)
+    ra = reverse_attention(layer_cost)
+    logit = np.zeros(len(layers))
+    for it in range(iters):
+        cand = per_layer_keep * (1.0 + 0.25 * np.tanh(logit)
+                                 + 0.15 * rng.standard_normal(len(layers)))
+        cand = np.clip(cand, 0.05, 1.0)
+        cand *= (keep * total) / sum(c * n for c, n in zip(cand, widths))
+        cand = np.clip(cand, 0.05, 1.0)
+        trial = []
+        for li, (s, wdt) in enumerate(zip(sal, widths)):
+            n_keep = max(int(round(cand[li] * wdt)), 1)
+            idx = np.argsort(-s["saliency"])[:n_keep]
+            m = np.zeros(wdt, np.float32)
+            m[idx] = 1.0
+            trial.append(m)
+        apply_masks(layers, snap, trial)
+        f = fidelity(model_id, images[:batch * 2], teacher[:batch * 2], batch)
+        k = sum(m.sum() for m in trial) / total
+        reward = -(1.0 - f) - lam * k
+        best_reward = -(1.0 - best[0]) - lam * best[2]
+        if reward > best_reward:
+            # Direction of the accepted move, computed BEFORE the budget is
+            # updated — comparing `cand` against itself would make every sign
+            # zero and the search a pure random walk.
+            step = np.sign(cand - per_layer_keep)
+            best = (f, [m.copy() for m in trial], k)
+            per_layer_keep = cand
+            logit += 0.5 * ra * step
+        if verbose and (it % 4 == 0 or it == iters - 1):
+            print(f"  PPO {it:2d} | fidelity {f:.4f} | kept {k:.1%} | "
+                  f"reward {reward:+.4f}", flush=True)
+
+    fid, masks, kept = best
+    _restore(layers, snap)
+    removed = compact_mlps(model, masks)
+    final = fidelity(model_id, images, teacher, batch)
+    report = {"model": model_id, "kept_fraction": float(kept),
+              "channels_removed": int(removed),
+              "channels_total": int(total),
+              "fidelity": float(final),
+              "layer_keep": [float(x) for x in per_layer_keep]}
+    if verbose:
+        print(f"  compacted: removed {removed:,}/{total:,} MLP channels, "
+              f"fidelity {final:.4f}", flush=True)
+    return model, report

python/elidedb/fdnnstudent.py

@@ -0,0 +1,231 @@
+"""FDNN students shaped like their teachers.
+
+A student is not a generic head bolted onto whatever vectors happen to
+be lying around. That was tried and it failed for a reason worth
+keeping: an attention-pool + ReLU MLP over FDNN-V frame vectors reached
+0.9168 cosine to the PE teacher while a CONSTANT prediction of the
+corpus mean scored 0.8629, and nearest-neighbour agreement was 0.005.
+The head had learned the mean. A least-squares oracle on the same input
+reached nn_top1 0.0155, so no head over those vectors could have worked
+- the information was not in them.
+
+So the student takes the TEACHER'S OWN ARCHITECTURE as its skeleton,
+reads pixels like the teacher does, and shrinks. What changes is the
+neuron, per the three FDNN rules:
+
+  RULE 1  each neuron is a sub-network. Every transformer block's MLP -
+          the 2/3 of a ViT's parameters that is elementwise GELU -
+          becomes a KAN-style sum over k heterogeneous bases of the
+          same pre-activation: FINER (variable-period oscillator),
+          Gabor (wavelet, fires on a burst), sine, poly-phase (chirp,
+          fires on acceleration). omega bands partition the spectrum so
+          different channels answer to different rates of change.
+          A GELU unit can only answer "how much"; these answer "how
+          much, how fast, and is it accelerating" - which is what a
+          video model's MLP is being asked for in the first place.
+
+  RULE 2  neurogenesis and apoptosis after training, each followed by a
+          re-settle fine-tune. `mask` is the aliveness vector the cycle
+          writes; it is frozen against the optimizer, because AdamW
+          weight-decays an unfrozen mask off 1.0 and every channel
+          quietly shrinks (measured on the context tower).
+
+  RULE 3  PPO + reverse attention decide who lives: utilization is the
+          drop in held-out fidelity when a channel is silenced.
+
+WHY THE SKELETON MATTERS. V-JEPA2 is 24 blocks of width 1024 over 8,192
+spatiotemporal tokens (256px, 64 frames, patch 16, tubelet 2). Most of
+that cost is token count, not depth. A student that keeps the tubelet
+embedding and the attentive pooler - the parts that decide WHAT is
+compared - while cutting resolution, frames, width and depth, is doing
+the teacher's computation at the teacher's shape. A student with a
+different shape is a different model that happens to be trained on the
+teacher's outputs, which is what failed.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+import mlx.core as mx
+import mlx.nn as nn
+
+# Basis identifiers, matching FDNNTemporalCell so the two implementations
+# cannot drift apart: 0 FINER, 1 Gabor, 2 sine, 3 poly-phase.
+FINER, GABOR, SINE, POLY = 0, 1, 2, 3
+
+
+class FDNNFeedForward(nn.Module):
+    """Rule 1, applied to a transformer block's MLP.
+
+    Standard: y = W2 @ gelu(W1 @ x). Here each of C output channels is a
+    KAN sum over k sub-functions of the SAME pre-activation, so one
+    channel can be periodic, another can fire only on a burst, another
+    only on acceleration - heterogeneous by construction rather than by
+    hoping a homogeneous nonlinearity specialises.
+
+    omega bands are spatial-temporal here, not purely temporal: tokens
+    are tubelets, so a band is a rate of change across the token grid.
+    """
+
+    def __init__(self, dim, channels, k_width=4,
+                 omega_bands=(0.8, 2.5, 8.0),
+                 band_fractions=(0.34, 0.33, 0.33), seed=0):
+        super().__init__()
+        rng = np.random.default_rng(seed)
+        C, k = channels, k_width
+        self.C, self.k = C, k
+
+        om = []
+        for b, fr in zip(omega_bands, band_fractions):
+            om.extend([b] * int(round(fr * C)))
+        om = (om + [omega_bands[-1]] * C)[:C]
+        self.omegas_per_neuron = np.array(om, np.float32)
+        self.omegas = mx.array(np.repeat(self.omegas_per_neuron, k))
+
+        half, quarter = max(k // 2, 1), max(k // 4, 1)
+        per = np.array([FINER] * half + [GABOR] * quarter
+                       + [POLY] * max(k - half - quarter, 0), np.int32)[:k]
+        self.basis_types = mx.array(np.tile(per, C).astype(np.int32))
+        # categorical, not a weight: unfrozen the optimizer drifts it off
+        # its exact values and silently reroutes every Gabor to poly
+        self.freeze(keys=["basis_types"], recurse=False)
+
+        mean_om = float(self.omegas_per_neuron.mean())
+        lim = float(np.sqrt(6.0 / dim) / mean_om)
+        self.W1 = mx.array(rng.uniform(-lim, lim, (dim, C * k)).astype(np.float32))
+        self.b1 = mx.array(rng.uniform(-2.0, 2.0, (C * k,)).astype(np.float32))
+        self.phases = mx.array(rng.uniform(0, 2 * np.pi, (C * k,)).astype(np.float32))
+        self.gabor_s = mx.array(rng.uniform(0.3, 1.5, (C * k,)).astype(np.float32))
+        log_om = np.log(np.clip(np.repeat(self.omegas_per_neuron, k), 1e-3, None))
+        self.log_alpha = mx.array(rng.uniform(np.minimum(0.0, log_om),
+                                              np.maximum(0.0, log_om) + 1e-6
+                                              ).astype(np.float32))
+        w2s = float(np.sqrt(6.0 / (C * k)))
+        self.w2 = mx.array(rng.uniform(-w2s, w2s, (C, k)).astype(np.float32))
+        pl = float(np.sqrt(6.0 / C))
+        self.Wp = mx.array(rng.uniform(-pl, pl, (C, dim)).astype(np.float32))
+
+        self.mask = mx.array(np.ones((C,), np.float32))     # rule 2
+        self.freeze(keys=["mask"], recurse=False)
+
+    def channels_out(self, x):
+        """Per-channel activation before the mask - rule 3's signal."""
+        pre = x @ self.W1 + self.b1
+        om_h = self.omegas * pre
+        sq = pre * pre
+        alpha = mx.exp(self.log_alpha)
+        finer = mx.sin(self.omegas * (mx.abs(pre) + 1.0) * pre + self.phases)
+        gab = mx.exp(-(self.gabor_s ** 2) * sq) * mx.sin(om_h + self.phases)
+        sine = mx.sin(om_h + self.phases)
+        poly = mx.sin(alpha * sq + om_h + self.phases)
+        acts = mx.where(self.basis_types == FINER, finer,
+                        mx.where(self.basis_types == GABOR, gab,
+                                 mx.where(self.basis_types == SINE, sine, poly)))
+        acts = acts.reshape(*pre.shape[:-1], self.C, self.k)
+        return mx.sum(acts * self.w2, axis=-1)
+
+    def __call__(self, x):
+        return (self.channels_out(x) * self.mask) @ self.Wp
+
+    def set_active_mask(self, m):
+        self.mask = mx.array(np.asarray(m, np.float32))
+
+
+class Block(nn.Module):
+    """A ViT block with the teacher's shape and an FDNN neuron inside."""
+
+    def __init__(self, dim, heads, channels, k_width=4, seed=0):
+        super().__init__()
+        self.n1 = nn.LayerNorm(dim)
+        self.attn = nn.MultiHeadAttention(dim, heads)
+        self.n2 = nn.LayerNorm(dim)
+        self.ff = FDNNFeedForward(dim, channels, k_width, seed=seed)
+
+    def __call__(self, x):
+        h = self.n1(x)
+        x = x + self.attn(h, h, h)
+        return x + self.ff(self.n2(x))
+
+
+class TubeletEmbed(nn.Module):
+    """The teacher's input stage: non-overlapping spatiotemporal patches.
+
+    Kept because it is what decides what a token IS. Resolution, frame
+    count, width and depth are all shrunk; the tokenisation is not
+    changed, so the student is comparing the same kind of thing.
+    """
+
+    def __init__(self, dim, patch=16, tubelet=2, in_ch=3):
+        super().__init__()
+        self.patch, self.tubelet = patch, tubelet
+        self.proj = nn.Linear(in_ch * patch * patch * tubelet, dim)
+
+    def __call__(self, v):                      # (B, T, H, W, 3) in [-1,1]
+        B, T, H, W, C = v.shape
+        p, t = self.patch, self.tubelet
+        gt, gh, gw = T // t, H // p, W // p
+        v = v[:, :gt * t, :gh * p, :gw * p]
+        v = v.reshape(B, gt, t, gh, p, gw, p, C)
+        v = v.transpose(0, 1, 3, 5, 2, 4, 6, 7).reshape(B, gt * gh * gw, -1)
+        return self.proj(v), (gt, gh, gw)
+
+
+class AttentivePool(nn.Module):
+    """The teacher pools with a learned query, so the student does too.
+    Mean pooling buries the few tokens that carry the event under the
+    many that carry the unchanged room."""
+
+    def __init__(self, dim, out_dim):
+        super().__init__()
+        self.q = mx.array((np.random.default_rng(0).normal(size=(dim,))
+                           / np.sqrt(dim)).astype(np.float32))
+        self.norm = nn.LayerNorm(dim)
+        self.proj = nn.Linear(dim, out_dim)
+
+    def __call__(self, x):
+        a = mx.softmax(x @ self.q, axis=1)[..., None]
+        y = self.proj(self.norm(mx.sum(a * x, axis=1)))
+        return y / (mx.linalg.norm(y, axis=-1, keepdims=True) + 1e-8)
+
+
+class VideoStudent(nn.Module):
+    """V-JEPA2's skeleton at 1/N the size, with FDNN neurons.
+
+    teacher  256px, 64 frames, patch 16, tubelet 2 -> 8192 tokens,
+             24 blocks, width 1024, 16 heads
+    student  configurable; the default cuts tokens 16x and width 5x,
+             which is where a ViT's cost actually lives.
+    """
+
+    def __init__(self, out_dim=1024, dim=192, depth=4, heads=3,
+                 channels=256, k_width=4, patch=16, tubelet=2,
+                 size=128, frames=16, seed=0):
+        super().__init__()
+        self.size, self.frames = size, frames
+        self.embed = TubeletEmbed(dim, patch, tubelet)
+        n_tok = (frames // tubelet) * (size // patch) ** 2
+        self.pos = mx.array((np.random.default_rng(seed).normal(
+            size=(1, n_tok, dim)) * 0.02).astype(np.float32))
+        self.blocks = [Block(dim, heads, channels, k_width, seed=seed + i)
+                       for i in range(depth)]
+        self.pool = AttentivePool(dim, out_dim)
+
+    def __call__(self, v):
+        x, _ = self.embed(v)
+        x = x + self.pos[:, :x.shape[1]]
+        for b in self.blocks:
+            x = b(x)
+        return self.pool(x)
+
+    def utilization(self, v):
+        """Rule 3's raw signal: per-channel mean |activation| per block."""
+        x, _ = self.embed(v)
+        x = x + self.pos[:, :x.shape[1]]
+        out = []
+        for b in self.blocks:
+            h = b.n1(x)
+            x = x + b.attn(h, h, h)
+            c = b.ff.channels_out(b.n2(x))
+            out.append(np.abs(np.array(c)).mean((0, 1)))
+            x = x + b.ff(b.n2(x))
+        return out

python/elidedb/fdnnv2.py

@@ -0,0 +1,249 @@
+"""FDNN-V2: the context head. Same speed class, different training signal.
+
+V1's measured dead end: distilled to an appearance teacher whose own space
+separates close/open at 0.60, no student can learn verbs — the target lacks
+them. V2 keeps V1's skeleton (stem -> FDNN recurrent cell, 0.27 ms/frame)
+and warm-starts from its weights; what changes is WHERE the gradient comes
+from (docs/FDNNV2_PLAN.md, all research-grounded):
+
+  L1 PREDICTIVE (V-JEPA-style, arXiv 2506.09985): from state h_t, predict
+     the embedding of frame t+k at two horizons. The future is free
+     supervision on every frame, and dynamics must enter h to predict it.
+     This is the biological claim made mechanical: understanding = a scene
+     model good enough to predict what happens next.
+  L2 ARROW OF TIME (Wei et al., CVPR 2018): classify forward vs reversed
+     clips from the final state. Open and close are time-reversals; one
+     binary head separates them by construction.
+  L3 VERB-FOCUSED CONTRASTIVE (arXiv 2304.06708): sigmoid contrastive
+     between clip context embeddings and 7B captions, with hard negatives
+     built by verb/direction swaps — the joint space queries actually live
+     in. A 2-layer text adapter maps SigLIP text embeddings into the
+     256-d context space (~0.1 ms per query).
+
+The appearance head keeps its V1 distillation target so every existing
+index and the SigLIP text tower continue to work unchanged.
+
+THE GATE IS AN EVENT DETECTOR. The cell's update gate z_t measures how much
+of the scene model this frame is allowed to overwrite. Sustained high gate
+activity marks an event boundary — so the encoder emits event segmentation
+for free, and event embeddings are pooled with NOVELTY WEIGHTS (gate
+activity), not uniformly: the moment the drawer closes outweighs the seconds
+it sat still (the TempMe lesson, arXiv 2409.01156, applied at pooling time).
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import mlx.core as mx
+import mlx.nn as nn
+import numpy as np
+
+from .fdnnvideo import EMBED_DIM, FDNNVideoEncoder
+
+CTX_DIM = 256
+
+# Verb/direction swaps for L3 hard negatives: shared lexicon (moved to
+# lexicon.py so the QUERY path can import it without this module's mlx)
+from .lexicon import derived_swaps  # noqa: E402,F401
+
+
+def swap_verbs(text: str, rng, store=None) -> str | None:
+    """One randomly chosen applicable swap -> a hard negative. None if no
+    swap applies (caption has no directional content to invert)."""
+    # Training negatives obey the no-hardwire rule too: a model taught
+    # from hand-written oppositions has the hand-writing baked into its
+    # weights, which is worse than a lookup table because it cannot be
+    # grepped out afterwards.
+    pairs = list(derived_swaps(store)) if store is not None else []
+    if not pairs:
+        return None
+    t = " " + text.lower() + " "
+    hits = []
+    for a, b in pairs:
+        if f" {a} " in t:
+            hits.append((a, b))
+        if f" {b} " in t:
+            hits.append((b, a))
+    if not hits:
+        # clause order flip is the fallback inversion for compounds
+        parts = re.split(r"\band then\b|\bthen\b|,", text)
+        if len(parts) >= 2:
+            return " then ".join(p.strip() for p in reversed(parts)
+                                 if p.strip())
+        return None
+    a, b = hits[rng.integers(len(hits))]
+    return re.sub(rf"\b{re.escape(a)}\b", b, text.lower(), count=1)
+
+
+class TextAdapter(nn.Module):
+    """SigLIP text embedding (1152) -> context space (256). Two layers,
+    ~0.7M params, ~0.1 ms — the entire query-time cost of verb awareness."""
+
+    def __init__(self, in_dim=EMBED_DIM, dim=CTX_DIM):
+        super().__init__()
+        self.fc1 = nn.Linear(in_dim, 512)
+        self.fc2 = nn.Linear(512, dim)
+
+    def __call__(self, x):
+        e = self.fc2(nn.silu(self.fc1(x)))
+        return e * mx.rsqrt(mx.sum(e * e, axis=-1, keepdims=True) + 1e-8)
+
+
+class FDNNv2(nn.Module):
+    """V1 skeleton + context head + predictors + arrow-of-time head."""
+
+    def __init__(self, base: FDNNVideoEncoder, ctx_dim=CTX_DIM,
+                 horizons=(2, 10), motion_dim=64):
+        super().__init__()
+        self.base = base
+        C = base.channels
+        G = base.cfg["glimpse"]
+        self.horizons = list(horizons)
+        self.motion_dim = motion_dim
+        # MOTION PATHWAY — the reversal-symmetry breaker. The gated cell is a
+        # leaky integrator; for smooth inputs an EMA is nearly order-invariant,
+        # and stage-A measured exactly that: AoT stuck at chance (0.47) while
+        # dominating the loss. Frame-difference features flip SIGN under time
+        # reversal, so direction becomes linearly readable. Velocity is not a
+        # nicety here; it is the only anti-symmetric signal in the model.
+        self.motion = nn.Linear(G, motion_dim)
+        # context head reads (glimpse, state, motion)
+        self.head_ctx = nn.Linear(G + C + motion_dim, ctx_dim)
+        # Predictors target the model's OWN future glimpse-change (stop-grad).
+        # A2 measured why not student-embedding changes: adjacent-frame true
+        # change is ~0.2 in norm while the student's own error is ~0.45 — the
+        # difference of noisy embeddings is noise, and the predictors sat at
+        # cosine 0 for 8 epochs. Own-latent prediction is JEPA's actual
+        # recipe; the appearance anchor stops the stem collapsing to constants.
+        self.pred = [nn.Linear(C + motion_dim, G) for _ in horizons]
+        # AoT reads the velocity SEQUENCE through a temporal conv, not the
+        # mean: this corpus is reciprocal motion (arm out, arm back), so mean
+        # signed velocity cancels — measured at chance twice. Order within
+        # the window is the signal; a conv kernel can be asymmetric in time.
+        self.aot_conv = nn.Conv1d(motion_dim, 32, 5, padding=2)
+        self.head_aot = nn.Linear(32, 1)
+        self.cfg = {"ctx_dim": ctx_dim, "horizons": self.horizons,
+                    "motion_dim": motion_dim, "base": base.cfg}
+
+    # ---- forward over a sequence, exposing everything the losses and the
+    # event segmenter need ---------------------------------------------------
+    def run(self, seq, h0=None):
+        """(B,T,H,W,3) -> dict of app (B,T,1152), ctx (B,T,ctx), preds,
+        gates (B,T), h_last."""
+        b = self.base
+        B, T = seq.shape[0], seq.shape[1]
+        g = b.stem(seq.reshape(B * T, *seq.shape[2:])).reshape(B, T, -1)
+        h = b.init_state(B) if h0 is None else h0
+        hs, gates = [], []
+        cell = b.cell
+        for t in range(T):
+            z = mx.sigmoid(g[:, t] @ cell.Wz + h @ cell.Uz + cell.bz)
+            h = cell(g[:, t], h)
+            hs.append(h)
+            gates.append(mx.mean(z, axis=-1))
+        hs = mx.stack(hs, axis=1)                    # (B,T,C)
+        gates = mx.stack(gates, axis=1)              # (B,T)
+        app = b.head_g(g) + b.head_h(hs)
+        app = app * mx.rsqrt(mx.sum(app * app, axis=-1, keepdims=True) + 1e-8)
+        # signed velocity of the glimpse; first frame gets zero motion.
+        # NORMALISED: measured, ||dg|| is real motion (corr 0.63 with pixel
+        # motion, 5x on moving frames) but only ~2% of the feature norm — fed
+        # raw, it drowned next to signals 50x larger and every motion head
+        # starved. Direction is unit-normalised; magnitude re-enters as a
+        # bounded gain, so both the WHAT and the HOW-MUCH of motion survive.
+        dg = mx.concatenate([mx.zeros_like(g[:, :1]),
+                             g[:, 1:] - g[:, :-1]], axis=1)
+        mag = mx.sqrt(mx.sum(dg * dg, axis=-1, keepdims=True) + 1e-8)
+        mfeat = nn.silu(self.motion(dg / mag)) * mx.tanh(mag)
+        cat = mx.concatenate([g, hs, mfeat], axis=-1)
+        ctx = self.head_ctx(cat)
+        ctx = ctx * mx.rsqrt(mx.sum(ctx * ctx, axis=-1, keepdims=True) + 1e-8)
+        hm = mx.concatenate([hs, mfeat], axis=-1)
+        preds = [p(hm) for p in self.pred]           # each (B,T,G)
+        a = nn.silu(self.aot_conv(mfeat))            # (B,T,32) time-conv
+        aot = self.head_aot(mx.mean(a, axis=1))[:, 0]
+        return {"app": app, "ctx": ctx, "preds": preds, "gates": gates,
+                "aot": aot, "h": h, "g": g}
+
+    # ---- streaming embed (the write path): app + ctx + gate per frame -----
+    def embed_stream_np(self, frames_u8, batch=128):
+        h = self.base.init_state(1)
+        apps, ctxs, gates = [], [], []
+        for i in range(0, len(frames_u8), batch):
+            x = mx.array(frames_u8[i:i + batch].astype(np.float32)
+                         / 127.5 - 1.0)[None]
+            out = self.run(x, h0=h)
+            h = out["h"]
+            apps.append(np.array(out["app"][0], np.float32))
+            ctxs.append(np.array(out["ctx"][0], np.float32))
+            gates.append(np.array(out["gates"][0], np.float32))
+        return (np.concatenate(apps), np.concatenate(ctxs),
+                np.concatenate(gates))
+
+
+# ===========================================================================
+# Event segmentation from the gate signal + novelty-weighted pooling
+# ===========================================================================
+def segment_events(gates, ts, min_len=6, smooth=5, thresh_pct=75.0):
+    """Gate-activity peaks -> event boundaries.
+
+    A boundary is where smoothed gate activity crosses above its own
+    percentile threshold after having been below — the scene model is being
+    rewritten. Percentile (not absolute) because gate scale is a trained
+    quantity; per-stream calibration is free.
+    Returns list of (start_idx, end_idx) covering the stream.
+    """
+    g = np.convolve(gates, np.ones(smooth) / smooth, mode="same")
+    thr = np.percentile(g, thresh_pct)
+    above = g > thr
+    bounds = [0]
+    for i in range(1, len(g)):
+        if above[i] and not above[i - 1] and i - bounds[-1] >= min_len:
+            bounds.append(i)
+    bounds.append(len(g))
+    return [(a, b) for a, b in zip(bounds[:-1], bounds[1:]) if b - a >= 2]
+
+
+def pool_event(vecs, gates, lo, hi):
+    """Novelty-weighted pool: frames weighted by gate activity, so change
+    dominates stillness. Uniform mean is the verb-eraser; this is not."""
+    w = gates[lo:hi] + 1e-3
+    w = w / w.sum()
+    v = (vecs[lo:hi] * w[:, None]).sum(0)
+    return v / (np.linalg.norm(v) + 1e-8)
+
+
+# ===========================================================================
+# persistence
+# ===========================================================================
+def save_v2(model, adapter, meta, path):
+    from mlx.utils import tree_flatten
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    np.savez(path / "v2.npz",
+             **{k: np.array(v) for k, v in tree_flatten(model.parameters())})
+    np.savez(path / "adapter.npz",
+             **{k: np.array(v)
+                for k, v in tree_flatten(adapter.parameters())})
+    (path / "v2.json").write_text(json.dumps({**meta, "cfg": model.cfg},
+                                             indent=2))
+
+
+def load_v2(path):
+    from mlx.utils import tree_unflatten
+    path = Path(path)
+    meta = json.loads((path / "v2.json").read_text())
+    base = FDNNVideoEncoder(**meta["cfg"]["base"])
+    model = FDNNv2(base, ctx_dim=meta["cfg"]["ctx_dim"],
+                   horizons=tuple(meta["cfg"]["horizons"]),
+                   motion_dim=meta["cfg"].get("motion_dim", 64))
+    z = np.load(path / "v2.npz")
+    model.update(tree_unflatten([(k, mx.array(z[k])) for k in z.files]))
+    model.base.cell.freeze(keys=["basis_types", "mask"], recurse=False)
+    adapter = TextAdapter()
+    z = np.load(path / "adapter.npz")
+    adapter.update(tree_unflatten([(k, mx.array(z[k])) for k in z.files]))
+    mx.eval(model.parameters(), adapter.parameters())
+    return model, adapter, meta

python/elidedb/fdnnvideo.py

@@ -0,0 +1,500 @@
+"""FDNN-V: a video-native embedding encoder, distilled from SigLIP.
+
+WHY THIS MODEL EXISTS
+---------------------
+The database must embed EVERY frame at write time. SigLIP cannot do that at
+scale because it is a 428M-parameter model that treats each frame as an
+unrelated photograph — measured 13-90 ms/frame on this machine. But video is
+not a pile of photographs: frame t is almost entirely explained by frame t-1
+(Deep Feature Flow, arXiv 1611.07715, built a whole recognition system on that
+observation). A human watching a video does not re-parse the scene 30 times a
+second either; they maintain a scene model and update it with what changed.
+
+FDNN-V is that shape, made of the three FDNN rules:
+
+  spatial glimpse (cheap, per frame)     "what is in front of me right now"
+      Gabor-initialised first conv        — V1 simple cells ARE Gabor filters
+      small conv pyramid                  — ventral stream
+          |
+  FDNN temporal core (rule 1)            "what has been going on"
+      recurrent state h_t; each channel is a KAN-style sum over k
+      heterogeneous sub-functions of (glimpse, state):
+        FINER   variable-period oscillator — periodic motion (gait, wipers)
+        Gabor   temporal wavelet           — bursts (a grasp, a brake light)
+        poly    chirp                      — acceleration (pulling away)
+      omega bands partition the temporal spectrum: slow = scene identity,
+      mid = object motion, fast = transitions
+          |
+  head -> SigLIP space (1152-d)          so every existing index, text query,
+                                          and centroid keeps working unchanged
+
+  rules 2+3 (apoptosis -> fine-tune -> neurogenesis -> fine-tune, decided by
+  PPO + reverse attention) run post-training in fdnnv_prune — and unlike the
+  attempt to prune SigLIP itself, the fine-tune step EXISTS here, because
+  distillation pairs are free: every frame of the corpus already has a teacher
+  embedding in `frame_vectors`.
+
+THE STREAMING CONTRACT
+----------------------
+`step(frame, h) -> (embedding, h')` is causal and O(1) per frame: no
+lookahead, no window buffer. That is what makes embed-on-write real — the
+encoder can sit inside the ingest loop and emit an embedding as each frame
+arrives, like any other index maintenance.
+
+WHAT DISTILLATION CAN AND CANNOT GIVE
+-------------------------------------
+The student lands in the teacher's embedding space, so text queries (embedded
+by the frozen SigLIP text tower) keep working. It can match the teacher ON
+THIS CORPUS's manifold; it is not a zero-shot model for arbitrary imagery.
+That is the correct trade for a database: specialise the index to the data it
+serves, keep the teacher for what it is — an offline labeller.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import mlx.core as mx
+import mlx.nn as nn
+import numpy as np
+
+EMBED_DIM = 1152          # SigLIP so400m space — compatibility is the point
+INPUT_HW = (144, 192)     # decode width 192 -> 192x144 (h, w)
+
+
+# ===========================================================================
+# V1: Gabor-initialised first convolution
+# ===========================================================================
+def gabor_bank(n_filters, ksize, rng):
+    """Oriented Gabor filters spanning orientation x frequency x phase.
+
+    Not decoration: the first layer of every competent visual system —
+    biological or learned — converges to oriented band-pass filters. Starting
+    there instead of at noise removes the epochs a small model would spend
+    rediscovering V1.
+    """
+    k = np.zeros((n_filters, ksize, ksize, 3), dtype=np.float32)
+    half = ksize // 2
+    ys, xs = np.mgrid[-half:half + 1, -half:half + 1]
+    for i in range(n_filters):
+        theta = np.pi * (i % 8) / 8.0
+        lam = ksize / (1.5 + (i // 8) % 3)
+        psi = 0.0 if (i // 24) % 2 == 0 else np.pi / 2
+        sigma = 0.4 * lam
+        xr = xs * np.cos(theta) + ys * np.sin(theta)
+        yr = -xs * np.sin(theta) + ys * np.cos(theta)
+        g = np.exp(-(xr**2 + 0.8 * yr**2) / (2 * sigma**2)) \
+            * np.cos(2 * np.pi * xr / lam + psi)
+        g -= g.mean()
+        g /= (np.abs(g).sum() + 1e-6)
+        # colour-opponent weighting: some filters luminance, some R-G, B-Y
+        cw = [(1, 1, 1), (1, -1, 0), (0.5, 0.5, -1)][i % 3]
+        for c in range(3):
+            k[i, :, :, c] = g * cw[c]
+    k += rng.normal(0, 0.01, k.shape).astype(np.float32)
+    return k
+
+
+# ===========================================================================
+# Ventral stream: small depthwise-separable pyramid
+# ===========================================================================
+class DWBlock(nn.Module):
+    def __init__(self, c_in, c_out, stride):
+        super().__init__()
+        self.dw = nn.Conv2d(c_in, c_in, 3, stride=stride, padding=1,
+                            groups=c_in)
+        self.pw = nn.Conv2d(c_in, c_out, 1)
+        self.norm = nn.LayerNorm(c_out)
+        self.res = (c_in == c_out and stride == 1)
+
+    def __call__(self, x):
+        y = self.norm(self.pw(nn.silu(self.dw(x))))
+        return x + y if self.res else y
+
+
+class ConvStem(nn.Module):
+    """Per-frame spatial encoder -> one glimpse vector. Small on purpose:
+    fine discrimination is amortised into the temporal state, and capacity
+    here is paid for EVERY frame FOREVER."""
+
+    def __init__(self, width=48, out_dim=256, seed=0):
+        super().__init__()
+        rng = np.random.default_rng(seed)
+        w = width
+        self.v1 = nn.Conv2d(3, w, 7, stride=2, padding=3)
+        self.v1.weight = mx.array(gabor_bank(w, 7, rng))
+        self.s1 = DWBlock(w, w * 2, 2)
+        self.s2 = DWBlock(w * 2, w * 4, 2)
+        self.s3 = DWBlock(w * 4, w * 8, 2)
+        self.r1 = DWBlock(w * 8, w * 8, 1)
+        self.r2 = DWBlock(w * 8, w * 8, 1)
+        self.proj = nn.Linear(w * 16, out_dim)
+        self.norm = nn.LayerNorm(out_dim)
+
+    def __call__(self, x):                      # (B, H, W, 3) in [-1, 1]
+        h = nn.silu(self.v1(x))
+        h = self.s1(h)
+        h = self.s2(h)
+        h = self.s3(h)
+        h = self.r2(self.r1(h))
+        mean = mx.mean(h, axis=(1, 2))
+        peak = mx.max(h, axis=(1, 2))           # mean = layout, max = salient
+        return self.norm(self.proj(mx.concatenate([mean, peak], axis=-1)))
+
+
+class ViTStem(nn.Module):
+    """The alternative stem: patchify + tiny transformer. Pure matmuls, which
+    Apple-silicon GEMM kernels love; raced against ConvStem by measurement,
+    never by taste."""
+
+    def __init__(self, dim=192, depth=4, heads=3, out_dim=256,
+                 patch=16, hw=INPUT_HW):
+        super().__init__()
+        self.patch = patch
+        self.nh, self.nw = hw[0] // patch, hw[1] // patch
+        self.embed = nn.Linear(patch * patch * 3, dim)
+        self.pos = mx.zeros((1, self.nh * self.nw, dim))
+        self.blocks = [_TinyBlock(dim, heads) for _ in range(depth)]
+        self.proj = nn.Linear(dim * 2, out_dim)
+        self.norm = nn.LayerNorm(out_dim)
+
+    def __call__(self, x):                      # (B, H, W, 3)
+        B, H, W, _ = x.shape
+        p = self.patch
+        t = x.reshape(B, self.nh, p, self.nw, p, 3).transpose(0, 1, 3, 2, 4, 5)
+        t = t.reshape(B, self.nh * self.nw, p * p * 3)
+        t = self.embed(t) + self.pos
+        for blk in self.blocks:
+            t = blk(t)
+        pooled = mx.concatenate([mx.mean(t, axis=1), mx.max(t, axis=1)],
+                                axis=-1)
+        return self.norm(self.proj(pooled))
+
+
+class _TinyBlock(nn.Module):
+    def __init__(self, dim, heads):
+        super().__init__()
+        self.n1 = nn.LayerNorm(dim)
+        self.att = nn.MultiHeadAttention(dim, heads)
+        self.n2 = nn.LayerNorm(dim)
+        self.fc1 = nn.Linear(dim, dim * 2)
+        self.fc2 = nn.Linear(dim * 2, dim)
+
+    def __call__(self, x):
+        y = self.n1(x)
+        x = x + self.att(y, y, y)
+        return x + self.fc2(nn.silu(self.fc1(self.n2(x))))
+
+
+# ===========================================================================
+# Rule 1: the temporal core — every channel is a sub-network
+# ===========================================================================
+class FDNNTemporalCell(nn.Module):
+    """Recurrent state whose channels are KAN-style sums over k heterogeneous
+    temporal sub-functions, gated GRU-style so state persists by default.
+
+    The bases read the JOINT signal (current glimpse, previous state), so a
+    FINER channel can oscillate with repeated motion, a Gabor channel can fire
+    on a burst of change, and a poly-phase channel can track acceleration —
+    while the gate decides how much of the old scene model each step is
+    allowed to overwrite. This is FDNN's HybridBiomimeticLayer with time as
+    the signal axis instead of a coordinate.
+    """
+
+    def __init__(self, in_dim=256, channels=256, k_width=4,
+                 omega_bands=(0.8, 2.5, 8.0),
+                 band_fractions=(0.34, 0.33, 0.33), seed=0):
+        # omega bands are LOWER than the context tower's (2, 6, 18) on
+        # purpose: that tower convolved over time feed-forward, this cell
+        # FEEDS BACK. sin bases at omega 15 inside a 32-step recurrence give
+        # chaotic gradients — measured: stage-2 loss climbed from 0.086 to
+        # 0.112 and val fidelity fell 0.019. Same bases, calmer spectrum.
+        super().__init__()
+        rng = np.random.default_rng(seed)
+        C, k = channels, k_width
+        self.C, self.k = C, k
+
+        omegas = []
+        for om, fr in zip(omega_bands, band_fractions):
+            omegas.extend([om] * int(round(fr * C)))
+        omegas = (omegas + [omega_bands[-1]] * C)[:C]
+        self.omegas_per_neuron = np.array(omegas, dtype=np.float32)
+        self.omegas = mx.array(np.repeat(self.omegas_per_neuron, k))
+
+        half, quarter = max(k // 2, 1), max(k // 4, 1)
+        per = np.array([0] * half + [1] * quarter
+                       + [3] * max(k - half - quarter, 0), np.int32)[:k]
+        self.basis_types = mx.array(np.tile(per, C).astype(np.int32))
+        # A categorical selector, not a weight: unfrozen, the optimizer
+        # promotes it to float and drifts it off its exact values, silently
+        # rerouting every Gabor neuron to the poly branch (measured on the
+        # context tower: 1.0 -> 0.9992 and `== 1` matched nothing).
+        self.freeze(keys=["basis_types"], recurse=False)
+
+        mean_om = float(self.omegas_per_neuron.mean())
+        lim_g = float(np.sqrt(6.0 / in_dim) / mean_om)
+        lim_h = float(np.sqrt(6.0 / C) / mean_om)
+        self.Wg = mx.array(rng.uniform(-lim_g, lim_g,
+                                       (in_dim, C * k)).astype(np.float32))
+        self.Wh = mx.array(rng.uniform(-lim_h, lim_h,
+                                       (C, C * k)).astype(np.float32))
+        self.b1 = mx.array(rng.uniform(-2.0, 2.0, (C * k,)).astype(np.float32))
+        self.phases = mx.array(rng.uniform(0, 2 * np.pi,
+                                           (C * k,)).astype(np.float32))
+        self.gabor_s = mx.array(rng.uniform(0.3, 1.5,
+                                            (C * k,)).astype(np.float32))
+        log_om = np.log(np.clip(np.repeat(self.omegas_per_neuron, k),
+                                1e-3, None))
+        # alpha starts log-uniform between 1 and omega. With sub-unit omegas
+        # (the calmed recurrent bands) log-omega is negative, so the interval
+        # must be ordered explicitly — uniform(0, negative) is an error.
+        self.log_alpha = mx.array(rng.uniform(np.minimum(0.0, log_om),
+                                              np.maximum(0.0, log_om) + 1e-6
+                                              ).astype(np.float32))
+        w2s = float(np.sqrt(6.0 / (C * k)))
+        self.w2 = mx.array(rng.uniform(-w2s, w2s, (C, k)).astype(np.float32))
+
+        zlim = float(np.sqrt(6.0 / (in_dim + C)))
+        self.Wz = mx.array(rng.uniform(-zlim, zlim,
+                                       (in_dim, C)).astype(np.float32))
+        self.Uz = mx.array(rng.uniform(-zlim, zlim,
+                                       (C, C)).astype(np.float32))
+        # Gate bias starts NEGATIVE: sigmoid(-1) ~ 0.27, so at init the state
+        # persists — a scene model that forgets everything every frame is just
+        # a per-frame model with extra steps.
+        self.bz = mx.array(np.full((C,), -1.0, np.float32))
+
+        self.mask = mx.array(np.ones((C,), np.float32))  # aliveness (rule 2)
+        # Aliveness is set by the pruning cycle, never by the optimizer —
+        # unfrozen, AdamW weight-decays it off 1.0 and every channel quietly
+        # shrinks (the measured context-tower failure mode).
+        self.freeze(keys=["mask"], recurse=False)
+
+    def set_active_mask(self, m):
+        self.mask = mx.array(np.asarray(m, dtype=np.float32))
+
+    def _cand(self, g, h):
+        pre = g @ self.Wg + h @ self.Wh + self.b1
+        om_h = self.omegas * pre
+        sq = pre * pre
+        alpha = mx.exp(self.log_alpha)
+        finer = mx.sin(self.omegas * (mx.abs(pre) + 1.0) * pre + self.phases)
+        gab = mx.exp(-(self.gabor_s ** 2) * sq) * mx.sin(om_h + self.phases)
+        sine = mx.sin(om_h + self.phases)
+        poly = mx.sin(alpha * sq + om_h + self.phases)
+        acts = mx.where(self.basis_types == 0, finer,
+                        mx.where(self.basis_types == 1, gab,
+                                 mx.where(self.basis_types == 2, sine, poly)))
+        acts = acts.reshape(-1, self.C, self.k)
+        return mx.sum(acts * self.w2, axis=-1)
+
+    def neuron_outputs(self, g, h):
+        """Per-neuron candidate BEFORE gate and mask — the pruning signal."""
+        return self._cand(g, h)
+
+    def __call__(self, g, h):
+        cand = self._cand(g, h) * self.mask
+        z = mx.sigmoid(g @ self.Wz + h @ self.Uz + self.bz) * self.mask
+        return (1.0 - z) * h + z * cand
+
+
+# ===========================================================================
+# The encoder
+# ===========================================================================
+class FDNNVideoEncoder(nn.Module):
+    def __init__(self, stem="conv", stem_width=48, glimpse=256, channels=256,
+                 k_width=4, embed_dim=EMBED_DIM, vit_depth=4, seed=0):
+        super().__init__()
+        self.cfg = dict(stem=stem, stem_width=stem_width, glimpse=glimpse,
+                        channels=channels, k_width=k_width,
+                        embed_dim=embed_dim, vit_depth=vit_depth, seed=seed)
+        if stem == "conv":
+            self.stem = ConvStem(width=stem_width, out_dim=glimpse, seed=seed)
+        else:
+            self.stem = ViTStem(dim=stem_width * 4, depth=vit_depth,
+                                out_dim=glimpse)
+        self.cell = FDNNTemporalCell(in_dim=glimpse, channels=channels,
+                                     k_width=k_width, seed=seed)
+        self.head_g = nn.Linear(glimpse, embed_dim)
+        # Temporal head starts at zero: at init the model IS the per-frame
+        # model (stage 1), and training can only add information from state.
+        # Same identity-safe discipline as every other init in this repo.
+        self.head_h = nn.Linear(channels, embed_dim)
+        self.head_h.weight = mx.zeros(self.head_h.weight.shape)
+        self.head_h.bias = mx.zeros((embed_dim,))
+        self.channels = channels
+
+    # ---- streaming: this is the embed-on-write contract -------------------
+    def init_state(self, batch=1):
+        return mx.zeros((batch, self.channels))
+
+    def step(self, frame, h):
+        """One frame in, one embedding out, O(1) state carried. Causal."""
+        g = self.stem(frame)
+        h = self.cell(g, h)
+        e = self.head_g(g) + self.head_h(h)
+        return e * mx.rsqrt(mx.sum(e * e, axis=-1, keepdims=True) + 1e-8), h
+
+    # ---- batched sequences (training / bulk ingest) -----------------------
+    def __call__(self, seq, h0=None):
+        """(B, T, H, W, 3) -> (B, T, D). Stem runs on all frames as one big
+        batch (the GEMM-friendly part); only the tiny cell recurs."""
+        B, T = seq.shape[0], seq.shape[1]
+        g = self.stem(seq.reshape(B * T, *seq.shape[2:])).reshape(B, T, -1)
+        h = self.init_state(B) if h0 is None else h0
+        outs = []
+        for t in range(T):
+            h = self.cell(g[:, t], h)
+            outs.append(h)
+        hs = mx.stack(outs, axis=1)
+        e = self.head_g(g) + self.head_h(hs)
+        return e * mx.rsqrt(mx.sum(e * e, axis=-1, keepdims=True) + 1e-8), h
+
+    def embed_frames_np(self, frames_u8, batch=64, chunk=None):
+        """uint8 (N, H, W, 3) of ONE stream, in time order -> (N, 1152).
+        Stateful across batches — one continuous pass over the stream."""
+        h = self.init_state(1)
+        out = []
+        for i in range(0, len(frames_u8), batch):
+            x = mx.array(frames_u8[i:i + batch].astype(np.float32)
+                         / 127.5 - 1.0)[None]
+            e, h = self(x, h0=h)
+            out.append(np.array(e[0], dtype=np.float32))
+        return np.concatenate(out, axis=0)
+
+
+# ===========================================================================
+# Distillation loss: pointwise + affinity mimicking
+# ===========================================================================
+def distill_loss(student, teacher, affinity_w=0.25, mu=None, centered_w=1.0,
+                 anchors=None, anchor_w=50.0):
+    """Distillation aimed at RETRIEVAL, not at raw closeness.
+
+    Plain pointwise cosine is a trap on a homogeneous corpus: every teacher
+    vector shares a huge common mode, so matching that alone buys ~0.9 cosine
+    while scrambling the thin discriminative residual that ranking runs on.
+    Measured: a student at fidelity 0.907 kept only 4.4% of the teacher's
+    top-10 neighbours, while the teacher AGAINST ITSELF at a different input
+    resolution — fidelity 0.921 — keeps 50.7%. Same closeness, 10x the
+    retrieval agreement: the difference is WHERE the error lives.
+
+    So three additional terms put the error where it does no harm:
+      centered   cosine on (v - mu): the mean-free residual is exactly what
+                 ranking compares, so it gets its own gradient.
+      affinity   within-batch similarity matching (TinyCLIP, arXiv
+                 2309.12314): preserve the teacher's ordering structure.
+      anchors    similarity profile against real caption-text embeddings from
+                 this store: text queries live in those directions, and
+                 image-text sims occupy a band ~50x narrower than image-image
+                 sims — hence the weight.
+    """
+    t = teacher * mx.rsqrt(mx.sum(teacher * teacher, axis=-1,
+                                  keepdims=True) + 1e-8)
+    loss = mx.mean(1.0 - mx.sum(student * t, axis=-1))
+    if mu is not None and centered_w > 0:
+        sc = student - mu
+        tc = t - mu
+        sc = sc * mx.rsqrt(mx.sum(sc * sc, axis=-1, keepdims=True) + 1e-8)
+        tc = tc * mx.rsqrt(mx.sum(tc * tc, axis=-1, keepdims=True) + 1e-8)
+        loss = loss + centered_w * mx.mean(1.0 - mx.sum(sc * tc, axis=-1))
+    if affinity_w > 0:
+        s2 = student.reshape(-1, student.shape[-1])
+        t2 = t.reshape(-1, t.shape[-1])
+        loss = loss + affinity_w * mx.mean(mx.square(s2 @ s2.T - t2 @ t2.T))
+    if anchors is not None and anchor_w > 0:
+        sa = student.reshape(-1, student.shape[-1]) @ anchors.T
+        ta = t.reshape(-1, t.shape[-1]) @ anchors.T
+        loss = loss + anchor_w * mx.mean(mx.square(sa - ta))
+    return loss
+
+
+# ===========================================================================
+# persistence
+# ===========================================================================
+def save_encoder(model, meta, path):
+    from mlx.utils import tree_flatten
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    np.savez(path / "weights.npz",
+             **{k: np.array(v) for k, v in tree_flatten(model.parameters())})
+    (path / "encoder.json").write_text(json.dumps(
+        {**meta, "cfg": model.cfg}, indent=2))
+
+
+def fdnnv_dir() -> Path:
+    """Where the FDNN-V encoder lives.
+
+    Repo-level `models/fdnnv`, NOT inside any store. The encoder used to
+    sit at `lake/bridge/models/fdnnv`, so clearing the stores deleted a
+    trained model along with the data (2026-07-28). A model is not store
+    data. The legacy path is still accepted for stores that predate the
+    move."""
+    here = Path("models/fdnnv")
+    if (here / "encoder.json").exists():
+        return here
+    legacy = Path("lake/bridge/models/fdnnv")
+    if (legacy / "encoder.json").exists():
+        return legacy
+    return here
+
+
+def load_encoder(path):
+    from mlx.utils import tree_unflatten
+    path = Path(path)
+    meta = json.loads((path / "encoder.json").read_text())
+    model = FDNNVideoEncoder(**meta["cfg"])
+    z = np.load(path / "weights.npz")
+    model.update(tree_unflatten([(k, mx.array(z[k])) for k in z.files]))
+    model.cell.freeze(keys=["basis_types", "mask"], recurse=False)
+    mx.eval(model.parameters())
+    return model, meta
+
+
+# ===========================================================================
+# The write path: chunked byte-range decode feeding the streaming encoder
+# ===========================================================================
+def embed_stream(store, model, rows, width=192, chunk=512, batch_cb=None):
+    """Embed one stream's frames in time order, state carried across chunks.
+
+    `chunk` bounds the decoder subprocess's rawvideo buffer (~1 GB at 512
+    frames of 640x480); the encoder state flows straight through, so the
+    result is identical to one infinite pass. This loop is the write path:
+    ingest can call it as frames land.
+    Returns (ts int64 array, vectors float32 (N, D), decode_s, embed_s).
+    """
+    import time as _time
+
+    from .video import FrameSet
+    ts_out, vecs = [], []
+    h = model.init_state(1)
+    dec_s = emb_s = 0.0
+    for i in range(0, len(rows), chunk):
+        t0 = _time.perf_counter()
+        dec = FrameSet(store, "frames", rows.slice(i, chunk)).decode(
+            width=width)
+        dec_s += _time.perf_counter() - t0
+        if not dec:
+            continue
+        frames = np.stack([d[1] for d in dec])
+        # the stem takes EXACTLY (in_h, in_w); sources with a different
+        # aspect ratio decode to other shapes (lab video came back square
+        # and crashed the reshape). Stretch — the encoder was distilled on
+        # stretched frames, so aspect distortion is in-distribution.
+        ih, iw = model.cfg["in_hw"] if "in_hw" in model.cfg else (144, 192)
+        if frames.shape[1] != ih or frames.shape[2] != iw:
+            xr = np.linspace(0, frames.shape[2] - 1, iw).round().astype(int)
+            yr = np.linspace(0, frames.shape[1] - 1, ih).round().astype(int)
+            frames = frames[:, yr][:, :, xr]
+        t0 = _time.perf_counter()
+        x = mx.array(frames.astype(np.float32) / 127.5 - 1.0)[None]
+        e, h = model(x, h0=h)
+        e = np.array(e[0], dtype=np.float32)
+        emb_s += _time.perf_counter() - t0
+        ts_out.extend(d[0] for d in dec)
+        vecs.append(e)
+        if batch_cb:
+            batch_cb(len(ts_out))
+    if not vecs:
+        return np.array([], np.int64), np.zeros((0, EMBED_DIM), np.float32), \
+            dec_s, emb_s
+    return (np.array(ts_out, np.int64), np.concatenate(vecs), dec_s, emb_s)

python/elidedb/fftools.py

@@ -0,0 +1,40 @@
+"""Locate the ffmpeg/ffprobe binaries robustly.
+
+Why this exists: a macOS .app (or anything launched from Finder/launchd) runs
+with a minimal PATH — typically `/usr/bin:/bin:/usr/sbin:/sbin` — which does
+NOT include Homebrew's `/opt/homebrew/bin`. A bare `["ffmpeg", ...]` then
+fails with `FileNotFoundError` even though ffmpeg is installed. We resolve the
+absolute path once, checking (in order): an explicit env override, the current
+PATH, and the common install locations on macOS/Linux.
+"""
+from __future__ import annotations
+
+import functools
+import os
+import shutil
+
+_COMMON_DIRS = [
+    "/opt/homebrew/bin",   # Apple Silicon Homebrew
+    "/usr/local/bin",      # Intel Homebrew / manual installs
+    "/opt/local/bin",      # MacPorts
+    "/usr/bin",
+]
+
+
+@functools.lru_cache(maxsize=None)
+def find(tool: str) -> str:
+    """Absolute path to `ffmpeg`/`ffprobe`, or raise with a fixable message."""
+    env = os.environ.get(f"ELIDEDB_{tool.upper()}")
+    if env and os.path.exists(env):
+        return env
+    found = shutil.which(tool)
+    if found:
+        return found
+    for d in _COMMON_DIRS:
+        cand = os.path.join(d, tool)
+        if os.path.exists(cand):
+            return cand
+    raise FileNotFoundError(
+        f"{tool} not found. Install it with `brew install ffmpeg`, or set "
+        f"ELIDEDB_{tool.upper()}=/path/to/{tool}. (Apps launched from Finder "
+        f"get a minimal PATH, so Homebrew's bin dir may not be visible.)")

python/elidedb/fusion.py

@@ -0,0 +1,110 @@
+"""Reciprocal rank fusion.
+
+WHY NOT JUST ADD THE SCORES
+---------------------------
+Because they are not on the same scale, and no amount of tuning fixes that.
+SigLIP image-text cosines on a homogeneous corpus occupy roughly 0.01-0.15
+(the modality gap squashes them); caption-LSA cosines spread over most of
+[-1, 1]; TF-IDF cosines are mostly 0 with a thin tail near 1. A weighted sum
+of those is governed by whichever signal happens to have the widest spread on
+that particular query, so the weight you set is not the weight you get.
+
+Standardising per query (z-scores) helps but still lets one ranker's outlier
+drag the result: a single candidate three sigma out on appearance outranks a
+candidate that every ranker agrees is second-best.
+
+RRF (Cormack, Clarke & Buettcher, SIGIR 2009) throws the magnitudes away and
+keeps only the ORDER:
+
+    score(d) = sum over rankers r of  w_r / (K + rank_r(d))
+
+That makes fusion scale-free by construction, and it rewards CONSENSUS: a
+document ranked 2nd by three rankers beats one ranked 1st by a single ranker
+and 200th by the rest. Which is exactly the failure being fixed — "crossing
+red car" returned any clip of a person crossing, because one strong signal on
+"crossing" was allowed to win alone. Under RRF the answer has to look right to
+the appearance index AND the caption index AND the lexical index.
+
+K (default 60, the constant from the paper) damps the top of the curve: it is
+the number of rank positions over which differences stop mattering much, so a
+ranker cannot dominate purely by being extremely confident about its #1.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+DEFAULT_K = 60.0
+
+
+def ranks_from_scores(scores: np.ndarray) -> np.ndarray:
+    """0-based ranks; highest score gets rank 0.
+
+    NaN means ABSTAIN, and an abstention is given the median rank rather than
+    the last. This matters: the lexical ranker can only score windows that
+    actually have a caption, and windows whose context vector was estimated by
+    the tower have none. Sending those to the bottom would let a ranker veto
+    every item it has no opinion about, which is the opposite of what "no
+    evidence" should mean. Median rank is the neutral position — it neither
+    helps nor hurts.
+    """
+    s = np.asarray(scores, dtype=float)
+    known = ~np.isnan(s)
+    r = np.empty(len(s), dtype=float)
+    if not known.any():
+        r[:] = 0.0
+        return r
+    sub = s[known]
+    order = np.argsort(-sub, kind="stable")
+    rr = np.empty(len(sub), dtype=float)
+    rr[order] = np.arange(len(sub), dtype=float)
+    r[known] = rr
+    r[~known] = float(np.median(rr))
+    return r
+
+
+def rrf(rankings: dict[str, np.ndarray], weights: dict[str, float] | None = None,
+        k: float = DEFAULT_K) -> np.ndarray:
+    """Fuse score vectors (all over the SAME candidate set, same order).
+
+    Pass raw scores, not ranks — this converts. Returns the fused score, where
+    higher is better, on an arbitrary but consistent scale.
+    """
+    if not rankings:
+        raise ValueError("rrf() needs at least one ranking")
+    n = len(next(iter(rankings.values())))
+    out = np.zeros(n, dtype=float)
+    for name, sc in rankings.items():
+        sc = np.asarray(sc, dtype=float)
+        if len(sc) != n:
+            raise ValueError(
+                f"ranker '{name}' has {len(sc)} scores, expected {n} — every "
+                "ranker must score the same candidate set")
+        w = 1.0 if weights is None else float(weights.get(name, 1.0))
+        if w == 0.0:
+            continue
+        out += w / (k + ranks_from_scores(sc) + 1.0)
+    return out
+
+
+def variant_max(vs):
+    """Row-wise max over query-variant score arrays. All-NaN rows
+    (episodes absent from a channel's table — they abstain, they are
+    not errors) stay NaN without numpy's All-NaN-slice RuntimeWarning,
+    which was leaking source lines into bench stdout."""
+    m = np.stack(vs)
+    out = np.full(m.shape[1], np.nan)
+    fin = np.isfinite(m).any(0)
+    if fin.any():
+        out[fin] = np.nanmax(m[:, fin], 0)
+    return out
+
+
+def explain_fusion(rankings, weights=None, k=DEFAULT_K, idx=None, top=5):
+    """Per-ranker rank of each fused winner. Answers 'why is this here?' —
+    which is the question a fused score alone can never answer."""
+    fused = rrf(rankings, weights, k)
+    order = np.argsort(-fused)[:top] if idx is None else idx
+    rk = {n: ranks_from_scores(s) for n, s in rankings.items()}
+    return [{"i": int(i), "fused": float(fused[i]),
+             "ranks": {n: int(r[i]) + 1 for n, r in rk.items()}}
+            for i in order]

python/elidedb/grounding.py

@@ -0,0 +1,218 @@
+"""GEOMETRIC RELATIONAL VERIFIER — boxes over time instead of a VLM.
+
+Calibration verdict that forced this: VLM judges see the right scene
+and say yes (7B est 1.0 on visually ~10%-pure sets); they cannot bind
+"X ends up inside/on Y". A detector can: ground the query's noun
+phrases to boxes on sampled frames, and the relation IS the geometry —
+containment (intersection-over-area of X in Y) low at the start and
+high at the end verifies "put X in/on Y"; the reverse verifies "take X
+out of Y". Deterministic, explainable, video-evidence-only.
+
+Interim detector: Grounding DINO (open-vocabulary, ungated). Measured
+on our frames (2026-07-24): green-object→drawer and lid→pot both
+verified by end-state containment; one mid-flight false positive under
+occlusion (sink read as lid) — which start/end predicates never see.
+SAM 3 (pending license approval) swaps in for masks + tracking later.
+
+Latency: ~1.2 s/frame on MPS — a VERIFICATION-tier cost (top-K
+candidates, 6 frames each), never a scan cost.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+_G = {}
+
+MODEL_ID = "IDEA-Research/grounding-dino-base"
+
+# "put X in Y" family vs "take X out of Y" family: sign of the expected
+# containment CHANGE. Generic English, nothing per-dataset.
+_INWARD = ("in", "into", "inside", "on", "onto", "on top of", "over")
+_OUTWARD = ("out", "out of", "from")
+
+
+def _load():
+    if "model" in _G:
+        return _G
+    import torch
+    from transformers import (AutoModelForZeroShotObjectDetection,
+                              AutoProcessor)
+    dev = "mps" if torch.backends.mps.is_available() else "cpu"
+    _G["proc"] = AutoProcessor.from_pretrained(MODEL_ID)
+    _G["model"] = AutoModelForZeroShotObjectDetection.from_pretrained(
+        MODEL_ID).to(dev).eval()
+    _G["dev"] = dev
+    return _G
+
+
+def detect_phrases(images, phrases, threshold=0.3):
+    """PIL images x phrases -> per image {phrase: (box, score)|None},
+    best box per phrase."""
+    import torch
+    g = _load()
+    prompt = " . ".join(p.lower().strip(". ") for p in phrases) + " ."
+    inputs = g["proc"](images=images, text=[prompt] * len(images),
+                       return_tensors="pt").to(g["dev"])
+    with torch.no_grad():
+        out = g["model"](**inputs)
+    res = g["proc"].post_process_grounded_object_detection(
+        out, inputs.input_ids, threshold=threshold, text_threshold=0.25,
+        target_sizes=[im.size[::-1] for im in images])
+    per = []
+    for r in res:
+        best = {}
+        for box, sc, lb in zip(r["boxes"], r["scores"],
+                               r["text_labels"]):
+            for p in phrases:
+                if p.lower().strip(". ") in lb or lb in p.lower():
+                    if p not in best or sc > best[p][1]:
+                        best[p] = (np.array([float(v) for v in box]),
+                                   float(sc))
+        per.append({p: best.get(p) for p in phrases})
+    return per
+
+
+def detect_regions(images, prompt="object", threshold=0.25):
+    """ALL boxes above threshold, per image — a class-agnostic REGION
+    PROPOSER rather than a phrase verifier.
+
+    detect_phrases keeps the single best box per phrase, which is right
+    when you are asking "where is the lid" and wrong when you are asking
+    "where are the objects": it returns at most one region per frame and
+    an object store needs every region in the frame.
+    """
+    import torch
+    g = _load()
+    text = prompt.lower().strip(". ") + " ."
+    inputs = g["proc"](images=images, text=[text] * len(images),
+                       return_tensors="pt").to(g["dev"])
+    with torch.no_grad():
+        out = g["model"](**inputs)
+    res = g["proc"].post_process_grounded_object_detection(
+        out, inputs.input_ids, threshold=threshold, text_threshold=0.2,
+        target_sizes=[im.size[::-1] for im in images])
+    per = []
+    for r in res:
+        boxes = [([float(v) for v in b], float(sc))
+                 for b, sc in zip(r["boxes"], r["scores"])]
+        boxes.sort(key=lambda x: -x[1])
+        per.append(boxes)
+    return per
+
+
+def _ioa(a, b):
+    """Intersection over area of A — how much of X sits inside Y."""
+    x0 = max(a[0], b[0]); y0 = max(a[1], b[1])
+    x1 = min(a[2], b[2]); y1 = min(a[3], b[3])
+    inter = max(0.0, x1 - x0) * max(0.0, y1 - y0)
+    area = max(1.0, (a[2] - a[0]) * (a[3] - a[1]))
+    return inter / area
+
+
+def parse_relation(text):
+    """'put the green object in the drawer' ->
+    ('a green object', 'in', 'a drawer') | None. Mechanical determiner-
+    phrase split around a spatial preposition; generic English only."""
+    import re
+    t = text.lower()
+    prep = None
+    for p in sorted(_INWARD + _OUTWARD, key=len, reverse=True):
+        m = re.search(rf"\b{p}\b", t)
+        if m:
+            prep = (p, m.start(), m.end())
+            break
+    if not prep:
+        return None
+    left, right = t[:prep[1]], t[prep[2]:]
+    # the landmark ends at the first conjunction — "out of the drawer
+    # and put it..." must not leak "and put" into the phrase
+    right = right.split(" and ")[0].split(" then ")[0]
+
+    def np_of(seg, last):
+        # GREEDY middle words bounded at closed-class function words
+        # (same _STOP mechanism as sig2.atoms_of): without the
+        # boundary this produced "a vessel and put" as the audit's X
+        # phrase — it grounded nowhere and the audit executed a 9/10
+        # true set (audit-bench-caught)
+        from .sig2 import _STOP
+        ms = list(re.finditer(
+            r"\b(?:a|an|the)\s+(?:(?!(?:%s)\b)\w+\s+){0,2}\w+"
+            r"(?=\s|$|\.)" % "|".join(_STOP), seg))
+        if not ms:
+            return None
+        m = ms[-1] if last else ms[0]
+        w = m.group(0).split()
+        while len(w) > 1 and w[-1] in _STOP:
+            w.pop()
+        head = " ".join(w[1:])
+        art = "an" if head[:1] in "aeiou" else "a"
+        return f"{art} {head}"
+    x, y = np_of(left, last=True), np_of(right, last=False)
+    if not x or not y:
+        return None
+    return x, prep[0], y
+
+
+def relation_margin(store, stream, t0, t1, x_phrase, y_phrase,
+                    inward, n_frames=8):
+    """Containment-change margin for one episode, computed on the SAM
+    3.1 VIDEO tracker's masklets (user rule: never per-frame images
+    when a video API exists — tracked identity through time is the
+    point). Positive = geometry agrees with the query direction; NaN =
+    abstain (landmark never seen, or no signal defined).
+
+    Two complementary signals, because containers OCCLUDE (bench-
+    caught: every put-in-drawer IoA delta was 0 — the object disappears
+    inside):
+      IoA change   — X's mask/box overlap with Y rises (put ON, or
+                     open container where X stays visible)
+      presence     — the tracker loses X while Y persists (put IN), or
+        transition   acquires X late (take OUT); tracker probabilities,
+                     not thresholded detections
+    """
+    from .sam3x import track_concepts
+    tr = track_concepts(store, stream, t0, t1, [x_phrase, y_phrase],
+                        n_frames=n_frames)
+    if tr is None:
+        return float("nan")
+    X, Y = tr[x_phrase], tr[y_phrase]
+    if max(Y["presence"]) <= 0:
+        return float("nan")          # scene lacks the landmark: abstain
+    n = len(X["presence"])
+    k = max(1, n // 3)
+
+    sigs = []
+    traj = []
+    for i in range(n):
+        if X["masks"][i] is not None and Y["masks"][i] is not None:
+            inter = float((X["masks"][i] & Y["masks"][i]).sum())
+            traj.append((i, inter / max(1.0,
+                                        float(X["masks"][i].sum()))))
+        elif X["boxes"][i] is not None and Y["boxes"][i] is not None:
+            traj.append((i, _ioa(X["boxes"][i], Y["boxes"][i])))
+    if len(traj) >= 2:
+        kk = max(1, len(traj) // 3)
+        sigs.append(float(np.mean([v for _, v in traj[-kk:]])
+                          - np.mean([v for _, v in traj[:kk]])))
+    pres = X["presence"]
+    early, late = float(np.mean(pres[:k])), float(np.mean(pres[-k:]))
+    if abs(early - late) > 0.2:
+        # disappearing INTO the container is inward-positive
+        sigs.append(early - late)
+    if not sigs:
+        return float("nan")
+    delta = float(np.mean(sigs))
+    return delta if inward else -delta
+
+
+def verify_relation(store, text, episodes, n_frames=6):
+    """Batch: query text + [(stream,t0,t1)] -> margins array (NaN =
+    abstain). Only called on verification-tier candidates."""
+    rel = parse_relation(text)
+    if rel is None:
+        return None
+    x, prep, y = rel
+    inward = prep in _INWARD
+    return np.array([relation_margin(store, s, a, b, x, y, inward,
+                                     n_frames=n_frames)
+                     for s, a, b in episodes])

python/elidedb/identity.py

@@ -0,0 +1,915 @@
+"""OBJECT IDENTITY on the write path, text-free, riding on tracks.
+
+Identity is a property of a physical object, not of a name and not of a
+category. The same spoon across every demo gets one id. A spatula gets
+a different id. A red pepper and a green pepper get different ids, even
+though every text-aligned encoder calls them both "pepper".
+
+Nothing here turns pixels into language. Regions come from a
+class-agnostic segmenter, identity from a ReID encoder; both vision
+only, both real time. This is separate from objects.py, which proposes
+regions for SEMANTIC retrieval - that channel answers "does this look
+like a cloth", this one answers "is this the same object again".
+
+CONTINUITY IS THE ARCHITECTURE
+------------------------------
+The earlier version sampled 3 frames per episode and asked the gallery
+about every crop independently. That is the wrong question asked ~500
+times: it made identity a threshold problem, and the threshold had no
+good setting - 0.55 built attractor ids that swallowed a green box, a
+broccoli, a toy mouse and a carrot; 0.85 fragmented to 1.15 sightings
+per object. Neither end works because a single crop of an object from
+one angle simply is not enough evidence.
+
+A tracker answers it for free instead. While an object stays visible,
+IoU + Kalman association says "same object" from GEOMETRY, at 0.25
+ms/frame, with no appearance model and no threshold. The object store
+is consulted only when continuity BREAKS - a new track appears - and
+then it is asked once, about a descriptor pooled over the whole track,
+not once per frame about one view.
+
+Measured over 24 episodes / 883 frames of Bridge:
+
+    median track length      24-48 frames (episodes are ~37)
+    singleton tracks         5%
+    object-store uploads     19, against 415 tracked detections
+                             = 95% fewer questions asked
+
+That 95% is the design. Fewer questions, each with far more evidence
+behind it.
+
+COST, and where it goes
+-----------------------
+Detection is STATELESS, so it batches across episode boundaries;
+association is STATEFUL, so it runs per episode, sequentially. Splitting
+them is what makes every-frame tracking affordable - ultralytics' own
+track() ties them together and pays batch-size-1 prices for both.
+
+    per-frame track() calls          15.8 ms/frame
+    batched track() (list per ep)     9.3
+    detect batched + associate        4.8   <- this module
+      of which detect  (fp16, 448)    4.16
+      of which associate              0.13
+      of which reid                   0.50  (was 4.1 per FRAME)
+
+At 18,000 frames per hour of video that is 1.43 min/hour marginal,
+against a 1 min/hour write budget of which 0.23 is already spent by the
+existing pass. STATED STRAIGHT: identity does not fit the budget. What
+riding on tracks bought is the ReID half, which used to dominate and is
+now 0.1 min/hour; the detector is the entire remaining cost, so closing
+the gap is a detector question, not a design one.
+
+fp16 is worth 14% of detect (4.94 -> 4.16 ms/frame) with the fitted cut
+and track count unchanged. That took interleaved runs to establish - a
+first attempt compared an fp16 run against fp32 runs taken earlier in a
+long session and read the thermal drift as fp16 being SLOWER.
+
+DEVICE. Defaults to the GPU, and this is now measured rather than
+assumed. The old 3-frames-per-episode path put CPU and MPS within 5%
+(19.3 vs 20.3 ms/frame) because per-call overhead dominated a batch of
+three. On real batches the gap is 3.7x - mps 6.7 ms/frame vs cpu 24.8
+at imgsz 640 - and the CPU gets WORSE with batching (93.9 ms/frame at
+batch 16) as threads contend. Frames are already resident on the GPU
+for the FDNN-V pass, and on CUDA a host round trip per frame costs more
+than the inference. CPU is the fallback, never the default.
+"""
+from __future__ import annotations
+
+import os
+from types import SimpleNamespace
+
+import numpy as np
+
+_M: dict = {}
+
+# WEIGHTS LIVE IN models/weights, not the repo root. ultralytics
+# downloads into the CWD by default, which is how 86 MB of checkpoints
+# ended up beside the README with 62 MB of it committed to git. _weights
+# resolves a bare name against models/weights and falls back to the bare
+# name so a missing file still auto-downloads - into models/weights,
+# because that is where we then look.
+def _weights(name):
+    from pathlib import Path as _P
+    d = _P(__file__).resolve().parents[2] / "models" / "weights"
+    d.mkdir(parents=True, exist_ok=True)
+    p = d / name
+    return str(p) if p.exists() else str(d / name)
+
+
+SEG_MODEL = os.environ.get("ELIDEDB_SEG") or _weights("yolo11n-seg.pt")
+REID_MODEL = os.environ.get("ELIDEDB_REID") or _weights("yolo26n-reid.onnx")
+# imgsz 448 rather than 384, deliberately paying 0.5 ms/frame for it.
+# 384 is cheaper (3.76 vs 4.23 ms/frame with fp16) and finds MORE boxes
+# (2.63 vs 2.44 per frame), but the extra boxes are marginal ones: its
+# proven-different pairs reach 0.757 against 0.555 at 448, i.e. noisier
+# negatives, and it recovered 72 multi-episode objects against 81. A
+# cheaper size that degrades the identity is not cheaper.
+DET_SZ = int(os.environ.get("ELIDEDB_DET_SZ", "448"))
+# free: same 2.44 boxes/frame, 4.74 -> 4.23 ms/frame
+DET_FP16 = os.environ.get("ELIDEDB_DET_FP16", "1") not in ("0", "")
+# detection is stateless, so the batch may cross episode boundaries;
+# 3.87 ms/frame at ~37 (one episode) against 3.32 at 64
+DET_BATCH = int(os.environ.get("ELIDEDB_DET_BATCH", "64"))
+# Global motion compensation estimates camera movement before
+# association. Default OFF from MEASUREMENT, not from an assumption
+# about this corpus: with sparseOptFlow, median track length was 47 at
+# imgsz 448 and 38 at 640; with none, 48 and 38 - identical - while the
+# optical flow cost 1.8 ms/frame, 7x the entire association step. A
+# corpus with a moving camera must re-measure and will likely want it
+# back; that is what the knob is for.
+GMC = os.environ.get("ELIDEDB_GMC", "none")
+# how many views of a track to embed. The pooled descriptor is what the
+# object store sees, so this trades evidence against ReID calls.
+EXEMPLARS = int(os.environ.get("ELIDEDB_OBJ_VIEWS", "4"))
+
+# "same physical object" cut. Not a constant to be tuned by hand - see
+# calibrate(), which fits it from the corpus being ingested. This value
+# is only the fallback for a corpus too small to fit on.
+MATCH = float(os.environ.get("ELIDEDB_OBJ_MATCH", "0.85"))
+# quantile of the free-negative distribution used as the cut
+CAL_Q = float(os.environ.get("ELIDEDB_OBJ_CAL_Q", "99.5"))
+# Adding an exemplar WIDENS the id's acceptance region, because matching
+# takes a max over the gallery. Unchecked that is a runaway: absorb ->
+# widen -> absorb more. A new view is admitted only if it is close to
+# EVERY exemplar already held, which keeps an id tight instead of
+# letting it sprawl across a chain of intermediate appearances.
+MAX_EXEMPLARS = 5
+ADMIT = float(os.environ.get("ELIDEDB_OBJ_ADMIT", "0.70"))
+MIN_SIDE = 16
+MAX_AREA = 0.5
+
+
+def device():
+    d = os.environ.get("ELIDEDB_DEVICE")
+    if d:
+        return d
+    try:
+        import torch
+        if torch.cuda.is_available():
+            return "cuda"
+        if torch.backends.mps.is_available():
+            return "mps"
+    except Exception:
+        pass
+    return "cpu"
+
+
+def _load():
+    # check for THIS function's own keys, not for _M being non-empty:
+    # propose() also caches into _M, so `if _M` short-circuited here and
+    # left reid unloaded the moment a proposer had run first.
+    if "reid" in _M:
+        return _M
+    from ultralytics import YOLO
+    from ultralytics.trackers.utils.reid import ReID
+    dev = device()
+    _M["seg"] = YOLO(SEG_MODEL)
+    # the ReID encoder runs under onnxruntime and picks its own
+    # execution provider; it does not share the torch device
+    _M["reid"] = ReID(REID_MODEL, device="cpu" if dev == "mps" else dev)
+    _M["dev"] = dev
+    return _M
+
+
+PROPOSER = os.environ.get("ELIDEDB_PROPOSER") or _weights("FastSAM-s.pt")
+
+
+def propose(frames, imgsz=DET_SZ, batch=DET_BATCH, conf=0.25):
+    """CLASS-AGNOSTIC region proposal. Not YOLO-with-single_cls.
+
+    MEASURED, same frames, same model: single_cls=True and
+    single_cls=False give byte-identical output - 3.10 det/frame, all of
+    it {oven, sink, bowl, person, spoon, wine glass}. single_cls is a
+    TRAINING flag; at inference the detector still fires only on
+    COCO-shaped things. Everything built on it inherited an 80-class
+    prior that was never intended, which is why looking for a container
+    found 0.7 regions per episode and they were ovens.
+
+    FastSAM is trained on SA-1B with no class list at all, and on this
+    corpus returns 45.3 regions/frame against COCO YOLO's 2.6, with 3.5
+    large structures per frame against 1.1.
+
+    It costs 24.93 ms/frame batched fp16 = 7.48 min per hour of video,
+    which is 7x the write budget - so this is a TEACHER. It is paid once
+    to make training pairs and then distilled, exactly like every other
+    teacher here. Never put it on the write path directly.
+    """
+    from ultralytics import FastSAM
+    if "prop" not in _M:
+        _M["prop"] = FastSAM(PROPOSER)
+    out = []
+    kw = {"quantize": "fp16"} if DET_FP16 else {}
+    for i in range(0, len(frames), batch):
+        chunk = frames[i:i + batch]
+        res = _M["prop"].predict(chunk, device=device(), verbose=False,
+                                 imgsz=imgsz, conf=conf, **kw)
+        for im, r in zip(chunk, res):
+            H, W = im.shape[:2]
+            if r.boxes is None or not len(r.boxes):
+                out.append(np.zeros((0, 4), np.int32))
+                continue
+            b = r.boxes.xyxy.cpu().numpy()
+            b = np.stack([b[:, 0].clip(0, W), b[:, 1].clip(0, H),
+                          b[:, 2].clip(0, W), b[:, 3].clip(0, H)],
+                         1).astype(np.int32)
+            wh = (b[:, 2] - b[:, 0]), (b[:, 3] - b[:, 1])
+            out.append(b[(wh[0] >= MIN_SIDE) & (wh[1] >= MIN_SIDE)])
+    return out
+
+
+def detect(frames, imgsz=DET_SZ, batch=DET_BATCH, conf=0.25):
+    """Class-agnostic regions per frame: [(boxes Nx4, conf N, area N)].
+
+    Stateless and therefore batched - the caller may hand in frames from
+    several episodes at once. single_cls collapses the 80 COCO classes
+    into one anonymous class, so the model reports "a thing is here" and
+    never a label.
+    """
+    m = _load()
+    out = []
+    kw = {"quantize": "fp16"} if DET_FP16 else {}
+    for i in range(0, len(frames), batch):
+        chunk = frames[i:i + batch]
+        res = m["seg"].predict(chunk, device=m["dev"], single_cls=True,
+                               verbose=False, imgsz=imgsz, conf=conf, **kw)
+        for im, r in zip(chunk, res):
+            H, W = im.shape[:2]
+            if r.boxes is None or not len(r.boxes):
+                out.append((np.zeros((0, 4), np.int32), np.zeros(0, np.float32),
+                            np.zeros(0, np.float32)))
+                continue
+            xy = r.boxes.xyxy.cpu().numpy()
+            cf = r.boxes.conf.cpu().numpy()
+            ar = (r.masks.data.sum((1, 2)).cpu().numpy()
+                  if r.masks is not None else np.zeros(len(xy)))
+            b = np.stack([xy[:, 0].clip(0, W), xy[:, 1].clip(0, H),
+                          xy[:, 2].clip(0, W), xy[:, 3].clip(0, H)],
+                         1).astype(np.int32)
+            wh = (b[:, 2] - b[:, 0]), (b[:, 3] - b[:, 1])
+            ok = ((wh[0] >= MIN_SIDE) & (wh[1] >= MIN_SIDE)
+                  & (wh[0] * wh[1] <= MAX_AREA * W * H))
+            out.append((b[ok], cf[ok].astype(np.float32),
+                        ar[ok].astype(np.float32)))
+    return out
+
+
+class _Dets:
+    """The minimal shape ultralytics' trackers consume: xywh/conf/cls,
+    a length, and boolean-mask indexing (they split detections into
+    high- and low-confidence subsets). Handing them this instead of a
+    Results object is what lets detection run batched somewhere else."""
+
+    __slots__ = ("xywh", "conf", "cls")
+
+    def __init__(self, xywh, conf, cls):
+        self.xywh, self.conf, self.cls = xywh, conf, cls
+
+    def __len__(self):
+        return len(self.conf)
+
+    def __getitem__(self, m):
+        return _Dets(self.xywh[m], self.conf[m], self.cls[m])
+
+    @property
+    def xyxy(self):
+        """Corner boxes, which global motion compensation asks for.
+
+        byte_tracker.py calls `self.gmc.apply(img, results_high.xyxy)` to
+        mask moving objects out before estimating camera motion, inside a
+        try/except that WARNS and falls back to an identity warp. Without
+        this property every frame took that fallback: 1,434 warnings in
+        the first two minutes of a write, and camera motion silently not
+        compensated.
+
+        It was invisible on this corpus because Bridge's camera is fixed,
+        where identity is the correct warp anyway - so the bug cost
+        nothing here and everything on a corpus that moves. A robot that
+        drives or a vehicle camera would have had its tracks fragmented
+        by exactly the motion GMC exists to remove.
+
+        xywh is centre-based (built that way in Stream.push, and what
+        ultralytics' xywh2ltwh assumes), so the corners are centre +/-
+        half-extent.
+        """
+        cx, cy, w, h = (self.xywh[:, 0], self.xywh[:, 1],
+                        self.xywh[:, 2], self.xywh[:, 3])
+        return np.stack([cx - w / 2, cy - h / 2,
+                         cx + w / 2, cy + h / 2], 1)
+
+
+def _tracker(gmc=None):
+    from ultralytics.trackers.bot_sort import BOTSORT
+    from ultralytics.utils import YAML
+    import ultralytics
+    from pathlib import Path
+    cfg = YAML.load(Path(ultralytics.__file__).parent
+                    / "cfg/trackers/botsort.yaml")
+    cfg["gmc_method"] = gmc or GMC
+    # BoT-SORT's own ReID would embed every detection on every frame,
+    # which is the cost this design exists to avoid. Association here is
+    # geometry only; appearance is consulted once per track, later.
+    cfg["with_reid"] = False
+    return BOTSORT(args=SimpleNamespace(**cfg))
+
+
+class Stream:
+    """CONTINUOUS tracking over a stream. No episode boundaries.
+
+    link() below takes one episode's frames and builds a fresh tracker
+    for each - correct when a corpus ships discrete demos, and an
+    assumption the engine has no right to make. Raw capture is a
+    continuous recording; episodes are something the engine must
+    PRODUCE. A driving log, a surveillance feed and a surgical recording
+    have no cuts to reset on.
+
+    So the tracker runs for the life of the stream and a track ends when
+    the OBJECT does - it leaves frame, is occluded past the buffer, or
+    is carried away. That track's span is exactly a PRESENCE INTERVAL:
+    "this object was here, from t0 to t1", one row however long it
+    lasted. An object sitting still for four hours is one row, not
+    72,000, and it is finally recorded at all - the motion-triggered
+    element path never produced a row for anything that did not move.
+
+    Online by construction: detections go in frame by frame, closed
+    tracks come out as they close, and only the open tracks are held.
+    A stream that does not fit in memory is the normal case, not an
+    edge case.
+
+    Exemplar crops are retained per OPEN track and embedded once, at
+    close - the same "ask the object store one question per track, with
+    a whole sighting behind it" that made identity work, now without
+    needing the episode to know when to ask.
+    """
+
+    def __init__(self, gmc=None, views=EXEMPLARS, buffer_s=6.0):
+        self.tr = _tracker(gmc)
+        self.views = views
+        # how long a track survives with no detection before it is
+        # declared ended, in SECONDS not frames: a frame count means
+        # different things at 5 fps and 30 fps, and the corpus chooses
+        # the frame rate.
+        self.buffer_s = buffer_s
+        self.open: dict[int, dict] = {}
+        self.last_ts = None
+
+    def update(self, ts, det, frame=None):
+        """One frame in; the tracks that CLOSED at this frame out.
+
+        `det` is (boxes Nx4, conf N, area N) from detect()/propose().
+        """
+        b, c, a = det
+        self.last_ts = int(ts)
+        seen = set()
+        if len(b):
+            xywh = np.stack([(b[:, 0] + b[:, 2]) / 2,
+                             (b[:, 1] + b[:, 3]) / 2,
+                             b[:, 2] - b[:, 0], b[:, 3] - b[:, 1]], 1)
+            rows = self.tr.update(
+                _Dets(xywh.astype(np.float32), c,
+                      np.zeros(len(b), np.float32)), frame)
+            for row in rows:
+                tid, di = int(row[-4]), int(row[-1])
+                if di >= len(b):
+                    continue
+                seen.add(tid)
+                t = self.open.setdefault(tid, {
+                    "ts": int(ts), "t1": int(ts), "n": 0, "t": [],
+                    "box": [], "conf": [], "area": [], "crops": []})
+                t["t1"] = int(ts)
+                t["n"] += 1
+                # the box list without its timestamps is a SHAPE, not a
+                # trajectory; every consumer that wanted motion had to
+                # guess the time axis back from (ts, t1, n)
+                t["t"].append(int(ts))
+                t["box"].append(b[di])
+                t["conf"].append(float(c[di]))
+                t["area"].append(float(a[di]))
+                # retain a bounded, spread set of views for the one
+                # ReID call this track will ever cost
+                if frame is not None and len(t["crops"]) < self.views:
+                    x0, y0, x1, y1 = (int(v) for v in b[di])
+                    if x1 > x0 and y1 > y0:
+                        t["crops"].append((b[di], frame[y0:y1, x0:x1]))
+        return self._reap(seen)
+
+    def _reap(self, seen):
+        gap = self.buffer_s * 1e9
+        done = []
+        for tid in list(self.open):
+            if tid in seen:
+                continue
+            if self.last_ts - self.open[tid]["t1"] > gap:
+                done.append((tid, self.open.pop(tid)))
+        return done
+
+    def flush(self):
+        """End of stream: everything still open is still real."""
+        out = list(self.open.items())
+        self.open = {}
+        return out
+
+
+def link(dets, frames=None, gmc=None):
+    """Associate one episode's consecutive detections into tracks.
+
+    Returns {track_id: {"f": [frame idx], "box": [...], "conf": [...],
+    "area": [...]}}. A fresh tracker per call, which is right only when
+    the caller really does have a scene cut. Prefer Stream for
+    continuous capture; this remains for corpora that ship discrete
+    clips, where resetting at a genuine cut avoids carrying Kalman state
+    across it.
+    """
+    tr = _tracker(gmc)
+    out: dict[int, dict] = {}
+    for j, (b, c, a) in enumerate(dets):
+        if not len(b):
+            continue
+        xywh = np.stack([(b[:, 0] + b[:, 2]) / 2, (b[:, 1] + b[:, 3]) / 2,
+                         b[:, 2] - b[:, 0], b[:, 3] - b[:, 1]], 1)
+        det = _Dets(xywh.astype(np.float32), c, np.zeros(len(b), np.float32))
+        rows = tr.update(det, None if frames is None else frames[j])
+        for row in rows:
+            # ultralytics packs [*xyxy, track_id, conf, cls, det_idx]
+            tid, di = int(row[-4]), int(row[-1])
+            if di >= len(b):
+                continue
+            t = out.setdefault(tid, {"f": [], "box": [], "conf": [],
+                                     "area": []})
+            t["f"].append(j)
+            t["box"].append(b[di])
+            t["conf"].append(float(c[di]))
+            t["area"].append(float(a[di]))
+    return out
+
+
+def _views(track, k=EXEMPLARS):
+    """Pick up to k frames of a track: the best-scoring view in each of
+    k equal slices of the track's life. Spread matters more than score -
+    k views of the same instant carry one view's worth of evidence."""
+    n = len(track["f"])
+    if n <= k:
+        return list(range(n))
+    edges = np.linspace(0, n, k + 1).round().astype(int)
+    conf = np.asarray(track["conf"])
+    return [int(a + conf[a:b].argmax())
+            for a, b in zip(edges[:-1], edges[1:]) if b > a]
+
+
+def features(frame, boxes):
+    """Appearance embedding per region. Vision only, no text."""
+    if not len(boxes):
+        return np.zeros((0, 512), np.float32)
+    m = _load()
+    b = np.asarray(boxes, np.float32)
+    xywh = np.stack([(b[:, 0] + b[:, 2]) / 2, (b[:, 1] + b[:, 3]) / 2,
+                     b[:, 2] - b[:, 0], b[:, 3] - b[:, 1]], 1)
+    f = np.asarray(m["reid"](frame, xywh))
+    f = f.reshape(len(boxes), -1).astype(np.float32)
+    return f / (np.linalg.norm(f, axis=1, keepdims=True) + 1e-8)
+
+
+def descriptors(frames, tracks, k=EXEMPLARS):
+    """One pooled appearance vector per track - the unit of upload.
+
+    This is the "break in continuity" moment: while a track holds, the
+    object store hears nothing about it. When the track is done, it is
+    described ONCE, by a mean over k views spread across its life, and
+    that single descriptor is what the store is asked about.
+    """
+    ids, out = [], []
+    for tid, t in tracks.items():
+        V = []
+        for i in _views(t, k):
+            V.append(features(frames[t["f"][i]], [t["box"][i]])[0])
+        v = np.mean(V, 0)
+        ids.append(tid)
+        out.append(v / (np.linalg.norm(v) + 1e-8))
+    return ids, (np.stack(out) if out else np.zeros((0, 512), np.float32))
+
+
+def _iou(a, b):
+    x0, y0 = max(a[0], b[0]), max(a[1], b[1])
+    x1, y1 = min(a[2], b[2]), min(a[3], b[3])
+    inter = max(x1 - x0, 0) * max(y1 - y0, 0)
+    ua = ((a[2] - a[0]) * (a[3] - a[1])
+          + (b[2] - b[0]) * (b[3] - b[1]) - inter)
+    return inter / ua if ua > 0 else 0.0
+
+
+def free_negatives(tracks, iou_max=0.1):
+    """Track-id pairs that are CERTAINLY different physical objects.
+
+    Two tracks occupying DISJOINT REGIONS OF THE SAME FRAME are two
+    different objects: one object cannot be in two places at one
+    instant, and the tracker has already linked each object to itself,
+    so a second track is a second thing. No annotation, no dataset
+    knowledge, no prior - geometry alone.
+
+    The disjointness test is not decoration. Co-existence ALONE is not
+    enough, because a detector will sometimes put two boxes on one
+    object; those two tracks co-exist and look identical, and they land
+    exactly in the high tail that a calibration quantile reads. Fitting
+    on co-existence alone drove the cut to its 0.95 ceiling on a 300-
+    episode run and fragmented the store to 1.21 sightings per object.
+    Requiring the boxes to be apart removes the double detections, which
+    are the only way two tracks of the same object can co-exist.
+    """
+    out, ids = [], list(tracks)
+    for x in range(len(ids)):
+        a = tracks[ids[x]]
+        fa = {f: i for i, f in enumerate(a["f"])}
+        for y in range(x + 1, len(ids)):
+            b = tracks[ids[y]]
+            shared = [f for f in b["f"] if f in fa]
+            if not shared:
+                continue
+            bf = {f: i for i, f in enumerate(b["f"])}
+            if all(_iou(a["box"][fa[f]], b["box"][bf[f]]) <= iou_max
+                   for f in shared):
+                out.append((ids[x], ids[y]))
+    return out
+
+
+def free_positives(tracks, iou_min=0.8):
+    """Track-id pairs that are CERTAINLY the SAME physical object.
+
+    The mirror of free_negatives, from the mirror of its argument. That
+    one says two tracks in DISJOINT regions of one frame are two objects,
+    because one object cannot be in two places at once. This one says two
+    tracks in the SAME region of one frame are ONE object, because two
+    objects cannot occupy one place at once. Both are geometry; neither
+    needs an annotation, a label or a dataset prior.
+
+    These pairs are DOUBLE DETECTIONS - the detector put two boxes on one
+    thing - which is why free_negatives works to exclude them. They were
+    treated as waste. They are not waste: they are the only proven-same
+    evidence this corpus can produce for free, and without them the cut
+    was fitted from one side of a two-sided decision.
+
+    iou_min is high on purpose. Overlap alone does not prove identity:
+    nested and contacting things - a lid on a jar, a hand on a pot -
+    overlap heavily and are two objects. Measured on fresh_bench, the
+    positive sample gets monotonically cleaner as the bar rises, and the
+    AUC it implies rises with it (0.860 at IoU>0.5 to 0.902 at IoU>0.95),
+    i.e. the loose bands are contaminated by exactly those nested pairs.
+    0.8 keeps thousands of pairs while paying most of that gap.
+
+    BIAS, stated, because it bounds what this can conclude: a same-frame
+    positive is the EASIEST positive there is - one instant, one
+    viewpoint, one exposure - while a same-frame negative is the HARDEST
+    negative. So the fitted cut is bracketed by two optimistic samples
+    pulling in opposite directions, and a genuine cross-episode
+    re-identification is harder than anything measured here.
+    """
+    out, ids = [], list(tracks)
+    for x in range(len(ids)):
+        a = tracks[ids[x]]
+        fa = {f: i for i, f in enumerate(a["f"])}
+        for y in range(x + 1, len(ids)):
+            b = tracks[ids[y]]
+            shared = [f for f in b["f"] if f in fa]
+            if not shared:
+                continue
+            bf = {f: i for i, f in enumerate(b["f"])}
+            if all(_iou(a["box"][fa[f]], b["box"][bf[f]]) >= iou_min
+                   for f in shared):
+                out.append((ids[x], ids[y]))
+    return out
+
+
+def interval_pairs(rows, iou_diff=0.1, iou_same=0.8, start_frac=0.25):
+    """free_negatives and free_positives over CLOSED intervals.
+
+    The write path does not hold tracks - it holds closed presence
+    intervals, each reduced to one box. Same two geometric arguments,
+    applied to what the writer actually has.
+
+    APPROXIMATION, stated: the retained box is the track's FIRST box, so
+    two boxes are only comparable when the tracks START together. That is
+    always true of the double detections the positive test is looking
+    for, and start_frac enforces it rather than assuming it. The negative
+    test does not need the guard - a pair wrongly called disjoint is a
+    pair dropped, not a pair mislabelled.
+
+    Args:
+        rows: (stream, meta) or (stream, meta, vec) as close_track emits;
+              meta carries ts, t1 and box.
+    Returns:
+        (neg, pos) index-pair lists into `rows`.
+    """
+    n = len(rows)
+    key = sorted(range(n), key=lambda i: (rows[i][0], rows[i][1]["ts"]))
+    neg, pos = [], []
+    for a in range(len(key)):
+        i = key[a]
+        si, mi = rows[i][0], rows[i][1]
+        for b in range(a + 1, len(key)):
+            j = key[b]
+            sj, mj = rows[j][0], rows[j][1]
+            if sj != si or mj["ts"] > mi["t1"]:
+                break                       # sorted: no later one overlaps
+            ov = _iou(mi["box"], mj["box"])
+            # the sweep runs in time order, so emit (min, max) rather
+            # than (earlier, later) - a pair is unordered and callers
+            # should not have to know which way round it came out.
+            e = (i, j) if i < j else (j, i)
+            if ov <= iou_diff:
+                neg.append(e)
+            elif ov >= iou_same:
+                span = min(mi["t1"] - mi["ts"], mj["t1"] - mj["ts"])
+                if abs(mj["ts"] - mi["ts"]) <= start_frac * max(span, 1):
+                    pos.append(e)
+    return neg, pos
+
+
+def handoff_pairs(rows, gap_s=1.0, iou_min=0.5):
+    """Proven-same evidence every corpus produces in BULK: track handoffs.
+
+    An interval that ends and another that begins at the same place
+    within `gap_s` is one object twice - things do not teleport, and
+    nothing else can arrive at that exact spot that fast. This is the
+    within-group continuity that double-detection positives cannot
+    supply (a clean proposer produces almost none: 77 pairs on the sim
+    corpus vs 927k negatives), and it is exactly the decision event
+    binding depends on: "is the block after the occlusion the block
+    from before it".
+
+    The retained box is the track's FIRST box, so a pair is emitted only
+    when the dying track's origin still overlaps the resuming track's
+    origin - true for the static objects that dominate any corpus, a
+    miss (never a mislabel) for objects whose track broke mid-flight.
+    """
+    from bisect import bisect_right
+    by = {}
+    for i, r in enumerate(rows):
+        by.setdefault(r[0], []).append(i)
+    out = []
+    gap = int(gap_s * 1e9)
+    for idxs in by.values():
+        idxs.sort(key=lambda i: rows[i][1]["ts"])
+        ts = [rows[i][1]["ts"] for i in idxs]
+        for i in idxs:
+            e = rows[i][1]["t1"]
+            for k in range(bisect_right(ts, e), bisect_right(ts, e + gap)):
+                j = idxs[k]
+                if _iou(rows[i][1]["box"], rows[j][1]["box"]) >= iou_min:
+                    out.append((i, j) if i < j else (j, i))
+    return out
+
+
+def calibrate(V, pairs, pos=None, q=CAL_Q, floor=0.5, ceil=0.95):
+    """Fit the match cut from proven pairs, on this corpus.
+
+    TWO-SIDED when proven-same pairs are supplied, and that is the
+    correction. The one-sided form below reads the q-th percentile of the
+    proven-DIFFERENT similarities - "tighter than all but q% of what I
+    can show is not the same object" - which is sound only if that sample
+    is clean. On fresh_bench it was not: double detections are 0.5% of
+    co-existing pairs and q=99.5 reads the top 0.5%, so the cut was very
+    nearly a readout of the contamination. It sat at 0.739, where only
+    26% of proven-same pairs are accepted, and the store fragmented to
+    78% singletons.
+
+    Fixing the contamination alone moves it to 0.692 - still 34% recall.
+    A one-sided fit cannot do better, because the tail of the negatives
+    says nothing about where the positives are. Hence Youden's J over
+    both: the cut that maximises (true accept rate - false merge rate),
+    the standard criterion when neither error has a stated price. It is
+    fitted, not chosen; no number here is hand-picked.
+
+    Fails safe in stages: no positives, use the one-sided percentile; too
+    few negatives to estimate at all, keep MATCH.
+
+    Args:
+        V: (N, D) unit-norm track descriptors.
+        pairs: proven-DIFFERENT index pairs, from free_negatives.
+        pos: proven-SAME index pairs, from free_positives. Optional.
+    """
+    if len(pairs) < 20:
+        return MATCH, len(pairs)
+    neg = np.array([float(V[i] @ V[j]) for i, j in pairs])
+    if pos is None or len(pos) < 20:
+        return float(np.clip(np.percentile(neg, q), floor, ceil)), len(neg)
+    p = np.array([float(V[i] @ V[j]) for i, j in pos])
+    grid = np.linspace(0.0, 1.0, 201)
+    j = ((p[None, :] >= grid[:, None]).mean(1)
+         - (neg[None, :] >= grid[:, None]).mean(1))
+    return float(np.clip(grid[int(j.argmax())], floor, ceil)), len(neg)
+
+
+def fit_cut(V, groups, neg, pos=None, grid=None, handoff=None):
+    """Fit the cut by MAXIMISING what identity is actually for.
+
+    Both free samples - proven-different and proven-same - are SAME-FRAME
+    pairs. The decision the gallery actually makes is not that one. It is
+    "is this new track the object I saw in a different episode?", and no
+    same-frame pair is evidence about it. So a statistic of those pairs
+    can bound the descriptor's quality but cannot choose the operating
+    point, and choosing it from one anyway is how the cut ended up where
+    it did.
+
+    The target quantity is measurable directly and needs no annotation:
+    HOW MANY OBJECTS RECUR ACROSS GROUPS. That is the whole point of a
+    persistent id, and it is self-limiting as an objective - too tight
+    and every sighting is a new id that recurs nowhere; too loose and
+    distinct objects collapse into one attractor, which also recurs
+    nowhere because there are no longer distinct objects to recur. It
+    therefore has an interior maximum, and that maximum is the fit.
+
+    Measured on fresh_bench (2,097 episodes, 73,521 intervals):
+
+        cut    objects  singletons  RECUR   worst false-merge
+        0.75    34,063     80.2%    6,447        0.18%
+        0.70    26,159     74.0%    6,475        0.22%   <- peak
+        0.60    14,011     57.3%    5,732        0.54%
+        0.50     6,320     36.8%    3,876        1.05%
+        0.42     2,618     19.4%    2,075        1.72%
+
+    which also disposes of the singleton rate as a target: driving it
+    from 80% to 19% costs two thirds of the recurrence and multiplies
+    proven-wrong merges by eight. Fewer, bigger, wronger objects.
+
+    Sweeping a cut used to be impossible - Gallery.assign was ~20 minutes
+    per pass - so the fit had to be a closed-form statistic. It is now
+    seconds, and an objective beats a proxy.
+
+    Args:
+        V: (N, D) unit-norm descriptors.
+        groups: (N,) group label per descriptor - the episode it sits in.
+        neg: proven-different pairs, for the reported false-merge rate.
+        pos: proven-same pairs, for the reported recovery rate.
+        grid: candidate cuts. Defaults to percentiles of the proven-
+              different similarities, so the range adapts to the corpus
+              rather than being a hand-written span.
+        handoff: track-handoff proven-same pairs (handoff_pairs). When
+              supplied in bulk they CONSTRAIN the objective - see below.
+    Returns:
+        (cut, report) - report lists every candidate that was tried.
+    """
+    g = np.asarray(groups)
+    g = g - g.min() + 1
+    span = int(g.max()) + 2
+    N = np.asarray(neg, np.int64).reshape(-1, 2)
+    Pp = np.asarray(pos if pos is not None else [], np.int64).reshape(-1, 2)
+    H = np.asarray(handoff if handoff is not None else [],
+                   np.int64).reshape(-1, 2)
+    if grid is None:
+        s = (np.einsum("ij,ij->i", V[N[:, 0]], V[N[:, 1]]) if len(N)
+             else np.array([MATCH]))
+        grid = np.unique(np.round(np.percentile(
+            s, [90, 95, 97.5, 99, 99.3, 99.5, 99.7, 99.9]), 3))
+
+    def _row(cut):
+        ids = Gallery(match=float(cut)).assign(V)
+        n = int(ids.max()) + 1
+        # objects present in more than one group
+        u = np.unique(ids.astype(np.int64) * span + g)
+        per = np.bincount((u // span).astype(np.int64), minlength=n)
+        row = {"cut": float(cut), "objects": n,
+               "recur": int((per > 1).sum()),
+               "singleton_pct": round(100.0 * float(
+                   (np.bincount(ids) == 1).mean()), 1)}
+        if len(N):
+            row["false_merge_pct"] = round(100.0 * float(
+                (ids[N[:, 0]] == ids[N[:, 1]]).mean()), 3)
+        if len(Pp):
+            row["recovered_pct"] = round(100.0 * float(
+                (ids[Pp[:, 0]] == ids[Pp[:, 1]]).mean()), 1)
+        if len(H):
+            row["handoff_pct"] = round(100.0 * float(
+                (ids[H[:, 0]] == ids[H[:, 1]]).mean()), 1)
+        return row
+
+    def _pick(rep):
+        # Recurrence alone is GAMEABLE BY FRAGMENTATION on a lookalike
+        # corpus: identical twins across episodes mean noise-clusters of
+        # one kind still span groups, so the count keeps rising as the
+        # cut climbs while real objects shatter (measured on the sim
+        # store: 21,492 objects for ~450 true blocks, 2.67 ids per
+        # block, 8% same-block event agreement). A cut that cannot
+        # re-find an object across a one-second track break identifies
+        # nothing - so when handoff pairs exist in bulk, continuity
+        # recovery is a CONSTRAINT on the recurrence objective, not a
+        # tiebreaker: maximise recurrence among cuts that recover >=70%
+        # of handoffs, and if none does, take the best recovery there is.
+        if len(H) >= 30:
+            ok = [r for r in rep if r.get("handoff_pct", 0.0) >= 70.0]
+            if ok:
+                return max(ok, key=lambda r: r["recur"])
+            return max(rep, key=lambda r: (r.get("handoff_pct", 0.0),
+                                           r["recur"]))
+        return max(rep, key=lambda r: r["recur"])
+
+    report = [_row(cut) for cut in grid]
+    best = _pick(report)
+    # The grid is percentiles of the proven-DIFFERENT similarities, and
+    # that anchor breaks when the descriptor is much better than the
+    # negatives are hard: recurrence keeps rising past the negatives'
+    # entire tail, the argmax lands on the grid's top edge, and the
+    # "interior maximum" was never actually bracketed. Measured on the
+    # DINOv3 rebuild: recur still climbing 7,590 -> 10,541 at the last
+    # point. So while the best cut IS the top edge, keep extending
+    # upward (midpoint steps toward 0.99) until the maximum is interior
+    # or the ceiling is reached - the fit must end bracketed, not
+    # truncated by an artifact of where the negatives happened to end.
+    while best["cut"] == report[-1]["cut"] and best["cut"] < 0.985:
+        report.append(_row(round(best["cut"]
+                                 + (0.99 - best["cut"]) / 2, 3)))
+        nxt = _pick(report)
+        if nxt["cut"] == best["cut"]:
+            break
+        best = nxt
+    return best["cut"], report
+
+
+class Gallery:
+    """Persistent identities, matched by appearance.
+
+    A GALLERY of exemplars per object, not a running mean. The mean is
+    what broke the earlier attempt: a centroid that updates as it
+    absorbs members lets a group CHAIN - green, to a slightly different
+    green, to red - so two objects merge through a path of intermediate
+    views. Several fixed exemplars, matched against the best of them,
+    has no such path. This is ordinary ReID gallery practice.
+
+    What it is asked about changed: entries are now TRACK descriptors
+    pooled over many frames, not single crops, so each question carries
+    a whole sighting's worth of evidence.
+    """
+
+    def __init__(self, match=MATCH, max_ex=MAX_EXEMPLARS, admit=ADMIT):
+        self.match, self.max_ex, self.admit = match, max_ex, admit
+        self.ex: list[np.ndarray] = []
+        self.n: list[int] = []
+        # every exemplar of every object in ONE matrix, plus which object
+        # owns each row. self.ex stays the public view of the same thing.
+        self._M = np.zeros((0, 0), np.float32)
+        self._own = np.zeros(0, np.int32)
+        self._m = 0
+
+    def _grow(self, dim):
+        if self._M.shape[0] > self._m:
+            return
+        cap = max(1024, self._M.shape[0] * 2)
+        M = np.zeros((cap, dim), np.float32)
+        if self._m:
+            M[:self._m] = self._M[:self._m]
+        own = np.zeros(cap, np.int32)
+        own[:self._m] = self._own[:self._m]
+        self._M, self._own = M, own
+
+    def assign(self, feats):
+        """Which object is each descriptor, in arrival order.
+
+        ONE matrix-vector product per descriptor, not one per object.
+        The old form looped over self.ex in Python, so a 73,521-track
+        corpus that had grown 32,756 objects did 2.4 billion iterations
+        of a two-line body - about 20 of the write's 54 minutes, and slow
+        enough that the cut could not be swept to find out it was wrong.
+
+        The reduction is exact, not an approximation: the best object is
+        the one owning the best EXEMPLAR, because max over objects of
+        (max over that object's exemplars) IS the max over all exemplars.
+        So a single argmax replaces the per-object max-then-compare.
+        """
+        ids = []
+        for v in feats:
+            v = np.ascontiguousarray(v, np.float32)
+            best, bs = -1, -1.0
+            if self._m:
+                s = self._M[:self._m] @ v
+                k = int(s.argmax())
+                best, bs = int(self._own[k]), float(s[k])
+            if best >= 0 and bs >= self.match:
+                ids.append(best)
+                self.n[best] += 1
+                E = self.ex[best]
+                # keep a view only if it ADDS one; near-duplicates of a
+                # stored exemplar teach the gallery nothing. Admit it
+                # only if it agrees with EVERY held exemplar - min(),
+                # not max() - so the acceptance region cannot sprawl.
+                if (len(E) < self.max_ex and bs < 0.95
+                        and float((E @ v).min()) >= self.admit):
+                    self.ex[best] = np.vstack([E, v])
+                    self._grow(len(v))
+                    self._M[self._m] = v
+                    self._own[self._m] = best
+                    self._m += 1
+            else:
+                self.ex.append(v[None, :])
+                self.n.append(1)
+                best = len(self.ex) - 1
+                ids.append(best)
+                self._grow(len(v))
+                self._M[self._m] = v
+                self._own[self._m] = best
+                self._m += 1
+        return np.asarray(ids, np.int32)
+
+    def centroids(self):
+        return np.stack([E.mean(0) / (np.linalg.norm(E.mean(0)) + 1e-8)
+                         for E in self.ex]) if self.ex else np.zeros(
+                             (0, 512), np.float32)
+
+    def __len__(self):
+        return len(self.ex)

python/elidedb/ingest.py

@@ -0,0 +1,158 @@
+"""Ingest primitives: the shared surface the write scripts build on.
+
+WHY THIS MODULE EXISTS
+----------------------
+`scripts/full_write.py` imported nine names from `scripts/write_once.py`,
+which is a SCRIPT with its own `main()`. That is the wrong dependency
+direction: a runnable entry point had become a library, so importing it
+pulled in argv parsing, module-level side effects and a second CLI, and
+neither file could be changed without checking the other.
+
+The same shape appears seven more times across `scripts/` - files
+importing `bench_product` for a constant, `extract_events` for two
+functions. Entry points should depend on the package; the package should
+never depend on an entry point.
+
+So the durable pieces live here, in `elidedb`, and the scripts become
+thin: parse arguments, call in, report. Anything with a `main()` is a
+program. Anything imported is a module. Not both.
+
+WHAT IS HERE
+------------
+Corpus geometry (where the bytes are, what the clock is) and the two
+loops every writer needs: streaming a file once, and cutting a demo's
+frames out of a continuous timeline.
+
+Dataset LAYOUT belongs in `corpus.json` (see corpus.py) rather than in
+constants here; the constants below are the Bridge defaults kept so the
+existing scripts keep working, and each is overridable.
+"""
+from __future__ import annotations
+
+import subprocess
+
+import numpy as np
+
+from .fftools import find
+
+# Bridge defaults. A different corpus supplies these through corpus.json
+# rather than by editing a constant - see corpus.Corpus.
+CAM = "observation.images.image_0"
+EPOCH_NS = 1_704_067_200_000_000_000
+FILE_STRIDE_NS = 20_000_000_000_000
+FPS = 5.0
+NGEOM = 12                      # frames per episode handed to geometry
+GEOM_W, GEOM_H = 256, 192       # geometry runs on its own small raster
+EMBED_W, EMBED_H = 192, 144     # FDNN-V's raster
+GAP_S = 60.0                    # silence inserted between demos
+CRF = 26                        # per-demo H.264 quality
+
+
+def gapped(spans, gap_s=GAP_S):
+    """Uniform gap between consecutive demos of a stream.
+
+    Without it two adjacent demos are contiguous in time and a window
+    query cannot express "this demo and not the next one". Returns
+    {(stream, t0): shift_ns}.
+    """
+    gap = int(gap_s * 1e9)
+    prev, shift = {}, {}
+    for s in sorted(spans, key=lambda r: (r["stream"], r["t0"])):
+        st = s["stream"]
+        new = s["t0"] if st not in prev else prev[st] + gap
+        shift[(st, s["t0"])] = new - s["t0"]
+        prev[st] = new + (s["t1"] - s["t0"])
+    return shift
+
+
+def frame_owner(spans, base, fps=FPS):
+    """{frame index -> episode id} for one file.
+
+    An episode owns EXACTLY the n frames the corpus declares. Deriving
+    the end by rounding t1 claims one extra frame at an inclusive bound -
+    verified against the seek-based writer, which produced 30 frames for
+    an episode where rounding produced 31, every other frame identical.
+    Trust the declared length, not a rounded timestamp.
+    """
+    owner = {}
+    for e in spans:
+        i0 = int(round((e["t0"] - base) / 1e9 * fps))
+        for i in range(i0, i0 + int(e["n"])):
+            owner[i] = e["episode"]
+    return owner
+
+
+def decode_stream(path, width=None, height=None, fps=FPS, chunk_frames=16):
+    """Decode a video ONCE, yielding raw RGB frames in batches.
+
+    The write path decoded the same pixels three times - once to cut
+    per-demo segments, once for the embedding raster, once again from
+    the store's own segments for region proposal. Measured, the third
+    was 41% of the presence stage and the second was the entire embed
+    stage. Everything that needs pixels should ride ONE decode, which is
+    what this yields.
+
+    `width`/`height` None keeps the source resolution: consumers that
+    want a smaller raster resize the frames they are given, rather than
+    each opening its own decoder.
+    """
+    vf = [f"fps={fps}"]
+    if width and height:
+        vf.append(f"scale={width}:{height}")
+    if width is None or height is None:
+        w, h = probe_size(path)
+        width, height = width or w, height or h
+    fb = width * height * 3
+    proc = subprocess.Popen(
+        [find("ffmpeg"), "-v", "error", "-i", str(path),
+         "-vf", ",".join(vf), "-f", "rawvideo", "-pix_fmt", "rgb24",
+         "pipe:1"], stdout=subprocess.PIPE, bufsize=fb * chunk_frames)
+    buf = b""
+    try:
+        while True:
+            data = proc.stdout.read(fb * chunk_frames - len(buf))
+            if data:
+                buf += data
+            n = len(buf) // fb
+            if n == 0 and not data:
+                break
+            if n == 0:
+                continue
+            yield np.frombuffer(buf[:n * fb], np.uint8).reshape(
+                n, height, width, 3)
+            buf = buf[n * fb:]
+    finally:
+        proc.stdout.close()
+        proc.wait()
+
+
+def probe_size(path):
+    """(width, height) of a video, without decoding it."""
+    r = subprocess.run(
+        [find("ffprobe"), "-v", "error", "-select_streams", "v:0",
+         "-show_entries", "stream=width,height", "-of", "csv=p=0",
+         str(path)], capture_output=True, text=True, check=True)
+    w, h = (int(x) for x in r.stdout.strip().split(",")[:2])
+    return w, h
+
+
+def encoder(path, width, height, fps=FPS, crf=CRF):
+    """An ffmpeg process that takes RAW FRAMES on stdin.
+
+    The store needs per-demo H.264 with exactly one IDR so a 2 s read is
+    a byte range. That encode is unavoidable; the DECODE inside it is
+    not - feeding already-decoded frames removes a whole pass over the
+    source.
+
+    -bf 0 keeps packet order equal to presentation order, which the
+    frame index depends on; -g/-keyint_min large with -sc_threshold 0
+    guarantees the single IDR.
+    """
+    return subprocess.Popen(
+        [find("ffmpeg"), "-v", "error", "-y",
+         "-f", "rawvideo", "-pix_fmt", "rgb24",
+         "-s", f"{width}x{height}", "-r", str(fps), "-i", "pipe:0",
+         "-an", "-c:v", "libx264", "-preset", "medium", "-crf", str(crf),
+         "-bf", "0", "-g", "10000", "-keyint_min", "10000",
+         "-sc_threshold", "0", "-f", "h264", str(path)],
+        stdin=subprocess.PIPE)

python/elidedb/itm.py

@@ -0,0 +1,175 @@
+"""ITM cross-encoder rerank — the discarded head, wired for live queries.
+
+InternVideo2's checkpoint ships an `itm_head` that every load discarded
+("Some weights ... were not used"). It is the cross-encoder half of the
+model's own retrieval recipe (BLIP-2 arXiv 2301.12597): text tokens
+cross-attend to video tokens, a 2-class head reads the fused CLS. It
+out-ranks everything else in this store — measured at k=1.5xsupport,
+ITM alone 0.38/0.25 against the cosine ensemble's 0.32/0.21 and the
+shipped RRF path's 0.29/0.23.
+
+Two measurements decide the shape of this module:
+
+  NO POOLING. Vision tokens are 1,025 x 1,408 per episode = 3.24 GB
+  corpus-wide, four times the raw source, so storing them in the store
+  is out. Pooling them is worse than out: 16x16 -> 8x8 per frame drops
+  Spearman against the full-token score to 0.18, and to NEGATIVE on two
+  of three probe queries. Cross-attention does not tolerate a reduced
+  key set. So the tokens are a disposable CACHE outside the store's
+  byte budget, never a table.
+
+  CASCADE, NOT SCAN. Reranking the top-N of the cheap fused ranking
+  reaches the full-scan number exactly: N=500 gives 0.40/0.27, N=150
+  already gives 0.38/0.25, and every query with support under ~200 is
+  saturated at N=150. So N scales with the ceiling k rather than the
+  corpus, which is L7 ("ITM is evidence inside a candidate set, not
+  authority over the corpus") arrived at from the cost side.
+
+ITM IS A STAGE, NOT A CHANNEL — and that distinction was measured, not
+chosen. Making it a weighted RRF voter and refitting cost 0.38 -> 0.27
+for two compounding reasons: RRF converts every channel to RANKS, which
+throws away the logit margin's scale, and that scale is where the
+cross-encoder's separation lives (the 0.40 offline number came from
+adding z-scores, not ranks); and the k-ladder refit then optimized the
+ladder mean away from the 1.5x-support operating point the product
+metric uses. So ITM stays a rerank STAGE alongside NMS and the
+confidence cut - stages the fitter switches on and off rather than
+weights - and the fit models it as such.
+
+The cache is content-addressed by (episode, model) and capped; deleting
+it costs time, never correctness.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import numpy as np
+
+_S: dict = {}
+# 3.24 GB holds the whole 1,122-episode corpus. This is a DISPOSABLE
+# cache under the store's _cache/, not a table: it never enters the
+# store's byte ledger, and deleting it costs recompute time, never
+# correctness. Override with ELIDEDB_ITM_CACHE_GB.
+CACHE_CAP_GB = float(__import__("os").environ.get(
+    "ELIDEDB_ITM_CACHE_GB", "4.0"))
+NF = 4
+
+
+def _head():
+    """The checkpoint's own 2-class matcher — AutoModel drops it because
+    the vendored class never declares the attribute."""
+    if "head" in _S:
+        return _S["head"], _S["m"], _S["dev"]
+    import torch
+
+    from .iv2 import MDIR, load_model
+    sd = torch.load(f"{MDIR}/pytorch_model.bin", map_location="cpu",
+                    weights_only=True, mmap=True)
+    m, dev = load_model()
+    h = torch.nn.Linear(sd["itm_head.weight"].shape[1], 2)
+    h.load_state_dict({"weight": sd["itm_head.weight"],
+                       "bias": sd["itm_head.bias"]})
+    h = h.to(dev, m.dtype).eval()
+    _S["head"], _S["m"], _S["dev"] = h, m, dev
+    return h, m, dev
+
+
+def _cache_dir(store):
+    d = Path(store.dir) / "_cache" / "itm_tokens"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _cache_path(store, stream, ts):
+    key = hashlib.sha1(f"{stream}|{ts}|iv2-1b|{NF}".encode()).hexdigest()
+    return _cache_dir(store) / f"{key}.npy"
+
+
+def _evict(store):
+    """Keep the disposable cache under CACHE_CAP_GB, oldest first."""
+    d = _cache_dir(store)
+    files = sorted(d.glob("*.npy"), key=lambda p: p.stat().st_mtime)
+    total = sum(p.stat().st_size for p in files)
+    cap = CACHE_CAP_GB * 1e9
+    while total > cap and files:
+        p = files.pop(0)
+        total -= p.stat().st_size
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+
+def _vision_tokens(store, frames_tbl, key):
+    """Cached (1, T, C) vision tokens for one episode."""
+    import cv2
+    import torch
+
+    from .iv2 import V_MEAN, V_STD
+    from .video import FrameSet
+    s, a, b = key
+    p = _cache_path(store, s, a)
+    _, m, dev = _head()
+    if p.exists():
+        arr = np.load(p)
+        return torch.from_numpy(arr).to(dev, m.dtype)
+    import pyarrow.compute as pc
+    sel = frames_tbl.filter(pc.and_(
+        pc.equal(frames_tbl.column("stream"), s),
+        pc.and_(pc.greater_equal(frames_tbl.column("ts"), a),
+                pc.less_equal(frames_tbl.column("ts"), b))))
+    if len(sel) < 2:
+        return None
+    pi = np.linspace(0, len(sel) - 1, min(NF, len(sel))).round().astype(int)
+    try:
+        dec = FrameSet(store, "frames", sel.take(pi)).decode(width=224)
+    except Exception:
+        return None
+    fr = [f for _, f in sorted(dec)]
+    if len(fr) < 2:
+        return None
+    fs = [cv2.resize(f, (224, 224)) for f in fr]
+    x = (np.stack(fs).astype(np.float32) / 255.0 - V_MEAN) / V_STD
+    px = torch.from_numpy(x).permute(0, 3, 1, 2)[None].to(dev, m.dtype)
+    with torch.no_grad():
+        vis, _ = m.encode_vision(px, test=True)
+    np.save(p, vis.cpu().numpy())
+    _evict(store)
+    return vis
+
+
+def itm_scores(store, text, keys):
+    """Logit margin P(match) - P(no match) for each candidate episode.
+
+    Returns np.array aligned with `keys`; NaN where frames are
+    undecodable. The vision pass dominates and is query-independent, so
+    a repeated query over the same candidates is nearly free."""
+    import torch
+    head, m, dev = _head()
+    frames_tbl = store.table("frames").scan()
+    tok = m.tokenizer(text, padding="max_length", truncation=True,
+                      max_length=m._config.max_txt_l,
+                      return_tensors="pt").to(dev)
+    out = np.full(len(keys), np.nan, np.float32)
+    for i, k in enumerate(keys):
+        vis = _vision_tokens(store, frames_tbl, k)
+        if vis is None:
+            continue
+        with torch.no_grad():
+            vam = torch.ones(vis.shape[:2], dtype=torch.long, device=dev)
+            o = m.get_text_encoder()(
+                tok.input_ids, attention_mask=tok.attention_mask,
+                encoder_hidden_states=vis, encoder_attention_mask=vam,
+                return_dict=True, mode="multi_modal")
+            lg = head(o.last_hidden_state[:, 0]).float()[0]
+        out[i] = float(lg[1] - lg[0])
+    return out
+
+
+def rerank_depth(k_max, n_total):
+    """Candidates to rerank. Measured: N=150 saturates every query with
+    support under ~200; only the 247-support query needed 500. Scaling
+    with the ceiling rather than the corpus keeps the cost proportional
+    to what the caller actually asked for."""
+    return int(min(max(150, 2 * k_max), n_total))

python/elidedb/iv2.py

@@ -0,0 +1,133 @@
+"""InternVideo2-Stage2 1B (Wang et al., ECCV 2024, arXiv 2403.15377)
+— the only true VIDEO-native text channel: stage-2 trains video-text
+contrastively WITH temporal modeling, which the frame-pooled image
+channels (PE, SigLIP2, X-CLIP pooling) structurally lack. Distilled
+small variants are reported much weaker on retrieval — 1B or nothing.
+
+One 512-d aligned vector per episode (4-frame clip, the f4
+checkpoint's native temporal extent), table iv2_vectors. Weights:
+ziyjiang/InternVideo2-1B (fp16 re-serialization of the official
+OpenGVLab stage2 checkpoint, towers only); modeling code vendored
+from VLM2Vec into models/iv2_stage2_1b by scripts/get_iv2.py (three
+MPS patches: flash-attn import guarded, LayerScale gamma naming so
+the checkpoint's 80 layer scales actually load, bert config resolved
+next to the file)."""
+from __future__ import annotations
+
+import numpy as np
+
+_S = {}
+
+MDIR = "models/iv2_stage2_1b"
+
+# InternVideo2's own demo preprocessing (frames2tensor): ImageNet
+# stats, 224 square, [B,T,C,H,W]
+V_MEAN = np.array([0.485, 0.456, 0.406], np.float32)
+V_STD = np.array([0.229, 0.224, 0.225], np.float32)
+
+
+def load_model():
+    if "model" not in _S:
+        from transformers import AutoModel
+
+        from .device import pick, strip_vision
+        dev, dtype = pick()
+        import transformers
+        kw = dict(trust_remote_code=True, torch_dtype=dtype)
+        if int(transformers.__version__.split(".")[0]) < 5:
+            # the 8GB-container path; transformers>=5 meta-device init
+            # breaks this custom port's from_pretrained, and the fp16
+            # towers load fine without it there
+            kw["low_cpu_mem_usage"] = True
+        m = AutoModel.from_pretrained(MDIR, **kw).to(dev).eval()
+        m = strip_vision(m, "vision_encoder")
+        m._config.device = dev      # get_txt_feat routes tokens here
+        _S["model"], _S["dev"], _S["dtype"] = m, dev, dtype
+    return _S["model"], _S["dev"]
+
+
+def text_vec(text):
+    cache = _S.setdefault("tcache", {})
+    if text in cache:
+        return cache[text]
+    m, _ = load_model()
+    v = m.get_txt_feat(text).float().cpu().numpy().reshape(-1)
+    if len(cache) > 256:
+        cache.clear()
+    cache[text] = v
+    return v
+
+
+def set_num_frames(n):
+    """Re-fit the vision encoder's temporal position embeddings to n
+    frames. OPT-IN and global to the loaded model.
+
+    The checkpoint ships a 4-frame clip: pos_embed is (1, 1 + 4*256, C),
+    and feeding 8 frames raises "size of tensor a (2049) must match
+    tensor b (1025)". That is a shape, not a capability - the patch
+    embedding is Conv3d with a kernel of (1,14,14), so tubelet size is
+    1 and T frames simply need T temporal positions. The repo's own
+    `interpolate_pos_embed(orig_t_size=4)` does exactly this, but only
+    while loading a checkpoint.
+
+    FOUR embeddings need it, not one: pos_embed AND clip_pos_embed both
+    carry the video-length grid (the image variants are separate and
+    untouched). Interpolating only the first fails deeper in the
+    forward, at the CLIP-alignment branch.
+
+    Sanity after interpolation: cos(4-frame, 8-frame) on the same span
+    is 0.999, i.e. the representation is preserved rather than rebuilt.
+    """
+    import torch
+    m, _ = load_model()
+    ve = m.vision_encoder
+    old = int(ve.num_frames)
+    if old == n:
+        return
+    def _interp(p):
+        cls, rest = p[:, :1, :], p[:, 1:, :]
+        C = rest.shape[-1]
+        L = rest.shape[1] // old
+        r = rest.view(1, old, L, C).permute(0, 3, 2, 1).float()
+        r = torch.nn.functional.interpolate(
+            r, size=(L, n), mode="bilinear", align_corners=False)
+        r = r.permute(0, 3, 2, 1).reshape(1, n * L, C).to(p.dtype)
+        return torch.nn.Parameter(torch.cat([cls, r], 1),
+                                  requires_grad=False)
+    L = (ve.pos_embed.shape[1] - 1) // old
+    for name in ("pos_embed", "clip_pos_embed"):
+        if hasattr(ve, name):
+            setattr(ve, name, _interp(getattr(ve, name).data))
+    ve.num_frames = n
+    ve.patch_embed.num_patches = n * L
+
+
+def clip_vec(frames_hwc):
+    """Aligned 512-d vector for a clip (HWC uint8 RGB).
+
+    Length must match the encoder's current num_frames - 4 by default,
+    or whatever set_num_frames() last fitted."""
+    import cv2
+    import torch
+    m, dev = load_model()
+    fs = [cv2.resize(f, (224, 224)) for f in frames_hwc]
+    x = (np.stack(fs).astype(np.float32) / 255.0 - V_MEAN) / V_STD
+    px = torch.from_numpy(x).permute(0, 3, 1, 2)[None].to(
+        dev, _S["dtype"])
+    return m.get_vid_feat(px).float().cpu().numpy().reshape(-1)
+
+
+def iv2_lookup(store, text):
+    from .embeddings import _vec_table
+    tbl, vecs = _vec_table(store, "iv2_vectors")
+    key = {}
+    for r, (s, a) in enumerate(zip(
+            tbl.column("stream").to_pylist(),
+            (int(v) for v in tbl.column("ts").to_pylist()))):
+        key[(str(s), a)] = r
+    sc = np.asarray(vecs) @ text_vec(text)
+
+    def lookup(s, a, b):
+        r = key.get((str(s), a))
+        return float(sc[r]) if r is not None else float("nan")
+    return lookup, None

python/elidedb/lexicon.py

@@ -0,0 +1,61 @@
+"""Closed-class English lexicon shared by query routing and training.
+
+Dependency-free ON PURPOSE: the query path imports this (via
+rerank.directional_swap), and it previously reached the same tables
+through fdnnv2, whose module level imports mlx. That worked on a Mac
+and crashed every Linux deployment. Lexicon is language knowledge, not
+model code; it lives where nothing heavier than a list comprehension
+runs.
+
+Verb/direction swaps: GENERIC english antonyms, no dataset nouns, per
+the no-hardwire rule.
+"""
+from __future__ import annotations
+
+# ---------------------------------------------------------------------
+# DERIVED OPPOSITES. The 81 pairs below and the 16 `un-` bases were
+# hand-authored, and fold/stack/cover are conspicuously this corpus's
+# vocabulary - a task prior in a file that claims to hold generic
+# English. The swap-contrast MECHANISM is sound and measured; the list
+# was not derived.
+#
+# derived_swaps() replaces it: opposites are found by reflection in an
+# embedding space over the vocabulary the CORPUS attested. On a driving
+# log that finds accelerate/brake without anyone having thought of them;
+# here it finds open/close. The hand list stays only as a cold-start
+# fallback for an empty store, and is labelled as such rather than
+# presented as knowledge.
+# ---------------------------------------------------------------------
+
+
+def derived_swaps(store, vec=None, min_count=2):
+    """Opposite pairs this corpus supports, or () if it cannot say."""
+    from .derive import attested, opposite_pairs
+    try:
+        if "labels" not in store.tables():
+            return ()
+        vals = store.table("labels").scan().column("value").to_pylist()
+        vocab = attested(vals, min_count=min_count)
+        if len(vocab) < 8:
+            return ()
+        if vec is None:
+            from .sig2 import _text_vec as vec
+        return tuple((a, b) for a, b, _ in opposite_pairs(vocab, vec))
+    except Exception:
+        return ()
+
+
+# THERE IS NO VERB TABLE. VERB_SWAPS (17 hand-authored pairs) and
+# _UN_BASES (16 hand-authored stems that generated ~64 more) lived here
+# as a "cold-start fallback", labelled a violation by their own comment
+# and kept anyway. A fallback that always fires is not a fallback: on
+# every store measured, derived_swaps returned 0 pairs, so the hand list
+# WAS the direction mechanism, and it was also feeding the student's
+# training negatives.
+#
+# Removed. derived_swaps() above is the only source of oppositions: what
+# THIS corpus attests, scored in its own embedding space. A corpus that
+# cannot express an opposition now yields None, and callers must handle
+# that honestly rather than borrow English from a list. A forklift
+# corpus gets forklift oppositions or it gets nothing - which is the
+# rule, and the point.

python/elidedb/log.py

@@ -0,0 +1,293 @@
+"""Transaction log: the Delta-Lake idea at StreetDex scale.
+
+A table's state is not "the files in the directory" — it is the fold of an
+append-only log of JSON commits. That one move buys, with plain files:
+
+- **snapshot isolation / time travel**: version N is immutable forever; a
+  reader at version N never sees version N+1's files.
+- **atomic multi-file commits**: a commit lands as one exclusively-created
+  log entry (O_EXCL is the lock — single writer, many readers).
+- **file-level zone maps**: every added file records rows/bytes/min_ts/max_ts,
+  so a time-window query prunes whole files from the log alone, before any
+  Parquet footer is opened. (Row-group pruning inside surviving files is
+  Parquet's own statistics — two layers, same idea.)
+- **schema-on-log**: the schema travels with the commit, so evolution is an
+  append, never a rewrite.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class FileEntry:
+    path: str  # relative to the table dir
+    rows: int
+    bytes: int
+    min_ts: int
+    max_ts: int
+    # Zone map for columns BEYOND ts: {column: [min, max]}. min_ts/max_ts
+    # are the same idea hard-coded for the one column every table has;
+    # this generalises it to whatever a table is clustered on, so
+    # "object_id == 7" can drop a file from the LOG - kilobytes of JSON
+    # already in memory - instead of opening its Parquet footer. That is
+    # a layer below Parquet: layer 0 costs nothing per file, the footer
+    # costs a seek and a read per surviving file, and at a thousand
+    # files the difference is the query.
+    #
+    # Only meaningful for a column the file is CLUSTERED on. A min/max
+    # over an unsorted column spans nearly the whole domain and prunes
+    # nothing, so the writer records these only for its sort keys -
+    # a zone map that never prunes is pure metadata cost.
+    zone: dict = field(default_factory=dict)
+    # END of the latest interval in this file, i.e. max(t1) - NOT
+    # max(ts). For point-like rows the two are the same and this is
+    # redundant; for INTERVALS they are not, and the difference is a
+    # wrong answer rather than a slow one.
+    #
+    # An object present from t=100 to t=900 in a file whose starts span
+    # 100..200 has max_ts=200. A query for [400, 500] overlaps that
+    # object, but `max_ts < t0` prunes the whole file and returns
+    # nothing. Verified: 0 rows where 1 was correct. Every table until
+    # now was point-like or short-lived so it never fired; presence
+    # intervals - "this object was on the table for four hours" - are
+    # exactly the shape that breaks it.
+    max_end: int = 0
+
+    def to_json(self):
+        d = dict(self.__dict__)
+        if not d["zone"]:
+            d.pop("zone")     # old readers, and old files, see no change
+        if not d["max_end"]:
+            d.pop("max_end")
+        return d
+
+    @staticmethod
+    def from_json(d):
+        # a file written before max_end existed falls back to max_ts,
+        # which is CONSERVATIVE only for point-like rows. It is recorded
+        # as such rather than silently trusted: see overlaps().
+        return FileEntry(d["path"], d["rows"], d["bytes"], d["min_ts"],
+                         d["max_ts"], d.get("zone", {}),
+                         int(d.get("max_end", 0)))
+
+    def overlaps(self, t0, t1) -> bool:
+        """True unless this file provably holds no interval meeting
+        [t0, t1]. Compares against the interval END, so a long-lived row
+        that starts before the window is not pruned away."""
+        end = self.max_end or self.max_ts
+        if t0 is not None and end < t0:
+            return False
+        if t1 is not None and self.min_ts > t1:
+            return False
+        return True
+
+    def may_contain(self, column, lo, hi) -> bool:
+        """False only when this file PROVABLY holds nothing in [lo, hi].
+
+        Absent statistics must answer True: a missing zone map means
+        unknown, never empty. Every file written before zone maps
+        existed takes that branch, so the optimisation degrades to the
+        old behaviour instead of silently losing rows.
+        """
+        z = self.zone.get(column)
+        if not z:
+            return True
+        return not (hi < z[0] or lo > z[1])
+
+
+@dataclass
+class TableState:
+    version: int = 0
+    kind: str = "timeseries"
+    schema: str = ""
+    files: list[FileEntry] = field(default_factory=list)
+    meta: dict = field(default_factory=dict)
+
+    @property
+    def rows(self):
+        return sum(f.rows for f in self.files)
+
+    @property
+    def bytes(self):
+        return sum(f.bytes for f in self.files)
+
+    @property
+    def min_ts(self):
+        return min((f.min_ts for f in self.files), default=0)
+
+    @property
+    def max_ts(self):
+        return max((f.max_ts for f in self.files), default=0)
+
+
+CHECKPOINT_EVERY = 10  # Delta checkpoints every 10th commit; same dial here
+
+
+def _fsync_dir(path: Path):
+    """Durability of a file's *existence* requires fsyncing its directory —
+    the metadata write that makes the entry reachable after power loss."""
+    fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def fsync_file(path: Path):
+    fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+class CommitConflict(RuntimeError):
+    """A concurrent commit removed files this transaction depended on."""
+
+
+class TableLog:
+    def __init__(self, table_dir: Path):
+        self.dir = Path(table_dir)
+        self.log_dir = self.dir / "_log"
+
+    def versions(self) -> list[int]:
+        if not self.log_dir.is_dir():
+            return []
+        return sorted(int(p.stem) for p in self.log_dir.glob("*.json")
+                      if p.stem.isdigit())
+
+    def _checkpoints(self) -> list[int]:
+        if not self.log_dir.is_dir():
+            return []
+        return sorted(int(p.name.split(".")[0])
+                      for p in self.log_dir.glob("*.checkpoint.json"))
+
+    def read_state(self, version: int | None = None) -> TableState:
+        st = TableState()
+        start = 0
+        # Checkpoints make the fold O(commits since checkpoint) instead of
+        # O(all commits) — the log stays an audit trail without becoming a
+        # read cost. Same move as Delta's _last_checkpoint.
+        for v in reversed(self._checkpoints()):
+            if version is None or v <= version:
+                c = json.loads(
+                    (self.log_dir / f"{v:020d}.checkpoint.json").read_text())
+                st.version = c["version"]
+                st.kind = c["kind"]
+                st.schema = c["schema"]
+                st.meta = dict(c["meta"])
+                st.files = [FileEntry.from_json(f) for f in c["files"]]
+                start = v
+                break
+        for v in self.versions():
+            if v <= start:
+                continue
+            if version is not None and v > version:
+                break
+            entry = json.loads((self.log_dir / f"{v:020d}.json").read_text())
+            st.version = v
+            st.kind = entry.get("table_kind", st.kind)
+            st.schema = entry.get("schema", st.schema)
+            st.meta.update(entry.get("meta", {}))
+            removed = set(entry.get("remove", []))
+            if removed:
+                st.files = [f for f in st.files if f.path not in removed]
+            st.files += [FileEntry.from_json(f) for f in entry.get("add", [])]
+        return st
+
+    def commit(self, *, op: str, kind: str, schema: str = "",
+               add: list[FileEntry] = (), remove: list[str] = (),
+               meta: dict | None = None, retries: int = 5) -> int:
+        """Optimistic concurrency, Delta-style: O_EXCL on the next log entry
+        is the lock. Losing the race means retrying at the next version —
+        append-vs-append never truly conflicts. Commits that REMOVE files
+        revalidate against the fresh state first: if a concurrent writer
+        already removed one of ours, that is a real conflict and we fail
+        cleanly instead of double-applying."""
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        for _ in range(retries):
+            version = (self.versions() or [0])[-1] + 1
+            if remove:
+                active = {f.path for f in self.read_state().files}
+                missing = [r for r in remove if r not in active]
+                if missing:
+                    raise CommitConflict(
+                        "files no longer active (concurrent rewrite?): "
+                        f"{missing[:3]}")
+            entry = {
+                "version": version,
+                "ts_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "op": op,
+                "table_kind": kind,
+                "schema": schema,
+                "add": [f.to_json() for f in add],
+                "remove": list(remove),
+                "meta": meta or {},
+            }
+            path = self.log_dir / f"{version:020d}.json"
+            # Torn-write-proof commit: the entry is fully written and fsynced
+            # under a temp name, then hard-LINKED to its final name. link()
+            # is atomic AND exclusive (fails if the name exists), so a
+            # partially-written entry can never appear under a version name —
+            # a crash leaves only an ignorable *.tmp. Atomicity + durability
+            # in one primitive; fsync of the directory makes the rename
+            # itself survive power loss.
+            tmp = self.log_dir / f".{version:020d}.{os.getpid()}.tmp"
+            fd = os.open(tmp, os.O_CREAT | os.O_WRONLY | os.O_TRUNC)
+            with os.fdopen(fd, "w") as f:
+                f.write(json.dumps(entry, indent=1))
+                f.flush()
+                os.fsync(f.fileno())
+            try:
+                os.link(tmp, path)
+            except FileExistsError:
+                os.unlink(tmp)
+                continue  # lost the race — re-read state, take the next slot
+            os.unlink(tmp)
+            _fsync_dir(self.log_dir)
+            if version % CHECKPOINT_EVERY == 0:
+                st = self.read_state(version)
+                cp_tmp = self.log_dir / f".cp{version}.{os.getpid()}.tmp"
+                cp_tmp.write_text(
+                    json.dumps({"version": st.version, "kind": st.kind,
+                                "schema": st.schema, "meta": st.meta,
+                                "files": [f.to_json() for f in st.files]}))
+                os.replace(cp_tmp,  # checkpoints are derived: replace is fine
+                           self.log_dir / f"{version:020d}.checkpoint.json")
+            # `_meta.json` beside the table: the human/tool-readable summary
+            # of CURRENT state (schema, rows, bytes, ts range) so a store
+            # browser or a pilot's script answers "what is in this table?"
+            # with one file read, not a log replay. Derived — a failure
+            # here must never fail the commit.
+            try:
+                st = self.read_state(version)
+                meta_tmp = self.dir / f".meta.{os.getpid()}.tmp"
+                meta_tmp.write_text(json.dumps({
+                    "version": st.version, "op": op, "kind": st.kind,
+                    "rows": sum(f.rows for f in st.files),
+                    "bytes": sum(f.bytes for f in st.files),
+                    "files": len(st.files),
+                    "min_ts": min((f.min_ts for f in st.files), default=None),
+                    "max_ts": max((f.max_ts for f in st.files), default=None),
+                    "schema": st.schema, "meta": st.meta,
+                    "ts_utc": entry["ts_utc"]}, indent=1))
+                os.replace(meta_tmp, self.dir / "_meta.json")
+            except Exception:
+                pass
+            return version
+        raise CommitConflict(f"lost the commit race {retries} times")
+
+    def history(self) -> list[dict]:
+        out = []
+        for v in self.versions():
+            e = json.loads((self.log_dir / f"{v:020d}.json").read_text())
+            out.append({"version": v, "ts_utc": e["ts_utc"], "op": e["op"],
+                        "added_files": len(e.get("add", [])),
+                        "added_rows": sum(a["rows"] for a in e.get("add", [])),
+                        "meta": e.get("meta", {})})
+        return out

python/elidedb/migrate.py

@@ -0,0 +1,163 @@
+"""v1 (custom SDX/SFI binaries) → v2 (Parquet lake) migration.
+
+Reads the v1 store's own files — SDX columnar chunks, SFI frame tables,
+embedding runs — and rewrites each as Parquet tables under a transaction
+log. Raw media files stay exactly where they are; only indexes and sensor
+rows move. This is the "no custom datatypes" pivot: the v1 formats keep
+working for the C++ engine, but the go-forward store is open-format.
+"""
+from __future__ import annotations
+
+import json
+import struct
+import sys
+from pathlib import Path
+
+import numpy as np
+import pyarrow as pa
+
+from .store import Store
+
+_SDX_TYPES = {0: ("i8", 8), 1: ("f8", 8), 2: ("f4", 4), 3: ("i8", 8), 4: ("i2", 2)}
+
+
+def read_sdx(path) -> pa.Table:
+    """Minimal SDX v1 reader (layout: FORMAT.md §1)."""
+    data = Path(path).read_bytes()
+    assert data[:4] == b"SDX1" and data[-4:] == b"SDX1", f"bad SDX: {path}"
+    (flen,) = struct.unpack_from("<I", data, len(data) - 8)
+    off = len(data) - 8 - flen
+    def u16():
+        nonlocal off; (v,) = struct.unpack_from("<H", data, off); off += 2; return v
+    def u32():
+        nonlocal off; (v,) = struct.unpack_from("<I", data, off); off += 4; return v
+    def i64():
+        nonlocal off; (v,) = struct.unpack_from("<q", data, off); off += 8; return v
+    def s():
+        nonlocal off
+        n = u16()
+        v = data[off:off + n].decode(); off += n; return v
+    _ver, _flags = u16(), u16()
+    _sid, _units = s(), s()
+    _clock_off = i64()
+    _chunk_target = u32()
+    ncol = u16()
+    cols = []
+    for _ in range(ncol):
+        name = s(); ty = data[off]; off += 2
+        cols.append((name, ty))
+    nchunk = u32()
+    spans = [[] for _ in cols]
+    for _ in range(nchunk):
+        _rows = u32(); off_pad = u32()  # noqa: F841
+        for c in range(ncol):
+            (doff, dlen, _mn, _mx) = struct.unpack_from("<QQQQ", data, off)
+            off += 32
+            spans[c].append((doff, dlen))
+    arrays = {}
+    for c, (name, ty) in enumerate(cols):
+        np_ty, _w = _SDX_TYPES[ty]
+        parts = [np.frombuffer(data, dtype=np_ty,
+                               count=dlen // int(np_ty[1]),
+                               offset=doff) for (doff, dlen) in spans[c]]
+        arrays["ts" if c == 0 else name] = np.concatenate(parts) if parts else \
+            np.array([], np_ty)
+    return pa.table({k: pa.array(v) for k, v in arrays.items()})
+
+
+def _sfi_frame_table(sfi_path, source_path, stream, width, height, codec):
+    sys.path.insert(0, str(Path(__file__).parents[2] / "ml"))
+    from sfi_reader import read_sfi
+    sfi = read_sfi(str(sfi_path))
+    fr = sfi.frames
+    n = len(fr)
+    return pa.table({
+        "ts": pa.array(fr["pts_ns"].astype("int64")),
+        "byte_offset": pa.array(fr["byte_offset"].astype("int64")),
+        "packet_size": pa.array(fr["packet_size"].astype("int32")),
+        "keyframe": pa.array((fr["flags"] & 1).astype(bool)),
+        "width": pa.array(np.full(n, width, "int32")),
+        "height": pa.array(np.full(n, height, "int32")),
+        "codec": pa.array([codec] * n),
+        "source": pa.array([str(source_path)] * n),
+        "stream": pa.array([stream] * n),
+    })
+
+
+def migrate_v1(v1_store: str, out_path: str, name: str,
+               run_id: str | None = None, verbose=True) -> Store:
+    v1 = Path(v1_store)
+    cur = int((v1 / "CURRENT").read_text().strip())
+    man = json.loads((v1 / "manifests" / f"manifest-{cur}.json").read_text())
+    db = Store.create(out_path, name)
+
+    # video: every SFI → rows of ONE frame_index table ("frames")
+    for vs in man.get("video_streams", []):
+        for seg in vs["segments"]:
+            t = _sfi_frame_table(v1 / seg["sfi_path"], seg["source_path"],
+                                 vs["stream_id"], vs.get("width", 0),
+                                 vs.get("height", 0), "mjpeg")
+            db.table("frames").append(t, kind="frame_index",
+                                      meta={"migrated_from": seg["sfi_path"]})
+            if verbose:
+                print(f"  frames << {vs['stream_id']} ({len(t)} rows)")
+
+    # sensors: every SDX → its own timeseries table
+    for ss in man.get("sensor_streams", []):
+        t = read_sdx(v1 / ss["sdx_path"])
+        tname = ss["stream_id"].replace("/", "_").replace(" ", "_").lower()
+        db.table(tname).append(t, meta={"migrated_from": ss["sdx_path"]})
+        if verbose:
+            print(f"  {tname} << {len(t):,} rows")
+
+    # embeddings run → embeddings + centroids tables
+    if run_id is None and man.get("semantic_run"):
+        run_id = man["semantic_run"]["run_id"]
+    if run_id:
+        run = v1 / "ml" / run_id
+        win = json.loads((run / "windows.json").read_text())
+        dim = win["dim"]
+        vecs = np.fromfile(run / "embeddings.f32", dtype=np.float32) \
+            .reshape(-1, dim)
+        labels = None
+        if (run / "clusters.json").exists():
+            cj = json.loads((run / "clusters.json").read_text())
+            labels = np.array(cj["labels"], "int32")
+            cents = np.array(cj["centroids"], "float32")
+        t = pa.table({
+            "ts": pa.array([w["t0_ns"] for w in win["windows"]], pa.int64()),
+            "t1": pa.array([w["t1_ns"] for w in win["windows"]], pa.int64()),
+            "stream": pa.array([w["stream_id"] for w in win["windows"]]),
+            "vector": pa.array([v.tolist() for v in vecs],
+                               pa.list_(pa.float32(), dim)),
+            **({"cluster": pa.array(labels)} if labels is not None else {}),
+        })
+        meta = json.loads((run / "meta.json").read_text())
+        db.table("embeddings").append(
+            t, kind="embeddings",
+            meta={"model": meta["model"], "dim": dim,
+                  "window_s": meta.get("window_s"), "migrated_from": run_id})
+        if labels is not None and len(cents):
+            ct = pa.table({
+                "ts": pa.array([0] * len(cents), pa.int64()),
+                "cluster": pa.array(range(len(cents)), pa.int32()),
+                "vector": pa.array([c.tolist() for c in cents],
+                                   pa.list_(pa.float32(), dim)),
+            })
+            db.table("centroids").append(ct, kind="centroids")
+        if verbose:
+            print(f"  embeddings << {len(t)} windows (dim {dim})")
+    return db
+
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser()
+    ap.add_argument("v1_store")
+    ap.add_argument("out")
+    ap.add_argument("--name", required=True)
+    args = ap.parse_args()
+    db = migrate_v1(args.v1_store, args.out, args.name)
+    for d in db.describe():
+        print(f"{d['table']:14s} {d['kind']:12s} {d['rows']:>12,} rows "
+              f"{d['bytes'] / 1e6:9.1f} MB  v{d['version']}")