simple-dynamsoft-mcp 7.3.54 → 7.4.1

package/data/metadata/data-manifest.json

@@ -108,8 +108,8 @@
       "branch": "master",
       "owner": "dynamsoft-docs",
       "repo": "web-twain-docs",
-      "commit": "973216bc5f9c5152664882c3ceb11679b74878ef",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/973216bc5f9c5152664882c3ceb11679b74878ef"
+      "commit": "84c36dde107cba2d80ed3ee7c42ab232c7434de2",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/84c36dde107cba2d80ed3ee7c42ab232c7434de2"
     },
     {
       "name": "data/samples/document-scanner-javascript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.3.54",
+  "version": "7.4.1",
   "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,13 +24,15 @@
   "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/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": "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/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: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",
     "test:stdio": "node --test test/integration/stdio.test.js",
     "test:http": "node --test test/integration/http.test.js",
     "test:package": "node --test test/integration/package-runtime.test.js",
+    "test:contract": "node --test test/contract/contract.test.js",
+    "check:version-drift": "node scripts/check-version-drift.mjs",
     "test:lazy": "node --test test/integration/lazy-hydration.test.js",
     "test:regression:unit": "node --test test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/profile-config.test.js test/unit/hydration-mode.test.js test/unit/logging.test.js",
     "test:regression:integration": "node --test test/integration/package-runtime.test.js test/integration/lazy-hydration.test.js",

package/scripts/check-version-drift.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Version-drift check (issue #158): compare the SDK versions the server advertises
+// (data/metadata/dynamsoft_sdks.json) against versions pinned inside served
+// samples (gradle bundles, npm deps, CDN URLs). Report-only by default — prints a
+// table and exits 1 when drift is found so CI can flag it.
+//
+// Usage: node scripts/check-version-drift.mjs [--data-dir <path>] (default: ./data or $MCP_DATA_DIR)
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+const dirFlagIdx = args.indexOf("--data-dir");
+const dataDir = dirFlagIdx !== -1 ? args[dirFlagIdx + 1] : (process.env.MCP_DATA_DIR || join(process.cwd(), "data"));
+
+const manifestPath = join(dataDir, "metadata", "dynamsoft_sdks.json");
+if (!existsSync(manifestPath)) {
+  console.error(`No SDK manifest at ${manifestPath}. Pass --data-dir or set MCP_DATA_DIR.`);
+  process.exit(2);
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+// Collect advertised versions (any "version": "x.y.z" under the sdk registry).
+const advertised = new Set();
+function collectVersions(obj) {
+  if (!obj || typeof obj !== "object") return;
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === "version" && typeof v === "string") advertised.add(v);
+    else if (typeof v === "object") collectVersions(v);
+  }
+}
+collectVersions(manifest);
+
+const PIN_PATTERNS = [
+  /barcodereaderbundle:(\d+\.\d+\.\d+)/g,
+  /dynamsoft-[a-z-]+["']?\s*:\s*["']\^?(\d+\.\d+\.\d+)/g,
+  /@dynamsoft\/[a-z-]+@(\d+\.\d+\.\d+)/g,
+  /capture-vision-bundle@(\d+\.\d+\.\d+)/g
+];
+
+const samplesDir = join(dataDir, "samples");
+const pinned = new Map(); // version -> example file
+
+function walk(dir, depth) {
+  if (depth > 6 || !existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || ["node_modules", "build", "Pods"].includes(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, depth + 1);
+    } else if (/\.(gradle|json|html|md|xml|podspec|txt)$/.test(entry.name)) {
+      let content = "";
+      try { content = readFileSync(full, "utf8"); } catch { continue; }
+      for (const re of PIN_PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+          if (!pinned.has(m[1])) pinned.set(m[1], full.replace(dataDir, "."));
+        }
+      }
+    }
+  }
+}
+
+if (existsSync(samplesDir)) walk(samplesDir, 0);
+
+const drift = [...pinned.entries()].filter(([ver]) => !advertised.has(ver));
+
+console.log("Advertised SDK versions:", [...advertised].sort().join(", ") || "(none)");
+console.log("\nPinned versions found in samples:");
+for (const [ver, file] of [...pinned.entries()].sort()) {
+  const mark = advertised.has(ver) ? "ok " : "DRIFT";
+  console.log(`  [${mark}] ${ver}  e.g. ${file}`);
+}
+
+if (drift.length) {
+  console.log(`\n${drift.length} pinned version(s) not in the advertised set (possible drift).`);
+  process.exit(1);
+}
+console.log("\nNo version drift detected.");

