@remnic/core 1.1.31 → 9.3.516

package/dist/{chunk-77H5NU3M.js → chunk-6BR7L222.js}

@@ -1,31 +1,29 @@
 import {
+  namespaceCollectionName
+} from "./chunk-KXULCVOC.js";
+import {
+  ALL_CATEGORY_DIRS,
   NamespaceStorageRouter
-} from "./chunk-RR2PKP3I.js";
+} from "./chunk-CHBI22MI.js";
 import {
-  namespaceCollectionName
-} from "./chunk-575RMLWN.js";
+  namespaceIdentityFromToken,
+  namespaceIdentityToken
+} from "./chunk-ZFXCQPNO.js";
 import {
   isSafeRouteNamespace
 } from "./chunk-U3PN77QT.js";
 
 // src/namespaces/migrate.ts
 import path from "path";
-import { access, mkdir, readdir, rename } from "fs/promises";
+import { access, lstat, mkdir, readdir, realpath, rename, rmdir } from "fs/promises";
 var LEGACY_NAMESPACE_CHILDREN = [
-  "facts",
-  "corrections",
+  ...ALL_CATEGORY_DIRS,
   "entities",
-  "questions",
   "artifacts",
   "identity",
   "state",
   "config",
   "summaries",
-  "procedures",
-  // Issue #564 PR 3: reasoning_trace memories live in their own subtree.
-  // Must be included here so namespace migration moves existing traces
-  // into the target namespace root alongside other memory data.
-  "reasoning-traces",
   "profile.md"
 ];
 async function exists(p) {
@@ -48,12 +46,15 @@ async function discoverConfiguredNamespaces(config) {
     config.sharedNamespace,
     ...config.namespacePolicies.map((policy) => policy.name)
   ]);
