@tpsdev-ai/flair 0.48.0 → 0.49.0

package/dist/lib/mcp-enable.js

@@ -555,12 +555,57 @@ function opsBaseUrl(opsPortOrUrl) {
 function basicAuthHeader(adminUser, adminPass) {
     return `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
 }
+/** The resolver's own predicate, verbatim (resources/mcp-handler.ts
+ *  `resolveAgentFromSub`): a credential is resolvable unless it is explicitly
+ *  revoked. The linking layer MUST use the same test — a credential the linker
+ *  considers inactive but the resolver would still serve is exactly the
+ *  invisible-duplicate hole #1317 is about. */
+function isResolvableCredential(cred) {
+    return cred?.status !== "revoked";
+}
 /**
  * Map the operator's IdP subject to their principal via `Credential(kind:
  * "idp")` — the SAME credential surface resources/mcp-handler.ts's
- * `resolveAgentFromSub` reads at request time. Idempotent: an existing
- * mapping for (provider, subject) is reused (lastUsedAt bumped) rather than
- * duplicated; the principal Agent is created only if missing.
+ * `resolveAgentFromSub` reads at request time.
+ *
+ * ## The uniqueness constraint (flair#1317, K&S ruling 2026-08-21)
+ *
+ * **At most one ACTIVE `Credential(kind:"idp", idpSubject:<sub>)` exists at a
+ * time, regardless of `idpProvider`.** This function is where that invariant is
+ * enforced, because it is the only supported writer of the mapping.
+ *
+ * It used to dedup on `(kind, idpProvider, idpSubject)` while the resolver read
+ * `(kind, idpSubject)`. A re-link under a different provider name therefore
+ * matched nothing, INSERTED a second active credential, and left
+ * `resolveAgentFromSub` picking whichever row its search iterator served first
+ * — identity resolution by iteration order, on a security-relevant mapping.
+ *
+ * The resolver's key is the correct one and does not change: an IdP subject is
+ * an identity, and "who is this subject?" has exactly one answer. `idpProvider`
+ * stays on the row as audit/diagnostic metadata, but it does not participate in
+ * uniqueness. So:
+ *
+ *   - same provider, existing active credential → RE-POINT it (`credentialReused`);
+ *   - any OTHER active credential for the subject → SUPERSEDE it: terminal
+ *     `status: "revoked"`, never a soft flag a later path could flip back
+ *     (revoked rows are never reused here — a re-link after a revoke mints a
+ *     fresh credential);
+ *   - the re-point/insert and every revocation go out as ONE ops-API `upsert`
+ *     batch, so there is no observable window with two active credentials or
+ *     zero. If the batch fails, nothing is claimed and the call throws;
+ *   - after the write the invariant is RE-READ and asserted. A store that
+ *     somehow holds ≠1 active credential for the subject is a hard error, not a
+ *     silent nondeterministic mapping.
+ *
+ * The principal Agent is created only if missing.
+ *
+ * RESIDUAL RISK, by design (Sherlock, #1317): whoever can call this for a
+ * subject can revoke that subject's prior credential. If two genuinely
+ * different people ever shared a subject string across providers, one's link
+ * kills the other's mapping. IdP subjects are opaque per-IdP identifiers so the
+ * collision is remote, and the alternative — duplicate active credentials with
+ * order-dependent resolution — is strictly worse. `credentialSuperseded` exists
+ * so the operator is told, not so the event is hidden.
  */
 export async function provisionIdpIdentityMapping(params, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
@@ -628,26 +673,43 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
         }
         principalCreated = true;
     }
-    // Reuse an existing Credential(kind:idp, provider, subject) mapping if present.
-    const searchCredRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({
-            operation: "search_by_conditions",
-            database: "flair",
-            table: "Credential",
-            operator: "and",
-            conditions: [
-                { search_attribute: "kind", search_type: "equals", search_value: "idp" },
-                { search_attribute: "idpProvider", search_type: "equals", search_value: params.idpProvider },
-                { search_attribute: "idpSubject", search_type: "equals", search_value: params.idpSubject },
-            ],
-            get_attributes: ["id", "principalId"],
-        }),
-    });
-    const existingCreds = searchCredRes.ok ? await searchCredRes.json().catch(() => []) : [];
-    const existing = Array.isArray(existingCreds) ? existingCreds[0] : undefined;
-    const credentialId = existing?.id ?? `cred_idp_${params.idpProvider}_${randomBytes(6).toString("hex")}`;
+    // ── flair#1317: look SUBJECT-WIDE, not (provider, subject) ─────────────────
+    // The resolver's key is (kind, idpSubject); anything narrower here leaves
+    // credentials that dedup cannot see but resolution can.
+    const findCredentialsForSubject = async () => {
+        const res = await fetchImpl(opsUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: authHeader },
+            body: JSON.stringify({
+                operation: "search_by_conditions",
+                database: "flair",
+                table: "Credential",
+                operator: "and",
+                conditions: [
+                    { search_attribute: "kind", search_type: "equals", search_value: "idp" },
+                    { search_attribute: "idpSubject", search_type: "equals", search_value: params.idpSubject },
+                ],
+                get_attributes: ["id", "principalId", "idpProvider", "idpSubject", "status", "label", "createdAt"],
+            }),
+        });
+        const body = res.ok ? await res.json().catch(() => []) : [];
+        return Array.isArray(body) ? body : [];
+    };
+    const subjectCreds = await findCredentialsForSubject();
+    const activeCreds = subjectCreds.filter(isResolvableCredential);
+    // Survivor: an ACTIVE same-provider credential is re-pointed (the idempotent
+    // re-run and the documented same-provider link). A revoked one is never
+    // resurrected — a re-link after a revoke mints a fresh credential.
+    const reused = activeCreds.find((c) => c?.idpProvider === params.idpProvider && c?.id);
+    const credentialId = reused?.id ?? `cred_idp_${params.idpProvider}_${randomBytes(6).toString("hex")}`;
+    // Everything else active for this subject is superseded. Under the old
+    // (provider, subject) key these rows were simply invisible; they are what made
+    // resolution order-dependent.
+    const superseded = activeCreds.filter((c) => c?.id && c.id !== credentialId);
+    // ONE batched write: the survivor first, then the revocations. A single
+    // ops-API operation is the strongest atomicity this surface can express, and
+    // ordering the survivor first means even a partially-applied batch can never
+    // leave the subject with ZERO resolvable credentials (the fail-open denial).
     const upsertRes = await fetchImpl(opsUrl, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: authHeader },
@@ -664,9 +726,25 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
                     status: "active",
                     idpProvider: params.idpProvider,
                     idpSubject: params.idpSubject,
-                    createdAt: existing ? undefined : now,
+                    createdAt: reused ? undefined : now,
                     lastUsedAt: now,
                 },
+                // Retained, not deleted: the revocation stays legible in storage and in
+                // Harper's table audit log (which records the full record image of
+                // every write). Identifying fields are echoed back so the row survives
+                // as a well-formed, revoked credential whichever merge semantics the
+                // ops API applies.
+                ...superseded.map((c) => ({
+                    id: c.id,
+                    principalId: c.principalId,
+                    kind: "idp",
+                    label: c.label,
+                    status: "revoked",
+                    idpProvider: c.idpProvider,
+                    idpSubject: params.idpSubject,
+                    createdAt: c.createdAt,
+                    updatedAt: now,
+                })),
             ],
         }),
     });
@@ -674,7 +752,26 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
         const text = await upsertRes.text().catch(() => "");
         throw new Error(`Identity mapping: failed to write Credential(kind:idp) mapping (HTTP ${upsertRes.status}): ${text}`);
     }
-    return { principalCreated, credentialId, credentialReused: Boolean(existing) };
+    // ── The invariant, RE-READ ────────────────────────────────────────────────
+    // Asserting what we intended to write proves nothing. This asks the store.
+    // ≠1 active credential means the resolver's answer for this subject is
+    // order-dependent, so this fails LOUDLY rather than returning a mapping the
+    // operator would reasonably believe is deterministic.
+    const afterCreds = (await findCredentialsForSubject()).filter(isResolvableCredential);
+    if (afterCreds.length !== 1 || afterCreds[0]?.id !== credentialId) {
+        const seen = afterCreds.map((c) => `${c?.id} → ${c?.principalId} (provider '${c?.idpProvider}')`).join("; ") || "none";
+        throw new Error(`Identity mapping: the uniqueness invariant does not hold after the write — subject '${params.idpSubject}' ` +
+            `has ${afterCreds.length} active Credential(kind:idp) row(s) [${seen}], expected exactly 1 (${credentialId}). ` +
+            `Runtime resolution for this subject would be iteration-order-dependent (flair#1317). ` +
+            `Inspect the Credential table for kind:"idp" idpSubject:"${params.idpSubject}" and revoke the rows that should not resolve.`);
+    }
+    return {
+        principalCreated,
+        credentialId,
+        credentialReused: Boolean(reused),
+        credentialSuperseded: superseded.length > 0,
+        supersededCredentialIds: superseded.map((c) => String(c.id)),
+    };
 }
 // ─── Restart only ────────────────────────────────────────────────────────────
 /** `restart` only — used by `disableMcp` (flag off + restart, no config
@@ -1069,10 +1166,21 @@ export async function enableMcp(params, deps = {}) {
         // and the one silent failure mode this surface has is discovering that
         // via an empty bootstrap. So the step that creates the mapping states it
         // plainly, names the link remedy, and points at the runtime diagnostic.
+        // flair#1317 — a cross-provider re-link REVOKES the subject's prior
+        // credential (one active credential per subject is the invariant). That is
+        // a credential dying, so it is stated as such, by id: an operator must
+        // never discover it later from something that stopped working.
+        const supersedeNote = mapping.credentialSuperseded
+            ? ` SUPERSEDED: ${mapping.supersededCredentialIds.length} prior Credential(kind:idp) row(s) for this subject ` +
+                `were REVOKED, not de-duplicated — ${mapping.supersededCredentialIds.join(", ")}. ` +
+                `They no longer resolve, and anything relying on them stops working. ` +
+                `Exactly one active credential per (kind, idpSubject) is the invariant that keeps resolution deterministic.`
+            : "";
         push(true, `connector identity: sub '${params.idpSubject}' (provider '${idpProvider}') resolves to Agent '${principal}' — ` +
             `every /mcp call reads and writes AS '${principal}'. ` +
             `principal ${mapping.principalCreated ? "created" : "already existed"}; ` +
-            `Credential(kind:idp) ${mapping.credentialReused ? "re-pointed" : "created"} (${mapping.credentialId}). ` +
+            `Credential(kind:idp) ${mapping.credentialReused ? "re-pointed" : "created"} (${mapping.credentialId}).` +
+            `${supersedeNote} ` +
             `If your CLI signs as a DIFFERENT agent id, the connector sees that agent's DISTINCT memory scope (by design) — ` +
             `re-run with --principal <your-agent-id> to link them. ` +
             `Diagnostic: the bootstrap tool's agentId/scope fields always say who the server resolved you to.`);

package/dist/resources/AgentSeed.js

@@ -19,6 +19,7 @@
 import { Resource, databases } from "harper";
 import { isAdmin, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
 import { reconcileAdminFields } from "./agent-admin.js";
+import { noteMemoryUpsert } from "./bm25-index-service.js";
 const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
     name: displayName,
     role,
@@ -124,6 +125,7 @@ export class AgentSeed extends Resource {
                     archived: false,
                 };
                 await databases.flair.Memory.put(record);
+                noteMemoryUpsert(record);
                 memories.push(record);
             }
         } // end !hasOnboardingMemory

package/dist/resources/Memory.js

@@ -13,6 +13,7 @@ import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeSco
 import { RECORD_TYPES } from "./record-types.js";
 import { attachTrust } from "./trust-block.js";
 import { recordCitations } from "./usage-recording.js";
+import { noteMemoryUpsert, noteMemoryDelete } from "./bm25-index-service.js";
 /**
  * flair#744 slice 1 — read the opt-in `includeTrust` flag for a by-id get.
  * Two entry shapes: an in-process caller (resources/mcp-tools.ts's memory_get)
@@ -306,7 +307,11 @@ async function closeSupersededRecord(ctx, oldId, patch) {
     if (!existing) {
         throw new Error(`supersede-close: record ${oldId} not found`);
     }
-    await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...existing, ...patch }));
+    const closed = { ...existing, ...patch };
+    await withDetachedTxn(ctx, () => databases.flair.Memory.put(closed));
+    // flair#1357 — a supersede-close sets `validTo`, which the retrieval filters
+    // read, so the lexical index has to see it as eagerly as a content write.
+    noteMemoryUpsert(closed);
 }
 /** Does an agent hold a "write" grant from `ownerId`? Same MemoryGrant lookup
  *  pattern as Memory.search()/SemanticSearch.ts (read/search scopes) — reused
@@ -766,6 +771,11 @@ export class Memory extends databases.flair.Memory {
         await stampOriginatorInstanceId(content);
         // ── Write the new record FIRST ──────────────────────────────────────────
         const result = await super.post(content);
+        // flair#1357 — read-your-write for the lexical leg. The table change feed
+        // (resources/bm25-index-service.ts) is the CORRECTNESS mechanism; this
+        // synchronous hook is what makes a store immediately searchable rather
+        // than searchable-after-the-feed-turns.
+        noteMemoryUpsert(content);
         // ── THEN close the superseded record ────────────────────────────────────
         // Write-new-BEFORE-close-old: the previous order (close-old via a fire-
         // and-forget `.catch(()=>{})` BEFORE the new write) could tombstone the
@@ -807,7 +817,9 @@ export class Memory extends databases.flair.Memory {
                 });
             }
             delete content._reindex;
-            return super.put(content);
+            const reindexed = await super.put(content);
+            noteMemoryUpsert(content);
+            return reindexed;
         }
         // Create/update ownership (same rule as post): a non-admin agent may only
         // write memories it owns, via resolveAgentAuth (gate annotation), not
@@ -1043,6 +1055,8 @@ export class Memory extends databases.flair.Memory {
         await stampOriginatorInstanceId(content);
         // ── Write the new/updated record FIRST ──────────────────────────────────
         const result = await super.put(content);
+        // flair#1357 — read-your-write for the lexical leg (see post()).
+        noteMemoryUpsert(content);
         // ── THEN close the superseded record (see post()) ───────────────────────
         await closeSupersededIfNeeded(ctx, content, "put");
         // flair#744 slice A: citation-on-write — POST-COMMIT, fully
@@ -1067,8 +1081,11 @@ export class Memory extends databases.flair.Memory {
         // before the read-gate fix — the read-scoping override must not leak
         // into delete()'s internal record lookup.
         const record = await super.get(id);
-        if (!record)
-            return super.delete(id);
+        if (!record) {
+            const gone = await super.delete(id);
+            noteMemoryDelete(id);
+            return gone;
+        }
         if (record.durability === "permanent") {
             // Middleware already guards this for non-admins, but belt-and-suspenders
             const ctx = this.getContext?.();
@@ -1081,6 +1098,8 @@ export class Memory extends databases.flair.Memory {
                 });
             }
         }
-        return super.delete(id);
+        const deleted = await super.delete(id);
+        noteMemoryDelete(id);
+        return deleted;
     }
 }

package/dist/resources/MemoryFeed.js

@@ -4,6 +4,7 @@ import { computeContentHash, findExistingMemoryByContentHash } from "./memory-fe
 import { FORBIDDEN, UNAUTH, stampAttribution } from "./record-type-kit.js";
 import { assertValidVisibility, assertVisibilityAllowedForDurability, PRIVATE_VISIBILITY } from "./memory-visibility.js";
 import { assertValidDurability } from "./memory-durability.js";
+import { noteMemoryUpsert } from "./bm25-index-service.js";
 export class FeedMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (the auth reshape removes the
     // gate's admin elevation).
@@ -125,6 +126,8 @@ export class FeedMemories extends Resource {
             record.visibility = PRIVATE_VISIBILITY;
         }
         await databases.flair.Memory.put(record);
+        // flair#1357 — raw-table write: hook it explicitly (see bm25-index-service).
+        noteMemoryUpsert(record);
         return record;
     }
     async *connect(target, incomingMessages) {

package/dist/resources/MemoryMaintenance.js

@@ -18,6 +18,7 @@
  */
 import { Resource, databases } from "harper";
 import { isAdmin } from "./agent-auth.js";
