@tpsdev-ai/flair 0.51.2 → 0.53.0

package/dist/resources/embedding-space-guard.js

@@ -0,0 +1,238 @@
+/**
+ * embedding-space-guard.ts — the QUERY-TIME vector-space uniformity gate
+ * (embedding-provider-seam design §3, slice 1; K&S-final).
+ *
+ * ─── The bug this closes ────────────────────────────────────────────────────
+ * There is NO query-time embedding-space guard today. Search cosines a query
+ * against every stored vector regardless of its `embeddingModel` stamp;
+ * Harper's `cosineDistance` silently zero-pads a mismatched-dimension vector
+ * and returns a garbage score instead of throwing (same-dims/different-space
+ * is silent garbage too), and `health.ts` only *warns*. So a mixed-space
+ * corpus — the transient state during ANY re-embed / model change — serves
+ * silently-wrong recall. This module makes a mismatched-space cosine
+ * impossible by construction on BOTH runtime cosine legs (recall + write-time
+ * dedup), the load-bearing safety piece Kern made a condition of sign-off.
+ *
+ * ─── Shape ──────────────────────────────────────────────────────────────────
+ * A PURE core (`normalizeStamp` / `currentSpaceRawForms` / `isUniformStampSet`
+ * — Harper-free, unit-testable directly, same discipline as dedup.ts / bm25.ts)
+ * plus a boot-computed + write-maintained "corpus uniform in the current space"
+ * LATCH so the gate costs ~nothing per query:
+ *   - boot pre-warm scans the DISTINCT active stamps once (module side effect,
+ *     same convention as embeddings-boot.ts / migration-boot.ts);
+ *   - a write persisting a FOREIGN stamp (federation / replication / an
+ *     explicit-stamp PUT) trips the latch immediately, no rescan;
+ *   - while tripped, a consult re-verifies at most once per RECHECK_MS, so a
+ *     completed re-embed REOPENS the gate automatically (any re-embed path —
+ *     the boot migration OR a live `flair reembed`), with no cross-process
+ *     signal needed.
+ * Both runtime legs consult the SAME `isEmbeddingSpaceUniform()` — a single
+ * chokepoint (like `prefixesEnabled()`), never scattered per-call-site checks.
+ *
+ * ─── Why the harper import is deferred ──────────────────────────────────────
+ * `harper` is dynamic-imported inside the scan only (never a top-level import)
+ * — exactly the reason embeddings-provider.ts defers it: a static
+ * `import { databases } from "harper"` would make ANY test that imports this
+ * file for its pure core alone eagerly load Harper's real `dist/index.js`,
+ * which throws at module scope outside a real Harper boot. The pure exports
+ * carry no harper dependency at all.
+ */
+import { EMBEDDING_ENGINE, getModelId } from "./embeddings-provider.js";
+// ─── Pure core (Harper-free) ────────────────────────────────────────────────
+/**
+ * Stamps that denote "no real vector space" and so never contribute to the
+ * uniformity set: an absent/empty stamp, and the legacy `hash-512d`
+ * hash-fallback marker (a row with no genuine model embedding). A missing or
+ * empty stored embedding cosines to a safe 0 (retrieval-core / dedup both
+ * guard `Array.isArray(embedding) ? … : []`), never a cross-space garbage
+ * score, so excluding these mirrors health.ts's own `realModels` filter.
+ */
+const NON_SPACE_STAMPS = new Set(["hash-512d"]);
+/**
+ * Canonicalize an `embeddingModel` stamp to its ENGINE-QUALIFIED space id, or
+ * `null` for a no-vector-space stamp. This is the one-time bare-name → `gguf:`
+ * equivalence: today's corpus is stamped with the BARE nomic name (no engine
+ * prefix), which denotes the SAME space as the engine-qualified id
+ * `getModelId()` now writes — so a bare stamp must NOT read as a foreign space
+ * and false-trip the gate. A qualified stamp (any engine, contains `:`) is
+ * already canonical; a bare stamp (no `:`) is the legacy gguf form and gets the
+ * `<engine>:` prefix. `getModelId()` guarantees a model id never itself
+ * contains `:` (it rejects a `FLAIR_EMBEDDING_MODEL` override that does), so a
+ * single `:` unambiguously separates engine from model.
+ */
+export function normalizeStamp(stamp) {
+    if (stamp == null)
+        return null;
+    const s = String(stamp).trim();
+    if (s === "" || NON_SPACE_STAMPS.has(s))
+        return null;
+    return s.includes(":") ? s : `${EMBEDDING_ENGINE}:${s}`;
+}
+/** The bare model id of an engine-qualified stamp (`gguf:x` → `x`); a stamp
+ *  with no engine prefix is returned unchanged. Inverse of the prefixing in
+ *  `normalizeStamp`. */
+export function stripEnginePrefix(stamp) {
+    const i = stamp.indexOf(":");
+    return i === -1 ? stamp : stamp.slice(i + 1);
+}
+/**
+ * The RAW stamp forms that all denote the CURRENT embedding space: the
+ * engine-qualified id `getModelId()` returns, plus its one-time bare-name
+ * equivalent. A stamp comparator (the migration's staleCondition, the CLI's
+ * `--stale-only`) treats a row as current-space iff its stamp is one of these,
+ * so a bare-stamped legacy row is never re-embedded as "stale". De-duplicated
+ * so a bare `currentModelId` (a unit-test injection) yields a single form.
+ */
+export function currentSpaceRawForms(currentModelId) {
+    return [...new Set([currentModelId, stripEnginePrefix(currentModelId)])];
+}
+/** Pure: is `stamp` one of the current-space raw forms? (metadata-string
+ *  compare only — never a vector-byte comparison; see
+ *  embedding-identity-tripwire.test.ts / flair#749). */
+export function isCurrentSpaceStamp(stamp, currentModelId) {
+    const n = normalizeStamp(stamp);
+    return n !== null && n === normalizeStamp(currentModelId);
+}
+/**
+ * Pure: is every active (real-vector) stamp in the set the current space? An
+ * empty set (fresh store) is uniform. No-vector stamps (null / `hash-512d`)
+ * are ignored — they carry no cross-space cosine hazard.
+ */
+export function isUniformStampSet(distinctStamps, currentModelId) {
+    const current = normalizeStamp(currentModelId);
+    for (const raw of distinctStamps) {
+        const n = normalizeStamp(raw);
+        if (n === null)
+            continue;
+        if (n !== current)
+            return false;
+    }
+    return true;
+}
+async function defaultTableGetter() {
+    const { databases } = await import("harper");
+    return databases.flair.Memory;
+}
+let _tableGetter = defaultTableGetter;
+let _modelIdGetter = getModelId;
+// `undefined` = not yet computed (pre-boot). Consult treats this as "scan
+// now"; a scan failure leaves it undefined so the next consult retries rather
+// than caching a verdict we could not compute.
+let _uniform = undefined;
+let _activeStamps = []; // normalized, capped — for the degrade diagnostic only
+let _lastScanAt = 0;
+let _scanning;
+// While the latch is TRIPPED, re-verify at most this often, so a completed
+// re-embed reopens the gate without paying a scan on every degraded query.
+// The happy (uniform) path never scans here at all — it returns in O(1).
+const RECHECK_MS = 30_000;
+const MAX_DIAG_STAMPS = 12;
+async function scan() {
+    const current = normalizeStamp(_modelIdGetter());
+    const seen = new Set();
+    let uniform = true;
+    try {
+        const table = await _tableGetter();
+        // Project ONLY the stamp — never the vector — so the boot scan is far
+        // cheaper than health.ts's existing full-record corpus read.
+        for await (const row of table.search({ select: ["embeddingModel"] })) {
+            const n = normalizeStamp(row.embeddingModel);
+            if (n === null)
+                continue;
+            if (seen.size < MAX_DIAG_STAMPS)
+                seen.add(n);
+            if (n !== current)
+                uniform = false;
+        }
+        _activeStamps = [...seen];
+        _uniform = uniform;
+        _lastScanAt = Date.now();
+    }
+    catch {
+        // No live table yet (boot race) — leave the prior verdict untouched and
+        // retry on the next consult. Never cache a verdict we couldn't compute.
+    }
+}
+function runScan() {
+    if (!_scanning)
+        _scanning = scan().finally(() => { _scanning = undefined; });
+    return _scanning;
+}
+/**
+ * THE single chokepoint. Returns true when the store is uniform in the current
+ * embedding space (safe to cosine the query/candidate against stored vectors),
+ * false when it is not (a mixed-space corpus — the caller must NOT cosine).
+ *
+ * O(1) on the happy path: once known-uniform, no scan, no allocation. Only
+ * (re)scans when the latch is unknown (pre-boot) or tripped-and-stale.
+ */
+export async function isEmbeddingSpaceUniform() {
+    if (_uniform === true)
+        return true;
+    if (_uniform === undefined || Date.now() - _lastScanAt >= RECHECK_MS) {
+        await runScan();
+    }
+    return _uniform ?? true;
+}
+/**
+ * Write-maintained trip: a persisted FOREIGN-space stamp closes the gate
+ * immediately, no rescan. A normal local write always stamps the current id
+ * (`getModelId()`), so it never trips; only a federation/replication write or
+ * an explicit-stamp PUT carrying another space's stamp does.
+ */
+export function noteWriteStamp(stamp) {
+    const n = normalizeStamp(stamp);
+    if (n === null)
+        return;
+    if (n !== normalizeStamp(_modelIdGetter())) {
+        if (!_activeStamps.includes(n) && _activeStamps.length < MAX_DIAG_STAMPS)
+            _activeStamps.push(n);
+        _uniform = false;
+    }
+}
+/**
+ * Force a fresh corpus scan and return the resulting uniformity. The explicit
+ * "re-embed completion clears it" primitive — used by the boot pre-warm, and
+ * callable after a bulk re-embed to reopen the gate promptly rather than
+ * waiting out RECHECK_MS.
+ */
+export async function recomputeLatch() {
+    _lastScanAt = 0; // bypass the throttle
+    await scan();
+    return _uniform ?? true;
+}
+/**
+ * Structured diagnostic for the degrade path — the current space id and the
+ * (capped) set of distinct active stamps observed, so the recall leg's
+ * `_warning` can name both spaces + the `flair reembed` remedy. Metadata
+ * strings only, never vectors.
+ */
+export function spaceGuardDiagnostics() {
+    return { current: normalizeStamp(_modelIdGetter()) ?? _modelIdGetter(), found: [..._activeStamps] };
+}
+// ─── Boot pre-warm (module side effect) ──────────────────────────────────────
+// Best-effort, single-shot, deferred to after the current synchronous load
+// phase (same setImmediate convention as migration-boot.ts). If it fires
+// before the Memory table is live, the scan silently no-ops and the first real
+// consult computes the latch lazily — correctness never depends on this
+// pre-warm, only the first query's latency does.
+let _prewarmScheduled = false;
+export function scheduleSpaceGuardPrewarm() {
+    if (_prewarmScheduled)
+        return;
+    _prewarmScheduled = true;
+    setImmediate(() => { void recomputeLatch().catch(() => { }); });
+}
+// Test-only seams — mirror embeddings-boot.ts's `_resetEmbeddingsBackendRegistrationForTests`.
+export function _setGuardTableGetterForTests(fn) { _tableGetter = fn; }
+export function _setGuardModelIdForTests(fn) { _modelIdGetter = fn; }
+export function _resetGuardForTests() {
+    _tableGetter = defaultTableGetter;
+    _modelIdGetter = getModelId;
+    _uniform = undefined;
+    _activeStamps = [];
+    _lastScanAt = 0;
+    _scanning = undefined;
+    _prewarmScheduled = false;
+}
+scheduleSpaceGuardPrewarm();