+  const configuredNamespaces = new Set(discovered);
   const namespacesDir = path.join(config.memoryDir, "namespaces");
   try {
     const entries = await readdir(namespacesDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && isSafeRouteNamespace(entry.name)) {
-        discovered.add(entry.name);
+      if (!entry.isDirectory()) continue;
+      const namespace = configuredNamespaces.has(entry.name) ? entry.name : namespaceIdentityFromToken(entry.name) ?? entry.name;
+      if (isSafeRouteNamespace(namespace)) {
+        discovered.add(namespace);
       }
     }
   } catch {
@@ -104,8 +105,13 @@ async function runNamespaceMigration(options) {
   if (!isSafeRouteNamespace(targetNamespace)) {
     throw new Error(`Invalid namespace: ${options.to}`);
   }
-  const targetRoot = path.join(options.config.memoryDir, "namespaces", targetNamespace);
+  const targetRoot = path.join(
+    options.config.memoryDir,
+    "namespaces",
+    namespaceIdentityToken(targetNamespace)
+  );
   const moved = [];
+  const renamePath = options.renameFn ?? rename;
   for (const child of LEGACY_NAMESPACE_CHILDREN) {
     const from = path.join(options.config.memoryDir, child);
     if (!await exists(from)) continue;
@@ -113,12 +119,42 @@ async function runNamespaceMigration(options) {
     if (await exists(to)) {
       throw new Error(`Target already contains ${child}: ${to}`);
     }
+    const sourceStat = await lstat(from);
+    if (sourceStat.isSymbolicLink()) {
+      throw new Error(`Refusing to migrate symlinked legacy path: ${from}`);
+    }
     moved.push({ from, to });
   }
   if (!options.dryRun && moved.length > 0) {
+    await assertSafeNamespaceTarget(options.config.memoryDir, targetRoot);
     await mkdir(targetRoot, { recursive: true });
-    for (const move of moved) {
-      await rename(move.from, move.to);
+    await assertSafeNamespaceTarget(options.config.memoryDir, targetRoot);
+    const completed = [];
+    try {
+      for (const move of moved) {
+        await renamePath(move.from, move.to);
+        completed.push(move);
+      }
+    } catch (cause) {
+      const rollbackErrors = [];
+      for (const move of completed.reverse()) {
+        try {
+          if (!await exists(move.from) && await exists(move.to)) {
+            await rename(move.to, move.from);
+          }
+        } catch (rollbackCause) {
+          rollbackErrors.push(rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause));
+        }
+      }
+      try {
+        await rmdir(targetRoot);
+      } catch {
+      }
+      const message = cause instanceof Error ? cause.message : String(cause);
+      throw new Error(
+        `Namespace migration failed and was rolled back: ${message}` + (rollbackErrors.length > 0 ? `; rollback errors: ${rollbackErrors.join("; ")}` : ""),
+        { cause }
+      );
     }
   }
   return {
@@ -132,10 +168,38 @@ async function runNamespaceMigration(options) {
     })
   };
 }
+async function assertSafeNamespaceTarget(memoryDir, targetRoot) {
+  const memoryReal = await realpath(memoryDir);
+  const namespacesDir = path.join(memoryDir, "namespaces");
+  if (await exists(namespacesDir)) {
+    const namespacesStat = await lstat(namespacesDir);
+    if (namespacesStat.isSymbolicLink()) {
+      throw new Error(`Refusing to migrate through symlinked namespaces directory: ${namespacesDir}`);
+    }
+    const namespacesReal = await realpath(namespacesDir);
+    if (!isPathInside(memoryReal, namespacesReal)) {
+      throw new Error(`Refusing to migrate through namespaces directory outside memoryDir: ${namespacesDir}`);
+    }
+  }
+  if (await exists(targetRoot)) {
+    const targetStat = await lstat(targetRoot);
+    if (targetStat.isSymbolicLink()) {
+      throw new Error(`Refusing to migrate into symlinked namespace root: ${targetRoot}`);
+    }
+    const targetReal = await realpath(targetRoot);
+    if (!isPathInside(memoryReal, targetReal)) {
+      throw new Error(`Refusing to migrate into namespace root outside memoryDir: ${targetRoot}`);
+    }
+  }
+}
+function isPathInside(root, child) {
+  const relative = path.relative(root, child);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
 
 export {
   listNamespaces,
   verifyNamespaces,
   runNamespaceMigration
 };
-//# sourceMappingURL=chunk-77H5NU3M.js.map
+//# sourceMappingURL=chunk-6BR7L222.js.map

package/dist/chunk-6BR7L222.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/namespaces/migrate.ts"],"sourcesContent":["import path from \"node:path\";\nimport { access, lstat, mkdir, readdir, realpath, rename, rmdir } from \"node:fs/promises\";\nimport type { PluginConfig } from \"../types.js\";\nimport { NamespaceStorageRouter } from \"./storage.js\";\nimport { namespaceCollectionName } from \"./search.js\";\nimport { isSafeRouteNamespace } from \"../routing/engine.js\";\nimport { namespaceIdentityFromToken, namespaceIdentityToken } from \"./identity.js\";\nimport { ALL_CATEGORY_DIRS } from \"../utils/category-dir.js\";\n\nconst LEGACY_NAMESPACE_CHILDREN = [\n  ...ALL_CATEGORY_DIRS,\n  \"entities\",\n  \"artifacts\",\n  \"identity\",\n  \"state\",\n  \"config\",\n  \"summaries\",\n  \"profile.md\",\n] as const;\n\nexport interface NamespaceInventoryEntry {\n  namespace: string;\n  rootDir: string;\n  exists: boolean;\n  usesLegacyRoot: boolean;\n  hasMemoryData: boolean;\n  collection: string;\n}\n\nexport interface NamespaceVerifyReport {\n  ok: boolean;\n  problems: string[];\n  namespaces: NamespaceInventoryEntry[];\n}\n\nexport interface NamespaceMigrationMove {\n  from: string;\n  to: string;\n}\n\nexport interface NamespaceMigrationReport {\n  dryRun: boolean;\n  fromRoot: string;\n  targetRoot: string;\n  moved: NamespaceMigrationMove[];\n  collection: string;\n}\n\nasync function exists(p: string): Promise<boolean> {\n  try {\n    await access(p);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function hasAnyLegacyData(rootDir: string): Promise<boolean> {\n  for (const child of LEGACY_NAMESPACE_CHILDREN) {\n    if (await exists(path.join(rootDir, child))) return true;\n  }\n  return false;\n}\n\nasync function discoverConfiguredNamespaces(\n  config: PluginConfig,\n): Promise<string[]> {\n  const discovered = new Set<string>([\n    config.defaultNamespace,\n    config.sharedNamespace,\n    ...config.namespacePolicies.map((policy) => policy.name),\n  ]);\n  const configuredNamespaces = new Set(discovered);\n\n  const namespacesDir = path.join(config.memoryDir, \"namespaces\");\n  try {\n    const entries = await readdir(namespacesDir, { withFileTypes: true });\n    for (const entry of entries) {\n      if (!entry.isDirectory()) continue;\n      const namespace = configuredNamespaces.has(entry.name)\n        ? entry.name\n        : namespaceIdentityFromToken(entry.name) ?? entry.name;\n      if (isSafeRouteNamespace(namespace)) {\n        discovered.add(namespace);\n      }\n    }\n  } catch {\n    // No namespace directory yet.\n  }\n\n  return [...discovered];\n}\n\nexport async function listNamespaces(options: {\n  config: PluginConfig;\n  storageRouter?: NamespaceStorageRouter;\n}): Promise<NamespaceInventoryEntry[]> {\n  const storageRouter = options.storageRouter ?? new NamespaceStorageRouter(options.config);\n  const namespaces = await discoverConfiguredNamespaces(options.config);\n  const items = await Promise.all(\n    namespaces.map(async (namespace) => {\n      const storage = await storageRouter.storageFor(namespace);\n      const usesLegacyRoot =\n        namespace === options.config.defaultNamespace &&\n        storage.dir === options.config.memoryDir;\n      return {\n        namespace,\n        rootDir: storage.dir,\n        exists: await exists(storage.dir),\n        usesLegacyRoot,\n        hasMemoryData: await hasAnyLegacyData(storage.dir),\n        collection: namespaceCollectionName(options.config.qmdCollection, namespace, {\n          defaultNamespace: options.config.defaultNamespace,\n          useLegacyDefaultCollection: usesLegacyRoot,\n        }),\n      } satisfies NamespaceInventoryEntry;\n    }),\n  );\n\n  return items.sort((a, b) => a.namespace.localeCompare(b.namespace));\n}\n\nexport async function verifyNamespaces(options: {\n  config: PluginConfig;\n  storageRouter?: NamespaceStorageRouter;\n}): Promise<NamespaceVerifyReport> {\n  const namespaces = await listNamespaces(options);\n  const problems: string[] = [];\n\n  for (const entry of namespaces) {\n    if (entry.exists && !entry.hasMemoryData) {\n      problems.push(`${entry.namespace}: root exists but contains no Engram data`);\n    }\n  }\n\n  return {\n    ok: problems.length === 0,\n    problems,\n    namespaces,\n  };\n}\n\nexport async function runNamespaceMigration(options: {\n  config: PluginConfig;\n  to: string;\n  dryRun?: boolean;\n  renameFn?: typeof rename;\n}): Promise<NamespaceMigrationReport> {\n  if (!options.config.namespacesEnabled) {\n    throw new Error(\"Namespaces are disabled.\");\n  }\n\n  const targetNamespace = options.to.trim();\n  if (!isSafeRouteNamespace(targetNamespace)) {\n    throw new Error(`Invalid namespace: ${options.to}`);\n  }\n\n  const targetRoot = path.join(\n    options.config.memoryDir,\n    \"namespaces\",\n    namespaceIdentityToken(targetNamespace),\n  );\n  const moved: NamespaceMigrationMove[] = [];\n  const renamePath = options.renameFn ?? rename;\n\n  for (const child of LEGACY_NAMESPACE_CHILDREN) {\n    const from = path.join(options.config.memoryDir, child);\n    if (!(await exists(from))) continue;\n    const to = path.join(targetRoot, child);\n    if (await exists(to)) {\n      throw new Error(`Target already contains ${child}: ${to}`);\n    }\n    const sourceStat = await lstat(from);\n    if (sourceStat.isSymbolicLink()) {\n      throw new Error(`Refusing to migrate symlinked legacy path: ${from}`);\n    }\n    moved.push({ from, to });\n  }\n\n  if (!options.dryRun && moved.length > 0) {\n    await assertSafeNamespaceTarget(options.config.memoryDir, targetRoot);\n    await mkdir(targetRoot, { recursive: true });\n    await assertSafeNamespaceTarget(options.config.memoryDir, targetRoot);\n    const completed: NamespaceMigrationMove[] = [];\n    try {\n      for (const move of moved) {\n        await renamePath(move.from, move.to);\n        completed.push(move);\n      }\n    } catch (cause) {\n      const rollbackErrors: string[] = [];\n      for (const move of completed.reverse()) {\n        try {\n          if (!(await exists(move.from)) && (await exists(move.to))) {\n            await rename(move.to, move.from);\n          }\n        } catch (rollbackCause) {\n          rollbackErrors.push(rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause));\n        }\n      }\n      try {\n        await rmdir(targetRoot);\n      } catch {\n        // Target may predate migration or still contain unrelated files.\n      }\n      const message = cause instanceof Error ? cause.message : String(cause);\n      throw new Error(\n        `Namespace migration failed and was rolled back: ${message}` +\n          (rollbackErrors.length > 0 ? `; rollback errors: ${rollbackErrors.join(\"; \")}` : \"\"),\n        { cause },\n      );\n    }\n  }\n\n  return {\n    dryRun: options.dryRun === true,\n    fromRoot: options.config.memoryDir,\n    targetRoot,\n    moved,\n    collection: namespaceCollectionName(options.config.qmdCollection, targetNamespace, {\n      defaultNamespace: options.config.defaultNamespace,\n      useLegacyDefaultCollection: false,\n    }),\n  };\n}\n\nasync function assertSafeNamespaceTarget(memoryDir: string, targetRoot: string): Promise<void> {\n  const memoryReal = await realpath(memoryDir);\n  const namespacesDir = path.join(memoryDir, \"namespaces\");\n  if (await exists(namespacesDir)) {\n    const namespacesStat = await lstat(namespacesDir);\n    if (namespacesStat.isSymbolicLink()) {\n      throw new Error(`Refusing to migrate through symlinked namespaces directory: ${namespacesDir}`);\n    }\n    const namespacesReal = await realpath(namespacesDir);\n    if (!isPathInside(memoryReal, namespacesReal)) {\n      throw new Error(`Refusing to migrate through namespaces directory outside memoryDir: ${namespacesDir}`);\n    }\n  }\n  if (await exists(targetRoot)) {\n    const targetStat = await lstat(targetRoot);\n    if (targetStat.isSymbolicLink()) {\n      throw new Error(`Refusing to migrate into symlinked namespace root: ${targetRoot}`);\n    }\n    const targetReal = await realpath(targetRoot);\n    if (!isPathInside(memoryReal, targetReal)) {\n      throw new Error(`Refusing to migrate into namespace root outside memoryDir: ${targetRoot}`);\n    }\n  }\n}\n\nfunction isPathInside(root: string, child: string): boolean {\n  const relative = path.relative(root, child);\n  return relative === \"\" || (!relative.startsWith(\"..\") && !path.isAbsolute(relative));\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-4KGVTPGD.js → chunk-6F6BXB7A.js}

@@ -1,16 +1,16 @@
 import {
   hasCodexMaterializeSentinel,
   materializeForNamespace
-} from "./chunk-RHY3HH7P.js";
+} from "./chunk-JFEKNTX7.js";
 import {
   resolveNamespaceChildRoot
 } from "./chunk-3UXOZBHV.js";
+import {
+  StorageManager
+} from "./chunk-UIPDNLXA.js";
 import {
   isSafeRouteNamespace
 } from "./chunk-U3PN77QT.js";
-import {
-  StorageManager
-} from "./chunk-VBJ7V5SK.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
@@ -31,6 +31,7 @@ async function runCodexMaterialize(options) {
   }
   const namespace = resolveNamespace(options.namespace, cfg);
   const memoryDir = options.memoryDir ?? cfg.memoryDir;
+  const codexHome = options.codexHome ?? cfg.codex?.codexHome ?? void 0;
   if (!memoryDir) {
     log.warn(`[codex-materialize] skipped \u2014 no memoryDir available`);
     return null;
@@ -39,10 +40,10 @@ async function runCodexMaterialize(options) {
   if (options.memories) {
     memories = options.memories;
   } else {
-    if (!hasCodexMaterializeSentinel(options.codexHome)) {
+    if (!hasCodexMaterializeSentinel(codexHome)) {
       return materializeForNamespace(namespace, {
         memories: [],
-        codexHome: options.codexHome,
+        codexHome,
         maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
         rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
         rolloutSummaries: options.rolloutSummaries,
@@ -55,7 +56,7 @@ async function runCodexMaterialize(options) {
   }
   const result = materializeForNamespace(namespace, {
     memories,
-    codexHome: options.codexHome,
+    codexHome,
     maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
     rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
     rolloutSummaries: options.rolloutSummaries,
@@ -116,4 +117,4 @@ export {
   runCodexMaterialize,
   runPostConsolidationMaterialize
 };
-//# sourceMappingURL=chunk-4KGVTPGD.js.map
+//# sourceMappingURL=chunk-6F6BXB7A.js.map

package/dist/chunk-6F6BXB7A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connectors/codex-materialize-runner.ts"],"sourcesContent":["/**\n * codex-materialize-runner.ts — Thin I/O bridge for the Codex materializer.\n *\n * The pure rendering logic lives in {@link ./codex-materialize.js}. This file\n * is the place callers (consolidation hooks, CLI, session-end hook) go when\n * they want the whole \"load memories from storage → render → write\" flow.\n *\n * Kept deliberately small so #378 never has to reach into orchestrator.ts /\n * importance.ts — the two files Wave 1 agents are editing concurrently.\n */\n\nimport { existsSync } from \"node:fs\";\n\nimport { log } from \"../logger.js\";\nimport { resolveNamespaceChildRoot } from \"../namespaces/path.js\";\nimport { isSafeRouteNamespace } from \"../routing/engine.js\";\nimport { StorageManager } from \"../storage.js\";\nimport type { PluginConfig, MemoryFile } from \"../types.js\";\nimport {\n  hasCodexMaterializeSentinel,\n  materializeForNamespace,\n  type MaterializeResult,\n  type RolloutSummaryInput,\n} from \"./codex-materialize.js\";\n\n/** Options accepted by the shared post-consolidation materialize helper. */\nexport interface PostConsolidationMaterializeOptions {\n  config: PluginConfig;\n  namespace?: string;\n  memories?: MemoryFile[];\n  memoryDir?: string;\n  codexHome?: string;\n  rolloutSummaries?: RolloutSummaryInput[];\n  now?: Date;\n}\n\n/** Options accepted by the runner. */\nexport interface RunMaterializeOptions {\n  /** Remnic config — we only read the `codexMaterialize*` fields. */\n  config: PluginConfig;\n  /** Namespace to materialize. Overrides the config's `codexMaterializeNamespace`. */\n  namespace?: string;\n  /** Override the memory directory (defaults to `config.memoryDir`). */\n  memoryDir?: string;\n  /** Override `<codex_home>` (useful for tests). */\n  codexHome?: string;\n  /** Optional pre-loaded memories (bypasses disk read — used in tests). */\n  memories?: MemoryFile[];\n  /** Optional rollout summaries supplied by the caller. */\n  rolloutSummaries?: RolloutSummaryInput[];\n  /** Current time injection for deterministic runs. */\n  now?: Date;\n  /** Reason string — logged for observability. */\n  reason?: \"consolidation\" | \"session_end\" | \"manual\" | \"cli\";\n}\n\n/**\n * Run the Codex materialization end-to-end. Returns `null` when the feature\n * is disabled in config or when the user hasn't opted in via the sentinel.\n * Never throws for \"expected\" skips; only throws on schema validation or I/O\n * errors that callers actually need to surface.\n */\nexport async function runCodexMaterialize(\n  options: RunMaterializeOptions,\n): Promise<MaterializeResult | null> {\n  const cfg = options.config;\n  if (!cfg.codexMaterializeMemories) {\n    log.debug(`[codex-materialize] skipped — codexMaterializeMemories=false`);\n    return null;\n  }\n\n  // Per-trigger gate: session-end runs must honor codexMaterializeOnSessionEnd.\n  // session-end.sh passes reason=\"session_end\"; when the user has turned off the\n  // session-end trigger we short-circuit here without touching disk.\n  if (options.reason === \"session_end\" && cfg.codexMaterializeOnSessionEnd === false) {\n    log.debug(\n      `[codex-materialize] skipped — session-end disabled via codexMaterializeOnSessionEnd=false`,\n    );\n    return null;\n  }\n\n  const namespace = resolveNamespace(options.namespace, cfg);\n  const memoryDir = options.memoryDir ?? cfg.memoryDir;\n  const codexHome = options.codexHome ?? cfg.codex?.codexHome ?? undefined;\n  if (!memoryDir) {\n    log.warn(`[codex-materialize] skipped — no memoryDir available`);\n    return null;\n  }\n\n  let memories: MemoryFile[];\n  if (options.memories) {\n    memories = options.memories;\n  } else {\n    if (!hasCodexMaterializeSentinel(codexHome)) {\n      return materializeForNamespace(namespace, {\n        memories: [],\n        codexHome,\n        maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,\n        rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,\n        rolloutSummaries: options.rolloutSummaries,\n        now: options.now,\n      });\n    }\n    const nsDir = resolveNamespaceDir(memoryDir, namespace, cfg);\n    const storage = new StorageManager(nsDir);\n    memories = await storage.readAllMemories();\n  }\n\n  // Intentionally NOT catching here: per the JSDoc contract above,\n  // schema-validation and I/O errors from `materializeForNamespace` must\n  // surface to callers so they can exit non-zero (CLI) or log + recover\n  // (consolidation post-hook, which has its own narrower try/catch).\n  // Catching everything would make a broken MEMORY.md render look like a\n  // successful skip, and invisible failures are strictly worse than loud\n  // ones for a feature that writes to `~/.codex/memories`.\n  const result = materializeForNamespace(namespace, {\n    memories,\n    codexHome,\n    maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,\n    rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,\n    rolloutSummaries: options.rolloutSummaries,\n    now: options.now,\n  });\n  if (options.reason) {\n    log.debug(\n      `[codex-materialize] ran reason=${options.reason} wrote=${result.wrote} files=${result.filesWritten.length}`,\n    );\n  }\n  return result;\n}\n\n/**\n * Shared helper for post-consolidation materialize hooks.\n *\n * `materializeAfterSemanticConsolidation` and `materializeAfterCausalConsolidation`\n * used to be two nearly-identical copies of this logic; keeping the actual\n * body here means any future guard/logging change happens in one place.\n *\n * The only per-caller knob is `logPrefix`, which is used to tag the\n * non-fatal warning emitted when the materializer throws.\n */\nexport async function runPostConsolidationMaterialize(\n  logPrefix: string,\n  options: PostConsolidationMaterializeOptions,\n): Promise<MaterializeResult | null> {\n  if (!options.config.codexMaterializeMemories) return null;\n  if (!options.config.codexMaterializeOnConsolidation) return null;\n  try {\n    return await runCodexMaterialize({\n      config: options.config,\n      namespace: options.namespace,\n      memories: options.memories,\n      memoryDir: options.memoryDir,\n      codexHome: options.codexHome,\n      rolloutSummaries: options.rolloutSummaries,\n      now: options.now,\n      reason: \"consolidation\",\n    });\n  } catch (error) {\n    log.warn(\n      `${logPrefix} Codex materialize post-hook failed (non-fatal): ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n    return null;\n  }\n}\n\nfunction resolveNamespace(override: string | undefined, cfg: PluginConfig): string {\n  const requested = (override ?? cfg.codexMaterializeNamespace ?? \"auto\").trim();\n  const defaultNamespace = (cfg.defaultNamespace ?? \"\").trim();\n  const namespace =\n    requested.length === 0 || requested === \"auto\"\n      ? (defaultNamespace.length > 0 ? defaultNamespace : \"default\")\n      : requested;\n  if (!isSafeRouteNamespace(namespace)) {\n    throw new Error(`invalid materialize namespace: ${namespace}`);\n  }\n  return namespace;\n}\n\n/**\n * Resolve the on-disk storage root for a namespace, matching\n * `NamespaceStorageRouter` in `packages/remnic-core/src/namespaces/storage.ts`.\n *\n * Contract:\n *  - When namespaces are disabled, every namespace maps to `memoryDir` itself.\n *  - When namespaces are enabled, non-default namespaces always live under\n *    `memoryDir/namespaces/<namespace>`.\n *  - The default namespace prefers `memoryDir/namespaces/<defaultNamespace>`\n *    when that directory already exists (migrated install); otherwise it\n *    falls back to the legacy `memoryDir` root so materialization does not\n *    silently switch directories out from under an existing install.\n */\nfunction resolveNamespaceDir(\n  memoryDir: string,\n  namespace: string,\n  cfg: PluginConfig,\n): string {\n  if (!cfg.namespacesEnabled) return memoryDir;\n\n  const defaultNamespace = (cfg.defaultNamespace ?? \"\").trim();\n  const ns = (namespace || defaultNamespace || \"default\").trim();\n  if (!isSafeRouteNamespace(ns)) {\n    throw new Error(`invalid materialize namespace: ${ns}`);\n  }\n  const namespacedRoot = resolveNamespaceChildRoot(memoryDir, ns, \"materialize namespace path\");\n\n  if (ns === defaultNamespace) {\n    return existsSync(namespacedRoot) ? namespacedRoot : memoryDir;\n  }\n  return namespacedRoot;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-NMZY542O.js → chunk-6URPAY2D.js}

@@ -1,13 +1,13 @@
 import {
   readEnvVar
-} from "./chunk-XIG5PDM7.js";
+} from "./chunk-JUC24CTX.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
 
 // src/embedding-fallback.ts
 import path from "path";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
 var DEFAULT_OPENAI_MODEL = "text-embedding-3-small";
 var EmbeddingTimeoutError = class extends Error {
   name = "EmbeddingTimeoutError";
@@ -45,6 +45,7 @@ var EmbeddingFallback = class {
   config;
   indexPath;
   loaded = null;
+  mutationQueue = Promise.resolve();
   async isAvailable() {
     return await this.resolveProvider() !== null;
   }
@@ -152,21 +153,33 @@ var EmbeddingFallback = class {
     if (!provider) return;
     const vector = await this.embed(content, provider, { mode: "index" });
     if (!vector) return;
-    const index = await this.loadIndex(provider);
-    const relPath = toMemoryRelativePath(this.config.memoryDir, filePath);
-    index.entries[memoryId] = {
-      vector,
-      path: relPath
-    };
-    await this.saveIndex(index);
+    await this.enqueueIndexMutation(async () => {
+      const index = await this.loadIndex(provider);
+      const relPath = toMemoryRelativePath(this.config.memoryDir, filePath);
+      index.entries[memoryId] = {
+        vector,
+        path: relPath
+      };
+      await this.saveIndex(index);
+    });
   }
   async removeFromIndex(memoryId) {
     const provider = await this.resolveProvider();
     if (!provider) return;
-    const index = await this.loadIndex(provider);
-    if (!index.entries[memoryId]) return;
-    delete index.entries[memoryId];
-    await this.saveIndex(index);
+    await this.enqueueIndexMutation(async () => {
+      const index = await this.loadIndex(provider);
+      if (!index.entries[memoryId]) return;
+      delete index.entries[memoryId];
+      await this.saveIndex(index);
+    });
+  }
+  enqueueIndexMutation(mutation) {
+    const run = this.mutationQueue.catch(() => void 0).then(mutation);
+    this.mutationQueue = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
   }
   async resolveProvider() {
     if (!this.config.embeddingFallbackEnabled) return null;
@@ -267,7 +280,7 @@ var EmbeddingFallback = class {
     try {
       const raw = await readFile(this.indexPath, "utf-8");
       const parsed = JSON.parse(raw);
-      if (parsed && parsed.version === 1 && parsed.entries && typeof parsed.entries === "object") {
+      if (parsed && parsed.version === 1 && parsed.provider === provider.type && parsed.model === provider.model && parsed.entries && typeof parsed.entries === "object") {
         this.loaded = {
           version: 1,
           provider: provider.type,
@@ -287,8 +300,19 @@ var EmbeddingFallback = class {
     return this.loaded;
   }
   async saveIndex(index) {
-    await mkdir(path.dirname(this.indexPath), { recursive: true });
-    await writeFile(this.indexPath, JSON.stringify(index), "utf-8");
+    const dir = path.dirname(this.indexPath);
+    await mkdir(dir, { recursive: true });
+    const tempPath = path.join(
+      dir,
+      `.embeddings.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
+    );
+    try {
+      await writeFile(tempPath, JSON.stringify(index), "utf-8");
+      await rename(tempPath, this.indexPath);
+    } catch (err) {
+      await rm(tempPath, { force: true }).catch(() => void 0);
+      throw err;
+    }
     this.loaded = index;
   }
 };
@@ -332,4 +356,4 @@ export {
   EmbeddingTimeoutError,
   EmbeddingFallback
 };
-//# sourceMappingURL=chunk-NMZY542O.js.map
+//# sourceMappingURL=chunk-6URPAY2D.js.map

package/dist/chunk-6URPAY2D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/embedding-fallback.ts"],"sourcesContent":["import path from \"node:path\";\nimport { mkdir, readFile, rename, rm, writeFile } from \"node:fs/promises\";\nimport { log } from \"./logger.js\";\nimport { readEnvVar } from \"./runtime/env.js\";\nimport type { PluginConfig } from \"./types.js\";\n\ntype EmbeddingProviderType = \"openai\" | \"local\";\n\ntype ProviderConfig = {\n  type: EmbeddingProviderType;\n  model: string;\n  endpoint: string;\n  headers: Record<string, string>;\n};\n\ntype EmbeddingIndexEntry = {\n  vector: number[];\n  path: string;\n};\n\ntype EmbeddingIndexFile = {\n  version: 1;\n  provider: EmbeddingProviderType;\n  model: string;\n  entries: Record<string, EmbeddingIndexEntry>;\n};\n\nconst DEFAULT_OPENAI_MODEL = \"text-embedding-3-small\";\n\n/**\n * Thrown by `EmbeddingFallback.search()` (via `embed()`) when the embedding\n * backend is effectively unavailable on the lookup path — either because the\n * HTTP fetch exceeded its deadline OR because the endpoint returned a non-2xx\n * status code. Callers that need to distinguish a backend outage from \"no\n * candidates\" can `instanceof`-check against this class.\n *\n * Round 9 fix (Finding UZqB): previously a timeout returned null from embed(),\n * which caused search() to return [] silently. decideSemanticDedup then\n * classified the result as no_candidates instead of backend_unavailable, so\n * the per-batch batchBackendUnavailable short-circuit never activated and\n * batches of N facts each paid a full timeout roundtrip.\n *\n * Round 10 fix (Findings Ui1J + Ui1L): search() now only re-throws this error\n * when the caller explicitly passes `{ throwOnTimeout: true }`. Without that\n * flag search() catches it and returns [] instead, preserving fail-open\n * semantics for recall-path callers (searchEmbeddingFallback) that have no\n * try/catch. Only the semantic-dedup path (semanticDedupLookup) passes the\n * flag so it can still reach decideSemanticDedup's backend_unavailable branch.\n *\n * Round 11 fix (Finding Ur_J): `embed()` now also throws this error from the\n * lookup path when the HTTP response is non-2xx (e.g. 429, 500, 503). Without\n * this, repeated 5xx outages would each return null → [] → no_candidates and\n * subsequent facts in the same batch would all pay full roundtrips instead of\n * tripping the per-batch backend_unavailable short-circuit.\n *\n * The class name is kept for backward compatibility — `EmbeddingTimeoutError`\n * now signals \"lookup backend unavailable\" rather than strictly \"timed out\".\n */\nexport class EmbeddingTimeoutError extends Error {\n  override readonly name = \"EmbeddingTimeoutError\" as const;\n  constructor(message: string) {\n    super(message);\n  }\n}\n\n/**\n * Maximum time to wait for an embedding HTTP request on the LOOKUP/query\n * path before giving up.\n *\n * The write-time semantic dedup guard in orchestrator.persistExtraction()\n * blocks each candidate fact on an embedding lookup. If the embedding\n * endpoint hangs (degraded OpenAI, stalled local gateway, DNS timeout),\n * extraction would otherwise stall indefinitely — a single bad backend\n * could freeze the entire persist loop. Bounding the fetch here ensures\n * the decision path fails open (returns null) within a predictable window\n * and writes proceed as non-duplicates.\n *\n * Tests can override via REMNIC_EMBEDDING_FETCH_TIMEOUT_MS so they don't\n * have to wait the full default on hung-fetch assertions.\n *\n * Related: joshuaswarren/remnic#373, PR #399 P1/P2 review.\n */\nconst DEFAULT_EMBEDDING_LOOKUP_TIMEOUT_MS = 5000;\n\n/**\n * Maximum time to wait for an embedding HTTP request on the INDEX path.\n *\n * Indexing runs asynchronously after a memory has already been persisted\n * to disk. It does not block extraction or writes — it only updates the\n * embedding index used by later semantic dedup lookups. A slow local\n * CPU-backed embedding model can legitimately take tens of seconds per\n * call, so applying the short lookup timeout here silently dropped index\n * updates and caused later dedup lookups to miss recently persisted\n * memories. Use a much larger budget on this path.\n *\n * Tests can override via REMNIC_EMBEDDING_INDEX_TIMEOUT_MS.\n */\nconst DEFAULT_EMBEDDING_INDEX_TIMEOUT_MS = 120_000;\n\nfunction resolveEmbeddingLookupTimeoutMs(): number {\n  const raw = readEnvVar(\"REMNIC_EMBEDDING_FETCH_TIMEOUT_MS\");\n  if (raw) {\n    const parsed = Number(raw);\n    if (Number.isFinite(parsed) && parsed > 0) {\n      return Math.floor(parsed);\n    }\n  }\n  return DEFAULT_EMBEDDING_LOOKUP_TIMEOUT_MS;\n}\n\nfunction resolveEmbeddingIndexTimeoutMs(): number {\n  const raw = readEnvVar(\"REMNIC_EMBEDDING_INDEX_TIMEOUT_MS\");\n  if (raw) {\n    const parsed = Number(raw);\n    if (Number.isFinite(parsed) && parsed > 0) {\n      return Math.floor(parsed);\n    }\n  }\n  return DEFAULT_EMBEDDING_INDEX_TIMEOUT_MS;\n}\n\n/**\n * Options for the low-level embed() call.\n *\n * `mode` selects the timeout profile:\n *   - \"lookup\" (default): bounded by the short lookup budget; fails open fast.\n *   - \"index\": bounded by a much longer budget so slow backends can still\n *     index newly persisted memories.\n */\nexport type EmbedMode = \"lookup\" | \"index\";\n\nexport class EmbeddingFallback {\n  private readonly indexPath: string;\n  private loaded: EmbeddingIndexFile | null = null;\n  private mutationQueue: Promise<void> = Promise.resolve();\n\n  constructor(private readonly config: PluginConfig) {\n    this.indexPath = path.join(config.memoryDir, \"state\", \"embeddings.json\");\n  }\n\n  async isAvailable(): Promise<boolean> {\n    return (await this.resolveProvider()) !== null;\n  }\n\n  /**\n   * Embed an array of texts and return their embedding vectors.\n   *\n   * This is the public batch-embed interface used by semantic chunking\n   * (Finding 1, PR #420 post-merge). Texts are grouped into batches of\n   * `embeddingBatchSize` (from `semanticChunkingConfig`, default 32) and\n   * each batch is dispatched concurrently via `Promise.all()`. This\n   * preserves the semantic intent of `embeddingBatchSize` — without batching,\n   * every text incurred a sequential HTTP round-trip, making the batch size\n   * config ineffective. (PR #439 post-merge Finding 2.)\n   *\n   * If the provider is unavailable or any single embedding fails, the method\n   * throws so the caller can fall back to recursive chunking.\n   */\n  async embedTexts(texts: string[]): Promise<number[][]> {\n    const provider = await this.resolveProvider();\n    if (!provider) {\n      throw new Error(\"Embedding provider is not available\");\n    }\n\n    const batchSize = Math.max(\n      1,\n      this.config.semanticChunkingConfig?.embeddingBatchSize ?? 32,\n    );\n\n    const vectors: number[][] = [];\n    for (let i = 0; i < texts.length; i += batchSize) {\n      const batch = texts.slice(i, i + batchSize);\n      const batchResults = await Promise.all(\n        batch.map((text) => this.embed(text, provider, { mode: \"lookup\" })),\n      );\n      for (const vec of batchResults) {\n        if (!vec) {\n          throw new Error(\"Embedding returned null for input text\");\n        }\n        vectors.push(vec);\n      }\n    }\n    return vectors;\n  }\n\n  /**\n   * Nearest-neighbor search against the embedding index.\n   *\n   * @param query         The query string to embed and search for.\n   * @param limit         Max number of hits to return.\n   * @param options       Optional filters.\n   *   - `pathPrefix`   Restrict candidates to entries whose indexed `path`\n   *                    starts with this prefix (relative to `memoryDir`).\n   *                    Used by the semantic dedup guard to scope lookups\n   *                    to the target namespace so a high-similarity hit\n   *                    from a different namespace can't suppress a write\n   *                    in the target namespace. Default: no filter.\n   *   - `pathExcludePrefixes`\n   *                    Exclude any entry whose indexed `path` starts with\n   *                    any of these prefixes. Used for the default\n   *                    namespace case: when the default namespace lives at\n   *                    `memoryDir` root (legacy layout) we still want to\n   *                    exclude `namespaces/<other>/…` entries.\n   */\n  async search(\n    query: string,\n    limit: number,\n    options: {\n      pathPrefix?: string;\n      pathExcludePrefixes?: readonly string[];\n      /**\n       * When true, an `EmbeddingTimeoutError` from the embedding backend is\n       * re-thrown to the caller. Use this on the semantic-dedup path so\n       * `decideSemanticDedup`'s catch block can classify the result as\n       * `reason=\"backend_unavailable\"` and activate the per-batch\n       * short-circuit.\n       *\n       * When false (the default), a timeout is caught here and search()\n       * returns [] instead — preserving fail-open semantics for the recall\n       * path (`searchEmbeddingFallback`) which has no surrounding try/catch.\n       * Without this gate a timed-out embedding request on the recall path\n       * would propagate as an unhandled rejection and abort recall entirely.\n       * (Round 10 fix, Findings Ui1J + Ui1L.)\n       */\n      throwOnTimeout?: boolean;\n    } = {},\n  ): Promise<Array<{ id: string; score: number; path: string }>> {\n    const provider = await this.resolveProvider();\n    if (!provider) return [];\n\n    const index = await this.loadIndex(provider);\n    const ids = Object.keys(index.entries);\n    if (ids.length === 0) return [];\n\n    let queryVector: number[] | null;\n    try {\n      queryVector = await this.embed(query, provider, { mode: \"lookup\" });\n    } catch (err) {\n      if (err instanceof EmbeddingTimeoutError) {\n        if (options.throwOnTimeout) {\n          throw err;\n        }\n        // Fail-open: recall-path callers get an empty result rather than an\n        // unhandled rejection that would abort recall entirely.\n        log.debug(\"embedding fallback search: timeout on lookup, returning [] (throwOnTimeout=false)\");\n        return [];\n      }\n      throw err;\n    }\n    if (!queryVector) return [];\n\n    const includePrefix = normalizePathPrefix(options.pathPrefix);\n    const excludePrefixes = (options.pathExcludePrefixes ?? [])\n      .map((p) => normalizePathPrefix(p))\n      .filter((p): p is string => typeof p === \"string\");\n\n    const scored = ids\n      .map((id) => {\n        const entry = index.entries[id];\n        return {\n          id,\n          path: entry.path,\n          score: cosineSimilarity(queryVector, entry.vector),\n        };\n      })\n      .filter((r) => {\n        if (!Number.isFinite(r.score)) return false;\n        const normalized = normalizeEntryPath(r.path);\n        if (includePrefix !== undefined && !normalized.startsWith(includePrefix)) {\n          return false;\n        }\n        for (const excl of excludePrefixes) {\n          if (normalized.startsWith(excl)) return false;\n        }\n        return true;\n      })\n      .sort((a, b) => b.score - a.score)\n      .slice(0, Math.max(1, limit));\n\n    return scored;\n  }\n\n  async indexFile(memoryId: string, content: string, filePath: string): Promise<void> {\n    const provider = await this.resolveProvider();\n    if (!provider) return;\n    // Indexing is not on the write-critical path: a newly persisted memory\n    // has already been written to disk by the time we reach this call. Use\n    // the long \"index\" timeout so slow local embedding backends can still\n    // add the entry to the index. Previously this used the short lookup\n    // budget and silently dropped updates, leaving later dedup lookups\n    // blind to the memory. Related: PR #399 P2.\n    const vector = await this.embed(content, provider, { mode: \"index\" });\n    if (!vector) return;\n\n    await this.enqueueIndexMutation(async () => {\n      const index = await this.loadIndex(provider);\n      const relPath = toMemoryRelativePath(this.config.memoryDir, filePath);\n      index.entries[memoryId] = {\n        vector,\n        path: relPath,\n      };\n      await this.saveIndex(index);\n    });\n  }\n\n  async removeFromIndex(memoryId: string): Promise<void> {\n    const provider = await this.resolveProvider();\n    if (!provider) return;\n\n    await this.enqueueIndexMutation(async () => {\n      const index = await this.loadIndex(provider);\n      if (!index.entries[memoryId]) return;\n      delete index.entries[memoryId];\n      await this.saveIndex(index);\n    });\n  }\n\n  private enqueueIndexMutation<T>(mutation: () => Promise<T>): Promise<T> {\n    const run = this.mutationQueue.catch(() => undefined).then(mutation);\n    this.mutationQueue = run.then(\n      () => undefined,\n      () => undefined,\n    );\n    return run;\n  }\n\n  private async resolveProvider(): Promise<ProviderConfig | null> {\n    if (!this.config.embeddingFallbackEnabled) return null;\n\n    const preferred = this.config.embeddingFallbackProvider;\n    const providers = preferred === \"auto\" ? [\"openai\", \"local\"] : [preferred];\n\n    for (const p of providers) {\n      if (p === \"openai\" && this.config.openaiApiKey) {\n        const baseUrl = this.config.openaiBaseUrl ?? \"https://api.openai.com/v1\";\n        return {\n          type: \"openai\",\n          model: DEFAULT_OPENAI_MODEL,\n          endpoint: `${baseUrl.replace(/\\/$/, \"\")}/embeddings`,\n          headers: {\n            \"Content-Type\": \"application/json\",\n            Authorization: `Bearer ${this.config.openaiApiKey}`,\n          },\n        };\n      }\n\n      if (p === \"local\" && this.config.localLlmEnabled && this.config.localLlmUrl) {\n        const base = this.config.localLlmUrl.replace(/\\/$/, \"\");\n        const endpoint = /\\/v1$/i.test(base) ? `${base}/embeddings` : `${base}/v1/embeddings`;\n        const headers: Record<string, string> = {\n          \"Content-Type\": \"application/json\",\n          ...(this.config.localLlmHeaders ?? {}),\n        };\n        if (this.config.localLlmApiKey && this.config.localLlmAuthHeader !== false) {\n          headers.Authorization = `Bearer ${this.config.localLlmApiKey}`;\n        }\n        return {\n          type: \"local\",\n          model:\n            this.config.embeddingFallbackModel ||\n            this.config.localLlmModel ||\n            DEFAULT_OPENAI_MODEL,\n          endpoint,\n          headers,\n        };\n      }\n    }\n\n    return null;\n  }\n\n  private async embed(\n    input: string,\n    provider: ProviderConfig,\n    options: { mode?: EmbedMode } = {},\n  ): Promise<number[] | null> {\n    // Bound the fetch so a hung embedding endpoint cannot stall callers.\n    // The lookup path uses a short budget (see DEFAULT_EMBEDDING_LOOKUP_TIMEOUT_MS\n    // docblock) so semantic dedup fails open fast. The index path uses a\n    // much longer budget because slow local backends (CPU embedding models)\n    // otherwise drop index updates and blind later dedup lookups. See\n    // DEFAULT_EMBEDDING_INDEX_TIMEOUT_MS docblock and PR #399 P2 review.\n    const mode: EmbedMode = options.mode ?? \"lookup\";\n    const timeoutMs =\n      mode === \"index\"\n        ? resolveEmbeddingIndexTimeoutMs()\n        : resolveEmbeddingLookupTimeoutMs();\n    try {\n      const res = await fetch(provider.endpoint, {\n        method: \"POST\",\n        headers: provider.headers,\n        body: JSON.stringify({\n          model: provider.model,\n          input: input.slice(0, 8000),\n          encoding_format: \"float\",\n        }),\n        signal: AbortSignal.timeout(timeoutMs),\n      });\n      if (!res.ok) {\n        log.debug(`embedding fallback request failed: ${provider.type} ${res.status}`);\n        // Round 11 fix (Finding Ur_J): on the LOOKUP path, a non-2xx response\n        // means the embedding backend is effectively unavailable. Throw the\n        // tagged error so search() (when called with throwOnTimeout) propagates\n        // to decideSemanticDedup's backend_unavailable branch, activating the\n        // per-batch short-circuit. Without this, repeated 429/5xx responses\n        // would silently return [] for every fact in the batch.\n        //\n        // On the INDEX path a non-2xx is non-fatal (the memory is already\n        // persisted; index update can be skipped) — return null there.\n        if (mode === \"lookup\") {\n          throw new EmbeddingTimeoutError(\n            `embedding backend returned ${res.status} (${provider.type})`,\n          );\n        }\n        return null;\n      }\n      const payload = (await res.json()) as any;\n      const vector = payload?.data?.[0]?.embedding;\n      if (!Array.isArray(vector)) return null;\n      return vector.map((n: unknown) => Number(n)).filter((n: number) => Number.isFinite(n));\n    } catch (err) {\n      // Round 11 (Finding Ur_J): the !res.ok branch above throws\n      // EmbeddingTimeoutError directly. Re-throw it here so the catch does\n      // not swallow our own intentional signal back into a null return.\n      if (err instanceof EmbeddingTimeoutError) {\n        throw err;\n      }\n      // AbortSignal.timeout throws a DOMException with name \"TimeoutError\";\n      // surface at warn level so operators can distinguish slow backends from\n      // generic errors.\n      const isTimeout =\n        err instanceof Error &&\n        (err.name === \"TimeoutError\" || err.name === \"AbortError\");\n      if (isTimeout) {\n        log.warn(\n          `embedding fallback fetch timed out after ${timeoutMs}ms (${provider.type}, mode=${mode})`,\n        );\n        // Round 9 fix (Finding UZqB): on the LOOKUP path a timeout means the\n        // embedding backend is effectively unavailable — re-throw so that\n        // search() propagates the error to semanticDedupLookup, which lets it\n        // reach decideSemanticDedup's catch block and return\n        // reason=\"backend_unavailable\". Without this, search() would silently\n        // return [] and the per-batch batchBackendUnavailable flag would never\n        // flip, causing subsequent facts in the same batch to each pay a full\n        // timeout roundtrip (N × timeout instead of 1 × timeout).\n        //\n        // On the INDEX path a timeout is not fatal (the memory is already\n        // persisted; index update can be skipped) — return null there so\n        // indexFile() stays non-blocking.\n        if (mode === \"lookup\") {\n          throw new EmbeddingTimeoutError(\n            `embedding backend timed out after ${timeoutMs}ms (${provider.type})`,\n          );\n        }\n      } else {\n        // Round 12 fix (PR #399 thread PRRT_kwDORJXyws56U6Gi): non-timeout\n        // transport failures (ECONNREFUSED, DNS errors, TLS failures) are just\n        // as fatal as timeouts on the LOOKUP path — the embedding backend is\n        // effectively unreachable. Throw EmbeddingTimeoutError so that\n        // search() (when called with throwOnTimeout:true) propagates the error\n        // to decideSemanticDedup's backend_unavailable branch, activating the\n        // per-batch short-circuit. Without this, each fact in the batch would\n        // pay a full ECONNREFUSED roundtrip and return null → [] → no_candidates,\n        // preventing batchBackendUnavailable from ever being set.\n        //\n        // On the INDEX path a transport failure is non-fatal — the memory is\n        // already persisted; index update can be safely skipped.\n        if (mode === \"lookup\") {\n          log.warn(\n            `embedding fallback transport error on lookup path (${provider.type}): ${err}`,\n          );\n          throw new EmbeddingTimeoutError(\n            `embedding backend transport failure (${provider.type}): ${err instanceof Error ? err.message : String(err)}`,\n          );\n        }\n        log.debug(`embedding fallback error: ${err}`);\n      }\n      return null;\n    }\n  }\n\n  private async loadIndex(provider: ProviderConfig): Promise<EmbeddingIndexFile> {\n    if (this.loaded && this.loaded.provider === provider.type && this.loaded.model === provider.model) {\n      return this.loaded;\n    }\n\n    try {\n      const raw = await readFile(this.indexPath, \"utf-8\");\n      const parsed = JSON.parse(raw) as EmbeddingIndexFile;\n      if (\n        parsed &&\n        parsed.version === 1 &&\n        parsed.provider === provider.type &&\n        parsed.model === provider.model &&\n        parsed.entries &&\n        typeof parsed.entries === \"object\"\n      ) {\n        this.loaded = {\n          version: 1,\n          provider: provider.type,\n          model: provider.model,\n          entries: parsed.entries,\n        };\n        return this.loaded;\n      }\n    } catch {\n      // ignore and create a new index\n    }\n\n    this.loaded = {\n      version: 1,\n      provider: provider.type,\n      model: provider.model,\n      entries: {},\n    };\n    return this.loaded;\n  }\n\n  private async saveIndex(index: EmbeddingIndexFile): Promise<void> {\n    const dir = path.dirname(this.indexPath);\n    await mkdir(dir, { recursive: true });\n    const tempPath = path.join(\n      dir,\n      `.embeddings.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,\n    );\n    try {\n      await writeFile(tempPath, JSON.stringify(index), \"utf-8\");\n      await rename(tempPath, this.indexPath);\n    } catch (err) {\n      await rm(tempPath, { force: true }).catch(() => undefined);\n      throw err;\n    }\n    this.loaded = index;\n  }\n}\n\nfunction toMemoryRelativePath(memoryDir: string, filePath: string): string {\n  if (!path.isAbsolute(filePath)) return filePath;\n  const rel = path.relative(memoryDir, filePath);\n  return rel.startsWith(\"..\") ? filePath : rel;\n}\n\n/**\n * Normalize an index entry path to forward-slashes for stable prefix\n * comparison. Entries are stored as `path.relative(memoryDir, …)` output,\n * which on Windows uses back-slashes. Normalize both sides so prefix\n * matching is OS-independent.\n *\n * Also strip a leading `./` so this helper's output is symmetric with\n * `normalizePathPrefix` below. `toMemoryRelativePath` is a pass-through for\n * non-absolute filePath inputs, so an index entry could legitimately carry a\n * stored path like `\"./namespaces/alpha/facts/f.md\"`. Without this strip, a\n * caller-supplied prefix `\"./namespaces/alpha\"` (which `normalizePathPrefix`\n * rewrites to `\"namespaces/alpha/\"`) would silently miss that entry and\n * namespace-scoped dedup would either let a near-duplicate through or fail\n * to exclude a cross-namespace hit.\n */\nfunction normalizeEntryPath(p: string): string {\n  let out = p.replace(/\\\\/g, \"/\");\n  if (out.startsWith(\"./\")) out = out.slice(2);\n  return out;\n}\n\n/**\n * Normalize a caller-supplied path prefix:\n *   - Return `undefined` for nullish/empty input (no filter).\n *   - Replace back-slashes with forward-slashes.\n *   - Strip a leading `./`.\n *   - Ensure a trailing `/` so `\"namespaces/a\"` doesn't accidentally match\n *     `\"namespaces/another/…\"`.\n */\nfunction normalizePathPrefix(prefix: string | undefined): string | undefined {\n  if (prefix === undefined || prefix === null) return undefined;\n  let p = String(prefix).replace(/\\\\/g, \"/\");\n  if (p.startsWith(\"./\")) p = p.slice(2);\n  if (p.length === 0) return undefined;\n  if (!p.endsWith(\"/\")) p = `${p}/`;\n  return p;\n}\n\nfunction cosineSimilarity(a: number[], b: number[]): number {\n  const n = Math.min(a.length, b.length);\n  if (n === 0) return 0;\n  let dot = 0;\n  let normA = 0;\n  let normB = 0;\n  for (let i = 0; i < n; i++) {\n    const av = a[i] ?? 0;\n    const bv = b[i] ?? 0;\n    dot += av * bv;\n    normA += av * av;\n    normB += bv * bv;\n  }\n  const denom = Math.sqrt(normA) * Math.sqrt(normB);\n  if (denom === 0) return 0;\n  return dot / denom;\n}\n"],"mappings":";;;;;;;;AAAA,OAAO,UAAU;AACjB,SAAS,OAAO,UAAU,QAAQ,IAAI,iBAAiB;AA0BvD,IAAM,uBAAuB;AA+BtB,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC7B,OAAO;AAAA,EACzB,YAAY,SAAiB;AAC3B,UAAM,OAAO;AAAA,EACf;AACF;AAmBA,IAAM,sCAAsC;AAe5C,IAAM,qCAAqC;AAE3C,SAAS,kCAA0C;AACjD,QAAM,MAAM,WAAW,mCAAmC;AAC1D,MAAI,KAAK;AACP,UAAM,SAAS,OAAO,GAAG;AACzB,QAAI,OAAO,SAAS,MAAM,KAAK,SAAS,GAAG;AACzC,aAAO,KAAK,MAAM,MAAM;AAAA,IAC1B;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,iCAAyC;AAChD,QAAM,MAAM,WAAW,mCAAmC;AAC1D,MAAI,KAAK;AACP,UAAM,SAAS,OAAO,GAAG;AACzB,QAAI,OAAO,SAAS,MAAM,KAAK,SAAS,GAAG;AACzC,aAAO,KAAK,MAAM,MAAM;AAAA,IAC1B;AAAA,EACF;AACA,SAAO;AACT;AAYO,IAAM,oBAAN,MAAwB;AAAA,EAK7B,YAA6B,QAAsB;AAAtB;AAC3B,SAAK,YAAY,KAAK,KAAK,OAAO,WAAW,SAAS,iBAAiB;AAAA,EACzE;AAAA,EAF6B;AAAA,EAJZ;AAAA,EACT,SAAoC;AAAA,EACpC,gBAA+B,QAAQ,QAAQ;AAAA,EAMvD,MAAM,cAAgC;AACpC,WAAQ,MAAM,KAAK,gBAAgB,MAAO;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgBA,MAAM,WAAW,OAAsC;AACrD,UAAM,WAAW,MAAM,KAAK,gBAAgB;AAC5C,QAAI,CAAC,UAAU;AACb,YAAM,IAAI,MAAM,qCAAqC;AAAA,IACvD;AAEA,UAAM,YAAY,KAAK;AAAA,MACrB;AAAA,MACA,KAAK,OAAO,wBAAwB,sBAAsB;AAAA,IAC5D;AAEA,UAAM,UAAsB,CAAC;AAC7B,aAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,WAAW;AAChD,YAAM,QAAQ,MAAM,MAAM,GAAG,IAAI,SAAS;AAC1C,YAAM,eAAe,MAAM,QAAQ;AAAA,QACjC,MAAM,IAAI,CAAC,SAAS,KAAK,MAAM,MAAM,UAAU,EAAE,MAAM,SAAS,CAAC,CAAC;AAAA,MACpE;AACA,iBAAW,OAAO,cAAc;AAC9B,YAAI,CAAC,KAAK;AACR,gBAAM,IAAI,MAAM,wCAAwC;AAAA,QAC1D;AACA,gBAAQ,KAAK,GAAG;AAAA,MAClB;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBA,MAAM,OACJ,OACA,OACA,UAkBI,CAAC,GACwD;AAC7D,UAAM,WAAW,MAAM,KAAK,gBAAgB;AAC5C,QAAI,CAAC,SAAU,QAAO,CAAC;AAEvB,UAAM,QAAQ,MAAM,KAAK,UAAU,QAAQ;AAC3C,UAAM,MAAM,OAAO,KAAK,MAAM,OAAO;AACrC,QAAI,IAAI,WAAW,EAAG,QAAO,CAAC;AAE9B,QAAI;AACJ,QAAI;AACF,oBAAc,MAAM,KAAK,MAAM,OAAO,UAAU,EAAE,MAAM,SAAS,CAAC;AAAA,IACpE,SAAS,KAAK;AACZ,UAAI,eAAe,uBAAuB;AACxC,YAAI,QAAQ,gBAAgB;AAC1B,gBAAM;AAAA,QACR;AAGA,YAAI,MAAM,mFAAmF;AAC7F,eAAO,CAAC;AAAA,MACV;AACA,YAAM;AAAA,IACR;AACA,QAAI,CAAC,YAAa,QAAO,CAAC;AAE1B,UAAM,gBAAgB,oBAAoB,QAAQ,UAAU;AAC5D,UAAM,mBAAmB,QAAQ,uBAAuB,CAAC,GACtD,IAAI,CAAC,MAAM,oBAAoB,CAAC,CAAC,EACjC,OAAO,CAAC,MAAmB,OAAO,MAAM,QAAQ;AAEnD,UAAM,SAAS,IACZ,IAAI,CAAC,OAAO;AACX,YAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,aAAO;AAAA,QACL;AAAA,QACA,MAAM,MAAM;AAAA,QACZ,OAAO,iBAAiB,aAAa,MAAM,MAAM;AAAA,MACnD;AAAA,IACF,CAAC,EACA,OAAO,CAAC,MAAM;AACb,UAAI,CAAC,OAAO,SAAS,EAAE,KAAK,EAAG,QAAO;AACtC,YAAM,aAAa,mBAAmB,EAAE,IAAI;AAC5C,UAAI,kBAAkB,UAAa,CAAC,WAAW,WAAW,aAAa,GAAG;AACxE,eAAO;AAAA,MACT;AACA,iBAAW,QAAQ,iBAAiB;AAClC,YAAI,WAAW,WAAW,IAAI,EAAG,QAAO;AAAA,MAC1C;AACA,aAAO;AAAA,IACT,CAAC,EACA,KAAK,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,EAChC,MAAM,GAAG,KAAK,IAAI,GAAG,KAAK,CAAC;AAE9B,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,UAAU,UAAkB,SAAiB,UAAiC;AAClF,UAAM,WAAW,MAAM,KAAK,gBAAgB;AAC5C,QAAI,CAAC,SAAU;AAOf,UAAM,SAAS,MAAM,KAAK,MAAM,SAAS,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpE,QAAI,CAAC,OAAQ;AAEb,UAAM,KAAK,qBAAqB,YAAY;AAC1C,YAAM,QAAQ,MAAM,KAAK,UAAU,QAAQ;AAC3C,YAAM,UAAU,qBAAqB,KAAK,OAAO,WAAW,QAAQ;AACpE,YAAM,QAAQ,QAAQ,IAAI;AAAA,QACxB;AAAA,QACA,MAAM;AAAA,MACR;AACA,YAAM,KAAK,UAAU,KAAK;AAAA,IAC5B,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,gBAAgB,UAAiC;AACrD,UAAM,WAAW,MAAM,KAAK,gBAAgB;AAC5C,QAAI,CAAC,SAAU;AAEf,UAAM,KAAK,qBAAqB,YAAY;AAC1C,YAAM,QAAQ,MAAM,KAAK,UAAU,QAAQ;AAC3C,UAAI,CAAC,MAAM,QAAQ,QAAQ,EAAG;AAC9B,aAAO,MAAM,QAAQ,QAAQ;AAC7B,YAAM,KAAK,UAAU,KAAK;AAAA,IAC5B,CAAC;AAAA,EACH;AAAA,EAEQ,qBAAwB,UAAwC;AACtE,UAAM,MAAM,KAAK,cAAc,MAAM,MAAM,MAAS,EAAE,KAAK,QAAQ;AACnE,SAAK,gBAAgB,IAAI;AAAA,MACvB,MAAM;AAAA,MACN,MAAM;AAAA,IACR;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,kBAAkD;AAC9D,QAAI,CAAC,KAAK,OAAO,yBAA0B,QAAO;AAElD,UAAM,YAAY,KAAK,OAAO;AAC9B,UAAM,YAAY,cAAc,SAAS,CAAC,UAAU,OAAO,IAAI,CAAC,SAAS;AAEzE,eAAW,KAAK,WAAW;AACzB,UAAI,MAAM,YAAY,KAAK,OAAO,cAAc;AAC9C,cAAM,UAAU,KAAK,OAAO,iBAAiB;AAC7C,eAAO;AAAA,UACL,MAAM;AAAA,UACN,OAAO;AAAA,UACP,UAAU,GAAG,QAAQ,QAAQ,OAAO,EAAE,CAAC;AAAA,UACvC,SAAS;AAAA,YACP,gBAAgB;AAAA,YAChB,eAAe,UAAU,KAAK,OAAO,YAAY;AAAA,UACnD;AAAA,QACF;AAAA,MACF;AAEA,UAAI,MAAM,WAAW,KAAK,OAAO,mBAAmB,KAAK,OAAO,aAAa;AAC3E,cAAM,OAAO,KAAK,OAAO,YAAY,QAAQ,OAAO,EAAE;AACtD,cAAM,WAAW,SAAS,KAAK,IAAI,IAAI,GAAG,IAAI,gBAAgB,GAAG,IAAI;AACrE,cAAM,UAAkC;AAAA,UACtC,gBAAgB;AAAA,UAChB,GAAI,KAAK,OAAO,mBAAmB,CAAC;AAAA,QACtC;AACA,YAAI,KAAK,OAAO,kBAAkB,KAAK,OAAO,uBAAuB,OAAO;AAC1E,kBAAQ,gBAAgB,UAAU,KAAK,OAAO,cAAc;AAAA,QAC9D;AACA,eAAO;AAAA,UACL,MAAM;AAAA,UACN,OACE,KAAK,OAAO,0BACZ,KAAK,OAAO,iBACZ;AAAA,UACF;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,MACZ,OACA,UACA,UAAgC,CAAC,GACP;AAO1B,UAAM,OAAkB,QAAQ,QAAQ;AACxC,UAAM,YACJ,SAAS,UACL,+BAA+B,IAC/B,gCAAgC;AACtC,QAAI;AACF,YAAM,MAAM,MAAM,MAAM,SAAS,UAAU;AAAA,QACzC,QAAQ;AAAA,QACR,SAAS,SAAS;AAAA,QAClB,MAAM,KAAK,UAAU;AAAA,UACnB,OAAO,SAAS;AAAA,UAChB,OAAO,MAAM,MAAM,GAAG,GAAI;AAAA,UAC1B,iBAAiB;AAAA,QACnB,CAAC;AAAA,QACD,QAAQ,YAAY,QAAQ,SAAS;AAAA,MACvC,CAAC;AACD,UAAI,CAAC,IAAI,IAAI;AACX,YAAI,MAAM,sCAAsC,SAAS,IAAI,IAAI,IAAI,MAAM,EAAE;AAU7E,YAAI,SAAS,UAAU;AACrB,gBAAM,IAAI;AAAA,YACR,8BAA8B,IAAI,MAAM,KAAK,SAAS,IAAI;AAAA,UAC5D;AAAA,QACF;AACA,eAAO;AAAA,MACT;AACA,YAAM,UAAW,MAAM,IAAI,KAAK;AAChC,YAAM,SAAS,SAAS,OAAO,CAAC,GAAG;AACnC,UAAI,CAAC,MAAM,QAAQ,MAAM,EAAG,QAAO;AACnC,aAAO,OAAO,IAAI,CAAC,MAAe,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,MAAc,OAAO,SAAS,CAAC,CAAC;AAAA,IACvF,SAAS,KAAK;AAIZ,UAAI,eAAe,uBAAuB;AACxC,cAAM;AAAA,MACR;AAIA,YAAM,YACJ,eAAe,UACd,IAAI,SAAS,kBAAkB,IAAI,SAAS;AAC/C,UAAI,WAAW;AACb,YAAI;AAAA,UACF,4CAA4C,SAAS,OAAO,SAAS,IAAI,UAAU,IAAI;AAAA,QACzF;AAaA,YAAI,SAAS,UAAU;AACrB,gBAAM,IAAI;AAAA,YACR,qCAAqC,SAAS,OAAO,SAAS,IAAI;AAAA,UACpE;AAAA,QACF;AAAA,MACF,OAAO;AAaL,YAAI,SAAS,UAAU;AACrB,cAAI;AAAA,YACF,sDAAsD,SAAS,IAAI,MAAM,GAAG;AAAA,UAC9E;AACA,gBAAM,IAAI;AAAA,YACR,wCAAwC,SAAS,IAAI,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,UAC7G;AAAA,QACF;AACA,YAAI,MAAM,6BAA6B,GAAG,EAAE;AAAA,MAC9C;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAc,UAAU,UAAuD;AAC7E,QAAI,KAAK,UAAU,KAAK,OAAO,aAAa,SAAS,QAAQ,KAAK,OAAO,UAAU,SAAS,OAAO;AACjG,aAAO,KAAK;AAAA,IACd;AAEA,QAAI;AACF,YAAM,MAAM,MAAM,SAAS,KAAK,WAAW,OAAO;AAClD,YAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,UACE,UACA,OAAO,YAAY,KACnB,OAAO,aAAa,SAAS,QAC7B,OAAO,UAAU,SAAS,SAC1B,OAAO,WACP,OAAO,OAAO,YAAY,UAC1B;AACA,aAAK,SAAS;AAAA,UACZ,SAAS;AAAA,UACT,UAAU,SAAS;AAAA,UACnB,OAAO,SAAS;AAAA,UAChB,SAAS,OAAO;AAAA,QAClB;AACA,eAAO,KAAK;AAAA,MACd;AAAA,IACF,QAAQ;AAAA,IAER;AAEA,SAAK,SAAS;AAAA,MACZ,SAAS;AAAA,MACT,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS;AAAA,MAChB,SAAS,CAAC;AAAA,IACZ;AACA,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAc,UAAU,OAA0C;AAChE,UAAM,MAAM,KAAK,QAAQ,KAAK,SAAS;AACvC,UAAM,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;AACpC,UAAM,WAAW,KAAK;AAAA,MACpB;AAAA,MACA,eAAe,QAAQ,GAAG,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AAAA,IACjF;AACA,QAAI;AACF,YAAM,UAAU,UAAU,KAAK,UAAU,KAAK,GAAG,OAAO;AACxD,YAAM,OAAO,UAAU,KAAK,SAAS;AAAA,IACvC,SAAS,KAAK;AACZ,YAAM,GAAG,UAAU,EAAE,OAAO,KAAK,CAAC,EAAE,MAAM,MAAM,MAAS;AACzD,YAAM;AAAA,IACR;AACA,SAAK,SAAS;AAAA,EAChB;AACF;AAEA,SAAS,qBAAqB,WAAmB,UAA0B;AACzE,MAAI,CAAC,KAAK,WAAW,QAAQ,EAAG,QAAO;AACvC,QAAM,MAAM,KAAK,SAAS,WAAW,QAAQ;AAC7C,SAAO,IAAI,WAAW,IAAI,IAAI,WAAW;AAC3C;AAiBA,SAAS,mBAAmB,GAAmB;AAC7C,MAAI,MAAM,EAAE,QAAQ,OAAO,GAAG;AAC9B,MAAI,IAAI,WAAW,IAAI,EAAG,OAAM,IAAI,MAAM,CAAC;AAC3C,SAAO;AACT;AAUA,SAAS,oBAAoB,QAAgD;AAC3E,MAAI,WAAW,UAAa,WAAW,KAAM,QAAO;AACpD,MAAI,IAAI,OAAO,MAAM,EAAE,QAAQ,OAAO,GAAG;AACzC,MAAI,EAAE,WAAW,IAAI,EAAG,KAAI,EAAE,MAAM,CAAC;AACrC,MAAI,EAAE,WAAW,EAAG,QAAO;AAC3B,MAAI,CAAC,EAAE,SAAS,GAAG,EAAG,KAAI,GAAG,CAAC;AAC9B,SAAO;AACT;AAEA,SAAS,iBAAiB,GAAa,GAAqB;AAC1D,QAAM,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM;AACrC,MAAI,MAAM,EAAG,QAAO;AACpB,MAAI,MAAM;AACV,MAAI,QAAQ;AACZ,MAAI,QAAQ;AACZ,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,KAAK,EAAE,CAAC,KAAK;AACnB,UAAM,KAAK,EAAE,CAAC,KAAK;AACnB,WAAO,KAAK;AACZ,aAAS,KAAK;AACd,aAAS,KAAK;AAAA,EAChB;AACA,QAAM,QAAQ,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK;AAChD,MAAI,UAAU,EAAG,QAAO;AACxB,SAAO,MAAM;AACf;","names":[]}

package/dist/{chunk-N53K2EXC.js → chunk-6VF75M3X.js}

@@ -1,6 +1,6 @@
 import {
   scanSignals
-} from "./chunk-XYIK4LF6.js";
+} from "./chunk-H3FZVNRN.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
@@ -140,4 +140,4 @@ var BootstrapEngine = class {
 export {
   BootstrapEngine
 };
-//# sourceMappingURL=chunk-N53K2EXC.js.map
+//# sourceMappingURL=chunk-6VF75M3X.js.map

package/dist/{chunk-XSZEP4SF.js → chunk-6XSPNR6L.js}

@@ -1,11 +1,11 @@
 import {
   runPostConsolidationMaterialize
-} from "./chunk-4KGVTPGD.js";
+} from "./chunk-6F6BXB7A.js";
 import {
   discoverMemoryExtensions,
   renderExtensionsBlock,
   resolveExtensionsRoot
-} from "./chunk-EJI5XIBB.js";
+} from "./chunk-JLNBQWZ2.js";
 import {
   isSemanticConsolidationLlmOperator
 } from "./chunk-G7D6GZ5J.js";
@@ -39,11 +39,13 @@ function findSimilarClusters(memories, config) {
     }));
     const clustered = /* @__PURE__ */ new Set();
     for (let i = 0; i < tokenized.length && totalCandidates < config.maxPerRun; i++) {
+      const remainingBudget = config.maxPerRun - totalCandidates;
+      if (remainingBudget < config.minClusterSize) break;
       if (clustered.has(tokenized[i].memory.frontmatter.id)) continue;
       const cluster = [tokenized[i].memory];
       let totalOverlap = 0;
       let comparisons = 0;
-      for (let j = i + 1; j < tokenized.length; j++) {
+      for (let j = i + 1; j < tokenized.length && cluster.length < remainingBudget; j++) {
         if (clustered.has(tokenized[j].memory.frontmatter.id)) continue;
         const aTokens = tokenized[i].tokens;
         const bTokens = tokenized[j].tokens;
@@ -55,7 +57,6 @@ function findSimilarClusters(memories, config) {
           cluster.push(tokenized[j].memory);
           totalOverlap += score;
           comparisons++;
-          if (totalCandidates + cluster.length >= config.maxPerRun) break;
         }
       }
       if (cluster.length >= config.minClusterSize) {
@@ -216,4 +217,4 @@ export {
   buildExtensionsBlockForConsolidation,
   materializeAfterSemanticConsolidation
 };
-//# sourceMappingURL=chunk-XSZEP4SF.js.map
+//# sourceMappingURL=chunk-6XSPNR6L.js.map

package/dist/chunk-6XSPNR6L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/semantic-consolidation.ts"],"sourcesContent":["/**\n * semantic-consolidation.ts — Semantic Consolidation Engine\n *\n * Finds clusters of semantically similar memories using token overlap,\n * synthesizes canonical versions via LLM, and archives the originals.\n * Reduces memory store bloat while preserving all unique information.\n */\n\nimport type { MemoryFile, PluginConfig } from \"./types.js\";\nimport { normalizeRecallTokens, countRecallTokenOverlap } from \"./recall-tokenization.js\";\nimport { runPostConsolidationMaterialize } from \"./connectors/codex-materialize-runner.js\";\nimport type { MaterializeResult, RolloutSummaryInput } from \"./connectors/codex-materialize.js\";\nimport { discoverMemoryExtensions, renderExtensionsBlock, resolveExtensionsRoot } from \"./memory-extension-host/index.js\";\nimport { log } from \"./logger.js\";\n\n// Re-export resolveExtensionsRoot for backward compatibility — existing\n// consumers that import from semantic-consolidation.ts continue to work.\nexport { resolveExtensionsRoot } from \"./memory-extension-host/index.js\";\n\n// Operator vocabulary (issue #561).  The types and validators live in a\n// standalone `consolidation-operator.ts` module so `storage.ts` can import\n// them without creating a `storage → semantic-consolidation →\n// codex-materialize-runner → storage` cycle.  Re-exported here so existing\n// consumers that reach for `./semantic-consolidation.js` keep working.\nexport {\n  CONSOLIDATION_OPERATORS,\n  isConsolidationOperator,\n  isSemanticConsolidationLlmOperator,\n  isValidDerivedFromEntry,\n  type ConsolidationOperator,\n  type SemanticConsolidationLlmOperator,\n} from \"./consolidation-operator.js\";\n\nimport {\n  CONSOLIDATION_OPERATORS as _CONSOLIDATION_OPERATORS,\n  isConsolidationOperator as _isConsolidationOperator,\n  isSemanticConsolidationLlmOperator as _isSemanticConsolidationLlmOperator,\n  type ConsolidationOperator as _ConsolidationOperator,\n  type SemanticConsolidationLlmOperator as _SemanticConsolidationLlmOperator,\n} from \"./consolidation-operator.js\";\n\nexport interface ConsolidationCluster {\n  category: string;\n  memories: MemoryFile[];\n  overlapScore: number;\n  canonicalContent?: string;\n}\n\nexport interface SemanticConsolidationResult {\n  clustersFound: number;\n  memoriesConsolidated: number;\n  memoriesArchived: number;\n  errors: number;\n  clusters: ConsolidationCluster[];\n}\n\n/**\n * Find clusters of semantically similar memories using token overlap.\n */\nexport function findSimilarClusters(\n  memories: MemoryFile[],\n  config: {\n    threshold: number;\n    minClusterSize: number;\n    excludeCategories: string[];\n    maxPerRun: number;\n  },\n): ConsolidationCluster[] {\n  const excluded = new Set(config.excludeCategories);\n\n  // Group by category first\n  const byCategory = new Map<string, MemoryFile[]>();\n  for (const m of memories) {\n    const cat = m.frontmatter.category;\n    if (excluded.has(cat)) continue;\n    if (m.frontmatter.status && m.frontmatter.status !== \"active\") continue;\n    const list = byCategory.get(cat) ?? [];\n    list.push(m);\n    byCategory.set(cat, list);\n  }\n\n  const clusters: ConsolidationCluster[] = [];\n  let totalCandidates = 0;\n\n  for (const [category, mems] of byCategory) {\n    if (totalCandidates >= config.maxPerRun) break;\n\n    // Token-normalize all memories in this category\n    const tokenized = mems.map((m) => ({\n      memory: m,\n      tokens: new Set(normalizeRecallTokens(m.content, [])),\n    }));\n\n    // Track which memories are already clustered\n    const clustered = new Set<string>();\n\n    for (let i = 0; i < tokenized.length && totalCandidates < config.maxPerRun; i++) {\n      const remainingBudget = config.maxPerRun - totalCandidates;\n      if (remainingBudget < config.minClusterSize) break;\n      if (clustered.has(tokenized[i].memory.frontmatter.id)) continue;\n\n      const cluster: MemoryFile[] = [tokenized[i].memory];\n      let totalOverlap = 0;\n      let comparisons = 0;\n\n      for (let j = i + 1; j < tokenized.length && cluster.length < remainingBudget; j++) {\n        if (clustered.has(tokenized[j].memory.frontmatter.id)) continue;\n\n        const aTokens = tokenized[i].tokens;\n        const bTokens = tokenized[j].tokens;\n        if (aTokens.size === 0 || bTokens.size === 0) continue;\n\n        // Bidirectional overlap: what fraction of tokens are shared\n        const overlap = countRecallTokenOverlap(aTokens, [...bTokens].join(\" \"));\n        const maxTokens = Math.max(aTokens.size, bTokens.size);\n        const score = maxTokens > 0 ? overlap / maxTokens : 0;\n\n        if (score >= config.threshold) {\n          cluster.push(tokenized[j].memory);\n          totalOverlap += score;\n          comparisons++;\n        }\n      }\n\n      if (cluster.length >= config.minClusterSize) {\n        for (const m of cluster) clustered.add(m.frontmatter.id);\n        clusters.push({\n          category,\n          memories: cluster,\n          overlapScore: comparisons > 0 ? totalOverlap / comparisons : 0,\n        });\n        totalCandidates += cluster.length;\n      }\n    }\n  }\n\n  return clusters;\n}\n\n/**\n * Build the LLM prompt for synthesizing a canonical memory from a cluster.\n */\nexport function buildConsolidationPrompt(cluster: ConsolidationCluster): string {\n  const memoryTexts = cluster.memories\n    .map(\n      (m, i) =>\n        `Memory ${i + 1} (${m.frontmatter.id}, created ${m.frontmatter.created}):\\n${m.content}`,\n    )\n    .join(\"\\n\\n\");\n\n  return `You are a memory consolidation system. The following ${cluster.memories.length} memories in the \"${cluster.category}\" category contain overlapping information.\n\nSynthesize them into ONE canonical memory that:\n1. Preserves ALL unique information from every source memory\n2. Removes redundancy and repetition\n3. Uses clear, concise language\n4. Maintains the same category and tone\n5. Does NOT add information that isn't in the sources\n\n${memoryTexts}\n\nWrite ONLY the consolidated memory content (no metadata, no explanation, no preamble):`;\n}\n\n/**\n * Parse the LLM response to extract the canonical content.\n */\nexport function parseConsolidationResponse(response: string): string {\n  return response.trim();\n}\n\n// ─── Operator-aware prompt / parse (issue #561 PR 3) ─────────────────────────\n\n/**\n * Structured result from an operator-aware consolidation LLM call.\n *\n * - `operator` — the consolidation operator the LLM chose for this cluster.\n *   Falls back to the heuristic default when the LLM omits or returns an\n *   unknown value (the parser never surfaces an invalid operator; see\n *   `parseOperatorAwareConsolidationResponse`).\n * - `output` — the canonical content (same format the legacy prompt\n *   returns).  Callers persist this as the body of the new memory.\n */\nexport interface OperatorAwareConsolidationResult {\n  // Restricted to the LLM-allowed subset (Cursor Bugbot, PR #730):\n  // `pattern-reinforcement` is reserved for the maintenance job and\n  // must never reach this struct from a consolidation LLM response.\n  operator: _SemanticConsolidationLlmOperator;\n  output: string;\n}\n\n/**\n * Heuristic default operator for a cluster.  Used as the fallback when the\n * LLM does not return a parseable operator, and as the \"floor\" decision in\n * `parseOperatorAwareConsolidationResponse`.\n *\n * Current heuristic (kept deliberately conservative — PR 3 only):\n *\n *   - Two or more memories being collapsed into one canonical blob is a\n *     MERGE by definition.  This is the path the current clustering\n *     pipeline exercises.\n *   - A cluster of size 1 that still reaches consolidation (future path,\n *     e.g. supersession of a single older memory by a newer value) is an\n *     UPDATE.\n *   - SPLIT is never selected by the heuristic because the current write\n *     path emits exactly one canonical memory per cluster.  The prompt\n *     reserves SPLIT for future cluster shapes where the LLM decides one\n *     logical source actually encodes several distinct facts — at which\n *     point the orchestrator would need to write multiple outputs.\n */\nexport function chooseConsolidationOperator(\n  cluster: ConsolidationCluster,\n): _SemanticConsolidationLlmOperator {\n  if (cluster.memories.length <= 1) return \"update\";\n  return \"merge\";\n}\n\n/**\n * Build the operator-aware LLM prompt.  The LLM is asked to return a\n * JSON object `{ \"operator\": <split|merge|update>, \"output\": <content> }`.\n *\n * The prompt is additive: it still asks for a single canonical blob under\n * `output`, so the upstream write path does not change.  Future expansions\n * (SPLIT emitting multiple outputs) are explicitly documented as\n * out-of-scope for the parser — `parseOperatorAwareConsolidationResponse`\n * collapses any SPLIT response into a single canonical output for now.\n */\nexport function buildOperatorAwareConsolidationPrompt(\n  cluster: ConsolidationCluster,\n): string {\n  const memoryTexts = cluster.memories\n    .map(\n      (m, i) =>\n        `Memory ${i + 1} (${m.frontmatter.id}, created ${m.frontmatter.created}):\\n${m.content}`,\n    )\n    .join(\"\\n\\n\");\n\n  return `You are a memory consolidation system.  The following ${cluster.memories.length} memories in the \"${cluster.category}\" category contain overlapping information.\n\nPick exactly ONE consolidation operator for this cluster and return a JSON object.\n\nOperator vocabulary:\n  - \"merge\"  — multiple distinct source memories overlap and should be collapsed into one canonical memory (most common).\n  - \"update\" — one source memory carries a stale value that a newer source supersedes within the same logical fact.\n  - \"split\"  — a single logical source really encodes multiple distinct facts that should be separated (rare; if you pick split, still emit ONE canonical body — the write path will chunk it later).\n\nOutput JSON ONLY, no prose before or after.  The \"operator\" key MUST be set to exactly one of the three strings \"merge\", \"update\", or \"split\" — never a pipe-separated placeholder like \"merge|update|split\".  Example shape:\n  {\n    \"operator\": \"merge\",\n    \"output\": \"<the canonical memory text>\"\n  }\n\nThe \"output\" value must:\n1. Preserve ALL unique information from every source memory\n2. Remove redundancy and repetition\n3. Use clear, concise language\n4. Match the \"${cluster.category}\" category and tone\n5. NOT add information that isn't in the sources\n\n${memoryTexts}\n\nReturn ONLY the JSON object:`;\n}\n\n/**\n * Parse an operator-aware consolidation response.\n *\n * Contract:\n *   - Accepts strict JSON `{ \"operator\": \"...\", \"output\": \"...\" }`.\n *   - Tolerates a JSON payload wrapped in a fenced code block (```json ...```).\n *   - Falls back to the heuristic operator when the JSON is malformed,\n *     the `operator` field is missing / unknown, or the raw response is\n *     a plain blob with no JSON at all.  This keeps PR 3 backwards\n *     compatible with older models that ignore the JSON instruction.\n *   - Never throws.  A missing / empty `output` field falls back to the\n *     trimmed raw response so the caller still writes something rather\n *     than dropping the cluster.\n */\nexport function parseOperatorAwareConsolidationResponse(\n  response: string,\n  cluster: ConsolidationCluster,\n): OperatorAwareConsolidationResult {\n  const fallback: OperatorAwareConsolidationResult = {\n    operator: chooseConsolidationOperator(cluster),\n    output: response.trim(),\n  };\n\n  const trimmed = response.trim();\n  if (trimmed.length === 0) return fallback;\n\n  // Strip a fenced code block if present.\n  const fenced = /^```(?:json)?\\s*([\\s\\S]*?)```\\s*$/u.exec(trimmed);\n  const payload = fenced ? fenced[1].trim() : trimmed;\n\n  // Find a balanced brace-delimited JSON object that has an `operator`\n  // key (PR #632 round-4 review, codex P1).  A first/last-brace slice\n  // breaks when the model prepends an earlier brace block (e.g.\n  // `Example: {\"note\":\"...\"} ... {\"operator\":\"merge\",...}`).  Walk the\n  // payload tracking nesting + string/escape state and skip past\n  // objects that don't look like our target shape.\n  const parsed = findLastJsonObjectWithOperator(payload);\n  if (parsed === undefined) return fallback;\n  if (typeof parsed !== \"object\" || parsed === null) return fallback;\n\n  const obj = parsed as Record<string, unknown>;\n  const rawOperator = typeof obj.operator === \"string\" ? obj.operator.trim().toLowerCase() : \"\";\n  const rawOutput = typeof obj.output === \"string\" ? obj.output : \"\";\n\n  // Narrow gate (Cursor Bugbot review on PR #730 head `aa1c2a8`):\n  // accept ONLY the legacy split/merge/update LLM vocabulary here.\n  // `pattern-reinforcement` joined the broader `ConsolidationOperator`\n  // type in #687 PR 2/4 but is reserved for the maintenance job — if\n  // an LLM hallucinates that operator we must NOT promote it onto\n  // `derived_via`.\n  const operator = _isSemanticConsolidationLlmOperator(rawOperator)\n    ? rawOperator\n    : chooseConsolidationOperator(cluster);\n  const output = rawOutput.trim().length > 0 ? rawOutput.trim() : response.trim();\n\n  return { operator, output };\n}\n\n/**\n * Walk `text`, find all balanced top-level `{ ... }` blocks whose\n * JSON.parse result is an object with an `operator` key, and return\n * the LAST one (function name reflects this — PR #632 review,\n * cursor Low).  Returns `undefined` when nothing matches.  Tracks\n * string state + escape sequences so braces inside string values\n * don't throw off the depth counter.\n *\n * Used by `parseOperatorAwareConsolidationResponse` to tolerate models\n * that prepend an explanatory JSON example block before the real\n * payload (PR #632 round-4 + round-5 review, codex P1).  We take the\n * LAST candidate so that an instructional example with an `operator`\n * key ahead of the real answer doesn't steal precedence — models\n * typically write the example first and the real answer last.\n */\nfunction findLastJsonObjectWithOperator(text: string): unknown {\n  let searchFrom = 0;\n  let last: unknown = undefined;\n  while (searchFrom < text.length) {\n    const start = text.indexOf(\"{\", searchFrom);\n    if (start < 0) return last;\n    let depth = 0;\n    let inString = false;\n    let escape = false;\n    let closed = false;\n    let endIdx = -1;\n    for (let i = start; i < text.length; i++) {\n      const ch = text[i];\n      if (inString) {\n        if (escape) {\n          escape = false;\n        } else if (ch === \"\\\\\") {\n          escape = true;\n        } else if (ch === '\"') {\n          inString = false;\n        }\n        continue;\n      }\n      if (ch === '\"') {\n        inString = true;\n      } else if (ch === \"{\") {\n        depth += 1;\n      } else if (ch === \"}\") {\n        depth -= 1;\n        if (depth === 0) {\n          closed = true;\n          endIdx = i;\n          break;\n        }\n      }\n    }\n    if (!closed) return last;\n    const slice = text.slice(start, endIdx + 1);\n    try {\n      const parsed = JSON.parse(slice);\n      if (\n        typeof parsed === \"object\" &&\n        parsed !== null &&\n        \"operator\" in (parsed as Record<string, unknown>)\n      ) {\n        last = parsed;\n      }\n    } catch {\n      // Fall through to the next candidate.\n    }\n    searchFrom = endIdx + 1;\n  }\n  return last;\n}\n\n// Silence unused-import warnings when tsup tree-shakes: these are used\n// above in chooseConsolidationOperator + parse helpers.\nvoid _CONSOLIDATION_OPERATORS;\n\n/**\n * Discover extensions and build the block to append to a consolidation prompt.\n * Returns \"\" when extensions are disabled or none are found.\n */\nexport async function buildExtensionsBlockForConsolidation(\n  config: PluginConfig,\n): Promise<string> {\n  if (!config.memoryExtensionsEnabled) return \"\";\n  const root = resolveExtensionsRoot(config);\n  const extensions = await discoverMemoryExtensions(root, log);\n  if (extensions.length === 0) return \"\";\n  return renderExtensionsBlock(extensions);\n}\n\n/**\n * Optional post-consolidation hook — materializes the namespace into Codex's\n * native memory layout when the consolidation run finishes. Kept here (rather\n * than in orchestrator.ts) so #378 doesn't conflict with Wave 1 edits.\n *\n * Safe to call regardless of config state: honors `codexMaterializeMemories`\n * and `codexMaterializeOnConsolidation` and silently becomes a no-op when\n * either is disabled.\n */\nexport async function materializeAfterSemanticConsolidation(options: {\n  config: PluginConfig;\n  namespace?: string;\n  memories?: MemoryFile[];\n  memoryDir?: string;\n  codexHome?: string;\n  rolloutSummaries?: RolloutSummaryInput[];\n  now?: Date;\n}): Promise<MaterializeResult | null> {\n  // Delegates to the shared post-consolidation helper so semantic and causal\n  // flows stay in lock-step — any guard/logging change happens in one place.\n  return runPostConsolidationMaterialize(\"[semantic-consolidation]\", options);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA2DO,SAAS,oBACd,UACA,QAMwB;AACxB,QAAM,WAAW,IAAI,IAAI,OAAO,iBAAiB;AAGjD,QAAM,aAAa,oBAAI,IAA0B;AACjD,aAAW,KAAK,UAAU;AACxB,UAAM,MAAM,EAAE,YAAY;AAC1B,QAAI,SAAS,IAAI,GAAG,EAAG;AACvB,QAAI,EAAE,YAAY,UAAU,EAAE,YAAY,WAAW,SAAU;AAC/D,UAAM,OAAO,WAAW,IAAI,GAAG,KAAK,CAAC;AACrC,SAAK,KAAK,CAAC;AACX,eAAW,IAAI,KAAK,IAAI;AAAA,EAC1B;AAEA,QAAM,WAAmC,CAAC;AAC1C,MAAI,kBAAkB;AAEtB,aAAW,CAAC,UAAU,IAAI,KAAK,YAAY;AACzC,QAAI,mBAAmB,OAAO,UAAW;AAGzC,UAAM,YAAY,KAAK,IAAI,CAAC,OAAO;AAAA,MACjC,QAAQ;AAAA,MACR,QAAQ,IAAI,IAAI,sBAAsB,EAAE,SAAS,CAAC,CAAC,CAAC;AAAA,IACtD,EAAE;AAGF,UAAM,YAAY,oBAAI,IAAY;AAElC,aAAS,IAAI,GAAG,IAAI,UAAU,UAAU,kBAAkB,OAAO,WAAW,KAAK;AAC/E,YAAM,kBAAkB,OAAO,YAAY;AAC3C,UAAI,kBAAkB,OAAO,eAAgB;AAC7C,UAAI,UAAU,IAAI,UAAU,CAAC,EAAE,OAAO,YAAY,EAAE,EAAG;AAEvD,YAAM,UAAwB,CAAC,UAAU,CAAC,EAAE,MAAM;AAClD,UAAI,eAAe;AACnB,UAAI,cAAc;AAElB,eAAS,IAAI,IAAI,GAAG,IAAI,UAAU,UAAU,QAAQ,SAAS,iBAAiB,KAAK;AACjF,YAAI,UAAU,IAAI,UAAU,CAAC,EAAE,OAAO,YAAY,EAAE,EAAG;AAEvD,cAAM,UAAU,UAAU,CAAC,EAAE;AAC7B,cAAM,UAAU,UAAU,CAAC,EAAE;AAC7B,YAAI,QAAQ,SAAS,KAAK,QAAQ,SAAS,EAAG;AAG9C,cAAM,UAAU,wBAAwB,SAAS,CAAC,GAAG,OAAO,EAAE,KAAK,GAAG,CAAC;AACvE,cAAM,YAAY,KAAK,IAAI,QAAQ,MAAM,QAAQ,IAAI;AACrD,cAAM,QAAQ,YAAY,IAAI,UAAU,YAAY;AAEpD,YAAI,SAAS,OAAO,WAAW;AAC7B,kBAAQ,KAAK,UAAU,CAAC,EAAE,MAAM;AAChC,0BAAgB;AAChB;AAAA,QACF;AAAA,MACF;AAEA,UAAI,QAAQ,UAAU,OAAO,gBAAgB;AAC3C,mBAAW,KAAK,QAAS,WAAU,IAAI,EAAE,YAAY,EAAE;AACvD,iBAAS,KAAK;AAAA,UACZ;AAAA,UACA,UAAU;AAAA,UACV,cAAc,cAAc,IAAI,eAAe,cAAc;AAAA,QAC/D,CAAC;AACD,2BAAmB,QAAQ;AAAA,MAC7B;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,yBAAyB,SAAuC;AAC9E,QAAM,cAAc,QAAQ,SACzB;AAAA,IACC,CAAC,GAAG,MACF,UAAU,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,OAAO;AAAA,EAAO,EAAE,OAAO;AAAA,EAC1F,EACC,KAAK,MAAM;AAEd,SAAO,wDAAwD,QAAQ,SAAS,MAAM,qBAAqB,QAAQ,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAS3H,WAAW;AAAA;AAAA;AAGb;AAKO,SAAS,2BAA2B,UAA0B;AACnE,SAAO,SAAS,KAAK;AACvB;AAyCO,SAAS,4BACd,SACmC;AACnC,MAAI,QAAQ,SAAS,UAAU,EAAG,QAAO;AACzC,SAAO;AACT;AAYO,SAAS,sCACd,SACQ;AACR,QAAM,cAAc,QAAQ,SACzB;AAAA,IACC,CAAC,GAAG,MACF,UAAU,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,OAAO;AAAA,EAAO,EAAE,OAAO;AAAA,EAC1F,EACC,KAAK,MAAM;AAEd,SAAO,yDAAyD,QAAQ,SAAS,MAAM,qBAAqB,QAAQ,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,gBAmB9G,QAAQ,QAAQ;AAAA;AAAA;AAAA,EAG9B,WAAW;AAAA;AAAA;AAGb;AAgBO,SAAS,wCACd,UACA,SACkC;AAClC,QAAM,WAA6C;AAAA,IACjD,UAAU,4BAA4B,OAAO;AAAA,IAC7C,QAAQ,SAAS,KAAK;AAAA,EACxB;AAEA,QAAM,UAAU,SAAS,KAAK;AAC9B,MAAI,QAAQ,WAAW,EAAG,QAAO;AAGjC,QAAM,SAAS,qCAAqC,KAAK,OAAO;AAChE,QAAM,UAAU,SAAS,OAAO,CAAC,EAAE,KAAK,IAAI;AAQ5C,QAAM,SAAS,+BAA+B,OAAO;AACrD,MAAI,WAAW,OAAW,QAAO;AACjC,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;AAE1D,QAAM,MAAM;AACZ,QAAM,cAAc,OAAO,IAAI,aAAa,WAAW,IAAI,SAAS,KAAK,EAAE,YAAY,IAAI;AAC3F,QAAM,YAAY,OAAO,IAAI,WAAW,WAAW,IAAI,SAAS;AAQhE,QAAM,WAAW,mCAAoC,WAAW,IAC5D,cACA,4BAA4B,OAAO;AACvC,QAAM,SAAS,UAAU,KAAK,EAAE,SAAS,IAAI,UAAU,KAAK,IAAI,SAAS,KAAK;AAE9E,SAAO,EAAE,UAAU,OAAO;AAC5B;AAiBA,SAAS,+BAA+B,MAAuB;AAC7D,MAAI,aAAa;AACjB,MAAI,OAAgB;AACpB,SAAO,aAAa,KAAK,QAAQ;AAC/B,UAAM,QAAQ,KAAK,QAAQ,KAAK,UAAU;AAC1C,QAAI,QAAQ,EAAG,QAAO;AACtB,QAAI,QAAQ;AACZ,QAAI,WAAW;AACf,QAAI,SAAS;AACb,QAAI,SAAS;AACb,QAAI,SAAS;AACb,aAAS,IAAI,OAAO,IAAI,KAAK,QAAQ,KAAK;AACxC,YAAM,KAAK,KAAK,CAAC;AACjB,UAAI,UAAU;AACZ,YAAI,QAAQ;AACV,mBAAS;AAAA,QACX,WAAW,OAAO,MAAM;AACtB,mBAAS;AAAA,QACX,WAAW,OAAO,KAAK;AACrB,qBAAW;AAAA,QACb;AACA;AAAA,MACF;AACA,UAAI,OAAO,KAAK;AACd,mBAAW;AAAA,MACb,WAAW,OAAO,KAAK;AACrB,iBAAS;AAAA,MACX,WAAW,OAAO,KAAK;AACrB,iBAAS;AACT,YAAI,UAAU,GAAG;AACf,mBAAS;AACT,mBAAS;AACT;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,QAAI,CAAC,OAAQ,QAAO;AACpB,UAAM,QAAQ,KAAK,MAAM,OAAO,SAAS,CAAC;AAC1C,QAAI;AACF,YAAM,SAAS,KAAK,MAAM,KAAK;AAC/B,UACE,OAAO,WAAW,YAClB,WAAW,QACX,cAAe,QACf;AACA,eAAO;AAAA,MACT;AAAA,IACF,QAAQ;AAAA,IAER;AACA,iBAAa,SAAS;AAAA,EACxB;AACA,SAAO;AACT;AAUA,eAAsB,qCACpB,QACiB;AACjB,MAAI,CAAC,OAAO,wBAAyB,QAAO;AAC5C,QAAM,OAAO,sBAAsB,MAAM;AACzC,QAAM,aAAa,MAAM,yBAAyB,MAAM,GAAG;AAC3D,MAAI,WAAW,WAAW,EAAG,QAAO;AACpC,SAAO,sBAAsB,UAAU;AACzC;AAWA,eAAsB,sCAAsC,SAQtB;AAGpC,SAAO,gCAAgC,4BAA4B,OAAO;AAC5E;","names":[]}

package/dist/{chunk-6H2TESSP.js → chunk-765K3SAT.js}

@@ -5,13 +5,13 @@ import {
 import {
   computeTransferOutputRel,
   isTransferPathExcluded
-} from "./chunk-I6K5FBRQ.js";
+} from "./chunk-UI3NYK34.js";
 import {
   listFilesRecursive,
   sha256File,
   toPosixRelPath,
   writeJsonFile
-} from "./chunk-AGZQD76C.js";
+} from "./chunk-GCGJW34D.js";
 
 // src/transfer/export-md.ts
 import path from "path";
@@ -59,4 +59,4 @@ export {
   exportMarkdownBundle,
   looksLikeEngramMdExport
 };
-//# sourceMappingURL=chunk-6H2TESSP.js.map
+//# sourceMappingURL=chunk-765K3SAT.js.map

package/dist/{chunk-EDTHC6UD.js → chunk-77NAFXUD.js}

@@ -4,7 +4,7 @@ import {
 import {
   mergeEnv,
   readEnvVar
-} from "./chunk-XIG5PDM7.js";
+} from "./chunk-JUC24CTX.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
@@ -1072,4 +1072,4 @@ var LocalLlmClient = class _LocalLlmClient {
 export {
   LocalLlmClient
 };
-//# sourceMappingURL=chunk-EDTHC6UD.js.map
+//# sourceMappingURL=chunk-77NAFXUD.js.map