@tpsdev-ai/flair 0.49.0 → 0.51.0

package/dist/resources/health.js

@@ -1,4 +1,4 @@
-import { Resource, databases } from "harper";
+import { Resource, databases, server, logger } from "harper";
 import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, dirname } from "node:path";
@@ -8,6 +8,9 @@ import { resolveBuildInfo } from "./build-info.js";
 import { getMigrationStatusSnapshot } from "./migrations/status.js";
 import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
+import { hybridEnabled } from "./bm25.js";
+import { bm25IndexEnabled, bm25IndexStatus } from "./bm25-index-service.js";
+import { buildPublicHealthBody, resolveSearchReadiness } from "./search-readiness.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -52,7 +55,7 @@ function resolveVersion() {
     return process.env.npm_package_version ?? "dev";
 }
 /**
- * Health endpoint — truly public, returns only { ok: true }.
+ * Health endpoint — truly public. Identity-free; no auth, no role check.
  *
  * `allowRead() { return true }` opens Harper's role gate for anonymous GETs,
  * which is what makes /Health work for callers outside `authorizeLocal`'s
@@ -66,8 +69,15 @@ function resolveVersion() {
  *
  * Same pattern as `FederationPair.allowCreate(){ return true }` (PR #299):
  * declare the Resource anonymously-accessible at the Harper layer; let the
- * handler itself enforce whatever it needs (in this case, nothing — /Health
- * is intentionally and always public).
+ * handler itself enforce whatever it needs.
+ *
+ * flair#1326: `ok: true` used to mean only "this resource answered." That
+ * is a green light that lies when search routes are not mounted yet, or
+ * when the hybrid BM25 index is still cold (first search after restart
+ * scans the corpus; the lag grows with store size). `searchReady` is
+ * always present. When search cannot be served at all, this endpoint
+ * returns HTTP 503 and `ok: false`. When the process is live but recall
+ * is still cold, it stays 200 and names the lag on `searchReadyReason`.
  *
  * Rich stats (memory counts, agent names, etc.) are behind /HealthDetail
  * which requires authentication. This prevents information leakage on
@@ -96,13 +106,35 @@ export class Health extends Resource {
         // a 40-hex sha when the build ran in a git work tree, an honest null
         // otherwise (tarball builds) — never omitted, never fabricated (Sherlock).
         const build = resolveBuildInfo();
-        return {
-            ok: true,
+        const readiness = currentSearchReadiness();
+        const body = buildPublicHealthBody(readiness, {
             version: build?.version ?? resolveVersion(),
             buildCommit: build?.commit ?? null,
-        };
+        });
+        if (readiness.status !== 200) {
+            return new Response(JSON.stringify(body), {
+                status: readiness.status,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        return body;
     }
 }
+/** Same sources /Health and /HealthDetail consult so they cannot disagree. */
+export function currentSearchReadiness() {
+    // Fail-open when the registry is missing (Sherlock on #1406 / flair#1411):
+    // do not 503 forever. resolveSearchReadiness warns once and names the
+    // degradation; we do not treat "registry should always be here" as a given.
+    const resources = server.resources ?? null;
+    return resolveSearchReadiness({
+        resources,
+        memoryTable: db.flair?.Memory,
+        bm25: bm25IndexStatus(),
+        hybridEnabled: hybridEnabled(),
+        bm25IndexEnabled: bm25IndexEnabled(),
+        warn: (message) => { logger.warn?.(message); },
+    });
+}
 /**
  * Authenticated health detail — returns memory/agent/soul stats + process info.
  * Requires Ed25519 agent auth or admin basic auth.
@@ -127,6 +159,18 @@ export class HealthDetail extends Resource {
         const stats = { ok: true };
         const nowMs = Date.now();
         const warnings = [];
+        // flair#1326: same search-ready signal as public /Health. HealthDetail
+        // stays HTTP 200 (it is a stats dump, not a traffic gate); the field
+        // and a warning name the lag so `flair status` / operators can see it.
+        const readiness = currentSearchReadiness();
+        stats.searchReady = readiness.searchReady;
+        // Public/detail shape is unchanged: searchReadyReason stays a lag signal
+        // (present iff !searchReady). Ready-path verification constants stay on
+        // the decision object (flair#1411).
+        if (!readiness.searchReady && readiness.searchReadyReason) {
+            stats.searchReadyReason = readiness.searchReadyReason;
+            warnings.push({ level: "warn", message: readiness.searchReadyReason });
+        }
         const ctx = this.getContext?.();
         // #614 fix: resolve identity via the shared three-way verdict
         // (internal/agent/anonymous — agent-auth.ts) instead of reading

package/dist/resources/mcp-tools.js

@@ -37,6 +37,7 @@
  */
 import { resolveVersion } from "./version.js";
 import { agentContext, adminContext, collectionResource } from "./in-process.js";
