@tpsdev-ai/flair 0.53.0 → 0.54.2

package/dist/resources/mcp-tools.js

@@ -26,15 +26,17 @@
  * the resolved agent, never from the tool arguments — an agent can only act as
  * itself (no forging of agentId / authorId in the body).
  *
- * NOTE (flair#677 scope call): the legacy `@tpsdev-ai/flair-mcp` stdio proxy
- * (packages/flair-mcp) is a SEPARATE, independently-published package that
- * talks to flair over HTTP via `FlairClient` — it is not wired through this
- * registry at all (its own tool list is hardcoded in packages/flair-mcp/src/
- * index.ts). Per the zero-install north star (retiring flair-mcp in favor of
- * this native /mcp handler), `attention` is added HERE only, not mirrored into
- * the legacy stdio proxy — adding it there would mean a separate package
- * version bump + a new FlairClient method, out of scope for this query-only
- * slice.
+ * NOTE (flair#1580, vendored by flair#1683): MCP-facing metadata (name,
+ * description, inputSchema, output shape) lives in the descriptor module
+ * vendored at build time into `./tool-descriptors/` (source of truth:
+ * packages/flair-tool-descriptors/src/index.ts — see
+ * scripts/vendor-tool-descriptors.mjs). It is imported by RELATIVE PATH so it
+ * resolves inside the packed tarball with no registry dependency on the
+ * private descriptor package. This registry
+ * binds each *native* descriptor to its Harper impl. The stdio adapter binds
+ * the same list (stdio surface) to FlairClient HTTP — tool-set drift is
+ * impossible by construction. One-sided tools (`attention`, archive verbs,
+ * `relationship_store`) are flagged on the descriptor, not hand-exempted.
  */
 /**
  * The delegated handler classes, held in a mutable registry, LAZILY loaded on
@@ -54,8 +56,9 @@
 import { AUTHORITY_FIELDS } from "./authority-field-guard.js";
 import { resolveVersion } from "./version.js";
 import { agentContext, adminContext, collectionResource } from "./in-process.js";
-import { RECORD_USAGE_ID_MERGE_CONTRACT, unionUsageMemoryIds } from "./usage-ids.js";
+import { unionUsageMemoryIds } from "./usage-ids.js";
 import { SKILL_TAG, isSkillWrite } from "./skill-write.js";
+import { NATIVE_TOOL_DESCRIPTORS, toMcpToolDef, } from "./tool-descriptors/index.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -405,7 +408,8 @@ async function skillSearch(agent, args) {
  * returns the same 404 as an unreadable id. Returning it would (a) make
  * skill_get an alias for memory_get, and (b) reveal a readable non-skill
  * memory's existence through a skill-shaped call; a uniform 404 does neither.
- * The embedding fields are stripped by default, same as memory_get.
+ * The embedding fields are always stripped (flair#1593) — there is no
+ * includeEmbedding opt-in. memory_get keeps that flag (flair#1188).
  */
 async function skillGet(agent, args) {
     const Cls = await handler("Memory");
@@ -419,7 +423,9 @@ async function skillGet(agent, args) {
     // returned (see the doc above).
     if (!isSkillWrite(result))
         return { error: "skill not found", status: 404 };
-    return args?.includeEmbedding === true ? result : stripInternalFields(result);
+    // flair#1593 — always strip. includeEmbedding used to bypass this and
+    // ride the raw vector; nothing in the skill_get contract needs it.
+    return stripInternalFields(result);
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -850,24 +856,33 @@ export function mcpToolName(table, toolPrefix, verb) {
     const override = TOOL_NAME_OVERRIDES[table]?.[verb];
     return override ?? `${toolPrefix}_${verb}`;
 }
-export const TOOLS = {
+/**
+ * Bind native descriptors to Harper impls + conformance contracts.
+ * A descriptor without a binding (or a binding without a native descriptor)
+ * throws at module load — the tool set is derived, not hand-copied.
+ */
+function bindNativeTools(bindings) {
+    const tools = {};
+    const missing = [];
+    for (const d of NATIVE_TOOL_DESCRIPTORS) {
+        const b = bindings[d.name];
+        if (!b) {
+            missing.push(d.name);
+            continue;
+        }
+        tools[d.name] = { def: toMcpToolDef(d), impl: b.impl, contract: b.contract };
+    }
+    if (missing.length > 0) {
+        throw new Error(`TOOLS missing Harper bindings for native descriptors: ${missing.join(", ")}`);
+    }
+    const extra = Object.keys(bindings).filter((n) => !Object.prototype.hasOwnProperty.call(tools, n)).sort();
+    if (extra.length > 0) {
+        throw new Error(`TOOLS bindings have no native descriptor: ${extra.join(", ")}`);
+    }
+    return tools;
+}
+export const TOOLS = bindNativeTools({
     memory_search: {
-        def: {
-            name: "memory_search",
-            description: "Search memories by meaning. Understands temporal queries like 'what happened today'. Scoped to your agent's own + granted memories.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: { type: "string", description: "Search query — natural language, semantic matching" },
-                    limit: { type: "number", description: "Max results (default 5)" },
-                    includeTrust: { type: "boolean", description: "Attach a per-result trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
-                    abstain: { type: "boolean", description: "Opt into first-class abstention: when the best match is below a global confidence threshold, return { abstained: true, reason, bestScore } with no weak matches instead of the N weakest results. Default false." },
-                    includeArchived: { type: "boolean", description: "Include basemented (archived) memories in results. Default false — archived memories are excluded from normal search. When true, archived memories are returned under the SAME read-scope gate as a normal search (never a wider scope)." },
-                },
-                required: ["query"],
-            },
-        },
         impl: memorySearch,
         contract: {
             summary: "{ results: MemoryRecord[] } — semantic hits scoped to the caller's own + granted memories; each hit carries content, never the raw embedding.",
@@ -881,30 +896,6 @@ export const TOOLS = {
         },
     },
     memory_store: {
-        def: {
-            name: "memory_store",
-            description: "Save information to persistent memory. Use for lessons, decisions, preferences, facts. Attributed to your authenticated agent.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    content: { type: "string", description: "What to remember" },
-                    type: { type: "string", enum: ["session", "lesson", "decision", "preference", "fact", "goal"], description: "Memory type (default session)" },
-                    durability: { type: "string", enum: ["permanent", "persistent", "standard", "ephemeral"], description: "permanent > persistent > standard > ephemeral (default standard)" },
-                    tags: { type: "array", items: { type: "string" }, description: "Tag strings" },
-                    visibility: {
-                        type: "string",
-                        enum: ["private", "shared"],
-                        description: "Writer-controlled sharing intent. Omit to use the server's durability-keyed default: " +
-                            "permanent/persistent -> shared, standard/ephemeral -> private. " +
-                            "private — owner-only, never visible to another agent, even one holding a memory grant. " +
-                            "shared — visible to the owner and every other agent on this instance. " +
-                            "The visibility the write actually landed on is returned in the result.",
-                    },
-                    usedMemoryIds: { type: "array", items: { type: "string" }, description: "IDs of memories that informed this write (citation-on-write). Credited via the same deduped usage ledger as record_usage. Optional." },
-                },
-                required: ["content"],
-            },
-        },
         impl: memoryStore,
         contract: {
             summary: "Write echo { id, written:true, deduplicated } — the new id + confirmation. No internal embedding fields; round-trips via memory_get.",
@@ -916,24 +907,6 @@ export const TOOLS = {
         },
     },
     skill_store: {
-        def: {
-            name: "skill_store",
-            description: "Write a skill (a reusable capability/procedure) as a skill-tagged memory. " +
-                "The `trigger` text is what the skill embeds from (the recall signal — 'when to use this'), " +
-                "and `content` is the full procedure. Skills are forced durability=persistent and are " +
-                "SkillScan-gated before the embed (a dangerous shell/network payload is rejected).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    content: { type: "string", description: "The full procedure (markdown body of the SKILL.md)" },
-                    trigger: { type: "string", description: "The 'when to use' text — the recall signal the skill embeds from" },
-                    name: { type: "string", description: "Skill name (SKILL.md frontmatter; stored in metadata)" },
-                    description: { type: "string", description: "Skill description (SKILL.md frontmatter; stored in metadata)" },
-                    tags: { type: "array", items: { type: "string" }, description: "Additional tags (the 'skill' tag is added automatically)" },
-                },
-                required: ["content"],
-            },
-        },
         impl: skillStore,
         contract: {
             summary: "Write echo { id, written:true, deduplicated } for the skill-tagged memory. No internal embedding fields; round-trips via memory_get.",
@@ -945,23 +918,6 @@ export const TOOLS = {
         },
     },
     skill_search: {
-        def: {
-            name: "skill_search",
-            description: "Find skills (reusable capabilities/procedures) that apply to a task. " +
-                "Ranks skill-tagged memories by their `trigger` ('when to use') against your task text. " +
-                "Returns a lightweight CATALOG — id, name, trigger, description, tags, agentId — NOT the full " +
-                "procedure (fetch that with skill_get). Scoped to your own + shared skills; another agent's " +
-                "private skill is never returned.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    task: { type: "string", description: "The task/context to match skills against — natural language; ranked against each skill's trigger" },
-                    limit: { type: "number", description: "Max skills to return (default 5)" },
-                },
-                required: ["task"],
-            },
-        },
         impl: skillSearch,
         contract: {
             summary: "{ results: SkillCard[] } — the skill catalog (lightweight id/name/trigger/description/tags/agentId, " +
@@ -979,25 +935,10 @@ export const TOOLS = {
         },
     },
     skill_get: {
-        def: {
-            name: "skill_get",
-            description: "Retrieve a full skill by ID — the complete procedure (`content`) plus trigger and metadata. " +
-                "The disclosure step after skill_search's catalog. Read-scoped: you can only get your own or a " +
-                "shared skill, never another agent's private skill. A non-skill id returns not-found.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "Skill (memory) ID" },
-                    includeEmbedding: { type: "boolean", description: "Include the raw embedding vector (large, rarely useful). Default false." },
-                },
-                required: ["id"],
-            },
-        },
         impl: skillGet,
         contract: {
             summary: "The full skill record { id, agentId, content, trigger, tags, durability, metadata, createdAt, ... } for a " +
-                "skill readable under the caller's read-scope — embedding + embeddingModel stripped by default. A non-owner " +
+                "skill readable under the caller's read-scope — embedding + embeddingModel always stripped. A non-owner " +
                 "cannot read another agent's private skill, and a readable non-skill id is not found (both 404).",
             requiredFields: ["id", "agentId", "content", "createdAt"],
             fieldTypes: { id: "string", agentId: "string", content: "string" },
@@ -1007,21 +948,6 @@ export const TOOLS = {
         },
     },
     memory_update: {
-        def: {
-            name: "memory_update",
-            description: "Update an existing memory by ID. Dedup-bypassed (this is an intentional overwrite, not a new write). " +
-                "Default: overwrites the same id in place. Pass preserveHistory=true to instead write a new version " +
-                "linked via `supersedes`, closing the old one's validity window.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "ID of the memory to update" },
-                    content: { type: "string", description: "New content" },
-                    preserveHistory: { type: "boolean", description: "Write a new version (supersedes-linked) instead of overwriting in place (default false)" },
-                },
-                required: ["id", "content"],
-            },
-        },
         impl: memoryUpdate,
         contract: {
             summary: "Write echo { id, written:true } for the in-place overwrite (or supersede). No internal embedding fields; the change round-trips via memory_get.",
@@ -1033,20 +959,6 @@ export const TOOLS = {
         },
     },
     memory_basement: {
-        def: {
-            name: "memory_basement",
-            description: "Send a memory to the basement (archive it). Sets archived=true and stamps archivedAt. " +
-                "The memory is removed from bootstrap and default search but remains retrievable via " +
-                "memory_get and memory_search(includeArchived:true). Deliberate and GLOBAL — this is a " +
-                "visibility flag, not a deletion: provenance and history are untouched. Scoped to your own memories only.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "ID of the memory to basement (archive)" },
-                },
-                required: ["id"],
-            },
-        },
         impl: memoryBasement,
         contract: {
             summary: "Write echo of the archived record { id, archived:true, archivedAt, ... }. No internal embedding fields; the flip round-trips via memory_get.",
@@ -1058,19 +970,6 @@ export const TOOLS = {
         },
     },
     memory_restore: {
-        def: {
-            name: "memory_restore",
-            description: "Restore a basemented (archived) memory. Clears archived and archivedAt. Deliberate and GLOBAL — " +
-                "this un-retires the memory for EVERY session, not a session-local view (per-session reuse is " +
-                "drawers, which do not exist yet). Scoped to your own memories only.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "ID of the memory to restore (un-archive)" },
-                },
-                required: ["id"],
-            },
-        },
         impl: memoryRestore,
         contract: {
             summary: "Write echo of the restored record { id, archived:false, ... }. No internal embedding fields; the flip round-trips via memory_get.",
@@ -1082,20 +981,6 @@ export const TOOLS = {
         },
     },
     memory_get: {
-        def: {
-            name: "memory_get",
-            description: "Retrieve a specific memory by ID. The record's raw embedding vector is omitted by default (it is large and not useful to a caller); pass includeEmbedding=true to include it.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "Memory ID" },
-                    includeTrust: { type: "boolean", description: "Attach a trust-evidence block (provenance, author, usage, freshness, supersession) to the record. Default false." },
-                    includeEmbedding: { type: "boolean", description: "Include the raw embedding vector (hundreds of floats) in the returned record. Omitted by default because it is large and rarely useful to a caller. Default false." },
-                },
-                required: ["id"],
-            },
-        },
         impl: memoryGet,
         contract: {
             summary: "The full memory record { id, agentId, content, durability, createdAt, ... } for the caller's own id — embedding + embeddingModel stripped by default.",
@@ -1107,16 +992,6 @@ export const TOOLS = {
         },
     },
     memory_delete: {
-        def: {
-            name: "memory_delete",
-            description: "Delete a memory by ID. You can only delete your own memories.",
-            annotations: { destructiveHint: true },
-            inputSchema: {
-                type: "object",
-                properties: { id: { type: "string", description: "Memory ID to delete" } },
-                required: ["id"],
-            },
-        },
         impl: memoryDelete,
         contract: {
             summary: "Deletes the caller's own memory at any durability tier (success echo is thin). Cross-owner deletion returns { error, status:403 } for a non-admin; a deleted row round-trips as gone via memory_get.",
@@ -1125,31 +1000,6 @@ export const TOOLS = {
         },
     },
     bootstrap: {
-        def: {
-            name: "bootstrap",
-            description: "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    maxTokens: { type: "number", description: "Content-selection budget in tokens (default 4000): the hard cap on how much soul/memory/finding CONTENT is selected. The actual serialized response (reported by tokenEstimate) may exceed this by the structured-container JSON scaffolding — maxTokens bounds what is selected, not the raw output size. Raise it to include more content." },
-                    currentTask: { type: "string", description: "Current task — enables semantic search for relevant memories" },
-                    channel: { type: "string", description: "Channel name (discord, tps-mail, claude-code)" },
-                    surface: { type: "string", description: "Surface name (tps-build, tps-review, cli-session)" },
-                    subjects: { type: "array", items: { type: "string" }, description: "Entity names to preload context for" },
-                    entities: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Your declared attention-plane vocabulary strings (e.g. \"issue:owner/repo#123\") for collision surfacing's 'Others in the room' block — teammates with overlapping active work. Falls back to your own most-recent workspace-state entities when omitted.",
-                    },
-                    includeTrust: { type: "boolean", description: "Also return a `trust` array with a per-included-memory trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
-                    abstain: { type: "boolean", description: "Opt into a task-relevance abstention verdict: also return an `abstention` object ({ abstained, bestScore, threshold }) reporting whether any memory covered `currentTask` above a global confidence threshold. Default false." },
-                    includeContext: { type: "boolean", description: "Also return the prose `context` string — a human-readable mirror of the structured soul/memories/predicted/teammateFindings containers (which are the canonical payload). Default false here: the structured fields already carry everything, so shipping the prose too would double the payload." },
-                    maxEvents: { type: "number", description: "Cap on how many recent org events to return (default 10). Events are counted against maxTokens like every other content section." },
-                    includeEventDetail: { type: "boolean", description: "Also include each org event's verbose `detail` JSON (migration internals, etc.). Default false: bootstrap ships lean events (id/kind/summary/createdAt/targetIds/scope); `detail` mostly restates the summary and is pure bloat for a connector." },
-                },
-            },
-        },
         impl: bootstrap,
         contract: {
             summary: "Session context: { agentId, soul, memories, predicted, teammateFindings, events, sections, tokenEstimate, memoriesIncluded, ..., context, flairVersion }. "
@@ -1159,6 +1009,7 @@ export const TOOLS = {
                 "sections", "tokenEstimate", "maxTokens", "memoriesIncluded", "memoriesAvailable",
                 "memoriesTruncated", "teammateFindingsIncluded", "teammateFindingsTruncated",
                 "teammateFindingsMatched", "context", "flairVersion",
+                "eventWatermark", "eventsHasMore", "eventsRemaining",
                 // flair#1270 — the payload token LEDGER: every token-charged content
                 // class has a counter, so tokenEstimate ≈ scaffoldTokens + soulTokens +
                 // memoryTokens + trustTokens + eventsTokens decomposes from the payload
@@ -1174,6 +1025,7 @@ export const TOOLS = {
                 teammateFindingsMatched: "number", context: "string", flairVersion: "string",
                 soulTokens: "number", memoryTokens: "number", trustTokens: "number",
                 eventsTokens: "number", scaffoldTokens: "number",
+                eventWatermark: "string", eventsHasMore: "boolean", eventsRemaining: "number",
             },
             invariants: {
                 // count == delivered — the historical count/charge/deliver drift.
@@ -1262,18 +1114,6 @@ export const TOOLS = {
         },
     },
     soul_set: {
-        def: {
-            name: "soul_set",
-            description: "Soul changes require operator credentials through the REST API or CLI; runtime tool calls are refused.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    key: { type: "string", description: "Entry key (e.g. 'role', 'standards', 'project')" },
-                    value: { type: "string", description: "Entry value" },
-                },
-                required: ["key", "value"],
-            },
-        },
         impl: soulSet,
         contract: {
             summary: "Refuses runtime Soul writes, including admin-agent delegation, with { error, status:403 }. Operators use the authenticated REST or CLI path.",
@@ -1282,16 +1122,6 @@ export const TOOLS = {
         },
     },
     soul_get: {
-        def: {
-            name: "soul_get",
-            description: "Get a personality or project context entry.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: { key: { type: "string", description: "Entry key" } },
-                required: ["key"],
-            },
-        },
         impl: soulGet,
         contract: {
             summary: "The soul entry { id, agentId, key, value, createdAt } for the caller's own `${agentId}:${key}`.",
@@ -1301,22 +1131,6 @@ export const TOOLS = {
         },
     },
     flair_workspace_set: {
-        def: {
-            name: "flair_workspace_set",
-            description: "Set your agent's current workspace state in the Office Space coordination layer. Attributed to you — you can only write your own state.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    ref: { type: "string", description: "Workspace ref — branch, worktree, or task ref" },
-                    label: { type: "string", description: "Human-readable label" },
-                    provider: { type: "string", description: "Provider/runtime (default mcp)" },
-                    task: { type: "string", description: "Task/issue id" },
-                    phase: { type: "string", description: "Current phase (design, implement, review)" },
-                    summary: { type: "string", description: "Short summary of current state" },
-                },
-                required: ["ref"],
-            },
-        },
         impl: workspaceSet,
         contract: {
             summary: "Writes the caller's workspace state keyed `${agentId}:${ref}`, attributed to the caller (never the body). The echo is thin; persistence is verified in storage.",
@@ -1324,21 +1138,6 @@ export const TOOLS = {
         },
     },
     flair_orgevent: {
-        def: {
-            name: "flair_orgevent",
-            description: "Publish an org-wide coordination event (claim/release/status) to the Office Space. Attributed to you — you cannot publish as another agent.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    kind: { type: "string", description: "Event kind (coord.claim, coord.release, status)" },
-                    summary: { type: "string", description: "Short summary of the event" },
-                    detail: { type: "string", description: "Longer detail payload" },
-                    scope: { type: "string", description: "Scope (an agent id, repo, or 'org')" },
-                    targets: { type: "array", items: { type: "string" }, description: "Recipient agent ids" },
-                },
-                required: ["kind", "summary"],
-            },
-        },
         impl: orgEvent,
         contract: {
             summary: "Publishes an org event attributed to the caller (authorId from identity, never the body). The echo is thin; persistence is verified in storage.",
@@ -1346,21 +1145,6 @@ export const TOOLS = {
         },
     },
     attention: {
-        def: {
-            name: "attention",
-            description: "What's touching entity E in the last N days? A unified, grouped-by-source view across memories, " +
-                "relationships, active work (WorkspaceState), teammate presence, and org events. Entity must be a " +
-                "vocabulary string (e.g. 'repo:owner/name', 'issue:owner/repo#123', 'subsystem:embeddings').",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    entity: { type: "string", description: "Vocabulary string, exact match (type:value — e.g. 'repo:tpsdev-ai/flair')" },
-                    days: { type: "number", description: "Window size in days (default 7)" },
-                },
-                required: ["entity"],
-            },
-        },
         impl: attention,
         contract: {
             summary: "Grouped-by-source view { entity, windowDays, since, groups:{memory,relationship,workspaceState,presence,orgEvent}, counts } for entity E over N days.",
@@ -1373,21 +1157,6 @@ export const TOOLS = {
         },
     },
     record_usage: {
-        def: {
-            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. " +
-                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). 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)" },
-                },
-            },
-        },
         impl: recordUsage,
         contract: {
             summary: "Invariant acknowledgement { recorded:true } — byte-identical regardless of how many ids counted (no id enumeration, Sherlock).",
@@ -1396,7 +1165,7 @@ export const TOOLS = {
             invariants: { fullyResolved: true },
         },
     },
