@tpsdev-ai/flair 0.30.0 → 0.31.0

package/dist/replication-convergence.js

@@ -0,0 +1,505 @@
+/**
+ * replication-convergence.ts — flair#878
+ *
+ * Harper Fabric's component replication to peers converges ASYNCHRONOUSLY. A
+ * peer-replication error raised by `harper deploy` is therefore a snapshot of
+ * one instant, not a terminal verdict: the origin has the component, one peer
+ * did not have it *at the moment the deploy call returned*, and Harper keeps
+ * healing after the CLI has stopped watching.
+ *
+ * The incident this module closes (flair#878): a two-node cluster upgrade
+ * reported
+ *
+ *     Component 'flair' was deployed on the origin node but failed to
+ *     replicate to 1 of 1 peer node(s): <peer> (Error: Connection closed 1006)
+ *
+ * and the CLI treated it as failure. Afterwards both nodes carried
+ * byte-identical component files and all data was intact — the upgrade had
+ * succeeded. Worse, the CLI's retry re-ran the full deploy while Harper was
+ * still healing, and *that* attempt died with an npm `ENOTEMPTY` on a native
+ * module, turning a transient warning into a hard, misleading failure.
+ *
+ * ── The signal this module uses ─────────────────────────────────────────────
+ * `cluster_status` — the operation that would answer "are my cluster peers in
+ * sync" — is harper-pro-only and unavailable in the OSS build this CLI ships
+ * (see src/fleet-verify.ts's header for the same constraint). What IS
+ * available in the OSS build is `get_components`, an `admin_read` operation
+ * that walks the components root and returns, per file, `{ name, size, mtime }`
+ * (directories recurse through `entries`; `node_modules` is excluded
+ * server-side). Addressing it at each node's OWN hostname yields a per-node
+ * fingerprint of the deployed component tree, and comparing peer-to-origin
+ * answers exactly the question the deploy error left open.
+ *
+ * `mtime` is the load-bearing half of that fingerprint, not decoration: a peer
+ * still holding the PREVIOUS version can easily match on size (a same-length
+ * version string, an unchanged asset) but cannot match on the extraction
+ * timestamp the origin just stamped. Size alone would be a much weaker check.
+ *
+ * ── Why a node-identity guard exists (the false-success this would otherwise
+ *    have) ────────────────────────────────────────────────────────────────────
+ * A Fabric cluster endpoint is GTM-steered: `https://<cluster>.<org>.
+ * harperfabric.com` resolves to ONE of the member nodes, and which one is not
+ * guaranteed stable between the deploy call and this poll. If the cluster
+ * endpoint happened to steer to the very peer that failed, a naive
+ * origin-vs-peer comparison would be comparing a node against ITSELF and would
+ * report `converged` for a cluster that never converged — precisely the
+ * failure mode that is worse than the bug being fixed, because it turns a
+ * false alarm into a false all-clear.
+ *
+ * The guard is a DNS resolution of both hostnames: the peer is only compared
+ * against the deploy target when the two resolve to disjoint address sets.
+ * Overlapping (or unresolvable) addresses yield `unknown`, never `converged`.
+ * This is the reporter's own observation encoded as a check rather than as
+ * prose a future reader has to remember — the two nodes "resolve to different
+ * IPs" is the property that makes the comparison meaningful at all.
+ *
+ * ── The invariant every caller may rely on ──────────────────────────────────
+ * `converged: true` is returned ONLY when every named peer was positively
+ * observed, over a distinct network identity, to hold a component tree
+ * identical to the origin's. Every other outcome — unparseable error, node
+ * name that is not an addressable host, DNS failure, shared address, HTTP
+ * failure, absent component, differing files — is `converged: false`. There is
+ * no path that infers convergence from the absence of evidence.
+ */
+import { lookup } from "node:dns/promises";
+// ─── Tunables ────────────────────────────────────────────────────────────────
+/**
+ * How long to wait for asynchronous peer replication to converge before giving
+ * up on confirming it. Generous on purpose: the whole point is that Harper is
+ * still working after the deploy call returned, and the cost of waiting is a
+ * slower failure report, while the cost of NOT waiting is the flair#878
+ * false-failure plus a destructive retry.
+ */
+export const DEFAULT_CONVERGENCE_TIMEOUT_MS = 180_000;
+/** How often to re-fingerprint every node while waiting. */
+export const CONVERGENCE_POLL_INTERVAL_MS = 10_000;
+/**
+ * Quiescence (see awaitOriginQuiescent): how many consecutive identical
+ * fingerprints of the ORIGIN's component tree count as "nothing is writing to
+ * it any more". Two is the minimum that can distinguish "stable" from "read
+ * once"; the interval between them is what gives it meaning.
+ */
+export const QUIESCENT_STABLE_READS = 2;
+export const DEFAULT_QUIESCENT_TIMEOUT_MS = 120_000;
+export const QUIESCENT_POLL_INTERVAL_MS = 5_000;
+/**
+ * Harper builds the message as (components/operations.js):
+ *
+ *   `Component '<name>' was deployed on the origin node but failed to
+ *    replicate to <failed> of <total> peer node(s): <node> (<error>)[, ...].
+ *    See deployment <id> (get_deployment) for details, or pass
+ *    ignore_replication_errors: true ...`
+ *
+ * Both counts and the deployment-id tail are optional here — the aim is to
+ * recover the peer NAMES, since those are the only handle the CLI has on the
+ * cluster's actual topology (`cluster_status` being unavailable). Anything
+ * unrecognised yields an empty peer list, which callers must treat as "cannot
+ * check", never as "nothing failed".
+ *
+ * Literal regexes only (no interpolation) — satisfies semgrep
+ * detect-non-literal-regexp.
+ */
+const REPLICATION_DETAIL_RE = /failed to replicate to (\d+)(?: of (\d+))? peer node\(s\):\s*([\s\S]*?)(?:\.\s*See deployment\s+(\S+?)\s*\(get_deployment\)|\.\s*$|$)/i;
+/** One `name (error)` entry out of the comma-separated detail list. */
+const PEER_ENTRY_RE = /([^,()]+?)\s*\(([^)]*)\)/g;
+export function parseReplicationFailure(output) {
+    const empty = {
+        peers: [],
+        failedCount: null,
+        totalCount: null,
+        deploymentId: null,
+    };
+    if (!output)
+        return empty;
+    const m = REPLICATION_DETAIL_RE.exec(output);
+    if (!m)
+        return empty;
+    const failedCount = Number.isFinite(Number(m[1])) ? Number(m[1]) : null;
+    const totalCount = m[2] != null && Number.isFinite(Number(m[2])) ? Number(m[2]) : null;
+    const deploymentId = m[4] ?? null;
+    const peers = [];
+    const detail = (m[3] ?? "").split("\n")[0];
+    for (const entry of detail.matchAll(PEER_ENTRY_RE)) {
+        const node = entry[1].trim();
+        if (!node)
+            continue;
+        peers.push({ node, error: entry[2].trim() });
+    }
+    return { peers, failedCount, totalCount, deploymentId };
+}
+/**
+ * Harper serialises `mtime` as a Date, which crosses JSON as an ISO string.
+ * Normalising through Date makes the comparison immune to a peer reporting a
+ * different-but-equivalent encoding; an unparseable value is compared verbatim
+ * rather than silently dropped (dropping it would weaken the check).
+ */
+function normalizeMtime(value) {
+    if (value == null)
+        return "-";
+    const asDate = new Date(value);
+    const ms = asDate.getTime();
+    return Number.isNaN(ms) ? `raw:${String(value)}` : asDate.toISOString();
+}
+function collectFiles(entry, prefix, out) {
+    if (!entry || typeof entry.name !== "string")
+        return;
+    const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (Array.isArray(entry.entries)) {
+        for (const child of entry.entries)
+            collectFiles(child, path, out);
+        return;
+    }
+    const size = typeof entry.size === "number" ? String(entry.size) : "?";
+    out.push(`${path} ${size} ${normalizeMtime(entry.mtime)}`);
+}
+/**
+ * Reduce a `get_components` response to a stable, comparable fingerprint of ONE
+ * component's file tree.
+ *
+ * Returns null when the response doesn't contain that component, or contains it
+ * with no files at all. Null is deliberately NOT a fingerprint: two nodes that
+ * both lack the component would otherwise "match" and be reported converged.
+ */
+export function fingerprintComponent(body, project) {
+    const roots = body?.entries;
+    if (!Array.isArray(roots))
+        return null;
+    const component = roots.find((e) => e && typeof e === "object" && e.name === project);
+    if (!component)
+        return null;
+    const children = Array.isArray(component.entries) ? component.entries : [];
+    const lines = [];
+    for (const child of children)
+        collectFiles(child, "", lines);
+    if (lines.length === 0)
+        return null;
+    lines.sort();
+    return lines.join("\n");
+}
+/** How many file entries differ between two fingerprints (for operator-facing detail). */
+export function fingerprintDiffCount(a, b) {
+    const left = new Set(a.split("\n"));
+    const right = new Set(b.split("\n"));
+    let diff = 0;
+    for (const line of left)
+        if (!right.has(line))
+            diff++;
+    for (const line of right)
+        if (!left.has(line))
+            diff++;
+    return diff;
+}
+// ─── Addressing a node ──────────────────────────────────────────────────────
+/**
+ * A Harper node name is a hostname (server/nodeName.ts derives it from
+ * `node.hostname`, the replication URL, or the TLS certificate CN), so it can
+ * normally be addressed directly with the deploy target's scheme and port.
+ *
+ * But harper's error detail is FREE TEXT — the per-peer entry falls back to the
+ * literal `'unknown'`, and a malformed cluster can put an arbitrary message
+ * there. Anything that isn't a plain `host[:port]` is rejected rather than
+ * guessed at: an unaddressable node yields "cannot check", which is safe, while
+ * a guessed address could reach the wrong machine, which is not.
+ */
+const HOSTPORT_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?(?::\d{1,5})?$/;
+export function resolvePeerUrl(node, referenceUrl) {
+    const trimmed = (node ?? "").trim();
+    if (!trimmed || trimmed.toLowerCase() === "unknown")
+        return null;
+    if (/^https?:\/\//i.test(trimmed)) {
+        try {
+            return new URL(trimmed).origin;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!HOSTPORT_RE.test(trimmed))
+        return null;
+    let reference;
+    try {
+        reference = new URL(referenceUrl);
+    }
+    catch {
+        return null;
+    }
+    const lastColon = trimmed.lastIndexOf(":");
+    const host = lastColon > 0 ? trimmed.slice(0, lastColon) : trimmed;
+    const port = lastColon > 0 ? trimmed.slice(lastColon + 1) : "";
+    const url = new URL(reference.origin);
+    url.hostname = host;
+    if (port)
+        url.port = port;
+    // Setting an invalid hostname on a URL is a silent no-op in WHATWG URL, which
+    // would leave us pointed at the ORIGIN while believing we addressed the peer.
+    if (url.hostname !== host.toLowerCase())
+        return null;
+    return url.origin;
+}
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Real `get_components` caller. Fabric serves the operations API on the same
+ * origin the deploy targets, with the same admin Basic auth the deploy used.
+ *
+ * NEVER logs or returns the credential, and never folds a response BODY into a
+ * thrown error — only the status code. An operations-API error body can echo
+ * request context, and this runs with cluster-admin credentials.
+ */
+export function buildOpsGetComponents(fabricUser, fabricPassword, timeoutMs = 15_000) {
+    const headers = { "Content-Type": "application/json" };
+    if (fabricUser && fabricPassword) {
+        headers.Authorization = `Basic ${Buffer.from(`${fabricUser}:${fabricPassword}`).toString("base64")}`;
+    }
+    return async (baseUrl) => {
+        const res = await fetch(baseUrl.replace(/\/+$/, "") + "/", {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ operation: "get_components" }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            throw new Error(`get_components returned HTTP ${res.status}`);
+        return (await res.json());
+    };
+}
+async function defaultResolveHostAddresses(hostname) {
+    const records = await lookup(hostname, { all: true });
+    return records.map((r) => r.address);
+}
+export function defaultConvergenceDeps(fabricUser, fabricPassword, onProgress) {
+    return {
+        getComponents: buildOpsGetComponents(fabricUser, fabricPassword),
+        resolveHostAddresses: defaultResolveHostAddresses,
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        onProgress,
+    };
+}
+function summarize(peers, converged, conclusive) {
+    if (peers.length === 0) {
+        return "harper's replication error named no peer nodes — convergence could not be checked";
+    }
+    if (converged) {
+        const names = peers.map((p) => p.node).join(", ");
+        return `all ${peers.length} peer node(s) hold the same component tree as the origin (${names})`;
+    }
+    const parts = peers.map((p) => `${p.node}: ${p.state} — ${p.detail}`);
+    return conclusive
+        ? `peer replication did NOT converge — ${parts.join("; ")}`
+        : `convergence could NOT be determined — ${parts.join("; ")}`;
+}
+/**
+ * Poll every named peer until its component tree matches the origin's, or the
+ * deadline passes.
+ *
+ * Never throws for cluster-side reasons: a peer that cannot be reached, named,
+ * or resolved is reported as `unknown` and the caller decides. The only
+ * unhandled throw would be a bug in an injected dep.
+ */
+export async function awaitReplicationConvergence(opts, deps) {
+    const started = deps.now();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_CONVERGENCE_TIMEOUT_MS;
+    const pollIntervalMs = opts.pollIntervalMs ?? CONVERGENCE_POLL_INTERVAL_MS;
+    const deadline = started + timeoutMs;
+    const results = opts.peers.map((p) => {
+        const url = resolvePeerUrl(p.node, opts.targetUrl);
+        return {
+            node: p.node,
+            url,
+            state: "unknown",
+            detail: url
+                ? "not checked yet"
+                : `harper reported "${p.node}", which is not an addressable host — this CLI will not guess an address for it, so convergence cannot be checked from here`,
+        };
+    });
+    const finish = () => {
+        const converged = results.length > 0 && results.every((r) => r.state === "converged");
+        const conclusive = results.length > 0 && results.every((r) => r.state !== "unknown");
+        return {
+            converged,
+            conclusive,
+            peers: results,
+            elapsedMs: deps.now() - started,
+            detail: summarize(results, converged, conclusive),
+        };
+    };
+    const addressable = results.filter((r) => r.url !== null);
+    if (addressable.length === 0)
+        return finish();
+    const targetHost = hostnameOf(opts.targetUrl);
+    let targetAddresses = [];
+    if (targetHost) {
+        try {
+            targetAddresses = await deps.resolveHostAddresses(targetHost);
+        }
+        catch {
+            targetAddresses = [];
+        }
+    }
+    for (;;) {
+        let originFingerprint = null;
+        let originError = null;
+        try {
+            originFingerprint = fingerprintComponent(await deps.getComponents(opts.targetUrl), opts.project);
+            if (!originFingerprint) {
+                originError = `the deploy target did not report a '${opts.project}' component tree to compare peers against`;
+            }
+        }
+        catch (err) {
+            originError = `could not read the deploy target's component tree: ${err?.message ?? String(err)}`;
+        }
+        for (const peer of results) {
+            if (peer.state === "converged" || peer.url === null)
+                continue;
+            if (!originFingerprint) {
+                peer.state = "unknown";
+                peer.detail = originError ?? "no origin fingerprint to compare against";
+                continue;
+            }
+            const peerHost = hostnameOf(peer.url);
+            let peerAddresses = [];
+            if (peerHost) {
+                try {
+                    peerAddresses = await deps.resolveHostAddresses(peerHost);
+                }
+                catch {
+                    peerAddresses = [];
+                }
+            }
+            if (peerAddresses.length === 0) {
+                peer.state = "unknown";
+                peer.detail = `${peerHost ?? peer.url} did not resolve — cannot reach this node to check whether it converged`;
+                continue;
+            }
+            if (targetAddresses.length === 0) {
+                peer.state = "unknown";
+                peer.detail =
+                    `the deploy target's own hostname did not resolve, so this peer cannot be proven to be a different ` +
+                        `node from it — refusing to compare a node against itself`;
+                continue;
+            }
+            if (peerAddresses.some((a) => targetAddresses.includes(a))) {
+                peer.state = "unknown";
+                peer.detail =
+                    `${peerHost} currently resolves to the same address as the deploy target — a Fabric cluster endpoint ` +
+                        `is steered to one member node, so this comparison would be the peer against itself. Refusing to ` +
+                        `report convergence from it`;
+                continue;
+            }
+            let peerFingerprint = null;
+            try {
+                peerFingerprint = fingerprintComponent(await deps.getComponents(peer.url), opts.project);
+            }
+            catch (err) {
+                peer.state = "unknown";
+                peer.detail = `could not read this node's component tree: ${err?.message ?? String(err)}`;
+                continue;
+            }
+            if (!peerFingerprint) {
+                peer.state = "diverged";
+                peer.detail = `this node reports no '${opts.project}' component at all`;
+                continue;
+            }
+            if (peerFingerprint === originFingerprint) {
+                peer.state = "converged";
+                peer.detail = "component files match the origin byte-for-byte (name, size and mtime)";
+                continue;
+            }
+            peer.state = "diverged";
+            peer.detail = `${fingerprintDiffCount(originFingerprint, peerFingerprint)} component file entr(ies) differ from the origin`;
+        }
+        if (results.every((r) => r.state === "converged"))
+            break;
+        if (deps.now() >= deadline)
+            break;
+        deps.onProgress?.(`waiting for peer replication to converge (${results.filter((r) => r.state === "converged").length}/${results.length} peer(s) match the origin so far)...`);
+        await deps.sleep(pollIntervalMs);
+    }
+    return finish();
+}
+/**
+ * Wait until the ORIGIN's component tree stops changing.
+ *
+ * This is the retry's clean-first precondition. Retrying on a fixed 5s/10s
+ * backoff re-issues a full deploy while the previous attempt's SERVER-SIDE work
+ * — tarball extraction and `npm install` into `<components-root>/<project>` —
+ * may still be running, and two writers in one component directory is the
+ * best available explanation for the reported
+ * `ENOTEMPTY: directory not empty, rmdir '.../node_modules/<pkg>/dist'`, the
+ * error that took that upgrade from "transient warning" to "failed".
+ *
+ * Stated honestly: the CLI cannot observe WHY the remote install failed — that
+ * happened inside Harper on another host. What it can do is remove the overlap,
+ * which is a necessary condition for any concurrent-writer explanation and
+ * costs nothing when the explanation is something else.
+ *
+ * What the CLI CANNOT do is make Harper's remote install clean-first directly.
+ * Harper consults a component's `install_command` only when `node_modules` is
+ * ABSENT — `components/Application.ts` returns early ("already has
+ * node_modules; skipping install") before the custom command is ever read — so
+ * it cannot be used to clear an existing tree, and `deploy_component` exposes no
+ * clean/force-reinstall option. Not starting attempt N+1 on top of attempt N is
+ * therefore the only clean-first guarantee available from this side.
+ *
+ * Returns `quiescent: false` when it could not establish stability. Callers
+ * must treat that as "do not retry", never as "safe to retry".
+ */
+export async function awaitOriginQuiescent(opts, deps) {
+    const started = deps.now();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_QUIESCENT_TIMEOUT_MS;
+    const pollIntervalMs = opts.pollIntervalMs ?? QUIESCENT_POLL_INTERVAL_MS;
+    const stableReads = opts.stableReads ?? QUIESCENT_STABLE_READS;
+    const deadline = started + timeoutMs;
+    let previous = null;
+    let streak = 0;
+    let lastError = null;
+    for (;;) {
+        let fingerprint = null;
+        try {
+            fingerprint = fingerprintComponent(await deps.getComponents(opts.targetUrl), opts.project);
+            if (!fingerprint)
+                lastError = `the deploy target reports no '${opts.project}' component tree`;
+        }
+        catch (err) {
+            lastError = err?.message ?? String(err);
+        }
+        if (fingerprint) {
+            if (previous !== null && fingerprint === previous) {
+                streak++;
+            }
+            else {
+                streak = 1;
+            }
+            previous = fingerprint;
+            lastError = null;
+            if (streak >= stableReads) {
+                return {
+                    quiescent: true,
+                    detail: `origin component tree unchanged across ${streak} consecutive reads`,
+                    elapsedMs: deps.now() - started,
+                };
+            }
+        }
+        else {
+            streak = 0;
+            previous = null;
+        }
+        if (deps.now() >= deadline) {
+            return {
+                quiescent: false,
+                detail: `origin component tree did not settle within ${timeoutMs}ms` +
+                    (lastError ? ` (last read: ${lastError})` : " — it is still being written to"),
+                elapsedMs: deps.now() - started,
+            };
+        }
+        deps.onProgress?.("waiting for the origin's component tree to settle before retrying...");
+        await deps.sleep(pollIntervalMs);
+    }
+}

package/dist/resources/MemoryBootstrap.js

@@ -11,7 +11,7 @@ import { buildCollisionEntries, buildEntityMatchCondition, freshPresenceByAgent,
 // The bounded HNSW candidate-pool retrieval for the task-relevant/teammate/
 // collision surfaces (flair-bootstrap-scale-fix) — the SAME pure core
 // SemanticSearch.ts's post() wraps, called bare here so an internal
-// bootstrap call never trips SemanticSearch's rate-limit/reranker/
+// bootstrap call never trips SemanticSearch's rate-limit or
 // retrievalCount hit-tracking side effects (see resources/
 // semantic-retrieval-core.ts's module doc for the full boundary).
 import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
@@ -619,12 +619,11 @@ export class BootstrapMemories extends Resource {
                     queryEmbedding,
                     conditions: [scope.condition],
                     limit: candidatePoolK,
-                    // HNSW-leg pushdown ONLY (K&S verdict): no BM25 fusion, no
-                    // reranker for bootstrap — a different cost profile (BM25 over the
-                    // org corpus for a one-shot session-load could be MORE expensive
-                    // than HNSW-only unless cached across sessions; the reranker is a
-                    // generative call per candidate). Both are explicit opt-in
-                    // follow-ons, gated on their own harness runs.
+                    // HNSW-leg pushdown ONLY (K&S verdict): no BM25 fusion for
+                    // bootstrap — a different cost profile, since BM25 over the org
+                    // corpus for a one-shot session-load could be MORE expensive than
+                    // HNSW-only unless cached across sessions. Turning it on is an
+                    // explicit opt-in follow-on, gated on its own harness run.
                     hybrid: false,
                     // Per-set (this K-bounded pool only, never cross-applied to the
                     // permanent/recent/predicted sets above) — see this function's
@@ -679,7 +678,7 @@ export class BootstrapMemories extends Resource {
                 // `candidates` are already `_score`-sorted best-first, so filtering
                 // preserves that order). `retrieveCandidates()`'s cosine similarity
                 // replaces the raw JS dot product as the ranking signal (HNSW-only,
-                // no BM25/rerank) — the K&S-ratified, closest-to-a-wash choice; the
+                // no BM25) — the K&S-ratified, closest-to-a-wash choice; the
                 // recall harness gates any regression from this ranking-signal
                 // change (magnitude-sensitive dot product → normalized cosine).
                 const scored = candidates

package/dist/resources/SemanticSearch.js

@@ -4,7 +4,6 @@ import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { resolveReadScope } from "./memory-read-scope.js";
-import { isRerankEnabled, getRerankTopN, getRerankBudgetMs, getRerankMinCandidates, rerankCandidates, } from "./rerank-provider.js";
 // The BM25 + union-RRF hybrid path is feature-flagged via hybridEnabled()
 // (imported from ./bm25 — Harper-free so it's unit-testable). Default is ON as
 // of 2026-07-08 (see ./bm25.ts's hybridEnabled() doc); set
@@ -15,7 +14,7 @@ import { hybridEnabled } from "./bm25.js";
 // supersede/isAllowed) now lives in the pure, side-effect-free
 // retrieveCandidates() core (flair-bootstrap-scale-fix, Kern-approved
 // extraction) — MemoryBootstrap.ts calls the SAME core bare, without
-// tripping this file's rate-limit/reranker/hit-tracking side effects. See
+// tripping this file's rate-limit/hit-tracking side effects. See
 // resources/semantic-retrieval-core.ts's module doc for the full boundary.
 import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
 import { attachTrust } from "./trust-block.js";
@@ -181,29 +180,18 @@ export class SemanticSearch extends Resource {
             }
         }
         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; the
-        // reranker still applies to its output further down regardless of which
-        // path produced `filteredResults`.
-        const rerankOn = isRerankEnabled();
-        const rerankTopN = getRerankTopN();
         // The overfetch policy (how many raw candidates to pull from the
         // HNSW/BM25 legs relative to what the caller ultimately wants) is THIS
         // wrapper's decision — retrieveCandidates() never multiplies its `limit`
         // param internally (see resources/semantic-retrieval-core.ts's doc), so
         // every caller (this one, and MemoryBootstrap's own K formula) computes
-        // its own fetch depth. Hybrid's semantic leg is never rerank-widened
-        // (matches the pre-extraction behavior: only the legacy path widened for
-        // rerank).
-        const candidateLimit = hybrid
-            ? limit * CANDIDATE_MULTIPLIER
-            : (rerankOn ? Math.max(limit * CANDIDATE_MULTIPLIER, rerankTopN) : limit * CANDIDATE_MULTIPLIER);
+        // its own fetch depth. Both the hybrid path (CANDIDATE_MULTIPLIER on the
+        // semantic leg + SEM_LIMIT on the BM25 leg, fused by RRF) and the legacy
+        // vector-only path overfetch by the same multiplier, which is what gives
+        // composite re-scoring headroom to reorder before the final slice.
+        const candidateLimit = limit * CANDIDATE_MULTIPLIER;
         const ctx = this.getContext?.();
-        let filteredResults = await retrieveCandidates({
+        const filteredResults = await retrieveCandidates({
             queryEmbedding: qEmb,
             q,
             conditions,
@@ -233,10 +221,10 @@ export class SemanticSearch extends Resource {
             withSemSimilarity: abstain || includeTrust,
         });
         // ─── flair#744 slice 2 — first-class abstention ("no memory covers this")
-        // Opt-in only. Evaluated on the RETRIEVED candidate pool, BEFORE the
-        // reranker / final slice / hit-tracking, so an abstaining recall does no
-        // rerank work and never bumps retrievalCount for memories it declines to
-        // surface. The decision reads ONLY the best absolute semantic similarity
+        // Opt-in only. Evaluated on the RETRIEVED candidate pool, BEFORE the final
+        // slice / hit-tracking, so an abstaining recall never bumps retrievalCount
+        // for memories it declines to surface. The decision reads ONLY the best
+        // absolute semantic similarity
         // (never any principal/authority signal — abstention.ts is pure and
         // authority-free), against the single GLOBAL threshold. Default OFF ⇒ this
         // whole block is skipped and the response is byte-identical to pre-slice-2.
@@ -253,28 +241,12 @@ export class SemanticSearch extends Resource {
                 };
             }
         }
-        // ─── 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` retrieveCandidates() produced — legacy HNSW-only OR
-        // the BM25+union-RRF hybrid path — since both converge into the same
-        // shape (retrieveCandidates never exposes which leg produced a result).
-        // 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 retrieveCandidates'
-        // own vector-order sort — recall is never blocked. retrieveCandidates
-        // already returns its output sorted best-first, so the non-rerank branch
-        // needs no additional sort here.
-        if (rerankOn && qEmb && q && filteredResults.length >= getRerankMinCandidates()) {
-            filteredResults = await rerankCandidates(String(q), filteredResults, {
-                topN: rerankTopN,
-                budgetMs: getRerankBudgetMs(),
-            });
-        }
+        // retrieveCandidates() already returns its output sorted best-first
+        // (whichever leg produced it — legacy HNSW-only, the BM25+union-RRF hybrid
+        // path, or the keyword-only fallback all converge into the same shape), so
+        // the final slice needs no additional sort. A cross-encoder rerank stage
+        // used to sit here and reorder the pool before this slice; it was removed
+        // in flair#893 after measuring Δp@3 = 0.000 at 4.1× query latency.
         const topResults = filteredResults.slice(0, limit);
         // Async hit tracking — don't block the response
         const now = new Date().toISOString();

package/dist/resources/abstention.js

@@ -100,7 +100,7 @@ export const STRONG_BAND = 0.55;
  * Reads ONLY the `_semSimilarity` number the retrieval core
  * (resources/semantic-retrieval-core.ts) attaches to each semantic-leg result
  * WHEN abstention is requested — an absolute cosine similarity in [0,1],
- * independent of the RRF normalization / rerank that make the ranking `_score`
+ * independent of the RRF normalization that makes the ranking `_score`
  * a *relative* signal (the top RRF-fused result is normalized to 1.0 regardless
  * of how weak the actual match is, so `_score` is unusable as a confidence
  * floor — this is why abstention reads the absolute similarity instead).