+import { RECORD_USAGE_ID_MERGE_CONTRACT, unionUsageMemoryIds } from "./usage-ids.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -538,9 +539,10 @@ async function attention(agent, args) {
 async function recordUsage(agent, args) {
     const Cls = await handler("RecordUsage");
     const h = new Cls(undefined, delegationContext(agent));
-    const memoryIds = Array.isArray(args?.memoryIds)
-        ? args.memoryIds
-        : typeof args?.memoryId === "string" ? [args.memoryId] : undefined;
+    // flair#1410: MERGE, do not prefer. The previous ternary dropped
+    // `memoryId` whenever `memoryIds` was an array (including `[]`).
+    const merged = unionUsageMemoryIds(args?.memoryId, args?.memoryIds);
+    const memoryIds = merged.length > 0 ? merged : undefined;
     return unwrap(await h.post({ memoryIds, attribution: args?.attribution }));
 }
 /**
@@ -811,6 +813,7 @@ export const TOOLS = {
                     { count: "memoriesIncluded", containers: ["memories", "predicted"] }, // #1199
                     { count: "teammateFindingsIncluded", containers: ["teammateFindings"] }, // #1199
                     { count: "sections.events", containers: ["events"] }, // #1206
+                    { count: "sections.soul", containers: ["soul"] }, // #1371
                 ],
                 // present + typed even when empty — never a bare {} / missing key (#1182).
                 selfDescribingEmpty: [
@@ -1004,12 +1007,13 @@ export const TOOLS = {
             name: "record_usage",
             description: "Report that one or more memories were actually USED — cited or relied on to ground an answer or decision. " +
                 "Distinct from search (surfacing a memory is not usage). Drives the recall-quality usage signal; dedup'd " +
-                "(you can only count once per memory) and rate-limited.",
+                "(you can only count once per memory) and rate-limited. " +
+                RECORD_USAGE_ID_MERGE_CONTRACT,
             inputSchema: {
                 type: "object",
                 properties: {
-                    memoryIds: { type: "array", items: { type: "string" }, description: "IDs of the memories that were used (max 20 per call)" },
-                    memoryId: { type: "string", description: "Convenience alias for a single memory id (use memoryIds for multiple)" },
+                    memoryIds: { type: "array", items: { type: "string" }, description: "IDs of the memories that were used (max 20 per call). Merged with memoryId when both are supplied." },
+                    memoryId: { type: "string", description: "Convenience alias for a single memory id. Merged with memoryIds when both are supplied — not dropped." },
                     attribution: { type: "string", description: "Optional free-text note on what used it (opaque — stored for audit only, max 500 chars)" },
                 },
             },

package/dist/resources/search-readiness.js

@@ -0,0 +1,123 @@
+/**
+ * search-readiness.ts — the honest /Health search-ready signal (flair#1326).
+ *
+ * Harper's process can answer /health (and Flair's /Health resource can
+ * answer {ok:true}) while search is still unusable:
+ *
+ *   1. Boot window — jsResources register incrementally. /Health can be up
+ *      while /Memory and /SemanticSearch still 404 from Harper's catch-all
+ *      (documented in packages/adk-flair-js/test/helpers/boot-harper.mjs).
+ *   2. Cold BM25 index — hybrid retrieval's persistent index is lazy-built
+ *      on the first search, not at component start (bm25-index-service.ts).
+ *      That first-query corpus scan grows with store size. /Health answering
+ *      is not "recall is warm."
+ *
+ * This module is Harper-free so the decision is unit-testable against the
+ * shipped function. Callers inject the registry / table / index status they
+ * already have.
+ *
+ * Two layers, on purpose:
+ *   - Routes/table not mounted → not healthy (ok:false, HTTP 503). A
+ *     traffic-gating probe that only looks at status must not get a green
+ *     light for a node whose search routes are not serving.
+ *   - Routes up but index still cold → process is live (ok:true, HTTP 200)
+ *     and searchReady:false names the lag. We do NOT 503 on a cold index:
+ *     the index builds on the first search, and a health check must not
+ *     trigger that scan (bm25-index-service.ts: "Eager building would add a
+ *     full corpus scan to every boot including … health checks"). 503-until-
+ *     warm would deadlock — health waits for the index, the index waits for
+ *     a search that never comes.
+ */
+/**
+ * How a ready result was verified. Constant strings — no interpolation
+ * (flair#1411). Public /Health still omits this field when searchReady is
+ * true; the values live on the decision object so a caller of
+ * resolveSearchReadiness can tell registry-verified from table-only.
+ */
+export const SEARCH_READY_REASON_VERIFIED_VIA_ROUTE_REGISTRY = "verified via route registry";
+export const SEARCH_READY_REASON_REGISTRY_UNAVAILABLE_TABLE_ONLY = "registry unavailable, table check only";
+/** Once-warn when the route-mount check is skipped (flair#1411). */
+export const MISSING_REGISTRY_WARN = "search route-mount verification is degraded; searchReady now rests on the table check alone";
+let warnedMissingRegistry = false;
+/** Test-only: forget the one-shot missing-registry warning. */
+export function _resetMissingRegistryWarnForTests() {
+    warnedMissingRegistry = false;
+}
+function routeMounted(resources, name) {
+    const entry = resources.get?.(name) ?? resources.getMatch?.(name);
+    return Boolean(entry?.Resource);
+}
+/**
+ * Decide whether search is actually usable, and whether /Health should claim
+ * the process is healthy.
+ *
+ * `resources` is optional. Stated fail-open (Sherlock on #1406 / flair#1411):
+ * when the registry is missing we skip the route-mount check rather than
+ * 503 forever. A table handle can exist while `/Memory` and `/SemanticSearch`
+ * still 404, so this is weaker than the primary defense. We do not fail
+ * closed. We warn once and name the degradation on `searchReadyReason`.
+ */
+export function resolveSearchReadiness(opts) {
+    let readyReason = SEARCH_READY_REASON_REGISTRY_UNAVAILABLE_TABLE_ONLY;
+    if (opts.resources) {
+        const memoryMounted = routeMounted(opts.resources, "Memory");
+        const searchMounted = routeMounted(opts.resources, "SemanticSearch");
+        if (!memoryMounted || !searchMounted) {
+            const missing = [
+                !memoryMounted ? "Memory" : null,
+                !searchMounted ? "SemanticSearch" : null,
+            ].filter(Boolean).join(", ");
+            return notServing(`search routes not mounted (${missing})`);
+        }
+        readyReason = SEARCH_READY_REASON_VERIFIED_VIA_ROUTE_REGISTRY;
+    }
+    else {
+        if (!warnedMissingRegistry) {
+            warnedMissingRegistry = true;
+            opts.warn?.(MISSING_REGISTRY_WARN);
+        }
+    }
+    if (!opts.memoryTable || typeof opts.memoryTable.search !== "function") {
+        return notServing("memory table not queryable");
+    }
+    // Hybrid + the persistent index are default-on. A cold or in-flight BM25
+    // index means the first search will pay a full corpus scan — the #1326
+    // lag. Name it; do not fail liveness.
+    //
+    // `disabled` (feed/build failure) and `FLAIR_BM25_INDEX=false` both fall
+    // back to the per-query scan. The kill switch never calls ensureReady, so
+    // status stays `empty` for the life of the process — that is serving, not
+    // cold. Treating it as lag would make searchReady false forever and refuse
+    // a node that is already answering recall.
+    const indexInPath = opts.hybridEnabled !== false && opts.bm25IndexEnabled !== false;
+    if (indexInPath && opts.bm25) {
+        if (opts.bm25.state === "building") {
+            return namesLag("bm25 index building — first search is still scanning the corpus");
+        }
+        if (opts.bm25.state === "empty") {
+            return namesLag("bm25 index not built (cold boot; first search scans the corpus)");
+        }
+    }
+    return { searchReady: true, ok: true, status: 200, searchReadyReason: readyReason };
+}
+function notServing(searchReadyReason) {
+    return { searchReady: false, ok: false, status: 503, searchReadyReason };
+}
+function namesLag(searchReadyReason) {
+    return { searchReady: false, ok: true, status: 200, searchReadyReason };
+}
+/** Public /Health JSON body. `searchReady` is always present (never omitted). */
+export function buildPublicHealthBody(readiness, identity) {
+    const body = {
+        ok: readiness.ok,
+        version: identity.version,
+        buildCommit: identity.buildCommit,
+        searchReady: readiness.searchReady,
+    };
+    // Public shape is unchanged: searchReadyReason is still present iff !searchReady.
+    // Ready-path verification constants stay on the decision object (flair#1411).
+    if (!readiness.searchReady && readiness.searchReadyReason) {
+        body.searchReadyReason = readiness.searchReadyReason;
+    }
+    return body;
+}

