@tpsdev-ai/flair 0.50.0 → 0.51.1

package/dist/lib/upgrade-migrations.js

@@ -0,0 +1,181 @@
+/**
+ * upgrade-migrations.ts — flair#1439
+ *
+ * Version-keyed migrations that `flair upgrade` applies automatically during
+ * the post-restart verification step. These are distinct from the Harper data
+ * migrations in `resources/migrations/`: those run inside the server and
+ * transform stored data. These run in the CLI and bring the LOCAL dev-env
+ * (hook files, config snippets) up to the state a fresh `flair init` would
+ * produce for the harnesses already wired on this machine.
+ *
+ * ## Consent model
+ *
+ * A migration runs when ALL of the following hold:
+ *   1. The installed harness/artifact is ALREADY present on this machine
+ *      (the user consented to that integration when they ran `flair init`).
+ *   2. The target version (`toVersion`) introduces the artifact for the first
+ *      time (`toAtLeast`), AND the previous version did not have it
+ *      (`fromBefore`).
+ *   3. The artifact is currently absent (idempotent: nothing to do if it's
+ *      already there).
+ *
+ * Because (1) is the consent gate, no extra flag or TTY interaction is
+ * required. The user already said "wire Codex" — the migration just applies
+ * the piece their old init couldn't know about.
+ *
+ * ## Adding a new migration
+ *
+ *   1. Push a new entry onto UPGRADE_MIGRATIONS.
+ *   2. Set `fromBefore` to the first version that includes the new artifact.
+ *   3. Set `toAtLeast` to the same version.
+ *   4. Implement `apply(ctx)` — return ok:false (surfaced as a warning) on
+ *      partial failure; throw only on hard failure that should be logged.
+ *
+ * Migrations run in order; later entries may assume earlier ones completed.
+ */
+import { installHook, hookSettingsPath, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { checkSessionStartHook, readClientMcpBlock } from "../doctor-client.js";
+import { parseSemverCore } from "../fabric-upgrade.js";
+// ─── Semver helpers ───────────────────────────────────────────────────────────
+/** True if version `a` is strictly less than `b`. */
+function semverLt(a, b) {
+    const pa = parseSemverCore(a);
+    const pb = parseSemverCore(b);
+    if (!pa || !pb)
+        return false;
+    if (pa[0] !== pb[0])
+        return pa[0] < pb[0];
+    if (pa[1] !== pb[1])
+        return pa[1] < pb[1];
+    return pa[2] < pb[2];
+}
+/** True if version `a` is greater than or equal to `b`. */
+function semverGte(a, b) {
+    return !semverLt(a, b);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Determine if a harness is "already wired" — the user previously ran
+ * `flair init` for it and the MCP block (config.toml / mcpServers JSON) is
+ * present. The hook itself is what we're migrating IN, so we deliberately
+ * do NOT check for the hook's presence here.
+ *
+ * Uses readClientMcpBlock (which temporarily overrides HOME) so the homeDir
+ * arg is honoured correctly in tests.
+ */
+function isHarnessWired(homeDir, harness) {
+    const clientId = harness === "codex" ? "codex" : "claude-code";
+    const block = readClientMcpBlock(clientId, homeDir);
+    return block.present;
+}
+/**
+ * Install the SessionStart hook for a harness, reading the agent id and flair
+ * URL from the existing MCP block (same as `resolveUpgradeHookInstall` in
+ * doctor-run.ts, but self-contained to avoid a circular dep).
+ */
+function applySessionStartHookForHarness(homeDir, harness, port) {
+    const id = `session-start-hook@0.50.0/${harness}`;
+    // Already present → idempotent no-op.
+    const settingsPath = hookSettingsPath(homeDir, harness);
+    const existing = checkSessionStartHook(homeDir, settingsPath);
+    if (existing.present) {
+        return { id, message: `SessionStart hook (${harness}): already present — no-op`, ok: true, wrote: false };
+    }
+    // Not wired at all → skip (don't wire a harness the user never had).
+    if (!isHarnessWired(homeDir, harness)) {
+        return { id, message: `SessionStart hook (${harness}): harness not wired — skip`, ok: true, wrote: false };
+    }
+    // Resolve agentId + flairUrl from the existing MCP block.
+    const clientId = harness === "codex" ? "codex" : "claude-code";
+    const block = readClientMcpBlock(clientId, homeDir);
+    const agentId = (typeof process.env.FLAIR_AGENT_ID === "string" && process.env.FLAIR_AGENT_ID) ||
+        block.agentId;
+    const flairUrl = (typeof process.env.FLAIR_URL === "string" && process.env.FLAIR_URL) ||
+        block.flairUrl ||
+        `http://127.0.0.1:${port}`;
+    if (!agentId) {
+        return {
+            id,
+            message: `SessionStart hook (${harness}): no agent id found in MCP config — run: flair hook install --harness ${harness}`,
+            ok: false,
+            wrote: false,
+        };
+    }
+    const result = installHook({ homeDir, harness, agentId, flairUrl });
+    return {
+        id,
+        message: result.message,
+        ok: result.ok,
+        wrote: result.ok,
+    };
+}
+// ─── Migration registry ───────────────────────────────────────────────────────
+/**
+ * Ordered list of all CLI upgrade migrations.
+ *
+ * To add a migration: push a new entry, set fromBefore/toAtLeast, implement
+ * apply(). The runner calls apply() only when the version window matches.
+ */
+export const UPGRADE_MIGRATIONS = [
+    {
+        id: "session-start-hook@0.50.0",
+        description: "Install missing SessionStart hook(s) for harnesses already wired in a pre-0.50.0 init",
+        fromBefore: "0.50.0",
+        toAtLeast: "0.50.0",
+        apply(ctx) {
+            // Only act on detected hook-capable harnesses already wired on this machine.
+            const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h) && isHarnessWired(ctx.homeDir, h));
+            if (harnesses.length === 0)
+                return [];
+            return harnesses.map((h) => applySessionStartHookForHarness(ctx.homeDir, h, ctx.port));
+        },
+    },
+];
+/**
+ * Run all CLI upgrade migrations whose version window matches
+ * `fromVersion → toVersion`. Migrations whose window is not matched are
+ * silently skipped (they're not pending for this upgrade pair).
+ *
+ * @param fromVersion  The previously installed version (null → unknown, skip
+ *                     migrations that need a version gate).
+ * @param toVersion    The newly installed version (null → unknown, skip all).
+ * @param ctx          Runtime context (homeDir, port, detectedClientIds).
+ */
+export function applyUpgradeMigrations(fromVersion, toVersion, ctx, 
+// Injectable for tests (e.g. the throwing-migration case); production callers
+// use the real registry.
+migrations = UPGRADE_MIGRATIONS) {
+    const applied = [];
+    if (!fromVersion || !toVersion) {
+        // Cannot gate on version — skip all version-keyed migrations.
+        return { applied, allOk: true };
+    }
+    for (const migration of migrations) {
+        const pending = semverLt(fromVersion, migration.fromBefore) &&
+            semverGte(toVersion, migration.toAtLeast);
+        if (!pending)
+            continue;
+        // A migration must never CRASH the upgrade: a thrown apply() is strictly
+        // worse than the pre-migration doctor failure it was meant to prevent — no
+        // summary, partial writes, and the doctor catalog never runs. Catch it,
+        // surface it as a non-fatal ok:false result, and let the catalog proceed
+        // (flair#1439, per Kern review).
+        let results;
+        try {
+            results = migration.apply(ctx);
+        }
+        catch (err) {
+            results = [{
+                    id: migration.id,
+                    message: `${migration.id}: migration failed (${err instanceof Error ? err.message : String(err)}) — run \`flair doctor\` to check the current state`,
+                    ok: false,
+                    wrote: false,
+                }];
+        }
+        if (results.length > 0) {
+            applied.push({ migration, results });
+        }
+    }
+    const allOk = applied.every((a) => a.results.every((r) => r.ok));
+    return { applied, allOk };
+}

