@tpsdev-ai/flair 0.49.0 → 0.51.0

package/dist/lib/scheduler-platform.js

@@ -20,9 +20,9 @@
  * in `verifyFirstRun()`: success may not be claimed until the thing the
  * operator asked for has been observed to happen once.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { resolve, dirname, isAbsolute } from "node:path";
-import { platform } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, realpathSync } from "node:fs";
+import { resolve, dirname, isAbsolute, basename } from "node:path";
+import { platform, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 /**
  * 30s ceiling on launchctl/systemctl invocations so a hung service manager
@@ -90,20 +90,71 @@ export function interpretActiveResult(plat, code, stdout, stderr) {
         return null; // spawn itself failed — inconclusive
     return false; // covers the no-bus case: empty stdout, nonzero/failed exit
 }
+/** True when this session already has the env `systemctl --user` needs. */
+export function sessionHasUserBusEnv(env = process.env) {
+    return Boolean(env.XDG_RUNTIME_DIR?.trim() && env.DBUS_SESSION_BUS_ADDRESS?.trim());
+}
+/**
+ * Reads whether lingering is already enabled for the current user.
+ * `loginctl show-user … Linger=yes` is the official answer; the stamp file
+ * `loginctl enable-linger` creates is the fallback when loginctl is missing
+ * or inconclusive. A failed probe is `null`, never linger-off — inventing
+ * linger-off would repeat the linger remedy after it already ran (#1107).
+ */
+export function probeUserLingerEnabled(opts = {}) {
+    const run = opts.run ?? spawnReport;
+    const lingerStampExists = opts.lingerStampExists ?? ((u) => existsSync(`/var/lib/systemd/linger/${u}`));
+    let user = "";
+    try {
+        user = userInfo().username;
+    }
+    catch {
+        user = process.env.USER || process.env.LOGNAME || "";
+    }
+    if (!user)
+        return null;
+    const r = run(["loginctl", "show-user", user, "--property=Linger"], STATUS_CHECK_TIMEOUT_MS);
+    const m = /^Linger=(yes|no)\s*$/m.exec(r.stdout ?? "");
+    if (m)
+        return m[1] === "yes";
+    if (lingerStampExists(user))
+        return true;
+    return null;
+}
 /**
- * Human remedy text for a failed scheduler-load attempt (flair#850). Covers
- * the one root cause traced so far: a missing systemd user session bus,
- * which blocks `systemctl --user` entirely in ssh-without-lingering,
- * container, and CI contexts. Returns null when the failure doesn't match a
- * known pattern — the caller already prints the raw stderr, so the operator
- * still has something to go on.
+ * Human remedy text for a failed scheduler-load attempt (flair#850, #1107).
+ * Covers the traced "no systemd user session bus" failure, which blocks
+ * `systemctl --user` entirely in ssh-without-lingering, container, and CI
+ * contexts. Two cases that used to share one remedy:
+ *   (a) lingering genuinely off — print `loginctl enable-linger`
+ *   (b) linger already on, this session has no user-bus env — print the
+ *       `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` export lines
+ * Repeating (a) after the operator has applied it is the #1107 lie.
+ * Returns null when the failure doesn't match a known pattern — the caller
+ * already prints the raw stderr, so the operator still has something to go on.
  *
  * `enableCommand` is the caller's own enable invocation, named in the remedy
  * so the operator is told to re-run the command they actually ran.
  */
-export function describeLoadFailure(plat, loadResult, enableCommand) {
+export function describeLoadFailure(plat, loadResult, enableCommand, session) {
     const stderr = loadResult.stderr || "";
     if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        if (session?.lingerEnabled === true) {
+            const env = session.env ?? process.env;
+            if (!sessionHasUserBusEnv(env)) {
+                return ("No systemd user session bus is available in this session. Lingering is already enabled — " +
+                    "do not re-run `loginctl enable-linger`. The remaining gap is this session's user-bus environment. " +
+                    "Export:\n" +
+                    "     export XDG_RUNTIME_DIR=/run/user/$(id -u)\n" +
+                    "     export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus\n" +
+                    `   then re-run \`${enableCommand}\`.`);
+            }
+            return ("No systemd user session bus is available in this session. Lingering is already enabled and " +
+                "this session already has XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS — " +
+                "do not re-run `loginctl enable-linger` or re-export those variables. " +
+                "Check that `$XDG_RUNTIME_DIR/bus` exists (the systemd --user instance may not be running), " +
+                `then re-run \`${enableCommand}\`.`);
+        }
         return ("No systemd user session bus is available in this session (common over ssh without lingering, " +
             "in containers, or under CI). Fix: enable lingering for this user — `loginctl enable-linger <user>` " +
             `— then re-run \`${enableCommand}\`.`);
@@ -172,6 +223,77 @@ export function resolveNodeBin(explicit) {
         "enable time — refusing to install a shim that would resolve `node` from the service manager's PATH " +
         "at run time. Install node (or put it on PATH for this shell) and re-run enable.");
 }
+/**
+ * Resolves the path enable will bake as FLAIR_BIN, and whether that path is
+ * the stable public `flair` entry (flair#1279).
+ *
+ * Resolution order:
+ *   1. `explicit` — caller/test override. Relatives are resolved against cwd.
+ *   2. `hooks.argv1` / `process.argv[1]` — whatever launched enable.
+ *   3. The public `flair` on PATH, only when (1) and (2) are empty.
+ * Nothing absolute resolvable ⇒ throw. A bare `"flair"` is not an exec
+ * target under #1231's `exec <node> <script>` form (`node flair` looks in
+ * cwd, not PATH).
+ */
+export function resolveFlairBin(explicit, hooks) {
+    const publicBin = hooks && "publicBin" in hooks ? (hooks.publicBin ?? null) : lookupPublicFlairBin();
+    const captured = explicit ?? hooks?.argv1 ?? process.argv[1];
+    let path;
+    if (typeof captured === "string" && captured.length > 0) {
+        path = isAbsolute(captured) ? captured : resolve(captured);
+    }
+    else if (publicBin) {
+        path = publicBin;
+    }
+    else {
+        throw new Error("unable to resolve an absolute path to the flair CLI (process.argv[1] was empty and `command -v flair` " +
+            "found nothing). The scheduler shim bakes this path in at enable time — refusing to install a shim " +
+            "whose exec target is unknown. Re-run enable via the `flair` command.");
+    }
+    return { path, publicBin, canonical: isCanonicalFlairBin(path, publicBin) };
+}
+/** True when `baked` is the public `flair` entry, not a working-tree capture. */
+export function isCanonicalFlairBin(baked, publicBin) {
+    if (basename(baked) === "flair")
+        return true;
+    if (publicBin && pathsReferToSameFile(baked, publicBin))
+        return true;
+    return false;
+}
+/**
+ * The enable-report lines for a non-canonical FLAIR_BIN. Empty when the
+ * baked path is the public entry — callers should not print a warning then.
+ */
+export function formatFlairBinWarning(baked, publicBin, enableCommand) {
+    if (isCanonicalFlairBin(baked, publicBin))
+        return [];
+    const lines = [
+        `⚠️  FLAIR_BIN is ${baked} — that is the process that ran enable, not a stable public entry.`,
+        `   A later blue/green directory swap, or deleting this working tree, will strand the scheduler unit.`,
+    ];
+    if (publicBin) {
+        lines.push(`   Public \`flair\` on PATH: ${publicBin}. Re-run \`${enableCommand}\` as the \`flair\` command to bake that path instead.`);
+    }
+    else {
+        lines.push(`   No \`flair\` on PATH. Re-run \`${enableCommand}\` via the installed \`flair\` command (or a stable symlink) so the baked path survives a tree swap.`);
+    }
+    return lines;
+}
+function lookupPublicFlairBin() {
+    const r = spawnReport(["/bin/sh", "-c", "command -v flair"], STATUS_CHECK_TIMEOUT_MS);
+    const found = r.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (r.code === 0 && found && isAbsolute(found) && existsSync(found))
+        return found;
+    return null;
+}
+function pathsReferToSameFile(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
 // ─── first-run verification (flair#1231) ────────────────────────────────────
 // A load/bootstrap command exiting 0 proves the service manager accepted the
 // job — not that the job can run. The only vantage that exercises the real

package/dist/lib/scratch-owner.js

@@ -0,0 +1,49 @@
+/**
+ * Owner stamp for harness scratch directories (flair#1032).
+ *
+ * Directory mtime is not a liveness signal: on Linux, appending to files
+ * inside subdirectories does not update the parent. The stamp records the
+ * creating process; a sweep may delete a tree only when that process is gone
+ * (and, for Harper trees, when `hdb.pid` is gone too).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const SCRATCH_OWNER_FILE = ".flair-scratch-owner";
+export function writeScratchOwnerStamp(dir, pid = process.pid) {
+    writeFileSync(join(dir, SCRATCH_OWNER_FILE), `${pid}\n`, { encoding: "utf-8" });
+}
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readPidFile(path) {
+    try {
+        const pid = Number(readFileSync(path, "utf-8").trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readScratchOwnerPid(dir) {
+    return readPidFile(join(dir, SCRATCH_OWNER_FILE));
+}
+export function hasScratchOwnerStamp(dir) {
+    return existsSync(join(dir, SCRATCH_OWNER_FILE));
+}
+/** True when the creating process is still alive. Unreadable stamp → not live. */
+export function scratchOwnerIsLive(dir) {
+    const pid = readScratchOwnerPid(dir);
+    return pid !== null && isPidAlive(pid);
+}
+export function hdbPidIsLive(dir) {
+    const pid = readPidFile(join(dir, "hdb.pid"));
+    return pid !== null && isPidAlive(pid);
+}

package/dist/rem/scheduler.js

@@ -19,7 +19,7 @@ import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, resolveFlairBin, formatFlairBinWarning, verifyFirstRun, probeUserLingerEnabled, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 // Re-exported so this module's public surface is unchanged by the extraction
 // into src/lib/scheduler-platform.ts (a second scheduler — `flair federation
 // sync enable` — needs the identical launchctl/systemctl interpretation, and
@@ -180,8 +180,8 @@ export async function queryActiveStateAsync(plat, timeoutMs = STATUS_CHECK_TIMEO
  * known pattern — the caller already prints the raw stderr, so the operator
  * still has something to go on.
  */
-export function describeLoadFailure(plat, loadResult) {
-    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable");
+export function describeLoadFailure(plat, loadResult, session) {
+    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable", session);
 }
 /**
  * Formats the `flair rem nightly enable` report from an `EnableResult`.
@@ -199,6 +199,15 @@ export function describeLoadFailure(plat, loadResult) {
  * happen once. A missing `loadResult`/`firstRun` (test-only skipLoad shape)
  * therefore withholds the headline too, instead of being treated as success.
  */
+function appendFlairBinWarning(lines, r) {
+    if (r.flairBinCanonical !== false || !r.flairBin)
+        return;
+    const warning = formatFlairBinWarning(r.flairBin, r.flairBinPublic ?? null, "flair rem nightly enable");
+    if (warning.length === 0)
+        return;
+    lines.push("");
+    lines.push(...warning);
+}
 export function formatEnableReport(r, input) {
     const { hour, minute, agentId, flairUrl } = input;
     const scheduleTime = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
@@ -216,11 +225,15 @@ export function formatEnableReport(r, input) {
         ];
         if (lr.stderr)
             lines.push(`     stderr: ${lr.stderr.trim()}`);
-        const remedy = describeLoadFailure(r.platform, lr);
+        const lingerEnabled = input.lingerEnabled !== undefined
+            ? input.lingerEnabled
+            : (r.platform === "linux" ? (input.probeLinger ?? probeUserLingerEnabled)() : undefined);
+        const remedy = describeLoadFailure(r.platform, lr, { lingerEnabled, env: input.env });
         lines.push("");
         lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
         lines.push("");
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair rem nightly status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     if (!r.firstRunVerified) {
@@ -272,6 +285,7 @@ export function formatEnableReport(r, input) {
         }
         lines.push("");
         lines.push(`   Check anytime with: flair rem nightly status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     const lines = [
@@ -288,6 +302,7 @@ export function formatEnableReport(r, input) {
     lines.push(`   First run:   completed through the service manager, exit 0`);
     lines.push("");
     lines.push(`Disable with \`flair rem nightly disable\`.`);
+    appendFlairBinWarning(lines, r);
     return { lines, ok: true };
 }
 /**
@@ -329,7 +344,8 @@ export function formatStatusReport(s) {
  */
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
-    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const resolvedFlair = resolveFlairBin(opts.flairBin);
+    const flairBin = resolvedFlair.path;
     const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
@@ -383,6 +399,7 @@ export function enableScheduler(opts) {
         return {
             platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult,
             firstRunVerified: firstRun?.verified === true, firstRun,
+            flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
         };
     }
     // Linux: systemd user units.
@@ -408,6 +425,7 @@ export function enableScheduler(opts) {
     return {
         platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult,
         firstRunVerified: firstRun?.verified === true, firstRun,
+        flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
     };
 }
 /**

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/MemoryBootstrap.js

@@ -502,16 +502,18 @@ export class BootstrapMemories extends Resource {
                     skillAssignments.push(record);
                     continue;
                 }
-                // flair#1182 — the raw soul container (key→value), independent of the
-                // token-budgeted/priority-truncated `sections.soul` lines built below.
-                soulMap[record.key] = record.value;
                 const line = `**${record.key}:** ${record.value}`;
                 const tokens = estimateTokens(line);
                 const priority = SOUL_KEY_PRIORITY[record.key] ?? 50;
-                soulEntries.push({ key: record.key, line, tokens, priority });
+                soulEntries.push({ key: record.key, value: record.value, line, tokens, priority });
             }
             // Sort by priority (lower = more important)
             soulEntries.sort((a, b) => a.priority - b.priority);
+            // flair#1371 — the structured `soul` map follows the admission decision.
+            // Filling it during the scan (flair#1182) shipped every key even when
+            // this loop dropped the entry, so sections.soul / soulTokens / the
+            // context pointer described N while `soul` delivered N+1 (delivered
+            // but not counted or charged — the #1206 mirror).
             for (const entry of soulEntries) {
                 if (soulTokens + entry.tokens > soulMaxTokens) {
                     // Skip large entries that exceed budget — truncate or skip
@@ -522,6 +524,7 @@ export class BootstrapMemories extends Resource {
                     if (maxChars > 100) {
                         const truncated = `**${entry.key}:** ${entry.line.slice(entry.key.length + 6, entry.key.length + 6 + maxChars)}…(truncated)`;
                         sections.soul.push(truncated);
+                        soulMap[entry.key] = entry.value;
                         const cost = estimateTokens(truncated);
                         soulTokens += cost;
                         tokenBudget -= cost; // #1199 — soul draws from the shared budget
@@ -529,6 +532,7 @@ export class BootstrapMemories extends Resource {
                     continue;
                 }
                 sections.soul.push(entry.line);
+                soulMap[entry.key] = entry.value;
                 soulTokens += entry.tokens;
                 tokenBudget -= entry.tokens; // #1199 — soul draws from the shared budget
             }

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 } = 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" };