@tpsdev-ai/flair 0.24.0 → 0.25.0

package/dist/resources/Memory.js

@@ -9,6 +9,24 @@ import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
+import { attachTrust } from "./trust-block.js";
+import { recordCitations } from "./usage-recording.js";
+/**
+ * flair#744 slice 1 — read the opt-in `includeTrust` flag for a by-id get.
+ * Two entry shapes: an in-process caller (resources/mcp-tools.ts's memory_get)
+ * passes it explicitly via the `opts` arg; an HTTP `GET /Memory/<id>?includeTrust=true`
+ * carries it as a query param on the RequestTarget. Defensive across the
+ * RequestTarget/URLSearchParams shapes Harper may hand us; anything other than
+ * a literal "true" reads as off, so the default response stays byte-identical.
+ */
+function wantsTrust(target, opts) {
+    if (opts?.includeTrust === true)
+        return true;
+    const raw = target?.get?.("includeTrust") ??
+        target?.searchParams?.get?.("includeTrust") ??
+        undefined;
+    return raw === "true" || raw === true;
+}
 /**
  * Owner ids a non-admin agent may READ (resolveAllowedOwners) live in
  * ./memory-read-scope.ts — still exported/used elsewhere (admin tooling).
@@ -439,7 +457,7 @@ export class Memory extends databases.flair.Memory {
      * with Memory's own "open-within-org" read-scope resolver above — same
      * dispatch shape Relationship.ts/WorkspaceState.ts's get() overrides use.
      */
