@remnic/core 10.0.44 → 10.0.46

package/dist/verified-recall.js

@@ -1,15 +1,15 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-XXW3P3RX.js";
+} from "./chunk-VWJ56T63.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-BIYVUPC6.js";
+import "./chunk-L46MG2GE.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-VY6BD5KB.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-CHNZPOWX.js";
-import "./chunk-4QLKVZH6.js";
+import "./chunk-PJBYVJKO.js";
+import "./chunk-2V664H6O.js";
 import "./chunk-XKDQTDXN.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-XRFLR3XF.js";
@@ -48,7 +48,7 @@ import "./chunk-LWRIGKFM.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-RROFIAYI.js";
+import "./chunk-I3IPXGFQ.js";
 import "./chunk-G26YNEOC.js";
 import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";

package/dist/who-knows-cli.js

@@ -4,15 +4,15 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-FPHU6KVI.js";
-import "./chunk-PJXSBXEC.js";
-import "./chunk-BIYVUPC6.js";
+} from "./chunk-BWRX322G.js";
+import "./chunk-JGMJZBFV.js";
+import "./chunk-L46MG2GE.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-VY6BD5KB.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-CHNZPOWX.js";
-import "./chunk-4QLKVZH6.js";
+import "./chunk-PJBYVJKO.js";
+import "./chunk-2V664H6O.js";
 import "./chunk-XKDQTDXN.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-XRFLR3XF.js";
@@ -51,7 +51,7 @@ import "./chunk-LWRIGKFM.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-RROFIAYI.js";
+import "./chunk-I3IPXGFQ.js";
 import "./chunk-G26YNEOC.js";
 import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";

package/dist/who-knows.js

@@ -9,14 +9,14 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-PJXSBXEC.js";
-import "./chunk-BIYVUPC6.js";
+} from "./chunk-JGMJZBFV.js";
+import "./chunk-L46MG2GE.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
 import "./chunk-VY6BD5KB.js";
 import "./chunk-G6OFEGUR.js";
-import "./chunk-CHNZPOWX.js";
-import "./chunk-4QLKVZH6.js";
+import "./chunk-PJBYVJKO.js";
+import "./chunk-2V664H6O.js";
 import "./chunk-XKDQTDXN.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-XRFLR3XF.js";
@@ -55,7 +55,7 @@ import "./chunk-LWRIGKFM.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
 import "./chunk-7CT3AI52.js";
-import "./chunk-RROFIAYI.js";
+import "./chunk-I3IPXGFQ.js";
 import "./chunk-G26YNEOC.js";
 import "./chunk-AF2XMJKD.js";
 import "./chunk-OR42ZI54.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.44",
+  "version": "10.0.46",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3347,7 +3347,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.44"
+    "@remnic/coding-graph": "^10.0.46"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/convergence-refresh.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { refreshConvergedNamespaces } from "./convergence-refresh.js";
+
+test("convergence refresh requests a forced, strict index update", async () => {
+  let observedOptions: unknown;
+  let continued = false;
+  await assert.rejects(
+    () => refreshConvergedNamespaces(
+      ["generalist"],
+      {
+        updateNamespacesDetailed: async (_namespaces, _execution, options) => {
+          observedOptions = options;
+          return { backendCount: 1, eligibleNamespaces: ["generalist"] };
+        },
+      },
+      async () => {
+        continued = true;
+        throw new Error("storage-reached");
+      },
+      false,
+    ),
+    /storage-reached/,
+  );
+  assert.equal(continued, true);
+  assert.deepEqual(observedOptions, { strict: true, force: true });
+});
+
+test("an index-update throttle skip fails convergence refresh", async () => {
+  let continued = false;
+  await assert.rejects(
+    () => refreshConvergedNamespaces(
+      ["generalist"],
+      {
+        updateNamespacesDetailed: async () => {
+          throw new Error("QMD update skipped by min-interval gate");
+        },
+      },
+      async () => {
+        continued = true;
+        throw new Error("storage-reached");
+      },
+      false,
+    ),
+    /min-interval/,
+  );
+  assert.equal(continued, false);
+});
+
+test("a real QMD refresh failure still fails convergence refresh", async () => {
+  let continued = false;
+  await assert.rejects(
+    () => refreshConvergedNamespaces(
+      ["generalist"],
+      {
+        updateNamespacesDetailed: async () => {
+          throw new Error("qmd exploded");
+        },
+      },
+      async () => {
+        continued = true;
+        throw new Error("storage-reached");
+      },
+      false,
+    ),
+    /qmd exploded/,
+  );
+  assert.equal(continued, false);
+});