package/dist/resources/semantic-retrieval-core.js

@@ -34,9 +34,11 @@
 // multiplies `limit` internally; any overfetch policy — SemanticSearch's
 // CANDIDATE_MULTIPLIER, MemoryBootstrap's K formula — is the CALLER's
 // decision, made
-// before calling in). Never exposes which internal leg (BM25+RRF hybrid vs.
-// legacy HNSW-only vs. keyword-only fallback) produced a given result — the
-// output shape is identical regardless of `hybrid`.
+// before calling in). The result array never annotates which internal leg
+// (BM25+RRF hybrid vs. legacy HNSW-only vs. keyword-only fallback) produced
+// a given row — that output shape is identical regardless of `hybrid`.
+// Per-leg membership is available only through the opt-in `onLegs`
+// callback (flair#1358); unset ⇒ the return is byte-identical to before.
 //
 // ── SCORE CONTRACT (flair#985) ───────────────────────────────────────────────
 // `_score` under `scoring:"raw"` is ALWAYS an ABSOLUTE similarity (cosine of
@@ -60,6 +62,15 @@ import { compositeScore } from "./scoring.js";
 import { buildBM25, fuseRrfNormalized, SEM_LIMIT } from "./bm25.js";
 import { isAllowedBm25Candidate } from "./bm25-filter.js";
 import { indexedBm25Ids } from "./bm25-index-service.js";
