@tpsdev-ai/flair 0.14.0 → 0.16.0

package/dist/resources/OrgEvent.js

@@ -23,8 +23,18 @@ export class OrgEvent extends databases.flair.OrgEvent {
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.authorId !== auth.agentId) {
-            return FORBIDDEN("forbidden: authorId must match authenticated agent");
+        // No-forge attribution: a non-admin agent's events are ALWAYS attributed to
+        // its authenticated identity (from the Ed25519 signature), never the body —
+        // an agent can only publish AS itself. We overwrite `authorId` rather than
+        // 403'ing a mismatch so a CLI client never has to echo its own id into the
+        // body (mirrors A2A message/send's "sender must match params.agentId" guard
+        // and Presence's "agentId from signature, NOT from body"). Admin agents may
+        // publish on behalf of another agent (body authorId honored, else their own).
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            content.authorId = auth.agentId;
+        }
+        else if (auth.kind === "agent" && auth.isAdmin) {
+            content.authorId ||= auth.agentId;
         }
         if (!content.id)
             content.id = `${content.authorId}-${new Date().toISOString()}`;

package/dist/resources/Presence.js

@@ -18,6 +18,7 @@
  */
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth } from "./agent-auth.js";
+import { b64ToArrayBuffer } from "./b64.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const WINDOW_MS = 30_000;
 const CURRENT_TASK_MAX_LENGTH = 200;