-    async get(target) {
+    async get(target, opts) {
         // Collection / query reads — the `GET /Memory/?<query>` form and the bare
         // collection — arrive as a RequestTarget with `isCollection === true`, and
         // are governed by search() (same owner/grant scoping). Only a genuine by-id
@@ -451,11 +469,24 @@ export class Memory extends databases.flair.Memory {
         // get (RequestTarget with isCollection false, or a bare id) falls through.
         // makeByIdReadGate re-applies this same guard internally (delegating to
         // this.search via `.call(this, ...)`) — kept here too as documentation of
-        // the invariant at the call site, harmless no-op double-check.
+        // the invariant at the call site, harmless no-op double-check. The trust
+        // block (flair#744) is NOT attached on the collection path — that routes to
+        // search(), which is out of this slice's by-id `get` surface.
         if (!target || (typeof target === "object" && target.isCollection)) {
             return this.search(target);
         }
-        return memoryByIdReadGate.call(this, target, (t) => super.get(t));
+        const result = await memoryByIdReadGate.call(this, target, (t) => super.get(t));
+        // flair#744 slice 1 — opt-in inline trust-evidence block, attached ONLY to
+        // a genuine by-id record (never a NOT_FOUND `Response`, never null), and
+        // ONLY after the ownership/read-scope gate above has already resolved. The
+        // block informs the reader; it never re-enters an authority decision
+        // (#735-spirit zero-authority invariant). Default OFF ⇒ the record is
+        // returned untouched (attachTrust returns the same reference) ⇒
+        // byte-identical to pre-slice-1.
+        if (result && typeof result === "object" && !(result instanceof Response) && typeof result.agentId === "string") {
+            return attachTrust(result, wantsTrust(target, opts));
+        }
+        return result;
     }
     /**
      * Override search() to scope collection GETs by authenticated agent.
@@ -538,6 +569,16 @@ export class Memory extends databases.flair.Memory {
             if (attr.denied)
                 return attr.denied;
         }
+        // flair#744 slice A: citation-on-write — consume-and-strip, same
+        // discipline as `claimedClient` below. Pull the optional
+        // `usedMemoryIds` off the write body now, BEFORE anything else touches
+        // `content`, so it is NEVER persisted on the Memory record itself.
+        // Recording happens POST-COMMIT, only when this was present (see the
+        // failure-isolated recordCitations() call near the return below) —
+        // omitted ⇒ `undefined` ⇒ zero new calls, byte-identical behavior.
+        const usedMemoryIds = content?.usedMemoryIds;
+        if (content && typeof content === "object")
+            delete content.usedMemoryIds;
         content.durability ||= "standard";
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
@@ -649,6 +690,20 @@ export class Memory extends databases.flair.Memory {
         // Now the safe failure state is two active records (recoverable), never
         // a lost write — and the failure is logged, never silently swallowed.
         await closeSupersededIfNeeded(ctx, content, "post");
+        // flair#744 slice A: citation-on-write — POST-COMMIT, fully
+        // failure-isolated. The write above already succeeded and `result` is
+        // final; crediting each cited memory through the shared usage ledger
+        // (same path as POST /RecordUsage) must never affect this response —
+        // any failure here is logged server-side and swallowed, never surfaced
+        // to the caller, never rolls back or retries the write.
+        if (usedMemoryIds !== undefined) {
+            try {
+                await recordCitations(ctx, auth, usedMemoryIds, new Date().toISOString());
+            }
+            catch (err) {
+                console.error("Memory.post: citation recording failed (write already committed)", err);
+            }
+        }
         return buildWriteResponse(content, result, dedupMatch);
     }
     async put(content) {
@@ -690,6 +745,13 @@ export class Memory extends databases.flair.Memory {
             if (attr.denied)
                 return attr.denied;
         }
+        // flair#744 slice A: citation-on-write — same consume-and-strip
+        // discipline as post() above. Strip BEFORE anything else touches
+        // `content` so it is never persisted on the row; recorded post-commit
+        // below only when present.
+        const usedMemoryIds = content?.usedMemoryIds;
+        if (content && typeof content === "object")
+            delete content.usedMemoryIds;
         const now = new Date().toISOString();
         content.updatedAt = now;
         // Set defaults that post() sets — put() is also used for new records via CLI
@@ -821,6 +883,16 @@ export class Memory extends databases.flair.Memory {
         const result = await super.put(content);
         // ── THEN close the superseded record (see post()) ───────────────────────
         await closeSupersededIfNeeded(ctx, content, "put");
+        // flair#744 slice A: citation-on-write — POST-COMMIT, fully
+        // failure-isolated (see post()'s identical comment above).
+        if (usedMemoryIds !== undefined) {
+            try {
+                await recordCitations(ctx, auth, usedMemoryIds, new Date().toISOString());
+            }
+            catch (err) {
+                console.error("Memory.put: citation recording failed (write already committed)", err);
+            }
+        }
         return buildWriteResponse(content, result, dedupMatch);
     }
     async delete(id) {

package/dist/resources/MemoryBootstrap.js

@@ -14,7 +14,9 @@ import { buildCollisionEntries, buildEntityMatchCondition, freshPresenceByAgent,
 // bootstrap call never trips SemanticSearch's rate-limit/reranker/
 // retrievalCount 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 { buildTrustBlock } from "./trust-block.js";
+import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
 /**
  * POST /MemoryBootstrap
  *
@@ -141,6 +143,8 @@ export class BootstrapMemories extends Resource {
         const { agentId: bodyAgentId, currentTask, maxTokens = 4000, includeSoul = true, since, channel, // e.g., "discord", "tps-mail", "claude-code"
         surface, // e.g., "tps-build", "tps-review", "cli-session"
         subjects, // e.g., ["flair", "auth"] — entities to preload context for
+        includeTrust = false, // flair#744 slice 1 — opt-in per-memory trust block
+        abstain = false, // flair#744 slice 2 — opt-in task-relevance abstention
          } = data || {};
         // Authenticated identity lives on getContext().request — `this.request` is
         // NOT populated on Harper v5 Resources. Reading it returned undefined and
@@ -348,8 +352,28 @@ export class BootstrapMemories extends Resource {
         memoriesAvailable = ownMemoriesAvailable;
         // Fields every own-scoped lifecycle slice below needs — explicit (no raw
         // `embedding`), matching the "select, no raw embedding" pushdown
-        // requirement.
-        const OWN_SELECT = ["id", "agentId", "content", "durability", "createdAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags"];
+        // requirement. flair#744 slice 1: when the caller opts into the per-memory
+        // trust block, widen the projection with the extra stored fields the block
+        // reads (`provenance`, `usageCount`, `validFrom`) — additive, and only when
+        // requested, so a non-trust bootstrap fetches (and returns) exactly what it
+        // did before. These records are never returned raw when the block is off,
+        // so widening the select cannot change the off-path response bytes.
+        const OWN_SELECT = includeTrust
+            ? ["id", "agentId", "content", "durability", "createdAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags", "provenance", "usageCount", "validFrom"]
+            : ["id", "agentId", "content", "durability", "createdAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags"];
+        // flair#744 slice 1 — the Memory records that became visible lines in the
+        // memory-bearing sections (permanent/recent/predicted/relevant/teammate),
+        // collected as they're added so the opt-in `trust` array below can carry a
+        // self-contained block per included memory. Stays empty (and unused) when
+        // includeTrust is off.
+        const includedTrustMemories = [];
+        // flair#744 slice 2 — the best absolute semantic similarity seen while
+        // scoring the task-relevant candidate pool (section 4). Drives the opt-in
+        // abstention verdict on the *task-relevance* surface only (bootstrap always
+        // returns identity/permanent/recent regardless — abstention is about "does
+        // any memory cover your current task", not the whole session load). Stays
+        // null when there's no currentTask / no embedding ⇒ never abstains.
+        let taskBestSimilarity = null;
         // --- 2. Permanent memories (always included, highest priority) ---
         // Own-scoped pushdown: `agentId==self` + `durability==permanent`, both
         // @indexed (a seek, not a scan) — strictly narrower than the prior
@@ -400,6 +424,8 @@ export class BootstrapMemories extends Resource {
             const cost = estimateTokens(line);
             if (cost <= tokenBudget) {
                 sections.permanent.push(line);
+                if (includeTrust)
+                    includedTrustMemories.push(m);
                 tokenBudget -= cost;
                 memoriesIncluded++;
             }
@@ -472,6 +498,8 @@ export class BootstrapMemories extends Resource {
                 continue;
             }
             sections.recent.push(line);
+            if (includeTrust)
+                includedTrustMemories.push(m);
             recentSpent += cost;
             tokenBudget -= cost;
             memoriesIncluded++;
@@ -512,6 +540,8 @@ export class BootstrapMemories extends Resource {
                     continue;
                 }
                 sections.predicted.push(line);
+                if (includeTrust)
+                    includedTrustMemories.push(m);
                 predictedSpent += cost;
                 tokenBudget -= cost;
                 memoriesIncluded++;
@@ -612,7 +642,37 @@ export class BootstrapMemories extends Resource {
                     // even though `conditions` already scoped the query.
                     isAllowed: scope.isAllowed,
                     ctx,
+                    // flair#744 slice 1: widen the projection with `provenance` (omitted
+                    // by the default select) ONLY when the trust block was requested, so
+                    // the block's provenance fields are populated for teammate/relevant
+                    // records without changing a non-trust bootstrap's fetch.
+                    select: includeTrust ? [...DEFAULT_SELECT, "provenance"] : undefined,
+                    // flair#744 slice 2 + confidence-band refinement: attach the absolute
+                    // cosine confidence (HNSW-leg, pre keyword bump) when abstention OR
+                    // the trust block is requested — abstention reads the best of it for
+                    // its verdict, and the per-memory trust block classifies each
+                    // task-relevant candidate's into a `matchQuality` band (Kern BINDING
+                    // condition 2: matchQuality needs `_semSimilarity`, so includeTrust
+                    // must turn this on too). Only the task-relevant candidates get a
+                    // similarity — permanent/recent/predicted come from raw own-scoped
+                    // reads with no retrieval score, so their block's matchQuality is
+                    // null (honest: those are lifecycle-window loads, not a retrieval
+                    // surface — confidence bands are a retrieval-surface feature). The
+                    // field is never returned raw (bootstrap renders memories as text
+                    // lines + a trust array), so no strip is needed here. Neither flag ⇒
+                    // candidates carry no `_semSimilarity` and the response is unchanged.
+                    withSemSimilarity: abstain || includeTrust,
                 });
+                // flair#744 slice 2: the best-match confidence for the abstention
+                // decision — the max absolute cosine across the retrieved pool, read
+                // ONLY from `_semSimilarity` (never any principal/authority field). Note
+                // this floor (ABSTENTION_THRESHOLD ≈ 0.15) sits BELOW bootstrap's own
+                // long-standing TASK_RELEVANCE_FLOOR (0.3) that gates `scored` below, so
+                // an abstaining task (bestSim < 0.15) already has no candidate passing
+                // the floor — abstention only ADDS an explicit "nothing covered this"
+                // signal, it never removes a memory the reader would otherwise have seen.
+                if (abstain)
+                    taskBestSimilarity = bestSemanticSimilarity(candidates);
                 // Preserve the ORIGINAL score > 0.3 floor exactly (bootstrap's own
                 // historical relevance floor — distinct from SemanticSearch's
                 // `minScore` request param — strict inequality, applied client-side;
@@ -658,6 +718,8 @@ export class BootstrapMemories extends Resource {
                     else {
                         sections.relevant.push(line);
                     }
+                    if (includeTrust)
+                        includedTrustMemories.push(m);
                     tokenBudget -= cost;
                     memoriesIncluded++;
                 }
@@ -865,8 +927,28 @@ export class BootstrapMemories extends Resource {
         const context = parts.join("\n\n");
         const soulTokens = sections.soul.reduce((sum, line) => sum + estimateTokens(line), 0);
         const memoryTokens = maxTokens - tokenBudget;
+        // flair#744 slice 1 — opt-in per-memory trust block. Bootstrap renders
+        // memories as text lines rather than result objects, so the block is
+        // surfaced as a `trust` array of self-contained entries (each carries its
+        // own `id` to correlate to a rendered line), one per INCLUDED memory. Built
+        // HERE, in the response tail, strictly after all read-scope resolution and
+        // purely for the response — never consulted for any authority decision
+        // (#735-spirit zero-authority invariant). Default OFF ⇒ the `trust` key is
+        // absent ⇒ the response is byte-identical to pre-slice-1.
+        const trust = includeTrust
+            ? includedTrustMemories.map((m) => ({ id: m.id, ...buildTrustBlock(m) }))
+            : undefined;
+        // flair#744 slice 2 — opt-in abstention verdict for the task-relevance
+        // surface. Present ONLY when `abstain` is requested (byte-identical to
+        // pre-slice-2 otherwise); scoped to whether any memory covered
+        // `currentTask` (bestScore null ⇒ no task/embedding ⇒ abstained:false). The
+        // decision reads only the confidence number — never a principal — against
+        // the single GLOBAL threshold.
+        const abstention = abstain ? evaluateAbstention(taskBestSimilarity) : undefined;
         return {
             context,
+            ...(trust ? { trust } : {}),
+            ...(abstention ? { abstention } : {}),
             sections: {
                 soul: sections.soul.length,
                 skills: sections.skills.length,

package/dist/resources/RecordUsage.js

@@ -11,6 +11,14 @@
  * REPLACES `retrievalBoost` in `compositeScore` outright (see that
  * function's doc).
  *
+ * flair#744 slice A: the actual ledger-write core below (formerly this
+ * class's private `_recordOne()`) has moved to ./usage-recording.ts's
+ * `recordUsageContribution()` — a shared, single-implementation extraction
+ * also used by citation-on-write (resources/Memory.ts's post()/put()) so
+ * there is exactly ONE place the (agentId, memoryId) ledger logic lives.
+ * This endpoint's own request handling (auth, rate limit, batch validation,
+ * the no-enumeration response) is unchanged.
+ *
  * WHY THIS IS ITS OWN ENDPOINT, NOT `Memory.put()` (Sherlock, K&S verdict —
  * FLAIR-USAGE-FEEDBACK-SIGNAL.md): usage feedback is fundamentally a
  * CROSS-AGENT write — agent B reports using agent A's memory, so the write
@@ -21,10 +29,10 @@
  * memory through this surface — not just the count. So this endpoint does
  * the narrowest possible thing instead: a TARGETED `usageCount`-only
  * bump (read-full-record, merge just this one field, write — see
- * _recordOne() below) against the RAW `Memory` table object, entirely
- * bypassing the `Memory` RESOURCE class (and its ownership gate) — its own
- * auth model is verified-agent + within-org + explicitly NO ownership
- * requirement.
+ * ./usage-recording.ts's recordUsageContribution()) against the RAW
+ * `Memory` table object, entirely bypassing the `Memory` RESOURCE class
+ * (and its ownership gate) — its own auth model is verified-agent +
+ * within-org + explicitly NO ownership requirement.
  *
  * WHY THIS ISN'T A @table-BACKED RESOURCE: the actual dedup ledger (one row
  * per (agentId, memoryId) contribution) lives in the `MemoryUsage` table
@@ -37,13 +45,14 @@
  * SAME class of gotcha resources/Memory.ts documents for a raw HTTP POST to
  * `/Memory`, but here it bites even an in-process call). So the ledger row
  * itself is written via `.put()` (upsert with the deterministic composite
- * id — see _recordOne()), and this endpoint's OWN HTTP surface lives on a
- * plain action `Resource` (same shape as resources/MemoryReflect.ts /
- * resources/SemanticSearch.ts) rather than extending a @table class, so POST
- * actually routes here. It talks to BOTH `Memory` and `MemoryUsage` via
- * their raw table objects (bypassing each resource class's own auth
- * wrapper — the same "call the other table directly" pattern
- * resources/Memory.ts already uses for `MemoryGrant` in hasWriteGrant()).
+ * id — see ./usage-recording.ts's recordUsageContribution()), and this
+ * endpoint's OWN HTTP surface lives on a plain action `Resource` (same shape
+ * as resources/MemoryReflect.ts / resources/SemanticSearch.ts) rather than
+ * extending a @table class, so POST actually routes here. It talks to BOTH
+ * `Memory` and `MemoryUsage` via their raw table objects (bypassing each
+ * resource class's own auth wrapper — the same "call the other table
+ * directly" pattern resources/Memory.ts already uses for `MemoryGrant` in
+ * hasWriteGrant()).
  *
  * ANTI-GAMING (Sherlock): usage feedback is a write that affects RANKING —
  * an abuse surface (inflate usageCount to boost a memory). Three-layer
@@ -73,13 +82,16 @@
  * sanitized (control-character-stripped, length-capped) and stored as-is,
  * for audit/analytics only. Treat it as untrusted data, always.
  */
-import { Resource, databases } from "@harperfast/harper";
+import { Resource } from "@harperfast/harper";
 import { resolveAgentAuth } from "./agent-auth.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
-import { withDetachedTxn } from "./table-helpers.js";
+import { recordUsageContribution, MAX_USAGE_IDS_PER_CALL } from "./usage-recording.js";
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const BAD_REQUEST = (msg) => new Response(JSON.stringify({ error: msg }), { status: 400, headers: { "Content-Type": "application/json" } });
-const MAX_IDS_PER_CALL = 20;
+// flair#744 slice A: sourced from the shared module (./usage-recording.ts)
+// so RecordUsage.post()'s validated-batch cap and citation-on-write's
+// advisory-batch cap can never drift apart.
+const MAX_IDS_PER_CALL = MAX_USAGE_IDS_PER_CALL;
 const MAX_ATTRIBUTION_LENGTH = 500;
 /**
  * Strip control/non-printable characters and cap length. Attribution is
@@ -148,7 +160,12 @@ export class RecordUsage extends Resource {
         const now = new Date().toISOString();
         for (const memoryId of memoryIds) {
             try {
-                await this._recordOne(ctx, agentId, memoryId, attribution, now);
+                // flair#744 slice A: the ledger-write core now lives in
+                // ./usage-recording.ts's recordUsageContribution() — a shared,
+                // single-implementation extraction (also used by citation-on-write,
+                // resources/Memory.ts's post()/put()). Byte-identical behavior to
+                // the former private _recordOne() this replaced.
+                await recordUsageContribution(ctx, agentId, memoryId, attribution, now);
             }
             catch (err) {
                 // Never let one bad id fail the whole batch, and never let an
@@ -162,69 +179,4 @@ export class RecordUsage extends Resource {
         // counted / were not found — see RECORDED_RESPONSE's doc.
         return RECORDED_RESPONSE;
     }
-    /**
-     * One (agentId, memoryId) contribution.
-     *
-     * Ledger-row-create FIRST, THEN the Memory.usageCount bump — so a crash
-     * between the two leaves the SAFE failure state (ledger row exists, count
-     * not yet bumped: a later retry just re-checks and no-ops) rather than the
-     * reverse (count bumped, no ledger row → a retry would double-count).
-     *
-     * Every discrete Harper call is wrapped INDIVIDUALLY in its own
-     * withDetachedTxn — never one wrap around a multi-step helper. A request
-     * that reads/writes MULTIPLE tables (or the same table twice) in sequence
-     * can otherwise inherit a closed transaction from a prior call's drained
-     * chain (table-helpers.ts's withDetachedTxn doc); resources/Memory.ts's
-     * closeSupersededRecord documents exactly why a single wrap around a
-     * multi-await async function does NOT protect a later call inside it —
-     * this mirrors that function's literal shape (get wrapped, then a
-     * SEPARATE put wrapped) rather than delegating to the generic
-     * patchRecord() helper, which would combine both into one un-safe wrap.
-     *
-     * The final get-then-put for the increment is a best-effort (non-atomic)
-     * read-modify-write, same class of race already accepted elsewhere in
-     * this codebase for count fields (e.g. retrievalCount's bump in
-     * SemanticSearch.ts) — a concurrent contribution from a DIFFERENT agent
-     * landing between this call's read and write could lose one increment.
-     * Re-fetching immediately before the write (rather than reusing the
-     * earlier existence-check read) narrows, without eliminating, that
-     * window. Not solved here: bounded, low-severity (an undercount, never an
-     * inflation), and orthogonal to the anti-gaming properties the cap/floor
-     * and dedup ledger actually defend.
-     */
-    async _recordOne(ctx, agentId, memoryId, attribution, now) {
-        const ledgerId = `${agentId}:${memoryId}`;
-        // Bypasses resources/MemoryUsage.ts's own auth wrapper by design — this
-        // IS the trusted internal caller that resource's module doc describes
-        // (same "raw table object" pattern resources/Memory.ts uses for
-        // MemoryGrant).
-        const existingContribution = await withDetachedTxn(ctx, () => databases.flair.MemoryUsage.get(ledgerId)).catch(() => null);
-        if (existingContribution)
-            return; // already counted by this agent — silent no-op
-        const memoryExists = await withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
-        if (!memoryExists)
-            return; // no such memory — silent no-op (no enumeration)
-        const ledgerRecord = { id: ledgerId, agentId, memoryId, createdAt: now };
-        if (attribution)
-            ledgerRecord.attribution = attribution;
-        // .put(), not .post(): Harper's raw TableResource has no default post()
-        // implementation for a static-style (non-`isCollection`-instantiated)
-        // call — confirmed live ("The MemoryUsage does not have a post method
-        // implemented", statusCode 405) — the SAME class of gotcha
-        // resources/Memory.ts documents for HTTP POST, but here it bites even
-        // this in-process call. Irrelevant anyway: ledgerId is already a
-        // deterministic composite key, so this is a create-with-explicit-id —
-        // exactly what PUT (upsert) is for, not an auto-generated-id insert.
-        await withDetachedTxn(ctx, () => databases.flair.MemoryUsage.put(ledgerRecord));
-        // Targeted usageCount-ONLY bump: read-full-record, merge just this one
-        // field, write — against the RAW Memory table, NEVER Memory.put() (the
-        // resource class): that would 403 this cross-agent write via its
-        // ownership check, and bypassing that check directly would risk letting
-        // this endpoint smuggle OTHER field changes through instead of just the
-        // count (module doc's "WHY THIS IS ITS OWN ENDPOINT").
-        const fresh = await withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
-        if (!fresh)
-            return; // deleted between the checks above and now — no-op
-        await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...fresh, usageCount: (fresh.usageCount ?? 0) + 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) };
+}

