@tpsdev-ai/flair 0.23.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).
@@ -291,8 +309,26 @@ async function hasWriteGrant(granteeId, ownerId) {
  * requires a "write" MemoryGrant from the target's owner (reuses the existing
  * agent-auth/grant machinery — no parallel auth logic). Returns a Response to
  * short-circuit with (400/403), or null to continue.
+ *
+ * flair#704: an explicit `supersedes: null` — the shape most JSON writers
+ * produce for an unset optional field (`JSON.stringify({supersedes: undefined})`
+ * drops the key, but plenty of writers instead do `{supersedes: x ?? null}`)
+ * — must be treated identically to the key being OMITTED, per the
+ * additive-schema convention (flair#695: an explicit null on an
+ * optional/nullable field reads as absent, not as a distinct value). Fixed by
+ * deleting the key BEFORE the type check below, so (a) the check never
+ * rejects it, and (b) `super.put()`/`super.post()` — Harper full-record
+ * replacement, see table-helpers.ts's header comment — never persists a
+ * literal `null` where "absent" was intended: the stored row ends up
+ * byte-for-byte identical to the omitted-key case, so every downstream
+ * `!content.supersedes` / `content.supersedes &&` check below (and in
+ * closeSupersededIfNeeded) already treats it as unset with no further
+ * changes needed.
  */
 async function validateAndAuthorizeSupersedes(content, auth) {
+    if (content.supersedes === null) {
+        delete content.supersedes;
+    }
     if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
         return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
             status: 400, headers: { "Content-Type": "application/json" },
@@ -421,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
@@ -433,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.
@@ -520,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;
@@ -631,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) {
@@ -672,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
@@ -803,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/Presence.js

@@ -32,7 +32,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { resolveAgentAuth, verifyAgentRequest } from "./agent-auth.js";
-import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
 const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "debugging", "idle"]);
@@ -409,11 +409,11 @@ export class Presence extends databases.flair.Presence {
             agentId = middlewareAgent;
         }
         else {
-            const m = authHeader.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
-            if (!m) {
+            const parsed = parseTpsEd25519Header(authHeader);
+            if (!parsed) {
                 return new Response(JSON.stringify({ error: "Ed25519 agent auth required for heartbeat" }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
-            const [, headerAgentId, tsRaw, nonce, sigB64] = m;
+            const { agentId: headerAgentId, tsRaw, nonce, signatureB64: sigB64 } = parsed;
             const ts = Number(tsRaw);
             const now = Date.now();
             if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS) {

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";
         }