package/src/convergence-refresh.ts

@@ -15,10 +15,12 @@ export async function refreshConvergedNamespaces(
   const targetNamespaces = Array.from(new Set(namespaces.map((namespace) => namespace.trim()).filter(Boolean)));
   if (targetNamespaces.length === 0) return;
 
+  // Forced so a min-interval skip cannot masquerade as proof that the
+  // converged writes are indexed; a real failure still fails the refresh.
   const searchResult = await namespaceSearchRouter.updateNamespacesDetailed(
     targetNamespaces,
     undefined,
-    { strict: true },
+    { strict: true, force: true },
   );
   if (searchEnabled) {
     const eligible = new Set(searchResult.eligibleNamespaces);

package/src/namespaces/search.ts

@@ -217,7 +217,7 @@ export class NamespaceSearchRouter {
   async updateNamespaces(
     namespaces: string[],
     execution?: SearchExecutionOptions,
-    options?: { strict?: boolean },
+    options?: { strict?: boolean; force?: boolean },
   ): Promise<number> {
     return (await this.updateNamespacesDetailed(namespaces, execution, options)).backendCount;
   }
@@ -225,7 +225,7 @@ export class NamespaceSearchRouter {
   async updateNamespacesDetailed(
     namespaces: string[],
     execution?: SearchExecutionOptions,
-    options?: { strict?: boolean },
+    options?: { strict?: boolean; force?: boolean },
   ): Promise<NamespaceUpdateResult> {
     const unique = Array.from(new Set(namespaces.map((value) => value.trim()).filter(Boolean)));
     const eligible = (await Promise.all(
@@ -578,10 +578,14 @@ function backendSearchLimit(
 async function updateBackendRecord(
   record: NamespaceBackendRecord,
   execution?: SearchExecutionOptions,
-  options?: { strict?: boolean },
+  options?: { strict?: boolean; force?: boolean },
 ): Promise<void> {
   if (options?.strict === true) {
     if (
+      // Forced refreshes must skip the throttled all-collections update: its
+      // success has to prove the current writes are indexed, which a throttle
+      // skip cannot.
+      options.force !== true &&
       record.backend.updatesAllCollections?.() === true &&
       typeof record.backend.updateStrict === "function"
     ) {

package/src/offline-sync.test.ts

@@ -3713,3 +3713,112 @@ test("applyOfflineSyncSnapshot consumes readIncomingFile for records without inl
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("buildOfflineSyncSnapshot skips a file that vanishes during the walk", async () => {
+  const root = await tempDir("remnic-offline-vanish");
+  try {
+    await write(root, "facts/keep.md", "keep");
+    await write(root, "facts/gone.md", "gone");
+    const snapshot = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "local",
+      includeContent: false,
+      readFileDigest: async ({ path: relPath, filePath }) => {
+        if (relPath.endsWith("gone.md")) {
+          await rm(filePath);
+          throw Object.assign(new Error("ENOENT: vanished"), { code: "ENOENT" });
+        }
+        const content = await readFile(filePath);
+        return {
+          sha256: createHash("sha256").update(content).digest("hex"),
+          bytes: content.length,
+        };
+      },
+    });
+    assert.deepEqual(snapshot.files.map((file) => file.path), ["facts/keep.md"]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("base snapshot fails when a base-known file vanishes before the fast-base stat", async () => {
+  const root = await tempDir("remnic-offline-base-vanish");
+  try {
+    await write(root, "facts/keep.md", "keep");
+    await write(root, "facts/gone.md", "gone");
+    const baseSnapshot = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "local",
+      includeContent: false,
+    });
+    await assert.rejects(
+      () => buildOfflineSyncSnapshotFromBase({
+        root,
+        sourceId: "local",
+        baseFiles: baseSnapshot.files,
+        baseCapturedAt: new Date(),
+        includeContent: false,
+        excludeFile: async ({ path: relPath, filePath }) => {
+          if (relPath === "facts/gone.md") await rm(filePath, { force: true });
+          return false;
+        },
+      }),
+      /base file vanished during walk/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("base snapshot omits a brand-new file that vanishes during the walk", async () => {
+  const root = await tempDir("remnic-offline-new-vanish");
+  try {
+    await write(root, "facts/keep.md", "keep");
+    await write(root, "facts/gone.md", "gone");
+    const baseSnapshot = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "local",
+      includeContent: false,
+    });
+    const baseFiles = baseSnapshot.files.filter((file) => file.path !== "facts/gone.md");
+    const snapshot = await buildOfflineSyncSnapshotFromBase({
+      root,
+      sourceId: "local",
+      baseFiles,
+      baseCapturedAt: new Date(),
+      includeContent: false,
+      excludeFile: async ({ path: relPath, filePath }) => {
+        if (relPath === "facts/gone.md") await rm(filePath, { force: true });
+        return false;
+      },
+    });
+    assert.deepEqual(snapshot.files.map((file) => file.path), ["facts/keep.md"]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("snapshot fails when an embedding generation member vanishes during the walk", async () => {
+  const root = await tempDir("remnic-offline-shard-vanish");
+  try {
+    await write(root, "state/embeddings/shard-0000.json", "a");
+    await write(root, "state/embeddings/shard-0001.json", "b");
+    await assert.rejects(
+      () => buildOfflineSyncSnapshot({
+        root,
+        sourceId: "local",
+        includeContent: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath === "state/embeddings/shard-0000.json") {
+            await rm(path.join(root, "state/embeddings/shard-0001.json"), { force: true });
+          }
+          const content = await readFile(filePath);
+          return { sha256: createHash("sha256").update(content).digest("hex"), bytes: content.length };
+        },
+      }),
+      /embedding generation member vanished/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/offline-sync.ts

@@ -12,6 +12,7 @@ import {
   utimes,
   writeFile,
 } from "node:fs/promises";
+import type { Stats } from "node:fs";
 import path from "node:path";
 import {
   DEFAULT_TRANSFER_EXCLUDE_DIRS,
@@ -26,6 +27,7 @@ import {
 import { parseFlexibleIsoTimestamp } from "./utils/iso-timestamp.js";
 import { EmbeddingIndexStorageError } from "./embedding-index-storage.js";
 import { isEmbeddingGenerationMarkerPath, matchesOfflineSyncDefaultExclude } from "./offline-sync-exclude-globs.js";
+import { isNotFoundError } from "./utils/errno.js";
 import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 import {
   applyIncomingEmbeddingGenerations,
@@ -790,6 +792,31 @@ async function canReuseFastBaseFileStateFromDisk(
 
 async function readOfflineSyncFileRecord(
   options: OfflineSyncFileRecordOptions,
+): Promise<OfflineSyncFileRecord | null> {
+  try {
+    return await readPresentOfflineSyncFileRecord(options);
+  } catch (error) {
+    // A file removed between readdir and stat/hash is a race, not a corrupt corpus.
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+}
+
+// A vanished path may only be omitted when nothing can misread the gap:
+// embedding generations travel and replace as one unit (issue #3148), and a
+// base-known file omitted here would fabricate a delete in
+// buildOfflineSyncChangesetFromSnapshot.
+function assertSnapshotVanishIsSafe(relPath: string, base: ReadonlyMap<string, unknown> | undefined): void {
+  if (embeddingGenerationMembership(relPath) !== null) {
+    throw new Error(`offline sync embedding generation member vanished during snapshot walk: ${relPath}`);
+  }
+  if (base?.has(relPath)) {
+    throw new Error(`offline sync snapshot base file vanished during walk: ${relPath}`);
+  }
+}
+
+async function readPresentOfflineSyncFileRecord(
+  options: OfflineSyncFileRecordOptions,
 ): Promise<OfflineSyncFileRecord> {
   throwIfOfflineSyncAborted(options.signal);
   const relPath = validateArchiveRelativePath(options.relPath, "offlineSyncFile.path");
@@ -895,7 +922,7 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         path: relPosix,
         filePath: abs,
       })) continue;
-      yield await readOfflineSyncFileRecord({
+      const record = await readOfflineSyncFileRecord({
         root,
         relPath: relPosix,
         filePath: abs,
@@ -904,6 +931,8 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         readFileDigest: options.readFileDigest,
         signal: options.signal,
       });
+      if (record) yield record;
+      else assertSnapshotVanishIsSafe(relPosix, undefined);
     }
   }
 
@@ -1060,7 +1089,18 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         path: relPosix,
         filePath: abs,
       })) continue;
-      const st = await stat(abs);
+      let st: Stats;
+      try {
+        st = await stat(abs);
+      } catch (error) {
+        // Same race readOfflineSyncFileRecord tolerates, unless omitting the
+        // path could fabricate a delete or downgrade a generation.
+        if (isNotFoundError(error)) {
+          assertSnapshotVanishIsSafe(relPosix, base);
+          continue;
+        }
+        throw error;
+      }
       const baseEntry = base.get(relPosix);
       if (
         options.includeContent !== true &&
@@ -1071,7 +1111,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         files.push(baseEntry);
         continue;
       }
-      files.push(await readOfflineSyncFileRecord({
+      const record = await readOfflineSyncFileRecord({
         root,
         relPath: relPosix,
         filePath: abs,
@@ -1079,7 +1119,9 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         readFile: options.readFile,
         readFileDigest: options.readFileDigest,
         signal: options.signal,
-      }));
+      });
+      if (record) files.push(record);
+      else assertSnapshotVanishIsSafe(relPosix, base);
     }
   }
 
@@ -1165,7 +1207,7 @@ export async function buildOfflineSyncSnapshotForPaths(options: {
     })) {
       throw new Error(`offline sync snapshot path is excluded: ${relPath}`);
     }
-    files.push(await readOfflineSyncFileRecord({
+    const record = await readOfflineSyncFileRecord({
       root,
       relPath,
       filePath,
@@ -1173,7 +1215,9 @@ export async function buildOfflineSyncSnapshotForPaths(options: {
       readFile: options.readFile,
       readFileDigest: options.readFileDigest,
       signal: options.signal,
-    }));
+    });
+    if (record) files.push(record);
+    else assertSnapshotVanishIsSafe(relPath, undefined);
   }
   throwIfOfflineSyncAborted(options.signal);
 

package/src/orchestrator-convergence-refresh.test.ts

@@ -22,38 +22,43 @@ test("refreshNamespacesAfterConvergence runs one strict QMD batch and rebuilds e
     });
     const qmdCalls: Array<{
       namespaces: string[];
-      options: { strict?: boolean } | undefined;
+      options: { strict?: boolean; force?: boolean } | undefined;
     }> = [];
     const storageCalls: string[] = [];
     const orchestrator = Object.create(Orchestrator.prototype) as Orchestrator;
-    const internals = orchestrator as unknown as {
+    type ConvergenceRefreshInternals = {
       config: { defaultNamespace: string; qmdEnabled: boolean };
       namespaceSearchRouter: {
         updateNamespacesDetailed(
           namespaces: string[],
           execution?: unknown,
-          options?: { strict?: boolean }
+          options?: { strict?: boolean; force?: boolean },
         ): Promise<{ backendCount: number; eligibleNamespaces: string[] }>;
       };
       getStorage(namespace: string): Promise<StorageManager>;
     };
-    internals.config = { defaultNamespace: "default", qmdEnabled: true };
-    internals.namespaceSearchRouter = {
-      async updateNamespacesDetailed(namespaces, _execution, options) {
-        qmdCalls.push({ namespaces, options });
-        return { backendCount: 1, eligibleNamespaces: namespaces };
-      },
-    };
     const storageByNamespace = new Map([
       ["team", teamStorage],
       ["shared", sharedStorage],
     ]);
-    internals.getStorage = async (namespace) => {
-      storageCalls.push(namespace);
-      const storage = storageByNamespace.get(namespace);
-      assert.ok(storage);
-      return storage;
+    // SAFETY: fresh prototype instance under test; every internals field is
+    // provided here before refreshNamespacesAfterConvergence runs.
+    const internals: ConvergenceRefreshInternals = {
+      config: { defaultNamespace: "default", qmdEnabled: true },
+      namespaceSearchRouter: {
+        async updateNamespacesDetailed(namespaces, _execution, options) {
+          qmdCalls.push({ namespaces, options });
+          return { backendCount: 1, eligibleNamespaces: namespaces };
+        },
+      },
+      getStorage: async (namespace) => {
+        storageCalls.push(namespace);
+        const storage = storageByNamespace.get(namespace);
+        assert.ok(storage);
+        return storage;
+      },
     };
+    Object.assign(orchestrator, internals);
     const refreshSurface = orchestrator as unknown as {
       refreshNamespacesAfterConvergence(namespaces: readonly string[]): Promise<void>;
     };
@@ -63,7 +68,7 @@ test("refreshNamespacesAfterConvergence runs one strict QMD batch and rebuilds e
     assert.deepEqual(qmdCalls, [
       {
         namespaces: ["team", "shared"],
-        options: { strict: true },
+        options: { strict: true, force: true },
       },
     ]);
     assert.deepEqual(storageCalls, ["team", "shared"]);

package/src/qmd-client.test.ts

@@ -80,6 +80,29 @@ test("updateStrict respects QMD update min-interval throttles", async () => {
   assert.equal(calls.length, 1);
 });
 
+test("a locked qmd update does not suppress the next strict update", async () => {
+  const client = new QmdClient("memories", 3, { updateMinIntervalMs: 0 });
+  client.resetUpdateThrottles();
+  let calls = 0;
+  Object.assign(client, {
+    available: true,
+    runQmdCommand: async () => {
+      calls += 1;
+      if (calls === 1) throw new Error("qmd update failed (code 1): SqliteError: database is locked");
+      return { stdout: "", stderr: "" };
+    },
+  } satisfies Partial<SubprocessInternals>);
+
+  try {
+    await assert.rejects(() => client.updateStrict(), /database is locked/);
+    await client.updateStrict();
+  } finally {
+    client.resetUpdateThrottles();
+  }
+
+  assert.equal(calls, 2);
+});
+
 test("embedCollectionStrict rejects QMD embed subprocess failures", async () => {
   const client = new QmdClient("memories", 3, { updateMinIntervalMs: 60_000 });
   client.resetUpdateThrottles();

package/src/qmd.ts

@@ -2406,15 +2406,20 @@ export class QmdClient implements SearchBackend {
       clearQmdResultCaches();
       log.debug(`QMD update completed for collection=${name}`);
     } catch (err) {
-      const at = Date.now();
-      if (options.perCollectionThrottle) {
-        globalState.lastUpdateFailByCollectionMs[name] = at;
-        globalState.lastGlobalUpdateFailAtMs = at;
-      } else {
-        this._lastUpdateFailAtMs = at;
-        globalState.lastGlobalUpdateFailAtMs = at;
-      }
       const msg = err instanceof Error ? err.message : String(err);
+      // Another qmd process holds the index. Arming the 15-minute failure
+      // backoff would make the next converge attempt fail even after the lock
+      // is gone. A real index failure still backs off.
+      if (!/database is locked|SQLITE_BUSY/i.test(msg)) {
+        const at = Date.now();
+        if (options.perCollectionThrottle) {
+          globalState.lastUpdateFailByCollectionMs[name] = at;
+          globalState.lastGlobalUpdateFailAtMs = at;
+        } else {
+          this._lastUpdateFailAtMs = at;
+          globalState.lastGlobalUpdateFailAtMs = at;
+        }
+      }
       log.warn(`QMD update failed for collection ${name}: ${msg}`);
       if (options.strict) {
         throw err;