@ontos-ai/knowhere-sdk 2.0.0 → 2.1.1

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,514 @@ 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";
+var snapshotManifestKey = "manifest/current.json";
+var snapshotIndexKey = "index.json";
+var defaultSnapshotChunkPageSize = 200;
+var snapshotJsonContentType = "application/json; 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);
+  const snapshot = await storeParsedSnapshot({
+    result: normalizedResult,
+    assetUrlsByFilePath,
+    keyPrefix: normalizedKeyPrefix,
+    options
+  });
+  return {
+    result: normalizedResult,
+    assetUrlsByFilePath,
+    snapshot
+  };
+}
+async function storeParsedSnapshot(input) {
+  const pageSize = normalizeSnapshotChunkPageSize(input.options.chunkPageSize);
+  const totalChunks = input.result.chunks.length;
+  const totalPages = Math.max(1, Math.ceil(totalChunks / pageSize));
+  const chunkPageReferences = [];
+  const chunkPageUrlsByPage = {};
+  for (let page = 1; page <= totalPages; page += 1) {
+    const pageChunks = input.result.chunks.slice((page - 1) * pageSize, page * pageSize);
+    const pageKey = `${input.keyPrefix}/chunks/page-${page}.json`;
+    const chunkPage = {
+      version: 1,
+      jobId: input.result.jobId,
+      revisionKey: input.options.revisionKey ?? input.result.jobId,
+      documentId: input.result.documentId,
+      namespace: input.result.namespace,
+      sourceFileName: input.result.manifest.sourceFileName,
+      page,
+      pageSize,
+      total: totalChunks,
+      totalPages,
+      chunks: pageChunks.map(
+        (chunk, index) => toSnapshotChunk(chunk, (page - 1) * pageSize + index + 1)
+      )
+    };
+    const pageUrl = await writeJsonObject({
+      key: pageKey,
+      value: chunkPage,
+      adapter: input.options.adapter
+    });
+    if (pageUrl) chunkPageUrlsByPage[page] = pageUrl;
+    chunkPageReferences.push({
+      page,
+      pageSize,
+      chunkCount: pageChunks.length,
+      key: pageKey,
+      url: pageUrl
+    });
+  }
+  const manifest = {
+    version: 1,
+    kind: "knowhere-parsed-result-snapshot",
+    jobId: input.result.jobId,
+    revisionKey: input.options.revisionKey ?? input.result.jobId,
+    documentId: input.result.documentId,
+    namespace: input.result.namespace,
+    sourceFileName: input.result.manifest.sourceFileName,
+    totalChunks,
+    typeCounts: countSnapshotChunkTypes(input.result.chunks),
+    chunkPageSize: pageSize,
+    chunkPages: chunkPageReferences,
+    assetUrlsByFilePath: input.assetUrlsByFilePath,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const manifestKey = `${input.keyPrefix}/${snapshotManifestKey}`;
+  const indexKey = `${input.keyPrefix}/${snapshotIndexKey}`;
+  const manifestUrl = await writeJsonObject({
+    key: manifestKey,
+    value: manifest,
+    adapter: input.options.adapter
+  });
+  const indexUrl = await writeJsonObject({
+    key: indexKey,
+    value: manifest,
+    adapter: input.options.adapter
+  });
+  return {
+    manifest,
+    manifestKey,
+    manifestUrl,
+    indexKey,
+    indexUrl,
+    chunkPageUrlsByPage
+  };
+}
+function countSnapshotChunkTypes(chunks) {
+  return chunks.reduce(
+    (counts, chunk) => {
+      counts[chunk.type] += 1;
+      return counts;
+    },
+    { text: 0, image: 0, table: 0, page: 0 }
+  );
+}
+async function writeJsonObject(input) {
+  const result = await input.adapter.writeObject({
+    key: input.key,
+    body: Buffer.from(JSON.stringify(input.value, null, 2), "utf8"),
+    contentType: snapshotJsonContentType,
+    metadata: {
+      kind: "knowhere-parsed-result-snapshot"
+    }
+  });
+  return result.url ?? await input.adapter.getObjectUrl?.(result.key) ?? void 0;
+}
+function normalizeSnapshotChunkPageSize(value) {
+  if (!Number.isInteger(value) || value === void 0) return defaultSnapshotChunkPageSize;
+  return Math.min(Math.max(value, 1), 1e3);
+}
+function toSnapshotChunk(chunk, position) {
+  const filePath = getSnapshotChunkFilePath(chunk);
+  return {
+    id: chunk.chunkId,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.type,
+    contentSource: chunk.contentSource,
+    content: chunk.content,
+    sectionPath: normalizeSnapshotSectionPath(chunk.path),
+    sourceChunkPath: chunk.path,
+    filePath,
+    sortOrder: position,
+    metadata: cloneChunkMetadata(chunk.metadata),
+    assetUrl: getSnapshotChunkAssetUrl(chunk)
+  };
+}
+function normalizeSnapshotSectionPath(path4) {
+  return path4.length > 0 ? path4 : void 0;
+}
+function getSnapshotChunkFilePath(chunk) {
+  if (chunk.type === "image" || chunk.type === "table") {
+    return chunk.filePath;
+  }
+  const filePath = chunk.metadata.filePath;
+  return typeof filePath === "string" ? filePath : void 0;
+}
+function getSnapshotChunkAssetUrl(chunk) {
+  return chunk.type === "image" || chunk.type === "table" ? chunk.assetUrl : void 0;
+}
+function cloneChunkMetadata(metadata) {
+  return { ...metadata };
+}
+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 parsedStorageKeyPrefix = "parsed";
+var manifestStoragePath = "manifest/current.json";
+var indexStoragePath = "index.json";
+var chunkPagePathPattern = /^chunks\/page-(\d+)\.json$/;
+async function syncParseResultToParsedDocumentStorage(params) {
+  const documentId = params.documentId ?? params.result.documentId ?? params.result.jobId;
+  const revisionKey = params.revisionKey ?? params.result.jobId;
+  const adapter = createParsedDocumentObjectStorageAdapter({
+    storage: params.storage,
+    documentId,
+    revisionKey
+  });
+  const stored = await storeParseResultAssets(params.result, {
+    adapter,
+    keyPrefix: parsedStorageKeyPrefix,
+    chunkPageSize: params.chunkPageSize,
+    revisionKey
+  });
+  return {
+    result: stored.result,
+    snapshot: stored.snapshot,
+    documentId,
+    revisionKey
+  };
+}
+function createParsedDocumentObjectStorageAdapter(params) {
+  return {
+    writeObject: (input) => writeParsedStorageObject(params, input),
+    headObject: (key) => headParsedStorageObject(params, key),
+    getObjectUrl: (key) => getParsedStorageObjectUrl(params, key)
+  };
+}
+async function writeParsedStorageObject(params, input) {
+  const storagePath = stripParsedStorageKeyPrefix(input.key);
+  if (storagePath === manifestStoragePath) {
+    const manifest = JSON.parse(
+      Buffer.from(input.body).toString("utf8")
+    );
+    await params.storage.writeManifest({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      manifest
+    });
+    return { key: input.key };
+  }
+  if (storagePath === indexStoragePath) {
+    return { key: input.key };
+  }
+  const chunkPageMatch = storagePath.match(chunkPagePathPattern);
+  if (chunkPageMatch) {
+    const page = JSON.parse(
+      Buffer.from(input.body).toString("utf8")
+    );
+    await params.storage.writeChunkPage({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      page
+    });
+    return { key: input.key };
+  }
+  const stored = await params.storage.writeAsset({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    sourcePath: storagePath,
+    body: input.body,
+    contentType: input.contentType,
+    metadata: input.metadata
+  });
+  return {
+    key: input.key,
+    url: stored.url
+  };
+}
+async function headParsedStorageObject(params, key) {
+  const storagePath = stripParsedStorageKeyPrefix(key);
+  if (storagePath === manifestStoragePath || storagePath === indexStoragePath || chunkPagePathPattern.test(storagePath)) {
+    return null;
+  }
+  const url = await params.storage.getAssetUrl({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    sourcePath: storagePath
+  });
+  return url ? {
+    key,
+    url
+  } : null;
+}
+async function getParsedStorageObjectUrl(params, key) {
+  const storagePath = stripParsedStorageKeyPrefix(key);
+  if (storagePath === manifestStoragePath || storagePath === indexStoragePath || chunkPagePathPattern.test(storagePath)) {
+    return null;
+  }
+  return params.storage.getAssetUrl({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    sourcePath: storagePath
+  });
+}
+function stripParsedStorageKeyPrefix(key) {
+  const prefix = `${parsedStorageKeyPrefix}/`;
+  return key.startsWith(prefix) ? key.slice(prefix.length) : key;
+}
+
 // src/knowledge/local-store.ts
 var import_crypto = require("crypto");
 var import_os = __toESM(require("os"));
@@ -1791,27 +2318,62 @@ 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_MAX_SYNC_ASSETS = 20;
+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 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,
+      parsedSnapshot: storedAssets.snapshot
+    };
+  }
+  /** @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 +2404,100 @@ 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,
+      parsedSnapshot: syncedStorage.snapshot ?? storedAssets.snapshot
+    };
+  }
+  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,
+      parsedSnapshot: stored.parsedSnapshot
+    };
+  }
+  /** @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,
+        chunkPageSize: parsedStorageConfig.limits?.chunkPageSize
+      });
+      return {
+        documentId: synced2.documentId,
+        revisionKey: synced2.revisionKey,
+        completed: true,
+        manifest: synced2.snapshot?.manifest
+      };
+    }
+    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,
+      chunkPageSize: parsedStorageConfig.limits?.chunkPageSize
+    });
+    return {
+      documentId: synced.documentId,
+      revisionKey: synced.revisionKey,
+      completed: true,
+      manifest: synced.snapshot?.manifest
+    };
+  }
+  async syncParseResultToConfiguredStorage(result) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return { result };
+    }
+    const synced = await syncParseResultToParsedDocumentStorage({
+      result,
+      storage: parsedStorageConfig.storage,
+      chunkPageSize: parsedStorageConfig.limits?.chunkPageSize
+    });
+    return {
+      result: synced.result,
+      snapshot: synced.snapshot
+    };
+  }
+  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 +2507,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 +2544,7 @@ var Knowledge = class _Knowledge {
       };
     }
     try {
-      const cached = await this.cacheJobResult({
+      const cached = await this.importJobResult({
         jobId,
         localDocumentId: trackedJob.localDocumentId
       });
@@ -1921,6 +2569,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 +2591,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 +2615,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 +2701,7 @@ var Knowledge = class _Knowledge {
       });
     }
     if (normalized.jobId) {
-      return this.cacheJobResult({
+      return this.importJobResult({
         jobId: normalized.jobId,
         localDocumentId: normalized.localDocumentId
       });
@@ -2051,31 +2721,677 @@ 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: shouldRequestRemoteAssetUrls(
+        params.assetUrlPolicy,
+        this.parsedStorageConfig
+      )
+    });
+    const revisionKey = getRemoteRevisionKey(remotePage);
+    const stored = await this.tryReadChunksFromParsedStorage({
+      documentId,
+      revisionKey,
+      params
+    });
+    if (stored) {
+      return stored;
+    }
+    const chunks = await this.toRemoteReadChunks({
+      documentId,
+      revisionKey,
+      chunks: remotePage.chunks,
+      assetUrlPolicy: params.assetUrlPolicy
+    });
+    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: shouldRequestRemoteAssetUrls(
+        params.assetUrlPolicy,
+        this.parsedStorageConfig
+      )
     });
-    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;
-  }
-};
-function normalizeDocumentReference(reference) {
-  if (typeof reference === "string") {
-    return { localDocumentId: reference };
+    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: shouldRequestRemoteAssetUrls(
+          params.assetUrlPolicy,
+          this.parsedStorageConfig
+        )
+      });
+    }
+    const chunks = await this.toRemoteReadChunks({
+      documentId,
+      revisionKey,
+      chunks: selected.slice(0, limit),
+      assetUrlPolicy: params.assetUrlPolicy
+    });
+    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
+    };
   }
-  return reference;
-}
-function looksLikeRemoteDocumentId(value) {
-  return REMOTE_DOCUMENT_ID_PATTERN.test(value);
+  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: false
+    });
+    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: false
+      });
+    }
+  }
+  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: false
+    });
+    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: false
+      });
+    }
+    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 parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return null;
+    }
+    const manifest = await this.readFreshParsedStorageManifest(
+      params.documentId,
+      params.revisionKey
+    );
+    if (!manifest) {
+      return null;
+    }
+    const pageParams = getReadPageParams(params.params);
+    const indexedChunks = await this.readStoredSnapshotChunks({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      manifest,
+      chunkType: params.params.chunkType
+    });
+    if (!indexedChunks) {
+      return null;
+    }
+    const scopedChunks = indexedChunks.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 = applyAssetUrlPolicyToReadChunks(
+      selected.map(toReadChunk),
+      params.params.assetUrlPolicy
+    );
+    const totalChunks = scopedChunks.length;
+    return {
+      document: createStoredKnowledgeDocument({
+        documentId: params.documentId,
+        manifest,
+        revisionKey: params.revisionKey,
+        typeCounts: countIndexedTypes(indexedChunks)
+      }),
+      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 parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return null;
+    }
+    const manifest = await this.readFreshParsedStorageManifest(
+      params.documentId,
+      params.revisionKey
+    );
+    if (!manifest) {
+      return null;
+    }
+    const indexedChunks = await this.readStoredSnapshotChunks({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      manifest,
+      chunkType: params.params.chunkType
+    });
+    if (!indexedChunks) {
+      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 = indexedChunks.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,
+              manifest,
+              revisionKey: params.revisionKey,
+              typeCounts: countIndexedTypes(indexedChunks)
+            }),
+            matches,
+            scannedChunks,
+            truncated: true
+          };
+        }
+      }
+    }
+    return {
+      document: createStoredKnowledgeDocument({
+        documentId: params.documentId,
+        manifest,
+        revisionKey: params.revisionKey,
+        typeCounts: countIndexedTypes(indexedChunks)
+      }),
+      matches,
+      scannedChunks,
+      truncated: false
+    };
+  }
+  async tryReadOutlineFromParsedStorage(documentId, revisionKey) {
+    const manifest = await this.readFreshParsedStorageManifest(documentId, revisionKey);
+    if (!manifest) {
+      return null;
+    }
+    const indexedChunks = await this.readStoredSnapshotChunks({
+      documentId,
+      revisionKey,
+      manifest
+    });
+    if (!indexedChunks) {
+      return null;
+    }
+    const sections = buildFlatSectionsFromIndexedChunks(indexedChunks);
+    const typeCounts = countIndexedTypes(indexedChunks);
+    return {
+      document: createStoredKnowledgeDocument({
+        documentId,
+        manifest,
+        revisionKey,
+        typeCounts
+      }),
+      totalChunks: manifest.totalChunks,
+      typeCounts,
+      sections,
+      sectionTree: nestSections(sections),
+      truncated: false
+    };
+  }
+  async readFreshParsedStorageManifest(documentId, revisionKey) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return null;
+    }
+    const manifest = await parsedStorageConfig.storage.readManifest({
+      documentId,
+      revisionKey
+    });
+    if (!manifest || !isFreshManifest(manifest, revisionKey)) {
+      return null;
+    }
+    return manifest;
+  }
+  async readStoredSnapshotChunks(params) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return null;
+    }
+    const chunks = [];
+    for (const pageReference of params.manifest.chunkPages) {
+      const page = await parsedStorageConfig.storage.readChunkPage({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        page: pageReference.page,
+        chunkType: params.chunkType
+      });
+      if (!page) {
+        return null;
+      }
+      chunks.push(
+        ...page.chunks.filter((chunk) => !params.chunkType || chunk.chunkType === params.chunkType).map(toIndexedSnapshotChunk)
+      );
+    }
+    return chunks.sort((left, right) => left.position - right.position);
+  }
+  async toRemoteReadChunks(params) {
+    const readChunks = params.chunks.map((chunk) => toRemoteReadChunk(chunk));
+    if (params.assetUrlPolicy === "durable") {
+      return this.hardenReadChunkAssetUrls({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        chunks: readChunks
+      });
+    }
+    return applyAssetUrlPolicyToReadChunks(readChunks, params.assetUrlPolicy);
+  }
+  async hardenReadChunkAssetUrls(params) {
+    const parsedStorageConfig = this.parsedStorageConfig;
+    if (!parsedStorageConfig) {
+      return applyAssetUrlPolicyToReadChunks(params.chunks, "none");
+    }
+    const hardenedChunks = [];
+    for (const chunk of params.chunks) {
+      hardenedChunks.push(
+        await hardenReadChunkAssetUrls({
+          storageConfig: parsedStorageConfig,
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          chunk
+        })
+      );
+    }
+    return hardenedChunks;
+  }
+  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,
+          nextAssetIndex: 0,
+          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 limits = getParsedStorageLimits(params.parsedStorageConfig.limits);
+    const existingProgress = params.revisionKey ? await params.parsedStorageConfig.storage.readSyncProgress({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey
+    }) : null;
+    let nextPage = existingProgress?.status === "running" ? existingProgress.nextChunkPage : 1;
+    let response = await this.client.documents.listChunks(params.documentId, {
+      page: nextPage,
+      pageSize: limits.remotePageSize,
+      includeAssetUrls: true
+    });
+    const revisionKey = params.revisionKey ?? getRemoteRevisionKey(response);
+    if (params.revisionKey && getRemoteRevisionKey(response) !== params.revisionKey) {
+      response = await this.client.documents.listChunks(params.documentId, {
+        page: 1,
+        pageSize: limits.remotePageSize,
+        includeAssetUrls: true
+      });
+      nextPage = 1;
+    }
+    const totalPages = response.pagination.totalPages;
+    const chunkPages = [];
+    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
+        });
+      }
+      const readChunks = await this.hardenReadChunkAssetUrls({
+        documentId: params.documentId,
+        revisionKey,
+        chunks: response.chunks.map(toRemoteReadChunk)
+      });
+      const page = toSnapshotChunkPageFromReadChunks({
+        response,
+        revisionKey,
+        chunks: readChunks
+      });
+      await params.parsedStorageConfig.storage.writeChunkPage({
+        documentId: params.documentId,
+        revisionKey,
+        page
+      });
+      chunkPages.push(page);
+      nextPage += 1;
+      syncedPages += 1;
+      await params.parsedStorageConfig.storage.writeSyncProgress({
+        documentId: params.documentId,
+        revisionKey,
+        nextChunkPage: nextPage,
+        nextAssetIndex: 0,
+        status: "running",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (syncedPages >= limits.maxPagesPerSync || Date.now() - startedAt >= limits.syncDeadlineMs) {
+        return {
+          documentId: params.documentId,
+          revisionKey,
+          completed: false
+        };
+      }
+    }
+    const manifest = createRemoteSnapshotManifest({
+      response,
+      revisionKey,
+      chunkPages
+    });
+    await params.parsedStorageConfig.storage.writeManifest({
+      documentId: params.documentId,
+      revisionKey,
+      manifest
+    });
+    await params.parsedStorageConfig.storage.writeSyncProgress({
+      documentId: params.documentId,
+      revisionKey,
+      nextChunkPage: totalPages + 1,
+      nextAssetIndex: 0,
+      status: "completed",
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return {
+      documentId: params.documentId,
+      revisionKey,
+      completed: true,
+      manifest
+    };
+  }
+  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
+    });
+    if (!response.jobId) {
+      throw new Error(
+        `Cannot sync server document ${documentId}: current published job id was not returned.`
+      );
+    }
+    return response.jobId;
+  }
+};
+function normalizeDocumentReference(reference) {
+  if (typeof reference === "string") {
+    return { localDocumentId: reference };
+  }
+  return reference;
+}
+function looksLikeRemoteDocumentId(value) {
+  return REMOTE_DOCUMENT_ID_PATTERN.test(value);
 }
 function createLocalDocumentIdForRemote(documentId) {
   if (SAFE_LOCAL_DOCUMENT_ID_PATTERN.test(documentId) && !documentId.includes("..") && !documentId.includes("/") && !documentId.includes("\\")) {
@@ -2084,6 +3400,488 @@ 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 {
+    chunkPageSize: clampLimit(limits?.chunkPageSize, DEFAULT_REMOTE_SCAN_PAGE_SIZE, MAX_PAGE_SIZE),
+    remotePageSize: clampLimit(
+      limits?.remotePageSize,
+      DEFAULT_REMOTE_SCAN_PAGE_SIZE,
+      MAX_PAGE_SIZE
+    ),
+    maxPagesPerSync: clampLimit(limits?.maxPagesPerSync, DEFAULT_MAX_SYNC_PAGES, 1e3),
+    maxAssetsPerSync: clampLimit(limits?.maxAssetsPerSync, DEFAULT_MAX_SYNC_ASSETS, 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 || params.assetUrlPolicy !== 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, pageSize, and assetUrlPolicy 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 shouldRequestRemoteAssetUrls(assetUrlPolicy, parsedStorageConfig) {
+  return assetUrlPolicy === "durable" && parsedStorageConfig !== void 0;
+}
+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 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 createStoredKnowledgeDocument(params) {
+  return {
+    localDocumentId: params.documentId,
+    jobId: params.manifest.jobId || params.revisionKey,
+    documentId: params.manifest.documentId ?? params.documentId,
+    namespace: params.manifest.namespace,
+    sourceFileName: params.manifest.sourceFileName,
+    chunkCount: params.manifest.totalChunks,
+    typeCounts: params.typeCounts,
+    resultDirectoryPath: `parsed-storage:${params.documentId}`,
+    createdAt: new Date(params.manifest.createdAt),
+    updatedAt: new Date(params.manifest.createdAt)
+  };
+}
+function isFreshManifest(manifest, revisionKey) {
+  return (manifest.revisionKey ?? manifest.jobId) === revisionKey;
+}
+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 toIndexedSnapshotChunk(chunk) {
+  return toIndexedReadChunk({
+    position: chunk.sortOrder,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    contentSource: chunk.contentSource,
+    content: chunk.content,
+    readableContent: chunk.chunkType === "page" && typeof chunk.metadata.summary === "string" && chunk.metadata.summary.trim().length > 0 ? chunk.metadata.summary : chunk.content,
+    sectionPath: chunk.sectionPath ?? "",
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    assetUrl: chunk.assetUrl,
+    pageNumbers: getChunkPageNumbers(chunk.metadata),
+    metadata: cloneMetadata(chunk.metadata)
+  });
+}
+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;
+}
+function applyAssetUrlPolicyToReadChunks(chunks, assetUrlPolicy) {
+  if (assetUrlPolicy !== "none") {
+    return chunks.map((chunk) => ({
+      ...chunk,
+      metadata: cloneMetadata(chunk.metadata)
+    }));
+  }
+  return chunks.map((chunk) => ({
+    ...chunk,
+    assetUrl: void 0,
+    metadata: removeAssetUrlsFromMetadata(chunk.metadata)
+  }));
+}
+async function hardenReadChunkAssetUrls(params) {
+  const metadata = cloneMetadata(params.chunk.metadata);
+  const assetUrl = await hardenPrimaryAssetUrl(params, metadata);
+  const pageAssets = await hardenPageAssetUrls(params, metadata);
+  if (pageAssets) {
+    metadata.pageAssets = pageAssets;
+  }
+  return {
+    ...params.chunk,
+    assetUrl,
+    metadata
+  };
+}
+async function hardenPrimaryAssetUrl(params, metadata) {
+  if (!params.chunk.assetUrl || !params.chunk.filePath) {
+    return void 0;
+  }
+  return writeDurableAssetUrl({
+    storageConfig: params.storageConfig,
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    sourcePath: params.chunk.filePath,
+    sourceUrl: params.chunk.assetUrl,
+    fallbackContentType: inferContentTypeFromPath(params.chunk.filePath),
+    metadata: {
+      chunkId: params.chunk.chunkId,
+      chunkType: params.chunk.chunkType,
+      sourcePath: params.chunk.filePath,
+      ...stringifyFlatMetadata(metadata)
+    }
+  });
+}
+async function hardenPageAssetUrls(params, metadata) {
+  const pageAssets = toUnknownArray(metadata.pageAssets);
+  if (!pageAssets) {
+    return void 0;
+  }
+  const hardenedAssets = [];
+  for (const pageAsset of pageAssets) {
+    if (!isRecord2(pageAsset)) {
+      hardenedAssets.push(pageAsset);
+      continue;
+    }
+    const artifactRef = pageAsset.artifactRef;
+    const sourceUrl = pageAsset.assetUrl;
+    if (typeof artifactRef !== "string" || typeof sourceUrl !== "string") {
+      hardenedAssets.push(removeAssetUrlField(pageAsset));
+      continue;
+    }
+    const durableUrl = await writeDurableAssetUrl({
+      storageConfig: params.storageConfig,
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      sourcePath: artifactRef,
+      sourceUrl,
+      fallbackContentType: typeof pageAsset.contentType === "string" ? pageAsset.contentType : inferContentTypeFromPath(artifactRef),
+      metadata: {
+        chunkId: params.chunk.chunkId,
+        chunkType: params.chunk.chunkType,
+        sourcePath: artifactRef
+      }
+    });
+    const rest = removeAssetUrlField(pageAsset);
+    hardenedAssets.push(durableUrl ? { ...rest, assetUrl: durableUrl } : rest);
+  }
+  return hardenedAssets;
+}
+async function writeDurableAssetUrl(params) {
+  const existingUrl = await params.storageConfig.storage.getAssetUrl({
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    sourcePath: params.sourcePath
+  });
+  if (existingUrl) {
+    return existingUrl;
+  }
+  try {
+    const fetched = await fetchAsset(params.sourceUrl, params.fallbackContentType);
+    const written = await params.storageConfig.storage.writeAsset({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      sourcePath: params.sourcePath,
+      body: fetched.body,
+      contentType: fetched.contentType,
+      metadata: params.metadata
+    });
+    return written.url ?? await params.storageConfig.storage.getAssetUrl({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      sourcePath: params.sourcePath
+    }) ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function fetchAsset(sourceUrl, fallbackContentType) {
+  const response = await fetch(sourceUrl);
+  if (!response.ok) {
+    throw new Error(`Unable to fetch parsed asset: ${response.status}`);
+  }
+  return {
+    body: new Uint8Array(await response.arrayBuffer()),
+    contentType: response.headers.get("content-type") ?? fallbackContentType
+  };
+}
+function removeAssetUrlsFromMetadata(metadata) {
+  const cloned = cloneMetadata(metadata);
+  const pageAssets = toUnknownArray(cloned.pageAssets);
+  if (!pageAssets) {
+    return cloned;
+  }
+  cloned.pageAssets = pageAssets.map((pageAsset) => {
+    if (!isRecord2(pageAsset)) {
+      return pageAsset;
+    }
+    return removeAssetUrlField(pageAsset);
+  });
+  return cloned;
+}
+function removeAssetUrlField(value) {
+  const cloned = { ...value };
+  delete cloned.assetUrl;
+  return cloned;
+}
+function toSnapshotChunkPageFromReadChunks(params) {
+  return {
+    version: 1,
+    jobId: params.response.jobId ?? params.revisionKey,
+    revisionKey: params.revisionKey,
+    documentId: params.response.documentId,
+    namespace: params.response.namespace,
+    sourceFileName: params.response.documentId,
+    page: params.response.pagination.page,
+    pageSize: params.response.pagination.pageSize,
+    total: params.response.pagination.total,
+    totalPages: params.response.pagination.totalPages,
+    chunks: params.chunks.map(toSnapshotChunkFromReadChunk)
+  };
+}
+function toSnapshotChunkFromReadChunk(chunk) {
+  return {
+    id: chunk.chunkId,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    contentSource: chunk.contentSource,
+    content: chunk.content,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    sortOrder: chunk.position,
+    metadata: cloneMetadata(chunk.metadata),
+    assetUrl: chunk.assetUrl
+  };
+}
+function createRemoteSnapshotManifest(params) {
+  return {
+    version: 1,
+    kind: "knowhere-parsed-result-snapshot",
+    jobId: params.response.jobId ?? params.revisionKey,
+    revisionKey: params.revisionKey,
+    documentId: params.response.documentId,
+    namespace: params.response.namespace,
+    sourceFileName: params.response.documentId,
+    totalChunks: params.response.pagination.total,
+    typeCounts: countSnapshotPagesTypes(params.chunkPages),
+    chunkPageSize: params.response.pagination.pageSize,
+    chunkPages: Array.from({ length: params.response.pagination.totalPages }, (_, index) => ({
+      page: index + 1,
+      pageSize: params.response.pagination.pageSize,
+      chunkCount: index + 1 === params.response.pagination.totalPages ? params.response.pagination.total - params.response.pagination.pageSize * (params.response.pagination.totalPages - 1) : params.response.pagination.pageSize,
+      key: `parsed/chunks/page-${index + 1}.json`
+    })),
+    assetUrlsByFilePath: {},
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function countSnapshotPagesTypes(pages) {
+  return pages.flatMap((page) => page.chunks).reduce(
+    (counts, chunk) => {
+      const chunkType = chunk.chunkType;
+      counts[chunkType] += 1;
+      return counts;
+    },
+    { text: 0, image: 0, table: 0, page: 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 stringifyFlatMetadata(metadata) {
+  const entries = Object.entries(metadata).flatMap(([key, value]) => {
+    if (typeof value === "string") {
+      return [[key, value]];
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      return [[key, String(value)]];
+    }
+    return [];
+  });
+  return Object.fromEntries(entries);
+}
+function toUnknownArray(value) {
+  return Array.isArray(value) ? value : null;
+}
+function inferContentTypeFromPath(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 indexChunks(result) {
   return result.chunks.map((chunk, index) => {
     const filePath = getChunkFilePath2(chunk);
@@ -2099,6 +3897,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 +3911,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 +3926,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 +3958,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 +4097,7 @@ function toReadChunk(chunk) {
     sectionPath: chunk.sectionPath,
     sourceChunkPath: chunk.sourceChunkPath,
     filePath: chunk.filePath,
+    assetUrl: chunk.assetUrl,
     pageNumbers: chunk.pageNumbers,
     metadata: chunk.metadata
   };
@@ -2472,7 +4274,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 +4322,145 @@ 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 DiskParsedDocumentStorage = class {
+  rootDirectory;
+  constructor(rootDirectory) {
+    this.rootDirectory = rootDirectory;
+  }
+  async readManifest(params) {
+    return this.readOptionalJson(
+      this.getManifestPath(params.documentId, params.revisionKey)
+    );
+  }
+  async writeManifest(params) {
+    await this.writeJson(
+      this.getManifestPath(params.documentId, params.revisionKey),
+      params.manifest
+    );
+  }
+  async readChunkPage(params) {
+    return this.readOptionalJson(
+      this.getChunkPagePath(params.documentId, params.revisionKey, params.page)
+    );
+  }
+  async writeChunkPage(params) {
+    await this.writeJson(
+      this.getChunkPagePath(params.documentId, params.revisionKey, params.page.page),
+      params.page
+    );
+  }
+  async writeAsset(params) {
+    const assetPath = this.getAssetPath(params.documentId, params.revisionKey, params.sourcePath);
+    await import_fs4.promises.mkdir(import_path4.default.dirname(assetPath), { recursive: true });
+    await import_fs4.promises.writeFile(assetPath, params.body);
+    await this.writeJson(`${assetPath}.metadata.json`, {
+      contentType: params.contentType,
+      metadata: params.metadata ?? {}
+    });
+    return {
+      sourcePath: params.sourcePath,
+      url: toFileUrl(assetPath)
+    };
+  }
+  async getAssetUrl(params) {
+    const assetPath = this.getAssetPath(params.documentId, params.revisionKey, params.sourcePath);
+    try {
+      await import_fs4.promises.access(assetPath);
+      return toFileUrl(assetPath);
+    } catch (error) {
+      if (isMissingFileError3(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async readSyncProgress(params) {
+    return this.readOptionalJson(
+      this.getProgressPath(params.documentId, params.revisionKey)
+    );
+  }
+  async writeSyncProgress(params) {
+    await this.writeJson(this.getProgressPath(params.documentId, params.revisionKey), params);
+  }
+  getManifestPath(documentId, revisionKey) {
+    return import_path4.default.join(
+      this.getRevisionDirectory(documentId, revisionKey),
+      "manifest",
+      "current.json"
+    );
+  }
+  getChunkPagePath(documentId, revisionKey, page) {
+    return import_path4.default.join(
+      this.getRevisionDirectory(documentId, revisionKey),
+      "chunks",
+      `page-${page}.json`
+    );
+  }
+  getProgressPath(documentId, revisionKey) {
+    return import_path4.default.join(this.getRevisionDirectory(documentId, revisionKey), "sync-progress.json");
+  }
+  getAssetPath(documentId, revisionKey, sourcePath) {
+    const normalizedSourcePath = normalizeRelativeStoragePath(sourcePath);
+    const assetPath = import_path4.default.resolve(
+      this.getRevisionDirectory(documentId, revisionKey),
+      "assets",
+      normalizedSourcePath
+    );
+    const assetsDirectory = import_path4.default.resolve(
+      this.getRevisionDirectory(documentId, revisionKey),
+      "assets"
+    );
+    if (!isPathInsideDirectory2(assetPath, assetsDirectory)) {
+      throw new Error(`Parsed asset path resolves outside storage: ${sourcePath}`);
+    }
+    return assetPath;
+  }
+  getRevisionDirectory(documentId, revisionKey) {
+    return import_path4.default.join(this.rootDirectory, hashPathPart(documentId), hashPathPart(revisionKey));
+  }
+  async readOptionalJson(filePath) {
+    try {
+      return JSON.parse(await import_fs4.promises.readFile(filePath, "utf8"));
+    } catch (error) {
+      if (isMissingFileError3(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async writeJson(filePath, value) {
+    await import_fs4.promises.mkdir(import_path4.default.dirname(filePath), { recursive: true });
+    await import_fs4.promises.writeFile(filePath, JSON.stringify(value, null, 2), {
+      encoding: "utf8",
+      flag: "w"
+    });
+  }
+};
+function hashPathPart(value) {
+  return (0, import_crypto3.createHash)("sha256").update(value).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 +4468,7 @@ var Knowhere = class {
   BadRequestError,
   ChecksumError,
   ConflictError,
+  DiskParsedDocumentStorage,
   Documents,
   GatewayTimeoutError,
   InternalServerError,
@@ -2542,5 +4489,7 @@ var Knowhere = class {
   ServiceUnavailableError,
   TimeoutError,
   VERSION,
-  ValidationError
+  ValidationError,
+  storeParseResultAssets,
+  syncParseResultToParsedDocumentStorage
 });