@tpsdev-ai/flair 0.24.0 → 0.25.1

package/README.md

@@ -134,6 +134,15 @@ flair memory search "native addon loading in sandboxed runtimes"
 # → [0.67] Harper v5 sandbox blocks node:module but process.dlopen works
 ```
 
+### Trust-Graded Recall
+Recall can carry an opt-in **trust-evidence block** per result — provenance (verified vs claimed author), usage signal, freshness/validity, supersession — so an agent weighs *what to trust*, not just *what matched*. On top of it:
+
+- **Confidence bands** (`matchQuality`): each result is labeled `strong` / `moderate` / `breadcrumb` from its absolute similarity — a weak-but-relevant hit is taken for what it is, not mistaken for a confident one.
+- **First-class abstention** (`abstain`): when nothing clears a confidence floor, recall returns an honest "no memory covers this" verdict instead of the N weakest matches.
+- **Citation-on-write** (`usedMemoryIds`) + **`record_usage`**: report which memories actually grounded an answer — a deduped, principal-bound usage signal (honest evidence, never retrieval-popularity) that strengthens future recall.
+
+Opt-in and additive (`includeTrust` / `abstain` on the recall path) — off by default, byte-identical when unused. Reachable today via the authenticated HTTP API and the native `/mcp` tools; first-class exposure in the `flair` CLI, `@tpsdev-ai/flair-client`, and the `flair-mcp` bridge is a follow-up. Full arc in the [CHANGELOG](CHANGELOG.md) (flair#744).
+
 ### Tiered Durability
 Not all memories are equal:
 
@@ -340,7 +349,7 @@ Add to your `CLAUDE.md`:
 
     At the start of every session, run mcp__flair__bootstrap before responding.
 
-Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The MCP server exposes `memory_store`, `memory_search`, `memory_get`, `memory_delete`, `bootstrap`, `soul_set`, `soul_get`.
+Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The `flair-mcp` server — the bridge these CLIs connect to — exposes `memory_store`, `memory_search`, `memory_update`, `memory_get`, `memory_delete`, `relationship_store`, `bootstrap`, `soul_set`, `soul_get`, `flair_workspace_set`, and `flair_orgevent`. (Flair's in-Harper native `/mcp` surface is a separate, still-experimental tool set with `attention` + `record_usage` — see Trust-Graded Recall above.)
 
 For per-CLI config snippets (Gemini CLI's `~/.gemini/settings.json`, Codex CLI's `~/.codex/config.toml`, etc.), see **[docs/mcp-clients.md](docs/mcp-clients.md)**. For a deeper Claude Code walk-through with `CLAUDE.md` patterns, see [docs/claude-code.md](docs/claude-code.md).
 
@@ -353,7 +362,7 @@ Use Flair as the memory backend for n8n's AI Agent. Same memories readable from
 @tpsdev-ai/n8n-nodes-flair
 ```
 
-Two nodes ship: **Flair Chat Memory** (Memory port, conversation buffer) and **Flair Search** (Tool port, semantic search + get-by-subject). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
+Three nodes ship: **Flair Chat Memory** (Memory port, conversation buffer), **Flair Search** (Tool port, semantic search + get-by-subject), and **Flair Write** (Tool port, store memories). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
 
 ### JavaScript / TypeScript (Client Library)
 
@@ -541,13 +550,13 @@ Flair is in active development and daily use. We dogfood it — the agents that
 - ✅ Web admin UI (principals, connectors, IdPs, instance config)
 - ✅ Federation (hub-and-spoke sync with signed requests and pairing tokens)
 - ✅ OpenClaw memory plugin
-- ✅ MCP server for Claude Code / Cursor / Windsurf
+- ✅ MCP server for Claude Code / Cursor / Codex / Gemini CLI
 - ✅ Lightweight client library (`@tpsdev-ai/flair-client`)
 - ✅ Portable agent identity (export/import between instances)
 - ✅ `flair --version`, `flair upgrade`
+- ✅ First-run soul wizard (interactive personality setup)
 
 **What's next:**
-- [ ] First-run soul wizard (interactive personality setup)
 - [ ] Git-backed memory sync
 - [ ] Encryption at rest (opt-in AES-256-GCM per memory)
 - [ ] Harper Fabric deployment (managed multi-office)

package/dist/cli.js

@@ -1641,6 +1641,23 @@ export function decideAfterVerify(result, previousVersion) {
     if (result.ok)
         return { kind: "ok" };
     const reason = result.error ?? "post-restart verification failed";
+    // A HEALTHY instance whose ONLY failure was that the verifier couldn't
+    // authenticate (401/403) is demonstrably UP: the public /Health answered
+    // 2xx AND the server responded to the authenticated probe — it rejected our
+    // credentials, it did not fail to respond. A version we couldn't READ is not
+    // grounds to roll back a RUNNING instance. Rolling back here is destructive
+    // AND self-defeating — the rollback's own re-verify hits the identical
+    // missing-credential wall, producing the false "ROLLBACK ALSO FAILED / state
+    // UNKNOWN" for an instance that was healthy the whole time. (The real
+    // incident: /HealthDetail became a verified-read in flair#747, so a machine
+    // with no admin-pass/agent key authenticates fine against the pre-upgrade
+    // version but not post-restart — the pre-flight credential check can't
+    // anticipate a version that changes /HealthDetail's auth requirement.)
+    // Report it as up-but-unverified and NEVER roll back. This supersedes
+    // flair#741 fix #3's "prefer the known-good version" default, which the
+    // incident proved wrong for a healthy instance.
+    if (isCredentialOnlyFailure(result))
+        return { kind: "healthy-unverified", reason };
     if (!previousVersion)
         return { kind: "cannot-rollback", reason };
     return { kind: "rollback", reason, toVersion: previousVersion };
@@ -8352,18 +8369,22 @@ program
         console.log(`✅ verified: healthy, authenticated${verify.version ? `, running ${verify.version}` : ""}`);
         return;
     }
-    console.error(`❌ post-restart verification failed: ${verdict.reason}`);
-    if (isCredentialOnlyFailure(verify)) {
-        // flair#741 fix #3: a responding server that rejects the verifier's
-        // credentials proves the instance is UP — it is not evidence the
-        // upgrade itself broke anything. Say so explicitly instead of leaving
-        // the reader to infer it from the raw error text. Rollback still
-        // proceeds below (a credential check that worked pre-upgrade — see
-        // the pre-flight above — and stopped working mid-run is an edge case
-        // ambiguous enough that "prefer the known-good version" is still the
-        // safer default), but the reason for it is now honest.
-        console.error("   The instance is up and responded — the verifier could not authenticate. This is not a sign the upgrade broke anything.");
+    // flair#741 follow-through: a healthy instance the verifier just couldn't
+    // authenticate against. The upgrade SUCCEEDED — the new version's server is
+    // up (public /Health passed); we simply couldn't read its version over the
+    // authenticated /HealthDetail. Report the caveat and STOP — never roll back
+    // a running instance over a credentials gap. (decideAfterVerify only
+    // returns this for isCredentialOnlyFailure(verify), so the old
+    // "print an honest note but roll back anyway" branch that used to sit below
+    // is gone — that credentials case can no longer reach the rollback path.)
+    if (verdict.kind === "healthy-unverified") {
+        console.log(`✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
+        console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
+        console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
+        return;
     }
+    console.error(`❌ post-restart verification failed: ${verdict.reason}`);
     if (verdict.kind === "cannot-rollback") {
         console.error("   Cannot roll back automatically: the previously-installed @tpsdev-ai/flair version is unknown.");
         console.error("   Check the instance now: flair doctor");

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