@tpsdev-ai/flair 0.23.0 → 0.25.0

package/dist/resources/abstention.js

@@ -0,0 +1,146 @@
+/**
+ * abstention.ts — first-class recall abstention ("no memory covers this")
+ * (flair#744 slice 2).
+ *
+ * ─── What this is ────────────────────────────────────────────────────────────
+ * Weak matches presented as answers are how a memory system *causes*
+ * confabulation instead of preventing it. When the best retrieval match is
+ * below a confidence floor, the honest response is a first-class "no memory
+ * covers this" verdict — NOT the N weakest matches dressed up as an answer.
+ * This module is the PURE, Harper-free decision core the recall wrappers
+ * (SemanticSearch.post, BootstrapMemories.post) consult in their response tail,
+ * strictly downstream of retrieval + read-scope resolution.
+ *
+ * ─── Opt-in, conservative, calibration is a SEPARATE follow-up ──────────────
+ * Slice 2 ships the abstention *response shape*, decoupled from threshold
+ * *calibration* (the design round's explicit sharpening). Consumers build
+ * against the API shape now; the promote-to-default calibration on the
+ * recall-bench corpus proceeds independently (NOT this slice). Until then the
+ * mode is opt-in (`abstain` request flag, default OFF ⇒ recall is byte-identical
+ * to today) and the threshold is a deliberately CONSERVATIVE hand-set constant
+ * that errs toward returning results rather than over-abstaining.
+ *
+ * ─── The GLOBAL-threshold invariant (flair#744 Sherlock BINDING condition 2) ─
+ * The abstention threshold MUST be GLOBAL (or scope-wide) and NEVER
+ * per-principal. A per-principal threshold ("this principal's memories need
+ * higher confidence to surface") would be an authority lever and would violate
+ * the zero-authority trust spine — the same discipline as the `claimed.*`
+ * guard (flair#735). This module makes that STRUCTURAL, not just documented:
+ *   1. ABSTENTION_THRESHOLD is a single module-level constant. There is no
+ *      per-principal (or any) threshold parameter — `evaluateAbstention` reads
+ *      the constant directly, so there is no lever to vary it per principal.
+ *   2. The decision consults ONLY a retrieval-confidence number. Neither
+ *      function below takes — or this module anywhere imports — an agentId,
+ *      principal, trust tier, or any authority signal. Enforced structurally by
+ *      test/unit/abstention-no-per-principal-tripwire.test.ts (the module is
+ *      scanned for authority tokens, and the decision function's arity is
+ *      pinned to its single numeric input).
+ */
+/**
+ * ABSTENTION_THRESHOLD — the single GLOBAL retrieval-confidence floor.
+ *
+ * When the best-match absolute semantic similarity (cosine, [0,1] — see
+ * `bestSemanticSimilarity`) is below this value, opt-in recall abstains
+ * ("no memory covers this") instead of returning the N weak matches.
+ *
+ * GLOBAL / data-driven, NEVER per-principal (Sherlock binding condition 2).
+ *
+ * CONSERVATIVE hand-set value (0.15): well below the strong-match band real
+ * embeddings produce for genuinely relevant memories, and below bootstrap's
+ * own long-standing task-relevance floor (0.3, resources/MemoryBootstrap.ts's
+ * TASK_RELEVANCE_FLOOR) — so abstention fires only when there is essentially
+ * nothing semantically near the query, erring toward returning results rather
+ * than over-abstaining. Promoting abstention to the DEFAULT recall mode, and
+ * tuning this value on the recall-bench corpus, is a SEPARATE follow-up (see
+ * flair#744) — this slice ships the response shape at a safe opt-in floor, not
+ * the calibrated default.
+ */
+export const ABSTENTION_THRESHOLD = 0.15;
+/**
+ * Confidence-band cut-points for `matchQuality` (flair#744 confidence-band
+ * refinement — "breadcrumbs, labeled"). Recall shouldn't be binary
+ * confident-match / nothing: a weak-but-present match is valuable if the agent
+ * KNOWS it's weak. The band classifier (resources/trust-block.ts's
+ * `classifyMatchQuality`) labels each result's absolute `_semSimilarity` as
+ * strong / moderate / breadcrumb against these two floors plus the abstention
+ * floor below:
+ *
+ *   sim >= STRONG_BAND (0.55)                    → "strong"
+ *   MODERATE_BAND (0.35) <= sim < STRONG_BAND    → "moderate"
+ *   ABSTENTION_THRESHOLD (0.15) <= sim < 0.35    → "breadcrumb"
+ *   sim < ABSTENTION_THRESHOLD (present anyway,  → "breadcrumb" (weakest present
+ *     abstention off)                                band — NO 4th band)
+ *
+ * ─── SINGLE SOURCE OF TRUTH (Kern BINDING condition 1) ──────────────────────
+ * These two band floors live HERE, in the SAME module as ABSTENTION_THRESHOLD,
+ * so the band cut-points and the abstention floor are one source of truth and
+ * cannot drift. The classifier's breadcrumb floor is ABSTENTION_THRESHOLD
+ * ITSELF (imported, never a duplicate `0.15` literal) — the bottom of the
+ * breadcrumb band is exactly the top of abstention: below it, opt-in abstention
+ * returns "no memory covers this" instead. If recall-bench moves
+ * ABSTENTION_THRESHOLD, breadcrumb's floor moves with it, automatically.
+ *
+ * ─── CONSERVATIVE hand-set placeholders (same posture as ABSTENTION_THRESHOLD)
+ * 0.35 / 0.55 are reasonable hand-set cuts for cosine similarity on common
+ * embedding models, but the point is they're REPLACEABLE without an API change.
+ * The real cut-points come from recall-bench (which similarity band correlates
+ * with "the agent found this useful") — that calibration is a SEPARATE
+ * follow-up (see flair#744), exactly like promoting abstention to the default.
+ * The field and its API shape ship now; the numbers get tuned independently.
+ *
+ * GLOBAL constants, NEVER per-principal (Sherlock): the classifier takes exactly
+ * one numeric input and references no principal/tier — structurally guarded by
+ * test/unit/abstention-no-per-principal-tripwire.test.ts.
+ */
+export const MODERATE_BAND = 0.35;
+export const STRONG_BAND = 0.55;
+/**
+ * Pick the best absolute semantic similarity across a retrieval candidate pool.
+ *
+ * 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`
+ * 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).
+ *
+ * Returns null when NO candidate carries a `_semSimilarity` (no embedding-based
+ * match at all — e.g. a keyword-only degraded search, or an empty pool). Per
+ * `evaluateAbstention`, null ⇒ never abstain (conservative: a degraded recall
+ * that couldn't even judge confidence should return what it found, not a
+ * confident "nothing covers this").
+ *
+ * PURE and authority-free: reads a single numeric field off each candidate,
+ * never any principal / agentId / tier / scope. It cannot make the decision
+ * per-principal because it never sees a principal.
+ */
+export function bestSemanticSimilarity(candidates) {
+    let best = null;
+    for (const c of candidates) {
+        const s = c?._semSimilarity;
+        if (typeof s === "number" && Number.isFinite(s) && (best === null || s > best)) {
+            best = s;
+        }
+    }
+    return best;
+}
+/**
+ * The abstention decision. PURE, and its ONLY input is a single confidence
+ * number (or null) — there is deliberately no threshold parameter and no
+ * principal parameter, so the outcome cannot be varied per principal (Sherlock
+ * binding condition 2): the threshold is always the module-global
+ * ABSTENTION_THRESHOLD.
+ *
+ *   - bestScore === null  ⇒ never abstain (no embedding-based match to judge;
+ *                            conservative — return what was found).
+ *   - bestScore < floor   ⇒ abstain ("no memory covers this").
+ *   - bestScore >= floor  ⇒ do not abstain (return normal results).
+ */
+export function evaluateAbstention(bestScore) {
+    const threshold = ABSTENTION_THRESHOLD;
+    const abstained = bestScore !== null && bestScore < threshold;
+    return abstained
+        ? { abstained: true, bestScore, threshold, reason: "no memory above confidence threshold" }
+        : { abstained: false, bestScore, threshold };
+}