-};
+});
 /** The tool definitions for a tools/list response (exactly the 12 curated tools). */
 export function listToolDefs() {
     return Object.values(TOOLS).map((t) => t.def);

package/dist/resources/memory-visibility.js

@@ -6,7 +6,7 @@
  *   - resources/memory-read-scope.ts's resolveReadScope() — the cross-agent
  *     READ scope every read path (Memory.search/get, SemanticSearch,
  *     MemoryBootstrap, the by-id auth-middleware guard) resolves through.
- *   - src/cli.ts's runFederationSyncOnce() — the federation-sync PUSH filter
+ *   - src/commands/federation.ts's runFederationSyncOnce() — the federation-sync PUSH filter
  *     that must not replicate `private` memories to peer instances.
  *
  * Deliberately has ZERO imports — not even "harper". That is
@@ -16,8 +16,8 @@
  * imports `databases` from "harper", and that package's
  * top-level init eagerly resolves storage paths and THROWS when there is no
  * live Harper runtime backing it (confirmed empirically — it takes down
- * even `flair --help`). So src/cli.ts must never import
- * resources/memory-read-scope.ts (or anything else that drags that
+ * even `flair --help`). So the CLI (src/cli.ts / src/commands/federation.ts)
+ * must never import resources/memory-read-scope.ts (or anything else that drags that
  * side-effecting import in) directly. This module is the safe seam: a pure
  * function + constant that both sides can import without dragging in
  * "harper".

package/dist/resources/migration-boot.js

@@ -61,6 +61,7 @@ import { buildRegistry } from "./migrations/registry.js";
 import { runMigrationCycle } from "./migrations/runner.js";
 import { markIdleMigrationsFailed, seedIdleProgress, setCyclePhase } from "./migrations/progress.js";
 import { describeUnresolvableDataDir, resolveWritableMigrationDataDir, } from "./migrations/data-dir.js";
+import { scheduleFollowUpCycles } from "./migrations/recheck.js";
 import { getMode } from "./embeddings-provider.js";
 /** Same "resolve the running package's own version" idiom as resources/health.ts. */
 export function resolveRunningVersion() {
@@ -147,6 +148,50 @@ function reportBootFailure(registry, reason) {
     markIdleMigrationsFailed(registry.list().map((m) => m.id), reason);
 }
 let scheduled = false;
+let followUp = null;
+/**
+ * Runs one cycle against an already-resolved writable data dir. Shared by
+ * the boot-keyed first pass and the flair#1073 follow-up rechecks. Never
+ * throws. Returns whether a follow-up series should be armed (true unless
+ * this invocation is itself a follow-up, or the cycle was a hard failure
+ * that needs an operator — those retry on the next restart).
+ */
+async function invokeCycle(registry, dataDir, opts = { followUp: false }) {
+    try {
+        const result = await runMigrationCycle({
+            registry,
+            getTable,
+            dataDir,
+            runningVersion: resolveRunningVersion(),
+        });
+        // `nothing pending` is the healthy no-op; `single-flight` is the
+        // lock guard working as designed on a multi-threaded boot. Anything
+        // else is a cycle that WANTED to run and couldn't, and must be loud.
+        if (!result.ran && result.reason && !isBenignSkip(result.reason)) {
+            if (!opts.followUp) {
+                reportBootFailure(registry, `migration cycle did not run: ${result.reason}`);
+            }
+            else {
+                console.error(`[flair-migrations] follow-up cycle did not run: ${result.reason}`);
+            }
+            return false;
+        }
+        if (opts.followUp && result.ran) {
+            console.info("[flair-migrations] follow-up cycle ran — embedding-stamp (or another pending migration) had work the boot pass missed");
+        }
+        return true;
+    }
+    catch (err) {
+        // Defense-in-depth only — runMigrationCycle is documented to never
+        // throw. A boot-path exception must never surface here regardless.
+        const reason = `unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`;
+        if (!opts.followUp)
+            reportBootFailure(registry, reason);
+        else
+            console.error(`[flair-migrations] ${reason}`);
+        return false;
+    }
+}
 export function scheduleMigrationBoot() {
     if (scheduled)
         return;
@@ -170,28 +215,22 @@ export function scheduleMigrationBoot() {
             // failure at that point is reported back rather than thrown, which is
             // precisely how flair#812 stayed invisible. See data-dir.ts.
             const resolved = resolveWritableMigrationDataDir();
-            if (!resolved.dataDir) {
+            const dataDir = resolved.dataDir;
+            if (!dataDir) {
                 reportBootFailure(registry, describeUnresolvableDataDir(resolved.tried));
                 return;
             }
-            try {
-                const result = await runMigrationCycle({
-                    registry,
-                    getTable,
-                    dataDir: resolved.dataDir,
-                    runningVersion: resolveRunningVersion(),
+            const ok = await invokeCycle(registry, dataDir, { followUp: false });
+            // flair#1073: even a clean "nothing pending" can be a Fabric race
+            // (tables ready, rows not yet visible). Arm delayed rechecks so a
+            // split corpus heals in-process instead of sitting until the next
+            // restart. A hard boot failure does not arm them — those need an
+            // operator or a restart (same as before).
+            if (ok) {
+                followUp?.cancel();
+                followUp = scheduleFollowUpCycles({
+                    run: () => invokeCycle(registry, dataDir, { followUp: true }).then(() => undefined),
                 });
-                // `nothing pending` is the healthy no-op; `single-flight` is the
-                // lock guard working as designed on a multi-threaded boot. Anything
-                // else is a cycle that WANTED to run and couldn't, and must be loud.
-                if (!result.ran && result.reason && !isBenignSkip(result.reason)) {
-                    reportBootFailure(registry, `migration cycle did not run: ${result.reason}`);
-                }
-            }
-            catch (err) {
-                // Defense-in-depth only — runMigrationCycle is documented to never
-                // throw. A boot-path exception must never surface here regardless.
-                reportBootFailure(registry, `unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
             }
         })();
     });
@@ -209,5 +248,7 @@ export function isBenignSkip(reason) {
 // ever boots once).
 export function _resetMigrationBootForTests() {
     scheduled = false;
+    followUp?.cancel();
+    followUp = null;
 }
 scheduleMigrationBoot();