+import { noteMemoryUpsert, noteMemoryDelete } from "./bm25-index-service.js";
 export class MemoryMaintenance extends Resource {
     /** POST requires auth — either an agent acting on its own memories, or admin. */
     allowCreate() {
@@ -65,6 +66,9 @@ export class MemoryMaintenance extends Resource {
                     if (!dryRun) {
                         try {
                             await databases.flair.Memory.delete(record.id);
+                            // flair#1357 — ephemeral expiry removes the row from what the
+                            // lexical leg may score.
+                            noteMemoryDelete(record.id);
                             stats.expired++;
                         }
                         catch {
@@ -88,11 +92,16 @@ export class MemoryMaintenance extends Resource {
                     if (ageDays > 30) {
                         if (!dryRun) {
                             try {
-                                await databases.flair.Memory.update(record.id, {
+                                const archivedRow = {
                                     ...record,
                                     archived: true,
                                     archivedAt: now.toISOString(),
-                                });
+                                };
+                                await databases.flair.Memory.update(record.id, archivedRow);
+                                // flair#1357 — an `archived` flip changes what the retrieval
+                                // conditions (`archived not_equal true`) admit, so the lexical
+                                // index has to see it, not just content writes.
+                                noteMemoryUpsert(archivedRow);
                                 stats.archived++;
                             }
                             catch {

package/dist/resources/bm25-index-service.js

@@ -0,0 +1,257 @@
+// ─── Harper wiring for the persistent BM25 index (flair#1357) ───────────────
+//
+// ./bm25-index.ts is the Harper-free data structure. This module owns the one
+// process-wide instance of it and answers the only two questions the retrieval
+// core asks: "can you serve this lexical leg?" and "here is a write you should
+// know about".
+//
+// ── WHERE THE INDEX STATE LIVES, AND WHY ────────────────────────────────────
+// In process memory, per Harper worker, NOT in a Harper table.
+//
+// A Harper-table posting list was considered and rejected on WRITE cost: a
+// memory averages ~26 tokens (the measured live corpus,
+// test/bench/corpus-profiler/profiles), so persisting postings would turn one
+// `Memory.put()` into ~25 additional indexed row writes inside the same
+// transaction — write amplification on the ingestion path in order to speed up
+// the read path. It would also put a Harper round-trip per query TERM back
+// into recall. The in-process structure costs one full corpus scan per worker
+// lifetime, which is exactly ONE instance of what the defect used to charge on
+// EVERY query.
+//
+// Footprint at 250k documents: ~6.5M postings held as paired Int32Arrays
+// (~52MB), the term dictionary (~20MB), and per-document scope metadata with
+// NO content and NO embedding (~50MB) — order 120MB steady state. For scale:
+// the code this replaces allocated a 250k-entry array of per-document term
+// Maps plus the whole projected corpus INCLUDING content, transiently, on
+// every single query.
+//
+// ── COLD BOOT: LAZY ─────────────────────────────────────────────────────────
+// Built on the first hybrid query that carries query text, not at component
+// start. Eager building would add a full corpus scan to every boot including
+// the many processes that never search (CLI verbs, migration boots, health
+// checks), and it would race the embedding engine's own model load. The first
+// query after boot pays what every query used to pay; every one after it pays
+// nothing. Concurrent first queries share a single build promise.
+//
+// ── STAYING CURRENT ─────────────────────────────────────────────────────────
+// Two mechanisms, deliberately overlapping:
+//
+//   1. THE TABLE'S OWN CHANGE FEED (`Memory.subscribe`) is the authority. It
+//      is the same audit-log-backed primitive `FeedMemories.connect()` already
+//      uses, and it observes the TABLE — so it sees writes that never touch a
+//      flair resource at all: operations-API writes, `flair` CLI direct
+//      writes, and Harper replication applying federated rows. A scheme built
+//      only from hooks in flair's own write paths CANNOT see those, which is
+//      why the feed — not the hook list — is the correctness argument.
+//      Verified against a stock instance: an operations-API insert and an
+//      operations-API delete both arrive (put/delete with the full row).
+//
+//   2. SYNCHRONOUS HOOKS at flair's own write surface (`noteMemoryUpsert` /
+//      `noteMemoryDelete`) give READ-YOUR-WRITE. The feed is asynchronous, so
+//      without the hooks a store immediately followed by a search would be a
+//      race — and the path being replaced had no such race, because it refetched
+//      the corpus every query. Both mechanisms are idempotent upserts keyed by
+//      id, so seeing a write twice is a no-op.
+//
+// If the feed cannot be established, or delivers an event shape we do not
+// understand (Harper emits a bare `reload` marker when a base copy / resync is
+// applied — precisely when the index CANNOT be patched incrementally), the
+// index marks itself stale and the next query rebuilds it. If subscription
+// fails outright, the index DISABLES itself and every query falls back to the
+// legacy per-query corpus scan. A slow-but-correct recall is acceptable; a
+// silently stale one is not — recall is the product floor.
+//
+// ── MULTI-WORKER ────────────────────────────────────────────────────────────
+// The instance is per worker thread, so in a multi-worker configuration each
+// worker pays its own first-query build and holds its own copy of the index.
+// Both of flair's shipped launch paths pin `THREADS_COUNT=1` (src/cli.ts's
+// launchd plist and its direct-spawn env), as does the integration harness, so
+// the shipped configuration has exactly one worker and "per worker" is "per
+// process". Cross-worker write visibility rides on mechanism (1): the feed is
+// audit-log-backed and the audit store is shared, so a write committed by
+// another worker still arrives. Mechanism (2) is local to the writing worker,
+// which is why it is an immediacy optimisation and never the correctness
+// argument.
+import { databases } from "harper";
+import { withDetachedTxn } from "./table-helpers.js";
+import { Bm25Index, INDEX_SELECT } from "./bm25-index.js";
+/** Kill switch. Default ON; set FLAIR_BM25_INDEX=false/0/off to force every
+ *  query back onto the legacy per-query corpus scan + buildBM25(). Read
+ *  per-call so it can be flipped without a rebuild and set per-case in tests. */
+export function bm25IndexEnabled() {
+    const v = (process.env.FLAIR_BM25_INDEX ?? "true").toLowerCase();
+    return v === "true" || v === "1" || v === "on";
+}
+const index = new Bm25Index();
+let state = "empty";
+let buildPromise = null;
+let pending = null;
+let feedStarted = false;
+let disabledReason = "";
+/** Test seam — resets everything this module owns. */
+export function __resetBm25IndexForTests() {
+    index.clear();
+    state = "empty";
+    buildPromise = null;
+    pending = null;
+    feedStarted = false;
+    disabledReason = "";
+}
+/** Diagnostics, for tests and `flair doctor`-shaped callers. */
+export function bm25IndexStatus() {
+    return { state, size: index.size, postings: index.postingCount, terms: index.termCount, reason: disabledReason };
+}
+function project(record) {
+    if (!record || typeof record.id !== "string")
+        return null;
+    const out = { id: record.id };
+    for (const k of INDEX_SELECT)
+        if (k !== "id" && k in record)
+            out[k] = record[k];
+    return out;
+}
+function apply(ev) {
+    if (ev.kind === "delete")
+        index.remove(ev.id);
+    else
+        index.upsert(ev.record);
+}
+function record(ev) {
+    if (state === "disabled" || state === "empty")
+        return; // a later build will scan it
+    if (state === "building") {
+        pending.push(ev);
+        return;
+    }
+    apply(ev);
+}
+/** Read-your-write hook: call immediately after a committed Memory write that
+ *  changed content or any scope/temporal attribute. Safe to call for writes
+ *  that changed neither (it is an idempotent re-index of one row). */
+export function noteMemoryUpsert(row) {
+    const r = project(row);
+    if (r)
+        record({ kind: "upsert", record: r });
+}
+/** Read-your-write hook: call immediately after a committed Memory delete. */
+export function noteMemoryDelete(id) {
+    if (typeof id === "string" && id.length > 0)
+        record({ kind: "delete", id });
+}
+/** Force the next query to rebuild — used when the feed reports a change we
+ *  cannot express incrementally (a resync/base-copy `reload` marker). */
+export function markBm25IndexStale(reason) {
+    if (state === "disabled")
+        return;
+    disabledReason = reason;
+    state = "empty";
+    buildPromise = null;
+}
+function disable(reason) {
+    state = "disabled";
+    disabledReason = reason;
+    buildPromise = null;
+    pending = null;
+    index.clear();
+}
+async function startFeed(ctx) {
+    if (feedStarted)
+        return;
+    feedStarted = true;
+    const subscription = await withDetachedTxn(ctx, () => databases.flair.Memory.subscribe({ omitCurrent: true }));
+    // Deliberately not awaited: the consumer runs for the life of the process.
+    (async () => {
+        try {
+            for await (const ev of subscription) {
+                const type = ev?.type;
+                if (type === "delete") {
+                    record({ kind: "delete", id: String(ev.id) });
+                }
+                else if (type === "put" || type === "insert" || type === "update" || type === "upsert") {
+                    const r = project(ev?.value);
+                    if (r)
+                        record({ kind: "upsert", record: r });
+                    else
+                        markBm25IndexStale(`feed ${type} event carried no usable record`);
+                }
+                else if (type !== undefined) {
+                    // Includes Harper's `reload` base-copy/resync marker: the table's
+                    // contents may have been replaced wholesale with no per-row events.
+                    markBm25IndexStale(`unhandled feed event type ${String(type)}`);
+                }
+            }
+            disable("change feed ended");
+        }
+        catch (err) {
+            disable("change feed error: " + String(err?.message ?? err));
+        }
+    })();
+}
+/**
+ * Build (or rebuild) the index from one full corpus scan.
+ *
+ * ORDER IS LOAD-BEARING: the change feed is started BEFORE the scan, and the
+ * events it delivers during the scan are buffered and replayed AFTER it. A
+ * delete that lands mid-scan for a row the cursor has not reached yet would
+ * otherwise be applied first and then undone by the cursor re-adding the row.
+ * Replaying after the scan lets the newer event win, whichever order they
+ * physically occurred in.
+ */
+async function build(ctx) {
+    state = "building";
+    pending = [];
+    index.clear();
+    try {
+        await startFeed(ctx);
+        const results = withDetachedTxn(ctx, () => databases.flair.Memory.search({ select: INDEX_SELECT }));
+        for await (const row of results) {
+            const r = project(row);
+            if (r)
+                index.upsert(r);
+        }
+    }
+    catch (err) {
+        disable("build failed: " + String(err?.message ?? err));
+        return false;
+    }
+    const buffered = pending ?? [];
+    pending = null;
+    // `state` may have been knocked back to "empty" by a stale marker that
+    // arrived during the scan; in that case do not claim readiness.
+    if (state !== "building")
+        return false;
+    state = "ready";
+    for (const ev of buffered)
+        apply(ev);
+    return true;
+}
+async function ensureReady(ctx) {
+    if (!bm25IndexEnabled())
+        return false;
+    if (state === "disabled")
+        return false;
+    if (state === "ready")
+        return true;
+    if (!buildPromise)
+        buildPromise = build(ctx).finally(() => { buildPromise = null; });
+    return buildPromise;
+}
+/**
+ * The lexical leg, served from the index. Returns the BM25 candidate ids
+ * (score>0, best-first, sliced to `limit`) — or NULL when the index declines,
+ * in which case the caller MUST run the legacy corpus scan + buildBM25(). Null
+ * is returned for: the kill switch, a failed/disabled index, and any query
+ * whose conditions the index cannot reproduce exactly (see
+ * ./bm25-index.ts's `planQuery`).
+ */
+export async function indexedBm25Ids(params) {
+    if (!(await ensureReady(params.ctx)))
+        return null;
+    try {
+        return index.rank(params);
+    }
+    catch (err) {
+        disable("rank failed: " + String(err?.message ?? err));
+        return null;
+    }
+}