@ontos-ai/knowhere-sdk 2.0.0 → 2.1.2

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   BadRequestError: () => BadRequestError,
   ChecksumError: () => ChecksumError,
   ConflictError: () => ConflictError,
+  DiskParsedDocumentStorage: () => DiskParsedDocumentStorage,
   Documents: () => Documents,
   GatewayTimeoutError: () => GatewayTimeoutError,
   InternalServerError: () => InternalServerError,
@@ -56,7 +57,9 @@ __export(index_exports, {
   TimeoutError: () => TimeoutError,
   VERSION: () => VERSION,
   ValidationError: () => ValidationError,
-  default: () => Knowhere
+  default: () => Knowhere,
+  storeParseResultAssets: () => storeParseResultAssets,
+  syncParseResultToParsedDocumentStorage: () => syncParseResultToParsedDocumentStorage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -369,8 +372,8 @@ function enrichParseResult(parseResult2, scope) {
   }
   return parseResult2;
 }
-function sanitizePath(path3) {
-  let sanitized = path3.replace(/^\/+/, "");
+function sanitizePath(path4) {
+  let sanitized = path4.replace(/^\/+/, "");
   sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
   sanitized = sanitized.replace(/\\/g, "/");
   return sanitized;
@@ -756,8 +759,8 @@ var BaseResource = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
-  endpoint(path3) {
-    return `/v2${path3.startsWith("/") ? path3 : `/${path3}`}`;
+  endpoint(path4) {
+    return `/v2${path4.startsWith("/") ? path4 : `/${path4}`}`;
   }
 };
 
@@ -973,17 +976,28 @@ async function saveExpandedParseResult(result, directory) {
   if (result.rawZip.length > 0) {
     const didExtractZip = await tryExtractRawZip(result.rawZip, directory);
     if (didExtractZip) {
+      await writeExpandedParseResultMetadata(result, directory);
       return directory;
     }
   }
   await import_fs2.promises.mkdir(directory, { recursive: true });
+  await writeExpandedParseResultMetadata(result, directory);
+  for (const imageChunk of result.imageChunks) {
+    await writeBinaryAsset(directory, imageChunk.filePath, imageChunk.data);
+  }
+  for (const tableChunk of result.tableChunks) {
+    await writeTextAsset(directory, tableChunk.filePath, tableChunk.html);
+  }
+  return directory;
+}
+async function writeExpandedParseResultMetadata(result, directory) {
   await import_fs2.promises.writeFile((0, import_path.join)(directory, "manifest.json"), JSON.stringify(result.manifest, null, 2));
   if (result.docNav) {
     await import_fs2.promises.writeFile((0, import_path.join)(directory, "doc_nav.json"), JSON.stringify(result.docNav, null, 2));
   }
   await import_fs2.promises.writeFile(
     (0, import_path.join)(directory, "chunks.json"),
-    JSON.stringify(serializeChunks(result.chunks), null, 2)
+    JSON.stringify(keysToSnake(serializeChunks(result.chunks)), null, 2)
   );
   if (result.chunksSlim) {
     await import_fs2.promises.writeFile(
@@ -1012,13 +1026,6 @@ async function saveExpandedParseResult(result, directory) {
   if (result.hierarchyViewHtml) {
     await import_fs2.promises.writeFile((0, import_path.join)(directory, "hierarchy_view.html"), result.hierarchyViewHtml);
   }
-  for (const imageChunk of result.imageChunks) {
-    await writeBinaryAsset(directory, imageChunk.filePath, imageChunk.data);
-  }
-  for (const tableChunk of result.tableChunks) {
-    await writeTextAsset(directory, tableChunk.filePath, tableChunk.html);
-  }
-  return directory;
 }
 async function tryExtractRawZip(zipBuffer, directory) {
   try {
@@ -1157,13 +1164,14 @@ function buildTextChunk(chunkData) {
   };
 }
 function buildPageChunk(chunkData) {
+  const metadata = chunkData.metadata ?? {};
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "page",
     contentSource: chunkData.contentSource ?? "summary",
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
-    metadata: chunkData.metadata ?? {}
+    metadata
   };
 }
 function buildImageChunk(chunkData, filePath, imageBuffer) {
@@ -1174,6 +1182,7 @@ function buildImageChunk(chunkData, filePath, imageBuffer) {
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     filePath,
+    assetUrl: chunkData.assetUrl,
     data: imageBuffer,
     metadata: chunkData.metadata ?? {},
     get format() {
@@ -1192,6 +1201,7 @@ function buildTableChunk(chunkData, filePath, html) {
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
     filePath,
+    assetUrl: chunkData.assetUrl,
     html,
     metadata: chunkData.metadata ?? {},
     async save(directory) {
@@ -1286,6 +1296,7 @@ function serializeChunks(chunks) {
       };
       if (chunk.type === "image" || chunk.type === "table") {
         rawChunk.filePath = chunk.filePath;
+        rawChunk.assetUrl = chunk.assetUrl;
       }
       return rawChunk;
     })
@@ -1494,6 +1505,14 @@ var Documents = class extends BaseResource {
       this.createChunkGetRequestConfig(params)
     );
   }
+  /**
+   * Get a signed normalized source-file URL for compatibility and debugging.
+   */
+  async getPageCitationSource(documentId) {
+    return this.httpClient.get(
+      this.endpoint(`/documents/${documentId}/files/page-citation-source`)
+    );
+  }
   /**
    * Archive one canonical document by ID.
    */
@@ -1566,6 +1585,477 @@ var Documents = class extends BaseResource {
 // src/knowledge/knowledge.ts
 var import_crypto2 = require("crypto");
 
+// src/storage/asset-storage.ts
+var import_jszip2 = __toESM(require("jszip"));
+var pageCitationAssetsMetadataKey = "pageAssets";
+var defaultImageContentType = "application/octet-stream";
+var tableContentType = "text/html; charset=utf-8";
+async function storeParseResultAssets(result, options) {
+  if (!options) {
+    return {
+      result,
+      assetUrlsByFilePath: {}
+    };
+  }
+  const normalizedKeyPrefix = normalizeStorageKeyPrefix(options.keyPrefix);
+  const assets = dedupeStorageAssets(await collectStorageAssets(result, normalizedKeyPrefix));
+  const assetUrlsByFilePath = {};
+  for (const asset of assets) {
+    const storedUrl = await storeAsset(asset, options.adapter, options.skipExisting ?? true);
+    if (storedUrl) {
+      assetUrlsByFilePath[asset.sourcePath] = storedUrl;
+    }
+  }
+  const normalizedResult = Object.keys(assetUrlsByFilePath).length === 0 ? result : rewriteResultAssetUrls(result, assetUrlsByFilePath);
+  return {
+    result: normalizedResult,
+    assetUrlsByFilePath
+  };
+}
+async function collectStorageAssets(result, keyPrefix) {
+  const resultZip = await loadResultZipForPageCitationAssets(result);
+  return [
+    ...result.imageChunks.flatMap((chunk) => collectImageStorageAsset(chunk, keyPrefix)),
+    ...result.tableChunks.flatMap((chunk) => collectTableStorageAsset(chunk, keyPrefix)),
+    ...resultZip ? await collectPageCitationStorageAssets(result.pageChunks, keyPrefix, resultZip) : []
+  ];
+}
+function collectImageStorageAsset(chunk, keyPrefix) {
+  const sourcePath = normalizeResultAssetPath(chunk.filePath);
+  if (!sourcePath) return [];
+  return [
+    {
+      sourcePath,
+      storageKey: `${keyPrefix}/${sourcePath}`,
+      body: chunk.data,
+      contentType: getImageContentType(chunk.filePath),
+      metadata: {
+        chunkId: chunk.chunkId,
+        chunkType: chunk.type,
+        sourcePath
+      }
+    }
+  ];
+}
+function collectTableStorageAsset(chunk, keyPrefix) {
+  const sourcePath = normalizeResultAssetPath(chunk.filePath);
+  if (!sourcePath) return [];
+  return [
+    {
+      sourcePath,
+      storageKey: `${keyPrefix}/${sourcePath}`,
+      body: Buffer.from(chunk.html, "utf8"),
+      contentType: tableContentType,
+      metadata: {
+        chunkId: chunk.chunkId,
+        chunkType: chunk.type,
+        sourcePath
+      }
+    }
+  ];
+}
+async function collectPageCitationStorageAssets(chunks, keyPrefix, resultZip) {
+  const assets = [];
+  for (const chunk of chunks) {
+    const pageAssets = parsePageCitationAssets(chunk.metadata[pageCitationAssetsMetadataKey]);
+    for (const pageAsset of pageAssets) {
+      const sourcePath = normalizeResultAssetPath(pageAsset.artifactRef);
+      if (!sourcePath) continue;
+      const zipEntry = resultZip.file(sourcePath);
+      if (!zipEntry) continue;
+      assets.push({
+        sourcePath,
+        storageKey: `${keyPrefix}/${sourcePath}`,
+        body: await zipEntry.async("uint8array"),
+        contentType: pageAsset.contentType,
+        metadata: getPageCitationAssetMetadata(chunk, pageAsset, sourcePath)
+      });
+    }
+  }
+  return assets;
+}
+function getPageCitationAssetMetadata(chunk, pageAsset, sourcePath) {
+  return {
+    chunkId: chunk.chunkId,
+    chunkType: chunk.type,
+    pageNum: String(pageAsset.pageNum),
+    sourcePath
+  };
+}
+async function loadResultZipForPageCitationAssets(result) {
+  if (!hasPageCitationAssetReferences(result) || result.rawZip.length === 0) {
+    return null;
+  }
+  try {
+    return await import_jszip2.default.loadAsync(result.rawZip);
+  } catch (cause) {
+    throw new Error("Unable to read page citation assets from the Knowhere result ZIP.", {
+      cause
+    });
+  }
+}
+function hasPageCitationAssetReferences(result) {
+  return result.pageChunks.some(
+    (chunk) => parsePageCitationAssets(chunk.metadata[pageCitationAssetsMetadataKey]).length > 0
+  );
+}
+function dedupeStorageAssets(assets) {
+  const assetsBySourcePath = /* @__PURE__ */ new Map();
+  for (const asset of assets) {
+    if (!assetsBySourcePath.has(asset.sourcePath)) {
+      assetsBySourcePath.set(asset.sourcePath, asset);
+    }
+  }
+  return [...assetsBySourcePath.values()];
+}
+async function storeAsset(asset, adapter, skipExisting) {
+  if (skipExisting && adapter.headObject) {
+    const existing = await adapter.headObject(asset.storageKey);
+    if (existing) {
+      const existingUrl = existing.url ?? await adapter.getObjectUrl?.(asset.storageKey);
+      if (existingUrl) return existingUrl;
+    }
+  }
+  const writeResult = await adapter.writeObject({
+    key: asset.storageKey,
+    body: asset.body,
+    contentType: asset.contentType,
+    metadata: asset.metadata
+  });
+  return writeResult.url ?? await adapter.getObjectUrl?.(writeResult.key) ?? null;
+}
+function rewriteResultAssetUrls(result, assetUrlsByFilePath) {
+  const chunks = result.chunks.map((chunk) => rewriteChunkAssetUrls(chunk, assetUrlsByFilePath));
+  result.chunks.splice(0, result.chunks.length, ...chunks);
+  refreshStaticChunkCollections(result);
+  return result;
+}
+function rewriteChunkAssetUrls(chunk, assetUrlsByPath) {
+  if (chunk.type === "image" || chunk.type === "table") {
+    const sourcePath = normalizeResultAssetPath(chunk.filePath);
+    const assetUrl = sourcePath ? assetUrlsByPath[sourcePath] : void 0;
+    if (!assetUrl) return chunk;
+    return {
+      ...chunk,
+      assetUrl
+    };
+  }
+  if (chunk.type === "page") {
+    const pageAssets = parsePageCitationAssets(chunk.metadata[pageCitationAssetsMetadataKey]);
+    if (pageAssets.length === 0) return chunk;
+    const rewrittenPageAssets = pageAssets.map((pageAsset) => {
+      const sourcePath = normalizeResultAssetPath(pageAsset.artifactRef);
+      const assetUrl = sourcePath ? assetUrlsByPath[sourcePath] : void 0;
+      return assetUrl ? { ...pageAsset, assetUrl } : pageAsset;
+    });
+    return {
+      ...chunk,
+      metadata: {
+        ...chunk.metadata,
+        [pageCitationAssetsMetadataKey]: rewrittenPageAssets
+      }
+    };
+  }
+  return chunk;
+}
+function parsePageCitationAssets(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!isRecord(item)) return [];
+    const pageNum = item.pageNum;
+    const artifactRef = item.artifactRef;
+    const contentType = item.contentType;
+    const source = item.source;
+    if (typeof pageNum !== "number" || !Number.isSafeInteger(pageNum) || pageNum <= 0) return [];
+    if (typeof artifactRef !== "string") return [];
+    if (contentType !== "image/png" && contentType !== "image/jpeg") return [];
+    if (source !== "knowhere-rendered-page-citation-source") return [];
+    return [
+      {
+        pageNum,
+        artifactRef,
+        assetUrl: typeof item.assetUrl === "string" ? item.assetUrl : void 0,
+        contentType,
+        width: typeof item.width === "number" ? item.width : void 0,
+        height: typeof item.height === "number" ? item.height : void 0,
+        source
+      }
+    ];
+  });
+}
+function normalizeStorageKeyPrefix(value) {
+  const normalized = normalizeStoragePath(value, { allowDotPrefix: false });
+  if (!normalized) {
+    throw new Error("storageAdapter keyPrefix must be a non-empty relative POSIX path.");
+  }
+  return normalized;
+}
+function normalizeResultAssetPath(value) {
+  return normalizeStoragePath(value, { allowDotPrefix: true });
+}
+function normalizeStoragePath(value, options) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.includes("\0")) return null;
+  if (trimmed.startsWith("/") || /^[A-Za-z]:/.test(trimmed)) return null;
+  const normalized = options.allowDotPrefix ? trimmed.replaceAll("\\", "/").replace(/^\.\/+/, "") : trimmed.replaceAll("\\", "/");
+  if (normalized.length === 0) return null;
+  const parts = normalized.split("/");
+  if (parts.some((part) => part.length === 0 || part === "." || part === "..")) return null;
+  return parts.join("/");
+}
+function refreshStaticChunkCollections(result) {
+  replaceStaticChunkCollection(
+    result,
+    "textChunks",
+    result.chunks.filter((chunk) => chunk.type === "text")
+  );
+  replaceStaticChunkCollection(
+    result,
+    "imageChunks",
+    result.chunks.filter((chunk) => chunk.type === "image")
+  );
+  replaceStaticChunkCollection(
+    result,
+    "tableChunks",
+    result.chunks.filter((chunk) => chunk.type === "table")
+  );
+  replaceStaticChunkCollection(
+    result,
+    "pageChunks",
+    result.chunks.filter((chunk) => chunk.type === "page")
+  );
+}
+function replaceStaticChunkCollection(result, property, value) {
+  const descriptor = Object.getOwnPropertyDescriptor(result, property);
+  if (!descriptor || descriptor.get || descriptor.writable !== true) return;
+  Object.defineProperty(result, property, {
+    ...descriptor,
+    value
+  });
+}
+function getImageContentType(filePath) {
+  const extension = filePath.split(".").at(-1)?.toLowerCase();
+  if (extension === "jpg" || extension === "jpeg") return "image/jpeg";
+  if (extension === "png") return "image/png";
+  if (extension === "webp") return "image/webp";
+  if (extension === "gif") return "image/gif";
+  if (extension === "svg") return "image/svg+xml";
+  return defaultImageContentType;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/storage/parsed-document-storage.ts
+var import_jszip3 = __toESM(require("jszip"));
+var parsedDocumentCommitPath = ".knowhere-sdk/commit.json";
+var jsonContentType = "application/json; charset=utf-8";
+var markdownContentType = "text/markdown; charset=utf-8";
+var csvContentType = "text/csv; charset=utf-8";
+var htmlContentType = "text/html; charset=utf-8";
+var binaryContentType = "application/octet-stream";
+async function syncParseResultToParsedDocumentStorage(params) {
+  const documentId = params.documentId ?? params.result.documentId ?? params.result.jobId;
+  const revisionKey = params.revisionKey ?? params.result.jobId;
+  const objects = await collectResultLayoutObjects(params.result);
+  for (const object of objects) {
+    await params.storage.writeObject({
+      documentId,
+      revisionKey,
+      ...object
+    });
+  }
+  const commit = {
+    version: 1,
+    documentId,
+    revisionKey,
+    source: params.source ?? "resultZip",
+    committedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeParsedDocumentJsonObject(params.storage, {
+    documentId,
+    revisionKey,
+    path: parsedDocumentCommitPath,
+    value: commit
+  });
+  return {
+    result: params.result,
+    documentId,
+    revisionKey,
+    commit
+  };
+}
+async function readParsedDocumentCommit(params) {
+  const object = await params.storage.readObject({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    path: parsedDocumentCommitPath
+  });
+  if (!object) {
+    return null;
+  }
+  const commit = readJsonObject(object);
+  return commit.revisionKey === params.revisionKey && commit.documentId === params.documentId ? commit : null;
+}
+function readJsonObject(object) {
+  return JSON.parse(Buffer.from(object.body).toString("utf8"));
+}
+async function collectResultLayoutObjects(result) {
+  const objectsByPath = /* @__PURE__ */ new Map();
+  const rawZipObjects = await collectRawZipObjects(result.rawZip);
+  for (const object of rawZipObjects) {
+    objectsByPath.set(object.path, object);
+  }
+  for (const object of collectGeneratedResultObjects(result)) {
+    if (!objectsByPath.has(object.path)) {
+      objectsByPath.set(object.path, object);
+    }
+  }
+  return [...objectsByPath.values()].filter((object) => !isSdkMetadataPath(object.path));
+}
+async function collectRawZipObjects(rawZip) {
+  try {
+    const zip = await import_jszip3.default.loadAsync(rawZip);
+    const objects = [];
+    for (const entry of Object.values(zip.files)) {
+      if (entry.dir || entry.name === "result.zip") {
+        continue;
+      }
+      objects.push({
+        path: normalizeResultPath(entry.name),
+        body: new Uint8Array(await entry.async("nodebuffer")),
+        contentType: inferContentTypeFromPath(entry.name)
+      });
+    }
+    return objects;
+  } catch {
+    return [];
+  }
+}
+function collectGeneratedResultObjects(result) {
+  const objects = [
+    createJsonObject("manifest.json", result.manifest),
+    createJsonObject("chunks.json", keysToSnake(serializeChunks2(result.chunks)))
+  ];
+  if (result.docNav) {
+    objects.push(createJsonObject("doc_nav.json", result.docNav));
+  }
+  if (result.fullMarkdown) {
+    objects.push(createTextObject("full.md", result.fullMarkdown, markdownContentType));
+  }
+  if (result.chunksSlim) {
+    objects.push(createJsonObject("chunks_slim.json", { chunks: result.chunksSlim }));
+  }
+  if (result.hierarchy) {
+    objects.push(createJsonObject("hierarchy.json", result.hierarchy));
+  }
+  if (result.tocHierarchies) {
+    objects.push(createJsonObject("toc_hierarchies.json", result.tocHierarchies));
+  }
+  if (result.kbCsv) {
+    objects.push(createTextObject("kb.csv", result.kbCsv, csvContentType));
+  }
+  if (result.hierarchyViewHtml) {
+    objects.push(
+      createTextObject("hierarchy_view.html", result.hierarchyViewHtml, htmlContentType)
+    );
+  }
+  for (const chunk of result.imageChunks) {
+    objects.push({
+      path: normalizeResultPath(chunk.filePath),
+      body: new Uint8Array(chunk.data),
+      contentType: inferContentTypeFromPath(chunk.filePath),
+      metadata: {
+        chunkId: chunk.chunkId,
+        chunkType: chunk.type,
+        sourcePath: chunk.filePath
+      }
+    });
+  }
+  for (const chunk of result.tableChunks) {
+    objects.push({
+      path: normalizeResultPath(chunk.filePath),
+      body: Buffer.from(chunk.html, "utf8"),
+      contentType: htmlContentType,
+      metadata: {
+        chunkId: chunk.chunkId,
+        chunkType: chunk.type,
+        sourcePath: chunk.filePath
+      }
+    });
+  }
+  return objects;
+}
+function serializeChunks2(chunks) {
+  return {
+    chunks: chunks.map((chunk) => {
+      const rawChunk = {
+        chunkId: chunk.chunkId,
+        type: chunk.type,
+        contentSource: chunk.contentSource,
+        content: chunk.content,
+        path: chunk.path,
+        metadata: chunk.metadata
+      };
+      if (chunk.type === "image" || chunk.type === "table") {
+        return {
+          ...rawChunk,
+          filePath: chunk.filePath,
+          assetUrl: chunk.assetUrl
+        };
+      }
+      return rawChunk;
+    })
+  };
+}
+async function writeParsedDocumentJsonObject(storage, params) {
+  await storage.writeObject({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    path: params.path,
+    body: Buffer.from(JSON.stringify(params.value, null, 2), "utf8"),
+    contentType: jsonContentType
+  });
+}
+function createJsonObject(path4, value) {
+  return {
+    path: path4,
+    body: Buffer.from(JSON.stringify(value, null, 2), "utf8"),
+    contentType: jsonContentType
+  };
+}
+function createTextObject(path4, value, contentType) {
+  return {
+    path: path4,
+    body: Buffer.from(value, "utf8"),
+    contentType
+  };
+}
+function inferContentTypeFromPath(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith(".json")) return jsonContentType;
+  if (lower.endsWith(".md")) return markdownContentType;
+  if (lower.endsWith(".csv")) return csvContentType;
+  if (lower.endsWith(".html") || lower.endsWith(".htm")) return htmlContentType;
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  return binaryContentType;
+}
+function normalizeResultPath(value) {
+  const normalized = value.replaceAll("\\", "/").replace(/^\.\/+/, "");
+  if (normalized.length === 0 || normalized.includes("\0") || normalized.startsWith("/") || normalized.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
+    throw new Error(`Invalid parsed result path: ${value}`);
+  }
+  return normalized;
+}
+function isSdkMetadataPath(path4) {
+  return path4 === ".knowhere-sdk" || path4.startsWith(".knowhere-sdk/");
+}
+
 // src/knowledge/local-store.ts
 var import_crypto = require("crypto");
 var import_os = __toESM(require("os"));
@@ -1791,27 +2281,61 @@ function isMissingFileError2(error) {
 // src/knowledge/knowledge.ts
 var DEFAULT_READ_LIMIT = 12;
 var MAX_READ_LIMIT = 40;
+var DEFAULT_PAGE_SIZE = 20;
+var MAX_PAGE_SIZE = 200;
 var DEFAULT_GREP_LIMIT = 20;
 var MAX_GREP_LIMIT = 50;
 var DEFAULT_CONTEXT_CHARS = 80;
+var DEFAULT_REMOTE_SCAN_PAGE_SIZE = 100;
+var DEFAULT_MAX_SYNC_PAGES = 10;
+var DEFAULT_SYNC_DEADLINE_MS = 8e3;
+var DEFAULT_GREP_MAX_PAGES = 50;
+var DEFAULT_GREP_DEADLINE_MS = 8e3;
+var DEFAULT_OUTLINE_MAX_PAGES = 50;
+var DEFAULT_OUTLINE_DEADLINE_MS = 8e3;
 var SAFE_LOCAL_DOCUMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 var REMOTE_DOCUMENT_ID_PATTERN = /^doc[_-]/;
+var remoteReconstructionPageDirectory = ".knowhere-sdk/remote-reconstruction/pages";
 var Knowledge = class _Knowledge {
   client;
   store;
+  cacheDirectory;
+  parsedStorageConfig;
   constructor(client, options) {
     this.client = client;
+    this.cacheDirectory = options?.cacheDirectory;
+    this.parsedStorageConfig = options?.parsedStorage;
     this.store = new LocalKnowledgeStore(options?.cacheDirectory);
   }
   withCacheDirectory(cacheDirectory) {
-    return new _Knowledge(this.client, { cacheDirectory });
+    return new _Knowledge(this.client, {
+      cacheDirectory,
+      parsedStorage: this.parsedStorageConfig
+    });
   }
-  async parse(params) {
-    const result = await this.client.parse(params);
+  withParsedStorage(parsedStorage) {
+    return new _Knowledge(this.client, {
+      cacheDirectory: this.cacheDirectory,
+      parsedStorage
+    });
+  }
+  async parseToLocalCache(params) {
+    const loadedResult = params.storageAdapter ? await this.parseWithoutClientStorageAdapter(params) : await this.client.parse(params);
+    const storedAssets = await storeParseResultAssets(loadedResult, params.storageAdapter);
+    const syncedStorage = await this.syncParseResultToConfiguredStorage(storedAssets.result);
+    const result = syncedStorage.result;
     const document = await this.store.saveResult(result, {
       localDocumentId: params.localDocumentId
     });
-    return { document, result };
+    return {
+      document,
+      result,
+      assetUrlsByFilePath: storedAssets.assetUrlsByFilePath
+    };
+  }
+  /** @deprecated Use parseToLocalCache for local cache imports or the top-level client.parse for server-safe parsing. */
+  async parse(params) {
+    return this.parseToLocalCache(params);
   }
   async startParse(params) {
     const job = await this.client.startParse(params);
@@ -1842,14 +2366,95 @@ var Knowledge = class _Knowledge {
       results
     };
   }
-  async cacheJobResult(params) {
-    const result = await this.client.jobs.load(params.jobId, {
+  async loadJobResult(params) {
+    const loadedResult = await this.client.jobs.load(params.jobId, {
       verifyChecksum: params.verifyChecksum
     });
+    const storedAssets = await storeParseResultAssets(loadedResult, params.storageAdapter);
+    const syncedStorage = await this.syncParseResultToConfiguredStorage(storedAssets.result);
+    const result = syncedStorage.result;
+    return {
+      result,
+      assetUrlsByFilePath: storedAssets.assetUrlsByFilePath
+    };
+  }
+  async importJobResult(params) {
+    const stored = await this.loadJobResult(params);
+    const result = stored.result;
     const document = await this.store.saveResult(result, {
       localDocumentId: params.localDocumentId
     });
-    return { document, result };
+    return {
+      document,
+      result,
+      assetUrlsByFilePath: stored.assetUrlsByFilePath
+    };
+  }
+  /** @deprecated Use importJobResult for local cache imports or loadJobResult for server-safe loads. */
+  async cacheJobResult(params) {
+    return this.importJobResult(params);
+  }
+  async syncParsedDocument(params) {
+    const normalized = normalizeDocumentReference(params);
+    const parsedStorageConfig = this.requireParsedStorageConfig();
+    if (normalized.documentId) {
+      return this.syncRemoteDocumentToParsedStorage({
+        documentId: normalized.documentId,
+        revisionKey: params.revisionKey,
+        parsedStorageConfig
+      });
+    }
+    if (normalized.jobId) {
+      const loadedResult = await this.client.jobs.load(normalized.jobId);
+      const synced2 = await syncParseResultToParsedDocumentStorage({
+        result: loadedResult,
+        storage: parsedStorageConfig.storage,
+        documentId: loadedResult.documentId ?? normalized.localDocumentId ?? normalized.jobId,
+        revisionKey: params.revisionKey ?? normalized.jobId
+      });
+      return {
+        documentId: synced2.documentId,
+        revisionKey: synced2.revisionKey,
+        completed: true,
+        commit: synced2.commit
+      };
+    }
+    if (!normalized.localDocumentId) {
+      throw new ValidationError("localDocumentId, documentId, or jobId is required");
+    }
+    const { result } = await this.store.loadResult(normalized.localDocumentId);
+    const synced = await syncParseResultToParsedDocumentStorage({
+      result,
+      storage: parsedStorageConfig.storage,
+      documentId: result.documentId ?? normalized.localDocumentId,
+      revisionKey: params.revisionKey ?? result.jobId
+    });
+    return {
+      documentId: synced.documentId,
+      revisionKey: synced.revisionKey,
+      completed: true,
+      commit: synced.commit
+    };
+  }
+  async syncParseResultToConfiguredStorage(result) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return { result };
+    }
+    const synced = await syncParseResultToParsedDocumentStorage({
+      result,
+      storage: parsedStorageConfig.storage
+    });
+    return {
+      result: synced.result,
+      commit: synced.commit
+    };
+  }
+  async parseWithoutClientStorageAdapter(params) {
+    const parseParams = { ...params };
+    delete parseParams.localDocumentId;
+    delete parseParams.storageAdapter;
+    return this.client.parse(parseParams);
   }
   async cacheDocument(params) {
     if (!params.documentId) {
@@ -1859,7 +2464,7 @@ var Knowledge = class _Knowledge {
       params.documentId
     );
     const jobId = await this.getPublishedDocumentJobId(params.documentId);
-    return this.cacheJobResult({
+    return this.importJobResult({
       jobId,
       localDocumentId: params.localDocumentId ?? existing?.localDocumentId ?? createLocalDocumentIdForRemote(params.documentId)
     });
@@ -1896,7 +2501,7 @@ var Knowledge = class _Knowledge {
       };
     }
     try {
-      const cached = await this.cacheJobResult({
+      const cached = await this.importJobResult({
         jobId,
         localDocumentId: trackedJob.localDocumentId
       });
@@ -1921,6 +2526,13 @@ var Knowledge = class _Knowledge {
     return this.store.listDocuments();
   }
   async getDocumentOutline(reference) {
+    const normalized = normalizeDocumentReference(reference);
+    if (normalized.documentId) {
+      return this.getRemoteDocumentOutline(normalized.documentId, normalized.revisionKey);
+    }
+    if (normalized.localDocumentId && looksLikeRemoteDocumentId(normalized.localDocumentId) && !await this.store.getDocument(normalized.localDocumentId)) {
+      return this.getRemoteDocumentOutline(normalized.localDocumentId, normalized.revisionKey);
+    }
     const { document, result } = await this.loadReadableResult(reference);
     const chunks = indexChunks(result);
     const sections = buildFlatSections(result, chunks);
@@ -1936,6 +2548,14 @@ var Knowledge = class _Knowledge {
     };
   }
   async readChunks(params) {
+    validateReadParams(params);
+    const normalized = normalizeDocumentReference(params);
+    if (normalized.documentId) {
+      return this.readRemoteDocumentChunks(normalized.documentId, params);
+    }
+    if (normalized.localDocumentId && looksLikeRemoteDocumentId(normalized.localDocumentId) && !await this.store.getDocument(normalized.localDocumentId)) {
+      return this.readRemoteDocumentChunks(normalized.localDocumentId, params);
+    }
     const { document, result } = await this.loadReadableResult(params);
     const limit = clampLimit(params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT);
     const chunks = indexChunks(result).filter((chunk) => matchesReadScope(chunk, params));
@@ -1952,6 +2572,13 @@ var Knowledge = class _Knowledge {
     if (!params.pattern) {
       throw new ValidationError("pattern is required");
     }
+    const normalized = normalizeDocumentReference(params);
+    if (normalized.documentId) {
+      return this.grepRemoteDocumentChunks(normalized.documentId, params);
+    }
+    if (normalized.localDocumentId && looksLikeRemoteDocumentId(normalized.localDocumentId) && !await this.store.getDocument(normalized.localDocumentId)) {
+      return this.grepRemoteDocumentChunks(normalized.localDocumentId, params);
+    }
     const { document, result } = await this.loadReadableResult(params);
     const maxResults = clampLimit(params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
     const contextChars = params.contextChars ?? DEFAULT_CONTEXT_CHARS;
@@ -2031,7 +2658,7 @@ var Knowledge = class _Knowledge {
       });
     }
     if (normalized.jobId) {
-      return this.cacheJobResult({
+      return this.importJobResult({
         jobId: normalized.jobId,
         localDocumentId: normalized.localDocumentId
       });
@@ -2051,21 +2678,657 @@ var Knowledge = class _Knowledge {
     }
     throw new Error(`Local Knowhere document not found: ${normalized.localDocumentId}`);
   }
-  async findLocalDocumentByRemoteId(documentId) {
-    const documents = await this.store.listDocuments();
-    return documents.find((document) => document.documentId === documentId);
+  async readRemoteDocumentChunks(documentId, params) {
+    const explicitRevisionKey = params.revisionKey ?? params.jobId;
+    if (explicitRevisionKey) {
+      const stored2 = await this.tryReadChunksFromParsedStorage({
+        documentId,
+        revisionKey: explicitRevisionKey,
+        params
+      });
+      if (stored2) {
+        return stored2;
+      }
+    }
+    if (hasScanReadFilters(params)) {
+      return this.scanRemoteDocumentChunks(documentId, params);
+    }
+    const pageParams = getReadPageParams(params);
+    const remotePage = await this.client.documents.listChunks(documentId, {
+      page: pageParams.page,
+      pageSize: pageParams.pageSize,
+      chunkType: params.chunkType,
+      includeAssetUrls: true
+    });
+    const revisionKey = getRemoteRevisionKey(remotePage);
+    const stored = await this.tryReadChunksFromParsedStorage({
+      documentId,
+      revisionKey,
+      params
+    });
+    if (stored) {
+      return stored;
+    }
+    const chunks = remotePage.chunks.map((chunk) => toRemoteReadChunk(chunk));
+    this.scheduleParsedStorageSync(documentId, revisionKey);
+    return {
+      document: createRemoteKnowledgeDocument({
+        documentId,
+        response: remotePage,
+        revisionKey
+      }),
+      chunks,
+      page: remotePage.pagination.page,
+      pageSize: remotePage.pagination.pageSize,
+      totalChunks: remotePage.pagination.total,
+      totalPages: remotePage.pagination.totalPages
+    };
   }
-  async getPublishedDocumentJobId(documentId) {
-    const response = await this.client.documents.listChunks(documentId, {
+  async scanRemoteDocumentChunks(documentId, params) {
+    const explicitRevisionKey = params.revisionKey ?? params.jobId;
+    if (explicitRevisionKey) {
+      const stored2 = await this.tryReadChunksFromParsedStorage({
+        documentId,
+        revisionKey: explicitRevisionKey,
+        params
+      });
+      if (stored2) {
+        return stored2;
+      }
+    }
+    const limit = clampLimit(params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT);
+    const limits = getParsedStorageLimits(this.parsedStorageConfig?.limits);
+    const firstPage = await this.client.documents.listChunks(documentId, {
       page: 1,
-      pageSize: 1
+      pageSize: limits.remotePageSize,
+      chunkType: params.chunkType,
+      includeAssetUrls: true
     });
-    if (!response.jobId) {
-      throw new Error(
-        `Cannot sync server document ${documentId}: current published job id was not returned.`
-      );
+    const revisionKey = getRemoteRevisionKey(firstPage);
+    const stored = await this.tryReadChunksFromParsedStorage({
+      documentId,
+      revisionKey,
+      params
+    });
+    if (stored) {
+      return stored;
     }
-    return response.jobId;
+    const selected = [];
+    let scannedPages = 0;
+    let page = 1;
+    let response = firstPage;
+    const startedAt = Date.now();
+    while (true) {
+      scannedPages += 1;
+      selected.push(...response.chunks.filter((chunk) => matchesRemoteReadScope(chunk, params)));
+      if (selected.length >= limit || response.pagination.page >= response.pagination.totalPages || scannedPages >= limits.outlineMaxPages || Date.now() - startedAt >= limits.outlineDeadlineMs) {
+        break;
+      }
+      page += 1;
+      response = await this.client.documents.listChunks(documentId, {
+        page,
+        pageSize: limits.remotePageSize,
+        chunkType: params.chunkType,
+        includeAssetUrls: true
+      });
+    }
+    const chunks = selected.slice(0, limit).map((chunk) => toRemoteReadChunk(chunk));
+    this.scheduleParsedStorageSync(documentId, revisionKey);
+    return {
+      document: createRemoteKnowledgeDocument({
+        documentId,
+        response: firstPage,
+        revisionKey
+      }),
+      chunks,
+      nextChunk: selected.length > limit ? toChunkPosition(selected[limit]) : void 0,
+      totalChunks: firstPage.pagination.total,
+      totalPages: firstPage.pagination.totalPages
+    };
+  }
+  async grepRemoteDocumentChunks(documentId, params) {
+    const explicitRevisionKey = params.revisionKey ?? params.jobId;
+    if (explicitRevisionKey && !params.continuationCursor) {
+      const stored2 = await this.tryGrepChunksFromParsedStorage({
+        documentId,
+        revisionKey: explicitRevisionKey,
+        params
+      });
+      if (stored2) {
+        return stored2;
+      }
+    }
+    const maxResults = clampLimit(params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
+    const contextChars = params.contextChars ?? DEFAULT_CONTEXT_CHARS;
+    const matcher = createMatcher(params);
+    const limits = getParsedStorageLimits(this.parsedStorageConfig?.limits);
+    const cursor = parseContinuationCursor(params.continuationCursor);
+    const startPage = cursor?.documentId === documentId ? cursor.nextPage : 1;
+    const firstPage = await this.client.documents.listChunks(documentId, {
+      page: startPage,
+      pageSize: limits.remotePageSize,
+      chunkType: params.chunkType,
+      includeAssetUrls: true
+    });
+    const revisionKey = getRemoteRevisionKey(firstPage);
+    const stored = startPage === 1 ? await this.tryGrepChunksFromParsedStorage({
+      documentId,
+      revisionKey,
+      params
+    }) : null;
+    if (stored) {
+      return stored;
+    }
+    const matches = [];
+    let scannedChunks = 0;
+    let scannedPages = 0;
+    let response = firstPage;
+    let page = startPage;
+    const startedAt = Date.now();
+    while (true) {
+      scannedPages += 1;
+      for (const [chunkIndex, chunk] of response.chunks.entries()) {
+        if (response.pagination.page === startPage && cursor?.nextChunkIndex !== void 0 && chunkIndex < cursor.nextChunkIndex) {
+          continue;
+        }
+        if (!matchesGrepScope(toIndexedRemoteChunk(chunk), params)) {
+          continue;
+        }
+        scannedChunks += 1;
+        const chunkMatches = matcher(chunk.content ?? "");
+        for (const [matchIndex, match] of chunkMatches.entries()) {
+          if (response.pagination.page === startPage && cursor?.nextChunkIndex === chunkIndex && cursor.nextMatchIndex !== void 0 && matchIndex < cursor.nextMatchIndex) {
+            continue;
+          }
+          matches.push({
+            position: toChunkPosition(chunk),
+            chunkId: chunk.chunkId,
+            chunkType: chunk.chunkType,
+            sectionPath: chunk.sectionPath ?? "",
+            sourceChunkPath: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
+            filePath: chunk.filePath ?? void 0,
+            startOffset: match.startOffset,
+            endOffset: match.endOffset,
+            snippet: buildSnippet(
+              chunk.content ?? "",
+              match.startOffset,
+              match.endOffset,
+              contextChars
+            )
+          });
+          if (matches.length >= maxResults) {
+            const continuationCursor = createGrepContinuationCursor({
+              documentId,
+              revisionKey,
+              response,
+              chunkIndex,
+              matchIndex,
+              chunkMatchCount: chunkMatches.length
+            });
+            this.scheduleParsedStorageSync(documentId, revisionKey);
+            return {
+              document: createRemoteKnowledgeDocument({
+                documentId,
+                response: firstPage,
+                revisionKey
+              }),
+              matches,
+              scannedChunks,
+              truncated: continuationCursor !== void 0,
+              continuationCursor
+            };
+          }
+        }
+      }
+      const shouldStop = response.pagination.page >= response.pagination.totalPages || scannedPages >= limits.grepMaxPages || Date.now() - startedAt >= limits.grepDeadlineMs;
+      if (shouldStop) {
+        const truncated = response.pagination.page < response.pagination.totalPages;
+        this.scheduleParsedStorageSync(documentId, revisionKey);
+        return {
+          document: createRemoteKnowledgeDocument({
+            documentId,
+            response: firstPage,
+            revisionKey
+          }),
+          matches,
+          scannedChunks,
+          truncated,
+          continuationCursor: truncated ? createContinuationCursor({
+            documentId,
+            revisionKey,
+            nextPage: response.pagination.page + 1
+          }) : void 0
+        };
+      }
+      page += 1;
+      response = await this.client.documents.listChunks(documentId, {
+        page,
+        pageSize: limits.remotePageSize,
+        chunkType: params.chunkType,
+        includeAssetUrls: true
+      });
+    }
+  }
+  async getRemoteDocumentOutline(documentId, revisionKeyOverride) {
+    if (revisionKeyOverride) {
+      const stored2 = await this.tryReadOutlineFromParsedStorage(documentId, revisionKeyOverride);
+      if (stored2) {
+        return stored2;
+      }
+    }
+    const limits = getParsedStorageLimits(this.parsedStorageConfig?.limits);
+    const firstPage = await this.client.documents.listChunks(documentId, {
+      page: 1,
+      pageSize: limits.remotePageSize,
+      includeAssetUrls: true
+    });
+    const revisionKey = getRemoteRevisionKey(firstPage);
+    const stored = await this.tryReadOutlineFromParsedStorage(documentId, revisionKey);
+    if (stored) {
+      return stored;
+    }
+    const chunks = [];
+    let page = 1;
+    let response = firstPage;
+    let scannedPages = 0;
+    const startedAt = Date.now();
+    while (true) {
+      scannedPages += 1;
+      chunks.push(...response.chunks.map(toIndexedRemoteChunk));
+      if (response.pagination.page >= response.pagination.totalPages || scannedPages >= limits.outlineMaxPages || Date.now() - startedAt >= limits.outlineDeadlineMs) {
+        break;
+      }
+      page += 1;
+      response = await this.client.documents.listChunks(documentId, {
+        page,
+        pageSize: limits.remotePageSize,
+        includeAssetUrls: true
+      });
+    }
+    const truncated = response.pagination.page < response.pagination.totalPages;
+    const sections = buildFlatSectionsFromIndexedChunks(chunks);
+    this.scheduleParsedStorageSync(documentId, revisionKey);
+    return {
+      document: createRemoteKnowledgeDocument({
+        documentId,
+        response: firstPage,
+        revisionKey,
+        typeCounts: countIndexedTypes(chunks)
+      }),
+      totalChunks: firstPage.pagination.total,
+      typeCounts: countIndexedTypes(chunks),
+      sections,
+      sectionTree: nestSections(sections),
+      truncated,
+      continuationCursor: truncated ? createContinuationCursor({
+        documentId,
+        revisionKey,
+        nextPage: response.pagination.page + 1
+      }) : void 0
+    };
+  }
+  async tryReadChunksFromParsedStorage(params) {
+    const storedResult = await this.readCommittedParsedStorageResult(
+      params.documentId,
+      params.revisionKey
+    );
+    if (!storedResult) return null;
+    const pageParams = getReadPageParams(params.params);
+    const scopedChunks = storedResult.chunks.filter((chunk) => !params.params.chunkType || chunk.chunkType === params.params.chunkType).filter((chunk) => matchesReadScope(chunk, params.params));
+    const selected = hasScanReadFilters(params.params) ? selectReadWindow(
+      scopedChunks,
+      params.params,
+      clampLimit(params.params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT)
+    ) : scopedChunks.slice(
+      (pageParams.page - 1) * pageParams.pageSize,
+      pageParams.page * pageParams.pageSize
+    );
+    const visibleChunks = await applyStoredAssetUrlsToReadChunks({
+      storageConfig: this.requireParsedStorageConfig(),
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      chunks: selected.map(toReadChunk)
+    });
+    const totalChunks = scopedChunks.length;
+    return {
+      document: createStoredKnowledgeDocument({
+        documentId: params.documentId,
+        storedResult,
+        revisionKey: params.revisionKey
+      }),
+      chunks: visibleChunks,
+      page: hasScanReadFilters(params.params) ? void 0 : pageParams.page,
+      pageSize: hasScanReadFilters(params.params) ? void 0 : pageParams.pageSize,
+      totalChunks,
+      totalPages: Math.max(1, Math.ceil(totalChunks / pageParams.pageSize)),
+      nextChunk: getNextChunkPosition(scopedChunks, selected)
+    };
+  }
+  async tryGrepChunksFromParsedStorage(params) {
+    const storedResult = await this.readCommittedParsedStorageResult(
+      params.documentId,
+      params.revisionKey
+    );
+    if (!storedResult) return null;
+    const maxResults = clampLimit(params.params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
+    const contextChars = params.params.contextChars ?? DEFAULT_CONTEXT_CHARS;
+    const matcher = createMatcher(params.params);
+    const scopedChunks = storedResult.chunks.filter((chunk) => !params.params.chunkType || chunk.chunkType === params.params.chunkType).filter((chunk) => matchesGrepScope(chunk, params.params));
+    const matches = [];
+    let scannedChunks = 0;
+    for (const chunk of scopedChunks) {
+      scannedChunks += 1;
+      for (const match of matcher(chunk.content)) {
+        matches.push({
+          position: chunk.position,
+          chunkId: chunk.chunkId,
+          chunkType: chunk.chunkType,
+          sectionPath: chunk.sectionPath,
+          sourceChunkPath: chunk.sourceChunkPath,
+          filePath: chunk.filePath,
+          startOffset: match.startOffset,
+          endOffset: match.endOffset,
+          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
+        });
+        if (matches.length >= maxResults) {
+          return {
+            document: createStoredKnowledgeDocument({
+              documentId: params.documentId,
+              storedResult,
+              revisionKey: params.revisionKey
+            }),
+            matches,
+            scannedChunks,
+            truncated: true
+          };
+        }
+      }
+    }
+    return {
+      document: createStoredKnowledgeDocument({
+        documentId: params.documentId,
+        storedResult,
+        revisionKey: params.revisionKey
+      }),
+      matches,
+      scannedChunks,
+      truncated: false
+    };
+  }
+  async tryReadOutlineFromParsedStorage(documentId, revisionKey) {
+    const storedResult = await this.readCommittedParsedStorageResult(documentId, revisionKey);
+    if (!storedResult) return null;
+    const sections = storedResult.docNav?.sections && storedResult.docNav.sections.length > 0 ? flattenSections(
+      storedResult.docNav.sections.map(
+        (section) => toKnowledgeSection(
+          section,
+          storedResult.chunks,
+          storedResult.manifest.sourceFileName
+        )
+      )
+    ) : buildFlatSectionsFromIndexedChunks(storedResult.chunks);
+    return {
+      document: createStoredKnowledgeDocument({
+        documentId,
+        storedResult,
+        revisionKey
+      }),
+      totalChunks: storedResult.chunks.length,
+      typeCounts: storedResult.typeCounts,
+      sections,
+      sectionTree: storedResult.docNav?.sections && storedResult.docNav.sections.length > 0 ? storedResult.docNav.sections.map(
+        (section) => toKnowledgeSection(
+          section,
+          storedResult.chunks,
+          storedResult.manifest.sourceFileName
+        )
+      ) : nestSections(sections),
+      truncated: false
+    };
+  }
+  async readCommittedParsedStorageResult(documentId, revisionKey) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return null;
+    }
+    const commit = await readParsedDocumentCommit({
+      storage: parsedStorageConfig.storage,
+      documentId,
+      revisionKey
+    });
+    if (!commit) {
+      return null;
+    }
+    const manifestObject = await parsedStorageConfig.storage.readObject({
+      documentId,
+      revisionKey,
+      path: "manifest.json"
+    });
+    const chunksObject = await parsedStorageConfig.storage.readObject({
+      documentId,
+      revisionKey,
+      path: "chunks.json"
+    });
+    if (!manifestObject || !chunksObject) {
+      return null;
+    }
+    const manifest = readJsonObject(manifestObject);
+    const chunks = parseStoredResultChunks({
+      payload: readJsonObject(chunksObject),
+      sourceFileName: manifest.sourceFileName
+    });
+    const docNavObject = await parsedStorageConfig.storage.readObject({
+      documentId,
+      revisionKey,
+      path: "doc_nav.json"
+    });
+    const docNav = docNavObject ? readJsonObject(docNavObject) : void 0;
+    return {
+      commit,
+      manifest,
+      chunks,
+      docNav: docNav?.sections ? { sections: docNav.sections } : void 0,
+      typeCounts: countIndexedTypes(chunks)
+    };
+  }
+  scheduleParsedStorageSync(documentId, revisionKey) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return;
+    }
+    const scheduler = parsedStorageConfig.scheduler ?? defaultParsedStorageScheduler;
+    const task = async () => {
+      try {
+        await this.syncRemoteDocumentToParsedStorage({
+          documentId,
+          revisionKey,
+          parsedStorageConfig
+        });
+      } catch (error) {
+        await parsedStorageConfig.storage.writeSyncProgress({
+          documentId,
+          revisionKey,
+          nextChunkPage: 1,
+          status: "failed",
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    };
+    void Promise.resolve(scheduler.schedule(task)).catch(() => void 0);
+  }
+  async syncRemoteDocumentToParsedStorage(params) {
+    const firstPage = await this.client.documents.listChunks(params.documentId, {
+      page: 1,
+      pageSize: 1,
+      includeAssetUrls: true
+    });
+    const revisionKey = params.revisionKey ?? getRemoteRevisionKey(firstPage);
+    if (params.revisionKey && getRemoteRevisionKey(firstPage) !== params.revisionKey) {
+      return this.syncRemoteDocumentToParsedStorage({
+        documentId: params.documentId,
+        parsedStorageConfig: params.parsedStorageConfig
+      });
+    }
+    if (firstPage.jobId) {
+      try {
+        const loadedResult = await this.client.jobs.load(firstPage.jobId);
+        const synced = await syncParseResultToParsedDocumentStorage({
+          result: loadedResult,
+          storage: params.parsedStorageConfig.storage,
+          documentId: params.documentId,
+          revisionKey,
+          source: "resultZip"
+        });
+        await params.parsedStorageConfig.storage.writeSyncProgress({
+          documentId: params.documentId,
+          revisionKey,
+          status: "completed",
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        return {
+          documentId: synced.documentId,
+          revisionKey: synced.revisionKey,
+          completed: true,
+          commit: synced.commit
+        };
+      } catch {
+      }
+    }
+    return this.syncRemoteDocumentChunksToParsedStorage({
+      documentId: params.documentId,
+      revisionKey,
+      firstPage,
+      parsedStorageConfig: params.parsedStorageConfig
+    });
+  }
+  async syncRemoteDocumentChunksToParsedStorage(params) {
+    const limits = getParsedStorageLimits(params.parsedStorageConfig.limits);
+    const existingProgress = await params.parsedStorageConfig.storage.readSyncProgress({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey
+    });
+    let nextPage = existingProgress?.status === "running" ? existingProgress.nextChunkPage ?? 1 : 1;
+    let response = nextPage === 1 && params.firstPage.pagination.pageSize === limits.remotePageSize ? params.firstPage : await this.client.documents.listChunks(params.documentId, {
+      page: nextPage,
+      pageSize: limits.remotePageSize,
+      includeAssetUrls: true
+    });
+    const totalPages = response.pagination.totalPages;
+    let syncedPages = 0;
+    const startedAt = Date.now();
+    while (nextPage <= totalPages) {
+      if (syncedPages > 0) {
+        response = await this.client.documents.listChunks(params.documentId, {
+          page: nextPage,
+          pageSize: limits.remotePageSize,
+          includeAssetUrls: true
+        });
+      }
+      await params.parsedStorageConfig.storage.writeObject({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        path: getRemoteReconstructionPagePath(response.pagination.page),
+        body: Buffer.from(JSON.stringify({ chunks: response.chunks }), "utf8"),
+        contentType: "application/json; charset=utf-8"
+      });
+      nextPage += 1;
+      syncedPages += 1;
+      await params.parsedStorageConfig.storage.writeSyncProgress({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        nextChunkPage: nextPage,
+        status: "running",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (syncedPages >= limits.maxPagesPerSync || Date.now() - startedAt >= limits.syncDeadlineMs) {
+        return {
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          completed: false
+        };
+      }
+    }
+    const chunks = await this.readRemoteReconstructionChunks({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      totalPages,
+      parsedStorageConfig: params.parsedStorageConfig
+    });
+    if (!chunks) {
+      return {
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        completed: false
+      };
+    }
+    const synced = await syncParseResultToParsedDocumentStorage({
+      result: createMinimalParseResultFromRemoteChunks({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        response,
+        chunks
+      }),
+      storage: params.parsedStorageConfig.storage,
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      source: "remoteReconstruction"
+    });
+    await params.parsedStorageConfig.storage.writeSyncProgress({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      nextChunkPage: totalPages + 1,
+      status: "completed",
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return {
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      completed: true,
+      commit: synced.commit
+    };
+  }
+  async readRemoteReconstructionChunks(params) {
+    const chunks = [];
+    for (let page = 1; page <= params.totalPages; page += 1) {
+      const object = await params.parsedStorageConfig.storage.readObject({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        path: getRemoteReconstructionPagePath(page)
+      });
+      if (!object) {
+        return null;
+      }
+      const payload = readJsonObject(object);
+      if (!isDocumentChunkArray(payload.chunks)) {
+        return null;
+      }
+      chunks.push(...payload.chunks);
+    }
+    return chunks;
+  }
+  requireParsedStorageConfig() {
+    if (!this.parsedStorageConfig) {
+      throw new ValidationError("parsed document storage is not configured");
+    }
+    return this.parsedStorageConfig;
+  }
+  async findLocalDocumentByRemoteId(documentId) {
+    const documents = await this.store.listDocuments();
+    return documents.find((document) => document.documentId === documentId);
+  }
+  async getPublishedDocumentJobId(documentId) {
+    const response = await this.client.documents.listChunks(documentId, {
+      page: 1,
+      pageSize: 1,
+      includeAssetUrls: true
+    });
+    if (!response.jobId) {
+      throw new Error(
+        `Cannot sync server document ${documentId}: current published job id was not returned.`
+      );
+    }
+    return response.jobId;
   }
 };
 function normalizeDocumentReference(reference) {
@@ -2084,6 +3347,496 @@ function createLocalDocumentIdForRemote(documentId) {
   const hash = (0, import_crypto2.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
   return `remote_${hash}`;
 }
+var defaultParsedStorageScheduler = {
+  schedule(task) {
+    void task();
+  }
+};
+function getParsedStorageLimits(limits) {
+  return {
+    remotePageSize: clampLimit(
+      limits?.remotePageSize,
+      DEFAULT_REMOTE_SCAN_PAGE_SIZE,
+      MAX_PAGE_SIZE
+    ),
+    maxPagesPerSync: clampLimit(limits?.maxPagesPerSync, DEFAULT_MAX_SYNC_PAGES, 1e3),
+    syncDeadlineMs: clampLimit(limits?.syncDeadlineMs, DEFAULT_SYNC_DEADLINE_MS, 6e4),
+    grepMaxPages: clampLimit(limits?.grepMaxPages, DEFAULT_GREP_MAX_PAGES, 1e3),
+    grepDeadlineMs: clampLimit(limits?.grepDeadlineMs, DEFAULT_GREP_DEADLINE_MS, 6e4),
+    outlineMaxPages: clampLimit(limits?.outlineMaxPages, DEFAULT_OUTLINE_MAX_PAGES, 1e3),
+    outlineDeadlineMs: clampLimit(limits?.outlineDeadlineMs, DEFAULT_OUTLINE_DEADLINE_MS, 6e4)
+  };
+}
+function validateReadParams(params) {
+  const usesPagedDisplay = params.page !== void 0 || params.pageSize !== void 0;
+  if (!usesPagedDisplay) {
+    return;
+  }
+  if (params.sectionPath !== void 0 || params.startChunk !== void 0 || params.endChunk !== void 0 || params.chunkId !== void 0) {
+    throw new ValidationError(
+      "page and pageSize cannot be combined with sectionPath, startChunk, endChunk, or chunkId"
+    );
+  }
+}
+function hasScanReadFilters(params) {
+  return params.sectionPath !== void 0 || params.startChunk !== void 0 || params.endChunk !== void 0 || params.chunkId !== void 0;
+}
+function getReadPageParams(params) {
+  return {
+    page: clampLimit(params.page, 1, Number.MAX_SAFE_INTEGER),
+    pageSize: clampLimit(params.pageSize ?? params.limit, DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE)
+  };
+}
+function getRemoteRevisionKey(response) {
+  const revisionKey = response.jobResultId ?? response.jobId;
+  if (!revisionKey) {
+    throw new Error(
+      `Cannot read server document ${response.documentId}: current published revision was not returned.`
+    );
+  }
+  return revisionKey;
+}
+function getRemoteReconstructionPagePath(page) {
+  return `${remoteReconstructionPageDirectory}/page-${page}.json`;
+}
+function createRemoteKnowledgeDocument(params) {
+  return {
+    localDocumentId: params.documentId,
+    jobId: params.response.jobId ?? params.revisionKey,
+    documentId: params.documentId,
+    namespace: params.response.namespace,
+    sourceFileName: params.documentId,
+    chunkCount: params.response.pagination.total,
+    typeCounts: params.typeCounts ?? countRemoteChunkTypes(params.response.chunks),
+    resultDirectoryPath: `remote:${params.documentId}`,
+    createdAt: /* @__PURE__ */ new Date(0),
+    updatedAt: /* @__PURE__ */ new Date(0)
+  };
+}
+function createMinimalParseResultFromRemoteChunks(params) {
+  const chunks = params.chunks.map(toMinimalChunkFromRemoteChunk);
+  const typeCounts = countRemoteChunkTypes(params.chunks);
+  return {
+    manifest: {
+      version: "2.0",
+      jobId: params.response.jobId ?? params.revisionKey,
+      sourceFileName: params.documentId,
+      statistics: {
+        totalChunks: chunks.length,
+        textChunks: typeCounts.text,
+        imageChunks: typeCounts.image,
+        tableChunks: typeCounts.table,
+        pageChunks: typeCounts.page
+      }
+    },
+    chunks,
+    rawZip: Buffer.from(""),
+    namespace: params.response.namespace,
+    documentId: params.documentId,
+    textChunks: chunks.filter(
+      (chunk) => chunk.type === "text"
+    ),
+    imageChunks: chunks.filter(
+      (chunk) => chunk.type === "image"
+    ),
+    tableChunks: chunks.filter(
+      (chunk) => chunk.type === "table"
+    ),
+    pageChunks: chunks.filter(
+      (chunk) => chunk.type === "page"
+    ),
+    jobId: params.response.jobId ?? params.revisionKey,
+    statistics: {
+      totalChunks: chunks.length,
+      textChunks: typeCounts.text,
+      imageChunks: typeCounts.image,
+      tableChunks: typeCounts.table,
+      pageChunks: typeCounts.page
+    },
+    getChunk: (chunkId) => chunks.find((chunk) => chunk.chunkId === chunkId),
+    save: () => Promise.reject(new Error("Minimal remote reconstruction cannot be saved directly."))
+  };
+}
+function toMinimalChunkFromRemoteChunk(chunk) {
+  const baseChunk = {
+    chunkId: chunk.chunkId,
+    contentSource: chunk.contentSource ?? void 0,
+    content: chunk.content ?? "",
+    path: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
+    metadata: cloneMetadata(chunk.metadata)
+  };
+  if (chunk.chunkType === "image") {
+    return {
+      ...baseChunk,
+      type: "image",
+      filePath: chunk.filePath ?? "",
+      assetUrl: chunk.assetUrl ?? void 0,
+      data: Buffer.alloc(0),
+      format: inferContentTypeFromPath2(chunk.filePath ?? "").replace("image/", ""),
+      save: () => Promise.resolve(chunk.filePath ?? "")
+    };
+  }
+  if (chunk.chunkType === "table") {
+    return {
+      ...baseChunk,
+      type: "table",
+      filePath: chunk.filePath ?? "",
+      assetUrl: chunk.assetUrl ?? void 0,
+      html: chunk.content ?? "",
+      save: () => Promise.resolve(chunk.filePath ?? "")
+    };
+  }
+  if (chunk.chunkType === "page") {
+    return {
+      ...baseChunk,
+      type: "page"
+    };
+  }
+  return {
+    ...baseChunk,
+    type: "text"
+  };
+}
+function createStoredKnowledgeDocument(params) {
+  return {
+    localDocumentId: params.documentId,
+    jobId: params.storedResult.manifest.jobId || params.revisionKey,
+    documentId: params.documentId,
+    sourceFileName: params.storedResult.manifest.sourceFileName,
+    chunkCount: params.storedResult.chunks.length,
+    typeCounts: params.storedResult.typeCounts,
+    resultDirectoryPath: `parsed-storage:${params.documentId}`,
+    createdAt: new Date(params.storedResult.commit.committedAt),
+    updatedAt: new Date(params.storedResult.commit.committedAt)
+  };
+}
+function toRemoteReadChunk(chunk) {
+  const metadata = cloneMetadata(chunk.metadata);
+  return {
+    position: toChunkPosition(chunk),
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    contentSource: chunk.contentSource ?? void 0,
+    content: chunk.content ?? "",
+    readableContent: getReadableRemoteChunkContent(chunk, metadata),
+    sectionPath: chunk.sectionPath ?? "",
+    sourceChunkPath: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
+    filePath: chunk.filePath ?? void 0,
+    assetUrl: chunk.assetUrl ?? void 0,
+    pageNumbers: getChunkPageNumbers(metadata),
+    metadata
+  };
+}
+function getReadableRemoteChunkContent(chunk, metadata) {
+  if (chunk.chunkType !== "page") {
+    return chunk.content ?? "";
+  }
+  const summary = metadata.summary;
+  return typeof summary === "string" && summary.trim().length > 0 ? summary : chunk.content ?? "";
+}
+function toIndexedRemoteChunk(chunk) {
+  const readChunk = toRemoteReadChunk(chunk);
+  return toIndexedReadChunk(readChunk);
+}
+function parseStoredResultChunks(params) {
+  const rawChunks = extractStoredChunkRecords(params.payload);
+  return rawChunks.map((record, index) => {
+    const metadata = readRecordMetadata(record);
+    const chunkType = readRecordString(record, "type", "chunkType", "chunk_type");
+    const content = readRecordString(record, "content") ?? "";
+    const sourceChunkPath = readRecordString(record, "path", "sourceChunkPath", "source_chunk_path") ?? "";
+    const chunk = {
+      position: index + 1,
+      chunkId: readRecordString(record, "chunkId", "chunk_id") ?? "",
+      chunkType: isKnowledgeChunkType(chunkType) ? chunkType : "text",
+      contentSource: readRecordString(record, "contentSource", "content_source"),
+      content,
+      readableContent: chunkType === "page" && typeof metadata.summary === "string" && metadata.summary.trim().length > 0 ? metadata.summary : content,
+      sectionPath: normalizeSectionPath(sourceChunkPath, params.sourceFileName),
+      sourceChunkPath,
+      filePath: readRecordString(record, "filePath", "file_path") ?? (typeof metadata.filePath === "string" ? metadata.filePath : void 0),
+      assetUrl: readRecordString(record, "assetUrl", "asset_url"),
+      pageNumbers: getChunkPageNumbers(metadata),
+      metadata
+    };
+    return toIndexedReadChunk(chunk);
+  });
+}
+function extractStoredChunkRecords(payload) {
+  if (Array.isArray(payload)) {
+    return payload.filter(isRecord2);
+  }
+  if (isRecord2(payload) && Array.isArray(payload.chunks)) {
+    return payload.chunks.filter(isRecord2);
+  }
+  return [];
+}
+function readRecordString(record, ...keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string") return value;
+  }
+  return void 0;
+}
+function readRecordNumber(record, ...keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "number") return value;
+  }
+  return void 0;
+}
+function readRecordMetadata(record) {
+  const metadata = record.metadata;
+  return isRecord2(metadata) ? keysToCamel(metadata) : {};
+}
+function isKnowledgeChunkType(value) {
+  return value === "text" || value === "image" || value === "table" || value === "page";
+}
+function toIndexedReadChunk(chunk) {
+  return {
+    source: createSyntheticChunk(chunk),
+    position: chunk.position,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    contentSource: chunk.contentSource,
+    content: chunk.content,
+    readableContent: chunk.readableContent,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    assetUrl: chunk.assetUrl,
+    pageNumbers: chunk.pageNumbers,
+    metadata: chunk.metadata
+  };
+}
+function createSyntheticChunk(chunk) {
+  return {
+    chunkId: chunk.chunkId,
+    type: chunk.chunkType,
+    contentSource: chunk.contentSource,
+    content: chunk.content,
+    path: chunk.sourceChunkPath,
+    metadata: chunk.metadata
+  };
+}
+function toChunkPosition(chunk) {
+  return chunk ? chunk.sortOrder + 1 : 1;
+}
+function buildFlatSectionsFromIndexedChunks(chunks) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const path4 = chunk.sectionPath || chunk.sourceChunkPath;
+    const existing = byPath.get(path4);
+    if (existing) {
+      addChunkToSection(existing, chunk);
+    } else {
+      byPath.set(path4, createSectionFromChunk(path4, chunk));
+    }
+  }
+  return [...byPath.values()].sort(compareSections);
+}
+function matchesRemoteReadScope(chunk, params) {
+  return matchesReadScope(toIndexedRemoteChunk(chunk), params);
+}
+function getNextChunkPosition(chunks, selected) {
+  const lastSelected = selected[selected.length - 1];
+  if (!lastSelected || selected.length >= chunks.length) {
+    return void 0;
+  }
+  return chunks[chunks.indexOf(lastSelected) + 1]?.position;
+}
+async function applyStoredAssetUrlsToReadChunks(params) {
+  return Promise.all(
+    params.chunks.map(
+      (chunk) => applyStoredAssetUrlsToReadChunk({
+        ...params,
+        chunk
+      })
+    )
+  );
+}
+async function applyStoredAssetUrlsToReadChunk(params) {
+  const metadata = cloneMetadata(params.chunk.metadata);
+  const storedAssetUrl = await getStoredObjectUrl({
+    storageConfig: params.storageConfig,
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    path: params.chunk.filePath
+  });
+  const pageAssets = await applyStoredPageAssetUrls({
+    storageConfig: params.storageConfig,
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    metadata
+  });
+  if (pageAssets) {
+    metadata.pageAssets = pageAssets;
+    delete metadata.page_assets;
+  }
+  return {
+    ...params.chunk,
+    assetUrl: storedAssetUrl ?? params.chunk.assetUrl,
+    metadata
+  };
+}
+async function applyStoredPageAssetUrls(params) {
+  const pageAssets = getStoredPageAssets(params.metadata);
+  if (!pageAssets) {
+    return void 0;
+  }
+  return Promise.all(
+    pageAssets.map(async (pageAsset) => {
+      if (!isRecord2(pageAsset)) {
+        return pageAsset;
+      }
+      const artifactRef = readRecordString(pageAsset, "artifactRef", "artifact_ref");
+      if (typeof artifactRef !== "string") {
+        return pageAsset;
+      }
+      const storedAssetUrl = await getStoredObjectUrl({
+        storageConfig: params.storageConfig,
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        path: artifactRef
+      });
+      if (storedAssetUrl) {
+        return {
+          ...pageAsset,
+          artifactRef,
+          assetUrl: storedAssetUrl
+        };
+      }
+      return pageAsset;
+    })
+  );
+}
+function getStoredPageAssets(metadata) {
+  const pageAssets = toUnknownArray(metadata.pageAssets) ?? toUnknownArray(metadata.page_assets) ?? void 0;
+  return pageAssets?.map(normalizeStoredPageAsset);
+}
+function normalizeStoredPageAsset(pageAsset) {
+  if (!isRecord2(pageAsset)) {
+    return pageAsset;
+  }
+  const normalizedPageAsset = { ...pageAsset };
+  delete normalizedPageAsset.page_num;
+  delete normalizedPageAsset.artifact_ref;
+  delete normalizedPageAsset.asset_url;
+  delete normalizedPageAsset.content_type;
+  const pageNum = readRecordNumber(pageAsset, "pageNum", "page_num");
+  const artifactRef = readRecordString(pageAsset, "artifactRef", "artifact_ref");
+  const assetUrl = readRecordString(pageAsset, "assetUrl", "asset_url");
+  const contentType = readRecordString(pageAsset, "contentType", "content_type");
+  return {
+    ...normalizedPageAsset,
+    ...pageNum === void 0 ? {} : { pageNum },
+    ...artifactRef === void 0 ? {} : { artifactRef },
+    ...assetUrl === void 0 ? {} : { assetUrl },
+    ...contentType === void 0 ? {} : { contentType }
+  };
+}
+async function getStoredObjectUrl(params) {
+  if (!params.path) {
+    return void 0;
+  }
+  return await params.storageConfig.storage.getObjectUrl?.({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    path: params.path
+  }) ?? void 0;
+}
+function countRemoteChunkTypes(chunks) {
+  return chunks.reduce(
+    (counts, chunk) => {
+      counts[chunk.chunkType] += 1;
+      return counts;
+    },
+    { text: 0, image: 0, table: 0, page: 0 }
+  );
+}
+function createContinuationCursor(cursor) {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function createGrepContinuationCursor(params) {
+  if (params.matchIndex + 1 < params.chunkMatchCount) {
+    return createContinuationCursor({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      nextPage: params.response.pagination.page,
+      nextChunkIndex: params.chunkIndex,
+      nextMatchIndex: params.matchIndex + 1
+    });
+  }
+  if (params.chunkIndex + 1 < params.response.chunks.length) {
+    return createContinuationCursor({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      nextPage: params.response.pagination.page,
+      nextChunkIndex: params.chunkIndex + 1,
+      nextMatchIndex: 0
+    });
+  }
+  if (params.response.pagination.page < params.response.pagination.totalPages) {
+    return createContinuationCursor({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      nextPage: params.response.pagination.page + 1,
+      nextChunkIndex: 0,
+      nextMatchIndex: 0
+    });
+  }
+  return void 0;
+}
+function parseContinuationCursor(value) {
+  if (!value) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    if (!isRecord2(parsed)) {
+      return null;
+    }
+    const documentId = parsed.documentId;
+    const revisionKey = parsed.revisionKey;
+    const nextPage = parsed.nextPage;
+    const nextChunkIndex = parsed.nextChunkIndex;
+    const nextMatchIndex = parsed.nextMatchIndex;
+    if (typeof documentId !== "string" || typeof revisionKey !== "string" || typeof nextPage !== "number" || !Number.isInteger(nextPage) || nextPage < 1 || !isOptionalNonNegativeInteger(nextChunkIndex) || !isOptionalNonNegativeInteger(nextMatchIndex)) {
+      return null;
+    }
+    return {
+      documentId,
+      revisionKey,
+      nextPage,
+      nextChunkIndex,
+      nextMatchIndex
+    };
+  } catch {
+    return null;
+  }
+}
+function isOptionalNonNegativeInteger(value) {
+  return value === void 0 || typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function cloneMetadata(metadata) {
+  return { ...metadata };
+}
+function toUnknownArray(value) {
+  return Array.isArray(value) ? value : null;
+}
+function inferContentTypeFromPath2(filePath) {
+  const extension = filePath.split(".").at(-1)?.toLowerCase();
+  if (extension === "png") return "image/png";
+  if (extension === "jpg" || extension === "jpeg") return "image/jpeg";
+  if (extension === "html" || extension === "htm") return "text/html; charset=utf-8";
+  return "application/octet-stream";
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDocumentChunkArray(value) {
+  return Array.isArray(value) && value.every(isRecord2);
+}
 function indexChunks(result) {
   return result.chunks.map((chunk, index) => {
     const filePath = getChunkFilePath2(chunk);
@@ -2099,6 +3852,7 @@ function indexChunks(result) {
       sectionPath: normalizeSectionPath(chunk.path, result.manifest.sourceFileName),
       sourceChunkPath: chunk.path,
       filePath,
+      assetUrl: getChunkAssetUrl(chunk),
       pageNumbers: getChunkPageNumbers(chunk.metadata),
       metadata: chunk.metadata
     };
@@ -2112,12 +3866,11 @@ function getReadableChunkContent(chunk) {
   return typeof summary === "string" && summary.trim().length > 0 ? summary : chunk.content;
 }
 function getChunkPageNumbers(metadata) {
-  const value = metadata.pageNums;
-  if (!Array.isArray(value)) {
-    return void 0;
-  }
-  const pageNumbers = value.filter(
-    (pageNumber) => Number.isInteger(pageNumber) && pageNumber > 0
+  const values = [metadata.pageNums, metadata.page_nums].filter(Array.isArray);
+  const pageNumbers = values.flatMap(
+    (value) => value.filter(
+      (pageNumber) => Number.isInteger(pageNumber) && pageNumber > 0
+    )
   );
   return pageNumbers.length > 0 ? [...new Set(pageNumbers)].sort((left, right) => left - right) : void 0;
 }
@@ -2128,14 +3881,17 @@ function getChunkFilePath2(chunk) {
   const filePath = chunk.metadata.filePath;
   return typeof filePath === "string" ? filePath : void 0;
 }
-function normalizeSectionPath(path3, sourceFileName) {
-  if (!path3) {
+function getChunkAssetUrl(chunk) {
+  return chunk.type === "image" || chunk.type === "table" ? chunk.assetUrl : void 0;
+}
+function normalizeSectionPath(path4, sourceFileName) {
+  if (!path4) {
     return "";
   }
-  if (path3.startsWith("images/") || path3.startsWith("tables/")) {
-    return path3;
+  if (path4.startsWith("images/") || path4.startsWith("tables/")) {
+    return path4;
   }
-  const parts = path3.split("/").filter(Boolean);
+  const parts = path4.split("/").filter(Boolean);
   if (sourceFileName) {
     const fileNameIndex = parts.indexOf(sourceFileName);
     if (fileNameIndex >= 0) {
@@ -2157,12 +3913,12 @@ function buildFlatSections(result, chunks) {
   }
   const byPath = /* @__PURE__ */ new Map();
   for (const chunk of chunks) {
-    const path3 = chunk.sectionPath || chunk.sourceChunkPath;
-    const existing = byPath.get(path3);
+    const path4 = chunk.sectionPath || chunk.sourceChunkPath;
+    const existing = byPath.get(path4);
     if (existing) {
       addChunkToSection(existing, chunk);
     } else {
-      byPath.set(path3, createSectionFromChunk(path3, chunk));
+      byPath.set(path4, createSectionFromChunk(path4, chunk));
     }
   }
   return [...byPath.values()].sort(compareSections);
@@ -2296,6 +4052,7 @@ function toReadChunk(chunk) {
     sectionPath: chunk.sectionPath,
     sourceChunkPath: chunk.sourceChunkPath,
     filePath: chunk.filePath,
+    assetUrl: chunk.assetUrl,
     pageNumbers: chunk.pageNumbers,
     metadata: chunk.metadata
   };
@@ -2472,7 +4229,12 @@ var Knowhere = class {
     const result = await this.jobs.load(jobResult, {
       verifyChecksum: params.verifyChecksum
     });
-    return enrichParseResult(result, jobResult);
+    const enrichedResult = enrichParseResult(result, {
+      namespace: jobResult.namespace,
+      documentId: jobResult.documentId ?? params.documentId
+    });
+    const storedResult = await storeParseResultAssets(enrichedResult, params.storageAdapter);
+    return storedResult.result;
   }
   /**
    * Start a parse job and return immediately after the URL job is created or
@@ -2515,6 +4277,160 @@ var Knowhere = class {
     return job;
   }
 };
+
+// src/storage/disk-parsed-document-storage.ts
+var import_crypto3 = require("crypto");
+var import_fs4 = require("fs");
+var import_path4 = __toESM(require("path"));
+var syncProgressPath = ".knowhere-sdk/sync-progress.json";
+var DiskParsedDocumentStorage = class {
+  rootDirectory;
+  constructor(rootDirectory) {
+    this.rootDirectory = rootDirectory;
+  }
+  async readObject(params) {
+    const objectPath = this.getObjectPath(params);
+    try {
+      const body = await import_fs4.promises.readFile(objectPath);
+      const metadata = await this.readObjectMetadata(objectPath);
+      return {
+        ...params,
+        body,
+        contentType: metadata?.contentType,
+        contentLength: body.byteLength,
+        metadata: metadata?.metadata,
+        url: toFileUrl(objectPath)
+      };
+    } catch (error) {
+      if (isMissingFileError3(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async writeObject(params) {
+    const objectPath = this.getObjectPath(params);
+    await import_fs4.promises.mkdir(import_path4.default.dirname(objectPath), { recursive: true });
+    await import_fs4.promises.writeFile(objectPath, params.body);
+    await this.writeObjectMetadata(objectPath, {
+      contentType: params.contentType,
+      metadata: params.metadata
+    });
+    return {
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      path: params.path,
+      url: toFileUrl(objectPath)
+    };
+  }
+  async headObject(params) {
+    const objectPath = this.getObjectPath(params);
+    try {
+      const stat = await import_fs4.promises.stat(objectPath);
+      const metadata = await this.readObjectMetadata(objectPath);
+      return {
+        ...params,
+        contentType: metadata?.contentType,
+        contentLength: stat.size,
+        metadata: metadata?.metadata,
+        url: toFileUrl(objectPath)
+      };
+    } catch (error) {
+      if (isMissingFileError3(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async getObjectUrl(params) {
+    const head = await this.headObject(params);
+    return head?.url ?? null;
+  }
+  async deletePrefix(params) {
+    await import_fs4.promises.rm(this.getRevisionDirectory(params.documentId, params.revisionKey), {
+      recursive: true,
+      force: true
+    });
+  }
+  async readSyncProgress(params) {
+    return this.readOptionalJson({
+      ...params,
+      path: syncProgressPath
+    });
+  }
+  async writeSyncProgress(params) {
+    await this.writeObject({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      path: syncProgressPath,
+      body: Buffer.from(JSON.stringify(params, null, 2), "utf8"),
+      contentType: "application/json; charset=utf-8"
+    });
+  }
+  getObjectPath(params) {
+    const revisionDirectory = this.getRevisionDirectory(params.documentId, params.revisionKey);
+    const objectPath = import_path4.default.resolve(revisionDirectory, normalizeRelativeStoragePath(params.path));
+    if (!isPathInsideDirectory2(objectPath, revisionDirectory)) {
+      throw new Error(`Parsed document object path resolves outside storage: ${params.path}`);
+    }
+    return objectPath;
+  }
+  getRevisionDirectory(documentId, revisionKey) {
+    return import_path4.default.join(this.rootDirectory, hashPathPart(documentId), hashPathPart(revisionKey));
+  }
+  async readOptionalJson(params) {
+    const object = await this.readObject(params);
+    if (!object) {
+      return null;
+    }
+    return JSON.parse(Buffer.from(object.body).toString("utf8"));
+  }
+  async readObjectMetadata(filePath) {
+    try {
+      return JSON.parse(
+        await import_fs4.promises.readFile(getMetadataPath(filePath), "utf8")
+      );
+    } catch (error) {
+      if (isMissingFileError3(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async writeObjectMetadata(filePath, metadata) {
+    await import_fs4.promises.writeFile(getMetadataPath(filePath), JSON.stringify(metadata, null, 2), {
+      encoding: "utf8",
+      flag: "w"
+    });
+  }
+};
+function getMetadataPath(filePath) {
+  return `${filePath}.metadata.json`;
+}
+function hashPathPart(value) {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new Error("Parsed document storage path part must be a non-empty value.");
+  }
+  return (0, import_crypto3.createHash)("sha256").update(normalized).digest("hex").slice(0, 24);
+}
+function normalizeRelativeStoragePath(value) {
+  const normalized = value.replaceAll("\\", "/").replace(/^\.\/+/, "");
+  if (normalized.length === 0 || normalized.includes("\0") || normalized.startsWith("/") || normalized.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
+    throw new Error(`Invalid parsed storage path: ${value}`);
+  }
+  return normalized;
+}
+function isPathInsideDirectory2(filePath, directory) {
+  const relative = import_path4.default.relative(directory, filePath);
+  return relative === "" || !relative.startsWith("..") && !import_path4.default.isAbsolute(relative);
+}
+function toFileUrl(filePath) {
+  return `file://${filePath}`;
+}
+function isMissingFileError3(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
@@ -2522,6 +4438,7 @@ var Knowhere = class {
   BadRequestError,
   ChecksumError,
   ConflictError,
+  DiskParsedDocumentStorage,
   Documents,
   GatewayTimeoutError,
   InternalServerError,
@@ -2542,5 +4459,7 @@ var Knowhere = class {
   ServiceUnavailableError,
   TimeoutError,
   VERSION,
-  ValidationError
+  ValidationError,
+  storeParseResultAssets,
+  syncParseResultToParsedDocumentStorage
 });