@@ -40,15 +41,8 @@ function pruneNonces() {
     }
 }
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
-function b64ToArrayBuffer(b64) {
-    const std = b64.replace(/-/g, "+").replace(/_/g, "/");
-    const bin = atob(std);
-    const buf = new ArrayBuffer(bin.length);
-    const view = new Uint8Array(buf);
-    for (let i = 0; i < bin.length; i++)
-        view[i] = bin.charCodeAt(i);
-    return buf;
-}
+// b64ToArrayBuffer lives in ./b64.ts (shared with auth-middleware.ts + agent-auth.ts
+// so the base64/base64url decoder can't drift across the three auth call sites).
 const keyCache = new Map();
 async function importEd25519Key(publicKeyStr) {
     if (keyCache.has(publicKeyStr))

package/dist/resources/SemanticSearch.js

@@ -8,6 +8,11 @@ import { wrapUntrusted } from "./content-safety.js";
 // relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
 // unit-tested directly (see test/unit/temporal-scoring.test.ts).
 import { compositeScore } from "./scoring.js";
+// BM25 + union-RRF hybrid retrieval (ops-i39b / FLAIR-BM25-HYBRID-RETRIEVAL).
+// Harper-free modules so the BM25 scoring, the candidate-union RRF, and the
+// SECURITY conditions-filter are unit-tested against the shipped code.
+import { buildBM25, fuseRrfNormalized, hybridEnabled, SEM_LIMIT } from "./bm25.js";
+import { isAllowedBm25Candidate } from "./bm25-filter.js";
 // Convert HNSW cosine distance (1 - similarity) to similarity score
 function distanceToSimilarity(distance) {
     return 1 - distance;
@@ -15,6 +20,9 @@ function distanceToSimilarity(distance) {
 // Candidate multiplier: fetch more candidates than needed from the HNSW index
 // so composite re-ranking has enough headroom to reorder results.
 const CANDIDATE_MULTIPLIER = 5;
+// The BM25 + union-RRF hybrid path is feature-flagged via hybridEnabled()
+// (imported from ./bm25 — Harper-free so it's unit-testable). Flag OFF (default)
+// → byte-identical to the pre-hybrid HNSW + +0.05 keyword-bump behavior.
 export class SemanticSearch extends Resource {
     // Self-authorize via the Ed25519 agent verify instead of relying on the auth
     // gate's admin super_user elevation (removed in the auth reshape). Any
@@ -161,8 +169,122 @@ export class SemanticSearch extends Resource {
             }
         }
         const results = [];
-        // ─── HNSW vector search path ───────────────────────────────────────────
-        if (qEmb) {
+        const hybrid = hybridEnabled();
+        if (hybrid) {
+            // ─── BM25 + union-RRF hybrid path (ops-i39b) ─────────────────────────
+            // 1. Semantic candidates via HNSW (unchanged fetch). 2. BM25 lexical pass
+            //    over the SCOPED corpus. 3. SECURITY: the BM25 candidate set is filtered
+            //    by the SAME conditions[] + temporal filters BEFORE fusion (the corpus
+            //    is fetched with those conditions, AND re-checked in-process as
+            //    defense-in-depth) so no other agent's memory is ever scored or fused.
+            //    4. Candidate-union RRF → normalize → feed as rawScore to compositeScore.
+            const ctx = this.getContext?.();
+            // ── (a) Semantic candidate records (best-first) ──────────────────────
+            // Same HNSW query as the legacy path; we keep the raw records so the BM25
+            // pass + fusion can re-derive rawScore. No embedding → empty semantic list
+            // (RRF degrades naturally to BM25-only).
+            const semRecords = [];
+            const semIds = [];
+            if (qEmb) {
+                const candidateLimit = limit * CANDIDATE_MULTIPLIER;
+                const semQuery = {
+                    sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
+                    select: ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
+                        "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "lastRetrieved",
+                        "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
+                        "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject",
+                        "validFrom", "validTo", "_safetyFlags", "$distance"],
+                    limit: candidateLimit,
+                };
+                if (conditions.length > 0)
+                    semQuery.conditions = conditions;
+                const semResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(semQuery));
+                for await (const record of semResults) {
+                    // Same per-record temporal gate as the legacy HNSW loop.
+                    if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
+                        continue;
+                    if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
+                        continue;
+                    if (asOf && record.validFrom && record.validFrom > asOf)
+                        continue;
+                    if (asOf && record.validTo && record.validTo <= asOf)
+                        continue;
+                    semRecords.push(record);
+                    semIds.push(record.id);
+                }
+            }
+            // ── (b) BM25 candidate records over the SCOPED corpus ────────────────
+            // SECURITY: fetch the corpus WITH the same conditions[] so Harper applies
+            // the agent boundary, then re-apply the identical predicate + temporal
+            // filters in-process (isAllowedBm25Candidate) BEFORE building/scoring the
+            // index. The BM25 index therefore only ever contains the caller's allowed
+            // memories — no other agent's content/term-frequency enters scoring or
+            // fusion. This is the conditions-filter-before-fusion gate.
+            // Explicit select (same fields as the HNSW path, no embedding / $distance)
+            // so the large embedding vector is never fetched into the BM25 corpus and
+            // never spread into a result payload.
+            const corpusSelect = ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
+                "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "lastRetrieved",
+                "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
+                "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject",
+                "validFrom", "validTo", "_safetyFlags"];
+            const corpusQuery = conditions.length > 0
+                ? { conditions, select: corpusSelect }
+                : { select: corpusSelect };
+            const corpusResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(corpusQuery));
+            const allowedById = new Map();
+            const bm25Docs = [];
+            for await (const record of corpusResults) {
+                // Defense-in-depth: re-check the SAME conditions[] + temporal filters
+                // in-process. Even if a Harper query change ever let an out-of-scope
+                // record through, it is dropped here BEFORE it can be BM25-scored/fused.
+                if (!isAllowedBm25Candidate(record, conditions, { sinceDate, asOf }))
+                    continue;
+                allowedById.set(record.id, record);
+                bm25Docs.push({ id: record.id, content: record.content });
+            }
+            // Carry semantic candidates that survived their temporal gate into the
+            // allowed map too (so a fused id always resolves to a record). Semantic
+            // records were fetched with the SAME conditions[], so they're in-scope.
+            for (const r of semRecords) {
+                if (!allowedById.has(r.id)) {
+                    const { $distance, ...rest } = r;
+                    allowedById.set(r.id, rest);
+                }
+            }
+            // ── (c) BM25 lexical ranking → top SEM_LIMIT (only when q present) ────
+            let bm25Ids = [];
+            if (q) {
+                const bm25 = buildBM25(bm25Docs);
+                const ranked = bm25.rank(String(q));
+                // Drop zero-score docs (no query-term overlap → contribute nothing) and
+                // cap at SEM_LIMIT — the production BM25 candidate window.
+                bm25Ids = ranked.filter(r => r.score > 0).slice(0, SEM_LIMIT).map(r => r.id);
+            }
+            // ── (d) Candidate-union RRF → normalized [0,1] rawScore ──────────────
+            // Union dedupes semantic ∪ bm25 ids; absent-from-a-list = 0 contribution.
+            const fused = fuseRrfNormalized(semIds, bm25Ids);
+            for (const [id, rrfRaw] of fused) {
+                const record = allowedById.get(id);
+                if (!record)
+                    continue; // should not happen — union ⊆ allowed
+                const rawScore = rrfRaw; // already normalized to [0,1]
+                let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+                if (temporalBoost > 1.0)
+                    finalScore *= temporalBoost;
+                const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
+                const source = record.agentId !== agentId ? record.agentId : undefined;
+                results.push({
+                    ...record,
+                    content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
+                    _score: Math.round(finalScore * 1000) / 1000,
+                    _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+                    _source: source,
+                });
+            }
+        }
+        else if (qEmb) {
+            // ─── HNSW vector search path ───────────────────────────────────────────
             const candidateLimit = limit * CANDIDATE_MULTIPLIER;
             const query = {
                 sort: { attribute: "embedding", target: qEmb, distance: "cosine" },

package/dist/resources/WorkspaceState.js

@@ -50,8 +50,18 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         // there was no authenticated agent, so anonymous could write any record).
         if (auth.kind === "anonymous")
             return UNAUTH();
-        if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
-            return FORBIDDEN("forbidden: cannot write workspace state for another agent");
+        // No-forge: a non-admin agent's workspace record is ALWAYS attributed to the
+        // authenticated identity (from the Ed25519 signature), never the body. We do
+        // NOT trust `content.agentId` — overwriting it (rather than 403'ing a
+        // mismatch) mirrors Presence.post(): "agentId from signature, NOT from body".
+        // An admin may write on behalf of another agent (content.agentId honored if
+        // present, else defaults to the admin's own id). Internal in-process callers
+        // keep whatever agentId they pass.
+        if (auth.kind === "agent" && !auth.isAdmin) {
+            content.agentId = auth.agentId;
+        }
+        else if (auth.kind === "agent" && auth.isAdmin) {
+            content.agentId ||= auth.agentId;
         }
         content.createdAt = new Date().toISOString();
         content.timestamp ||= content.createdAt;

package/dist/resources/agent-auth.js

@@ -16,6 +16,7 @@
  * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
  */
 import { databases } from "@harperfast/harper";
+import { b64ToArrayBuffer } from "./b64.js";
 const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
@@ -27,16 +28,8 @@ export const FLAIR_AGENT_USERNAME = "flair-agent";
 // Replay protection: remember recently-seen (agent:nonce), pruned by the window.
 const nonceSeen = new Map();
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
-function b64ToArrayBuffer(b64) {
-    // Handle both standard and URL-safe base64.
-    const std = b64.replace(/-/g, "+").replace(/_/g, "/");
-    const bin = atob(std);
-    const buf = new ArrayBuffer(bin.length);
-    const view = new Uint8Array(buf);
-    for (let i = 0; i < bin.length; i++)
-        view[i] = bin.charCodeAt(i);
-    return buf;
-}
+// b64ToArrayBuffer lives in ./b64.ts (shared with auth-middleware.ts + Presence.ts
+// so the base64/base64url decoder can't drift across the three auth call sites).
 const keyCache = new Map();
 async function importEd25519Key(publicKeyStr) {
     const cached = keyCache.get(publicKeyStr);

package/dist/resources/auth-middleware.js

@@ -2,6 +2,7 @@ import { patchRecord } from "./table-helpers.js";
 import { server, databases } from "@harperfast/harper";
 import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
+import { b64ToArrayBuffer } from "./b64.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -37,16 +38,8 @@ const nonceSeen = new Map();
 // auth reshape this gate and the per-resource allow* helpers must agree on who's
 // an admin — one implementation guarantees they can't diverge.
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
-function b64ToArrayBuffer(b64) {
-    // Handle both standard and URL-safe base64
-    const std = b64.replace(/-/g, '+').replace(/_/g, '/');
-    const bin = atob(std);
-    const buf = new ArrayBuffer(bin.length);
-    const view = new Uint8Array(buf);
-    for (let i = 0; i < bin.length; i++)
-        view[i] = bin.charCodeAt(i);
-    return buf;
-}
+// b64ToArrayBuffer lives in ./b64.ts (shared with agent-auth.ts + Presence.ts so
+// the base64/base64url decoder can't drift across the three auth call sites).
 const keyCache = new Map();
 async function importEd25519Key(publicKeyStr) {
     if (keyCache.has(publicKeyStr))

package/dist/resources/b64.js

@@ -0,0 +1,40 @@
+/**
+ * b64 — single shared base64 / base64url decoder for Ed25519 auth.
+ *
+ * This was previously copy-pasted into three files (auth-middleware.ts,
+ * agent-auth.ts, Presence.ts) and they drifted: some copies fed url-safe input
+ * straight to `atob`, which rejects `-`/`_` ("Invalid character") and 401s any
+ * agent whose public key (or signature) is base64url-encoded. Found in the
+ * Rivet × krais cross-org dogfood: an Agent registered with a base64url pubkey
+ * containing `-`/`_` failed signature verification. One shared decoder so the
+ * three call sites can't diverge again (same lesson as HarperFast/harper#1466).
+ *
+ * Accepts BOTH standard base64 (`+` `/`, with optional `=` padding) AND
+ * base64url (`-` `_`, padded or unpadded). Standard input is unchanged.
+ */
+/**
+ * Decode a base64 OR base64url string to an ArrayBuffer.
+ *
+ * Normalizes url-safe alphabet (`-`→`+`, `_`→`/`) and right-pads with `=` to a
+ * length that is a multiple of 4 before calling `atob`, so unpadded base64url
+ * (the common JWK / Buffer.toString('base64url') form — e.g. a 32-byte key is
+ * 43 chars, a 64-byte signature is 86 chars) decodes correctly regardless of
+ * how lenient the host runtime's `atob` is about missing padding.
+ */
+export function b64ToArrayBuffer(b64) {
+    // Normalize base64url → standard base64 alphabet.
+    let std = b64.replace(/-/g, "+").replace(/_/g, "/");
+    // Right-pad to a multiple of 4 so atob accepts unpadded base64url input.
+    const remainder = std.length % 4;
+    if (remainder === 2)
+        std += "==";
+    else if (remainder === 3)
+        std += "=";
+    // remainder === 1 is not a valid base64 length; let atob throw as before.
+    const bin = atob(std);
+    const buf = new ArrayBuffer(bin.length);
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < bin.length; i++)
+        view[i] = bin.charCodeAt(i);
+    return buf;
+}

package/dist/resources/bm25-filter.js

@@ -0,0 +1,84 @@
+// ─── BM25 candidate SECURITY filter (the hard cross-agent trust boundary) ────
+// Per spec FLAIR-BM25-HYBRID-RETRIEVAL §26 + Sherlock's gate (§45-46):
+//
+//   "apply the SAME conditions[] filter (agent scoping, archived exclusion,
+//    tag/subject) to the BM25 candidates BEFORE fusion. BM25-scoring other
+//    agents' private memories and filtering only after fusion would leak
+//    term-frequency / content metadata across agent boundaries. The conditions
+//    filter MUST precede the union/fusion."
+//
+// The HNSW path gets this filter FOR FREE — Harper applies conditions[] inside
+// Memory.search(). The BM25 pass runs in-process over the corpus, so it MUST
+// re-apply the IDENTICAL predicate itself, BEFORE any scoring is fused or even
+// returned. This module is the single source of that predicate.
+//
+// Harper-free + pure so the security test exercises the SHIPPED predicate
+// directly (test/unit/bm25-security.test.ts).
+//
+// The condition shapes mirror EXACTLY what SemanticSearch.ts builds:
+//   - leaf:  { attribute, comparator, value }
+//   - group: { operator: "or", conditions: [...] }
+// supported comparators: "equals", "not_equal" (the only ones SemanticSearch
+// emits into conditions[]). An unknown comparator/shape is treated as NON-matching
+// (fail closed — never leak on an unrecognized condition).
+function isGroup(c) {
+    return c.operator !== undefined && Array.isArray(c.conditions);
+}
+// Evaluate a single leaf condition against a record. `tags` is array-valued in
+// Harper; "equals" on an array attribute is membership (matches Harper's
+// array-attribute equals semantics used by the tag filter).
+function matchLeaf(cond, record) {
+    const actual = record?.[cond.attribute];
+    switch (cond.comparator) {
+        case "equals":
+            if (Array.isArray(actual))
+                return actual.includes(cond.value);
+            return actual === cond.value;
+        case "not_equal":
+            // Harper "not_equal" semantics used for `archived not_equal true`: a record
+            // WITHOUT the field (undefined) is included — it is "not equal" to true.
+            if (Array.isArray(actual))
+                return !actual.includes(cond.value);
+            return actual !== cond.value;
+        default:
+            // Unknown comparator → fail closed (do NOT pass a record on a condition we
+            // can't evaluate; that could leak across the agent boundary).
+            return false;
+    }
+}
+function matchCondition(cond, record) {
+    if (isGroup(cond)) {
+        const results = cond.conditions.map((c) => matchCondition(c, record));
+        return cond.operator === "or" ? results.some(Boolean) : results.every(Boolean);
+    }
+    return matchLeaf(cond, record);
+}
+// AND across the top-level conditions[] (Harper's default for a conditions array
+// — same as SemanticSearch passing them as the implicit-AND query.conditions).
+export function matchesConditions(conditions, record) {
+    for (const c of conditions) {
+        if (!matchCondition(c, record))
+            return false;
+    }
+    return true;
+}
+export function passesRecordFilters(record, f = {}) {
+    const now = f.now ?? Date.now();
+    if (record?.expiresAt && Date.parse(record.expiresAt) < now)
+        return false;
+    if (f.sinceDate && record?.createdAt && new Date(record.createdAt) < f.sinceDate)
+        return false;
+    if (f.asOf && record?.validFrom && record.validFrom > f.asOf)
+        return false;
+    if (f.asOf && record?.validTo && record.validTo <= f.asOf)
+        return false;
+    return true;
+}
+// The full BM25-candidate security filter: a record is a valid BM25 candidate
+// ONLY if it passes BOTH the agent-scoping/archived/tag/subject conditions[] AND
+// the per-record temporal filters — IDENTICAL to the HNSW candidate gate. Apply
+// this to the corpus BEFORE building/scoring the union (defense at the boundary,
+// not after fusion).
+export function isAllowedBm25Candidate(record, conditions, timeFilters = {}) {
+    return matchesConditions(conditions, record) && passesRecordFilters(record, timeFilters);
+}

package/dist/resources/bm25.js

@@ -0,0 +1,130 @@
+// ─── BM25 + union-RRF hybrid retrieval (Harper-free, unit-testable) ──────────
+// Per spec FLAIR-BM25-HYBRID-RETRIEVAL (Kern-approved, ops-i39b). This module is
+// deliberately Harper-free — same rationale as ./scoring.ts — so the BM25
+// scoring, the candidate-union RRF fusion, and the security conditions-filter
+// can be unit-tested directly against the SHIPPED code without a live Harper.
+//
+// Ported from the pilot ops/tools/agent-fabric/bm25-rrf-pilot.mjs (commit
+// 5552320), which validated: BM25 alone recovers 5/6 severe misses into top-3;
+// candidate-UNION RRF (NOT naive whole-corpus RRF) recovers 4/6 into top-10 with
+// no regression on the within-cluster gate (p@3 holds 0.88).
+// ─── Feature flag: BM25 + union-RRF hybrid retrieval ────────────────────────
+// Flag OFF (default) → SemanticSearch behavior is byte-identical to the
+// pre-hybrid path (HNSW + the +0.05 exact-substring keyword bump). Flag ON → the
+// hybrid path. Toggle with FLAIR_HYBRID_RETRIEVAL=true (also "1" / "on"). Read
+// per-call so it can be flipped without a rebuild and set per-case in tests.
+// Lives here (Harper-free) so it's unit-testable.
+export function hybridEnabled() {
+    const v = (process.env.FLAIR_HYBRID_RETRIEVAL ?? "").toLowerCase();
+    return v === "true" || v === "1" || v === "on";
+}
+// BM25 parameters (Kern-approved): k1≈1.2, b≈0.75; standard IDF + BM25.
+export const BM25_K1 = 1.2;
+export const BM25_B = 0.75;
+// RRF constant (Cormack et al. 2009 default). A doc absent from a list
+// contributes 0 from that list (rank = ∞).
+export const RRF_K = 60;
+// BM25 candidate window — top-N by BM25 score fused into the union (spec §35:
+// "BM25 uses a fixed SEM_LIMIT=50"). Independent of CANDIDATE_MULTIPLIER (the
+// HNSW fetch size, which is left untouched).
+export const SEM_LIMIT = 50;
+// Tokenize: lowercase, split on non-alphanumeric, drop trivial stopwords and
+// 1-char tokens. Standard, language-agnostic enough for the corpus.
+const STOP = new Set(("a an the and or but of to in on at for with from by as is are was were be been being " +
+    "this that these those it its do does did so if then than when how what why who whom which while " +
+    "i you he she we they them his her our your their not no yes can will would should could may might " +
+    "have has had get got into out over under again about up down off all any each").split(" "));
+export function tokenize(text) {
+    return ((text || "").toLowerCase().match(/[a-z0-9]+/g) || []).filter((t) => t.length > 1 && !STOP.has(t));
+}
+// Build a BM25 index over docs[].content. Standard Robertson/Sparck-Jones BM25
+// with the +1 IDF variant (always non-negative — the common Lucene/Elasticsearch
+// form).
+export function buildBM25(docs) {
+    const N = docs.length;
+    const docTokens = docs.map((d) => tokenize(d.content || ""));
+    const docLen = docTokens.map((t) => t.length);
+    const avgdl = docLen.reduce((s, x) => s + x, 0) / (N || 1);
+    const tfPerDoc = docTokens.map((toks) => {
+        const tf = new Map();
+        for (const t of toks)
+            tf.set(t, (tf.get(t) || 0) + 1);
+        return tf;
+    });
+    const df = new Map();
+    for (const tf of tfPerDoc)
+        for (const term of tf.keys())
+            df.set(term, (df.get(term) || 0) + 1);
+    const idf = new Map();
+    for (const [term, n] of df)
+        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
+    function rank(query) {
+        const qToks = [...new Set(tokenize(query))];
+        const scored = docs.map((d, i) => {
+            const tf = tfPerDoc[i];
+            const dl = docLen[i];
+            let s = 0;
+            for (const term of qToks) {
+                const f = tf.get(term);
+                if (!f)
+                    continue;
+                const numer = f * (BM25_K1 + 1);
+                const denom = f + BM25_K1 * (1 - BM25_B + BM25_B * (dl / (avgdl || 1)));
+                s += (idf.get(term) || 0) * (numer / denom);
+            }
+            return { id: d.id, score: s };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored;
+    }
+    return { rank, get N() { return N; }, get avgdl() { return avgdl; } };
+}
+// ─── Reciprocal Rank Fusion over a candidate UNION ──────────────────────────
+// rankings: array of ordered id-lists (best-first). A doc absent from a list
+// contributes 0 from that list. `universe` = the id set fused over — for the
+// production hybrid this is the candidate UNION (semantic ∪ bm25), NOT the whole
+// corpus (naive whole-corpus RRF FAILS — the broken semantic list floods the
+// fusion and buries BM25's rank-1 hits; pilot confirmed 0/6).
+//
+// Returns a Map id → raw RRF score. Caller normalizes + sorts.
+export function rrfScores(rankings, universe) {
+    const score = new Map();
+    for (const id of universe)
+        score.set(id, 0);
+    for (const list of rankings) {
+        list.forEach((id, idx) => {
+            if (!score.has(id))
+                return; // doc not in this universe (union mode)
+            score.set(id, (score.get(id) || 0) + 1 / (RRF_K + idx + 1)); // idx+1 = 1-based rank
+        });
+    }
+    return score;
+}
+// Fuse semantic + BM25 candidate id-lists via candidate-union RRF and return a
+// per-id score normalized to [0,1] (rrf / max_rrf_in_union). This normalized
+// value is the rawScore fed to compositeScore so durability/recency/rBoost and
+// the RBOOST_RELEVANCE_FLOOR / minScore thresholds still apply unchanged.
+//
+//   semIds  — semantic candidate ids, best-first (from the HNSW pass).
+//   bm25Ids — BM25 candidate ids, best-first, already sliced to SEM_LIMIT and
+//             already SECURITY-FILTERED (see filterBm25Candidates) BEFORE this call.
+//
+// The union dedupes ids across both lists. Absent-from-a-list = 0 contribution.
+export function fuseRrfNormalized(semIds, bm25Ids) {
+    const union = new Set([...semIds, ...bm25Ids]);
+    const raw = rrfScores([semIds, bm25Ids], union);
+    let maxRrf = 0;
+    for (const v of raw.values())
+        if (v > maxRrf)
+            maxRrf = v;
+    const norm = new Map();
+    if (maxRrf <= 0) {
+        // Degenerate (empty union) — nothing to normalize.
+        for (const [id] of raw)
+            norm.set(id, 0);
+        return norm;
+    }
+    for (const [id, v] of raw)
+        norm.set(id, v / maxRrf);
+    return norm;
+}

package/dist/resources/embeddings-provider.js

@@ -9,6 +9,39 @@
  * the VM linker entirely.
  */
 import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+/**
+ * Resolve the directory the embeddings model lives in / downloads into.
+ *
+ * Resolution order (everything writable, never the read-only package dir):
+ *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
+ *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
+ *                                ~/.flair/data when it spawns Harper). User-
+ *                                owned and writable even on sudo-global installs.
+ *   3. <cwd>/models            — ONLY if a model already lives there. Backward
+ *                                compat for existing writable installs that
+ *                                downloaded into the package dir before this fix;
+ *                                never used as a download target on fresh installs.
+ *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
+ *
+ * The chosen dir is always writable, so the embeddings engine can download the
+ * model on first use without hitting EACCES on a root-owned package dir.
+ */
+export function resolveModelsDir() {
+    const override = process.env.FLAIR_MODELS_DIR;
+    if (override)
+        return override;
+    const rootPath = process.env.ROOTPATH;
+    if (rootPath)
+        return join(rootPath, "models");
+    // Backward compat: a prior (writable) install may have the model cached in
+    // the package dir. Reuse it rather than re-downloading — but only if present.
+    const cwdModels = join(process.cwd(), "models");
+    if (existsSync(cwdModels))
+        return cwdModels;
+    return join(homedir(), ".flair", "data", "models");
+}
 let _state = "uninitialized";
 let _initError;
 let _warnedOnce = false;
@@ -29,19 +62,21 @@ async function ensureInit() {
         return;
     }
     catch {
-        // Not initialized — init with modelsDir pointing to where Harper's
-        // plugin loader downloaded the model (process.cwd() is the app dir).
+        // Not initialized — init with modelsDir pointing at a USER-WRITABLE
+        // location. On a sudo/root-owned global install the Flair package dir
+        // (process.cwd()) is root-owned, so a model download into <cwd>/models
+        // fails with EACCES and semantic search silently dies (ops-am0v). The
+        // model — and everything else Flair writes — must live under ~/.flair.
+        //
         // NOTE: import.meta.dirname and __dirname are both undefined in Harper v5's
-        // VM sandbox / worker threads, so we use process.cwd() which points to the
-        // Flair application directory.
+        // VM sandbox / worker threads, so we resolve from env + process.cwd().
         try {
             if (!_hfe) {
                 _hfe = await import("harper-fabric-embeddings");
             }
-            const modelsDir = join(process.cwd(), "models");
+            const modelsDir = resolveModelsDir();
             // Find the native addon binary explicitly to avoid __dirname-dependent
             // discovery in @node-llama-cpp which fails in Harper's VM sandbox.
-            const { existsSync } = await import("node:fs");
             const platforms = ["linux-x64", "mac-arm64-metal", "mac-arm64", "win-x64"];
             let addonPath;
             for (const platform of platforms) {