@tpsdev-ai/flair 0.24.0 → 0.25.1

package/dist/resources/SemanticSearch.js

@@ -17,7 +17,9 @@ import { hybridEnabled } from "./bm25.js";
 // extraction) — MemoryBootstrap.ts calls the SAME core bare, without
 // tripping this file's rate-limit/reranker/hit-tracking side effects. See
 // resources/semantic-retrieval-core.ts's module doc for the full boundary.
-import { retrieveCandidates } from "./semantic-retrieval-core.js";
+import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
+import { attachTrust } from "./trust-block.js";
+import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
 // 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;
@@ -60,7 +62,7 @@ export class SemanticSearch extends Resource {
         // recall-harness (test/bench/recall-harness/run.ts) and `recall-eval.mjs`
         // before reconsidering this default if the compositeScore formula or
         // corpus changes.
-        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf } = data || {};
+        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, abstain = false } = data || {};
         // Authenticated identity lives on the Harper Resource context (getContext().request).
         // `this.request` is NOT populated on Harper v5 Resources — prior reads here
         // silently returned undefined and the defense-in-depth scope check below
@@ -216,7 +218,41 @@ export class SemanticSearch extends Resource {
             isAllowed: scope?.isAllowed,
             hybrid,
             ctx,
+            // flair#744 slice 1: the trust block needs `provenance`, which the
+            // default projection omits. Widen the select ONLY when the caller opts
+            // in — passing undefined otherwise keeps the default (no `provenance`)
+            // so a non-trust recall response stays byte-identical.
+            select: includeTrust ? [...DEFAULT_SELECT, "provenance"] : undefined,
+            // flair#744 slice 2 + confidence-band refinement: attach the absolute
+            // per-result cosine confidence when the caller opts into abstention OR
+            // the trust block — abstention reads the best of it for its verdict, and
+            // the trust block classifies each result's into a `matchQuality` band
+            // (Kern BINDING condition 2: matchQuality needs `_semSimilarity`, so
+            // includeTrust must also turn this on). Neither flag ⇒ result objects stay
+            // byte-identical (no `_semSimilarity` attached).
+            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
+        // (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.
+        let abstention = null;
+        if (abstain) {
+            abstention = evaluateAbstention(bestSemanticSimilarity(filteredResults));
+            if (abstention.abstained) {
+                return {
+                    abstained: true,
+                    reason: abstention.reason,
+                    bestScore: abstention.bestScore,
+                    threshold: abstention.threshold,
+                    results: [],
+                };
+            }
+        }
         // ─── 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
@@ -248,8 +284,40 @@ export class SemanticSearch extends Resource {
                 lastRetrieved: now,
             }).catch(() => { });
         }
+        // flair#744 slice 1 — opt-in inline trust-evidence block. Assembled HERE,
+        // in the response tail, strictly AFTER read-scope resolution
+        // (retrieveCandidates + scope.isAllowed already ran) and purely for the
+        // response — it never feeds back into any authority/scope/attribution/dedup
+        // decision (the #735-spirit zero-authority invariant; structurally guarded
+        // by test/unit/trust-block-zero-authority-tripwire.test.ts). Default OFF ⇒
+        // `results` is the untouched `topResults`, byte-identical to pre-slice-1.
+        //
+        // Order matters (confidence-band refinement): attachTrust must run BEFORE
+        // the `_semSimilarity` strip below, because buildTrustBlock reads that field
+        // off the record to classify `matchQuality`. attachTrust returns a shallow
+        // copy carrying `trust` (and still-present `_semSimilarity`); the strip then
+        // drops the internal field from the copy.
+        const trusted = includeTrust ? topResults.map((r) => attachTrust(r, true)) : topResults;
+        // flair#744 slice 2 + refinement: strip the internal `_semSimilarity`
+        // confidence field from the consumer-facing results — it exists ONLY to feed
+        // the abstention decision and the matchQuality classification, never the
+        // response shape. Attached whenever abstain OR includeTrust turned
+        // withSemSimilarity on, so strip in both cases. A no-op (and byte-identical)
+        // when neither flag is set (the field was never attached).
+        const results = (abstain || includeTrust)
+            ? trusted.map(({ _semSimilarity, ...r }) => r)
+            : trusted;
         // Surface degradation warning when semantic search was unavailable
-        const response = { results: topResults };
+        const response = { results };
+        // flair#744 slice 2: in opt-in abstain mode that did NOT abstain, carry the
+        // (negative) verdict so a consumer building against the abstention shape
+        // always reads a stable `abstained`/`bestScore`/`threshold`. Absent when
+        // abstain is off ⇒ byte-identical to pre-slice-2.
+        if (abstention) {
+            response.abstained = abstention.abstained;
+            response.bestScore = abstention.bestScore;
+            response.threshold = abstention.threshold;
+        }
         if (!qEmb && q && getMode() === "none") {
             response._warning = "semantic search unavailable — results are keyword-only";
         }

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/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 } : {}),
             });
         }
     }

package/dist/resources/trust-block.js