+import { byRecencyThenId } from "./sort-comparators.js";
+/**
+ * The only way a row enters the ranked pool. `_rank` is a required
+ * argument — not an object property that `...any` can swallow — so a
+ * push site that omits it is a compile error (flair#1415).
+ */
+function pushRanked(rows, row, _rank) {
+    rows.push({ ...row, _rank });
+}
 // Convert HNSW cosine distance (1 - similarity) to similarity score.
 function distanceToSimilarity(distance) {
     return 1 - distance;
@@ -86,10 +97,12 @@ export const DEFAULT_SELECT = ["id", "agentId", "content", "contentHash", "visib
     "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject", "summary",
     "validFrom", "validTo", "_safetyFlags"];
 export async function retrieveCandidates(params) {
-    const { queryEmbedding: qEmb, q, conditions, limit, select = DEFAULT_SELECT, includeSuperseded = false, scoring = "raw", temporalBoost = 1.0, sinceDate = null, asOf, minScore = 0, agentId, isAllowed, hybrid, ctx, withSemSimilarity = false, } = params;
+    const { queryEmbedding: qEmb, q, conditions, limit, select = DEFAULT_SELECT, includeSuperseded = false, scoring = "raw", temporalBoost = 1.0, sinceDate = null, asOf, minScore = 0, agentId, isAllowed, hybrid, ctx, withSemSimilarity = false, onLegs, } = params;
     const passesAllowed = (record) => !isAllowed || isAllowed(record);
     const hnswSelect = [...select, "$distance"];
     const results = [];
+    const hnswLegIds = [];
+    const bm25LegIds = [];
     if (hybrid) {
         // ─── BM25 + union-RRF hybrid path ────────────────────────────────────
         // 1. Semantic candidates via HNSW (unchanged fetch). 2. BM25 lexical pass
@@ -153,6 +166,7 @@ export async function retrieveCandidates(params) {
                 }
                 semRecords.push(record);
                 semIds.push(record.id);
+                hnswLegIds.push(record.id);
             }
         }
         // ── (b) The BM25 lexical leg ─────────────────────────────────────────
@@ -259,6 +273,8 @@ export async function retrieveCandidates(params) {
             }
             bm25Ids = resolved;
         }
