@tpsdev-ai/flair 0.50.0 → 0.51.0

package/dist/resources/SemanticSearch.js

@@ -61,7 +61,7 @@ export class SemanticSearch extends Resource {
         // recall-harness (test/bench/recall-harness/run.ts) and `recall-eval.mjs`
         // before reconsidering this default if the compositeScore formula or
         // corpus changes.
-        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, includeMetadata = false, abstain = false, explain = false } = data || {};
+        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, includeMetadata = false, abstain = false, explain = false, includeLegs = false } = data || {};
         // Authenticated identity lives on the Harper Resource context (getContext().request).
         // `this.request` is NOT populated on Harper v5 Resources — prior reads here
         // silently returned undefined and the defense-in-depth scope check below
@@ -215,6 +215,7 @@ export class SemanticSearch extends Resource {
         // composite re-scoring headroom to reorder before the final slice.
         const candidateLimit = limit * CANDIDATE_MULTIPLIER;
         const ctx = this.getContext?.();
+        let legs;
         const filteredResults = await retrieveCandidates({
             queryEmbedding: qEmb,
             q,
@@ -230,6 +231,7 @@ export class SemanticSearch extends Resource {
             isAllowed: scope?.isAllowed,
             hybrid,
             ctx,
+            onLegs: includeLegs ? (l) => { legs = l; } : undefined,
             // flair#744 slice 1: the trust block needs `provenance`, which the
             // default projection omits. Widen the select ONLY when the caller opts
             // in — passing undefined otherwise keeps the default (no `provenance`)
@@ -330,6 +332,11 @@ export class SemanticSearch extends Resource {
         if (!qEmb && q && getMode() === "none") {
             response._warning = "semantic search unavailable — results are keyword-only";
         }
+        // flair#1358: opt-in per-leg candidate ids for the bench instrument.
+        // Default OFF ⇒ response is byte-identical (no `legs` key). The ranked
+        // `results` slice is unchanged either way — this is observation only.
+        if (includeLegs && legs)
+            response.legs = legs;
         return response;
     }
 }

package/dist/resources/federation-classify.js

@@ -5,6 +5,96 @@
  * spinning up Harper's database module. The same SkipReason names are used
  * in SyncLog.skippedReasons so operators can grep for them.
  */
+/**
+ * Static policy for every table FederationSync will merge.
+ *
+ * Lives next to SkipReason / SyncRecord so the principal-owning decision is
+ * one visible list, not a condition scattered through the apply path.
+ * `Federation.ts` types its `tableMap` as `Record<FederationSyncTable, …>`,
+ * so adding a federated table without deciding `principalOwning` here is a
+ * type error rather than a silent default.
+ *
+ * Scope the principalId requirement by TABLE, never by field presence.
+ * Memory carries agentId / a provenance stamp; Soul, Agent, and
+ * Relationship do not, and will legitimately have no principalId.
+ */
+export const FEDERATION_TABLE_POLICY = {
+    Memory: { principalOwning: true },
+    Soul: { principalOwning: false },
+    Agent: { principalOwning: false },
+    Relationship: { principalOwning: false },
+};
+export const FEDERATION_SYNC_TABLES = Object.keys(FEDERATION_TABLE_POLICY);
+export const PRINCIPAL_OWNING_TABLES = new Set(FEDERATION_SYNC_TABLES.filter((t) => FEDERATION_TABLE_POLICY[t].principalOwning));
+/** Wire `v` when present; assume 1 when absent (today's records omit it). */
+export function recordSignatureVersion(record) {
+    return record.v ?? 1;
+}
+/**
+ * Rebuild the object FederationSync verifies against the originator's key.
+ *
+ * Load-bearing details, both of which fail every existing record if missed:
+ *
+ * 1. `v` is not on the wire today. The push side signs a body containing
+ *    `v: 1` but sends a SyncRecord without it. Verification works today
+ *    only because the receiver pinned the same literal. Default it.
+ *    Apply `v` AFTER the spread so an absent/undefined `record.v` cannot
+ *    overwrite the default.
+ *
+ * 2. `principalId` IS on the wire today for some records, but it is
+ *    attached AFTER signing (informational). Spreading it into a v:1
+ *    verify body changes the field set and fails those records. v:1
+ *    therefore strips it; v:2 signs it, so it stays.
+ *
+ * `originatorInstanceId` is the classifyRecord originator (same override
+ * the pre-3a hardcoded reconstruction used), not a blind spread of the
+ * wire field.
+ */
+export function reconstructRecordVerifyBody(record, originator) {
+    const v = recordSignatureVersion(record);
+    const { signature, v: _wireV, principalId, ...payload } = record;
+    const verifyPayload = v >= 2 && principalId !== undefined ? { ...payload, principalId } : payload;
+    return {
+        ...verifyPayload,
+        v,
+        originatorInstanceId: originator,
+        signature,
+    };
+}
+/**
+ * Per-record principal entitlement — apply-site check, DB-free.
+ *
+ * Table in PRINCIPAL_OWNING_TABLES → principalId is mandatory on v:2
+ * (absent is a skip, mismatched is a skip). Table not in the set →
+ * principalId is not consulted at all.
+ *
+ * Does not load Agent, does not read originatorInstanceId off an Agent
+ * row. The record's own stamp is the binding.
+ *
+ * `enforceV1Principal` is Phase 3 (FLAIR_FEDERATION_REQUIRE_RECORD_PRINCIPAL):
+ * skip leftover v:1 records on principal-owning tables that lack
+ * principalId. Off by default — v:1 Memory keeps merging until an
+ * operator flips the flag after the fleet is on v:2.
+ */
+export function checkPrincipalEntitlement(record, opts = {}) {
+    if (!PRINCIPAL_OWNING_TABLES.has(record.table)) {
+        return null;
+    }
+    const v = recordSignatureVersion(record);
+    if (v >= 2) {
+        if (typeof record.principalId !== "string" ||
+            record.principalId.length === 0 ||
+            record.principalId !== record.data?.agentId) {
+            return "principal_mismatch";
+        }
+        return null;
+    }
+    if (opts.enforceV1Principal &&
+        (typeof record.principalId !== "string" || record.principalId.length === 0)) {
+        return "principal_mismatch";
+    }
+    return null;
+}
 export function classifyRecord(record, peerRole, receiverInstanceId, local, knownTables, now = new Date()) {
     if (!knownTables.has(record.table)) {
         return { action: "skip", reason: "unknown_table" };

package/dist/resources/health.js

@@ -121,22 +121,18 @@ export class Health extends Resource {
     }
 }
 /** Same sources /Health and /HealthDetail consult so they cannot disagree. */
-let _warnedMissingRegistry = false;
-function currentSearchReadiness() {
-    // Shipped Harper launch: this Resource is already registered, so
-    // server.resources is populated. The null skip is a stated fail-open
-    // (Sherlock on #1406) for the injectable/test path — not an accident.
+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;
-    if (!resources && !_warnedMissingRegistry) {
-        _warnedMissingRegistry = true;
-        logger.warn?.("Health: server.resources is absent — skipping the search-route mount check (table-only fail-open). Shipped Harper launch always exposes the registry.");
-    }
     return resolveSearchReadiness({
         resources,
         memoryTable: db.flair?.Memory,
         bm25: bm25IndexStatus(),
         hybridEnabled: hybridEnabled(),
         bm25IndexEnabled: bm25IndexEnabled(),
+        warn: (message) => { logger.warn?.(message); },
     });
 }
 /**
@@ -168,7 +164,10 @@ export class HealthDetail extends Resource {
         // and a warning name the lag so `flair status` / operators can see it.
         const readiness = currentSearchReadiness();
         stats.searchReady = readiness.searchReady;
-        if (readiness.searchReadyReason) {
+        // 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 });
         }

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 }));
 }
 /**
@@ -1005,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

@@ -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.0",
   "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