@@ -0,0 +1,187 @@
+/**
+ * trust-block.ts — the opt-in, inline trust-evidence block surfaced on recall
+ * results (flair#744 slice 1: "surface what we already record at the point of
+ * decision").
+ *
+ * ─── What this is ────────────────────────────────────────────────────────────
+ * A PURE, Harper-free assembler: `buildTrustBlock(record)` maps a single
+ * Memory record's ALREADY-STORED fields into a compact, self-contained trust
+ * block that `search` (SemanticSearch), `get` (Memory.get), and `bootstrap`
+ * (BootstrapMemories) attach to each result WHEN THE CALLER OPTS IN. No new
+ * computation, no cross-record lookups, no DB access — every field below is
+ * read straight off the record the recall path already resolved. That is the
+ * whole point of slice 1: the memory layer already records per-fact trust
+ * evidence at write time; this surfaces it at read time, where the consuming
+ * agent actually decides what to repeat.
+ *
+ * ─── The zero-authority invariant (flair#744 Sherlock condition 2 / #735) ────
+ * The trust block INFORMS THE READER ONLY. It is assembled AFTER read-scope
+ * resolution, purely for the response, and MUST NEVER enter an authority /
+ * scope / attribution / dedup decision anywhere — the same discipline as the
+ * `claimed.*` zero-authority guard (flair#735). Two things keep that true:
+ *   1. This module is pure and side-effect-free: buildTrustBlock NEVER mutates
+ *      its input record (it only reads), so assembling a block can never alter
+ *      a record a later decision reads.
+ *   2. No authority-decision module imports it. That is structurally enforced
+ *      by test/unit/trust-block-zero-authority-tripwire.test.ts (the #735-style
+ *      source scan): record-type-kit.ts, memory-read-scope.ts, Memory.ts's
+ *      dedup gates, RecordUsage.ts, mcp-handler.ts, and the retrieval/scoping
+ *      core (semantic-retrieval-core.ts) never reference the trust block — it
+ *      is assembled strictly DOWNSTREAM of scope resolution, in the response
+ *      tail of each recall wrapper.
+ *
+ * ─── `claimed.*` is surfaced as a BOOLEAN only ──────────────────────────────
+ * `hasClaimedProvenance` reports only WHETHER the record carries a self-
+ * reported `claimed` sub-object — never its content. Raw `claimed.model` /
+ * `claimed.client` values are self-reported and unverified (resources/
+ * provenance.ts); exposing them as authoritative trust evidence would defeat
+ * the verified-vs-claimed distinction the block exists to draw. The advisory
+ * "there is a self-report here" bit is enough for the reader to weight it.
+ *
+ * ─── Tier is DEFERRED to a later slice (flair#744 Sherlock condition 1) ─────
+ * The block deliberately does NOT carry a derived trust `tier`. A tier is not
+ * a field on the Memory record — it lives on the AUTHOR's Agent/OAuthClient
+ * principal record (`defaultTrustTier`), so surfacing it would require a
+ * per-author lookup on the hot recall path (exactly the read-path cost the
+ * flair#744 design round ruled out) AND the scope-gate Sherlock's condition 1
+ * mandates ("include tier only when reader.scope == author.scope"). That
+ * scope-gate needs an org/scope boundary primitive that does not yet exist in
+ * flair's single-tenant "open-within-org" read model. Both are more than
+ * trivial for slice 1, so per the spec's explicit allowance the tier field is
+ * deferred whole — the scope-gate ships WITH it, when it ships. Everything
+ * else in the block (provenance, author principal, usage, freshness,
+ * supersession) is on the Memory record itself and ships now.
+ *
+ * ─── `matchQuality` confidence band (flair#744 refinement) ──────────────────
+ * When the recall path attached an absolute semantic similarity to the result
+ * (`_semSimilarity`, cosine in [0,1] — attached only on the retrieval surface,
+ * when the caller opts into the block or into abstention), the block labels it
+ * with a confidence band — strong / moderate / breadcrumb — so a weak-but-
+ * present match is TAKEN FOR WHAT IT IS, not mistaken for a confident one (the
+ * hallucination risk is undifferentiated weak matches, not weak matches per se).
+ * Derived PURELY from that one number against the global band cut-points in
+ * resources/abstention.ts (single source of truth with the abstention floor —
+ * see classifyMatchQuality). When there is no similarity to judge (a by-id
+ * `get`, or a keyword-only degraded search — no `_semSimilarity`), the band is
+ * `null`: an honest "we couldn't classify this one", never a false label.
+ */
+import { ABSTENTION_THRESHOLD, MODERATE_BAND, STRONG_BAND } from "./abstention.js";
+const MS_PER_DAY = 86_400_000;
+/**
+ * Classify a result's absolute semantic similarity (`_semSimilarity`, cosine in
+ * [0,1]) into a confidence band. PURE: its ONLY input is that one number — no
+ * principal / agentId / tier / scope — so the band is GLOBAL and can never be
+ * varied per principal (Sherlock; structurally guarded by
+ * test/unit/abstention-no-per-principal-tripwire.test.ts, same spine as the
+ * abstention decision).
+ *
+ *   sim >= STRONG_BAND            → "strong"
+ *   MODERATE_BAND <= sim < STRONG → "moderate"
+ *   ABSTENTION_THRESHOLD <= sim   → "breadcrumb"  (bottom of breadcrumb IS the
+ *                                                   abstention floor — one
+ *                                                   shared constant, no dup)
+ *   sim < ABSTENTION_THRESHOLD    → "breadcrumb"  (a result present below the
+ *                                                   abstention floor — abstention
+ *                                                   off, or it slipped in — is
+ *                                                   still the WEAKEST present
+ *                                                   band; there is NO 4th band)
+ *   not a finite number (null/undefined/NaN) → null  (no signal to classify;
+ *                                                      never a false label)
+ *
+ * The breadcrumb floor references ABSTENTION_THRESHOLD directly (Kern BINDING
+ * condition 1): the band cut-points and the abstention floor are one source of
+ * truth (resources/abstention.ts) and cannot drift — if recall-bench moves the
+ * abstention floor, breadcrumb's floor moves with it.
+ */
+export function classifyMatchQuality(semSimilarity) {
+    if (typeof semSimilarity !== "number" || !Number.isFinite(semSimilarity))
+        return null;
+    if (semSimilarity >= STRONG_BAND)
+        return "strong";
+    if (semSimilarity >= MODERATE_BAND)
+        return "moderate";
+    if (semSimilarity >= ABSTENTION_THRESHOLD)
+        return "breadcrumb";
+    // Present below the abstention floor (abstention off, or a straggler): still
+    // the weakest present band — breadcrumb, never a 4th band.
+    return "breadcrumb";
+}
+function parseTime(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return NaN;
+    return Date.parse(value);
+}
+/**
+ * Assemble the trust block for one Memory record. Pure: reads only, NEVER
+ * mutates `record`. `now` is injectable for deterministic tests (defaults to
+ * the current wall clock).
+ */
+export function buildTrustBlock(record, now = Date.now()) {
+    // ── Provenance (verified vs claimed) ──────────────────────────────────────
+    let verifiedAuthor = null;
+    let verifiedAt = null;
+    let hasClaimedProvenance = false;
+    if (typeof record.provenance === "string" && record.provenance.length > 0) {
+        try {
+            const p = JSON.parse(record.provenance);
+            if (p && typeof p === "object") {
+                if (p.verified && typeof p.verified === "object") {
+                    verifiedAuthor = typeof p.verified.agentId === "string" ? p.verified.agentId : null;
+                    verifiedAt = typeof p.verified.timestamp === "string" ? p.verified.timestamp : null;
+                }
+                // Boolean only — the self-reported content is deliberately NOT surfaced.
+                hasClaimedProvenance = p.claimed != null && typeof p.claimed === "object";
+            }
+        }
+        catch {
+            // Malformed provenance → treated as unattributed, never throws.
+        }
+    }
+    // ── Freshness / validity ──────────────────────────────────────────────────
+    const validFrom = typeof record.validFrom === "string" ? record.validFrom : null;
+    const validTo = typeof record.validTo === "string" ? record.validTo : null;
+    const createdAt = typeof record.createdAt === "string" ? record.createdAt : null;
+    const validToMs = parseTime(validTo);
+    const validFromMs = parseTime(validFrom);
+    let validityStatus = "valid";
+    if (Number.isFinite(validToMs) && validToMs <= now) {
+        validityStatus = "expired";
+    }
+    else if (Number.isFinite(validFromMs) && validFromMs > now) {
+        validityStatus = "future";
+    }
+    const createdMs = parseTime(createdAt);
+    const ageDays = Number.isFinite(createdMs)
+        ? Math.max(0, Math.floor((now - createdMs) / MS_PER_DAY))
+        : null;
+    return {
+        author: typeof record.agentId === "string" ? record.agentId : null,
+        provenanceStatus: verifiedAuthor ? "verified" : "unattributed",
+        verifiedAuthor,
+        verifiedAt,
+        hasClaimedProvenance,
+        usageCount: typeof record.usageCount === "number" ? record.usageCount : null,
+        validityStatus,
+        validFrom,
+        validTo,
+        createdAt,
+        ageDays,
+        supersedes: typeof record.supersedes === "string" ? record.supersedes : null,
+        // flair#744 refinement — confidence band from the result's absolute
+        // similarity (null when there is no signal to judge). Pure, global,
+        // score-only: classifyMatchQuality sees ONLY the number.
+        matchQuality: classifyMatchQuality(record._semSimilarity),
+    };
+}
+/**
+ * Opt-in attach: the single primitive `search`/`get` use to layer the trust
+ * block onto a result. `includeTrust === false` (the default) returns the
+ * EXACT SAME record reference untouched — the clean-migration guarantee that a
+ * consumer who doesn't request the block sees a byte-identical response. When
+ * true, returns a shallow copy with `trust` added (never mutates the input).
+ */
+export function attachTrust(record, includeTrust, now) {
+    if (!includeTrust)
+        return record;
+    return { ...record, trust: buildTrustBlock(record, now) };
+}