package/dist/resources/usage-recording.js

@@ -0,0 +1,160 @@
+/**
+ * usage-recording.ts — shared usage-ledger recording core (flair#744 slice A,
+ * "citation-on-write"; extracted from RecordUsage.ts's flair#683 signal so
+ * there is exactly ONE implementation of the ledger logic, not two that can
+ * drift).
+ *
+ * Two callers share this core, both crediting the SAME deduped,
+ * principal-bound `MemoryUsage` ledger + the targeted `Memory.usageCount`
+ * bump:
+ *   - `POST /RecordUsage` (resources/RecordUsage.ts) — an agent explicitly
+ *     reports "I used this memory" as a standalone call.
+ *   - Citation-on-write (resources/Memory.ts's post()/put(), via
+ *     `recordCitations()` below) — an agent cites `usedMemoryIds` inline on a
+ *     memory WRITE; each cited id is credited the same way, post-commit and
+ *     failure-isolated from the write itself.
+ *
+ * `recordUsageContribution()` is an EXACT extraction of what was
+ * RecordUsage.ts's private `_recordOne()` — see its doc below for the
+ * ledger-then-count ordering, the individually-wrapped `withDetachedTxn`
+ * discipline, and the accepted best-effort race on the final
+ * read-modify-write. This move changes WHERE the logic lives, not what it
+ * does — behavior is byte-identical for RecordUsage.ts's existing callers.
+ *
+ * `recordCitations()` is the NEW batch helper citation-on-write uses: the
+ * same agent-required / cap / dedup / per-id failure-isolation shape as
+ * RecordUsage.post()'s loop, parameterized so Memory.ts can drive it from a
+ * write body instead of a dedicated POST body. It NEVER reads the ledger for
+ * authority — it only writes contributions; `usedMemoryIds` must never enter
+ * an access/scope/attribution/dedup decision (flair#744 slice A invariant 3).
+ */
+import { databases } from "@harperfast/harper";
+import { withDetachedTxn } from "./table-helpers.js";
+/**
+ * Per-call cap on ids credited in one batch — shared by RecordUsage.post()'s
+ * validated `memoryIds` body (rejects a batch over the cap with a 400) and
+ * recordCitations()'s advisory `usedMemoryIds` (silently slices instead —
+ * see that function's doc for why the two differ here).
+ */
+export const MAX_USAGE_IDS_PER_CALL = 20;
+/**
+ * One (agentId, memoryId) contribution — the shared ledger-write core.
+ *
+ * Ledger-row-create FIRST, THEN the Memory.usageCount bump — so a crash
+ * between the two leaves the SAFE failure state (ledger row exists, count
+ * not yet bumped: a later retry just re-checks and no-ops) rather than the
+ * reverse (count bumped, no ledger row → a retry would double-count).
+ *
+ * Every discrete Harper call is wrapped INDIVIDUALLY in its own
+ * withDetachedTxn — never one wrap around a multi-step helper. A request
+ * that reads/writes MULTIPLE tables (or the same table twice) in sequence
+ * can otherwise inherit a closed transaction from a prior call's drained
+ * chain (table-helpers.ts's withDetachedTxn doc); resources/Memory.ts's
+ * closeSupersededRecord documents exactly why a single wrap around a
+ * multi-await async function does NOT protect a later call inside it —
+ * this mirrors that function's literal shape (get wrapped, then a
+ * SEPARATE put wrapped) rather than delegating to the generic
+ * patchRecord() helper, which would combine both into one un-safe wrap.
+ *
+ * The final get-then-put for the increment is a best-effort (non-atomic)
+ * read-modify-write, same class of race already accepted elsewhere in
+ * this codebase for count fields (e.g. retrievalCount's bump in
+ * SemanticSearch.ts) — a concurrent contribution from a DIFFERENT agent
+ * landing between this call's read and write could lose one increment.
+ * Re-fetching immediately before the write (rather than reusing the
+ * earlier existence-check read) narrows, without eliminating, that
+ * window. Not solved here: bounded, low-severity (an undercount, never an
+ * inflation), and orthogonal to the anti-gaming properties the cap/floor
+ * and dedup ledger actually defend.
+ *
+ * Called by RecordUsage.post() (explicit usage feedback) and by
+ * recordCitations() below (citation-on-write) — identical ledger semantics
+ * regardless of which surface triggered the contribution.
+ */
+export async function recordUsageContribution(ctx, agentId, memoryId, attribution, now) {
+    const ledgerId = `${agentId}:${memoryId}`;
+    // Bypasses resources/MemoryUsage.ts's own auth wrapper by design — this
+    // IS the trusted internal caller that resource's module doc describes
+    // (same "raw table object" pattern resources/Memory.ts uses for
+    // MemoryGrant).
+    const existingContribution = await withDetachedTxn(ctx, () => databases.flair.MemoryUsage.get(ledgerId)).catch(() => null);
+    if (existingContribution)
+        return; // already counted by this agent — silent no-op
+    const memoryExists = await withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
+    if (!memoryExists)
+        return; // no such memory — silent no-op (no enumeration)
+    const ledgerRecord = { id: ledgerId, agentId, memoryId, createdAt: now };
+    if (attribution)
+        ledgerRecord.attribution = attribution;
+    // .put(), not .post(): Harper's raw TableResource has no default post()
+    // implementation for a static-style (non-`isCollection`-instantiated)
+    // call — confirmed live ("The MemoryUsage does not have a post method
+    // implemented", statusCode 405) — the SAME class of gotcha
+    // resources/Memory.ts documents for HTTP POST, but here it bites even
+    // this in-process call. Irrelevant anyway: ledgerId is already a
+    // deterministic composite key, so this is a create-with-explicit-id —
+    // exactly what PUT (upsert) is for, not an auto-generated-id insert.
+    await withDetachedTxn(ctx, () => databases.flair.MemoryUsage.put(ledgerRecord));
+    // Targeted usageCount-ONLY bump: read-full-record, merge just this one
+    // field, write — against the RAW Memory table, NEVER Memory.put() (the
+    // resource class): that would 403 this cross-agent write via its
+    // ownership check, and bypassing that check directly would risk letting
+    // this write path smuggle OTHER field changes through instead of just the
+    // count (RecordUsage.ts module doc's "WHY THIS IS ITS OWN ENDPOINT").
+    const fresh = await withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
+    if (!fresh)
+        return; // deleted between the checks above and now — no-op
+    await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...fresh, usageCount: (fresh.usageCount ?? 0) + 1 }));
+}
+/**
+ * Batch citation helper — credits every id in `usedMemoryIds` through
+ * `recordFn` (the real `recordUsageContribution` by default), one contribution
+ * per unique id, capped at `MAX_USAGE_IDS_PER_CALL`.
+ *
+ * Called by Memory.ts's post()/put() POST-COMMIT, wrapped in its own
+ * try/catch at the call site — this function itself never throws (every
+ * per-id failure is caught and logged below), but callers still isolate the
+ * call as a second line of defense so a write can never be affected by
+ * citation recording (flair#744 slice A invariant 1).
+ *
+ *   - `auth.kind !== "agent"` ⇒ return immediately, no-op. Internal/admin/
+ *     anonymous writes have no agent identity to attribute a contribution
+ *     TO — same rule RecordUsage.post() applies ("usage feedback requires a
+ *     verified agent identity").
+ *   - `usedMemoryIds` not a non-empty array of non-empty strings ⇒ no-op
+ *     (advisory field, never a validated request body — a malformed value
+ *     is silently ignored, never a 400).
+ *   - Deduped within the call (`[...new Set(...)]`), THEN capped at
+ *     MAX_USAGE_IDS_PER_CALL by slicing — a citation list is advisory, not a
+ *     validated request body, so an oversized list is trimmed rather than
+ *     rejected (unlike RecordUsage.post()'s validated `memoryIds`, which
+ *     400s over the same cap).
+ *   - Each id is credited independently: one id throwing never stops the
+ *     rest, and the failure is logged server-side, never surfaced to the
+ *     caller (the write already committed by the time this runs).
+ *
+ * `agentId` passed to `recordFn` is ALWAYS `auth.agentId` — the resolved
+ * auth context, never anything derived from `usedMemoryIds` or any other
+ * caller-supplied input (flair#744 slice A invariant 4: no forging on
+ * behalf of another identity).
+ */
+export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn = recordUsageContribution) {
+    if (auth.kind !== "agent")
+        return;
+    if (!Array.isArray(usedMemoryIds) ||
+        usedMemoryIds.length === 0 ||
+        !usedMemoryIds.every((id) => typeof id === "string" && id.length > 0)) {
+        return;
+    }
+    const ids = [...new Set(usedMemoryIds)].slice(0, MAX_USAGE_IDS_PER_CALL);
+    for (const id of ids) {
+        try {
+            await recordFn(ctx, auth.agentId, id, undefined, now);
+        }
+        catch (err) {
+            // Never let one bad id stop the batch — same no-op-on-error discipline
+            // as RecordUsage.post()'s loop, log server-side only.
+            console.error("recordCitations: failed to credit (no-op)", { memoryId: id, err });
+        }
+    }
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.24.0",
+  "version": "0.25.0",
+  "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -54,7 +55,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.1.17",
+    "@harperfast/harper": "5.1.22",
     "@harperfast/oauth": "2.4.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",