simple-dynamsoft-mcp 7.7.0 → 7.7.2

package/data/metadata/data-manifest.json

@@ -28,8 +28,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "barcode-reader-docs-server",
-      "commit": "7aa8985f9918460466b3dde1426f5ad1342fa93e",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-server/zip/7aa8985f9918460466b3dde1426f5ad1342fa93e"
+      "commit": "f82b5b92fb039064be3d355f9aeaacf0947b7096",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-server/zip/f82b5b92fb039064be3d355f9aeaacf0947b7096"
     },
     {
       "name": "data/documentation/capture-vision-docs",
@@ -38,8 +38,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "capture-vision-docs",
-      "commit": "f3ddf9614ca3d5f153bdc780cd740732d30d3de9",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs/zip/f3ddf9614ca3d5f153bdc780cd740732d30d3de9"
+      "commit": "428c0080975aee70f15e09deda09ca548a4f9a93",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs/zip/428c0080975aee70f15e09deda09ca548a4f9a93"
     },
     {
       "name": "data/documentation/capture-vision-docs-js",
@@ -68,8 +68,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "capture-vision-docs-server",
-      "commit": "1e7455238c8fe8f935640c1c31c0c433798ce1f0",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs-server/zip/1e7455238c8fe8f935640c1c31c0c433798ce1f0"
+      "commit": "4138672377f9ac99380bc985d28fbbe457c31c2b",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs-server/zip/4138672377f9ac99380bc985d28fbbe457c31c2b"
     },
     {
       "name": "data/documentation/document-viewer-docs",
@@ -108,8 +108,8 @@
       "branch": "master",
       "owner": "dynamsoft-docs",
       "repo": "web-twain-docs",
-      "commit": "3cb367e1e733a6556902f328b6b51fad0280d2b9",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/3cb367e1e733a6556902f328b6b51fad0280d2b9"
+      "commit": "256fe47f8b83c79cbf8f23034fe77eab65a3fc7b",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/256fe47f8b83c79cbf8f23034fe77eab65a3fc7b"
     },
     {
       "name": "data/samples/document-scanner-javascript",
@@ -148,8 +148,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-c-cpp-samples",
-      "commit": "8d4b48cc525d65569ae63c2317c907a06b5e8322",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-c-cpp-samples/zip/8d4b48cc525d65569ae63c2317c907a06b5e8322"
+      "commit": "96e6242b43253a930b1edf6bbe5b0dbcadf1bb5a",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-c-cpp-samples/zip/96e6242b43253a930b1edf6bbe5b0dbcadf1bb5a"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-dotnet",
@@ -158,8 +158,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-dotnet-samples",
-      "commit": "641cdf391b514e67a75f5bb6bc25ace068af8b38",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-dotnet-samples/zip/641cdf391b514e67a75f5bb6bc25ace068af8b38"
+      "commit": "49e205da121046998d8633c80ff2e31d3d3594f3",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-dotnet-samples/zip/49e205da121046998d8633c80ff2e31d3d3594f3"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-flutter",
@@ -178,8 +178,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-java-samples",
-      "commit": "caab3b6c1737f465047f84bbb77f827f19bb8523",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-java-samples/zip/caab3b6c1737f465047f84bbb77f827f19bb8523"
+      "commit": "fbadec4609803fb3ec542b20b630adb99481cfe2",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-java-samples/zip/fbadec4609803fb3ec542b20b630adb99481cfe2"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-maui",
@@ -208,8 +208,8 @@
       "branch": "master",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-python-samples",
-      "commit": "a754aab9e4fb9630519382402f32250c94d8643b",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-python-samples/zip/a754aab9e4fb9630519382402f32250c94d8643b"
+      "commit": "bd63acaaf5d8b427aee7d3d1c8b316dc3021b9f5",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-python-samples/zip/bd63acaaf5d8b427aee7d3d1c8b316dc3021b9f5"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-react-native",
@@ -228,8 +228,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-cpp-samples",
-      "commit": "9bd516bc1961425eed02b2308505a9a6c775b38d",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-cpp-samples/zip/9bd516bc1961425eed02b2308505a9a6c775b38d"
+      "commit": "cfd0fc6f4fee070e188955dd0cccfab39ff2c02d",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-cpp-samples/zip/cfd0fc6f4fee070e188955dd0cccfab39ff2c02d"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-dotnet",
@@ -238,8 +238,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-dotnet-samples",
-      "commit": "871ffea41164e08ed1315157c3feb7912915fa40",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-dotnet-samples/zip/871ffea41164e08ed1315157c3feb7912915fa40"
+      "commit": "f3fe6aecc7c3c628f4241fe3a52ed448680c9d64",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-dotnet-samples/zip/f3fe6aecc7c3c628f4241fe3a52ed448680c9d64"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-flutter",
@@ -258,8 +258,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-java-samples",
-      "commit": "760f9e3f5fed9c74d813ffc30fbcd9a5a96bf576",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-java-samples/zip/760f9e3f5fed9c74d813ffc30fbcd9a5a96bf576"
+      "commit": "83660139a8d32b0b319b6bc0b213b827437ddc43",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-java-samples/zip/83660139a8d32b0b319b6bc0b213b827437ddc43"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-maui",
@@ -298,8 +298,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-python-samples",
-      "commit": "f54b2d281b8325e8765f535be8ef6ebf157f4a54",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-python-samples/zip/f54b2d281b8325e8765f535be8ef6ebf157f4a54"
+      "commit": "6f350f5d68e3ddcd90041bf46cac5541677f04b5",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-python-samples/zip/6f350f5d68e3ddcd90041bf46cac5541677f04b5"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-react-native",

package/data/metadata/dynamsoft_sdks.json

@@ -120,7 +120,7 @@
     "dbr-server": {
       "name": "Dynamsoft Barcode Reader Server/Desktop SDK",
       "description": "Barcode scanning for server/desktop platforms including Python, .NET, Java, C++, and Node.js.",
-      "version": "11.6.4000",
+      "version": "11.6.5000",
       "default_platform": "python",
       "snippet_path": "dynamsoft-barcode-reader/server",
       "platforms": {
@@ -255,7 +255,7 @@
     "dcv-core": {
       "name": "Dynamsoft Capture Vision Core",
       "description": "Unified architecture documentation for Capture Vision capabilities across barcode, MRZ, document normalization, and parsing workflows.",
-      "version": "3.6.4000",
+      "version": "3.6.5000",
       "default_platform": "core",
       "snippet_path": "dynamsoft-capture-vision/core",
       "platforms": {
@@ -270,7 +270,7 @@
     "dcv-server": {
       "name": "Dynamsoft Capture Vision Server/Desktop SDK",
       "description": "Capture Vision workflows for Python, .NET, Java, C++, and Node.js, including MRZ, document normalization, and driver license scenarios.",
-      "version": "3.6.4000",
+      "version": "3.6.5000",
       "default_platform": "python",
       "snippet_path": "dynamsoft-capture-vision/server",
       "platforms": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.7.0",
+  "version": "7.7.2",
   "description": "MCP server for Dynamsoft SDKs - Capture Vision, Barcode Reader (Mobile/Python/Web), Dynamic Web TWAIN, and Document Viewer. Provides documentation, code snippets, and API guidance.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "npm run test:lite",
-    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js test/unit/shared-docs.test.js test/unit/vector-cache.test.js test/unit/doc-slugs.test.js",
+    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js test/unit/shared-docs.test.js test/unit/vector-cache.test.js test/unit/doc-slugs.test.js test/unit/incremental-embedding.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",

package/scripts/prebuild-rag-index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
 function toPosixPath(path) {
@@ -25,7 +25,7 @@ ensureEnvDefaults();
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const { prewarmRagIndex, ragConfig } = await import("../src/rag/index.js");
 
-await prewarmRagIndex();
+await prewarmRagIndex({ throwOnError: true });
 
 const cacheDir = resolve(ragConfig.cacheDir);
 if (!existsSync(cacheDir)) {
@@ -33,8 +33,10 @@ if (!existsSync(cacheDir)) {
 }
 
 // Each cache is a JSON header plus a sibling `.f32` vector file (see
-// src/rag/vector-cache.js); both ship in the release archive.
-const cacheFiles = readdirSync(cacheDir, { withFileTypes: true })
+// src/rag/vector-cache.js); both ship in the release archive. A header with no
+// `.f32` is a pre-7.7 all-JSON cache (e.g. restored from an older CI cache):
+// the runtime cannot load it, so it is deleted rather than shipped.
+const allHeaders = readdirSync(cacheDir, { withFileTypes: true })
   .filter((entry) => entry.isFile())
   .map((entry) => join(cacheDir, entry.name))
   .filter((path) => {
@@ -46,16 +48,50 @@ const cacheFiles = readdirSync(cacheDir, { withFileTypes: true })
   })
   .sort();
 
+const toVectorFile = (path) => path.replace(/\.json$/i, ".f32");
+const readMeta = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")).meta || {};
+  } catch {
+    return {};
+  }
+};
+// The model the build just used; only its cache is shipped.
+const activeModel = ragConfig.provider === "gemini" ? ragConfig.geminiModel : "";
+
+const cacheFiles = [];
+for (const path of allHeaders) {
+  if (!existsSync(toVectorFile(path))) {
+    rmSync(path, { force: true });
+    console.log(`[rag-prebuild] removed legacy cache without vectors: ${basename(path)}`);
+    continue;
+  }
+  const meta = readMeta(path);
+  if (meta.provider === ragConfig.provider && meta.model !== activeModel) {
+    // A seeded index for a previous model (e.g. after a model change). The
+    // build succeeded with the active model, so it is obsolete; never ship it.
+    rmSync(path, { force: true });
+    rmSync(toVectorFile(path), { force: true });
+    console.log(`[rag-prebuild] removed cache for previous model ${meta.model}: ${basename(path)}`);
+    continue;
+  }
+  cacheFiles.push(path);
+}
+
 if (cacheFiles.length === 0) {
-  throw new Error(`No cache JSON files found in ${cacheDir}.`);
+  throw new Error(`No cache files with vectors found in ${cacheDir}.`);
 }
 
-const vectorFiles = cacheFiles.map((path) => path.replace(/\.json$/i, ".f32"));
-const missingVectors = vectorFiles.filter((path) => !existsSync(path));
-if (missingVectors.length > 0) {
-  throw new Error(`Vector files missing for cache headers: ${missingVectors.map((path) => basename(path)).join(", ")}`);
+// A successful build prunes every other cache for its provider/model, so exactly
+// one complete cache for the active model must remain; more means a stale
+// seeded index survived and could be shipped under this version.
+const providerCaches = cacheFiles.filter((path) => readMeta(path).provider === ragConfig.provider);
+if (providerCaches.length !== 1) {
+  throw new Error(`Expected exactly one ${ragConfig.provider} cache for ${activeModel} after the build, found ${providerCaches.length}: ${providerCaches.map((path) => basename(path)).join(", ")}`);
 }
 
+const vectorFiles = cacheFiles.map(toVectorFile);
+
 let indexSignature = "";
 let indexCacheKey = "";
 const geminiCacheFile = cacheFiles.find((path) => /rag-gemini-.*\.json$/i.test(path));

package/scripts/seed-rag-cache.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Seed a RAG cache directory with the vectors from the latest published
+# release, so the next build embeds only chunks whose text changed.
+#
+#   scripts/seed-rag-cache.sh <cache-dir> [release-tag]
+#
+# release-tag: seed from that release instead of the latest one.
+#
+# Needs `gh` with GH_TOKEN. Skips (exit 0) when the directory already holds a
+# vector file or no release asset exists; a seed is an optimization only.
+set -euo pipefail
+
+cache_dir="${1:?usage: seed-rag-cache.sh <cache-dir> [release-tag]}"
+release_tag="${2:-}"
+repo="${GITHUB_REPOSITORY:-yushulx/simple-dynamsoft-mcp}"
+mkdir -p "$cache_dir"
+
+# Only a complete cache (header + vectors) counts; a leftover partial
+# checkpoint from an interrupted run must not block seeding.
+for header in "$cache_dir"/rag-gemini-*.json; do
+  [[ -e "$header" && "$header" != *.checkpoint.json && -f "${header%.json}.f32" ]] || continue
+  echo "[seed] $cache_dir already has a complete cache ($(basename "$header")); not seeding"
+  exit 0
+done
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+if ! gh release download ${release_tag:+"$release_tag"} --repo "$repo" --pattern 'prebuilt-rag-index-gemini-*.tar.gz' --dir "$work" 2>"$work/err.log"; then
+  echo "[seed] no previous release index available: $(tr '\n' ' ' < "$work/err.log")"
+  exit 0
+fi
+
+archive="$(find "$work" -maxdepth 1 -name 'prebuilt-rag-index-gemini-*.tar.gz' | head -n 1)"
+mkdir -p "$work/extract"
+tar -xzf "$archive" -C "$work/extract"
+copied=0
+while IFS= read -r file; do
+  cp "$file" "$cache_dir/"
+  copied=$((copied + 1))
+done < <(find "$work/extract" -type f -name 'rag-gemini-*' ! -name '*.checkpoint.*')
+echo "[seed] copied $copied file(s) from $(basename "$archive") into $cache_dir"

package/src/rag/config.js

@@ -71,6 +71,9 @@ const ragConfig = {
   minScore: readFloatEnv("RAG_MIN_SCORE", 0.2),
   includeScore: readBoolEnv("RAG_INCLUDE_SCORE", false),
   rebuild: readBoolEnv("RAG_REBUILD", false),
+  // Upper bound on chunks one build may embed (0 = no limit). CI sets it so a
+  // missing seed or an unexpected change cannot trigger a full paid re-embed.
+  maxEmbedChunks: readIntEnv("RAG_MAX_EMBED_CHUNKS", 0),
   prewarm: readBoolEnv("RAG_PREWARM", defaultPrewarm),
   prewarmBlock: readBoolEnv("RAG_PREWARM_BLOCK", false),
   prebuiltIndexAutoDownload: readBoolEnv("RAG_PREBUILT_INDEX_AUTO_DOWNLOAD", true),

package/src/rag/index.js

@@ -215,7 +215,9 @@ async function searchResources({ query, product, edition, platform, type, limit,
   return [];
 }
 
-async function prewarmRagIndex() {
+// `throwOnError` rethrows build failures; the prebuild script uses it so a
+// failed build cannot publish whatever older index is in the cache dir.
+async function prewarmRagIndex({ throwOnError = false } = {}) {
   if (!ragConfig.prewarm) return;
   logRagConfigOnce(ragConfig);
   const providers = providerOrchestrator.resolveProviderChain();
@@ -245,6 +247,7 @@ async function prewarmRagIndex() {
       provider: primary,
       error: error.message
     }, { level: "error" });
+    if (throwOnError) throw error;
   }
 }
 

package/src/rag/providers.js

@@ -275,12 +275,6 @@ function createProviderOrchestrator({
     const cacheKey = createHash("sha256").update(JSON.stringify(cacheMeta)).digest("hex");
     const cacheFile = join(ragConfig.cacheDir, vectorCache.makeCacheFileName(name, model, cacheKey));
     const checkpointFile = join(ragConfig.cacheDir, vectorCache.makeCheckpointFileName(name, model, cacheKey));
-    const expectedCacheState = {
-      cacheKey,
-      signature,
-      provider: name,
-      model
-    };
     logRag(
       `provider=${name} cache_file=${cacheFile} rebuild=${ragConfig.rebuild} cache_key=${cacheKey.slice(0, 12)}`
     );
@@ -289,103 +283,110 @@ function createProviderOrchestrator({
     const loadIndex = async () => {
       if (indexPromise) return indexPromise;
       indexPromise = (async () => {
-        if (!ragConfig.rebuild) {
-          let cacheState = vectorCache.loadVectorIndexCache(cacheFile, expectedCacheState);
-          if (cacheState.hit) {
-            const cached = cacheState.payload;
-            logRag(
-              `cache hit provider=${name} file=${cacheFile} items=${cached.items.length} vectors=${cached.vectors.length}`
-            );
-            return {
-              items: cached.items,
-              vectors: cached.vectors
-            };
-          }
-          logRag(`cache miss provider=${name} file=${cacheFile} reason=${cacheState.reason}`);
+        // Every load goes through chunk-hash validation: a cache file is
+        // trusted only for chunks whose text hash still matches, never because
+        // its signature or filename matches.
+        if (ragConfig.rebuild) {
+          logRag(`cache bypass provider=${name} file=${cacheFile} reason=rebuild_true`);
+          vectorCache.clearVectorIndexCheckpoint(checkpointFile);
+        }
 
-          const downloadResult = await vectorCache.maybeDownloadPrebuiltVectorIndex({
+        const items = utils.buildEmbeddingItems(resourceIndex, ragConfig);
+        // Each chunk is identified by a hash of model + text, so vectors from any
+        // earlier cache, checkpoint, or release can be reused for unchanged text
+        // and only new or edited chunks are embedded.
+        const indexedItems = items.map((item) => ({
+          id: item.id,
+          uri: item.uri,
+          hash: createHash("sha256").update(`${model}\n${item.text}`).digest("hex").slice(0, 32)
+        }));
+        const checkpointHashes = new Set();
+        const collect = () => (ragConfig.rebuild
+          ? new Map()
+          : vectorCache.collectReusableVectors({ provider: name, model, checkpointHashes }));
+        let reusable = collect();
+        // Local caches do not cover every chunk (e.g. an older release's index
+        // after an upgrade): try this release's prebuilt index before paying to
+        // embed, then re-collect.
+        if (!ragConfig.rebuild && indexedItems.some((item) => !reusable.has(item.hash))) {
+          const download = await vectorCache.maybeDownloadPrebuiltVectorIndex({
             provider: name,
             model,
             cacheKey,
             signature,
             cacheFile
           });
-          if (downloadResult.downloaded) {
-            cacheState = vectorCache.loadVectorIndexCache(cacheFile, expectedCacheState);
-            if (cacheState.hit) {
-              const cached = cacheState.payload;
-              logRag(
-                `cache hit provider=${name} file=${cacheFile} source=prebuilt_download items=${cached.items.length} vectors=${cached.vectors.length}`
-              );
-              return {
-                items: cached.items,
-                vectors: cached.vectors
-              };
-            }
-            logRag(`cache miss provider=${name} file=${cacheFile} source=prebuilt_download reason=${cacheState.reason}`);
-          }
-        } else {
-          logRag(`cache bypass provider=${name} file=${cacheFile} reason=rebuild_true`);
-          vectorCache.clearVectorIndexCheckpoint(checkpointFile);
+          if (download.downloaded) reusable = collect();
+        }
+        const vectors = indexedItems.map((item) => reusable.get(item.hash) || null);
+        const missing = [];
+        vectors.forEach((vector, index) => {
+          if (!vector) missing.push(index);
+        });
+        logRag(
+          `index plan provider=${name} items=${indexedItems.length} reused=${indexedItems.length - missing.length} to_embed=${missing.length}`
+        );
+        if (ragConfig.maxEmbedChunks > 0 && missing.length > ragConfig.maxEmbedChunks) {
+          throw new Error(
+            `Refusing to embed ${missing.length} chunks (RAG_MAX_EMBED_CHUNKS=${ragConfig.maxEmbedChunks}); ` +
+            `only ${indexedItems.length - missing.length}/${indexedItems.length} could be reused. ` +
+            "Check that the cache was seeded from a matching release index."
+          );
         }
 
-        const items = utils.buildEmbeddingItems(resourceIndex, ragConfig);
-        const texts = items.map((item) => item.text);
-        const indexedItems = items.map((item) => ({ id: item.id, uri: item.uri }));
-        let normalized = [];
-        let resumeFrom = 0;
-        if (!ragConfig.rebuild) {
-          const checkpointState = vectorCache.loadVectorIndexCheckpoint(checkpointFile, cacheKey, indexedItems);
-          if (checkpointState.hit) {
-            normalized = checkpointState.payload.vectors;
-            resumeFrom = normalized.length;
-            logRag(
-              `checkpoint resume provider=${name} file=${checkpointFile} completed=${resumeFrom}/${texts.length}`
-            );
-          } else if (checkpointState.reason !== "missing") {
-            logRag(`checkpoint ignored provider=${name} file=${checkpointFile} reason=${checkpointState.reason}`);
-          }
+        if (missing.length === 0 && vectorCache.cacheHeaderMatches({ cacheFile, provider: name, model, items: indexedItems })) {
+          vectorCache.clearVectorIndexCheckpoint(checkpointFile);
+          vectorCache.pruneOtherCaches({ provider: name, model, keepFile: cacheFile });
+          logRag(`cache hit provider=${name} file=${cacheFile} items=${indexedItems.length}`);
+          return { items: indexedItems, vectors };
         }
 
         if (name === "gemini" && embedder.resetMetrics) {
           embedder.resetMetrics();
         }
 
+        // The checkpoint keeps every vector this build had to produce: newly
+        // embedded ones plus those recovered from an earlier checkpoint, so a
+        // second interruption does not lose the first attempt's progress.
+        const missingSet = new Set(missing);
+        const checkpointIndices = indexedItems
+          .map((item, index) => index)
+          .filter((index) => missingSet.has(index) || checkpointHashes.has(indexedItems[index].hash));
         const checkpointIntervalMs = 5000;
         let lastCheckpointAt = 0;
         const persistCheckpoint = (force = false) => {
           const now = Date.now();
           if (!force && now - lastCheckpointAt < checkpointIntervalMs) return;
-          const payload = {
+          const done = checkpointIndices.filter((index) => vectors[index]);
+          vectorCache.saveVectorIndexCheckpoint(checkpointFile, {
             cacheKey,
             meta: cacheMeta,
-            items: indexedItems,
-            vectors: normalized,
-            completed: normalized.length,
-            total: texts.length,
+            items: done.map((index) => indexedItems[index]),
+            vectors: done.map((index) => vectors[index]),
             updatedAt: new Date().toISOString()
-          };
-          vectorCache.saveVectorIndexCheckpoint(checkpointFile, payload);
+          });
           lastCheckpointAt = now;
         };
 
-        if (resumeFrom < texts.length) {
-          logRag(
-            `building index provider=${name} embed_items=${texts.length} remaining=${texts.length - resumeFrom} batch_size=${batchSize}`
-          );
+        if (missing.length > 0) {
+          logRag(`building index provider=${name} embed_items=${missing.length} batch_size=${batchSize}`);
+          let filled = 0;
           try {
             const embeddingResult = await embedTextsWithProgress(
-              texts.slice(resumeFrom),
+              missing.map((index) => items[index].text),
               embedder,
               batchSize,
               {
-                offset: resumeFrom,
-                total: texts.length,
+                offset: 0,
+                total: missing.length,
                 providerName: name,
                 logRag,
                 isRateLimitError: (error) => utils.isRateLimitError(error, isRateLimitGeminiStatus),
-                onChunk: ({ vectors, completed, total }) => {
-                  normalized.push(...vectors.map(utils.normalizeVector));
+                onChunk: ({ vectors: chunk, completed, total }) => {
+                  for (const vector of chunk) {
+                    vectors[missing[filled]] = utils.normalizeVector(vector);
+                    filled += 1;
+                  }
                   persistCheckpoint(completed >= total);
                 }
               }
@@ -409,24 +410,25 @@ function createProviderOrchestrator({
                 `gemini build failed provider=${name} requests=${metrics.requests || 0} retries=${metrics.retries || 0} ` +
                 `retry_delay_ms=${metrics.retryDelayMs || 0} throttle_events=${metrics.throttleEvents || 0} ` +
                 `throttle_delay_ms=${metrics.throttleDelayMs || 0} rate_limit_retries=${metrics.rateLimitRetries || 0} ` +
-                `checkpoint_completed=${normalized.length}/${texts.length} error=${error.message}`
+                `checkpoint_completed=${filled}/${missing.length} error=${error.message}`
               );
             }
             throw error;
           }
-        } else {
-          logRag(`checkpoint already complete provider=${name} completed=${resumeFrom}/${texts.length}`);
         }
 
         const payload = {
           cacheKey,
           meta: cacheMeta,
           items: indexedItems,
-          vectors: normalized
+          vectors
         };
         vectorCache.saveVectorIndexCache(cacheFile, payload);
         vectorCache.clearVectorIndexCheckpoint(checkpointFile);
-        logRag(`cache saved provider=${name} file=${cacheFile} items=${payload.items.length} vectors=${payload.vectors.length}`);
+        vectorCache.pruneOtherCaches({ provider: name, model, keepFile: cacheFile });
+        logRag(
+          `cache saved provider=${name} file=${cacheFile} items=${payload.items.length} embedded=${missing.length}`
+        );
         return {
           items: payload.items,
           vectors: payload.vectors

package/src/rag/vector-cache.js

@@ -10,14 +10,100 @@ function ensureDirectory(path) {
   }
 }
 
-function makeCacheFileName(provider, model, cacheKey) {
+function cacheFilePrefix(provider, model) {
   const safeModel = String(model || "default").replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 32);
-  return `rag-${provider}-${safeModel}-${cacheKey.slice(0, 12)}.json`;
+  return `rag-${provider}-${safeModel}-`;
+}
+
+function makeCacheFileName(provider, model, cacheKey) {
+  return `${cacheFilePrefix(provider, model)}${cacheKey.slice(0, 12)}.json`;
 }
 
 function makeCheckpointFileName(provider, model, cacheKey) {
-  const safeModel = String(model || "default").replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 32);
-  return `rag-${provider}-${safeModel}-${cacheKey.slice(0, 12)}.checkpoint.json`;
+  return `${cacheFilePrefix(provider, model)}${cacheKey.slice(0, 12)}.checkpoint.json`;
+}
+
+// Header metadata only (no vectors). Returns null when unreadable.
+function readHeader(headerFile) {
+  try {
+    return JSON.parse(readFileSync(headerFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function headerBelongsTo(header, provider, model) {
+  return header?.meta?.provider === provider && header?.meta?.model === model;
+}
+
+// Cache and checkpoint headers whose stored provider and model match exactly.
+// The filename prefix only narrows the search: sanitized/truncated model names
+// can share a prefix (`m` vs `m-other`).
+function listProviderCacheHeaders(cacheDir, provider, model) {
+  if (!existsSync(cacheDir)) return [];
+  const prefix = cacheFilePrefix(provider, model);
+  return readdirSync(cacheDir)
+    .filter((name) => name.startsWith(prefix) && name.endsWith(".json"))
+    .map((name) => join(cacheDir, name))
+    .filter((path) => headerBelongsTo(readHeader(path), provider, model));
+}
+
+function isCheckpointHeader(path) {
+  return path.endsWith(".checkpoint.json");
+}
+
+// True when `cacheFile` already holds exactly these items (same order and
+// chunk hashes) with a correctly sized vector file, so a build that embeds
+// nothing does not need to rewrite it.
+function cacheHeaderMatches({ cacheFile, provider, model, items }) {
+  const header = readHeader(cacheFile);
+  if (!header || !headerBelongsTo(header, provider, model) || header.vectorFormat !== VECTOR_FORMAT) return false;
+  if (!Array.isArray(header.items) || header.items.length !== items.length || header.vectorCount !== items.length) return false;
+  if (!header.items.every((item, i) => item.hash && item.hash === items[i].hash && item.id === items[i].id && item.uri === items[i].uri)) {
+    return false;
+  }
+  const vectorFile = vectorFileFor(cacheFile);
+  return existsSync(vectorFile)
+    && statSync(vectorFile).size === header.vectorCount * header.dimensions * Float32Array.BYTES_PER_ELEMENT;
+}
+
+
+// Vectors already computed for identical chunk text, keyed by item `hash`
+// (see providers.js). Sources are every cache and checkpoint for the same
+// provider/model in cacheDir: a previous version's cache, an extracted
+// previous release, or a partial checkpoint. Only caches whose items carry
+// chunk-text hashes are used; older hash-less caches cannot prove their text
+// is unchanged, so they are ignored.
+// `checkpointHashes` (optional Set) receives the hashes found in checkpoints,
+// so a resumed build can carry them into its own checkpoint.
+function collectReusableVectors({ cacheDir, provider, model, checkpointHashes }) {
+  const reusable = new Map();
+  for (const headerFile of listProviderCacheHeaders(cacheDir, provider, model)) {
+    let payload;
+    try {
+      const result = readVectorFiles(headerFile);
+      if (result.error) continue;
+      payload = result.payload;
+    } catch {
+      continue;
+    }
+    if (!payload.items.every((item) => item.hash)) continue;
+    const fromCheckpoint = isCheckpointHeader(headerFile);
+    payload.items.forEach((item, i) => {
+      if (!payload.vectors[i]) return;
+      if (fromCheckpoint) checkpointHashes?.add(item.hash);
+      if (!reusable.has(item.hash)) reusable.set(item.hash, payload.vectors[i]);
+    });
+  }
+  return reusable;
+}
+
+// Keep only `keepFile` (and its vectors) among this provider/model's caches,
+// so restored/seeded caches do not accumulate in CI caches or release assets.
+function pruneOtherCaches({ cacheDir, provider, model, keepFile }) {
+  for (const headerFile of listProviderCacheHeaders(cacheDir, provider, model)) {
+    if (resolve(headerFile) !== resolve(keepFile)) removeVectorFiles(headerFile);
+  }
 }
 
 // Cache layout: a JSON header (`<name>.json`: cacheKey, meta, items, vector
@@ -126,35 +212,8 @@ function saveVectorIndexCache(cacheDir, cacheFile, payload) {
   writeVectorFiles(cacheFile, payload);
 }
 
-function loadVectorIndexCheckpoint(checkpointFile, expectedKey, expectedItems) {
-  if (!existsSync(checkpointFile)) {
-    return { hit: false, reason: "missing", payload: null };
-  }
-  try {
-    const { payload: parsed, error } = readVectorFiles(checkpointFile);
-    if (error) {
-      return { hit: false, reason: error, payload: null };
-    }
-    if (parsed.cacheKey !== expectedKey) {
-      return { hit: false, reason: "cache_key_mismatch", payload: null };
-    }
-    if (parsed.items.length !== expectedItems.length) {
-      return { hit: false, reason: "items_length_mismatch", payload: null };
-    }
-    for (let i = 0; i < expectedItems.length; i += 1) {
-      if (parsed.items[i]?.id !== expectedItems[i]?.id || parsed.items[i]?.uri !== expectedItems[i]?.uri) {
-        return { hit: false, reason: "items_mismatch", payload: null };
-      }
-    }
-    if (parsed.vectors.length > expectedItems.length) {
-      return { hit: false, reason: "vectors_overflow", payload: null };
-    }
-    return { hit: true, reason: "ok", payload: parsed };
-  } catch {
-    return { hit: false, reason: "parse_error", payload: null };
-  }
-}
-
+// Checkpoints hold only the items embedded so far (each with its `hash`);
+// collectReusableVectors picks them up on the next attempt.
 function saveVectorIndexCheckpoint(cacheDir, checkpointFile, payload) {
   ensureDirectory(cacheDir);
   writeVectorFiles(checkpointFile, payload);
@@ -332,21 +391,18 @@ function createVectorCacheHelpers({ ragConfig, pkgVersion, legacyPrebuiltIndexUr
               continue;
             }
 
-            const migratedPayload = {
-              ...candidateCache.payload,
-              cacheKey,
-              meta: {
-                ...(candidateCache.payload.meta || {}),
-                provider,
-                model,
-                signature
-              }
-            };
-            saveVectorIndexCache(ragConfig.cacheDir, cacheFile, migratedPayload);
+            // Install unchanged (own cacheKey and signature) under a separate
+            // name, so a local cache with the same name (and vectors for local
+            // edits) is not overwritten. The build reuses only vectors whose
+            // chunk-text hash matches, then prunes this extra copy.
+            ensureDirectory(ragConfig.cacheDir);
+            const installedFile = join(ragConfig.cacheDir, basename(sourceCacheFile).replace(/\.json$/i, "-prebuilt.json"));
+            copyFileSync(sourceCacheFile, installedFile);
+            copyFileSync(vectorFileFor(sourceCacheFile), vectorFileFor(installedFile));
             logRag(
-              `prebuilt index installed provider=${provider} cache_file=${cacheFile} source=${basename(sourceCacheFile)} mode=version_only_compat version=${cachePackageVersion}`
+              `prebuilt index installed provider=${provider} cache_file=${installedFile} version=${cachePackageVersion}`
             );
-            return { downloaded: true, reason: "installed_version_only_compat" };
+            return { downloaded: true, reason: "installed" };
           }
 
           throw new Error(
@@ -371,9 +427,11 @@ function createVectorCacheHelpers({ ragConfig, pkgVersion, legacyPrebuiltIndexUr
     makeCheckpointFileName,
     loadVectorIndexCache,
     saveVectorIndexCache: (cacheFile, payload) => saveVectorIndexCache(ragConfig.cacheDir, cacheFile, payload),
-    loadVectorIndexCheckpoint,
     saveVectorIndexCheckpoint: (checkpointFile, payload) => saveVectorIndexCheckpoint(ragConfig.cacheDir, checkpointFile, payload),
     clearVectorIndexCheckpoint,
+    collectReusableVectors: (options) => collectReusableVectors({ cacheDir: ragConfig.cacheDir, ...options }),
+    cacheHeaderMatches,
+    pruneOtherCaches: (options) => pruneOtherCaches({ cacheDir: ragConfig.cacheDir, ...options }),
     maybeDownloadPrebuiltVectorIndex
   };
 }

package/src/server/resource-index.js

@@ -84,7 +84,11 @@ import {
 } from "./resource-index/builders.js";
 
 const registry = JSON.parse(readFileSync(registryPath, "utf8"));
-const registrySha256 = createHash("sha256").update(readFileSync(registryPath)).digest("hex");
+// Hash LF-normalized text so Windows (CRLF) and Linux checkouts of the same
+// registry produce the same RAG index signature.
+const registrySha256 = createHash("sha256")
+  .update(readFileSync(registryPath, "utf8").replace(/\r\n/g, "\n"))
+  .digest("hex");
 
 function inferDbrMobilePlatform(articlePath) {
   const normalized = String(articlePath || "").replace(/\\/g, "/").toLowerCase();