package/src/rag/config.js

@@ -63,6 +63,11 @@ const ragConfig = {
   modelCacheDir: readEnvValue("RAG_MODEL_CACHE_DIR", join(dataRoot, ".rag-cache", "models")),
   chunkSize: readIntEnv("RAG_CHUNK_SIZE", 1200),
   chunkOverlap: readIntEnv("RAG_CHUNK_OVERLAP", 200),
+  // Keep the total embedded-chunk count within V8's ~512MB max-string limit,
+  // which the prebuilt Gemini cache hits via a single JSON.stringify of ~3072-dim
+  // vectors. At 24 the release prebuild overflowed ("Invalid string length"); 6 is
+  // the count the pre-v7.4 release built successfully on this data. Raising this
+  // needs the ceiling-proof cache format tracked in the v7.5 follow-ups.
   maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 6),
   maxTextChars: readIntEnv("RAG_MAX_TEXT_CHARS", 4000),
   minScore: readFloatEnv("RAG_MIN_SCORE", 0.2),

package/src/rag/index.js

@@ -28,7 +28,9 @@ import {
   buildIndexSignature,
   normalizeVector,
   dotProduct,
-  isRateLimitError
+  isRateLimitError,
+  expandQueryTokens,
+  extractSnippet
 } from "./search-utils.js";
 import { createProviderOrchestrator } from "./providers.js";
 import { createVectorCacheHelpers } from "./vector-cache.js";