package/dist/resources/Federation.js

@@ -5,8 +5,8 @@ import { allowAdmin } from "./agent-auth.js";
 import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, generateNonce, } from "./federation-crypto.js";
 import { initFederationCleanup } from "./federation-cleanup.js";
 import { createPersistentNonceStore, initNonceStoreCleanup } from "./federation-nonce-store.js";
-import { classifyRecord } from "./federation-classify.js";
-export { classifyRecord } from "./federation-classify.js";
+import { classifyRecord, reconstructRecordVerifyBody, checkPrincipalEntitlement, } from "./federation-classify.js";
+export { classifyRecord, reconstructRecordVerifyBody, checkPrincipalEntitlement, recordSignatureVersion, PRINCIPAL_OWNING_TABLES, FEDERATION_TABLE_POLICY, FEDERATION_SYNC_TABLES, } from "./federation-classify.js";
 // Module-level nonce store for federation anti-replay.
 // Shared across FederationPair + FederationSync — nonces are globally unique
 // (generated by signBodyFresh per request with 128-bit random nonces).
@@ -37,6 +37,17 @@ export { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodyS
 function requireRecordSignatures() {
     return (process.env.FLAIR_FEDERATION_REQUIRE_RECORD_SIGNATURES ?? "").toLowerCase() === "true";
 }
+/**
+ * Phase 3 of flair#1416 — skip leftover v:1 records on principal-owning
+ * tables that lack principalId. Default OFF. Flip only once every paired
+ * peer is emitting v:2 (check SyncLog for unsigned / v:1 Memory). Same
+ * operator-decision pattern as requireRecordSignatures() — never
+ * auto-flipped. v:2 Memory is already mandatory-principal regardless of
+ * this flag (see checkPrincipalEntitlement).
+ */
+function requireRecordPrincipal() {
+    return (process.env.FLAIR_FEDERATION_REQUIRE_RECORD_PRINCIPAL ?? "").toLowerCase() === "true";
+}
 // ─── Conflict resolution ─────────────────────────────────────────────────────
 /**
  * Field-level Last-Write-Wins merge.
@@ -359,7 +370,10 @@ export class FederationSync extends Resource {
             skipped++;
             skippedReasons[reason] = (skippedReasons[reason] ?? 0) + 1;
         }
-        // Table name → Harper database table mapping
+        // Table name → Harper database table mapping.
+        // Typed against FEDERATION_TABLE_POLICY so adding a federated table
+        // without deciding principalOwning is a type error, not a silent
+        // default (flair#1416 — refuse by whitelist, never by field presence).
         const tableMap = {
             Memory: databases.flair.Memory,
             Soul: databases.flair.Soul,
@@ -369,7 +383,9 @@ export class FederationSync extends Resource {
         const knownTables = new Set(Object.keys(tableMap));
         for (const record of records) {
             try {
-                const table = tableMap[record.table];
+                const table = (record.table in tableMap)
+                    ? tableMap[record.table]
+                    : undefined;
                 const local = table ? await table.get(record.id) : null;
                 const decision = classifyRecord(record, peer.role, instanceId, local, knownTables);
                 if (decision.action === "skip") {
@@ -403,22 +419,15 @@ export class FederationSync extends Resource {
                         recordSkip("unknown_originator_key");
                         continue;
                     }
-                    // CONTRACT — must match src/cli.ts runFederationSyncOnce's signing
-                    // payload byte-for-byte: keys { v, table, id, data, updatedAt,
-                    // originatorInstanceId }. canonicalize() sorts keys, so field ORDER
-                    // doesn't matter, but the field SET and values do. `v: 1` versions
-                    // the canonical form itself — bump it on BOTH sides together if the
-                    // signed field set ever changes, so an old signature fails closed
-                    // instead of silently mis-verifying under a new form.
-                    const signatureValid = verifyBodySignature({
-                        v: 1,
-                        table: record.table,
-                        id: record.id,
-                        data: record.data,
-                        updatedAt: record.updatedAt,
-                        originatorInstanceId: originator,
-                        signature: record.signature,
-                    }, originatorPublicKey);
+                    // CONTRACT — reconstruct from the record (v defaults to 1 when
+                    // absent — v is NOT on the wire today). Must match
+                    // reconstructRecordVerifyBody / src/cli.ts's signing payload.
+                    // A hardcoded { v: 1, table, id, data, updatedAt,
+                    // originatorInstanceId } field set can only ever verify one
+                    // shape; building from the record is what makes v:2 (principalId
+                    // in the signed body) verifiable without breaking existing
+                    // records. See flair#1416.
+                    const signatureValid = verifyBodySignature(reconstructRecordVerifyBody(record, originator), originatorPublicKey);
                     if (!signatureValid) {
                         recordSkip("invalid_signature");
                         continue;
@@ -431,6 +440,19 @@ export class FederationSync extends Resource {
                     recordSkip("missing_signature");
                     continue;
                 }
+                // ── Per-record principal entitlement (flair#1416 / slice 3a) ──
+                // After signature verification, before table.put. Scoped by the
+                // explicit PRINCIPAL_OWNING_TABLES set (Memory), never by whether
+                // principalId happens to be present — absent Memory principalId
+                // is a skip, not an accept. Soul/Agent/Relationship are not in
+                // the set and are not consulted. No Agent.get.
+                const principalSkip = checkPrincipalEntitlement(record, {
+                    enforceV1Principal: requireRecordPrincipal(),
+                });
+                if (principalSkip) {
+                    recordSkip(principalSkip);
+                    continue;
+                }
                 const mergedData = mergeRecord(local, record);
                 mergedData._originatorInstanceId = decision.originator;
                 mergedData._syncedFrom = instanceId;

package/dist/resources/MemoryArchive.js

@@ -0,0 +1,94 @@
+/**
+ * MemoryArchive.ts — user-facing archive action (flair#1472, Deliverable A).
+ *
+ * POST /MemoryArchive — sets or clears the `archived` visibility flag on a
+ * memory by id:
+ *   - `action: "basement"` → archived=true + stamps archivedAt (and archivedBy)
+ *   - `action: "restore"`  → archived=false + clears archivedAt/archivedBy
+ *
+ * `archived` is a VISIBILITY flag, not a deletion: basementing removes a
+ * memory 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 (per-session reuse is drawers, Deliverable B, which does not exist
+ * yet). The CLI help text must make that global scope explicit.
+ *
+ * Own-lane scope: 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. Anonymous HTTP is
+ * denied (401).
+ *
+ * Registered automatically at /MemoryArchive via config.yaml's
+ * `jsResource: files: dist/resources/*.js` (named export → export name).
+ */
+import { Resource } from "harper";
+import { Memory } from "./Memory.js";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** Unwrap a Harper Response (has .json() + .status) into a plain object, else pass through. */
+async function unwrap(value) {
+    if (value && typeof value === "object" && typeof value.json === "function" && "status" in value) {
+        try {
+            const body = await value.json();
+            return { ...body, status: value.status };
+        }
+        catch {
+            return { error: "request failed", status: value.status };
+        }
+    }
+    return value;
+}
+export class MemoryArchive extends Resource {
+    /** POST requires auth — an agent acting on its own memories (or admin). */
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async post(data) {
+        const { id, action } = data || {};
+        if (!id)
+            return json(400, { error: "id required" });
+        if (action !== "basement" && action !== "restore") {
+            return json(400, { error: "action must be 'basement' or 'restore'" });
+        }
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return json(401, { error: "authentication required" });
+        if (auth.kind !== "agent")
+            return json(403, { error: "forbidden" });
+        // Read the existing record — Memory.get()'s read-scope gate applies (own +
+        // org-non-private only). A non-readable id returns a 404 Response.
+        const existing = await Memory.get(id, ctx);
+        const record = await unwrap(existing);
+        if (!record || typeof record !== "object" || !record.id) {
+            return json(404, { error: "memory not found" });
+        }
+        const archived = action === "basement";
+        const merged = {
+            ...record,
+            archived,
+            updatedAt: new Date().toISOString(),
+        };
+        if (archived) {
+            // archivedBy is set by the caller (Memory.put() stamps archivedAt when
+            // archived===true). 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, silently drop the vector).
+            merged.archivedBy = auth.agentId;
+        }
+        else {
+            delete merged.archivedAt;
+            delete merged.archivedBy;
+        }
+        // Write back — Memory.put()'s ownership gate applies (stampAttribution), so
+        // a non-admin caller cannot flip another agent's memory (403).
+        const result = await Memory.put(merged, ctx);
+        return unwrap(result);
+    }
+}

package/dist/resources/MemoryBootstrap.js

@@ -697,6 +697,7 @@ export class BootstrapMemories extends Resource {
             conditions: [
                 { attribute: "agentId", comparator: "equals", value: agentId },
                 { attribute: "durability", comparator: "equals", value: "permanent" },
+                { attribute: "archived", comparator: "not_equal", value: true },
             ],
             select: OWN_SELECT,
         }));