package/dist/resources/agent-auth.js

@@ -16,7 +16,7 @@
  * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
  */
 import { databases } from "@harperfast/harper";
-import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -56,15 +56,14 @@ async function getAdminAgents() {
 export async function isAdmin(agentId) {
     return (await getAdminAgents()).has(agentId);
 }
-const HEADER_RE = /^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/;
 async function doVerify(request) {
     const header = request?.headers?.get?.("authorization") ??
         request?.headers?.asObject?.authorization ??
         "";
-    const m = HEADER_RE.exec(header);
-    if (!m)
+    const parsed = parseTpsEd25519Header(header);
+    if (!parsed)
         return null;
-    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const { agentId, tsRaw, nonce, signatureB64 } = parsed;
     const ts = Number(tsRaw);
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)

package/dist/resources/auth-middleware.js

@@ -2,7 +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 { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
@@ -230,8 +230,8 @@ server.http(async (request, nextLayer) => {
         return nextLayer(request);
     }
     // ── Ed25519 agent auth ────────────────────────────────────────────────────
-    const m = header.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
-    if (!m) {
+    const parsed = parseTpsEd25519Header(header);
+    if (!parsed) {
         // For browser-accessible admin pages, emit `WWW-Authenticate: Basic` so
         // the browser shows a native auth dialog instead of a bare 401 page.
         // JSON API endpoints don't get this — they should keep the structured
@@ -260,7 +260,7 @@ server.http(async (request, nextLayer) => {
         catch { /* frozen headers — annotation on the request object still applies */ }
         return nextLayer(request);
     }
-    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const { agentId, tsRaw, nonce, signatureB64 } = parsed;
     const ts = Number(tsRaw);
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)

package/dist/resources/ed25519-auth.js

@@ -42,6 +42,43 @@ export { b64ToArrayBuffer };
  * stated "plugin-shaped, config via env" design intent.
  */
 export const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
+// ─── Auth header parsing (single shared implementation) ────────────────────
+//
+// One parser for the `Authorization: TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`
+// header, used by all 3 call sites (auth-middleware.ts, agent-auth.ts,
+// Presence.ts) so the grammar and its input bounds can't drift.
+/**
+ * Upper bound on the accepted Authorization header length. A well-formed
+ * TPS-Ed25519 header (`TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`) is a few hundred
+ * chars at most; anything materially larger is malformed. The header is
+ * untrusted client input, so we cap its length before running the regex,
+ * keeping parse cost bounded regardless of the input's shape.
+ */
+export const MAX_AUTH_HEADER_LEN = 4096;
+/**
+ * TPS-Ed25519 auth header grammar.
+ *
+ * The two colon-delimited text captures use `[^:\s]+` (not `[^:]+`) so they are
+ * disjoint from the preceding `\s+`: with no character shared between the two
+ * adjacent quantifiers there is exactly one way to split any input, so matching
+ * is linear-time on every input (including long, degenerate ones). A real
+ * agentId / nonce / signature never contains whitespace, so excluding it is
+ * behavior-preserving for well-formed headers.
+ */
+export const TPS_ED25519_HEADER_RE = /^TPS-Ed25519\s+([^:\s]+):(\d+):([^:\s]+):(.+)$/;
+/**
+ * Parse a TPS-Ed25519 `Authorization` header value into its fields, or return
+ * null if it is over `MAX_AUTH_HEADER_LEN` or doesn't match the grammar.
+ * Callers treat null exactly as a header that carries no valid agent auth.
+ */
+export function parseTpsEd25519Header(header) {
+    if (!header || header.length > MAX_AUTH_HEADER_LEN)
+        return null;
+    const m = TPS_ED25519_HEADER_RE.exec(header);
+    if (!m)
+        return null;
+    return { agentId: m[1], tsRaw: m[2], nonce: m[3], signatureB64: m[4] };
+}
 // ─── Replay guard (single shared instance) ─────────────────────────────────
 //
 // nonceSeen is the ONE module-level singleton — the whole point of this

package/dist/resources/embeddings-boot.js

@@ -87,6 +87,41 @@
 import { resolveModelsDir } from "./embeddings-provider.js";
 const LOGICAL_NAME = "default";
 const MODEL_NAME = "nomic-embed-text";
+/**
+ * Pooling declaration (HFE 0.5.0+, harper-fabric-embeddings' `init()`
+ * `pooling` option). Verification, not override: the native addon has no
+ * pooling knob of its own — llama.cpp always pools by whatever the GGUF's
+ * own `<arch>.pooling_type` metadata says. Declaring the expectation makes
+ * HFE assert it at init and fail loudly on absent/mismatched metadata,
+ * instead of a metadata-less or mismatched conversion silently pooling the
+ * wrong way (see node_modules/harper-fabric-embeddings/README.md's `init()`
+ * table for the exact contract this PR bumps to).
+ *
+ * "mean" is nomic-embed-text-v1.5's actual pooling type — NOT assumed from
+ * the model's reputation, directly confirmed against the shipped GGUF:
+ * `node_modules/.bin/node-llama-cpp inspect gguf
+ * ~/.flair/data/models/nomic-embed-text-v1.5.Q4_K_M.gguf` reports
+ * `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
+ * `enum llama_pooling_type` maps 1 -> `LLAMA_POOLING_TYPE_MEAN` (0 = none,
+ * 1 = mean, 2 = cls, 3 = last, 4 = rank). nomic-embed-text is a
+ * NomicBertModel architecture, not Qwen3 (last-token) — flair registers no
+ * Qwen3-class embedding model today (the Qwen3-Reranker-0.6B in
+ * resources/rerank-provider.ts is a SEPARATE code path that calls
+ * node-llama-cpp directly for generative yes/no scoring, never goes through
+ * HFE's register()/init(), and has no embedding-pooling context at all — see
+ * that file's header). If a Qwen3-class (last-token-pooling) embedding model
+ * is ever registered here, it must declare `pooling: "last"`, not "mean".
+ *
+ * Applies to the bench-only `modelPath` override too (`benchModelPathOverride()`
+ * below): `FLAIR_RECALL_HARNESS_MODEL_PATH` lets an operator point this
+ * registration at an arbitrary GGUF for a Q4/Q8 bakeoff, and this constant
+ * assumes whatever file lands there is still nomic-family (mean-pooling) —
+ * true for every bakeoff run to date (same base model, different quant).
+ * HFE 0.5.0's verification is exactly the safety net that turns "someone
+ * points --model-file at a non-nomic, non-mean-pooling GGUF" into a loud
+ * boot-time failure instead of a silently-wrong pooling pass.
+ */
+const EMBEDDING_POOLING = "mean";
 /**
  * BENCH-ONLY escape hatch — NOT a production feature flag, never documented
  * as an operator setting, and never read anywhere else in this codebase.
@@ -131,7 +166,9 @@ export async function registerEmbeddingsBackend() {
         await register({
             logicalName: LOGICAL_NAME,
             kind: "embedding",
-            config: modelPath ? { modelPath } : { modelName: MODEL_NAME, modelsDir: resolveModelsDir() },
+            config: modelPath
+                ? { modelPath, pooling: EMBEDDING_POOLING }
+                : { modelName: MODEL_NAME, modelsDir: resolveModelsDir(), pooling: EMBEDDING_POOLING },
         });
     }
     catch (err) {

package/dist/resources/mcp-tools.js

@@ -114,7 +114,16 @@ async function unwrap(value) {
 async function memorySearch(agent, args) {
     const Cls = await handler("SemanticSearch");
     const h = new Cls(undefined, delegationContext(agent));
-    return unwrap(await h.post({ q: args?.query, limit: args?.limit ?? 5 }));
+    const body = { q: args?.query, limit: args?.limit ?? 5 };
+    // flair#744 slice 1 — opt-in inline trust block per result. Forwarded ONLY
+    // when requested so a plain search delegates a byte-identical body.
+    if (args?.includeTrust === true)
+        body.includeTrust = true;
+    // flair#744 slice 2 — opt-in abstention verdict. Forwarded ONLY when
+    // requested so a plain search delegates a byte-identical body.
+    if (args?.abstain === true)
+        body.abstain = true;
+    return unwrap(await h.post(body));
 }
 async function memoryStore(agent, args) {
     const Cls = await handler("Memory");
@@ -136,6 +145,13 @@ async function memoryStore(agent, args) {
     // Omitted entirely when the token carried no client_id.
     if (agent.clientId)
         body.claimedClient = agent.clientId;
+    // flair#744 slice A: citation-on-write — forward the optional
+    // usedMemoryIds array only when the caller actually supplied it, so an
+    // omitted citation list delegates a byte-identical body (Memory.post()
+    // consumes-and-strips this before the row is written, then credits each
+    // id post-commit through the shared usage ledger).
+    if (Array.isArray(args?.usedMemoryIds))
+        body.usedMemoryIds = args.usedMemoryIds;
     return unwrap(await h.post(body));
 }
 /**
@@ -201,7 +217,11 @@ async function memoryUpdate(agent, args) {
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
     const h = new Cls(undefined, delegationContext(agent));
-    return unwrap(await h.get(args?.id));
+    // flair#744 slice 1 — opt-in inline trust block on the returned record.
+    // Pass the opts arg ONLY when requested so a plain get() call is unchanged.
+    return unwrap(args?.includeTrust === true
+        ? await h.get(args?.id, { includeTrust: true })
+        : await h.get(args?.id));
 }
 async function memoryDelete(agent, args) {
     const Cls = await handler("Memory");
@@ -211,7 +231,7 @@ async function memoryDelete(agent, args) {
 async function bootstrap(agent, args) {
     const Cls = await handler("BootstrapMemories");
     const h = new Cls(undefined, delegationContext(agent));
-    return unwrap(await h.post({
+    const body = {
         agentId: agent.agentId,
         maxTokens: args?.maxTokens ?? 4000,
         currentTask: args?.currentTask,
@@ -219,7 +239,16 @@ async function bootstrap(agent, args) {
         surface: args?.surface,
         subjects: args?.subjects,
         entities: args?.entities,
-    }));
+    };
+    // flair#744 slice 1 — opt-in per-memory trust block array. Forwarded ONLY
+    // when requested so a plain bootstrap delegates a byte-identical body.
+    if (args?.includeTrust === true)
+        body.includeTrust = true;
+    // flair#744 slice 2 — opt-in task-relevance abstention verdict. Forwarded
+    // ONLY when requested so a plain bootstrap delegates a byte-identical body.
+    if (args?.abstain === true)
+        body.abstain = true;
+    return unwrap(await h.post(body));
 }
 async function soulSet(agent, args) {
     const Cls = await handler("Soul");
@@ -345,6 +374,8 @@ export const TOOLS = {
                 properties: {
                     query: { type: "string", description: "Search query — natural language, semantic matching" },
                     limit: { type: "number", description: "Max results (default 5)" },
+                    includeTrust: { type: "boolean", description: "Attach a per-result trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
+                    abstain: { type: "boolean", description: "Opt into first-class abstention: when the best match is below a global confidence threshold, return { abstained: true, reason, bestScore } with no weak matches instead of the N weakest results. Default false." },
                 },
                 required: ["query"],
             },
@@ -362,6 +393,7 @@ export const TOOLS = {
                     type: { type: "string", enum: ["session", "lesson", "decision", "preference", "fact", "goal"], description: "Memory type (default session)" },
                     durability: { type: "string", enum: ["permanent", "persistent", "standard", "ephemeral"], description: "permanent > persistent > standard > ephemeral (default standard)" },
                     tags: { type: "array", items: { type: "string" }, description: "Tag strings" },
+                    usedMemoryIds: { type: "array", items: { type: "string" }, description: "IDs of memories that informed this write (citation-on-write). Credited via the same deduped usage ledger as record_usage. Optional." },
                 },
                 required: ["content"],
             },
@@ -393,7 +425,10 @@ export const TOOLS = {
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
-                properties: { id: { type: "string", description: "Memory ID" } },
+                properties: {
+                    id: { type: "string", description: "Memory ID" },
+                    includeTrust: { type: "boolean", description: "Attach a trust-evidence block (provenance, author, usage, freshness, supersession) to the record. Default false." },
+                },
                 required: ["id"],
             },
         },
@@ -430,6 +465,8 @@ export const TOOLS = {
                         items: { type: "string" },
                         description: "Your declared attention-plane vocabulary strings (e.g. \"issue:owner/repo#123\") for collision surfacing's 'Others in the room' block — teammates with overlapping active work. Falls back to your own most-recent workspace-state entities when omitted.",
                     },
+                    includeTrust: { type: "boolean", description: "Also return a `trust` array with a per-included-memory trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
+                    abstain: { type: "boolean", description: "Opt into a task-relevance abstention verdict: also return an `abstention` object ({ abstained, bestScore, threshold }) reporting whether any memory covered `currentTask` above a global confidence threshold. Default false." },
                 },
             },
         },

package/dist/resources/semantic-retrieval-core.js

@@ -58,13 +58,18 @@ function distanceToSimilarity(distance) {
 // m.content`, so dropping it here would silently regress bootstrap's
 // "Others in the room" surface even though SemanticSearch never asserts on
 // its absence.
-const DEFAULT_SELECT = ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
+// Exported so the opt-in trust-block path (flair#744 slice 1) can widen it with
+// `provenance` ONLY when a caller requests the block — the default projection
+// deliberately omits `provenance` (it's only needed for the trust block), and
+// adding it unconditionally would change every existing recall response's
+// bytes. See SemanticSearch.ts / MemoryBootstrap.ts's `includeTrust` handling.
+export const DEFAULT_SELECT = ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
     "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "usageCount", "lastRetrieved",
     "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
     "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject", "summary",
     "validFrom", "validTo", "_safetyFlags"];
 export async function retrieveCandidates(params) {
-    const { queryEmbedding: qEmb, q, conditions, limit, select = DEFAULT_SELECT, includeSuperseded = false, scoring = "raw", temporalBoost = 1.0, sinceDate = null, asOf, minScore = 0, agentId, isAllowed, hybrid, ctx, } = params;
+    const { queryEmbedding: qEmb, q, conditions, limit, select = DEFAULT_SELECT, includeSuperseded = false, scoring = "raw", temporalBoost = 1.0, sinceDate = null, asOf, minScore = 0, agentId, isAllowed, hybrid, ctx, withSemSimilarity = false, } = params;
     const passesAllowed = (record) => !isAllowed || isAllowed(record);
     const hnswSelect = [...select, "$distance"];
     const results = [];
@@ -79,6 +84,11 @@ export async function retrieveCandidates(params) {
         // ── (a) Semantic candidate records (best-first) ──────────────────────
         const semRecords = [];
         const semIds = [];
+        // flair#744 slice 2: absolute cosine similarity per semantic candidate
+        // (from the HNSW `$distance`), captured HERE before `$distance` is stripped
+        // downstream — the confidence signal the abstention decision reads (only
+        // when `withSemSimilarity`; empty/unused otherwise).
+        const semSimById = new Map();
         if (qEmb) {
             const semQuery = {
                 sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
@@ -108,6 +118,9 @@ export async function retrieveCandidates(params) {
                     continue;
                 if (!passesAllowed(record))
                     continue;
+                if (withSemSimilarity && record.$distance !== undefined) {
+                    semSimById.set(record.id, distanceToSimilarity(record.$distance));
+                }
                 semRecords.push(record);
                 semIds.push(record.id);
             }
@@ -177,12 +190,17 @@ export async function retrieveCandidates(params) {
                     finalScore *= temporalBoost;
                 const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
                 const source = record.agentId !== agentId ? record.agentId : undefined;
+                // flair#744 slice 2: absolute cosine confidence for the abstention
+                // decision — only for records that had a semantic (HNSW) candidate; a
+                // BM25-lexical-only match carries no cosine and contributes none.
+                const semSim = withSemSimilarity ? semSimById.get(id) : 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,
+                    ...(semSim !== undefined ? { _semSimilarity: semSim } : {}),
                 });
             }
         }
@@ -241,12 +259,16 @@ export async function retrieveCandidates(params) {
             const { $distance, ...rest } = record;
             const isFlagged = rest._safetyFlags && Array.isArray(rest._safetyFlags) && rest._safetyFlags.length > 0;
             const source = record.agentId !== agentId ? record.agentId : undefined;
+            // flair#744 slice 2: the absolute cosine (`semanticScore`, pre keyword
+            // bump) is the abstention confidence signal on this legacy/bootstrap
+            // (HNSW-leg-only) path.
             results.push({
                 ...rest,
                 content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
+                ...(withSemSimilarity ? { _semSimilarity: semanticScore } : {}),
             });
         }
     }