package/dist/resources/embeddings-provider.js

@@ -367,14 +367,31 @@ export function getMode() {
  * mass "stale" transition is this flip's intended payload, not a bug.
  */
 const EMBEDDING_VARIANT = "searchprefix";
+/**
+ * The embedding ENGINE identity carried by every model-id stamp
+ * (embedding-provider-seam design, slice 1). `gguf` is the only engine today
+ * (harper-fabric-embeddings' GGUF backend); the seam that SELECTS an
+ * alternative engine is slice 2 — this slice only QUALIFIES the stamp so the
+ * vector-space guard can tell two engines apart even when they share a model
+ * name/dims (dims-only would silently pass a mixed comparison — Sherlock
+ * binding req #3). Kept next to getModelId() so the stamp and
+ * resources/embedding-space-guard.ts's one-time bare-name → `gguf:`
+ * equivalence read the SAME constant and cannot drift.
+ */
+export const EMBEDDING_ENGINE = "gguf";
 /**
  * Get the current embedding model identifier.
  * Used for stamping memories and detecting stale embeddings. Reads the SAME
  * `prefixesEnabled()` chokepoint `buildEmbedOptions()` does (see THE GATE's
- * doc above `EMBEDDING_PREFIXES_ENABLED`) — gate on (default): bumps to
- * `<base>+searchprefix` (see `EMBEDDING_VARIANT` above). Gate off (only
- * reachable now via the bench-only override, see `harnessPrefixOverride()`):
- * bare base id, no suffix. A prefixed vector and an unprefixed vector of the
+ * doc above `EMBEDDING_PREFIXES_ENABLED`) — gate on (default): returns the
+ * engine-qualified `<engine>:<base>+searchprefix` (see `EMBEDDING_ENGINE` /
+ * `EMBEDDING_VARIANT` above). Gate off (only reachable now via the bench-only
+ * override, see `harnessPrefixOverride()`): `<engine>:<base>`, no suffix. The
+ * `<engine>:` prefix is new in embedding-space-guard slice 1; a legacy BARE
+ * stamp (no prefix) denotes the SAME gguf space and is reconciled by
+ * resources/embedding-space-guard.ts's normalizeStamp() and the migration/CLI
+ * stale comparators, so today's corpus is NOT read as stale. A prefixed vector
+ * and an unprefixed vector of the
  * SAME text are genuinely different vectors (dedup must not short-circuit
  * across them), and `--stale-only` needs a distinct string to target the
  * rows that still need re-embedding. `+` is URL-safe and doesn't collide
@@ -384,7 +401,17 @@ const EMBEDDING_VARIANT = "searchprefix";
  */
 export function getModelId() {
     const base = process.env.FLAIR_EMBEDDING_MODEL ?? "nomic-embed-text-v1.5-Q4_K_M";
-    return prefixesEnabled() ? `${base}+${EMBEDDING_VARIANT}` : base;
+    // The bare-name override must not collide with the `<engine>:<model>` stamp
+    // format — a ':' in the base makes the qualified stamp ambiguous
+    // (`gguf:a:b`) and would break the guard's engine/model split. Fail loudly at
+    // the stamp site rather than silently writing an un-parseable id (a shipped
+    // config default is a trust anchor: derive or fail, never fail-open).
+    if (base.includes(":")) {
+        throw new Error(`[embeddings] FLAIR_EMBEDDING_MODEL must not contain ':' — it is reserved for the ` +
+            `<engine>:<model> embedding stamp (embedding-space-guard slice 1); got ${JSON.stringify(base)}`);
+    }
+    const suffix = prefixesEnabled() ? `+${EMBEDDING_VARIANT}` : "";
+    return `${EMBEDDING_ENGINE}:${base}${suffix}`;
 }
 /**
  * Get embedding engine status for diagnostics.

package/dist/resources/federation-classify.js

@@ -23,7 +23,28 @@ export const FEDERATION_TABLE_POLICY = {
     Soul: { principalOwning: false },
     Agent: { principalOwning: false },
     Relationship: { principalOwning: false },
+    // Flair Relay S1 (flair#1521): the Message envelope's owning principal is the
+    // SENDER (`from`), not `agentId` — see PRINCIPAL_OWNER_FIELD below. S1 does
+    // not sync Message cross-host (the spoke push list in src/cli.ts is a separate
+    // hardcoded set), but the policy + owner-field land now so S2 is not a schema
+    // or policy migration (the design's ship-order, flair#1521 §12).
+    Message: { principalOwning: true },
 };
+/**
+ * Per-table owning-principal field. `checkPrincipalEntitlement` used to hardcode
+ * the owner as `data.agentId` (correct for Memory, the only principal-owning
+ * table then). Message owns by `from`, so the owner field is now a per-table
+ * map rather than a literal. Tables absent here fall back to `agentId` — only
+ * principal-owning tables ever reach the check, and Memory keeps its field.
+ */
+export const PRINCIPAL_OWNER_FIELD = {
+    Memory: "agentId",
+    Message: "from",
+};
+/** The owning-principal field for a table (default `agentId`). */
+export function principalOwnerField(table) {
+    return PRINCIPAL_OWNER_FIELD[table] ?? "agentId";
+}
 export const FEDERATION_SYNC_TABLES = Object.keys(FEDERATION_TABLE_POLICY);
 export const PRINCIPAL_OWNING_TABLES = new Set(FEDERATION_SYNC_TABLES.filter((t) => FEDERATION_TABLE_POLICY[t].principalOwning));
 /** Wire `v` when present; assume 1 when absent (today's records omit it). */
@@ -80,11 +101,12 @@ export function checkPrincipalEntitlement(record, opts = {}) {
     if (!PRINCIPAL_OWNING_TABLES.has(record.table)) {
         return null;
     }
+    const ownerField = principalOwnerField(record.table);
     const v = recordSignatureVersion(record);
     if (v >= 2) {
         if (typeof record.principalId !== "string" ||
             record.principalId.length === 0 ||
-            record.principalId !== record.data?.agentId) {
+            record.principalId !== record.data?.[ownerField]) {
             return "principal_mismatch";
         }
         return null;

package/dist/resources/health.js

@@ -10,6 +10,7 @@ import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
 import { hybridEnabled } from "./bm25.js";
 import { bm25IndexEnabled, bm25IndexStatus } from "./bm25-index-service.js";
+import { normalizeStamp } from "./embedding-space-guard.js";
 import { buildPublicHealthBody, resolveSearchReadiness } from "./search-readiness.js";
 const db = databases;
 const redactHome = (p) => {
@@ -248,8 +249,16 @@ export class HealthDetail extends Resource {
                     });
                 }
             }
-            // Mixed embedding models — searches across vector spaces return garbage.
-            if (realModels.length > 1) {
+            // Mixed embedding SPACES — searches across vector spaces return garbage.
+            // Count distinct SPACES, not raw stamps: after the engine-qualified stamp
+            // (embedding-space-guard slice 1) a healthy corpus can carry BOTH the
+            // qualified id (`gguf:…`) and its bare-name equivalent (today's rows) for
+            // the SAME space — normalize so that pairing is one space, not a false
+            // "mixed" warning. A genuine multi-space corpus (a real mid-flight
+            // re-embed) still trips it, and that is exactly when the query-time guard
+            // degrades recall to keyword-only.
+            const distinctSpaces = new Set(realModels.map((k) => normalizeStamp(k)).filter((s) => s !== null));
+            if (distinctSpaces.size > 1) {
                 const list = realModels.map((k) => `${k}:${modelCounts[k]}`).join(", ");
                 warnings.push({
                     level: "warn",

package/dist/resources/hit-tracking.js

@@ -0,0 +1,244 @@
+/**
+ * hit-tracking.ts — search-hit counters without rewriting Memory (flair#1528).
+ *
+ * SemanticSearch used to `patchRecord` every returned hit:
+ *   retrievalCount: (row.retrievalCount || 0) + 1
+ * that is a full-row Harper put (embeddings included). Concurrent searches
+ * of the same hits lost increments (read-modify-write on the retrieved
+ * snapshot) and still wrote storage on a read path.
+ *
+ * This module is the remaining #1528 slice (BM25 metadata-skip already
+ * landed in #1545 and is not revisited here):
+ *   - increments go to MemoryHitStat, a small per-id row, never Memory
+ *   - per-id promise tails serialize flushes and coalesce pending deltas
+ *     so overlapping hits add instead of racing
+ *   - GET /Memory/{id}, Memory.search, AdminMemory detail, and consolidate
+ *     overlay the stat row so retrievalCount / lastRetrieved stay the
+ *     observable Memory fields they have always been
+ *
+ * Fire-and-forget from SemanticSearch: a failed flush is swallowed, same
+ * best-effort class as the previous `.catch(() => {})` patch. Bootstrap
+ * still does not call this module.
+ *
+ * Every Harper call is wrapped individually in withDetachedTxn — never one
+ * wrap around a multi-await helper. Search already read Memory on the
+ * request context; a later HitStat get/put on that closed chain would
+ * inherit the closed transaction (table-helpers.ts / usage-recording.ts).
+ */
+import { databases } from "harper";
+import { withDetachedTxn } from "./table-helpers.js";
+function asRow(value, id) {
+    if (!value)
+        return null;
+    return {
+        id,
+        retrievalCount: Number(value.retrievalCount) || 0,
+        lastRetrieved: value.lastRetrieved,
+    };
+}
+export class HitTracker {
+    tables;
+    pending = new Map();
+    tails = new Map();
+    cache = new Map();
+    metricsState = { writes: 0, successfulPuts: 0, failedPuts: 0 };
+    constructor(tables) {
+        this.tables = tables;
+    }
+    get metrics() {
+        return { ...this.metricsState };
+    }
+    noteHits(ids, now, ctx) {
+        for (const id of ids) {
+            if (typeof id !== "string" || id.length === 0)
+                continue;
+            const prev = this.pending.get(id);
+            if (prev) {
+                prev.delta += 1;
+                prev.lastRetrieved = now;
+            }
+            else {
+                this.pending.set(id, { delta: 1, lastRetrieved: now });
+            }
+            this.enqueueFlush(id, ctx);
+        }
+    }
+    async apply(record, ctx) {
+        if (!record || typeof record !== "object")
+            return record;
+        const id = record.id;
+        if (typeof id !== "string" || id.length === 0)
+            return record;
+        const stat = await this.statFor(id, ctx);
+        if (!stat)
+            return record;
+        const current = record;
+        if (current.retrievalCount === stat.retrievalCount && current.lastRetrieved === stat.lastRetrieved) {
+            return record;
+        }
+        return { ...record, retrievalCount: stat.retrievalCount, lastRetrieved: stat.lastRetrieved };
+    }
+    async statFor(id, ctx) {
+        const cached = this.cache.get(id);
+        if (cached)
+            return cached;
+        const read = await this.readStat(id, ctx);
+        if (read.kind !== "hit")
+            return null;
+        this.cache.set(id, read.row);
+        return read.row;
+    }
+    async whenIdle() {
+        for (let spins = 0; spins < 32; spins++) {
+            for (const id of this.pending.keys())
+                this.enqueueFlush(id);
+            if (this.tails.size === 0 && ![...this.pending.values()].some((p) => p.delta > 0))
+                return;
+            await Promise.all([...this.tails.values()]);
+        }
+    }
+    async clear(id, ctx) {
+        this.pending.delete(id);
+        this.cache.delete(id);
+        if (!this.tables.stats.delete)
+            return;
+        await withDetachedTxn(ctx, () => this.tables.stats.delete(id));
+    }
+    enqueueFlush(id, ctx) {
+        const prev = this.tails.get(id) ?? Promise.resolve();
+        const next = prev
+            .then(() => this.runFlush(id, ctx))
+            .catch(() => { })
+            .finally(() => {
+            if (this.tails.get(id) === next)
+                this.tails.delete(id);
+        });
+        this.tails.set(id, next);
+    }
+    async runFlush(id, ctx) {
+        const taken = this.pending.get(id);
+        if (!taken || taken.delta <= 0)
+            return;
+        this.pending.delete(id);
+        const read = await this.readStat(id, ctx);
+        // A get error is not a miss. Memory.retrievalCount is frozen once
+        // increments moved off the Memory row — seeding from it and putting
+        // would overwrite the unread committed HitStat count (Bugbot on #1565).
+        if (read.kind === "error") {
+            this.requeue(id, taken);
+            return;
+        }
+        let base = read.kind === "hit" ? read.row.retrievalCount : null;
+        if (base == null) {
+            const memory = await withDetachedTxn(ctx, () => this.tables.memory.get(id)).catch(() => null);
+            base = memory?.retrievalCount ?? 0;
+        }
+        const row = {
+            id,
+            retrievalCount: base + taken.delta,
+            lastRetrieved: taken.lastRetrieved,
+        };
+        this.metricsState.writes += 1;
+        try {
+            await withDetachedTxn(ctx, () => this.tables.stats.put(row));
+            this.metricsState.successfulPuts += 1;
+            this.cache.set(id, row);
+        }
+        catch {
+            this.metricsState.failedPuts += 1;
+            this.requeue(id, taken);
+        }
+    }
+    requeue(id, taken) {
+        const again = this.pending.get(id);
+        if (again) {
+            again.delta += taken.delta;
+            if (taken.lastRetrieved > (again.lastRetrieved ?? ""))
+                again.lastRetrieved = taken.lastRetrieved;
+        }
+        else {
+            this.pending.set(id, taken);
+        }
+    }
+    async readStat(id, ctx) {
+        try {
+            const raw = await withDetachedTxn(ctx, () => this.tables.stats.get(id));
+            const row = asRow(raw, id);
+            return row ? { kind: "hit", row } : { kind: "miss" };
+        }
+        catch {
+            return { kind: "error" };
+        }
+    }
+}
+function liveTables() {
+    const statsTable = () => databases.flair?.MemoryHitStat;
+    const memoryTable = () => databases.flair?.Memory;
+    return {
+        stats: {
+            get: async (id) => {
+                const table = statsTable();
+                if (!table?.get)
+                    return null;
+                return table.get(id);
+            },
+            put: async (row) => {
+                const table = statsTable();
+                if (!table?.put)
+                    return;
+                return table.put(row);
+            },
+            delete: async (id) => {
+                const table = statsTable();
+                if (!table?.delete)
+                    return;
+                return table.delete(id);
+            },
+        },
+        memory: {
+            get: async (id) => {
+                const table = memoryTable();
+                if (!table?.get)
+                    return null;
+                return table.get(id);
+            },
+        },
+    };
+}
+let live;
+export function liveHitTracker() {
+    live ??= new HitTracker(liveTables());
+    return live;
+}
+/** Fire-and-forget increment for SemanticSearch's returned hit ids. */
+export function noteSearchHits(ids, now, ctx) {
+    liveHitTracker().noteHits(ids, now, ctx);
+}
+/** Overlay MemoryHitStat onto a Memory-shaped record. */
+export function applyHitStats(record, ctx) {
+    return liveHitTracker().apply(record, ctx);
+}
+/** Overlay an async-iterable / thenable Memory search result. */
+export function overlayHitStatsResult(result, ctx) {
+    if (result && typeof result.then === "function") {
+        return result.then((value) => overlayHitStatsResult(value, ctx));
+    }
+    if (!result || result instanceof Response)
+        return result;
+    if (typeof result[Symbol.asyncIterator] === "function") {
+        const tracker = liveHitTracker();
+        return (async function* overlayHits() {
+            for await (const row of result) {
+                yield await tracker.apply(row, ctx);
+            }
+        })();
+    }
+    return liveHitTracker().apply(result, ctx);
+}
+export function clearHitStats(id, ctx) {
+    return liveHitTracker().clear(id, ctx);
+}
+/** Test-only: drop the process singleton so the next call rebuilds it. */
+export function resetLiveHitTracker() {
+    live = undefined;
+}