@tpsdev-ai/flair 0.21.0 → 0.22.0

package/dist/resources/Presence.js

@@ -27,11 +27,15 @@
  *     in-org agents only; see get()'s inline comment.
  */
 import { databases } from "@harperfast/harper";
+import { existsSync, readFileSync } from "node:fs";
+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";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
-const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "idle"]);
+const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "debugging", "idle"]);
 function idleThresholdMs() {
     const env = process.env.PRESENCE_IDLE_THRESHOLD_MS;
     return env ? Number(env) || 90_000 : 90_000;
@@ -40,6 +44,94 @@ function offlineThresholdMs() {
     const env = process.env.PRESENCE_OFFLINE_THRESHOLD_MS;
     return env ? Number(env) || 600_000 : 600_000;
 }
+// ─── Version stamping (flair#639) ──────────────────────────────────────────────
+//
+// Auto-presence (packages/flair-mcp/src/presence.ts, flair#608) gives agents a
+// heartbeat, but the record never said which Flair *instance* served it —
+// fleet skew across hosts was only discoverable by probing each one by hand.
+// Every heartbeat now stamps the RUNNING server's own flair + harper versions,
+// so `flair doctor`'s fleet-presence section (src/cli.ts + src/fleet-presence.ts)
+// can flag stale instances org-relatively, no per-host probing required.
+/**
+ * Resolve the running @tpsdev-ai/flair version from package.json (duplicated
+ * from resources/health.ts / admin-layout.ts / AdminInstance.ts — same "keep
+ * in sync" idiom noted in those files: each resource module keeps its own
+ * copy for dependency isolation rather than importing a shared helper).
+ * `process.env.npm_package_version` is only populated inside `npm run`, so
+ * reading package.json relative to THIS running module is the only way to
+ * report the version of the code that's actually executing.
+ */
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
+/**
+ * Resolve the running @harperfast/harper version. Unlike flair's own
+ * package.json (readable via a plain relative path above), Harper's package
+ * only exports "." → dist/index.js — there's no "./package.json" subpath, so
+ * requiring it directly throws (Node's exports-map enforcement). Resolve the
+ * main entry via createRequire instead, then walk up from dist/index.js to
+ * the package root's package.json. Returns null (not a placeholder string)
+ * on failure so callers/readers can tell "genuinely unknown" apart from a
+ * real version — same tri-state as fabric-upgrade.ts's last-resort Harper
+ * version lookup.
+ */
+function resolveHarperVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        const mainPath = req.resolve("@harperfast/harper");
+        const pkgPath = join(dirname(mainPath), "..", "package.json");
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+    }
+    catch { /* fall through */ }
+    return null;
+}
+/**
+ * Build the record to persist for a presence heartbeat. Pure — no Harper
+ * calls, no version resolution of its own — so the record SHAPE (and post()'s
+ * merge-vs-insert plumbing around it) can be unit-tested without a live
+ * Harper or the real filesystem. Callers pass already-resolved versions
+ * (resolveVersion()/resolveHarperVersion() above), so tests can pin them
+ * directly. Mirrors buildPresenceBody() in packages/flair-mcp/src/presence.ts
+ * — same "exported pure builder, exported for tests" idiom, server side.
+ */
+export function buildPresenceRecord(agentId, now, currentTask, activity, existingActivity, existingActivityUpdatedAt, flairVersion, harperVersion) {
+    // A heartbeat "asserts" what the agent is doing when it carries an activity
+    // and/or a (non-empty) currentTask. Only such a beat re-stamps
+    // activityUpdatedAt to `now`; a pure liveness beat (neither field) refreshes
+    // lastHeartbeatAt but PRESERVES the prior stamp — so activity ages on its own
+    // and lapses to last-known once the agent stops asserting it, with no manual
+    // clear (natural-presence). Backward compatible: today every real heartbeat
+    // carries activity, so this simply keeps activity fresh while an agent works.
+    const asserted = activity !== undefined || sanitizeCurrentTask(currentTask) !== null;
+    return {
+        agentId,
+        lastHeartbeatAt: now,
+        currentTask: sanitizeCurrentTask(currentTask),
+        activity: activity ?? (existingActivity ?? "idle"),
+        activityUpdatedAt: asserted ? now : (existingActivityUpdatedAt ?? null),
+        flairVersion,
+        harperVersion,
+    };
+}
 // ─── Nonce replay + crypto helpers ─────────────────────────────────────────────
 // WINDOW_MS, isNonceReplay/recordNonce (the ONE shared nonce store), and
 // importEd25519Key all live in ./ed25519-auth.ts — the single
