@tpsdev-ai/flair 0.17.0 → 0.18.0

package/dist/resources/Memory.js

@@ -4,6 +4,232 @@ import { isAdmin, resolveAgentAuth } from "./agent-auth.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, isConservativeMatch, } from "./dedup.js";
+const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+/**
+ * ─── Server-side conservative-duplicate gate (memory-integrity fix) ──────────
+ *
+ * NEVER SUPPRESSES A WRITE. This gate only computes a SIGNAL — the caller
+ * (Memory.post / Memory.put) always proceeds to write the new record. When a
+ * conservative match is found, the signal is attached to the RESPONSE only
+ * (deduplicated/matchedId/matchConfidence). There must be no code path where
+ * finding a match causes the write to be skipped: that was the #526 bug (two
+ * topically-close but DISTINCT findings — one about replication
+ * route-directionality, one about DDL/schema replication — and the SECOND was
+ * silently dropped because the old client-side gate returned the existing
+ * record instead of writing).
+ *
+ * Conservative match = raw cosine >= cosineThreshold AND Jaccard token-overlap
+ * >= lexicalThreshold, checked ONLY against the SINGLE top-cosine candidate
+ * (scoped to the same agentId as the write — never cross-agent). If that one
+ * candidate fails either gate, there is no match; we do not fall back to the
+ * 2nd-most-similar candidate.
+ *
+ * Previously this lived client-side (packages/flair-client/src/client.ts,
+ * pre-fix) and only ran for callers that opted into `dedup:true` over HTTP
+ * PUT — the Model-2 /mcp handler (resources/mcp-tools.ts), which calls
+ * Memory.post() directly, got ZERO dedup checking. Moving the gate here makes
+ * it apply uniformly regardless of transport (HTTP PUT vs in-process post()).
+ *
+ * NOTE on HTTP verbs: the Memory schema only exposes PUT over HTTP (a raw
+ * HTTP POST /Memory returns "Memory does not have a post method implemented"
+ * — see src/cli.ts's `flair test` command and commit 2fa6d22 / ops-pj5).
+ * `Memory.post()` IS reachable, but only via an in-process resource
+ * instantiation (as resources/mcp-tools.ts does) — never via the real HTTP
+ * POST route. Because flair-client's write() (used by flair-mcp, the CLI, and
+ * every other integration package) issues an HTTP PUT, the actual
+ * field-observed bug (#526) flows through Memory.put(), not Memory.post().
+ * The gate below is therefore a SHARED helper invoked from both post() and
+ * put() — anchored in the same place the design calls out (Memory.post), but
+ * wired into put() too so the write path real callers actually use is
+ * protected. See memory-integrity-fix report for the full writeup of this
+ * deviation from a literal "gate lives only in Memory.post" reading.
+ */
+async function findConservativeDedupMatch(ctx, agentId, contentText, embedding, cosineThreshold, lexicalThreshold) {
+    if (!agentId || !embedding || embedding.length === 0)
+        return null;
+    try {
+        const query = {
+            sort: { attribute: "embedding", target: embedding, distance: "cosine" },
+            conditions: [
+                { attribute: "agentId", comparator: "equals", value: agentId },
+                { attribute: "archived", comparator: "not_equal", value: true },
+            ],
+            select: ["id", "content", "$distance"],
+            limit: 1,
+        };
+        let top = null;
+        // Detach ctx.transaction around this search — same rationale as
+        // Memory.search()/SemanticSearch.ts: a drained search generator can leave
+        // a CLOSED transaction in ctx's chain that the subsequent WRITE
+        // (super.post/super.put, right after this gate runs) would otherwise
+        // inherit. Detaching here protects that write, not this read.
+        const results = withDetachedTxn(ctx, () => databases.flair.Memory.search(query));
+        for await (const record of results) {
+            top = record;
+            break; // single top-cosine candidate only — never fall back further
+        }
+        if (!top)
+            return null;
+        const cosine = 1 - (top.$distance ?? 1);
+        const confidence = computeMatchConfidence(contentText, top.content, cosine);
+        if (!isConservativeMatch(confidence.cosine, confidence.lexical, cosineThreshold, lexicalThreshold)) {
+            return null;
+        }
+        return { matchedId: top.id, cosine: confidence.cosine, lexical: confidence.lexical };
+    }
+    catch {
+        // Dedup-check failures (embedding engine down, search error, etc.) must
+        // NEVER block or alter the write — treat as "no match found".
+        return null;
+    }
+}
+/**
+ * Run the dedup gate for a create-shaped write. Mutates `content.embedding` /
+ * `content.embeddingModel` when it computes a fresh embedding, so the
+ * existing "generate embedding if missing" step later in post()/put() reuses
+ * it instead of recomputing. Always strips the client-forwarded hint fields
+ * (dedup / dedupThreshold / lexicalThreshold) so they never persist onto the
+ * stored record — they are passthrough tuning hints, not schema fields.
+ *
+ * Returns the match signal, or null (no match / gate not applicable).
+ */
+async function runDedupGate(ctx, content) {
+    const cosineThreshold = typeof content.dedupThreshold === "number" ? content.dedupThreshold : DEDUP_COSINE_THRESHOLD_DEFAULT;
+    const lexicalThreshold = typeof content.lexicalThreshold === "number" ? content.lexicalThreshold : DEDUP_LEXICAL_THRESHOLD_DEFAULT;
+    delete content.dedup;
+    delete content.dedupThreshold;
+    delete content.lexicalThreshold;
+    if (typeof content.content !== "string" || content.content.length < DEDUP_MIN_CONTENT_LENGTH) {
+        return null;
+    }
+    let embedding = Array.isArray(content.embedding) ? content.embedding : null;
+    if (!embedding) {
+        try {
+            embedding = await getEmbedding(content.content);
+        }
+        catch {
+            embedding = null;
+        }
+        if (embedding) {
+            content.embedding = embedding;
+            content.embeddingModel = getModelId();
+        }
+    }
+    if (!embedding)
+        return null;
+    return findConservativeDedupMatch(ctx, content.agentId, content.content, embedding, cosineThreshold, lexicalThreshold);
+}
+/** Build the final write response: always `written: true`, always includes
+ *  `id`, and layers the dedup collision signal on top when present. Never a
+ *  code path where a match suppresses these base fields. */
+function buildWriteResponse(content, result, dedupMatch) {
+    const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
+    const response = {
+        id: content.id,
+        ...base,
+        written: true,
+        deduplicated: !!dedupMatch,
+    };
+    if (dedupMatch) {
+        response.matchedId = dedupMatch.matchedId;
+        response.matchConfidence = { cosine: dedupMatch.cosine, lexical: dedupMatch.lexical };
+    }
+    return response;
+}
+/**
+ * Read-modify-write close of a superseded record, with the SAME transaction
+ * detachment discipline as findConservativeDedupMatch (each discrete Harper
+ * call individually wrapped — see withDetachedTxn's doc for why a single
+ * wrap around a multi-await async function would not protect the later
+ * call). Does NOT swallow failures (ops-a4t5 fix) — throws so the caller can
+ * log it. Never called before the new record is already written.
+ */
+async function closeSupersededRecord(ctx, oldId, patch) {
+    const existing = await withDetachedTxn(ctx, () => databases.flair.Memory.get(oldId));
+    if (!existing) {
+        throw new Error(`supersede-close: record ${oldId} not found`);
+    }
+    await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...existing, ...patch }));
+}
+/** Does an agent hold a "write" grant from `ownerId`? Same MemoryGrant lookup
+ *  pattern as Memory.search()/SemanticSearch.ts (read/search scopes) — reused
+ *  here for the "write" scope that gates cross-agent supersede. */
+async function hasWriteGrant(granteeId, ownerId) {
+    try {
+        for await (const grant of databases.flair.MemoryGrant.search({
+            conditions: [
+                { attribute: "granteeId", comparator: "equals", value: granteeId },
+                { attribute: "ownerId", comparator: "equals", value: ownerId },
+            ],
+        })) {
+            if (grant.scope === "write")
+                return true;
+        }
+    }
+    catch {
+        /* MemoryGrant table not yet populated — no grant */
+    }
+    return false;
+}
+/**
+ * Shared by post() AND put(): the Memory schema only exposes a working HTTP
+ * PUT route (a raw HTTP POST /Memory 404s with "Memory does not have a post
+ * method implemented" — see src/cli.ts's `flair test` command / commit
+ * 2fa6d22 / ops-pj5). Memory.post() IS reachable, but only via an in-process
+ * resource instantiation (resources/mcp-tools.ts does this). Since
+ * flair-client's write()/update() — used by flair-mcp, the CLI, and every
+ * other integration package — issue HTTP PUT, `supersedes` must be fully
+ * handled (validated, authorized, and closed) from BOTH entry points for the
+ * real-world write path to actually get the fix, not just the in-process one.
+ *
+ * Validates the `supersedes` field's shape and, for a cross-agent supersede,
+ * requires a "write" MemoryGrant from the target's owner (reuses the existing
+ * agent-auth/grant machinery — no parallel auth logic). Returns a Response to
+ * short-circuit with (400/403), or null to continue.
+ */
+async function validateAndAuthorizeSupersedes(content, auth) {
+    if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
+        return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
+            status: 400, headers: { "Content-Type": "application/json" },
+        });
+    }
+    if (content.supersedes && auth.kind === "agent" && !auth.isAdmin) {
+        const target = await databases.flair.Memory.get(content.supersedes).catch(() => null);
+        if (target && target.agentId !== auth.agentId) {
+            if (!(await hasWriteGrant(auth.agentId, target.agentId))) {
+                return FORBIDDEN("forbidden: cannot supersede a memory owned by another agent without a write grant");
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Close the superseded record — called AFTER the new record has already been
+ * written (write-new-BEFORE-close-old, ops-a4t5 fix). Safe failure state is
+ * two active records (recoverable), never a tombstoned-old-with-lost-new.
+ * Failure is logged (observable), never silently swallowed. No-op if
+ * `content.supersedes` is not set.
+ */
+async function closeSupersededIfNeeded(ctx, content, methodLabel) {
+    if (!content.supersedes)
+        return;
+    try {
+        await closeSupersededRecord(ctx, content.supersedes, {
+            validTo: content.validFrom ?? content.createdAt,
+            updatedAt: content.createdAt ?? content.updatedAt,
+        });
+    }
+    catch (err) {
+        // Constant format string + structured data: memory ids are agent-controlled,
+        // so interpolating them into console.error's format position (with a trailing
+        // `err` arg) would let an id containing %s/%o consume/hide the real error
+        // (semgrep unsafe-formatstring). Keep all dynamic values in the data object.
+        console.error("Memory.closeSuperseded: failed to close superseded record after writing new record " +
+            "(ops-a4t5 — observable, not silent; new record is safely written, old record remains active until retried)", { method: methodLabel, supersededId: content.supersedes, newRecordId: content.id, err });
+    }
+}
 export class Memory extends databases.flair.Memory {
     /**
      * Override search() to scope collection GETs by authenticated agent.
@@ -78,20 +304,17 @@ export class Memory extends databases.flair.Memory {
         // resolveAgentAuth (reads the gate's tpsAgent annotation) — NOT context.user
         // .username, which is the fallback "admin" super_user while de-elevation is
         // dormant and would wrongly 403 every agent's own write. internal/admin → pass.
+        let auth;
         {
-            const auth = await resolveAgentAuth(ctx);
+            auth = await resolveAgentAuth(ctx);
             // Anonymous HTTP must NOT write. Pre-flip the global gate rejected no-auth
             // upstream; with the non-rejecting gate, each write path self-enforces (same
             // rule search() applies to reads).
             if (auth.kind === "anonymous") {
-                return new Response(JSON.stringify({ error: "authentication required" }), {
-                    status: 401, headers: { "Content-Type": "application/json" },
-                });
+                return UNAUTH();
             }
             if (auth.kind === "agent" && !auth.isAdmin && content?.agentId && content.agentId !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "forbidden: cannot write memory owned by another agent" }), {
-                    status: 403, headers: { "Content-Type": "application/json" },
-                });
+                return FORBIDDEN("forbidden: cannot write memory owned by another agent");
             }
         }
         content.durability ||= "standard";
@@ -111,23 +334,16 @@ export class Memory extends databases.flair.Memory {
                 catch { }
             }
         }
-        // supersedes: optional reference to the ID of the memory this one replaces
-        if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
-            return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
-                status: 400, headers: { "Content-Type": "application/json" },
-            });
-        }
+        // supersedes: optional reference to the ID of the memory this one
+        // replaces. Validates shape + cross-agent-write authorization (shared
+        // with put() — see validateAndAuthorizeSupersedes doc).
+        const supersedesError = await validateAndAuthorizeSupersedes(content, auth);
+        if (supersedesError)
+            return supersedesError;
         // Temporal validity: validFrom defaults to now, validTo left null for active facts.
-        // When a memory supersedes another, close the superseded memory's validity window.
         if (!content.validFrom) {
             content.validFrom = content.createdAt;
         }
-        if (content.supersedes) {
-            patchRecord(databases.flair.Memory, content.supersedes, {
-                validTo: content.validFrom,
-                updatedAt: content.createdAt,
-            }).catch(() => { });
-        }
         if (content.durability === "ephemeral" && !content.expiresAt) {
             const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
             content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();
@@ -147,7 +363,22 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = safety.flags;
             }
         }
-        // Generate embedding from content text
+        // Server-side conservative-duplicate gate (memory-integrity fix). A
+        // supersede write is an intentional version-link, not an ambiguous "is
+        // this a duplicate of something else" situation — bypass the gate for it
+        // (this also gives memory_update's preserveHistory mode dedup-bypass for
+        // free, without a separate flag). NEVER suppresses the write either way.
+        let dedupMatch = null;
+        if (!content.supersedes) {
+            dedupMatch = await runDedupGate(ctx, content);
+        }
+        else {
+            delete content.dedup;
+            delete content.dedupThreshold;
+            delete content.lexicalThreshold;
+        }
+        // Generate embedding from content text (no-op if the dedup gate above
+        // already computed one for this content).
         if (content.content && !content.embedding) {
             const vec = await getEmbedding(content.content);
             if (vec) {
@@ -155,7 +386,16 @@ export class Memory extends databases.flair.Memory {
                 content.embeddingModel = getModelId();
             }
         }
-        return super.post(content);
+        // ── Write the new record FIRST ──────────────────────────────────────────
+        const result = await super.post(content);
+        // ── THEN close the superseded record (ops-a4t5 fix) ─────────────────────
+        // Write-new-BEFORE-close-old: the previous order (close-old via a fire-
+        // and-forget `.catch(()=>{})` BEFORE the new write) could tombstone the
+        // old record and then lose the new one if the write failed afterward.
+        // Now the safe failure state is two active records (recoverable), never
+        // a lost write — and the failure is logged, never silently swallowed.
+        await closeSupersededIfNeeded(ctx, content, "post");
+        return buildWriteResponse(content, result, dedupMatch);
     }
     async put(content) {
         // Reindex migration bypass: admin-only escape hatch used by the
@@ -181,19 +421,16 @@ export class Memory extends databases.flair.Memory {
         // write memories it owns, via resolveAgentAuth (gate annotation), not
         // context.user.username (the dormant-de-elevation fallback is "admin").
         // The _reindex admin path above bypasses this.
+        const ctx = this.getContext?.();
+        let auth;
         {
-            const octx = this.getContext?.();
-            const auth = await resolveAgentAuth(octx);
+            auth = await resolveAgentAuth(ctx);
             // Anonymous HTTP must NOT write (non-rejecting gate → self-enforce here).
             if (auth.kind === "anonymous") {
-                return new Response(JSON.stringify({ error: "authentication required" }), {
-                    status: 401, headers: { "Content-Type": "application/json" },
-                });
+                return UNAUTH();
             }
             if (auth.kind === "agent" && !auth.isAdmin && content?.agentId && content.agentId !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "forbidden: cannot write memory owned by another agent" }), {
-                    status: 403, headers: { "Content-Type": "application/json" },
-                });
+                return FORBIDDEN("forbidden: cannot write memory owned by another agent");
             }
         }
         const now = new Date().toISOString();
@@ -201,6 +438,16 @@ export class Memory extends databases.flair.Memory {
         // Set defaults that post() sets — put() is also used for new records via CLI
         content.archived = content.archived ?? false;
         content.createdAt = content.createdAt ?? now;
+        // supersedes: optional reference to the ID of the memory this one
+        // replaces. Validates shape + cross-agent-write authorization (shared
+        // with post() — see validateAndAuthorizeSupersedes doc for why PUT needs
+        // this too: it's the only HTTP-reachable create path).
+        const supersedesError = await validateAndAuthorizeSupersedes(content, auth);
+        if (supersedesError)
+            return supersedesError;
+        if (content.supersedes && !content.validFrom) {
+            content.validFrom = content.createdAt;
+        }
         // Content safety scan on updated content + summary (ops-i2jb).
         if (content.content || content.summary) {
             const safety = scanFields(content, ["content", "summary"]);
@@ -219,7 +466,36 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = null;
             }
         }
-        // Re-generate embedding if content changed
+        // Server-side conservative-duplicate gate (memory-integrity fix). PUT is
+        // an upsert: only run the gate for a FRESH create (target id does not yet
+        // exist) that is NOT a supersede-link write. An update of an EXISTING id
+        // (memory_update's default same-id overwrite path) is an intentional,
+        // explicit overwrite, and a supersede-link write is an intentional
+        // version-link — neither is an ambiguous "is this a duplicate of
+        // something else" write, so both are dedup-bypassed automatically, no
+        // separate flag needed. NEVER suppresses the write either way.
+        let dedupMatch = null;
+        if (content.supersedes) {
+            delete content.dedup;
+            delete content.dedupThreshold;
+            delete content.lexicalThreshold;
+        }
+        else if (content.id) {
+            const preExisting = await databases.flair.Memory.get(content.id).catch(() => null);
+            if (!preExisting) {
+                dedupMatch = await runDedupGate(ctx, content);
+            }
+            else {
+                delete content.dedup;
+                delete content.dedupThreshold;
+                delete content.lexicalThreshold;
+            }
+        }
+        else {
+            dedupMatch = await runDedupGate(ctx, content);
+        }
+        // Re-generate embedding if content changed (no-op if the dedup gate above
+        // already computed one for this content).
         if (content.content && !content.embedding) {
             const vec = await getEmbedding(content.content);
             if (vec) {
@@ -240,7 +516,11 @@ export class Memory extends databases.flair.Memory {
         if (content.promotionStatus === "approved") {
             content.durability = "permanent";
         }
-        return super.put(content);
+        // ── Write the new/updated record FIRST ──────────────────────────────────
+        const result = await super.put(content);
+        // ── THEN close the superseded record (ops-a4t5 fix; see post()) ────────
+        await closeSupersededIfNeeded(ctx, content, "put");
+        return buildWriteResponse(content, result, dedupMatch);
     }
     async delete(id) {
         const record = await this.get(id);

package/dist/resources/SemanticSearch.js

@@ -4,6 +4,7 @@ import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { wrapUntrusted } from "./content-safety.js";
+import { isRerankEnabled, getRerankTopN, getRerankBudgetMs, getRerankMinCandidates, rerankCandidates, } from "./rerank-provider.js";
 // Temporal decay + relevance scoring (incl. the OPS-AYGD retrievalBoost cap +
 // relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
 // unit-tested directly (see test/unit/temporal-scoring.test.ts).
@@ -170,6 +171,16 @@ export class SemanticSearch extends Resource {
         }
         const results = [];
         const hybrid = hybridEnabled();
+        // When the reranker is on, widen the legacy HNSW fetch so it has a deeper
+        // pool to re-score (retrieve topN → rerank → slice to limit). Decoupled
+        // from CANDIDATE_MULTIPLIER so composite re-ranking keeps its existing
+        // headroom. Scoped to the legacy (non-hybrid) vector path below — the
+        // hybrid path's candidate pool is already governed by CANDIDATE_MULTIPLIER
+        // (semantic leg) + SEM_LIMIT (BM25 leg) via RRF union (ops-i39b); the
+        // reranker still applies to its output further down regardless of which
+        // path produced `filteredResults`.
+        const rerankOn = isRerankEnabled();
+        const rerankTopN = getRerankTopN();
         if (hybrid) {
             // ─── BM25 + union-RRF hybrid path (ops-i39b) ─────────────────────────
             // 1. Semantic candidates via HNSW (unchanged fetch). 2. BM25 lexical pass
@@ -284,8 +295,10 @@ export class SemanticSearch extends Resource {
             }
         }
         else if (qEmb) {
-            // ─── HNSW vector search path ───────────────────────────────────────────
-            const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+            // ─── HNSW vector search path (legacy, hybrid flag OFF) ────────────────
+            const candidateLimit = rerankOn
+                ? Math.max(limit * CANDIDATE_MULTIPLIER, rerankTopN)
+                : limit * CANDIDATE_MULTIPLIER;
             const query = {
                 sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
                 select: ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
@@ -387,7 +400,32 @@ export class SemanticSearch extends Resource {
         if (minScore > 0) {
             filteredResults = filteredResults.filter((r) => r._score >= minScore);
         }
-        filteredResults.sort((a, b) => b._score - a._score);
+        // ─── Cross-encoder rerank (best-effort, fail-open to vector order) ───────
+        // Re-scores query+candidate TOGETHER (cross-attention the pooled embedding
+        // can't do) and reorders before the final slice. Reorders whatever
+        // `filteredResults` the retrieval stage above produced — legacy HNSW-only
+        // OR the BM25+union-RRF hybrid path (ops-i39b) — since both converge into
+        // the same `results`/`filteredResults` shape before this point; hybrid
+        // retrieves+fuses, the reranker only reorders the fused set. Still gated
+        // on `qEmb` (an embedding was actually generated); the pure keyword-only
+        // fallback (no qEmb at all) is untouched either way. The reranker
+        // overwrites `_score` with the rerank score (so margin measurement reads it)
+        // and preserves the semantic score as `_semScore`; `_rawScore` is left as-is
+        // so recall-bench's scoring:"raw" path stays reproducible. On init failure,
+        // timeout, or any throw, rerankCandidates returns the input UNCHANGED and we
+        // fall through to the existing vector-order sort — recall is never blocked.
+        if (rerankOn && qEmb && q && filteredResults.length >= getRerankMinCandidates()) {
+            // Pre-sort by vector order so the topN fed to the reranker is the most
+            // semantically-promising slice (filteredResults isn't sorted yet here).
+            filteredResults.sort((a, b) => b._score - a._score);
+            filteredResults = await rerankCandidates(String(q), filteredResults, {
+                topN: rerankTopN,
+                budgetMs: getRerankBudgetMs(),
+            });
+        }
+        else {
+            filteredResults.sort((a, b) => b._score - a._score);
+        }
         const topResults = filteredResults.slice(0, limit);
         // Async hit tracking — don't block the response
         const now = new Date().toISOString();

package/dist/resources/dedup.js

@@ -0,0 +1,62 @@
+// ─── Conservative near-duplicate detection primitives (Harper-free) ─────────
+// Memory-integrity fix (#526/#548 field regressions). This module is
+// deliberately Harper-free — same rationale as ./bm25.ts and ./scoring.ts —
+// so the cosine+Jaccard co-gate math is unit-testable directly against the
+// SHIPPED code without a live Harper. The DB-touching top-1-cosine lookup
+// (needs `databases`) lives in ./Memory.ts, built on top of these primitives.
+//
+// ── THE INVARIANT ────────────────────────────────────────────────────────────
+// This module NEVER decides whether to write. It only scores a candidate
+// match. Callers (Memory.post / Memory.put) always write the new record; a
+// "conservative match" is surfaced to the caller as a SIGNAL on the response
+// (deduplicated/matchedId/matchConfidence), never as a reason to skip the
+// write. That was the #526 bug: two topically-close but DISTINCT findings —
+// one about replication route-directionality, one about DDL/schema
+// replication — and the second was silently dropped because raw cosine alone
+// flagged it as a "duplicate" of the first. Requiring BOTH cosine AND lexical
+// (Jaccard token-overlap) to clear their thresholds against the SAME single
+// top-cosine candidate catches true near-dups while sparing topic collisions
+// (high cosine, low lexical) — and even then, only ever as a non-suppressing
+// signal.
+import { tokenize } from "./bm25.js";
+/** Default raw-cosine similarity threshold for a candidate to even be considered. */
+export const DEDUP_COSINE_THRESHOLD_DEFAULT = 0.95;
+/** Default Jaccard token-overlap threshold (of the top cosine candidate). */
+export const DEDUP_LEXICAL_THRESHOLD_DEFAULT = 0.5;
+/** Below this content length, similarity scoring is unreliable ("ok" would
+ *  match "ok" trivially) — the dedup gate is bypassed entirely. */
+export const DEDUP_MIN_CONTENT_LENGTH = 20;
+/** Jaccard similarity of two token sets: |A∩B| / |A∪B|. An empty side yields 0
+ *  (no signal — never treated as "fully similar" by vacuous set equality). */
+export function jaccardSimilarity(tokensA, tokensB) {
+    const a = new Set(tokensA);
+    const b = new Set(tokensB);
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Conservative match = cosine AND lexical BOTH clear their thresholds.
+ * Both gates are required — a topic collision (high cosine, low lexical: two
+ * DIFFERENT findings that merely share a topic/vocabulary) must NOT be
+ * flagged as a duplicate. Only a true near-duplicate (high cosine AND high
+ * lexical overlap) is flagged.
+ */
+export function isConservativeMatch(cosine, lexical, cosineThreshold = DEDUP_COSINE_THRESHOLD_DEFAULT, lexicalThreshold = DEDUP_LEXICAL_THRESHOLD_DEFAULT) {
+    return cosine >= cosineThreshold && lexical >= lexicalThreshold;
+}
+/** Compute the {cosine, lexical} confidence pair for a candidate against the
+ *  new content's text, using the shared bm25 tokenizer. Rounded to 3dp to
+ *  match the existing _score rounding convention (SemanticSearch.ts). */
+export function computeMatchConfidence(newContent, candidateContent, cosine) {
+    const lexical = jaccardSimilarity(tokenize(newContent), tokenize(candidateContent || ""));
+    return {
+        cosine: Math.round(cosine * 1000) / 1000,
+        lexical: Math.round(lexical * 1000) / 1000,
+    };
+}

package/dist/resources/health.js

@@ -2,6 +2,7 @@ import { Resource, databases } from "@harperfast/harper";
 import { promises as fsp } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
+import { getRerankStatus } from "./rerank-provider.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -515,6 +516,22 @@ export class HealthDetail extends Resource {
         catch {
             stats.bridges = null;
         }
+        // ── Reranker ──
+        // Cross-encoder rerank stage. Reports flag/model/mode + live counters so we
+        // can see if it's silently degrading (fallbackCount climbing) in prod.
+        try {
+            const rr = getRerankStatus();
+            stats.rerank = rr;
+            if (rr.enabled && rr.state === "failed") {
+                warnings.push({ level: "warn", message: `reranker enabled but unavailable: ${rr.error ?? "init failed"} — recall falling back to vector order` });
+            }
+            if (rr.enabled && rr.rerankCount > 0 && rr.fallbackCount > rr.rerankCount) {
+                warnings.push({ level: "warn", message: `reranker falling back more than reranking (${rr.fallbackCount} fallbacks / ${rr.rerankCount} reranks) — check latency budget / topN` });
+            }
+        }
+        catch {
+            stats.rerank = null;
+        }
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──

package/dist/resources/mcp-tools.js

@@ -1,17 +1,17 @@
 /**
- * mcp-tools.ts — the 9 curated flair tools for the Model-2 custom /mcp handler.
+ * mcp-tools.ts — the 10 curated flair tools for the Model-2 custom /mcp handler.
  *
- * Curated BY CONSTRUCTION: this module implements exactly the 9 tools that the
+ * Curated BY CONSTRUCTION: this module implements exactly the 10 tools that the
  * `@tpsdev-ai/flair-mcp` stdio proxy exposes, each a thin wrapper over the
  * existing flair Resource handler. No business logic is re-implemented — the
  * wrapped handlers (Memory / SemanticSearch / BootstrapMemories / Soul /
  * WorkspaceState / OrgEvent) enforce per-agent scoping/ownership via
  * `resolveAgentAuth(getContext())`, so the MCP surface inherits the SAME security
  * model as the signed-REST path. There is no raw CRUD surface — the only way to
- * reach the datastore through /mcp is via one of these 9 semantic tools.
+ * reach the datastore through /mcp is via one of these 10 semantic tools.
  *
- *   memory_search · memory_store · memory_get · memory_delete · bootstrap ·
- *   soul_set · soul_get · flair_workspace_set · flair_orgevent
+ *   memory_search · memory_store · memory_update · memory_get · memory_delete ·
+ *   bootstrap · soul_set · soul_get · flair_workspace_set · flair_orgevent
  *
  * ── The scoping seam ────────────────────────────────────────────────────────
  * The /mcp handler resolves the OAuth token's `sub` → a flair `Agent` id, then
@@ -116,6 +116,58 @@ async function memoryStore(agent, args) {
         tags: args?.tags,
     }));
 }
+/**
+ * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
+ * integrity fix). Mirrors flair-client's MemoryApi.update() (packages/
+ * flair-client/src/client.ts), reimplemented against the resource instance
+ * API instead of HTTP since this handler calls the Memory resource directly
+ * (same pattern as memoryStore vs the flair-mcp stdio tool). Auth is enforced
+ * by Memory.get()/Memory.put()/Memory.post()'s EXISTING ownership checks — no
+ * parallel auth logic here.
+ *
+ * Default (preserveHistory unset/false): read the existing record, merge the
+ * new content on top (Harper PUT is full-record replacement — never send a
+ * bare partial), clear the stale embedding so the server regenerates it, and
+ * PUT the merged record back to the SAME id.
+ *
+ * preserveHistory: true: write a NEW id with `supersedes: id`. Memory.post()
+ * validates/authorizes the supersede (denying a cross-agent supersede without
+ * a "write" MemoryGrant) and closes the old record's validTo AFTER the new
+ * record is written (never the reverse — see resources/Memory.ts).
+ */
+async function memoryUpdate(agent, args) {
+    const Cls = await handler("Memory");
+    const h = new Cls(undefined, delegationContext(agent));
+    const id = args?.id;
+    const content = args?.content;
+    const preserveHistory = args?.preserveHistory === true;
+    const existing = await h.get(id);
+    if (!existing) {
+        return { error: "memory not found", status: 404 };
+    }
+    if (preserveHistory) {
+        const newId = `${agent.agentId}-${crypto.randomUUID()}`;
+        const record = {
+            ...existing,
+            id: newId,
+            content,
+            supersedes: id,
+            createdAt: new Date().toISOString(),
+        };
+        delete record.updatedAt;
+        delete record.embedding;
+        delete record.embeddingModel;
+        delete record.validFrom;
+        delete record.validTo;
+        delete record.archivedAt;
+        h.isCollection = true;
+        return unwrap(await h.post(record));
+    }
+    const merged = { ...existing, content, updatedAt: new Date().toISOString() };
+    delete merged.embedding;
+    delete merged.embeddingModel;
+    return unwrap(await h.put(merged));
+}
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
     const h = new Cls(undefined, delegationContext(agent));
@@ -231,6 +283,24 @@ export const TOOLS = {
         },
         impl: memoryStore,
     },
+    memory_update: {
+        def: {
+            name: "memory_update",
+            description: "Update an existing memory by ID. Dedup-bypassed (this is an intentional overwrite, not a new write). " +
+                "Default: overwrites the same id in place. Pass preserveHistory=true to instead write a new version " +
+                "linked via `supersedes`, closing the old one's validity window.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "ID of the memory to update" },
+                    content: { type: "string", description: "New content" },
+                    preserveHistory: { type: "boolean", description: "Write a new version (supersedes-linked) instead of overwriting in place (default false)" },
+                },
+                required: ["id", "content"],
+            },
+        },
+        impl: memoryUpdate,
+    },
     memory_get: {
         def: {
             name: "memory_get",

package/dist/resources/rerank-provider.js

@@ -0,0 +1,361 @@
+/**
+ * rerank-provider.ts
+ *
+ * In-process cross-encoder reranker for Flair's recall path. Mirrors the
+ * embeddings-provider.ts shape: dynamic import of node-llama-cpp (deferred to
+ * first use to dodge Harper 5.x's VM-sandbox linker race), lazy singleton init,
+ * and graceful passthrough on ANY failure — the reranker is best-effort and must
+ * NEVER block or break recall.
+ *
+ * Two inference modes (selected by FLAIR_RERANK_MODEL):
+ *
+ *  1. "qwen3-reranker-0.6b-q8" (DEFAULT, quality) — Qwen3-Reranker-0.6B is a
+ *     causal-LM reranker, NOT a rank-pooling cross-encoder. Its GGUF reports
+ *     supportsRanking=false, so node-llama-cpp's createRankingContext() rejects
+ *     it. The correct path is generative: format query+doc into the official
+ *     instruction prompt ending at the assistant turn, evaluate, and read the
+ *     next-token probability of "yes" vs "no":
+ *         score = P(yes) / (P(yes) + P(no))
+ *     Implemented via seq.controlledEvaluate with generateNext probabilities.
+ *     (Validated offline in RERANK-PILOT-RESULTS.md: 4/4 target cases flipped
+ *     positive, p@1 6/8→8/8, mean margin 0.028→0.688, ~1.2s / 16 docs on rockit.)
+ *
+ *  2. "jina-reranker-v2" (latency fallback) — jina-reranker-v2 IS a rank-pooling
+ *     cross-encoder; its gpustack GGUF loads via createRankingContext()/rankAll
+ *     (supportsRanking=true). ~145ms / 16 docs but weaker (7/8, leaves the
+ *     hardest consensus case negative). Selectable where latency is tight.
+ *
+ * Serving path = the same in-process node-llama-cpp the embedding engine ships.
+ * No Ollama (no logprobs, no rerank endpoint — verified), no network hop, no
+ * new auth boundary.
+ *
+ * GGUF files are NOT committed; they are provisioned into models/ alongside the
+ * embedding GGUF. See docs/rerank-provisioning.md for download sources.
+ */
+import { join } from "node:path";
+// Known reranker models → GGUF filename + inference mode. The default is the
+// quality model (Qwen3 generative). jina is the latency model (rank API).
+const MODELS = {
+    "qwen3-reranker-0.6b-q8": { file: "Qwen3-Reranker-0.6B-q8_0.gguf", mode: "generative" },
+    "jina-reranker-v2": { file: "jina-reranker-v2-base.Q8_0.gguf", mode: "rank" },
+};
+const DEFAULT_MODEL = "qwen3-reranker-0.6b-q8";
+// Official Qwen3-Reranker prompt scaffold (generative yes/no judgement).
+const QWEN_PREFIX = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>\n<|im_start|>user\n';
+const QWEN_SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n";
+const QWEN_INSTRUCT = "Given a web search query, retrieve relevant passages that answer the query";
+function buildQwenPrompt(q, doc) {
+    return `${QWEN_PREFIX}<Instruct>: ${QWEN_INSTRUCT}\n<Query>: ${q}\n<Document>: ${doc}${QWEN_SUFFIX}`;
+}
+// Cap per-document content fed to the reranker. Short atomic notes are the norm;
+// this bounds context blow-up + latency on the occasional huge memory.
+const MAX_DOC_CHARS = 2000;
+let _state = "uninitialized";
+let _initError;
+let _warnedOnce = false;
+let _modelKey = "";
+let _mode;
+// node-llama-cpp handles (kept alive as a singleton like the embedding engine).
+let _nlc = null;
+let _llama = null;
+let _model = null;
+// generative mode handles
+let _ctx = null;
+let _seq = null;
+let _yesToks = [];
+let _noToks = [];
+// rank mode handle
+let _rankCtx = null;
+// Diagnostics surfaced via getRerankStatus() / health.ts.
+let _lastLatencyMs = null;
+let _fallbackCount = 0;
+let _rerankCount = 0;
+function resolveModelKey() {
+    const requested = process.env.FLAIR_RERANK_MODEL?.trim();
+    if (requested && MODELS[requested])
+        return requested;
+    return DEFAULT_MODEL;
+}
+/** Discover the platform addon binary the same way embeddings-provider.ts does. */
+async function findAddonPath() {
+    const { existsSync } = await import("node:fs");
+    const platforms = ["linux-x64", "mac-arm64-metal", "mac-arm64", "win-x64", "linux-arm64", "mac-x64"];
+    for (const platform of platforms) {
+        const candidate = join(process.cwd(), "node_modules", "@node-llama-cpp", platform, "bins", platform, "llama-addon.node");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+async function ensureInit() {
+    if (_state === "ready")
+        return;
+    if (_state === "failed")
+        return; // already logged once — don't thrash
+    try {
+        _modelKey = resolveModelKey();
+        const spec = MODELS[_modelKey];
+        _mode = spec.mode;
+        const { existsSync } = await import("node:fs");
+        const modelPath = join(process.cwd(), "models", spec.file);
+        if (!existsSync(modelPath)) {
+            throw new Error(`reranker GGUF not found: models/${spec.file} (provision per docs/rerank-provisioning.md)`);
+        }
+        // Dynamic import — deferred to avoid Harper 5.x VM linker race (same reason
+        // embeddings-provider.ts defers harper-fabric-embeddings).
+        if (!_nlc)
+            _nlc = await import("node-llama-cpp");
+        // node-llama-cpp finds its prebuilt binary from process.cwd()/node_modules
+        // when run inside the Flair app dir (Harper's runtime cwd). We don't need to
+        // pass the addon path explicitly to getLlama() — but we surface it for
+        // diagnostics and as a guard that a binary exists at all.
+        const addonPath = await findAddonPath();
+        if (!addonPath) {
+            throw new Error("no @node-llama-cpp platform addon found under node_modules");
+        }
+        _llama = await _nlc.getLlama();
+        _model = await _llama.loadModel({ modelPath });
+        if (_mode === "generative") {
+            _ctx = await _model.createContext({ contextSize: 1024 });
+            _seq = _ctx.getSequence();
+            // Resolve yes/no token ids (both case variants — the post-</think>
+            // position puts mass on "yes"/"Yes").
+            _yesToks = [_model.tokenize("yes", false)[0], _model.tokenize("Yes", false)[0]].filter((t) => t != null);
+            _noToks = [_model.tokenize("no", false)[0], _model.tokenize("No", false)[0]].filter((t) => t != null);
+            if (_yesToks.length === 0 || _noToks.length === 0) {
+                throw new Error("failed to resolve yes/no token ids for generative reranker");
+            }
+        }
+        else {
+            // rank-pooling cross-encoder (jina). Reject if the GGUF isn't a ranking model.
+            if (!_model.fileInsights?.supportsRanking) {
+                throw new Error(`model ${spec.file} does not support ranking (not a rank-pooling cross-encoder)`);
+            }
+            // Context must fit query + the longest document (jina concatenates them).
+            // 512 is too small for real memories; 2048 covers MAX_DOC_CHARS + query.
+            _rankCtx = await _model.createRankingContext({ contextSize: 2048 });
+        }
+        _state = "ready";
+    }
+    catch (err) {
+        _state = "failed";
+        _initError = err?.message || String(err);
+        if (!_warnedOnce) {
+            console.warn(`[rerank] WARN: reranker unavailable, recall falls back to vector order. Error: ${_initError}`);
+            _warnedOnce = true;
+        }
+        // Best-effort cleanup of any partial handles.
+        await disposeHandles().catch(() => { });
+    }
+}
+async function disposeHandles() {
+    try {
+        if (_rankCtx) {
+            await _rankCtx.dispose();
+            _rankCtx = null;
+        }
+        if (_ctx) {
+            await _ctx.dispose();
+            _ctx = null;
+            _seq = null;
+        }
+        if (_model) {
+            await _model.dispose();
+            _model = null;
+        }
+    }
+    catch { /* ignore */ }
+}
+/** Reset (or recreate) the shared generative sequence to a clean KV state. */
+async function resetSequence() {
+    try {
+        if (_seq && typeof _seq.clearHistory === "function") {
+            await _seq.clearHistory();
+            return;
+        }
+    }
+    catch { /* fall through to recreate */ }
+    // clearHistory unavailable or threw — recreate the sequence from the context.
+    try {
+        _seq?.dispose?.();
+    }
+    catch { /* ignore */ }
+    _seq = _ctx.getSequence();
+}
+/** Generative yes/no score for one (query, doc) pair. */
+async function scoreGenerative(q, doc) {
+    const tokens = _model.tokenize(buildQwenPrompt(q, doc.slice(0, MAX_DOC_CHARS)), true);
+    // Reset the sequence so each pair is scored independently (deterministic) and
+    // a prior eval can't poison this one ("Eval has failed" after a bad state).
+    await resetSequence();
+    const input = tokens.map((t, i) => i === tokens.length - 1 ? [t, { generateNext: { probabilities: true } }] : t);
+    const out = await _seq.controlledEvaluate(input);
+    const lastDefined = [...out].reverse().find((x) => x !== undefined);
+    const probs = lastDefined?.next?.probabilities;
+    // Defensive: under some runtimes (observed in Harper's resource worker with a
+    // second native llama backend already resident — HFE's raw-addon embedding
+    // engine) controlledEvaluate returns an empty result array (no decoded
+    // logits). Treat that as "can't score" and signal the caller to fall open,
+    // rather than silently returning 0 (which would corrupt the ranking).
+    if (out.length === 0 || !probs) {
+        throw new Error("generative reranker produced no logits (empty controlledEvaluate result)");
+    }
+    const pYes = _yesToks.reduce((s, t) => s + (probs.get(t) ?? 0), 0);
+    const pNo = _noToks.reduce((s, t) => s + (probs.get(t) ?? 0), 0);
+    return pYes + pNo > 0 ? pYes / (pYes + pNo) : 0;
+}
+// Serialize all engine work. node-llama-cpp's context/sequence is single-use:
+// concurrent controlledEvaluate calls on the shared sequence corrupt the KV
+// cache ("Eval has failed"). Harper calls SemanticSearch.post() concurrently,
+// so we funnel every rerank through one in-process queue. Each search still
+// gets the full engine; they just don't overlap on the hardware. The latency
+// budget in rerankCandidates bounds how long any one search waits.
+let _engineChain = Promise.resolve();
+function runExclusive(fn) {
+    const next = _engineChain.then(fn, fn);
+    // Keep the chain alive regardless of this task's outcome.
+    _engineChain = next.then(() => undefined, () => undefined);
+    return next;
+}
+/**
+ * Score query against a batch of documents. Returns an array of scores in the
+ * same order as `docs`, in [0,1]. Higher = more relevant. Throws on engine
+ * error (caller catches and falls back to vector order). Engine access is
+ * serialized — see runExclusive.
+ */
+export async function rerankScores(query, docs) {
+    await ensureInit();
+    if (_state !== "ready")
+        throw new Error("reranker not ready");
+    if (_mode === "rank") {
+        const trimmed = docs.map((d) => String(d ?? "").slice(0, MAX_DOC_CHARS));
+        return runExclusive(() => _rankCtx.rankAll(query, trimmed));
+    }
+    // generative — score sequentially under the engine lock (single shared
+    // sequence; deterministic). The whole batch holds the lock for one search so
+    // its sequence resets aren't interleaved with another search's.
+    return runExclusive(async () => {
+        const scores = [];
+        for (const d of docs) {
+            scores.push(await scoreGenerative(query, String(d ?? "")));
+        }
+        return scores;
+    });
+}
+/**
+ * Rerank `candidates` (each must carry `content`) against `query`. Reorders in
+ * place by rerank score and overwrites `_score` with it (so downstream margin
+ * measurement reads the rerank score); preserves the original semantic score as
+ * `_semScore`. `_rawScore` is intentionally NOT touched (recall-bench's raw mode
+ * must stay reproducible).
+ *
+ * FAIL-OPEN: on init failure, timeout, or any throw, returns the input array
+ * UNCHANGED (caller then applies the existing vector-order sort). Never throws.
+ */
+export async function rerankCandidates(query, candidates, opts) {
+    const top = candidates.slice(0, Math.max(0, opts.topN));
+    if (top.length < 2)
+        return candidates;
+    const t0 = Date.now();
+    let timer;
+    try {
+        const docs = top.map((c) => String(c.content ?? ""));
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), Math.max(1, opts.budgetMs));
+        });
+        // Swallow a LATE rejection: if the budget wins the race, the scoring promise
+        // is still pending and may reject afterwards — attach a no-op catch so it
+        // doesn't surface as an unhandled rejection.
+        const scoring = rerankScores(query, docs);
+        scoring.catch(() => { });
+        const scores = await Promise.race([scoring, timeout]);
+        if (timer)
+            clearTimeout(timer);
+        if (scores === null) {
+            // Budget exceeded — abandon rerank, keep vector order. No partial reorder.
+            _fallbackCount++;
+            return candidates;
+        }
+        // Attach rerank score, preserve the semantic score for diagnostics.
+        const reranked = top.map((c, i) => {
+            const sem = c._score;
+            c._semScore = sem;
+            c._score = Math.round((scores[i] ?? 0) * 1000) / 1000;
+            return c;
+        });
+        reranked.sort((a, b) => (b._score ?? 0) - (a._score ?? 0));
+        // Candidates beyond topN (not reranked) keep their vector position AFTER the
+        // reranked block — they were already the tail of the vector-ordered pool.
+        const tail = candidates.slice(top.length);
+        _lastLatencyMs = Date.now() - t0;
+        _rerankCount++;
+        return [...reranked, ...tail];
+    }
+    catch (err) {
+        if (timer)
+            clearTimeout(timer);
+        _fallbackCount++;
+        if (!_warnedOnce) {
+            console.warn(`[rerank] WARN: rerank threw, falling back to vector order. Error: ${err?.message || err}`);
+            _warnedOnce = true;
+        }
+        return candidates;
+    }
+}
+/** Is the master flag on? (Default OFF.) */
+export function isRerankEnabled() {
+    return process.env.FLAIR_RERANK_ENABLED === "true";
+}
+/** Candidate count fed to the reranker. Caps the HNSW fetch. */
+export function getRerankTopN() {
+    const v = Number(process.env.FLAIR_RERANK_TOPN);
+    return Number.isFinite(v) && v > 0 ? Math.floor(v) : 50;
+}
+/** Hard latency budget for the whole rerank stage (ms). */
+export function getRerankBudgetMs() {
+    const v = Number(process.env.FLAIR_RERANK_BUDGET_MS);
+    return Number.isFinite(v) && v > 0 ? Math.floor(v) : 2500;
+}
+/** Skip rerank below this many candidates (nothing to reorder). */
+export function getRerankMinCandidates() {
+    const v = Number(process.env.FLAIR_RERANK_MIN_CANDIDATES);
+    return Number.isFinite(v) && v >= 2 ? Math.floor(v) : 2;
+}
+/** Status surface for health.ts. */
+export function getRerankStatus() {
+    return {
+        enabled: isRerankEnabled(),
+        model: _modelKey || resolveModelKey(),
+        mode: _mode ?? "uninitialized",
+        state: _state,
+        topN: getRerankTopN(),
+        budgetMs: getRerankBudgetMs(),
+        lastLatencyMs: _lastLatencyMs,
+        rerankCount: _rerankCount,
+        fallbackCount: _fallbackCount,
+        error: _initError,
+    };
+}
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Exported pure helpers so the deterministic scoring path can be unit-tested
+// without loading a 600MB GGUF (mirrors the pilot's deterministic approach:
+// given fixed yes/no probabilities, the score + reorder math is exact).
+/** P(yes)/(P(yes)+P(no)) — the generative reranker's scoring function. */
+export function yesNoScore(pYes, pNo) {
+    return pYes + pNo > 0 ? pYes / (pYes + pNo) : 0;
+}
+/**
+ * Pure reorder used by rerankCandidates: attach scores, overwrite `_score`,
+ * preserve `_semScore`, leave `_rawScore` untouched, sort desc, append the
+ * non-reranked tail. Exported for deterministic unit tests.
+ */
+export function applyRerank(candidates, scores, topN) {
+    const top = candidates.slice(0, Math.max(0, topN));
+    const reranked = top.map((c, i) => {
+        c._semScore = c._score;
+        c._score = Math.round((scores[i] ?? 0) * 1000) / 1000;
+        return c;
+    });
+    reranked.sort((a, b) => (b._score ?? 0) - (a._score ?? 0));
+    return [...reranked, ...candidates.slice(top.length)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -62,6 +62,7 @@
     "harper-fabric-embeddings": "0.2.3",
     "jose": "6.2.2",
     "js-yaml": "4.1.1",
+    "node-llama-cpp": "3.18.1",
     "tar": "7.5.13",
     "tweetnacl": "1.0.3"
   },