+        if (q)
+            bm25LegIds.push(...bm25Ids);
         // ── (d) No retrieval signal at all → full scoped listing ────────────
         if (!q && !qEmb) {
             for (const record of allowedById.values()) {
@@ -268,14 +284,13 @@ export async function retrieveCandidates(params) {
                     finalScore *= temporalBoost;
                 const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
                 const source = record.agentId !== agentId ? record.agentId : undefined;
-                results.push({
+                pushRanked(results, {
                     ...record,
                     content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                     _source: source,
-                    _rank: finalScore,
-                });
+                }, finalScore);
             }
         }
         else {
@@ -323,22 +338,21 @@ export async function retrieveCandidates(params) {
                     finalScore *= temporalBoost;
                 const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
                 const source = record.agentId !== agentId ? record.agentId : undefined;
-                results.push({
+                // Ordering key: fused rank for raw mode; composite value for
+                // composite mode (composite ordering is unchanged by #985 — its
+                // rrfRaw input and result order are exactly the pre-#985 behavior).
+                pushRanked(results, {
                     ...record,
                     content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                     _source: source,
-                    // Ordering key: fused rank for raw mode; composite value for
-                    // composite mode (composite ordering is unchanged by #985 — its
-                    // rrfRaw input and result order are exactly the pre-#985 behavior).
-                    _rank: scoring === "raw" ? rrfRaw : finalScore,
                     // flair#744 slice 2: the opt-in absolute-confidence field for the
                     // abstention decision. Attach remains OPT-IN so non-abstain
                     // responses stay byte-identical (the capture above is now
                     // unconditional, but the response field is not).
                     ...(withSemSimilarity && semSim !== undefined ? { _semSimilarity: semSim } : {}),
-                });
+                }, scoring === "raw" ? rrfRaw : finalScore);
             }
         }
     }
@@ -400,15 +414,15 @@ export async function retrieveCandidates(params) {
             // flair#744 slice 2: the absolute cosine (`semanticScore`, pre keyword
             // bump) is the abstention confidence signal on this legacy/bootstrap
             // (HNSW-leg-only) path.
-            results.push({
+            pushRanked(results, {
                 ...rest,
                 content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
-                _rank: finalScore,
                 ...(withSemSimilarity ? { _semSimilarity: semanticScore } : {}),
-            });
+            }, finalScore);
+            hnswLegIds.push(record.id);
         }
     }
     else {
@@ -446,14 +460,13 @@ export async function retrieveCandidates(params) {
                 finalScore *= temporalBoost;
             const isFlagged = rest._safetyFlags && Array.isArray(rest._safetyFlags) && rest._safetyFlags.length > 0;
             const source = record.agentId !== agentId ? record.agentId : undefined;
-            results.push({
+            pushRanked(results, {
                 ...rest,
                 content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
-                _rank: finalScore,
-            });
+            }, finalScore);
         }
     }
     // Build superseded set and filter (unless caller opts in to see full