@@ -61,16 +153,81 @@ export function derivePresenceStatus(now, lastHeartbeatAt, idleMs, offlineMs) {
         return "idle";
     return "offline";
 }
+// ─── Activity decay (natural-presence) ─────────────────────────────────────────
+//
+// Presence is a LIVENESS BEACON, not a sticky status board: an offline agent
+// has, by definition, no *current* activity, so returning its last `activity`
+// / `currentTask` as if live is a lie (an agent offline 13 days still read as
+// `activity: "debugging"`; another showed a finished-task `currentTask` 20h
+// after going dark). These two pure functions decide "is this record's
+// activity still CURRENT, or has it lapsed into last-known?" — same offline
+// threshold, and the SAME graceful-degradation-on-old-records discipline, as
+// derivePresenceStatus() above and flair#639's version staleness.
+/**
+ * Resolve the timestamp used to judge activity freshness. Prefer the per-field
+ * `activityUpdatedAt` stamp (additive/nullable, mirrors flair#639); fall back
+ * to `lastHeartbeatAt` for records written before this feature existed — so an
+ * old row degrades to "activity is exactly as fresh as its heartbeat" (never
+ * claiming activity is FRESHER than the beat that carried it) rather than
+ * reading as permanently stale or throwing. Returns null only when NEITHER is
+ * a finite number (nothing to judge against → treated as stale by callers).
+ */
+export function activityFreshnessAt(activityUpdatedAt, lastHeartbeatAt) {
+    if (typeof activityUpdatedAt === "number" && Number.isFinite(activityUpdatedAt))
+        return activityUpdatedAt;
+    if (typeof lastHeartbeatAt === "number" && Number.isFinite(lastHeartbeatAt))
+        return lastHeartbeatAt;
+    return null;
+}
+/**
+ * Pure decay rule: is a record's activity/currentTask still CURRENT? Activity
+ * is fresh while its freshness stamp is younger than the SAME offline
+ * threshold that flips presenceStatus to "offline" — so an offline agent can
+ * never present a live-looking activity label. Because the stamp only moves
+ * forward when a heartbeat actually carries activity (see buildPresenceRecord),
+ * activity also lapses INDEPENDENTLY of raw liveness: an agent that keeps
+ * heartbeating liveness but stops asserting what it's doing decays to
+ * last-known on its own, no manual "clear" call needed. Clock skew (a stamp in
+ * the future) is treated as fresh, matching derivePresenceStatus().
+ */
+export function isActivityFresh(now, activityUpdatedAt, lastHeartbeatAt, offlineMs) {
+    const offline = offlineMs ?? offlineThresholdMs();
+    const at = activityFreshnessAt(activityUpdatedAt, lastHeartbeatAt);
+    if (at == null)
+        return false;
+    const elapsed = now - at;
+    if (elapsed < 0)
+        return true;
+    return elapsed < offline;
+}
 // ─── Public-safe field allowlist ──────────────────────────────────────────────