@@ -43,6 +45,8 @@ const searchUtils = {
   normalizeVector,
   dotProduct,
   isRateLimitError,
+  expandQueryTokens,
+  extractSnippet,
   entryMatchesScope: (entry, filters) => entryMatchesScope(entry, filters, {
     editionMatches,
     platformMatches

package/src/rag/lexical-provider.js

@@ -1,12 +1,38 @@
 import Fuse from "fuse.js";
+import { expandQueryTokens, extractSnippet } from "./search-utils.js";
 
 const DEFAULT_FUSE_OPTIONS = {
-  keys: ["title", "summary", "tags", "uri"],
+  keys: [
+    { name: "title", weight: 3 },
+    { name: "tags", weight: 2 },
+    { name: "summary", weight: 1 }
+  ],
   threshold: 0.35,
   ignoreLocation: true,
   includeScore: true
 };
 
+const BODY_INDEX_CHARS = 4000;
+
+// Field-weighted BM25 haystack: title/tags outrank summary; doc/sample body text
+// is indexed at low weight so body-only content is findable; the URI's last slug
+// segment is kept (it is often the most descriptive token) while scheme/version
+// noise is dropped (issue #147).
+function buildLexicalHaystack(entry) {
+  const title = entry.title || "";
+  const tags = Array.isArray(entry.tags) ? entry.tags.join(" ") : "";
+  const summary = entry.summary || "";
+  const body = entry.embedText ? String(entry.embedText).slice(0, BODY_INDEX_CHARS) : "";
+  const uriSlug = String(entry.uri || "").split("/").filter(Boolean).pop() || "";
+  return [
+    title, title, title,
+    tags, tags,
+    summary,
+    uriSlug,
+    body
+  ].join(" \n ");
+}
+
 const BM25_K1 = 1.2;
 const BM25_B = 0.75;
 
@@ -41,12 +67,7 @@ function buildBm25Index(entries) {
   let totalLength = 0;
 
   entries.forEach((entry, index) => {
-    const haystack = [
-      entry.title,
-      entry.summary,
-      Array.isArray(entry.tags) ? entry.tags.join(" ") : "",
-      entry.uri
-    ].join(" \n ");
+    const haystack = buildLexicalHaystack(entry);
 
     const tokens = tokenize(haystack);
     const termFreq = new Map();
@@ -66,7 +87,8 @@ function buildBm25Index(entries) {
       index,
       entry,
       length: tokens.length,
-      termFreq
+      termFreq,
+      snippetText: entry.embedText || entry.summary || entry.title || ""
     });
   });
 
@@ -107,33 +129,40 @@ function createLexicalProvider({
   const fuse = new Fuse(entries, fuseOptions);
   const bm25Index = buildBm25Index(entries);
   const entryByUri = new Map(entries.map((entry) => [entry.uri, entry]));
+  const snippetTextByUri = new Map(bm25Index.documents.map((doc) => [doc.entry.uri, doc.snippetText]));
 
   return {
     name: "lexical",
     search: async (query, filters, limit) => {
-      const terms = [...new Set(tokenize(query))];
+      // Expand with domain synonyms/stems so vocabulary gaps (webcam/camera,
+      // datamatrix/data matrix, scanning/scan) do not zero the BM25 component.
+      const terms = expandQueryTokens([...new Set(tokenize(query))]);
       const fuseHits = fuse.search(query);
       const fuseScoreByUri = new Map();
-      let maxFuse = 0;
 
       for (const hit of fuseHits) {
         const candidateScore = Number.isFinite(hit.score) ? Math.max(0, 1 - hit.score) : 0;
         const current = fuseScoreByUri.get(hit.item.uri) || 0;
         if (candidateScore > current) {
           fuseScoreByUri.set(hit.item.uri, candidateScore);
-          if (candidateScore > maxFuse) maxFuse = candidateScore;
         }
       }
 
       const bm25ScoreByUri = new Map();
       let maxBm25 = 0;
+      // Compute maxFuse over IN-SCOPE hits only. Computing it over all hits let an
+      // out-of-scope fuzzy match deflate every in-scope fuse contribution (issue #147).
+      let maxFuse = 0;
 
       for (const doc of bm25Index.documents) {
         if (!entryMatchesScope(doc.entry, filters)) continue;
         const score = computeBm25Score(bm25Index, doc, terms);
-        if (score <= 0) continue;
-        bm25ScoreByUri.set(doc.entry.uri, score);
-        if (score > maxBm25) maxBm25 = score;
+        if (score > 0) {
+          bm25ScoreByUri.set(doc.entry.uri, score);
+          if (score > maxBm25) maxBm25 = score;
+        }
+        const fuseScore = fuseScoreByUri.get(doc.entry.uri) || 0;
+        if (fuseScore > maxFuse) maxFuse = fuseScore;
       }
 
       const scopedUris = new Set();
@@ -155,7 +184,11 @@ function createLexicalProvider({
       }
 
       merged.sort(compareLexicalResults);
-      const ranked = merged.map((item) => attachScore(item.entry, item.score));
+      const ranked = merged.map((item) => {
+        const scored = attachScore(item.entry, item.score);
+        const snippet = extractSnippet(snippetTextByUri.get(item.entry.uri) || "", terms);
+        return snippet ? { ...scored, matchedSnippet: snippet } : scored;
+      });
       if (limit) return ranked.slice(0, limit);
       return ranked;
     },

package/src/rag/providers.js

@@ -438,8 +438,16 @@ function createProviderOrchestrator({
     return {
       name,
       search: async (query, filters, limit) => {
-        const prepared = utils.truncateText(utils.normalizeText(query), ragConfig.maxTextChars);
-        if (!prepared) return [];
+        const baseQuery = utils.normalizeText(query);
+        if (!baseQuery) return [];
+        // Lightly append domain synonyms/stems so jargon-heavy queries embed with
+        // the vocabulary the docs use, without letting expansion dominate the
+        // original query (which stays first). (#148)
+        const expanded = utils.expandQueryTokens ? utils.expandQueryTokens(baseQuery.toLowerCase().split(/\s+/)) : [];
+        const baseTokens = new Set(baseQuery.toLowerCase().split(/\s+/));
+        const extraTerms = expanded.filter((t) => !baseTokens.has(t)).slice(0, 8);
+        const enriched = extraTerms.length ? `${baseQuery} ${extraTerms.join(" ")}` : baseQuery;
+        const prepared = utils.truncateText(enriched, ragConfig.maxTextChars);
         const index = await loadIndex();
         const queryVector = utils.normalizeVector(await embedder.embed(prepared));
         const bestByUri = new Map();
@@ -452,13 +460,26 @@ function createProviderOrchestrator({
           if (!entry || !utils.entryMatchesScope(entry, filters)) continue;
           const existing = bestByUri.get(item.uri);
           if (!existing || score > existing.score) {
-            bestByUri.set(item.uri, { entry, score });
+            bestByUri.set(item.uri, { entry, score, chunkText: item.text });
           }
         }
 
-        const results = Array.from(bestByUri.values())
-          .sort((a, b) => b.score - a.score)
-          .map((item) => utils.attachScore(item.entry, item.score));
+        const ordered = Array.from(bestByUri.values()).sort((a, b) => b.score - a.score);
+        // Relative cutoff: once we have a confident top hit, drop tail results
+        // scoring far below it (the fixed absolute floor above is a near no-op for
+        // normalized Gemini embeddings). (#149)
+        const topScore = ordered.length ? ordered[0].score : 0;
+        // When the top score is non-positive (only reachable with RAG_MIN_SCORE=0
+        // and unrelated content), keep everything rather than dropping the top hit.
+        const relativeFloor = topScore > 0 ? topScore * 0.85 : -Infinity;
+        const kept = ordered.filter((item) => item.score >= relativeFloor);
+
+        const snippetTerms = baseQuery.toLowerCase().split(/\s+/).filter(Boolean);
+        const results = kept.map((item) => {
+          const scored = utils.attachScore(item.entry, item.score);
+          const snippet = utils.extractSnippet ? utils.extractSnippet(item.chunkText || "", snippetTerms, 240) : "";
+          return snippet ? { ...scored, matchedSnippet: snippet } : scored;
+        });
 
         if (limit) return results.slice(0, limit);
         return results;

package/src/rag/search-utils.js

@@ -2,7 +2,11 @@ import Fuse from "fuse.js";
 
 function createFuseSearch(resourceIndex) {
   return new Fuse(resourceIndex, {
-    keys: ["title", "summary", "tags", "uri"],
+    keys: [
+      { name: "title", weight: 3 },
+      { name: "tags", weight: 2 },
+      { name: "summary", weight: 1 }
+    ],
     threshold: 0.35,
     ignoreLocation: true,
     includeScore: true
@@ -62,6 +66,135 @@ function chunkText(text, chunkSize, chunkOverlap, maxChunks) {
   return chunks;
 }
 
+// Heading-aware chunking: split a markdown doc on ATX headings, prepend the
+// nearest heading path to each section, then size-bound sections into chunks so
+// the whole document is covered (not just its first ~6k chars) and each chunk
+// keeps section context (issue #149).
+function chunkMarkdown(text, chunkSize, chunkOverlap, maxChunks) {
+  const raw = String(text || "");
+  if (!raw.trim()) return [];
+  const lines = raw.split(/\r?\n/);
+  const headingStack = [];
+  const sections = [];
+  let current = { path: "", lines: [] };
+
+  const flush = () => {
+    const body = current.lines.join(" ").replace(/\s+/g, " ").trim();
+    if (body) sections.push({ path: current.path, body });
+  };
+
+  let inFence = false;
+  for (const line of lines) {
+    // Track fenced code blocks so a `# ` comment inside Python/bash/YAML is not
+    // mistaken for a markdown heading (which would fragment the code and hijack
+    // the heading breadcrumb for following prose).
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      current.lines.push(line);
+      continue;
+    }
+    const heading = inFence ? null : line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      flush();
+      const level = heading[1].length;
+      const title = heading[2].replace(/\s+/g, " ").trim();
+      while (headingStack.length && headingStack[headingStack.length - 1].level >= level) {
+        headingStack.pop();
+      }
+      headingStack.push({ level, title });
+      current = { path: headingStack.map((h) => h.title).join(" > "), lines: [] };
+    } else {
+      current.lines.push(line);
+    }
+  }
+  flush();
+
+  if (sections.length === 0) {
+    return chunkText(raw, chunkSize, chunkOverlap, maxChunks);
+  }
+
+  const chunks = [];
+  for (const section of sections) {
+    const prefix = section.path ? `${section.path}\n` : "";
+    const pieces = chunkText(section.body, chunkSize, chunkOverlap, maxChunks);
+    for (const piece of pieces) {
+      chunks.push(`${prefix}${piece}`.trim());
+      if (maxChunks && chunks.length >= maxChunks) return chunks;
+    }
+  }
+  return chunks;
+}
+
+// Domain synonym / jargon expansion so lexical scoring survives the vocabulary
+// gap between how developers phrase questions and how docs/samples are titled
+// (issue #148). Kept deliberately small and high-precision.
+const TOKEN_SYNONYMS = {
+  datamatrix: ["data", "matrix"],
+  pdf417: ["pdf417"],
+  qr: ["qrcode"],
+  qrcode: ["qr"],
+  webcam: ["camera", "video"],
+  camera: ["webcam", "video"],
+  video: ["camera"],
+  scan: ["decode", "read"],
+  scanning: ["scan", "decode", "read"],
+  decode: ["scan", "read"],
+  read: ["scan", "decode"],
+  reading: ["read", "scan"],
+  deskew: ["normalize", "rectify"],
+  normalize: ["deskew"],
+  normalization: ["deskew", "normalize"],
+  licence: ["license"],
+  passport: ["mrz"],
+  mrz: ["passport"],
+  gs1: ["gs1", "ai"],
+  barcode: ["barcode"]
+};
+
+// Very light suffix folding to a stem, so "scanning"/"readers" reach "scan"/"reader".
+function stemToken(token) {
+  if (token.length <= 4) return token;
+  for (const suffix of ["ing", "ers", "er", "es", "s"]) {
+    if (token.endsWith(suffix) && token.length - suffix.length >= 3) {
+      return token.slice(0, token.length - suffix.length);
+    }
+  }
+  return token;
+}
+
+function expandQueryTokens(tokens) {
+  const out = new Set();
+  for (const token of tokens) {
+    if (!token) continue;
+    out.add(token);
+    const stem = stemToken(token);
+    if (stem !== token) out.add(stem);
+    const synonyms = TOKEN_SYNONYMS[token] || TOKEN_SYNONYMS[stem];
+    if (synonyms) {
+      for (const syn of synonyms) out.add(syn);
+    }
+  }
+  return [...out];
+}
+
+// A ~maxLen window around the first query term found in text — used to give the
+// agent a matched snippet in search results (issues #146/#149).
+function extractSnippet(text, terms, maxLen = 240) {
+  const cleaned = normalizeText(text);
+  if (!cleaned) return "";
+  const lower = cleaned.toLowerCase();
+  let hitAt = -1;
+  for (const term of terms) {
+    if (!term) continue;
+    const at = lower.indexOf(term.toLowerCase());
+    if (at !== -1 && (hitAt === -1 || at < hitAt)) hitAt = at;
+  }
+  if (hitAt === -1) return truncateText(cleaned, maxLen);
+  const start = Math.max(0, hitAt - Math.floor(maxLen / 3));
+  const snippet = cleaned.slice(start, start + maxLen).trim();
+  return (start > 0 ? "…" : "") + snippet + (start + maxLen < cleaned.length ? "…" : "");
+}
+
 function buildEntryBaseText(entry) {
   const parts = [entry.title, entry.summary];
   if (Array.isArray(entry.tags) && entry.tags.length > 0) {
@@ -75,8 +208,8 @@ function buildEmbeddingItems(resourceIndex, ragConfig) {
   for (const entry of resourceIndex) {
     const baseText = buildEntryBaseText(entry);
     if (!baseText) continue;
-    if (entry.type === "doc" && entry.embedText) {
-      const chunks = chunkText(entry.embedText, ragConfig.chunkSize, ragConfig.chunkOverlap, ragConfig.maxChunksPerDoc);
+    if (entry.embedText) {
+      const chunks = chunkMarkdown(entry.embedText, ragConfig.chunkSize, ragConfig.chunkOverlap, ragConfig.maxChunksPerDoc);
       if (chunks.length === 0) {
         items.push({
           id: entry.id,
@@ -122,7 +255,9 @@ function buildIndexSignature({ pkgVersion, signatureData, ragConfig }) {
     chunkSize: ragConfig.chunkSize,
     chunkOverlap: ragConfig.chunkOverlap,
     maxChunksPerDoc: ragConfig.maxChunksPerDoc,
-    maxTextChars: ragConfig.maxTextChars
+    maxTextChars: ragConfig.maxTextChars,
+    // Bump when the chunking strategy changes so cached vector indexes rebuild.
+    chunkStrategy: "heading-aware-v1"
   });
 }
 
@@ -158,6 +293,11 @@ export {
   entryMatchesScope,
   normalizeText,
   truncateText,
+  chunkText,
+  chunkMarkdown,
+  expandQueryTokens,
+  stemToken,
+  extractSnippet,
   buildEmbeddingItems,
   buildIndexSignature,
   normalizeVector,

package/src/rag/vector-cache.js

@@ -59,7 +59,23 @@ function loadVectorIndexCache(
 
 function saveVectorIndexCache(cacheDir, cacheFile, payload) {
   ensureDirectory(cacheDir);
-  writeFileSync(cacheFile, JSON.stringify(payload));
+  let serialized;
+  try {
+    serialized = JSON.stringify(payload);
+  } catch (error) {
+    // JSON.stringify throws "Invalid string length" once the serialized cache
+    // exceeds V8's ~512MB max string length (reached with a large index of
+    // high-dimensional vectors). Fail with an actionable message instead.
+    if (error instanceof RangeError) {
+      const itemCount = Array.isArray(payload?.items) ? payload.items.length : "unknown";
+      throw new Error(
+        `Vector cache too large to serialize (${itemCount} items) — exceeds the JSON string limit. ` +
+        "Lower RAG_MAX_CHUNKS_PER_DOC or adopt a ceiling-proof cache format."
+      );
+    }
+    throw error;
+  }
+  writeFileSync(cacheFile, serialized);
 }
 
 function loadVectorIndexCheckpoint(checkpointFile, expectedKey, expectedItems) {