@tpsdev-ai/flair 0.50.0 → 0.51.1

package/dist/resources/mcp-tools.js

@@ -10,9 +10,10 @@
  * per-source scoping — see resources/AttentionQuery.ts's module doc), so the
  * MCP surface inherits the SAME security model as the signed-REST path. There
  * is no raw CRUD surface — the only way to reach the datastore through /mcp is
- * via one of these 12 semantic tools.
+ * via one of these 14 semantic tools.
  *
  *   memory_search · memory_store · memory_update · memory_get · memory_delete ·
+ *   memory_basement · memory_restore ·
  *   bootstrap · soul_set · soul_get · flair_workspace_set · flair_orgevent ·
  *   attention · record_usage
  *
@@ -37,6 +38,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,
@@ -183,6 +185,10 @@ async function memorySearch(agent, args) {
     // requested so a plain search delegates a byte-identical body.
     if (args?.abstain === true)
         body.abstain = true;
+    // flair#1472 — opt-in basement inclusion. Forwarded ONLY when requested so a
+    // plain search delegates a byte-identical body (archived excluded by default).
+    if (args?.includeArchived === true)
+        body.includeArchived = true;
     return unwrap(await h.post(body));
 }
 async function memoryStore(agent, args) {
@@ -350,6 +356,56 @@ async function memoryUpdate(agent, args) {
     // regenerates the vector server-side); no-op when the response carries none.
     return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
 }
+// ── flair#1472 memory_basement / memory_restore ──────────────────────────────
+// The user-facing archive action. `archived` is a VISIBILITY flag, not a
+// deletion: basementing a memory removes it from bootstrap + default search
+// but leaves the row, its provenance, and its history fully intact (still
+// retrievable via memory_get and memory_search(includeArchived:true)). Restore
+// is the deliberate, GLOBAL inverse — it un-retires the memory for EVERY
+// session, not a session-local view (that is drawers, Deliverable B, which does
+// not exist yet). Both are writes scoped to the caller's own lane: the read
+// uses Memory.get()'s read-scope gate and the write uses Memory.put()'s
+// ownership gate (stampAttribution), so a caller can neither read nor write
+// another agent's memory here.
+async function memoryBasement(agent, args) {
+    const Cls = await handler("Memory");
+    const id = args?.id;
+    const existing = await unwrap(await Cls.get(id, delegationContext(agent)));
+    if (!existing || existing.error != null || existing.status === 404) {
+        return { error: "memory not found", status: 404 };
+    }
+    const merged = {
+        ...existing,
+        archived: true,
+        archivedBy: agent.agentId,
+        updatedAt: new Date().toISOString(),
+    };
+    // Memory.put() stamps archivedAt when archived===true (see Memory.ts). The
+    // content is unchanged, so the existing embedding stays valid — do NOT clear
+    // it (clearing would force a needless re-embed and, if the embedding engine
+    // is unavailable, would silently drop the vector).
+    if (agent.clientId)
+        merged.claimedClient = agent.clientId;
+    return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
+}
+async function memoryRestore(agent, args) {
+    const Cls = await handler("Memory");
+    const id = args?.id;
+    const existing = await unwrap(await Cls.get(id, delegationContext(agent)));
+    if (!existing || existing.error != null || existing.status === 404) {
+        return { error: "memory not found", status: 404 };
+    }
+    const merged = {
+        ...existing,
+        archived: false,
+        updatedAt: new Date().toISOString(),
+    };
+    delete merged.archivedAt;
+    delete merged.archivedBy;
+    if (agent.clientId)
+        merged.claimedClient = agent.clientId;
+    return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
+}
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
     // flair#1181 — by-id reads MUST use the STATIC `Cls.get(id, context)` form,
@@ -538,9 +594,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 }));
 }
 /**
@@ -633,6 +690,7 @@ export const TOOLS = {
                     limit: { type: "number", description: "Max results (default 5)" },
                     includeTrust: { type: "boolean", description: "Attach a per-result trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
                     abstain: { type: "boolean", description: "Opt into first-class abstention: when the best match is below a global confidence threshold, return { abstained: true, reason, bestScore } with no weak matches instead of the N weakest results. Default false." },
+                    includeArchived: { type: "boolean", description: "Include basemented (archived) memories in results. Default false — archived memories are excluded from normal search. When true, archived memories are returned under the SAME read-scope gate as a normal search (never a wider scope)." },
                 },
                 required: ["query"],
             },
@@ -710,6 +768,55 @@ export const TOOLS = {
             errorShape: { trigger: "updating a non-existent id", fields: ["error", "status"] },
         },
     },
+    memory_basement: {
+        def: {
+            name: "memory_basement",
+            description: "Send a memory to the basement (archive it). Sets archived=true and stamps archivedAt. " +
+                "The memory is removed from bootstrap and default search but remains retrievable via " +
+                "memory_get and memory_search(includeArchived:true). Deliberate and GLOBAL — this is a " +
+                "visibility flag, not a deletion: provenance and history are untouched. Scoped to your own memories only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "ID of the memory to basement (archive)" },
+                },
+                required: ["id"],
+            },
+        },
+        impl: memoryBasement,
+        contract: {
+            summary: "Write echo of the archived record { id, archived:true, archivedAt, ... }. No internal embedding fields; the flip round-trips via memory_get.",
+            requiredFields: ["id", "archived"],
+            fieldTypes: { id: "string", archived: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "basementing a non-existent or non-owned id", fields: ["error", "status"] },
+        },
+    },
+    memory_restore: {
+        def: {
+            name: "memory_restore",
+            description: "Restore a basemented (archived) memory. Clears archived and archivedAt. Deliberate and GLOBAL — " +
+                "this un-retires the memory for EVERY session, not a session-local view (per-session reuse is " +
+                "drawers, which do not exist yet). Scoped to your own memories only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "ID of the memory to restore (un-archive)" },
+                },
+                required: ["id"],
+            },
+        },
+        impl: memoryRestore,
+        contract: {
+            summary: "Write echo of the restored record { id, archived:false, ... }. No internal embedding fields; the flip round-trips via memory_get.",
+            requiredFields: ["id", "archived"],
+            fieldTypes: { id: "string", archived: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "restoring a non-existent or non-owned id", fields: ["error", "status"] },
+        },
+    },
     memory_get: {
         def: {
             name: "memory_get",
@@ -1005,12 +1112,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/record-types.js

@@ -361,8 +361,10 @@ export const RECORD_TYPES = {
 //   bootstrap    — Soul + Memory + predicted-context composite (BootstrapMemories)
 //   attention    — cross-table aggregate query (AttentionQuery.ts), not a table verb
 //   record_usage — usage-signal resource (RecordUsage.ts), not a table verb
+//   memory_basement — archive action (flair#1472), not a table verb
+//   memory_restore  — un-archive action (flair#1472), not a table verb
 //
-export const COMPOSITE_MCP_TOOLS = ["bootstrap", "attention", "record_usage"];
+export const COMPOSITE_MCP_TOOLS = ["bootstrap", "attention", "record_usage", "memory_basement", "memory_restore"];
 // ─── Runtime immutability ───────────────────────────────────────────────────
 // Belt-and-suspenders backstop for the "static, compiled" invariant (see
 // header doc). TypeScript's `as const satisfies` already gives compile-time

package/dist/resources/search-readiness.js

@@ -28,6 +28,21 @@
  *     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);
@@ -36,16 +51,14 @@ function routeMounted(resources, name) {
  * Decide whether search is actually usable, and whether /Health should claim
  * the process is healthy.
  *
- * `resources` is optional. Stated fail-open (Sherlock on #1406): 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. In the shipped launch path
- * `/Health` is served by this Resource after Harper has registered us, so
- * `server.resources` is populated; the skip is the injectable/test path
- * (and a theoretical export without a registry). Health.ts logs once if
- * the live call site actually takes it.
+ * `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");
@@ -56,6 +69,13 @@ export function resolveSearchReadiness(opts) {
             ].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");
@@ -78,7 +98,7 @@ export function resolveSearchReadiness(opts) {
             return namesLag("bm25 index not built (cold boot; first search scans the corpus)");
         }
     }
-    return { searchReady: true, ok: true, status: 200 };
+    return { searchReady: true, ok: true, status: 200, searchReadyReason: readyReason };
 }
 function notServing(searchReadyReason) {
     return { searchReady: false, ok: false, status: 503, searchReadyReason };
@@ -94,7 +114,10 @@ export function buildPublicHealthBody(readiness, identity) {
         buildCommit: identity.buildCommit,
         searchReady: readiness.searchReady,
     };
-    if (readiness.searchReadyReason)
+    // 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
@@ -61,6 +63,14 @@ 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;
@@ -87,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
@@ -154,6 +166,7 @@ export async function retrieveCandidates(params) {
                 }
                 semRecords.push(record);
                 semIds.push(record.id);
+                hnswLegIds.push(record.id);
             }
         }
         // ── (b) The BM25 lexical leg ─────────────────────────────────────────
@@ -260,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()) {
@@ -269,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 {
@@ -324,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);
             }
         }
     }
@@ -401,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 {
@@ -447,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
@@ -480,7 +492,9 @@ 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
@@ -495,5 +509,10 @@ export async function retrieveCandidates(params) {
     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/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 };
+}

package/docs/federation.md

@@ -171,6 +171,17 @@ Re-pairing an existing peer (same instance ID, same public key) does not require
 
 Spoke instances can only push records they originated. A spoke cannot overwrite records from another spoke or from the hub. The hub can relay records from any origin.
 
+### Per-record signatures and principalId
+
+Each pushed record carries an Ed25519 signature over a versioned canonical body. `v` lives inside that body so versions are distinguishable: a `v: 1` signature cannot verify as `v: 2`.
+
+- **`v: 1` (today's wire):** signed fields are `{ v, table, id, data, updatedAt, originatorInstanceId }`. Senders did not put `v` on the wire; receivers default absent `v` to `1`. `principalId` may appear on the record (from a Memory provenance stamp) but was not in the signed field set.
+- **`v: 2`:** `principalId` is included in the signed payload when the row has a write-time provenance stamp (`provenance.verified.agentId`). `v` is on the wire.
+
+On apply, after the signature checks, **Memory** (the only principal-owning federated table) requires `principalId` to be present and equal to `data.agentId`. Absent is a skip (`principal_mismatch`), not an accept. Soul, Agent, and Relationship are not in that set and still sync without a principal.
+
+Receivers must be upgraded before senders. A Phase 1 receiver verifies both shapes in one batch. Old receivers cannot reconstruct a `v: 2` body and will skip those records (per-record, not a batch outage) until they upgrade. Optional `FLAIR_FEDERATION_REQUIRE_RECORD_PRINCIPAL=true` skips leftover `v: 1` Memory records that lack `principalId` once the fleet is on `v: 2`.
+
 ### Timestamp ceiling
 
 Records with `updatedAt` more than 5 minutes in the future are rejected. This prevents an attacker from using far-future timestamps to permanently win last-write-wins (LWW) merge conflicts.

package/docs/supply-chain-policy.md

@@ -151,7 +151,7 @@ Mirrors the CI test-unit gates locally so issues are caught at `git commit` time
 Runs three checks before each commit:
 - `check-workspace-deps.mjs` — workspace internal-dep version lockstep
 - `check-dep-ages.mjs` — supply-chain bake-time (≥7 days for external pinned deps)
-- `check-impl-term-leaks.sh` — no Bead refs / impl labels in user-facing docs
+- `check-impl-term-leaks.sh` — no Bead refs / impl labels in user-facing docs, `CHANGELOG.md`, or `.changelog/`
 
 Each check matches a CI gate exactly so the local and remote outcomes can't drift. Bypass with `git commit --no-verify` when warranted (rare; CI will still catch you). Skip just the dep-ages check (the slowest one, ~2-5s of registry fetches) with `FLAIR_PRECOMMIT_SKIP_DEP_AGES=1 git commit`.
 

package/docs/upgrade.md

@@ -65,7 +65,15 @@ actually running:
 - **Post-restart verification** (skip with `--no-verify`) confirms the
   restarted instance answers `/Health`, that an authenticated request
   round-trips, and that the reported running version matches what was just
-  installed.
+  installed. It then runs the same enumerable doctor install-health checks
+  (`flair doctor`'s client-integration catalog, plus launchd management)
+  and prints `✅ verified: healthy` only when every check ran and none
+  failed. A missing Codex SessionStart hook — which `flair init` before
+  0.50.0 never wrote — is one of those checks. Installing the hook is
+  consent-bearing (it executes at every session start): an interactive
+  upgrade prompts; a non-interactive upgrade states the gap and withholds
+  ✅. Pass `--install-hooks` to consent without a prompt, then `flair
+  doctor` exits 0.
 - **On a failed restart OR a failed verification**, `flair upgrade`
   automatically reinstalls the previously-running `@tpsdev-ai/flair` version,
   restarts again, and re-verifies — then exits nonzero with a clear report of
@@ -517,6 +525,14 @@ The backwards-boot refusal (flair#1049) catches this: the old binary refuses to
 naming both versions and the data directory, with recovery instructions. A pre-upgrade
 snapshot exists at the named path. Restoring it returns the store to a working state.
 
+**Patch-level break inside 5.2:** Harper 5.2.7 writes LZ4-compressed RocksDB that
+Harper 5.2.0 cannot open (`LZ4 not supported in this build`). Downgrade from a
+5.2.7-written store to the npm-published 5.2.0 pin is forward-only — same
+recovery as the 5.1 → 5.2 break: `flair snapshot restore <path>`. The
+`downgrade-boot` suite treats that Harper crash as the loud-refusal branch of
+the flair#1050 invariant (it boots Harper via `startHarper`, so the CLI stamp
+phrasing is not on that path).
+
 **As observed when this suite was added (2026-07-08):** the npm-published baseline
 (0.21.0) boots cleanly against data written by a HEAD build roughly 14 commits ahead of
 it (several security-hardening and CLI-behavior changes, no Flair schema migration, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.50.0",
+  "version": "0.51.1",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -65,7 +65,7 @@
     "@harperfast/oauth": "2.5.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
-    "harper": "5.2.0",
+    "harper": "5.2.7",
     "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
     "js-yaml": "^4.3.1",

package/schemas/federation.graphql

@@ -58,7 +58,7 @@ type SyncLog @table(database: "flair") {
   direction: String! @indexed      # "push" | "pull"
   recordCount: Int                 # how many records merged in this batch
   skippedCount: Int                # how many records skipped (sum of skippedReasons)
-  skippedReasons: String           # JSON: { unknown_table: N, non_originator: N, future_timestamp: N, no_op_same_hash: N, merge_error: N }
+  skippedReasons: String           # JSON: { unknown_table: N, non_originator: N, future_timestamp: N, no_op_same_hash: N, merge_error: N, unknown_originator_key: N, invalid_signature: N, missing_signature: N, principal_mismatch: N }
   status: String @indexed          # "success" | "partial" | "failed"
   error: String                    # human-readable summary if partial/failed (includes per-record error messages, capped)
   durationMs: Int                  # how long the sync took