@@ -767,6 +768,7 @@ export class BootstrapMemories extends Resource {
             conditions: [
                 { attribute: "agentId", comparator: "equals", value: agentId },
                 { attribute: "durability", comparator: "not_equal", value: "permanent" },
+                { attribute: "archived", comparator: "not_equal", value: true },
             ],
             select: OWN_SELECT,
             sort: { attribute: "createdAt", descending: true },
@@ -952,7 +954,7 @@ export class BootstrapMemories extends Resource {
                 const candidatePoolK = Math.min(MAX_CANDIDATE_POOL, Math.max(3 * expectedFill, 5 * teammateIds.length, MIN_CANDIDATE_POOL));
                 const candidates = await retrieveCandidates({
                     queryEmbedding,
-                    conditions: [scope.condition],
+                    conditions: [scope.condition, { attribute: "archived", comparator: "not_equal", value: true }],
                     limit: candidatePoolK,
                     // flair#1246 — ONE RANKER, ONE SCALE: this pass now invokes the
                     // core in the SAME mode memory_search does (hybrid + q via the

package/dist/resources/RecordUsage.js

@@ -97,6 +97,7 @@ import { Resource } from "harper";
 import { resolveAgentAuth } from "./agent-auth.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { recordUsageContribution, MAX_USAGE_IDS_PER_CALL } from "./usage-recording.js";
+import { resolveRecordUsageIds } from "./usage-ids.js";
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const BAD_REQUEST = (msg) => new Response(JSON.stringify({ error: msg }), { status: 400, headers: { "Content-Type": "application/json" } });
 // flair#744 slice A: sourced from the shared module (./usage-recording.ts)
@@ -159,14 +160,20 @@ export class RecordUsage extends Resource {
         const rl = checkRateLimit(agentId, "usage");
         if (!rl.allowed)
             return rateLimitResponse(rl.retryAfterMs, "usage");
-        const rawIds = data?.memoryIds ?? (typeof data?.memoryId === "string" ? [data.memoryId] : undefined);
-        if (!Array.isArray(rawIds) || rawIds.length === 0 || !rawIds.every((id) => typeof id === "string" && id.length > 0)) {
+        // flair#1410: MERGE memoryId + memoryIds (union, then dedupe). The
+        // previous `data?.memoryIds ?? [data?.memoryId]` preferred the plural
+        // and silently dropped the singular — quiet data loss. Unioning HERE
+        // means a client that POSTs both fields straight through (without
+        // flattening first) still credits both. Native `/mcp` also unions
+        // before calling this; the endpoint is the guarantee, not the client.
+        const resolved = resolveRecordUsageIds(data, MAX_IDS_PER_CALL);
+        if (!resolved.ok) {
+            if (resolved.error === "cap") {
+                return BAD_REQUEST(`memoryIds exceeds the per-call limit of ${MAX_IDS_PER_CALL}`);
+            }
             return BAD_REQUEST("memoryIds must be a non-empty array of memory id strings");
         }
-        if (rawIds.length > MAX_IDS_PER_CALL) {
-            return BAD_REQUEST(`memoryIds exceeds the per-call limit of ${MAX_IDS_PER_CALL}`);
-        }
-        const memoryIds = [...new Set(rawIds)]; // dedupe within THIS call too
+        const memoryIds = resolved.ids;
         const attribution = sanitizeAttribution(data?.attribution);
         const now = new Date().toISOString();
         for (const memoryId of memoryIds) {

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, includeArchived = 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
@@ -160,7 +160,12 @@ export class SemanticSearch extends Resource {
         }
         // Exclude archived records. Use "not_equal" (Harper v5 comparator) instead of
         // "equals false" so records without the archived field are included.
-        conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+        // flair#1472 — `includeArchived` opts back IN to the basement: when true the
+        // archived predicate is omitted entirely, so basemented memories are returned
+        // under the SAME read-scope gate as a normal search (never a wider scope).
+        if (!includeArchived) {
+            conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+        }
         if (tag) {
             conditions.push({ attribute: "tags", comparator: "equals", value: tag });
         }
@@ -215,6 +220,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 +236,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 +337,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 });
         }