@llmnesia/mcp 0.2.4 → 0.2.6

package/dist/{chunk-NSVHWVEK.js → chunk-HL5QE57W.js}

@@ -3,7 +3,7 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-JSNSTAFD.js";
+} from "./chunk-YRK2DRGG.js";
 
 // src/config.ts
 import { readFileSync } from "fs";
@@ -13,14 +13,22 @@ var CORPUS_FORMAT_VERSION = 2;
 function nativeHostConfigPath() {
   return join(homedir(), ".llmnesia", "config.json");
 }
-function readNativeHostCorpusRoot() {
+function readNativeHostConfig() {
   try {
     const parsed = JSON.parse(readFileSync(nativeHostConfigPath(), "utf8"));
-    return typeof parsed.corpusRoot === "string" ? parsed.corpusRoot : void 0;
+    return parsed && typeof parsed === "object" ? parsed : void 0;
   } catch {
     return void 0;
   }
 }
+function readNativeHostCorpusRoot() {
+  const root = readNativeHostConfig()?.corpusRoot;
+  return typeof root === "string" ? root : void 0;
+}
+function readNativeHostViewerExtensionId() {
+  const id = readNativeHostConfig()?.viewerExtensionId;
+  return typeof id === "string" ? id : void 0;
+}
 function resolveCorpusDir(explicit) {
   const raw = explicit ?? process.env.LLMNESIA_CORPUS_DIR ?? readNativeHostCorpusRoot() ?? "~/.llmnesia/corpus";
   return expandHome(raw);
@@ -63,6 +71,14 @@ var CorpusPaths = class {
   get metaFile() {
     return join2(this.root, "meta.json");
   }
+  /** Content-free state for automatic storage maintenance. */
+  get maintenanceStateFile() {
+    return join2(this.root, "maintenance-v1.json");
+  }
+  /** Cross-process lease preventing several MCP clients compacting together. */
+  get maintenanceLockFile() {
+    return join2(this.root, ".maintenance-v1.lock");
+  }
   get inboxDir() {
     return join2(this.root, "inbox");
   }
@@ -228,6 +244,8 @@ var DIR_MODE = 448;
 var FILE_MODE = 384;
 var gzip = promisify(gzipCallback);
 var gunzip = promisify(gunzipCallback);
+var MAINTENANCE_WRITE_WAIT_MS = 2e3;
+var MAINTENANCE_WRITE_POLL_MS = 50;
 var Corpus = class {
   paths;
   // Serialize writes within this process so concurrent upserts (inbox drain +
@@ -291,6 +309,7 @@ var Corpus = class {
    */
   async upsert(record) {
     return this.enqueueWrite(async () => {
+      await waitForMaintenanceLease(this.paths.maintenanceLockFile);
       const canonical = canonicalizeConversation(record);
       const { conversation } = canonical;
       const file = this.paths.compressedConversationFile(conversation.platform, conversation.docId);
@@ -473,6 +492,7 @@ var Corpus = class {
    */
   async migrateLegacyConversations(options = {}) {
     const dryRun = options.dryRun === true;
+    const yieldEvery = Math.max(0, Math.floor(options.yieldEvery ?? 0));
     const before = await this.conversationStorageStats();
     const report = {
       ...before,
@@ -495,18 +515,22 @@ var Corpus = class {
         const legacyFile = join3(dir, name);
         const compressedFile = join3(dir, `${name}.gz`);
         try {
-          const legacy = await readPlainConversationIfExists(legacyFile);
-          if (!legacy) throw new Error("legacy JSON could not be parsed");
-          const compressed = await readCompressedConversationIfExists(compressedFile);
-          const winner = pickNewerConversation(compressed, legacy) ?? legacy;
-          const serialized = serializeConversation(canonicalizeConversation(winner));
-          const compressedBytes = await gzip(Buffer.from(serialized, "utf8"), { level: 9 });
-          report.projectedCompressedBytes -= await fileSizeIfExists(compressedFile);
-          report.projectedCompressedBytes += compressedBytes.byteLength;
-          if (!dryRun) {
-            await writeVerifiedCompressedConversationAtomic(compressedFile, compressedBytes, serialized);
-            await fs.rm(legacyFile);
-          }
+          const migrateOne = async () => {
+            const legacy = await readPlainConversationIfExists(legacyFile);
+            if (!legacy) throw new Error("legacy JSON could not be parsed");
+            const compressed = await readCompressedConversationIfExists(compressedFile);
+            const winner = pickNewerConversation(compressed, legacy) ?? legacy;
+            const serialized = serializeConversation(canonicalizeConversation(winner));
+            const compressedBytes = await gzip(Buffer.from(serialized, "utf8"), { level: 9 });
+            report.projectedCompressedBytes -= await fileSizeIfExists(compressedFile);
+            report.projectedCompressedBytes += compressedBytes.byteLength;
+            if (!dryRun) {
+              await writeVerifiedCompressedConversationAtomic(compressedFile, compressedBytes, serialized);
+              await fs.rm(legacyFile);
+            }
+          };
+          if (dryRun) await migrateOne();
+          else await this.enqueueWrite(migrateOne);
           report.migrated += 1;
           report.legacyRemoved += 1;
         } catch (error) {
@@ -515,6 +539,9 @@ var Corpus = class {
             error: error instanceof Error ? error.message : String(error)
           });
         }
+        if (yieldEvery > 0 && (report.migrated + report.failures.length) % yieldEvery === 0) {
+          await yieldToEventLoop();
+        }
       }
     }
     if (!dryRun && report.failures.length === 0) {
@@ -558,6 +585,23 @@ var Corpus = class {
     );
   }
 };
+function yieldToEventLoop() {
+  return new Promise((resolve2) => setImmediate(resolve2));
+}
+async function waitForMaintenanceLease(file) {
+  const deadline = Date.now() + MAINTENANCE_WRITE_WAIT_MS;
+  while (true) {
+    try {
+      await fs.access(file);
+    } catch {
+      return;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error("automatic corpus maintenance is in progress; retry this write shortly");
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, MAINTENANCE_WRITE_POLL_MS));
+  }
+}
 async function readJsonIfExists(file) {
   try {
     const raw = await fs.readFile(file, "utf8");
@@ -1359,43 +1403,421 @@ function normalizeMatchRole(role) {
   return role === "assistant" || role === "user" || role === "system" ? role : "unknown";
 }
 
+// src/storageMaintenance.ts
+import { promises as fs4 } from "fs";
+import { join as join5 } from "path";
+async function inspectCorpusStorage(corpus) {
+  const conversations = await corpus.conversationStorageStats();
+  const processed = await directoryFiles(corpus.paths.processedDir);
+  const quarantine = await directoryFiles(corpus.paths.quarantineDir);
+  const activeNames = [
+    corpus.paths.indexDbFile,
+    `${corpus.paths.indexDbFile}-wal`,
+    `${corpus.paths.indexDbFile}-shm`
+  ];
+  const activeIndex = await explicitFiles(activeNames);
+  const staleNames = await staleIndexFiles(corpus.paths.indexDir);
+  const stalePaths = staleNames.flatMap((name) => {
+    const base = join5(corpus.paths.indexDir, name);
+    return [base, `${base}-wal`, `${base}-shm`];
+  });
+  const staleIndexes = await explicitFiles(stalePaths);
+  const root = await directoryFiles(corpus.paths.root);
+  const classifiedBytes = conversations.legacyBytes + conversations.compressedBytes + processed.bytes + quarantine.bytes + activeIndex.bytes + staleIndexes.bytes;
+  const classifiedFiles = conversations.legacyFiles + conversations.compressedFiles + processed.files + quarantine.files + activeIndex.files + staleIndexes.files;
+  const other = {
+    files: Math.max(0, root.files - classifiedFiles),
+    bytes: Math.max(0, root.bytes - classifiedBytes)
+  };
+  return {
+    root: corpus.paths.root,
+    conversations,
+    processed,
+    quarantine,
+    activeIndex,
+    staleIndexes,
+    other,
+    totalBytes: root.bytes,
+    immediatelyReclaimableBytes: processed.bytes + staleIndexes.bytes
+  };
+}
+async function compactCorpus(corpus, options = {}) {
+  const dryRun = options.dryRun === true;
+  const before = await inspectCorpusStorage(corpus);
+  if (dryRun) {
+    const compression = await corpus.migrateLegacyConversations({ dryRun: true });
+    const compressionSavings = Math.max(
+      0,
+      compression.legacyBytes + compression.compressedBytes - compression.projectedCompressedBytes
+    );
+    return {
+      dryRun: true,
+      before,
+      compression,
+      processedRemoved: before.processed,
+      staleIndexesRemoved: before.staleIndexes,
+      after: null,
+      reclaimedBytes: before.immediatelyReclaimableBytes + compressionSavings
+    };
+  }
+  await corpus.init();
+  const processedRemoved = await removeDirectoryFiles(corpus.paths.processedDir);
+  const index = options.index ?? await openSearchIndex(corpus);
+  try {
+    index.compact();
+  } finally {
+    if (!options.index) index.close();
+  }
+  const appliedCompression = await corpus.migrateLegacyConversations({
+    yieldEvery: options.yieldEvery
+  });
+  if (appliedCompression.failures.length > 0) {
+    throw new Error(
+      `Corpus compression left ${appliedCompression.failures.length} legacy file(s) untouched; stale indexes were preserved. Run compact again after fixing the reported files.`
+    );
+  }
+  const staleIndexesRemoved = await removeStaleIndexes(corpus);
+  const after = await inspectCorpusStorage(corpus);
+  return {
+    dryRun: false,
+    before,
+    compression: appliedCompression,
+    processedRemoved,
+    staleIndexesRemoved,
+    after,
+    reclaimedBytes: Math.max(0, before.totalBytes - after.totalBytes)
+  };
+}
+async function removeStaleIndexes(corpus) {
+  const names = await staleIndexFiles(corpus.paths.indexDir);
+  const paths = names.flatMap((name) => {
+    const base = join5(corpus.paths.indexDir, name);
+    return [base, `${base}-wal`, `${base}-shm`];
+  });
+  const before = await explicitFiles(paths);
+  for (const name of names) {
+    await deleteIndexDb(join5(corpus.paths.indexDir, name));
+  }
+  return before;
+}
+async function removeDirectoryFiles(dir) {
+  const before = await directoryFiles(dir);
+  await removeFilesRecursively(dir);
+  return before;
+}
+async function removeFilesRecursively(dir) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join5(dir, entry.name);
+    if (entry.isDirectory()) await removeFilesRecursively(path);
+    else if (entry.isFile()) await fs4.rm(path, { force: true });
+  }
+}
+async function explicitFiles(files) {
+  let count = 0;
+  let bytes = 0;
+  for (const file of files) {
+    try {
+      const stat = await fs4.stat(file);
+      if (stat.isFile()) {
+        count += 1;
+        bytes += stat.size;
+      }
+    } catch {
+    }
+  }
+  return { files: count, bytes };
+}
+async function directoryFiles(dir) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir, { withFileTypes: true });
+  } catch {
+    return { files: 0, bytes: 0 };
+  }
+  let files = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    const path = join5(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await directoryFiles(path);
+      files += nested.files;
+      bytes += nested.bytes;
+    } else if (entry.isFile()) {
+      files += 1;
+      bytes += (await fs4.stat(path)).size;
+    }
+  }
+  return { files, bytes };
+}
+
+// src/autoMaintenance.ts
+import { constants as fsConstants, promises as fs5 } from "fs";
+import { dirname as dirname2 } from "path";
+var FILE_MODE2 = 384;
+var STATE_SCHEMA_VERSION = 1;
+var FORMAT_KEY = `corpus-${CORPUS_FORMAT_VERSION}-index-${INDEX_FORMAT_VERSION}`;
+var AUTO_MAINTENANCE_GRACE_MS = 3 * 24 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_RETRY_MS = 24 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_LOCK_STALE_MS = 6 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_YIELD_EVERY = 25;
+var AUTO_MAINTENANCE_SETTLE_MS = 1e3;
+function isAutomaticMaintenanceDisabled(env = process.env) {
+  const raw = env.LLMNESIA_NO_AUTO_MAINTENANCE;
+  return raw === "1" || raw === "true";
+}
+async function runAutomaticMaintenance(corpus, index, options = {}) {
+  const env = options.env ?? process.env;
+  if (isAutomaticMaintenanceDisabled(env)) return { action: "disabled" };
+  await corpus.init();
+  const now = options.now ?? Date.now;
+  const at = now();
+  const graceMs = options.graceMs ?? AUTO_MAINTENANCE_GRACE_MS;
+  const recheckMs = options.recheckMs ?? AUTO_MAINTENANCE_RECHECK_MS;
+  const retryMs = options.retryMs ?? AUTO_MAINTENANCE_RETRY_MS;
+  const state = await readState(corpus);
+  if (state?.formatKey === FORMAT_KEY && state.status === "complete" && state.completedAt !== void 0 && at - state.completedAt < recheckMs) {
+    return { action: "recently-checked", completedAt: state.completedAt };
+  }
+  if (state?.formatKey === FORMAT_KEY && state.nextEligibleAt !== void 0 && at < state.nextEligibleAt) {
+    return { action: "deferred", until: state.nextEligibleAt };
+  }
+  const before = await inspectCorpusStorage(corpus);
+  if (!hasWork(before)) {
+    await writeState(corpus, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      formatKey: FORMAT_KEY,
+      status: "complete",
+      firstSeenAt: state?.formatKey === FORMAT_KEY ? state.firstSeenAt : at,
+      completedAt: at,
+      beforeBytes: before.totalBytes,
+      afterBytes: before.totalBytes,
+      reclaimedBytes: 0
+    });
+    return { action: "no-work" };
+  }
+  const firstSeenAt = state?.formatKey === FORMAT_KEY ? state.firstSeenAt : at;
+  const eligibleAt = firstSeenAt + Math.max(0, graceMs);
+  if (at < eligibleAt) {
+    await writeState(corpus, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      formatKey: FORMAT_KEY,
+      status: "waiting",
+      firstSeenAt,
+      nextEligibleAt: eligibleAt,
+      beforeBytes: before.totalBytes
+    });
+    return { action: "deferred", until: eligibleAt };
+  }
+  const lease = await acquireLease(
+    corpus,
+    at,
+    options.lockStaleMs ?? AUTO_MAINTENANCE_LOCK_STALE_MS
+  );
+  if (!lease) return { action: "locked" };
+  try {
+    await delay(options.settleMs ?? AUTO_MAINTENANCE_SETTLE_MS);
+    const lockedBefore = await inspectCorpusStorage(corpus);
+    if (!hasWork(lockedBefore)) {
+      await writeState(corpus, {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        formatKey: FORMAT_KEY,
+        status: "complete",
+        firstSeenAt,
+        completedAt: now(),
+        beforeBytes: lockedBefore.totalBytes,
+        afterBytes: lockedBefore.totalBytes,
+        reclaimedBytes: 0
+      });
+      return { action: "no-work" };
+    }
+    await writeState(corpus, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      formatKey: FORMAT_KEY,
+      status: "running",
+      firstSeenAt,
+      lastAttemptAt: at,
+      beforeBytes: lockedBefore.totalBytes
+    });
+    try {
+      const report = await compactCorpus(corpus, {
+        index,
+        yieldEvery: options.yieldEvery ?? AUTO_MAINTENANCE_YIELD_EVERY
+      });
+      const completedAt = now();
+      await writeState(corpus, {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        formatKey: FORMAT_KEY,
+        status: "complete",
+        firstSeenAt,
+        lastAttemptAt: at,
+        completedAt,
+        beforeBytes: report.before.totalBytes,
+        afterBytes: report.after?.totalBytes ?? report.before.totalBytes,
+        reclaimedBytes: report.reclaimedBytes
+      });
+      return { action: "compacted", report };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const retryAt = now() + Math.max(0, retryMs);
+      await writeState(corpus, {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        formatKey: FORMAT_KEY,
+        status: "failed",
+        firstSeenAt,
+        lastAttemptAt: at,
+        nextEligibleAt: retryAt,
+        beforeBytes: lockedBefore.totalBytes,
+        lastError: message
+      });
+      return { action: "failed", error: message, retryAt };
+    }
+  } finally {
+    await lease.release();
+  }
+}
+async function readAutomaticMaintenanceState(corpus) {
+  return readState(corpus);
+}
+function hasWork(report) {
+  return report.conversations.legacyFiles > 0 || report.processed.files > 0 || report.staleIndexes.files > 0;
+}
+async function readState(corpus) {
+  try {
+    const parsed = JSON.parse(
+      await fs5.readFile(corpus.paths.maintenanceStateFile, "utf8")
+    );
+    return parsed?.schemaVersion === STATE_SCHEMA_VERSION ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function writeState(corpus, state) {
+  const file = corpus.paths.maintenanceStateFile;
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  await fs5.mkdir(dirname2(file), { recursive: true });
+  try {
+    const handle = await fs5.open(
+      temp,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      FILE_MODE2
+    );
+    try {
+      await handle.writeFile(`${JSON.stringify(state, null, 2)}
+`, "utf8");
+    } finally {
+      await handle.close();
+    }
+    await fs5.rename(temp, file);
+  } finally {
+    await fs5.rm(temp, { force: true }).catch(() => {
+    });
+  }
+}
+async function acquireLease(corpus, now, staleMs) {
+  const file = corpus.paths.maintenanceLockFile;
+  const token = `${process.pid}-${now}-${Math.random().toString(16).slice(2)}`;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await fs5.open(file, "wx", FILE_MODE2);
+      try {
+        await handle.writeFile(`${JSON.stringify({ token, pid: process.pid, startedAt: now })}
+`, "utf8");
+      } finally {
+        await handle.close();
+      }
+      return {
+        token,
+        release: async () => {
+          try {
+            const current = JSON.parse(await fs5.readFile(file, "utf8"));
+            if (current.token === token) await fs5.rm(file, { force: true });
+          } catch {
+          }
+        }
+      };
+    } catch (error) {
+      if (!isAlreadyExists(error)) throw error;
+      const existing = await readLease(file);
+      const alive = existing?.pid ? isProcessAlive(existing.pid) : false;
+      const age = existing?.startedAt ? now - existing.startedAt : Number.POSITIVE_INFINITY;
+      if (alive && age < staleMs) return null;
+      const stale = `${file}.stale-${token}`;
+      try {
+        await fs5.rename(file, stale);
+        await fs5.rm(stale, { force: true });
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+async function readLease(file) {
+  try {
+    return JSON.parse(await fs5.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function isAlreadyExists(error) {
+  return error.code === "EEXIST";
+}
+function delay(ms) {
+  return ms > 0 ? new Promise((resolve2) => setTimeout(resolve2, ms)) : Promise.resolve();
+}
+
 // src/runtimeInstall.ts
 import { cp, mkdir, readdir as readdir2, rename, rm, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join5 } from "path";
+import { dirname as dirname3, join as join6 } from "path";
 import { fileURLToPath } from "url";
 function defaultSourceDir() {
-  return dirname2(fileURLToPath(import.meta.url));
+  return dirname3(fileURLToPath(import.meta.url));
 }
 function runtimeBinDir(home = homedir2()) {
-  return join5(home, ".llmnesia", "bin");
+  return join6(home, ".llmnesia", "bin");
 }
 async function installRuntime(options = {}) {
   const home = options.home ?? homedir2();
   const sourceDir = options.sourceDir ?? defaultSourceDir();
   const nodePath = options.nodePath ?? process.execPath;
   const binDir = runtimeBinDir(home);
-  const sourceEntry = join5(sourceDir, "cli.js");
+  const sourceEntry = join6(sourceDir, "cli.js");
   if (!existsSync(sourceEntry)) {
     throw new Error(
       `Cannot locate the built runtime: no cli.js in ${sourceDir}. Run this from an installed package (npx -y @llmnesia/mcp@latest install) or build first (npm run build).`
     );
   }
-  const parentDir = dirname2(binDir);
+  const parentDir = dirname3(binDir);
   const nonce = `${process.pid}-${Date.now()}`;
-  const stagingDir = join5(parentDir, `.bin-install-${nonce}`);
-  const backupDir = join5(parentDir, `.bin-backup-${nonce}`);
+  const stagingDir = join6(parentDir, `.bin-install-${nonce}`);
+  const backupDir = join6(parentDir, `.bin-backup-${nonce}`);
   await mkdir(parentDir, { recursive: true });
   await rm(stagingDir, { recursive: true, force: true });
   await rm(backupDir, { recursive: true, force: true });
   await mkdir(stagingDir, { recursive: true });
   try {
     for (const name of await readdir2(sourceDir)) {
-      await cp(join5(sourceDir, name), join5(stagingDir, name), { recursive: true });
+      await cp(join6(sourceDir, name), join6(stagingDir, name), { recursive: true });
     }
     await writeFile(
-      join5(stagingDir, "package.json"),
+      join6(stagingDir, "package.json"),
       `${JSON.stringify(
         {
           name: "llmnesia-mcp-runtime",
@@ -1429,7 +1851,7 @@ async function installRuntime(options = {}) {
   } finally {
     await rm(stagingDir, { recursive: true, force: true });
   }
-  const entry = join5(binDir, "cli.js");
+  const entry = join6(binDir, "cli.js");
   return {
     binDir,
     entry,
@@ -1450,7 +1872,7 @@ async function uninstallRuntime(home = homedir2()) {
 // src/selfUpdate.ts
 import { spawn } from "child_process";
 import { mkdtemp, readFile, rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3, join as join6 } from "path";
+import { dirname as dirname4, join as join7 } from "path";
 import { homedir as homedir3, tmpdir } from "os";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var PACKAGE_NAME = "@llmnesia/mcp";
@@ -1460,9 +1882,9 @@ var REGISTRY_TIMEOUT_MS = 5e3;
 var INSTALL_TIMEOUT_MS = 12e4;
 var UPDATE_CHECK_DELAY_MS = 3e4;
 function stateFile(home) {
-  return join6(home, ".llmnesia", "update-state.json");
+  return join7(home, ".llmnesia", "update-state.json");
 }
-async function readState(home) {
+async function readState2(home) {
   try {
     const parsed = JSON.parse(await readFile(stateFile(home), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : {};
@@ -1470,7 +1892,7 @@ async function readState(home) {
     return {};
   }
 }
-async function writeState(home, state) {
+async function writeState2(home, state) {
   try {
     await writeFile2(stateFile(home), `${JSON.stringify(state, null, 2)}
 `, "utf8");
@@ -1522,11 +1944,11 @@ async function fetchLatestFromRegistry() {
   }
 }
 function npmCommand() {
-  const binDir = dirname3(process.execPath);
-  return process.platform === "win32" ? join6(binDir, "npm.cmd") : join6(binDir, "npm");
+  const binDir = dirname4(process.execPath);
+  return process.platform === "win32" ? join7(binDir, "npm.cmd") : join7(binDir, "npm");
 }
 async function npmDownload(version) {
-  const prefix = await mkdtemp(join6(tmpdir(), "llmnesia-update-"));
+  const prefix = await mkdtemp(join7(tmpdir(), "llmnesia-update-"));
   await new Promise((resolve2, reject) => {
     const child = spawn(
       npmCommand(),
@@ -1561,7 +1983,7 @@ async function npmDownload(version) {
       }
     });
   });
-  return join6(prefix, "node_modules", PACKAGE_NAME, "dist");
+  return join7(prefix, "node_modules", PACKAGE_NAME, "dist");
 }
 async function maybeSelfUpdate(options = {}) {
   const env = options.env ?? process.env;
@@ -1570,7 +1992,7 @@ async function maybeSelfUpdate(options = {}) {
   }
   const home = options.home ?? homedir3();
   const currentVersion = options.currentVersion ?? VERSION;
-  const runningDir = options.runningDir ?? dirname3(fileURLToPath2(import.meta.url));
+  const runningDir = options.runningDir ?? dirname4(fileURLToPath2(import.meta.url));
   if (runningDir !== runtimeBinDir(home)) {
     return { action: "not-installed-runtime" };
   }
@@ -1578,7 +2000,7 @@ async function maybeSelfUpdate(options = {}) {
     return { action: "not-a-release-build", currentVersion };
   }
   const now = options.now ?? Date.now;
-  const state = await readState(home);
+  const state = await readState2(home);
   if (state.lastCheckedAt !== void 0 && now() - state.lastCheckedAt < UPDATE_CHECK_INTERVAL_MS) {
     return { action: "throttled" };
   }
@@ -1586,30 +2008,30 @@ async function maybeSelfUpdate(options = {}) {
   try {
     latest = await (options.fetchLatestVersion ?? fetchLatestFromRegistry)();
   } catch (err) {
-    await writeState(home, { ...state, lastCheckedAt: now() });
+    await writeState2(home, { ...state, lastCheckedAt: now() });
     return { action: "check-failed", error: err instanceof Error ? err.message : String(err) };
   }
   const checked = { ...state, lastCheckedAt: now(), lastSeenVersion: latest };
   if (!isStableRelease(latest) || compareVersions(latest, currentVersion) <= 0) {
-    await writeState(home, checked);
+    await writeState2(home, checked);
     return { action: "up-to-date", latest };
   }
   if (state.lastFailedVersion === latest) {
-    await writeState(home, checked);
+    await writeState2(home, checked);
     return { action: "skipped-failed-before", latest };
   }
   let sourceDir;
   try {
     sourceDir = await (options.downloadPackage ?? npmDownload)(latest);
     await installRuntime({ home, sourceDir, version: latest });
-    await writeState(home, { ...checked, lastUpdatedTo: latest, lastFailedVersion: void 0 });
+    await writeState2(home, { ...checked, lastUpdatedTo: latest, lastFailedVersion: void 0 });
     return { action: "updated", from: currentVersion, to: latest };
   } catch (err) {
-    await writeState(home, { ...checked, lastFailedVersion: latest });
+    await writeState2(home, { ...checked, lastFailedVersion: latest });
     return { action: "update-failed", latest, error: err instanceof Error ? err.message : String(err) };
   } finally {
     if (sourceDir) {
-      await rm2(join6(sourceDir, "..", "..", ".."), { recursive: true, force: true }).catch(() => {
+      await rm2(join7(sourceDir, "..", "..", ".."), { recursive: true, force: true }).catch(() => {
       });
     }
   }
@@ -1649,6 +2071,7 @@ function describeOutcome(outcome) {
 }
 
 export {
+  readNativeHostViewerExtensionId,
   resolveCorpusDir,
   staleIndexFiles,
   Corpus,
@@ -1658,6 +2081,11 @@ export {
   SearchIndex,
   openSearchIndex,
   deleteIndexDb,
+  inspectCorpusStorage,
+  compactCorpus,
+  AUTO_MAINTENANCE_RECHECK_MS,
+  runAutomaticMaintenance,
+  readAutomaticMaintenanceState,
   runtimeBinDir,
   installRuntime,
   uninstallRuntime,