@@ -479,13 +492,27 @@ export async function retrieveCandidates(params) {
     }
     // Order by the internal ranking key (fused RRF rank on the hybrid raw path;
     // identical to `_score` everywhere else), then strip it — `_rank` is an
-    // ordering key, never part of the response shape. Note the hybrid raw
+    // ordering key, never part of the response shape. Required on
+    // RetrievalRankedRow / pushRanked (flair#1415) so a missing value cannot
+    // silently NaN this comparator into the recency tail. Note the hybrid raw
     // ordering is deliberately NOT by `_score`: the recall win of hybrid
     // retrieval lives in the fused ORDER (a BM25 rank-1 rescue outranks weak
     // semantic hits), while `_score` carries the honest absolute evidence for
     // each result — the two can disagree, and that is correct.
-    filteredResults.sort((a, b) => b._rank - a._rank);
+    //
+    // Ties at this sort are cross-leg RRF identities (flair#1412): no
+    // within-leg tie-break can prevent `1/(k+3)+1/(k+5) === 1/(k+5)+1/(k+3)`.
+    // Break them by createdAt DESC (null → oldest, never NaN) then id ASC.
+    // Determinism is the id ASC total order. createdAt is best-effort recency
+    // within an exact `_rank` tie — federated writer clocks can skew, and
+    // that cannot reintroduce nondeterminism (see byRecencyThenId).
+    filteredResults.sort((a, b) => (b._rank - a._rank) || byRecencyThenId(a, b));
     for (const r of filteredResults)
         delete r._rank;
+    onLegs?.({
+        hnsw: hnswLegIds,
+        bm25: bm25LegIds,
+        fused: filteredResults.map((r) => r.id),
+    });
     return filteredResults;
 }

package/dist/resources/sort-comparators.js