+// flairVersion/harperVersion (flair#639) are content-gated the SAME way as
+// currentTask (see get()'s includeVerifiedFields) even though version
+// numbers aren't free text — precedent is HealthDetail vs the public /Health
+// endpoint (resources/health.ts): version info is deliberately withheld from
+// anonymous callers to avoid fingerprinting a publicly exposed instance for
+// known-CVE targeting. Anonymous readers get null for both, same as currentTask.
+// activity/lastActivity/activityUpdatedAt/activityAgeMs/activityFresh
+// (natural-presence) are all public-safe: `activity` and `lastActivity` are a
+// fixed vocabulary label (coding|reviewing|planning|debugging|idle), the two timestamps
+// and the boolean are liveness metadata of the same class as the already-public
+// lastHeartbeatAt. Only `currentTask` (free text) stays content-gated to
+// verified readers — see get()'s includeVerifiedFields.
 const ROSTER_ALLOWLIST = new Set([
     "id",
     "displayName",
     "role",
     "runtime",
     "activity",
+    "lastActivity",
+    "activityUpdatedAt",
+    "activityAgeMs",
+    "activityFresh",
     "presenceStatus",
     "currentTask",
     "lastHeartbeatAt",
+    "flairVersion",
+    "harperVersion",
 ]);
 function sanitizeCurrentTask(task) {
     if (typeof task !== "string")
@@ -138,6 +295,10 @@ export class Presence extends databases.flair.Presence {
      * super_user, Basic-admin, internal in-process) gets currentTask=null.
      * allowRead() is UNCHANGED (still `true`) — the roster itself stays public;
      * only the free-text field is gated, per the issue's field-level option.
+     *
+     * flairVersion/harperVersion (flair#639) ride the SAME gate, renamed to
+     * includeVerifiedFields since it now covers more than currentTask — see the
+     * ROSTER_ALLOWLIST comment above for why version numbers are gated too.
      */
     async get() {
         // Extract the raw request the same way post() does (getContext().request
@@ -148,7 +309,7 @@ export class Presence extends databases.flair.Presence {
         const ctx = this.getContext?.();
         const request = ctx?.request ?? ctx;
         const agentAuth = request ? await verifyAgentRequest(request) : null;
-        const includeCurrentTask = agentAuth !== null;
+        const includeVerifiedFields = agentAuth !== null;
         const now = Date.now();
         const idleThreshold = idleThresholdMs();
         const offlineThreshold = offlineThresholdMs();
@@ -164,22 +325,58 @@ export class Presence extends databases.flair.Presence {
                     agent = await databases.flair.Agent.get(agentId);
                 }
                 catch { /* agent may not exist or be deactivated */ }
+                const lastHeartbeatAt = typeof row?.lastHeartbeatAt === "number"
+                    ? row.lastHeartbeatAt
+                    : Number(row?.lastHeartbeatAt ?? 0);
+                // activityUpdatedAt is BigInt in the schema (Harper may hand it back as
+                // number|string|bigint) and absent on pre-feature records — normalize
+                // to a finite number or null so activityFreshnessAt() can fall back.
+                const activityUpdatedAt = row?.activityUpdatedAt == null
+                    ? null
+                    : (typeof row.activityUpdatedAt === "number" ? row.activityUpdatedAt : Number(row.activityUpdatedAt));
+                // NATURAL PRESENCE: bind activity/currentTask to freshness. A stale
+                // record has no *current* activity — present the last-known label under
+                // dedicated fields, never as the live `activity`. `activity` is the
+                // CURRENT truth (falls to "idle" — the "nothing right now" vocabulary
+                // value — once stale); `lastActivity` preserves the raw last-known
+                // label so a reader can render "offline (was: coding)".
+                const rawActivity = (typeof row?.activity === "string" && row.activity.length > 0)
+                    ? row.activity
+                    : "idle";
+                const activityFresh = isActivityFresh(now, activityUpdatedAt, lastHeartbeatAt, offlineThreshold);
+                const freshnessAt = activityFreshnessAt(activityUpdatedAt, lastHeartbeatAt);
                 const entry = {
                     id: agentId,
                     displayName: agent?.displayName ?? agent?.name ?? agentId,
                     role: agent?.role ?? "agent",
                     runtime: agent?.runtime ?? null,
-                    activity: row?.activity ?? "idle",
-                    presenceStatus: derivePresenceStatus(now, typeof row?.lastHeartbeatAt === "number"
-                        ? row.lastHeartbeatAt
-                        : Number(row?.lastHeartbeatAt ?? 0), idleThreshold, offlineThreshold),
-                    // Anonymous/unverified readers get `null` here (key stays present,
-                    // schema-stable) instead of the sanitized task text — see the
-                    // currentTask CONTENT gate doc above get().
-                    currentTask: includeCurrentTask ? sanitizeCurrentTask(row?.currentTask) : null,
-                    lastHeartbeatAt: typeof row?.lastHeartbeatAt === "number"
-                        ? row.lastHeartbeatAt
-                        : Number(row?.lastHeartbeatAt ?? 0),
+                    // Current activity — only truthful while fresh; "idle" once decayed.
+                    activity: activityFresh ? rawActivity : "idle",
+                    // Last-known activity label regardless of freshness (public-safe, same
+                    // vocabulary as activity) → enables "was: <activity>" rendering.
+                    lastActivity: rawActivity,
+                    // When activity was last asserted (resolved; falls back to
+                    // lastHeartbeatAt for pre-feature records — see activityFreshnessAt).
+                    activityUpdatedAt: freshnessAt,
+                    // How stale that assertion is, so a reader can show "was active Xh
+                    // ago" without needing the server's clock or the threshold.
+                    activityAgeMs: freshnessAt != null ? Math.max(0, now - freshnessAt) : null,
+                    // The server's verdict — makes staleness impossible to misread.
+                    activityFresh,
+                    presenceStatus: derivePresenceStatus(now, lastHeartbeatAt, idleThreshold, offlineThreshold),
+                    // currentTask is current only when the reader is verified AND the
+                    // record is fresh. A stale record's task (a finished-task string it
+                    // never cleared) is NOT current → null, same as the anonymous case.
+                    // Anonymous/unverified readers always get null (key stays present,
+                    // schema-stable) — see the currentTask CONTENT gate doc above get().
+                    currentTask: (includeVerifiedFields && activityFresh) ? sanitizeCurrentTask(row?.currentTask) : null,
+                    lastHeartbeatAt,
+                    // flair#639: absent on records written before this feature (older
+                    // instance, never re-heartbeated since upgrading) — `row?.field ??
+                    // null` tolerates that directly, same as every other optional field
+                    // here. Gated to verified readers; see ROSTER_ALLOWLIST comment.
+                    flairVersion: includeVerifiedFields ? (row?.flairVersion ?? null) : null,
+                    harperVersion: includeVerifiedFields ? (row?.harperVersion ?? null) : null,
                 };
                 results.push(pickAllowlisted(entry));
             }
@@ -263,12 +460,14 @@ export class Presence extends databases.flair.Presence {
                 existing = await databases.flair.Presence.get(agentId);
             }
             catch { /* first heartbeat */ }
-            const record = {
-                agentId,
-                lastHeartbeatAt: now,
-                currentTask: sanitizeCurrentTask(currentTask),
-                activity: activity ?? (existing?.activity ?? "idle"),
-            };
+            // flair#639: stamp THIS server's own running versions on every
+            // heartbeat — an upgrade takes effect on the instance's very next
+            // heartbeat, no separate migration needed.
+            const record = buildPresenceRecord(agentId, now, currentTask, activity, existing?.activity, 
+            // Preserve the prior activity-freshness stamp when THIS beat asserts no
+            // activity/task (pure liveness) — normalize the BigInt-ish stored value
+            // to a number so buildPresenceRecord's `?? null` fallback behaves.
+            existing?.activityUpdatedAt == null ? null : Number(existing.activityUpdatedAt), resolveVersion(), resolveHarperVersion());
             if (existing) {
                 const merged = { ...existing, ...record };
                 await databases.flair.Presence.put(merged);

package/dist/resources/RecordUsage.js

@@ -0,0 +1,230 @@
+/**
+ * POST /RecordUsage — the usage-feedback signal (flair#683).
+ *
+ * A generic "record that a memory was actually used" surface: an agent that
+ * grounded an answer or decision on a recalled memory reports it here.
+ * Distinct from — and NEVER wired to — retrieval: `Memory.retrievalCount`
+ * (bumped on every SemanticSearch hit, resources/SemanticSearch.ts:~551) is
+ * the WEAK, self-reinforcing signal root-caused in flair#623 ("a search hit
+ * counted as usage"); `Memory.usageCount` (this endpoint's only writer) is
+ * the STRONG signal driving `usageBoost` in resources/scoring.ts, which
+ * REPLACES `retrievalBoost` in `compositeScore` outright (see that
+ * function's doc).
+ *
+ * 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
+ * target is A's record, not B's own. `Memory.put()`'s ownership check
+ * (resources/Memory.ts: "a non-admin agent may only write memories it
+ * owns") would 403 every single legitimate call. Bypassing that check
+ * instead would open the door to modifying ANY field on another agent's
+ * 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.
+ *
+ * WHY THIS ISN'T A @table-BACKED RESOURCE: the actual dedup ledger (one row
+ * per (agentId, memoryId) contribution) lives in the `MemoryUsage` table
+ * (schemas/memory.graphql), guarded by resources/MemoryUsage.ts. But this
+ * endpoint's whole shape is "POST a list of ids that got used" — and Harper's
+ * base TableResource has no default `post()` implementation for a
+ * static-style raw-table call outside an `isCollection`-instantiated
+ * resource (confirmed live: `databases.flair.MemoryUsage.post(...)` throws
+ * "The MemoryUsage does not have a post method implemented", HTTP 405 — the
+ * 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()).
+ *
+ * ANTI-GAMING (Sherlock): usage feedback is a write that affects RANKING —
+ * an abuse surface (inflate usageCount to boost a memory). Three-layer
+ * defense:
+ *   1. Rate limiter — a ~30 RPM bucket per agent (resources/rate-limiter.ts,
+ *      "usage" bucket), same shape as every other write path here.
+ *   2. Dedup bound — each (agentId, memoryId) pair contributes AT MOST 1 to
+ *      usageCount, enforced by the MemoryUsage ledger (a fresh ledger row
+ *      required before any increment; a repeat call is a silent no-op).
+ *   3. The capped, floor-gated `usageBoost` itself (resources/scoring.ts) —
+ *      even a fully-gamed usageCount can only nudge a score by +10% above
+ *      the relevance floor; it's a tie-breaker, never an override. Sybil
+ *      (many distinct agent identities) has a bounded blast radius per
+ *      identity, and Ed25519-verified identity isn't free to mint at scale.
+ *
+ * NO ID ENUMERATION (Sherlock): the response is IDENTICAL — `{ recorded:
+ * true }` — for every syntactically-valid input, regardless of whether a
+ * given id was a fresh increment, an already-counted no-op (this agent
+ * already contributed), or a not-found no-op (no such memory). A caller
+ * cannot distinguish "that id doesn't exist" from "you already used it" by
+ * inspecting the response; per-id/per-batch success is deliberately never
+ * reported (see RECORDED_RESPONSE's doc below for why even partial-batch
+ * counts would leak information).
+ *
+ * ATTRIBUTION is OPAQUE (Sherlock): an optional free-text hint about what
+ * used the memory. Never parsed, never fed to an LLM, never rendered —
+ * 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 { resolveAgentAuth } from "./agent-auth.js";
+import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { withDetachedTxn } from "./table-helpers.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;
+const MAX_ATTRIBUTION_LENGTH = 500;
+/**
+ * Strip control/non-printable characters and cap length. Attribution is
+ * OPAQUE (module doc) — this is baseline hygiene against a caller smuggling
+ * something (terminal escapes, a giant blob) into stored data, not content
+ * moderation or safety scanning (content-safety.ts's scanContent() is for
+ * memory CONTENT that gets injected into agent context via bootstrap;
+ * attribution is never surfaced that way, so that scanner doesn't apply
+ * here — deliberately a separate, narrower sanitizer).
+ */
+function sanitizeAttribution(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    const cleaned = raw
+        .replace(/[\x00-\x1F\x7F-\x9F]/g, " ") // strip C0/C1 control chars
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned)
+        return undefined;
+    return cleaned.slice(0, MAX_ATTRIBUTION_LENGTH);
+}
+/**
+ * The INVARIANT response for any syntactically-valid request, regardless of
+ * outcome (fresh increment / already-counted / not-found — see module doc's
+ * "NO ID ENUMERATION"). Deliberately does not report per-id or even
+ * aggregate success counts: for a batch of N ids where one is fake, a
+ * response like `{ recorded: 4, of: 5 }` would let a caller binary-search
+ * which id in a batch doesn't exist just as surely as a per-id breakdown
+ * would. The only externally observable state change is the actual
+ * `usageCount` on a memory the caller is independently authorized to READ
+ * (via Memory.get/search/SemanticSearch) — a SEPARATE, already-scoped call,
+ * never this endpoint.
+ */
+const RECORDED_RESPONSE = { recorded: true };
+export class RecordUsage extends Resource {
+    // Any verified agent may report usage — any further scoping (which memory,
+    // whether it's a dup) is enforced inside post() itself, never here.
+    async allowCreate() {
+        return (await resolveAgentAuth(this.getContext?.())).kind !== "anonymous";
+    }
+    async post(data) {
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        // Usage feedback attributes a contribution to a SPECIFIC agent identity
+        // (the MemoryUsage ledger's dedup key) — a trusted internal call with no
+        // per-agent identity, or an admin acting with no agent context, has
+        // nothing to attribute a contribution TO. Agent-facing only.
+        if (auth.kind !== "agent") {
+            return BAD_REQUEST("usage feedback requires a verified agent identity");
+        }
+        const agentId = auth.agentId;
+        const rl = checkRateLimit(agentId, "usage");
+        if (!rl.allowed)
+            return rateLimitResponse(rl.retryAfterMs, "usage");
+        const rawIds = data?.memoryIds ?? (typeof data?.memoryId === "string" ? [data.memoryId] : undefined);
+        if (!Array.isArray(rawIds) || rawIds.length === 0 || !rawIds.every((id) => typeof id === "string" && id.length > 0)) {
+            return BAD_REQUEST("memoryIds must be a non-empty array of memory id strings");
+        }
+        if (rawIds.length > MAX_IDS_PER_CALL) {
+            return BAD_REQUEST(`memoryIds exceeds the per-call limit of ${MAX_IDS_PER_CALL}`);
+        }
+        const memoryIds = [...new Set(rawIds)]; // dedupe within THIS call too
+        const attribution = sanitizeAttribution(data?.attribution);
+        const now = new Date().toISOString();
+        for (const memoryId of memoryIds) {
+            try {
+                await this._recordOne(ctx, agentId, memoryId, attribution, now);
+            }
+            catch (err) {
+                // Never let one bad id fail the whole batch, and never let an
+                // internal error leak existence information either — log
+                // server-side, collapse to the same no-op the response already
+                // returns for every other outcome.
+                console.error("RecordUsage.post: failed to record usage (treated as no-op)", { memoryId, err });
+            }
+        }
+        // Deliberately does NOT report which ids succeeded / were already
+        // 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 }));
+    }
+}