clay-server 4.0.0-beta.8 → 4.0.0

package/lib/knowledge-search.js

@@ -0,0 +1,240 @@
+// Shared BM25 adapter for Clay Knowledge surfaces.
+//
+// There is exactly one ranking implementation in Clay: the generic
+// buildIndex/searchIndex engine in session-search.js, including its tokenizer
+// with CJK/Japanese/Thai bigram segmentation. This module is a thin adapter
+// over it, not a second ranker.
+//
+// Field weighting is expressed by controlled repetition of a field's text
+// before indexing, which is how session-search.js already weights digests.
+// A title repeated three times contributes three times the term frequency of
+// the body, so BM25 saturation and length normalisation still apply normally.
+//
+// Long records are segmented rather than truncated. A record whose body runs to
+// tens of thousands of characters is indexed as several overlapping documents,
+// so a term that appears only near the end is still found. Short fields (title,
+// name, tags) are anchors and are repeated into every segment, so weighting is
+// identical in each one. Segments are collapsed back to one result per original
+// item by taking its best-scoring segment; the caller still applies its own
+// score, recency, and reference tie-breaks on top.
+
+var sessionSearch = require("./session-search");
+
+var MAX_SNIPPET_CHARS = 320;
+var SNIPPET_LEAD_CHARS = 80;
+// A field at or under this length is an anchor, replicated into every segment.
+// Anything longer is windowed.
+var SEGMENT_CHARS = 8000;
+// Overlap so a term straddling a window boundary is still indexed intact.
+var SEGMENT_OVERLAP = 800;
+// Memory bound. A record needing more windows than this is indexed up to the
+// cap; the cap is high enough that no realistic Knowledge record reaches it.
+var MAX_SEGMENTS_PER_ITEM = 64;
+
+function repeat(text, weight) {
+  var out = [];
+  for (var i = 0; i < weight; i++) out.push(text);
+  return out.join(" ");
+}
+
+function normalizeWeight(weight) {
+  return Number.isFinite(weight) ? Math.max(1, Math.floor(weight)) : 1;
+}
+
+function usableFields(fields) {
+  var out = [];
+  for (var i = 0; i < (fields || []).length; i++) {
+    var field = fields[i];
+    if (!field || typeof field.text !== "string" || !field.text) continue;
+    out.push({ text: field.text, weight: normalizeWeight(field.weight) });
+  }
+  return out;
+}
+
+// Kept for callers and tests that want the single-document form. Anchors and
+// short bodies produce exactly this text.
+function weightedText(fields) {
+  var parts = [];
+  var usable = usableFields(fields);
+  for (var i = 0; i < usable.length; i++) parts.push(repeat(usable[i].text, usable[i].weight));
+  return parts.join(" ");
+}
+
+var SEGMENT_STRIDE = SEGMENT_CHARS - SEGMENT_OVERLAP;
+// The maximum searchable characters of one long field that can be indexed
+// before the segment cap stops coverage. Reported to callers so an incomplete
+// index is stated rather than implied.
+var MAX_INDEXED_CHARS = SEGMENT_CHARS + (MAX_SEGMENTS_PER_ITEM - 1) * SEGMENT_STRIDE;
+
+// One shared plan drives both the indexed documents and the coverage report,
+// so what a caller is told was indexed is exactly what was indexed.
+function planSegments(fields) {
+  var usable = usableFields(fields);
+  var anchors = [];
+  var longs = [];
+  for (var i = 0; i < usable.length; i++) {
+    if (usable[i].text.length > SEGMENT_CHARS) longs.push(usable[i]);
+    else anchors.push(usable[i]);
+  }
+
+  var windows = [];
+  var totalChars = 0;
+  var indexedChars = 0;
+  for (var l = 0; l < longs.length; l++) {
+    var text = longs[l].text;
+    totalChars += text.length;
+    var covered = 0;
+    for (var offset = 0; offset < text.length && windows.length < MAX_SEGMENTS_PER_ITEM; offset += SEGMENT_STRIDE) {
+      var end = Math.min(text.length, offset + SEGMENT_CHARS);
+      windows.push({ field: longs[l], start: offset, end: end });
+      covered = end;
+      if (end >= text.length) break;
+    }
+    indexedChars += covered;
+  }
+  for (var a = 0; a < anchors.length; a++) {
+    totalChars += anchors[a].text.length;
+    indexedChars += anchors[a].text.length;
+  }
+
+  return {
+    anchors: anchors,
+    longs: longs,
+    windows: windows,
+    totalChars: totalChars,
+    indexedChars: indexedChars,
+    complete: indexedChars >= totalChars,
+  };
+}
+
+// How much of an item's searchable text this adapter can index. `complete` is
+// false when the segment cap stopped short, which means a term appearing only
+// in the uncovered tail cannot be ranked.
+function coverage(fields) {
+  var plan = planSegments(fields);
+  return { totalChars: plan.totalChars, indexedChars: plan.indexedChars, complete: plan.complete };
+}
+
+// One item becomes one or more BM25 documents. Short fields anchor every
+// segment so title and tag weighting is consistent wherever the body matched.
+function segmentTexts(fields) {
+  var plan = planSegments(fields);
+  var anchorText = weightedText(plan.anchors);
+  if (plan.windows.length === 0) return [anchorText];
+
+  var texts = [];
+  for (var w = 0; w < plan.windows.length; w++) {
+    var window = plan.windows[w];
+    var body = repeat(window.field.text.substring(window.start, window.end), window.field.weight);
+    texts.push(anchorText ? anchorText + " " + body : body);
+  }
+  return texts;
+}
+
+// Build the generic {id, text, meta} documents the shared engine expects.
+// project(item, position) must return { id, fields, meta }. One item may yield
+// several documents; each carries the item's position so results collapse back.
+function buildDocs(items, project) {
+  var docs = [];
+  for (var i = 0; i < (items || []).length; i++) {
+    var projected = project(items[i], i);
+    if (!projected) continue;
+    var texts = segmentTexts(projected.fields);
+    for (var s = 0; s < texts.length; s++) {
+      docs.push({
+        id: projected.id,
+        text: texts[s],
+        meta: { position: i, segment: s, id: projected.id, meta: projected.meta },
+      });
+    }
+  }
+  return docs;
+}
+
+// Rank with the shared engine. Returns [{ id, score, meta }] highest first, one
+// entry per original item. A query that tokenizes to nothing scores nothing,
+// rather than silently falling back to a different matching strategy.
+//
+// Aggregation across an item's segments is the maximum segment score: a record
+// is as relevant as its best-matching part, so a long record is neither
+// penalised for its unmatched bulk nor rewarded for repeating a term across
+// windows that overlap.
+function rank(items, query, project, maxResults) {
+  var docs = buildDocs(items, project);
+  if (docs.length === 0) return [];
+  var index = sessionSearch.buildIndex(docs);
+  var scored = sessionSearch.searchIndex(index, query, docs.length);
+
+  var bestByPosition = new Map();
+  for (var i = 0; i < scored.length; i++) {
+    var envelope = scored[i].meta;
+    if (!envelope) continue;
+    var existing = bestByPosition.get(envelope.position);
+    if (existing && existing.score >= scored[i].score) continue;
+    bestByPosition.set(envelope.position, { id: envelope.id, score: scored[i].score, meta: envelope.meta });
+  }
+
+  var collapsed = [];
+  bestByPosition.forEach(function (entry) { collapsed.push(entry); });
+  // Stable, deterministic ordering before the caller applies its own
+  // recency and reference tie-breaks.
+  collapsed.sort(function (a, b) {
+    return b.score - a.score || compareIds(a.id, b.id);
+  });
+  var limit = maxResults || collapsed.length;
+  return collapsed.slice(0, limit);
+}
+
+// Locale-independent lexical order over UTF-16 code units, for the opaque ids
+// and refs that Knowledge uses as its deterministic tie-break.
+//
+// Those identifiers are base64url, so they contain both "-" (0x2D) and "_"
+// (0x5F). String.prototype.localeCompare applies collation rules that order
+// those two the other way round from code-unit order, and the result depends on
+// the ICU data the runtime happens to carry, so it cannot express a
+// deterministic order that holds across machines. This matches the default
+// Array.prototype.sort ordering exactly.
+function compareIds(a, b) {
+  var left = String(a);
+  var right = String(b);
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// A snippet centred on the first query term that appears in the text, so the
+// excerpt shows why the document matched rather than just its opening. Works
+// across the whole record, not only its first segment.
+function snippet(text, query, maxChars) {
+  if (typeof text !== "string" || !text) return "";
+  var limit = maxChars || MAX_SNIPPET_CHARS;
+  var haystack = text.toLowerCase();
+  var tokens = sessionSearch.tokenize(query || "");
+  var best = -1;
+  for (var i = 0; i < tokens.length; i++) {
+    var at = haystack.indexOf(tokens[i]);
+    if (at !== -1 && (best === -1 || at < best)) best = at;
+  }
+  if (best === -1) {
+    var raw = (query || "").trim().toLowerCase();
+    if (raw) best = haystack.indexOf(raw);
+  }
+  var start = best === -1 ? 0 : Math.max(0, best - SNIPPET_LEAD_CHARS);
+  return text.substring(start, start + limit);
+}
+
+module.exports = {
+  MAX_SNIPPET_CHARS: MAX_SNIPPET_CHARS,
+  SEGMENT_CHARS: SEGMENT_CHARS,
+  SEGMENT_OVERLAP: SEGMENT_OVERLAP,
+  SEGMENT_STRIDE: SEGMENT_STRIDE,
+  MAX_SEGMENTS_PER_ITEM: MAX_SEGMENTS_PER_ITEM,
+  MAX_INDEXED_CHARS: MAX_INDEXED_CHARS,
+  tokenize: sessionSearch.tokenize,
+  weightedText: weightedText,
+  planSegments: planSegments,
+  coverage: coverage,
+  segmentTexts: segmentTexts,
+  buildDocs: buildDocs,
+  compareIds: compareIds,
+  rank: rank,
+  snippet: snippet,
+};

package/lib/mate-knowledge-mcp-server.js

@@ -0,0 +1,151 @@
+// SDK-free `clay-knowledge` MCP tool definitions for Mate Knowledge.
+//
+// Two disjoint tool sets. An ordinary Mate gets tools with no mateId, owner, or
+// scope argument at all, because the binding decides the scope and a tool
+// argument must never be able to widen it or reveal that other Mates exist.
+// Authoritative builtin Clay gets same-user cross-Mate read tools that may name
+// a mateId for list and search, while read resolves an opaque reference inside
+// the authorized user's Mate scopes only.
+
+var buildShape = require("./session-spawn-mcp-server").buildShape;
+var service = require("./mate-knowledge-service");
+
+var MATE_CONTRACT =
+  "Your Knowledge is the durable personal and expertise context you own: what you have learned, the material you keep, and your accumulated observations. " +
+  "It is yours alone. There are no other Knowledge collections available to you here, and project Logs are a separate, unrelated surface. " +
+  "Search it when recalling something specific would genuinely change your answer, and read only the records you actually need. " +
+  "Do not enumerate or restate your Knowledge to the user unasked, and never reproduce whole records as filler.";
+
+var CLAY_CONTRACT =
+  "You may read the Knowledge of Mates belonging to the current user in order to coordinate between them, and only for that user. " +
+  "Use it to find who holds relevant expertise or context, and to answer with that context attributed to the Mate that owns it. " +
+  "Search first, read narrowly, and cite the owning Mate. Never reproduce a Mate's Knowledge wholesale, and never present it as your own.";
+
+var REF_DESCRIPTION = "Opaque knowledge reference returned by a list or search tool.";
+var PAGE_DESCRIPTION = "Page size, from 1 to " + service.MAX_PAGE + ".";
+var CURSOR_DESCRIPTION = "Opaque pagination cursor from a previous response.";
+var OFFSET_DESCRIPTION = "Character offset to start from. Omit for the beginning; pass the previous response's nextOffset to continue.";
+var MAX_CHARS_DESCRIPTION = "Characters to return, from 1 to " + service.MAX_READ_CHARS + ". Defaults to " + service.DEFAULT_READ_CHARS + ".";
+var READ_RESULT = " The whole record is reassembled and verified before any slice is returned. The response carries offset, totalChars, nextOffset, and complete; when nextOffset is not null, call again with it to continue.";
+
+function textResult(value) {
+  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
+}
+
+function errorResult(error) {
+  return Promise.resolve({
+    content: [{ type: "text", text: "Error: " + (error && error.message ? error.message : String(error)) }],
+    isError: true,
+  });
+}
+
+// An unbound descriptor exists only so a tool list can be advertised before a
+// session is known. Every call against it fails closed.
+function handler(bound, method) {
+  return function (args) {
+    if (!bound || typeof bound[method] !== "function") {
+      return errorResult(new Error("Knowledge tools require an exact session-bound Mate."));
+    }
+    try {
+      return textResult(bound[method](args || {}));
+    } catch (e) {
+      return errorResult(e);
+    }
+  };
+}
+
+function mateTools(bound) {
+  return [
+    {
+      name: "list_knowledge",
+      description: MATE_CONTRACT + " List your own Knowledge records, most recently updated first. Returns summaries with a short preview, not full records.",
+      inputSchema: buildShape({
+        kind: { type: "string", description: "Optional record kind filter, such as knowledge-file, memory-summary, session-digest, or user-observation." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }),
+      handler: handler(bound, "listKnowledge"),
+    },
+    {
+      name: "search_knowledge",
+      description: MATE_CONTRACT + " Search your own Knowledge by relevance. Returns ranked summaries with a matching snippet.",
+      inputSchema: buildShape({
+        query: { type: "string", description: "Search query." },
+        kind: { type: "string", description: "Optional record kind filter." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }, ["query"]),
+      handler: handler(bound, "searchKnowledge"),
+    },
+    {
+      name: "read_knowledge",
+      description: MATE_CONTRACT + " Read one of your own Knowledge records. Read only what you need." + READ_RESULT,
+      inputSchema: buildShape({
+        ref: { type: "string", description: REF_DESCRIPTION },
+        offset: { type: "number", description: OFFSET_DESCRIPTION },
+        maxChars: { type: "number", description: MAX_CHARS_DESCRIPTION },
+      }, ["ref"]),
+      handler: handler(bound, "readKnowledge"),
+    },
+  ];
+}
+
+function clayTools(bound) {
+  return [
+    {
+      name: "list_mate_knowledge",
+      description: CLAY_CONTRACT + " List Knowledge records across the current user's Mates, or one named Mate. Available only to authoritative builtin Clay.",
+      inputSchema: buildShape({
+        mateId: { type: "string", description: "Optional exact Mate id belonging to the current user. Omit to span all of them." },
+        kind: { type: "string", description: "Optional record kind filter." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }),
+      handler: handler(bound, "listMateKnowledge"),
+    },
+    {
+      name: "search_mate_knowledge",
+      description: CLAY_CONTRACT + " Search Knowledge across the current user's Mates, or one named Mate. Results identify the owning Mate. Available only to authoritative builtin Clay.",
+      inputSchema: buildShape({
+        query: { type: "string", description: "Search query." },
+        mateId: { type: "string", description: "Optional exact Mate id belonging to the current user." },
+        kind: { type: "string", description: "Optional record kind filter." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }, ["query"]),
+      handler: handler(bound, "searchMateKnowledge"),
+    },
+    {
+      name: "read_mate_knowledge",
+      description: CLAY_CONTRACT + " Read one Knowledge record using the opaque reference returned by a list or search tool. The reference resolves only inside the current user's Mate Knowledge. Available only to authoritative builtin Clay." + READ_RESULT,
+      inputSchema: buildShape({
+        ref: { type: "string", description: REF_DESCRIPTION },
+        offset: { type: "number", description: OFFSET_DESCRIPTION },
+        maxChars: { type: "number", description: MAX_CHARS_DESCRIPTION },
+      }, ["ref"]),
+      handler: handler(bound, "readMateKnowledge"),
+    },
+  ];
+}
+
+// A binding is either one Mate's own scope or Clay's cross-Mate read view. The
+// two sets are never advertised together, so no tool name is duplicated.
+function getToolDefs(bound, includeClay) {
+  return includeClay === true ? clayTools(bound) : mateTools(bound);
+}
+
+function createMcpServer(adapter, bound, includeClay) {
+  if (!adapter || typeof adapter.createToolServer !== "function") return null;
+  return adapter.createToolServer({
+    name: "clay-knowledge",
+    version: "1.0.0",
+    tools: getToolDefs(bound, includeClay),
+  });
+}
+
+module.exports = {
+  MATE_CONTRACT: MATE_CONTRACT,
+  CLAY_CONTRACT: CLAY_CONTRACT,
+  getToolDefs: getToolDefs,
+  createMcpServer: createMcpServer,
+};

package/lib/mate-knowledge-migration.js

@@ -0,0 +1,283 @@
+// Automatic upgrade migration: legacy Mate memory and knowledge files into the
+// Clay-wide append-only Knowledge backend.
+//
+// This module owns discovery, the run lock, and versioned state. The actual
+// source-to-record work lives in mate-knowledge-sync.js, which is the same code
+// the live write-through bridge uses, so a startup import and a post-mutation
+// mirror can never disagree about how a source is represented.
+//
+// Properties this migration guarantees:
+//   - Non-destructive. Legacy files are read and never written, renamed, or
+//     removed. They stay the live source for the existing read paths.
+//   - Idempotent. Every source unit carries a stable import key, so a restart,
+//     a partial run, or a deleted state file re-imports nothing.
+//   - Overlap-safe. A run lock keeps two daemons from importing at once, and
+//     the importer folds away a duplicate even if the lock is bypassed.
+//   - Torn-input tolerant. An unparseable journal line is counted and skipped;
+//     it never aborts the run.
+//   - Honest. A source that cannot be represented is reported as a failure
+//     rather than silently truncated or skipped.
+//   - Isolated. Each user's Mates land in their own scope, derived from the
+//     Mate storage root that already separates users on disk.
+
+var fs = require("fs");
+var path = require("path");
+var config = require("./config");
+var recordStore = require("./knowledge-record-store");
+var mateSync = require("./mate-knowledge-sync");
+
+var MIGRATION_NAME = "mate-knowledge";
+var MIGRATION_VERSION = 2;
+var LOCK_STALE_MS = 10 * 60 * 1000;
+
+function knowledgeRoot() {
+  return recordStore.knowledgeRoot();
+}
+
+function statePath(baseDir) {
+  return path.join(baseDir || knowledgeRoot(), "migration-state.json");
+}
+
+function lockPath(baseDir) {
+  return path.join(baseDir || knowledgeRoot(), ".mate-migration.lock");
+}
+
+function isMateDirName(name) {
+  return typeof name === "string" && name.indexOf("mate_") === 0;
+}
+
+function safeReadDir(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return [];
+  }
+}
+
+function mateNames(matesRoot) {
+  var names = {};
+  try {
+    var parsed = JSON.parse(fs.readFileSync(path.join(matesRoot, "mates.json"), "utf8"));
+    var list = (parsed && parsed.mates) || [];
+    for (var i = 0; i < list.length; i++) {
+      if (list[i] && list[i].id) names[list[i].id] = list[i].name || null;
+    }
+  } catch (e) {
+    // A missing or corrupt registry only costs provenance detail.
+  }
+  return names;
+}
+
+function collectFromRoot(matesRoot, out) {
+  var names = mateNames(matesRoot);
+  var entries = safeReadDir(matesRoot);
+  for (var i = 0; i < entries.length; i++) {
+    if (!entries[i].isDirectory() || !isMateDirName(entries[i].name)) continue;
+    var scope = mateSync.scopeForMateDir(path.join(matesRoot, entries[i].name));
+    if (!scope) continue;
+    scope.mateName = names[entries[i].name] || null;
+    out.push(scope);
+  }
+}
+
+// Both storage layouts are walked directly rather than through the Mate
+// registry, so a Mate whose registry entry is missing or corrupt still gets
+// its durable content migrated.
+//   single-user:  {CONFIG_DIR}/mates/mate_*
+//   multi-user:   {CONFIG_DIR}/mates/{userId}/mate_*
+//   OS users:     roots supplied by the caller
+function discoverMates(opts) {
+  var options = opts || {};
+  var out = [];
+  var matesHome = options.matesHome || path.join(config.CONFIG_DIR, "mates");
+  collectFromRoot(matesHome, out);
+
+  var entries = safeReadDir(matesHome);
+  for (var i = 0; i < entries.length; i++) {
+    if (!entries[i].isDirectory() || isMateDirName(entries[i].name)) continue;
+    collectFromRoot(path.join(matesHome, entries[i].name), out);
+  }
+
+  var roots = options.extraRoots || [];
+  for (var r = 0; r < roots.length; r++) {
+    if (!roots[r] || !roots[r].matesRoot) continue;
+    collectFromRoot(roots[r].matesRoot, out);
+  }
+  return out;
+}
+
+// --- Versioned state -------------------------------------------------
+
+// State is a fast-path hint and an audit trail, never the authority. Deleting
+// it makes the next run re-scan and import nothing, because the import keys
+// already present in the records are what actually decide.
+function loadState(baseDir) {
+  try {
+    var parsed = JSON.parse(fs.readFileSync(statePath(baseDir), "utf8"));
+    if (parsed && parsed.version === MIGRATION_VERSION && parsed.scopes) return parsed;
+  } catch (e) {}
+  return { version: MIGRATION_VERSION, migration: MIGRATION_NAME, scopes: {}, lastRunAt: 0 };
+}
+
+function saveState(baseDir, state) {
+  var target = statePath(baseDir);
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    var temporary = target + ".tmp." + process.pid;
+    fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n");
+    config.chmodSafe(temporary, 0o600);
+    fs.renameSync(temporary, target);
+  } catch (e) {
+    // A migration that cannot record state still completed its imports.
+  }
+}
+
+// --- Run lock ---------------------------------------------------------
+
+function writeLock(target) {
+  var payload = JSON.stringify({ pid: process.pid, startedAt: Date.now() }) + "\n";
+  var fd = fs.openSync(target, "wx");
+  try {
+    fs.writeSync(fd, Buffer.from(payload, "utf8"));
+  } finally {
+    fs.closeSync(fd);
+  }
+  return target;
+}
+
+// A live holder always wins, no matter how long it has been running. Stealing
+// a lock from a running daemon would let two daemons import at once and would
+// let the first one unlink the second one's lock on completion. Age alone can
+// only reclaim a lock whose holder is gone or unidentifiable.
+function acquireLock(baseDir) {
+  var target = lockPath(baseDir);
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+  } catch (e) {}
+  try {
+    return writeLock(target);
+  } catch (e) {
+    if (!e || e.code !== "EEXIST") return null;
+  }
+
+  var holder = null;
+  try {
+    holder = JSON.parse(fs.readFileSync(target, "utf8"));
+  } catch (e2) {}
+
+  var pid = holder && holder.pid;
+  if (pid && config.isPidAlive(pid)) return null;
+
+  // No identifiable holder: only reclaim once it is unambiguously abandoned.
+  if (!pid) {
+    var age = Date.now() - ((holder && holder.startedAt) || 0);
+    if (age < LOCK_STALE_MS) return null;
+  }
+
+  try {
+    fs.unlinkSync(target);
+    return writeLock(target);
+  } catch (e3) {
+    return null;
+  }
+}
+
+function releaseLock(target) {
+  if (!target) return;
+  try { fs.unlinkSync(target); } catch (e) {}
+}
+
+// --- Entry point -------------------------------------------------------
+
+function run(opts) {
+  var options = opts || {};
+  var baseDir = options.baseDir || knowledgeRoot();
+  var summary = mateSync.newSummary();
+  summary.migration = MIGRATION_NAME;
+  summary.version = MIGRATION_VERSION;
+  summary.scopes = 0;
+
+  var lock = acquireLock(baseDir);
+  if (!lock) {
+    summary.skipped = "locked";
+    return summary;
+  }
+  try {
+    var mates = discoverMates(options);
+    var state = loadState(baseDir);
+    for (var i = 0; i < mates.length; i++) {
+      var before = summary.failed;
+      try {
+        mateSync.reconcileMate({
+          scope: mates[i],
+          mateName: mates[i].mateName,
+          baseDir: baseDir,
+          actor: { type: "migration" },
+          summary: summary,
+        });
+      } catch (e) {
+        summary.failed++;
+        summary.errors.push({ scopeId: mates[i].scopeId, message: e.message });
+      }
+      summary.scopes++;
+      state.scopes[mates[i].scopeId] = {
+        version: MIGRATION_VERSION,
+        mateId: mates[i].mateId,
+        userId: mates[i].userId,
+        completedAt: Date.now(),
+        // A scope with a failure is recorded as incomplete so it is never
+        // reported as migrated while a source is missing content.
+        complete: summary.failed === before,
+      };
+    }
+    state.lastRunAt = Date.now();
+    saveState(baseDir, state);
+    return summary;
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+// Startup wrapper: never throws, never blocks boot, logs only when it did work
+// or when a source could not be represented.
+function runAtStartup(opts) {
+  var summary;
+  try {
+    summary = run(opts);
+  } catch (e) {
+    console.error("[knowledge-migration] Mate knowledge migration failed:", e.message);
+    return null;
+  }
+  if (summary.skipped === "locked") return summary;
+  if (summary.created > 0 || summary.revised > 0 || summary.deleted > 0) {
+    console.log("[knowledge-migration] Mate knowledge: " + summary.created + " imported, " +
+      summary.revised + " revised, " + summary.deleted + " tombstoned, " +
+      summary.unchanged + " unchanged across " + summary.scopes + " scope(s)");
+  }
+  if (summary.failed > 0) {
+    console.error("[knowledge-migration] " + summary.failed + " source(s) could not be migrated; " +
+      "legacy files remain authoritative. First error: " + (summary.errors[0] && summary.errors[0].message));
+  }
+  return summary;
+}
+
+module.exports = {
+  MIGRATION_NAME: MIGRATION_NAME,
+  MIGRATION_VERSION: MIGRATION_VERSION,
+  LOCK_STALE_MS: LOCK_STALE_MS,
+  IDENTITY_FILES: mateSync.IDENTITY_FILES,
+  EXCLUDED_FILES: mateSync.EXCLUDED_FILES,
+  JOURNAL_KINDS: mateSync.JOURNAL_KINDS,
+  ownerKeyForRoot: mateSync.ownerKeyForRoot,
+  scopeIdFor: mateSync.scopeIdFor,
+  scopeForMateDir: mateSync.scopeForMateDir,
+  sourceKindFor: mateSync.sourceKindFor,
+  discoverMates: discoverMates,
+  statePath: statePath,
+  lockPath: lockPath,
+  loadState: loadState,
+  acquireLock: acquireLock,
+  releaseLock: releaseLock,
+  run: run,
+  runAtStartup: runAtStartup,
+};