@@ -0,0 +1,45 @@
+/**
+ * Deterministic sort comparators (flair#1412).
+ *
+ * Retrieval and selection sorts used to key on one number (score, rank,
+ * priority) and then inherit `Array.prototype.sort`'s input order on ties.
+ * That input order is Harper scan order, which is free to change across
+ * restarts. The family below makes the tie-break the default thing to
+ * reach for: each helper has its own primary key, and they share the
+ * `compareKey` tail — not one comparator forced onto every site.
+ *
+ * Do not collapse this into a single `byScoreThenId`. cosine.ts keys on
+ * corpus `.index`; MemoryBootstrap (flair#1409, not this PR) keys on the
+ * soul `key`. The shared part is the tail.
+ *
+ * Locale-independent: `compareKey` is code-unit / numeric `<`/`>`, never
+ * `localeCompare`. ISO-8601 UTC strings compare chronologically that way.
+ */
+/** Total-order tail. Works for ids, corpus indexes, soul keys. */
+export function compareKey(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Score / rank descending, then `id` ascending. */
+export function byNumberDescThenId(getNumber) {
+    return (a, b) => (getNumber(b) - getNumber(a)) || compareKey(a.id, b.id);
+}
+/**
+ * `createdAt` DESC (null → oldest, never NaN) then `id` ASC.
+ *
+ * Determinism comes from `id` ASC — ids are unique, so this is a total
+ * order no matter what `createdAt` does. Do not date-arithmetic a
+ * possibly-null field: `new Date(null).getTime()` is 0, but subtracting
+ * NaN (unparseable / missing-after-coercion) is undefined behaviour for
+ * `Array.prototype.sort`. Empty-string fallback keeps the comparison in
+ * string space; an empty value is less than any ISO-8601 UTC timestamp,
+ * so it sorts last under DESC.
+ *
+ * Clock-skew caveat: `createdAt` is writer-stamped. Across federated
+ * writers this is best-effort recency within an exact `_rank` tie, not a
+ * correctness claim. Skew can misorder rows the ranker already called
+ * equivalent; it cannot reintroduce nondeterminism, because `id` ASC
+ * still resolves every remaining tie.
+ */
+export function byRecencyThenId(a, b) {
+    return compareKey(b.createdAt ?? "", a.createdAt ?? "") || compareKey(a.id, b.id);
+}

package/dist/resources/usage-ids.js

@@ -0,0 +1,63 @@
+/**
+ * usage-ids.ts — which memory ids a usage-feedback call credits (flair#1410).
+ *
+ * `record_usage` / `POST /RecordUsage` accept both singular `memoryId` and
+ * plural `memoryIds`. MERGE, not prefer: a caller who supplies both means
+ * both. Preferring `memoryIds` (`data?.memoryIds ?? [data?.memoryId]`)
+ * silently dropped the singular id — quiet data loss, same class as
+ * #1206 / #1371.
+ *
+ * Pure: no Harper. Native `/mcp` (`resources/mcp-tools.ts`) and the HTTP
+ * endpoint (`resources/RecordUsage.ts`) both call this so the credited set
+ * does not depend on every client flattening first. Stdio `flair-mcp`
+ * merges independently in `buildRecordUsageBody`; the conformance test
+ * pins the two surfaces to the same set.
+ */
+/** Stated on both MCP tool schemas so a caller can predict the merge without reading source. */
+export const RECORD_USAGE_ID_MERGE_CONTRACT = "When both memoryId and memoryIds are supplied they are merged (union, then deduped) — a caller who passes both means both.";
+/**
+ * Union `memoryId` + `memoryIds`, then dedupe. Empty / non-string entries
+ * in the plural list are skipped (same filter as stdio `buildRecordUsageBody`).
+ * Used by native `/mcp` to flatten the tool args before `RecordUsage.post`.
+ */
+export function unionUsageMemoryIds(memoryId, memoryIds) {
+    const ids = [];
+    if (Array.isArray(memoryIds)) {
+        for (const id of memoryIds) {
+            if (typeof id === "string" && id.length > 0)
+                ids.push(id);
+        }
+    }
+    if (typeof memoryId === "string" && memoryId.length > 0) {
+        ids.push(memoryId);
+    }
+    return [...new Set(ids)];
+}
+/**
+ * HTTP-endpoint resolver: union both fields, then apply RecordUsage.post()'s
+ * existing validation (non-empty strings, per-call cap on the unique credited
+ * set). Cap after dedupe so an overlapping `memoryId` does not 400 a legal
+ * unique set that native `/mcp` and stdio already accept. A present-but-invalid
+ * `memoryIds` still 400s. The max-20 anti-gaming bound is unchanged — it
+ * limits unique ids credited, not raw concatenation length.
+ */
+export function resolveRecordUsageIds(data, maxIds) {
+    const memoryIds = data?.memoryIds;
+    const memoryId = data?.memoryId;
+    if (memoryIds != null) {
+        if (!Array.isArray(memoryIds) || !memoryIds.every((id) => typeof id === "string" && id.length > 0)) {
+            return { ok: false, error: "invalid" };
+        }
+    }
+    const raw = [];
+    if (Array.isArray(memoryIds))
+        raw.push(...memoryIds);
+    if (typeof memoryId === "string" && memoryId.length > 0)
+        raw.push(memoryId);
+    if (raw.length === 0)
+        return { ok: false, error: "empty" };
+    const ids = [...new Set(raw)];
+    if (ids.length > maxIds)
+        return { ok: false, error: "cap" };
+    return { ok: true, ids };
+}