simple-dynamsoft-mcp 7.7.1 → 7.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.7.1",
+  "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

@@ -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)) {
@@ -49,20 +49,47 @@ const allHeaders = 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))) {
-    cacheFiles.push(path);
-  } else {
+  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 files with vectors found in ${cacheDir}.`);
 }
 
+// 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 = "";

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();