@ontos-ai/knowhere-sdk 2.4.2 → 2.5.0

package/dist/index.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -15,17 +18,877 @@ var __copyProps = (to, from, except, desc) => {
       if (!__hasOwnProp.call(to, key) && key !== except)
         __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
   }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/constants.ts
+var DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES, DEFAULT_POLL_INTERVAL, MAX_POLL_INTERVAL, DEFAULT_POLL_TIMEOUT, POLL_INTERVAL_INCREASE_THRESHOLD, POLL_INTERVAL_MULTIPLIER, INITIAL_RETRY_DELAY, MAX_RETRY_DELAY, RETRY_DELAY_BASE, RETRYABLE_STATUS_CODES, TERMINAL_JOB_STATUSES, ENV;
+var init_constants = __esm({
+  "src/constants.ts"() {
+    "use strict";
+    DEFAULT_BASE_URL = "https://api.knowhereto.ai";
+    DEFAULT_TIMEOUT = 6e4;
+    DEFAULT_MAX_RETRIES = 5;
+    DEFAULT_POLL_INTERVAL = 1e4;
+    MAX_POLL_INTERVAL = 3e4;
+    DEFAULT_POLL_TIMEOUT = 18e5;
+    POLL_INTERVAL_INCREASE_THRESHOLD = 6e4;
+    POLL_INTERVAL_MULTIPLIER = 1.2;
+    INITIAL_RETRY_DELAY = 500;
+    MAX_RETRY_DELAY = 3e4;
+    RETRY_DELAY_BASE = 2;
+    RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([409, 429, 502, 503, 504]);
+    TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["done", "failed"]);
+    ENV = {
+      API_KEY: "KNOWHERE_API_KEY",
+      BASE_URL: "KNOWHERE_BASE_URL",
+      LOG_LEVEL: "KNOWHERE_LOG_LEVEL"
+    };
+  }
+});
+
+// src/errors/base.ts
+var KnowhereError, NetworkError, TimeoutError, PollingTimeoutError, ChecksumError, ValidationError, InvalidStateError;
+var init_base = __esm({
+  "src/errors/base.ts"() {
+    "use strict";
+    KnowhereError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "KnowhereError";
+        Object.setPrototypeOf(this, new.target.prototype);
+      }
+    };
+    NetworkError = class extends KnowhereError {
+      constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "NetworkError";
+      }
+      cause;
+    };
+    TimeoutError = class extends NetworkError {
+      constructor(message = "Request timed out") {
+        super(message);
+        this.name = "TimeoutError";
+      }
+    };
+    PollingTimeoutError = class extends KnowhereError {
+      constructor(message = "Polling timed out", elapsedMs) {
+        super(message);
+        this.elapsedMs = elapsedMs;
+        this.name = "PollingTimeoutError";
+      }
+      elapsedMs;
+    };
+    ChecksumError = class extends KnowhereError {
+      constructor(message = "Checksum verification failed", expected, actual) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "ChecksumError";
+      }
+      expected;
+      actual;
+    };
+    ValidationError = class extends KnowhereError {
+      constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+      }
+    };
+    InvalidStateError = class extends KnowhereError {
+      constructor(message) {
+        super(message);
+        this.name = "InvalidStateError";
+      }
+    };
+  }
+});
+
+// src/errors/parsed-document-archive-error.ts
+var ParsedDocumentArchiveError;
+var init_parsed_document_archive_error = __esm({
+  "src/errors/parsed-document-archive-error.ts"() {
+    "use strict";
+    init_base();
+    ParsedDocumentArchiveError = class extends KnowhereError {
+      code = "ARCHIVE_SPOOL_FAILED";
+      cause;
+      constructor(cause) {
+        super(
+          "Parsed result ZIP temporary storage is unavailable. Range-enabled object storage avoids temporary disk usage."
+        );
+        this.name = "ParsedDocumentArchiveError";
+        this.cause = cause;
+      }
+    };
+  }
+});
+
+// src/lib/utils.ts
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function snakeToCamel(str) {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function keysToCamel(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => keysToCamel(item));
+  }
+  if (typeof obj === "object" && obj.constructor === Object) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[snakeToCamel(key)] = keysToCamel(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function keysToSnake(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => keysToSnake(item));
+  }
+  if (typeof obj === "object" && obj.constructor === Object) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[camelToSnake(key)] = keysToSnake(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function parseDates(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => parseDates(item));
+  }
+  if (typeof obj === "object" && obj.constructor === Object) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if ((key.endsWith("At") || key.endsWith("Date")) && typeof value === "string" && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        result[key] = new Date(value);
+      } else {
+        result[key] = parseDates(value);
+      }
+    }
+    return result;
+  }
+  return obj;
+}
+function isTerminalStatus(status) {
+  return TERMINAL_JOB_STATUSES.has(status);
+}
+function enrichJobResult(jobResult) {
+  const computedProperties = {};
+  if (!Object.getOwnPropertyDescriptor(jobResult, "isTerminal")) {
+    computedProperties.isTerminal = {
+      get() {
+        return isTerminalStatus(this.status);
+      },
+      enumerable: true,
+      configurable: true
+    };
+  }
+  if (!Object.getOwnPropertyDescriptor(jobResult, "isDone")) {
+    computedProperties.isDone = {
+      get() {
+        return this.status === "done";
+      },
+      enumerable: true,
+      configurable: true
+    };
+  }
+  if (!Object.getOwnPropertyDescriptor(jobResult, "isFailed")) {
+    computedProperties.isFailed = {
+      get() {
+        return this.status === "failed";
+      },
+      enumerable: true,
+      configurable: true
+    };
+  }
+  if (Object.keys(computedProperties).length > 0) {
+    Object.defineProperties(jobResult, computedProperties);
+  }
+  return jobResult;
+}
+function enrichParseResult(parseResult2, scope) {
+  if (scope.namespace !== void 0) {
+    parseResult2.namespace = scope.namespace;
+  }
+  if (scope.documentId !== void 0) {
+    parseResult2.documentId = scope.documentId;
+  }
+  return parseResult2;
+}
+function sanitizePath(path4) {
+  let sanitized = path4.replace(/^\/+/, "");
+  sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
+  sanitized = sanitized.replace(/\\/g, "/");
+  return sanitized;
+}
+function getFileExtension(filename) {
+  const match = filename.match(/\.([^.]+)$/);
+  return match ? match[1].toLowerCase() : "";
+}
+function jitter(value, percent = 0.2) {
+  const randomFactor = 1 + (Math.random() * 2 - 1) * percent;
+  return Math.round(value * randomFactor);
+}
+var init_utils = __esm({
+  "src/lib/utils.ts"() {
+    "use strict";
+    init_constants();
+  }
+});
+
+// src/storage/parsed-document-storage.ts
+async function syncParseResultToParsedDocumentStorage(params) {
+  const documentId = params.documentId ?? params.result.documentId ?? params.result.jobId;
+  const revisionKey = params.revisionKey ?? params.result.jobId;
+  for await (const object of collectResultLayoutObjects(params.result)) {
+    params.signal?.throwIfAborted();
+    await params.storage.writeObject({
+      documentId,
+      revisionKey,
+      ...object
+    });
+  }
+  await params.beforeCommit?.();
+  params.signal?.throwIfAborted();
+  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 storedPaths = /* @__PURE__ */ new Set();
+  let zip;
+  try {
+    zip = await import_jszip3.default.loadAsync(result.rawZip);
+  } catch {
+  }
+  if (zip) {
+    for (const entry of Object.values(zip.files)) {
+      if (entry.dir || entry.name === "result.zip") continue;
+      const path4 = normalizeResultPath(entry.name);
+      if (isSdkMetadataPath(path4)) continue;
+      storedPaths.add(path4);
+      yield {
+        path: path4,
+        body: await entry.async("nodebuffer"),
+        contentType: inferContentTypeFromPath(path4)
+      };
+    }
+  }
+  for (const object of generateMissingResultObjects(result, storedPaths)) yield object;
+}
+function* generateMissingResultObjects(result, storedPaths) {
+  if (!storedPaths.has("manifest.json")) yield createJsonObject("manifest.json", result.manifest);
+  if (!storedPaths.has("chunks.json"))
+    yield createJsonObject("chunks.json", keysToSnake(serializeChunks2(result.chunks)));
+  if (!storedPaths.has("doc_nav.json") && result.docNav)
+    yield createJsonObject("doc_nav.json", result.docNav);
+  if (!storedPaths.has("full.md") && result.fullMarkdown)
+    yield createTextObject("full.md", result.fullMarkdown, markdownContentType);
+  if (!storedPaths.has("chunks_slim.json") && result.chunksSlim)
+    yield createJsonObject("chunks_slim.json", { chunks: result.chunksSlim });
+  if (!storedPaths.has("hierarchy.json") && result.hierarchy)
+    yield createJsonObject("hierarchy.json", result.hierarchy);
+  if (!storedPaths.has("toc_hierarchies.json") && result.tocHierarchies)
+    yield createJsonObject("toc_hierarchies.json", result.tocHierarchies);
+  if (!storedPaths.has("kb.csv") && result.kbCsv)
+    yield createTextObject("kb.csv", result.kbCsv, csvContentType);
+  if (!storedPaths.has("hierarchy_view.html") && result.hierarchyViewHtml)
+    yield createTextObject("hierarchy_view.html", result.hierarchyViewHtml, htmlContentType);
+  for (const chunk of result.imageChunks) {
+    const path4 = normalizeResultPath(chunk.filePath);
+    if (storedPaths.has(path4)) continue;
+    yield {
+      path: path4,
+      body: chunk.data,
+      contentType: inferContentTypeFromPath(path4),
+      metadata: { chunkId: chunk.chunkId, chunkType: chunk.type, sourcePath: chunk.filePath }
+    };
+  }
+  for (const chunk of result.tableChunks) {
+    const path4 = normalizeResultPath(chunk.filePath);
+    if (storedPaths.has(path4)) continue;
+    yield {
+      path: path4,
+      body: Buffer.from(chunk.html, "utf8"),
+      contentType: htmlContentType,
+      metadata: { chunkId: chunk.chunkId, chunkType: chunk.type, sourcePath: chunk.filePath }
+    };
+  }
+}
+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/");
+}
+var import_jszip3, parsedDocumentCommitPath, jsonContentType, markdownContentType, csvContentType, htmlContentType, binaryContentType;
+var init_parsed_document_storage = __esm({
+  "src/storage/parsed-document-storage.ts"() {
+    "use strict";
+    import_jszip3 = __toESM(require("jszip"));
+    init_utils();
+    parsedDocumentCommitPath = ".knowhere-sdk/commit.json";
+    jsonContentType = "application/json; charset=utf-8";
+    markdownContentType = "text/markdown; charset=utf-8";
+    csvContentType = "text/csv; charset=utf-8";
+    htmlContentType = "text/html; charset=utf-8";
+    binaryContentType = "application/octet-stream";
+  }
+});
+
+// src/storage/sequential-parsed-document-archive.ts
+var sequential_parsed_document_archive_exports = {};
+__export(sequential_parsed_document_archive_exports, {
+  openSequentialArchive: () => openSequentialArchive
+});
+async function openSequentialArchive(params, identity) {
+  const response = await fetch(params.resultUrl, { signal: params.signal });
+  if (!response.ok || !response.body)
+    throw new Error(`Parsed result download failed (HTTP ${response.status}).`);
+  if (createDownloadIdentity(params.jobId, response) !== identity) {
+    await response.body.cancel();
+    throw new Error("Parsed result archive identity changed before sequential download.");
+  }
+  let directory;
+  try {
+    directory = await (0, import_promises2.mkdtemp)((0, import_path2.join)((0, import_os.tmpdir)(), "knowhere-sync-"));
+  } catch (error) {
+    await response.body.cancel();
+    throw new ParsedDocumentArchiveError(error);
+  }
+  let file;
+  try {
+    file = await (0, import_promises2.open)((0, import_path2.join)(directory, "archive.zip"), "w+");
+  } catch (error) {
+    await response.body.cancel();
+    await (0, import_promises2.rm)(directory, { recursive: true, force: true });
+    throw new ParsedDocumentArchiveError(error);
+  }
+  const input = import_stream.Readable.fromWeb(response.body);
+  const parser = (0, import_parse.default)({ forceStream: true });
+  const checksums = /* @__PURE__ */ new Map();
+  let archiveSize = 0;
+  const spool = new import_stream.Transform({
+    transform(chunk, _encoding, callback) {
+      archiveSize += chunk.length;
+      void file.writeFile(chunk).then(
+        () => {
+          callback(null, chunk);
+        },
+        (error) => {
+          callback(new ParsedDocumentArchiveError(error));
+        }
+      );
+    }
+  });
+  const completed = (0, import_promises.pipeline)(input, spool, parser, { signal: params.signal });
+  void completed.catch(() => void 0);
+  return {
+    identity,
+    downloadIdentity: identity,
+    canSkipEntries: false,
+    entries: (async function* () {
+      for await (const value of parser) {
+        const entry = value;
+        if (entry.type === "Directory" || !isSnapshotPath(entry.path)) {
+          await entry.autodrain().promise();
+          continue;
+        }
+        const path4 = normalizeResultPath(entry.path);
+        yield {
+          path: path4,
+          read: () => {
+            let checksum = 0;
+            let size = 0;
+            return import_stream.Readable.toWeb(entry).pipeThrough(
+              new TransformStream({
+                transform(chunk, controller) {
+                  checksum = (0, import_zlib.crc32)(chunk, checksum);
+                  size += chunk.length;
+                  controller.enqueue(chunk);
+                },
+                flush() {
+                  checksums.set(path4, { checksum, size });
+                }
+              })
+            );
+          }
+        };
+      }
+      await completed;
+      const reader = new import_zip.ZipReader(new DiskArchiveReader(file, archiveSize), {
+        useWebWorkers: false
+      });
+      try {
+        const files = (await reader.getEntries()).filter(
+          (entry) => !entry.directory && isSnapshotPath(entry.filename)
+        );
+        if (files.length !== checksums.size)
+          throw new Error("Parsed result ZIP directory does not match sequential entries.");
+        for (const entry of files) {
+          const actual = checksums.get(normalizeResultPath(entry.filename));
+          if (!actual || actual.checksum !== entry.signature || actual.size !== entry.uncompressedSize)
+            throw new Error(`Invalid parsed result ZIP checksum or size: ${entry.filename}`);
+        }
+      } finally {
+        await reader.close();
+      }
+    })(),
+    close: async () => {
+      input.destroy();
+      spool.destroy();
+      parser.destroy();
+      await completed.catch(() => void 0);
+      try {
+        await file.close();
+      } finally {
+        await (0, import_promises2.rm)(directory, { recursive: true, force: true });
+      }
+    }
+  };
+}
+var import_stream, import_promises, import_promises2, import_os, import_path2, import_zlib, import_zip, import_parse, DiskArchiveReader;
+var init_sequential_parsed_document_archive = __esm({
+  "src/storage/sequential-parsed-document-archive.ts"() {
+    "use strict";
+    import_stream = require("stream");
+    import_promises = require("stream/promises");
+    import_promises2 = require("fs/promises");
+    import_os = require("os");
+    import_path2 = require("path");
+    import_zlib = require("zlib");
+    import_zip = require("@zip.js/zip.js");
+    import_parse = __toESM(require("unzipper/lib/parse.js"));
+    init_parsed_document_archive_error();
+    init_parsed_document_storage();
+    init_streamed_parsed_document_sync();
+    DiskArchiveReader = class extends import_zip.Reader {
+      constructor(file, size) {
+        super(file);
+        this.file = file;
+        this.size = size;
+      }
+      file;
+      async readUint8Array(index, length) {
+        const body = new Uint8Array(length);
+        const { bytesRead } = await this.file.read(body, 0, length, index);
+        if (bytesRead !== length) throw new Error("Truncated parsed result ZIP.");
+        return body;
+      }
+    };
+  }
+});
+
+// src/storage/streamed-parsed-document-sync.ts
+async function syncRemoteResultArchive(params) {
+  params.signal?.throwIfAborted();
+  const startedAt = Date.now();
+  const maxEntries = Math.max(1, params.limits?.maxEntriesPerSync ?? 100);
+  const deadlineMs = Math.max(1, params.limits?.archiveSyncDeadlineMs ?? 12e4);
+  const previous = await params.storage.readSyncProgress(params);
+  const source = await openArchive(params);
+  const entryHashes = [];
+  const paths = /* @__PURE__ */ new Set();
+  let entryIndex = 0;
+  let copiedEntries = 0;
+  const nextEntry = previous?.status === "completed" ? 0 : previous?.nextArchiveEntry ?? 0;
+  try {
+    if (previous?.archiveIdentity && previous.archiveIdentity !== source.identity) {
+      throw new Error("Parsed result archive identity changed; start a new revision.");
+    }
+    if (previous?.pinnedRevisionKey && previous.pinnedRevisionKey !== params.revisionKey) {
+      throw new Error("Parsed result revision changed while resuming archive sync.");
+    }
+    for await (const entry of source.entries) {
+      params.signal?.throwIfAborted();
+      if (paths.has(entry.path)) throw new Error(`Duplicate parsed result path: ${entry.path}`);
+      paths.add(entry.path);
+      if (entryIndex >= nextEntry && copiedEntries > 0 && (copiedEntries >= maxEntries || Date.now() - startedAt >= deadlineMs)) {
+        return { documentId: params.documentId, revisionKey: params.revisionKey, completed: false };
+      }
+      if (entryIndex < nextEntry && source.canSkipEntries) {
+        const previousHash = previous?.archiveEntryHashes?.[entryIndex];
+        if (!previousHash) throw new Error("Parsed archive checkpoint is missing an entry hash.");
+        entryHashes.push(previousHash);
+        entryIndex += 1;
+        continue;
+      }
+      const hash = (0, import_crypto.createHash)("sha256");
+      const body = entry.read().pipeThrough(
+        new TransformStream({
+          transform(chunk, controller) {
+            params.signal?.throwIfAborted();
+            hash.update(chunk);
+            controller.enqueue(chunk);
+          }
+        })
+      );
+      if (entryIndex < nextEntry) {
+        await body.pipeTo(new WritableStream(), { signal: params.signal });
+      } else {
+        await writeStream(params.storage, {
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          path: entry.path,
+          body,
+          contentType: inferContentTypeFromPath(entry.path),
+          signal: params.signal
+        });
+      }
+      const entryHash = (0, import_crypto.createHash)("sha256").update(entry.path).update(hash.digest()).digest("hex");
+      if (entryIndex < nextEntry && previous?.archiveEntryHashes?.[entryIndex] !== entryHash) {
+        throw new Error("Parsed result archive entry changed while resuming.");
+      }
+      entryHashes.push(entryHash);
+      entryIndex += 1;
+      if (entryIndex <= nextEntry) continue;
+      copiedEntries += 1;
+      await params.storage.writeSyncProgress({
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        pinnedRevisionKey: params.revisionKey,
+        archiveIdentity: source.identity,
+        archiveEntryHashes: [...entryHashes],
+        nextArchiveEntry: entryIndex,
+        status: "running",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    await validateRequiredObjects(params, paths);
+    await params.verifyRevision?.();
+    params.signal?.throwIfAborted();
+    const commit = {
+      version: 1,
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      source: "resultZip",
+      committedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await params.storage.writeObject({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      path: parsedDocumentCommitPath,
+      body: Buffer.from(JSON.stringify(commit, null, 2)),
+      contentType: "application/json; charset=utf-8"
+    });
+    await params.storage.writeSyncProgress({
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      pinnedRevisionKey: params.revisionKey,
+      archiveIdentity: source.identity,
+      archiveEntryHashes: entryHashes,
+      nextArchiveEntry: entryIndex,
+      status: "completed",
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (params.retainResultArchive) {
+      try {
+        await retainArchive(params, source.downloadIdentity);
+      } catch {
+      }
+    }
+    return {
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      completed: true,
+      commit
+    };
+  } finally {
+    await source.close();
+  }
+}
+async function openArchive(params) {
+  const probe = await fetch(params.resultUrl, {
+    headers: { Range: "bytes=0-0" },
+    signal: params.signal
+  });
+  if (!probe.ok) {
+    await probe.body?.cancel();
+    throw new Error(`Parsed result download failed (HTTP ${probe.status}).`);
+  }
+  const identity = createDownloadIdentity(params.jobId, probe);
+  const supportsRange = probe.status === 206 && probe.headers.has("content-range");
+  await probe.body?.cancel();
+  if (!supportsRange) {
+    const { openSequentialArchive: openSequentialArchive2 } = await Promise.resolve().then(() => (init_sequential_parsed_document_archive(), sequential_parsed_document_archive_exports));
+    return openSequentialArchive2(params, identity);
+  }
+  const options = {
+    forceRangeRequests: true,
+    preventHeadRequest: true,
+    checkResourceChanges: true,
+    fetch: async (input, init) => {
+      const response = await fetch(input, { ...init, signal: params.signal });
+      if (response.status !== 206) {
+        await response.body?.cancel();
+        throw new Error(`Parsed result Range request failed (HTTP ${response.status}).`);
+      }
+      return response;
+    }
+  };
+  const reader = new import_zip2.ZipReader(new import_zip2.HttpRangeReader(params.resultUrl, options), {
+    useWebWorkers: false,
+    checkCrc32: true
+  });
+  try {
+    const entries = await reader.getEntries();
+    const files = entries.filter(
+      (entry) => !entry.directory && isSnapshotPath(entry.filename)
+    );
+    const archiveIdentity = (0, import_crypto.createHash)("sha256").update(identity).update(
+      JSON.stringify(
+        files.map((entry) => [entry.filename, entry.uncompressedSize, entry.signature])
+      )
+    ).digest("hex");
+    return {
+      identity: archiveIdentity,
+      downloadIdentity: identity,
+      canSkipEntries: true,
+      entries: (function* () {
+        for (const entry of files)
+          yield {
+            path: normalizeResultPath(entry.filename),
+            read: () => readRangeEntry(entry, params.signal)
+          };
+      })(),
+      close: async () => {
+        await reader.close();
+      }
+    };
+  } catch (error) {
+    await reader.close();
+    throw error;
+  }
+}
+function readRangeEntry(entry, signal) {
+  const stream = new TransformStream();
+  void entry.getData(stream.writable, { signal, checkCrc32: true, useWebWorkers: false }).catch(async (error) => {
+    try {
+      await stream.writable.abort(error);
+    } catch {
+    }
+  });
+  return stream.readable;
+}
+async function writeStream(storage, params) {
+  if (storage.writeObjectStream) {
+    try {
+      await storage.writeObjectStream(params);
+    } catch (error) {
+      await params.body.cancel(error).catch(() => void 0);
+      throw error;
+    }
+    return;
+  }
+  const parts = [];
+  for await (const part of params.body) {
+    params.signal?.throwIfAborted();
+    parts.push(part);
+  }
+  await storage.writeObject({ ...params, body: Buffer.concat(parts) });
+}
+async function validateRequiredObjects(params, paths) {
+  const required = /* @__PURE__ */ new Set(["manifest.json", "chunks.json"]);
+  for (const path4 of required)
+    if (!paths.has(path4)) throw new Error(`Required parsed result file missing: ${path4}`);
+  const manifestObject = await params.storage.readObject({ ...params, path: "manifest.json" });
+  const chunksObject = await params.storage.readObject({ ...params, path: "chunks.json" });
+  if (!manifestObject || !chunksObject)
+    throw new Error("Required parsed result manifest.json or chunks.json was not persisted.");
+  const manifest = JSON.parse(Buffer.from(manifestObject.body).toString("utf8"));
+  const payload = JSON.parse(Buffer.from(chunksObject.body).toString("utf8"));
+  if (!isRecord2(manifest)) throw new Error("Invalid parsed result manifest.json.");
+  const manifestJobId = manifest.job_id ?? manifest.jobId;
+  if (manifestJobId !== params.jobId)
+    throw new Error("Parsed result manifest job identity differs from the pinned job.");
+  const chunks = Array.isArray(payload) ? payload : isRecord2(payload) ? payload.chunks : void 0;
+  if (!Array.isArray(chunks)) throw new Error("Invalid parsed result chunks.json.");
+  if (isRecord2(manifest.files)) {
+    for (const path4 of Object.values(manifest.files))
+      if (typeof path4 === "string") required.add(normalizeResultPath(path4));
+  }
+  for (const chunk of chunks) {
+    if (!isRecord2(chunk)) throw new Error("Invalid parsed result chunk.");
+    const metadata = chunk.metadata;
+    const chunkType = chunk.type ?? chunk.chunk_type ?? chunk.chunkType;
+    const filePath = chunk.file_path ?? chunk.filePath ?? (isRecord2(metadata) ? metadata.file_path ?? metadata.filePath : void 0) ?? (chunkType === "image" || chunkType === "table" ? chunk.path : void 0);
+    if (typeof filePath === "string") required.add(normalizeResultPath(filePath));
+    if (!isRecord2(metadata)) continue;
+    const pageAssets = metadata.page_assets ?? metadata.pageAssets;
+    if (!Array.isArray(pageAssets)) continue;
+    for (const asset of pageAssets)
+      if (isRecord2(asset)) {
+        const ref = asset.artifact_ref ?? asset.artifactRef;
+        if (typeof ref === "string") required.add(normalizeResultPath(ref));
+      }
+  }
+  for (const path4 of required)
+    if (!paths.has(path4)) throw new Error(`Required parsed result file missing: ${path4}`);
+}
+async function retainArchive(params, expectedIdentity) {
+  const response = await fetch(params.resultUrl, { signal: params.signal });
+  if (!response.ok || !response.body)
+    throw new Error(`Optional archive download failed (HTTP ${response.status}).`);
+  if (createDownloadIdentity(params.jobId, response) !== expectedIdentity) {
+    await response.body.cancel();
+    throw new Error("Optional result archive identity changed.");
+  }
+  await writeStream(params.storage, {
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    path: "result.zip",
+    body: response.body,
+    contentType: "application/zip",
+    signal: params.signal
+  });
+}
+function isSnapshotPath(path4) {
+  const normalized = normalizeResultPath(path4.replace(/\/$/, ""));
+  return normalized !== "result.zip" && normalized !== ".knowhere-sdk" && !normalized.startsWith(".knowhere-sdk/");
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createDownloadIdentity(jobId, response) {
+  return (0, import_crypto.createHash)("sha256").update(
+    JSON.stringify([
+      jobId,
+      response.headers.get("etag"),
+      response.headers.get("last-modified"),
+      response.headers.get("content-range")?.split("/").at(-1) ?? response.headers.get("content-length")
+    ])
+  ).digest("hex");
+}
+var import_crypto, import_zip2;
+var init_streamed_parsed_document_sync = __esm({
+  "src/storage/streamed-parsed-document-sync.ts"() {
+    "use strict";
+    import_crypto = require("crypto");
+    import_zip2 = require("@zip.js/zip.js");
+    init_parsed_document_storage();
+  }
+});
 
 // src/index.ts
 var index_exports = {};
@@ -49,6 +912,7 @@ __export(index_exports, {
   NODE_SDK_DOCUMENT_METADATA_DEFAULTS: () => NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
+  ParsedDocumentArchiveError: () => ParsedDocumentArchiveError,
   PaymentRequiredError: () => PaymentRequiredError,
   PermissionDeniedError: () => PermissionDeniedError,
   PollingTimeoutError: () => PollingTimeoutError,
@@ -66,7 +930,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_path3 = __toESM(require("path"));
+var import_path4 = __toESM(require("path"));
 
 // src/lib/http-client.ts
 var import_axios = __toESM(require("axios"));
@@ -74,80 +938,14 @@ var import_axios = __toESM(require("axios"));
 // src/version.ts
 var VERSION = "2.1.3";
 
-// src/constants.ts
-var DEFAULT_BASE_URL = "https://api.knowhereto.ai";
-var DEFAULT_TIMEOUT = 6e4;
-var DEFAULT_MAX_RETRIES = 5;
-var DEFAULT_POLL_INTERVAL = 1e4;
-var MAX_POLL_INTERVAL = 3e4;
-var DEFAULT_POLL_TIMEOUT = 18e5;
-var POLL_INTERVAL_INCREASE_THRESHOLD = 6e4;
-var POLL_INTERVAL_MULTIPLIER = 1.2;
-var INITIAL_RETRY_DELAY = 500;
-var MAX_RETRY_DELAY = 3e4;
-var RETRY_DELAY_BASE = 2;
-var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([409, 429, 502, 503, 504]);
-var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["done", "failed"]);
-var ENV = {
-  API_KEY: "KNOWHERE_API_KEY",
-  BASE_URL: "KNOWHERE_BASE_URL",
-  LOG_LEVEL: "KNOWHERE_LOG_LEVEL"
-};
+// src/lib/http-client.ts
+init_constants();
 
-// src/errors/base.ts
-var KnowhereError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "KnowhereError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var NetworkError = class extends KnowhereError {
-  constructor(message, cause) {
-    super(message);
-    this.cause = cause;
-    this.name = "NetworkError";
-  }
-  cause;
-};
-var TimeoutError = class extends NetworkError {
-  constructor(message = "Request timed out") {
-    super(message);
-    this.name = "TimeoutError";
-  }
-};
-var PollingTimeoutError = class extends KnowhereError {
-  constructor(message = "Polling timed out", elapsedMs) {
-    super(message);
-    this.elapsedMs = elapsedMs;
-    this.name = "PollingTimeoutError";
-  }
-  elapsedMs;
-};
-var ChecksumError = class extends KnowhereError {
-  constructor(message = "Checksum verification failed", expected, actual) {
-    super(message);
-    this.expected = expected;
-    this.actual = actual;
-    this.name = "ChecksumError";
-  }
-  expected;
-  actual;
-};
-var ValidationError = class extends KnowhereError {
-  constructor(message) {
-    super(message);
-    this.name = "ValidationError";
-  }
-};
-var InvalidStateError = class extends KnowhereError {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidStateError";
-  }
-};
+// src/errors/index.ts
+init_base();
 
 // src/errors/api-errors.ts
+init_base();
 var APIError = class extends KnowhereError {
   constructor(message, statusCode, code, requestId, details, body) {
     super(message);
@@ -234,162 +1032,48 @@ function createAPIError(statusCode, message, code, requestId, details, body, ret
       return new AuthenticationError(message, code, requestId, details, body);
     case 402:
       return new PaymentRequiredError(message, code, requestId, details, body);
-    case 403:
-      return new PermissionDeniedError(message, code, requestId, details, body);
-    case 404:
-      return new NotFoundError(message, code, requestId, details, body);
-    case 409:
-      return new ConflictError(message, code, requestId, details, body);
-    case 429:
-      return new RateLimitError(message, code, requestId, details, body, retryAfter);
-    case 500:
-      return new InternalServerError(message, code, requestId, details, body);
-    case 502:
-    case 503:
-      return new ServiceUnavailableError(message, statusCode, code, requestId, details, body);
-    case 504:
-      return new GatewayTimeoutError(message, code, requestId, details, body);
-    default:
-      return new APIError(message, statusCode, code, requestId, details, body);
-  }
-}
-
-// src/errors/job-errors.ts
-var JobFailedError = class extends KnowhereError {
-  constructor(message, code, jobResult) {
-    super(message);
-    this.code = code;
-    this.jobResult = jobResult;
-    this.name = "JobFailedError";
-  }
-  code;
-  jobResult;
-};
-
-// src/lib/utils.ts
-function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
-}
-function snakeToCamel(str) {
-  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-function camelToSnake(str) {
-  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-}
-function keysToCamel(obj) {
-  if (obj === null || obj === void 0) {
-    return obj;
-  }
-  if (Array.isArray(obj)) {
-    return obj.map((item) => keysToCamel(item));
-  }
-  if (typeof obj === "object" && obj.constructor === Object) {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[snakeToCamel(key)] = keysToCamel(value);
-    }
-    return result;
-  }
-  return obj;
-}
-function keysToSnake(obj) {
-  if (obj === null || obj === void 0) {
-    return obj;
-  }
-  if (Array.isArray(obj)) {
-    return obj.map((item) => keysToSnake(item));
-  }
-  if (typeof obj === "object" && obj.constructor === Object) {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[camelToSnake(key)] = keysToSnake(value);
-    }
-    return result;
-  }
-  return obj;
-}
-function parseDates(obj) {
-  if (obj === null || obj === void 0) {
-    return obj;
-  }
-  if (Array.isArray(obj)) {
-    return obj.map((item) => parseDates(item));
-  }
-  if (typeof obj === "object" && obj.constructor === Object) {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      if ((key.endsWith("At") || key.endsWith("Date")) && typeof value === "string" && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
-        result[key] = new Date(value);
-      } else {
-        result[key] = parseDates(value);
-      }
-    }
-    return result;
-  }
-  return obj;
-}
-function isTerminalStatus(status) {
-  return TERMINAL_JOB_STATUSES.has(status);
-}
-function enrichJobResult(jobResult) {
-  const computedProperties = {};
-  if (!Object.getOwnPropertyDescriptor(jobResult, "isTerminal")) {
-    computedProperties.isTerminal = {
-      get() {
-        return isTerminalStatus(this.status);
-      },
-      enumerable: true,
-      configurable: true
-    };
-  }
-  if (!Object.getOwnPropertyDescriptor(jobResult, "isDone")) {
-    computedProperties.isDone = {
-      get() {
-        return this.status === "done";
-      },
-      enumerable: true,
-      configurable: true
-    };
-  }
-  if (!Object.getOwnPropertyDescriptor(jobResult, "isFailed")) {
-    computedProperties.isFailed = {
-      get() {
-        return this.status === "failed";
-      },
-      enumerable: true,
-      configurable: true
-    };
-  }
-  if (Object.keys(computedProperties).length > 0) {
-    Object.defineProperties(jobResult, computedProperties);
+    case 403:
+      return new PermissionDeniedError(message, code, requestId, details, body);
+    case 404:
+      return new NotFoundError(message, code, requestId, details, body);
+    case 409:
+      return new ConflictError(message, code, requestId, details, body);
+    case 429:
+      return new RateLimitError(message, code, requestId, details, body, retryAfter);
+    case 500:
+      return new InternalServerError(message, code, requestId, details, body);
+    case 502:
+    case 503:
+      return new ServiceUnavailableError(message, statusCode, code, requestId, details, body);
+    case 504:
+      return new GatewayTimeoutError(message, code, requestId, details, body);
+    default:
+      return new APIError(message, statusCode, code, requestId, details, body);
   }
-  return jobResult;
 }
-function enrichParseResult(parseResult2, scope) {
-  if (scope.namespace !== void 0) {
-    parseResult2.namespace = scope.namespace;
-  }
-  if (scope.documentId !== void 0) {
-    parseResult2.documentId = scope.documentId;
+
+// src/errors/job-errors.ts
+init_base();
+var JobFailedError = class extends KnowhereError {
+  constructor(message, code, jobResult) {
+    super(message);
+    this.code = code;
+    this.jobResult = jobResult;
+    this.name = "JobFailedError";
   }
-  return parseResult2;
-}
-function sanitizePath(path4) {
-  let sanitized = path4.replace(/^\/+/, "");
-  sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
-  sanitized = sanitized.replace(/\\/g, "/");
-  return sanitized;
-}
-function getFileExtension(filename) {
-  const match = filename.match(/\.([^.]+)$/);
-  return match ? match[1].toLowerCase() : "";
-}
-function jitter(value, percent = 0.2) {
-  const randomFactor = 1 + (Math.random() * 2 - 1) * percent;
-  return Math.round(value * randomFactor);
-}
+  code;
+  jobResult;
+};
+
+// src/errors/index.ts
+init_parsed_document_archive_error();
+
+// src/lib/http-client.ts
+init_utils();
 
 // src/lib/retry.ts
+init_constants();
+init_utils();
 function getErrorCode(error) {
   const errorWithResponse = error;
   return errorWithResponse?.response?.data?.error?.code ?? errorWithResponse?.response?.data?.code ?? errorWithResponse?.code;
@@ -815,6 +1499,8 @@ function isReadStream(obj) {
 }
 
 // src/lib/polling.ts
+init_constants();
+init_utils();
 async function pollJobStatus(httpClient, jobId, options) {
   const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL;
   const pollTimeout = options?.pollTimeout ?? DEFAULT_POLL_TIMEOUT;
@@ -865,6 +1551,7 @@ async function pollJobStatus(httpClient, jobId, options) {
 var import_jszip = __toESM(require("jszip"));
 var import_fs2 = require("fs");
 var import_path = require("path");
+init_utils();
 async function parseResult(httpClient, resultUrl, options) {
   const zipBuffer = await httpClient.download(resultUrl);
   if (options?.verifyChecksum !== false) {
@@ -1367,6 +2054,7 @@ function isMissingFileError(error) {
 }
 
 // src/resources/jobs.ts
+init_utils();
 var Jobs = class extends BaseResource {
   pendingUploadJobs = /* @__PURE__ */ new Map();
   /**
@@ -1607,7 +2295,7 @@ var Documents = class extends BaseResource {
 };
 
 // src/knowledge/knowledge.ts
-var import_crypto2 = require("crypto");
+var import_crypto3 = require("crypto");
 
 // src/storage/asset-storage.ts
 var import_jszip2 = __toESM(require("jszip"));
@@ -1871,220 +2559,16 @@ 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/knowledge.ts
+init_parsed_document_storage();
+init_utils();
+init_streamed_parsed_document_sync();
 
 // src/knowledge/local-store.ts
-var import_crypto = require("crypto");
-var import_os = __toESM(require("os"));
+var import_crypto2 = require("crypto");
+var import_os2 = __toESM(require("os"));
 var import_fs3 = require("fs");
-var import_path2 = __toESM(require("path"));
+var import_path3 = __toESM(require("path"));
 var STORE_VERSION = 1;
 var LOCAL_DOCUMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 var LocalKnowledgeStore = class {
@@ -2092,8 +2576,8 @@ var LocalKnowledgeStore = class {
   indexPath;
   resultCache = /* @__PURE__ */ new Map();
   constructor(cacheDirectory) {
-    this.cacheDirectory = cacheDirectory ?? import_path2.default.join(import_os.default.homedir(), ".knowhere-node-sdk", "knowledge");
-    this.indexPath = import_path2.default.join(this.cacheDirectory, "index.json");
+    this.cacheDirectory = cacheDirectory ?? import_path3.default.join(import_os2.default.homedir(), ".knowhere-node-sdk", "knowledge");
+    this.indexPath = import_path3.default.join(this.cacheDirectory, "index.json");
   }
   async saveResult(result, options) {
     await import_fs3.promises.mkdir(this.cacheDirectory, { recursive: true });
@@ -2218,8 +2702,8 @@ var LocalKnowledgeStore = class {
     return { document, result };
   }
   getResultDirectoryPath(localDocumentId) {
-    const documentsDirectory = import_path2.default.resolve(this.cacheDirectory, "documents");
-    const resultDirectoryPath = import_path2.default.resolve(documentsDirectory, localDocumentId);
+    const documentsDirectory = import_path3.default.resolve(this.cacheDirectory, "documents");
+    const resultDirectoryPath = import_path3.default.resolve(documentsDirectory, localDocumentId);
     if (!isPathInsideDirectory(resultDirectoryPath, documentsDirectory)) {
       throw new Error(`Local Knowhere document ID resolves outside the cache: ${localDocumentId}`);
     }
@@ -2253,7 +2737,7 @@ var LocalKnowledgeStore = class {
   }
 };
 function validateLocalDocumentId(localDocumentId) {
-  if (!LOCAL_DOCUMENT_ID_PATTERN.test(localDocumentId) || localDocumentId.includes("..") || import_path2.default.basename(localDocumentId) !== localDocumentId) {
+  if (!LOCAL_DOCUMENT_ID_PATTERN.test(localDocumentId) || localDocumentId.includes("..") || import_path3.default.basename(localDocumentId) !== localDocumentId) {
     throw new Error(
       "Local Knowhere document ID must be a safe slug containing only letters, numbers, dots, underscores, or hyphens"
     );
@@ -2261,11 +2745,11 @@ function validateLocalDocumentId(localDocumentId) {
   return localDocumentId;
 }
 function isPathInsideDirectory(targetPath, parentDirectory) {
-  const relativePath = import_path2.default.relative(parentDirectory, targetPath);
-  return relativePath.length === 0 || !relativePath.startsWith("..") && !import_path2.default.isAbsolute(relativePath);
+  const relativePath = import_path3.default.relative(parentDirectory, targetPath);
+  return relativePath.length === 0 || !relativePath.startsWith("..") && !import_path3.default.isAbsolute(relativePath);
 }
 function createLocalDocumentId(result) {
-  const hash = (0, import_crypto.createHash)("sha256").update(result.jobId).update("\0").update(result.manifest.sourceFileName).digest("hex").slice(0, 16);
+  const hash = (0, import_crypto2.createHash)("sha256").update(result.jobId).update("\0").update(result.manifest.sourceFileName).digest("hex").slice(0, 16);
   return `local_${hash}`;
 }
 function countChunkTypes(result) {
@@ -2419,29 +2903,32 @@ var Knowledge = class _Knowledge {
     return this.importJobResult(params);
   }
   async syncParsedDocument(params) {
+    params.signal?.throwIfAborted();
     const normalized = normalizeDocumentReference(params);
     const parsedStorageConfig = this.requireParsedStorageConfig();
     if (normalized.documentId) {
       return this.syncRemoteDocumentToParsedStorage({
         documentId: normalized.documentId,
         revisionKey: params.revisionKey,
-        parsedStorageConfig
+        parsedStorageConfig,
+        signal: params.signal,
+        retainResultArchive: params.retainResultArchive
       });
     }
     if (normalized.jobId) {
-      const loadedResult = await this.client.jobs.load(normalized.jobId);
-      const synced2 = await syncParseResultToParsedDocumentStorage({
-        result: loadedResult,
+      const job = await this.client.jobs.get(normalized.jobId);
+      if (!job.isDone || !job.resultUrl)
+        throw new ValidationError("Completed job result archive is unavailable");
+      return syncRemoteResultArchive({
+        documentId: job.documentId ?? normalized.localDocumentId ?? normalized.jobId,
+        revisionKey: params.revisionKey ?? normalized.jobId,
+        jobId: normalized.jobId,
+        resultUrl: job.resultUrl,
         storage: parsedStorageConfig.storage,
-        documentId: loadedResult.documentId ?? normalized.localDocumentId ?? normalized.jobId,
-        revisionKey: params.revisionKey ?? normalized.jobId
+        limits: parsedStorageConfig.limits,
+        signal: params.signal,
+        retainResultArchive: params.retainResultArchive
       });
-      return {
-        documentId: synced2.documentId,
-        revisionKey: synced2.revisionKey,
-        completed: true,
-        commit: synced2.commit
-      };
     }
     if (!normalized.localDocumentId) {
       throw new ValidationError("localDocumentId, documentId, or jobId is required");
@@ -3139,10 +3626,14 @@ var Knowledge = class _Knowledge {
           parsedStorageConfig
         });
       } catch (error) {
+        const previous = await parsedStorageConfig.storage.readSyncProgress({
+          documentId,
+          revisionKey
+        });
         await parsedStorageConfig.storage.writeSyncProgress({
+          ...previous,
           documentId,
           revisionKey,
-          nextChunkPage: 1,
           status: "failed",
           updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
           error: error instanceof Error ? error.message : String(error)
@@ -3152,6 +3643,7 @@ var Knowledge = class _Knowledge {
     void Promise.resolve(scheduler.schedule(task)).catch(() => void 0);
   }
   async syncRemoteDocumentToParsedStorage(params) {
+    params.signal?.throwIfAborted();
     const firstPage = await this.client.documents.listChunks(params.documentId, {
       page: 1,
       pageSize: 1,
@@ -3159,55 +3651,67 @@ var Knowledge = class _Knowledge {
     });
     const revisionKey = params.revisionKey ?? getRemoteRevisionKey(firstPage);
     if (params.revisionKey && getRemoteRevisionKey(firstPage) !== params.revisionKey) {
-      return this.syncRemoteDocumentToParsedStorage({
-        documentId: params.documentId,
-        parsedStorageConfig: params.parsedStorageConfig
-      });
+      throw new ValidationError("Published document revision changed before parsed snapshot sync");
     }
     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({
+      const job = await this.client.jobs.get(firstPage.jobId).catch((error) => {
+        if (error instanceof NotFoundError) return null;
+        throw error;
+      });
+      if (job?.isDone && job.resultUrl) {
+        if (job.documentId && job.documentId !== params.documentId)
+          throw new ValidationError("Parsed job document identity differs from requested document");
+        return syncRemoteResultArchive({
           documentId: params.documentId,
           revisionKey,
-          status: "completed",
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+          jobId: firstPage.jobId,
+          resultUrl: job.resultUrl,
+          storage: params.parsedStorageConfig.storage,
+          limits: params.parsedStorageConfig.limits,
+          signal: params.signal,
+          retainResultArchive: params.retainResultArchive,
+          verifyRevision: async () => {
+            const current = await this.client.documents.listChunks(params.documentId, {
+              page: 1,
+              pageSize: 1,
+              includeAssetUrls: true
+            });
+            if (getRemoteRevisionKey(current) !== revisionKey || current.jobId !== firstPage.jobId)
+              throw new ValidationError(
+                "Published document revision changed during parsed snapshot sync"
+              );
+          }
         });
-        return {
-          documentId: synced.documentId,
-          revisionKey: synced.revisionKey,
-          completed: true,
-          commit: synced.commit
-        };
-      } catch {
       }
     }
     return this.syncRemoteDocumentChunksToParsedStorage({
       documentId: params.documentId,
       revisionKey,
       firstPage,
-      parsedStorageConfig: params.parsedStorageConfig
+      parsedStorageConfig: params.parsedStorageConfig,
+      signal: params.signal
     });
   }
   async syncRemoteDocumentChunksToParsedStorage(params) {
+    params.signal?.throwIfAborted();
     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 nextPage = existingProgress?.status === "running" || existingProgress?.status === "failed" ? 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
     });
+    validateRemoteReconstructionRevision(
+      params.documentId,
+      params.revisionKey,
+      params.firstPage.jobId,
+      response
+    );
+    params.signal?.throwIfAborted();
     const totalPages = response.pagination.totalPages;
     let syncedPages = 0;
     const startedAt = Date.now();
@@ -3219,6 +3723,13 @@ var Knowledge = class _Knowledge {
           includeAssetUrls: true
         });
       }
+      params.signal?.throwIfAborted();
+      validateRemoteReconstructionRevision(
+        params.documentId,
+        params.revisionKey,
+        params.firstPage.jobId,
+        response
+      );
       await params.parsedStorageConfig.storage.writeObject({
         documentId: params.documentId,
         revisionKey: params.revisionKey,
@@ -3266,7 +3777,23 @@ var Knowledge = class _Knowledge {
       storage: params.parsedStorageConfig.storage,
       documentId: params.documentId,
       revisionKey: params.revisionKey,
-      source: "remoteReconstruction"
+      source: "remoteReconstruction",
+      signal: params.signal,
+      beforeCommit: async () => {
+        params.signal?.throwIfAborted();
+        const current = await this.client.documents.listChunks(params.documentId, {
+          page: 1,
+          pageSize: 1,
+          includeAssetUrls: true
+        });
+        params.signal?.throwIfAborted();
+        validateRemoteReconstructionRevision(
+          params.documentId,
+          params.revisionKey,
+          params.firstPage.jobId,
+          current
+        );
+      }
     });
     await params.parsedStorageConfig.storage.writeSyncProgress({
       documentId: params.documentId,
@@ -3338,7 +3865,7 @@ function createLocalDocumentIdForRemote(documentId) {
   if (SAFE_LOCAL_DOCUMENT_ID_PATTERN.test(documentId) && !documentId.includes("..") && !documentId.includes("/") && !documentId.includes("\\")) {
     return documentId;
   }
-  const hash = (0, import_crypto2.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
+  const hash = (0, import_crypto3.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
   return `remote_${hash}`;
 }
 var defaultParsedStorageScheduler = {
@@ -3558,10 +4085,10 @@ function parseStoredResultChunks(params) {
 }
 function extractStoredChunkRecords(payload) {
   if (Array.isArray(payload)) {
-    return payload.filter(isRecord2);
+    return payload.filter(isRecord3);
   }
-  if (isRecord2(payload) && Array.isArray(payload.chunks)) {
-    return payload.chunks.filter(isRecord2);
+  if (isRecord3(payload) && Array.isArray(payload.chunks)) {
+    return payload.chunks.filter(isRecord3);
   }
   return [];
 }
@@ -3581,7 +4108,7 @@ function readRecordNumber(record, ...keys) {
 }
 function readRecordMetadata(record) {
   const metadata = record.metadata;
-  return isRecord2(metadata) ? keysToCamel(metadata) : {};
+  return isRecord3(metadata) ? keysToCamel(metadata) : {};
 }
 function isKnowledgeChunkType(value) {
   return value === "text" || value === "image" || value === "table" || value === "page";
@@ -3680,7 +4207,7 @@ async function applyStoredPageAssetUrls(params) {
   }
   return Promise.all(
     pageAssets.map(async (pageAsset) => {
-      if (!isRecord2(pageAsset)) {
+      if (!isRecord3(pageAsset)) {
         return pageAsset;
       }
       const artifactRef = readRecordString(pageAsset, "artifactRef", "artifact_ref");
@@ -3709,7 +4236,7 @@ function getStoredPageAssets(metadata) {
   return pageAssets?.map(normalizeStoredPageAsset);
 }
 function normalizeStoredPageAsset(pageAsset) {
-  if (!isRecord2(pageAsset)) {
+  if (!isRecord3(pageAsset)) {
     return pageAsset;
   }
   const normalizedPageAsset = { ...pageAsset };
@@ -3787,7 +4314,7 @@ function parseContinuationCursor(value) {
   }
   try {
     const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
-    if (!isRecord2(parsed)) {
+    if (!isRecord3(parsed)) {
       return null;
     }
     const documentId = parsed.documentId;
@@ -3825,11 +4352,11 @@ function inferContentTypeFromPath2(filePath) {
   if (extension === "html" || extension === "htm") return "text/html; charset=utf-8";
   return "application/octet-stream";
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isDocumentChunkArray(value) {
-  return Array.isArray(value) && value.every(isRecord2);
+  return Array.isArray(value) && value.every(isRecord3);
 }
 function indexChunks(result) {
   return result.chunks.map((chunk, index) => {
@@ -4132,17 +4659,24 @@ function toRemoteSearchResult(result, documentByServerId) {
     sourceFileName: result.source.sourceFileName ?? void 0
   };
 }
+function validateRemoteReconstructionRevision(documentId, revisionKey, jobId, response) {
+  if (response.documentId !== documentId || getRemoteRevisionKey(response) !== revisionKey || (response.jobId ?? void 0) !== (jobId ?? void 0)) {
+    throw new ValidationError("Published document revision changed during remote reconstruction");
+  }
+}
 
 // src/client.ts
+init_constants();
+init_utils();
 function inferFileName(file, explicitFileName) {
   if (explicitFileName) {
     return explicitFileName;
   }
   if (typeof file === "string") {
-    return import_path3.default.basename(file);
+    return import_path4.default.basename(file);
   }
   if (isReadStream2(file) && typeof file.path === "string") {
-    return import_path3.default.basename(file.path);
+    return import_path4.default.basename(file.path);
   }
   return void 0;
 }
@@ -4288,9 +4822,9 @@ var Knowhere = class {
 };
 
 // src/storage/disk-parsed-document-storage.ts
-var import_crypto3 = require("crypto");
+var import_crypto4 = require("crypto");
 var import_fs4 = require("fs");
-var import_path4 = __toESM(require("path"));
+var import_path5 = __toESM(require("path"));
 var syncProgressPath = ".knowhere-sdk/sync-progress.json";
 var DiskParsedDocumentStorage = class {
   rootDirectory;
@@ -4319,7 +4853,7 @@ var DiskParsedDocumentStorage = class {
   }
   async writeObject(params) {
     const objectPath = this.getObjectPath(params);
-    await import_fs4.promises.mkdir(import_path4.default.dirname(objectPath), { recursive: true });
+    await import_fs4.promises.mkdir(import_path5.default.dirname(objectPath), { recursive: true });
     await import_fs4.promises.writeFile(objectPath, params.body);
     await this.writeObjectMetadata(objectPath, {
       contentType: params.contentType,
@@ -4378,14 +4912,14 @@ var DiskParsedDocumentStorage = class {
   }
   getObjectPath(params) {
     const revisionDirectory = this.getRevisionDirectory(params.documentId, params.revisionKey);
-    const objectPath = import_path4.default.resolve(revisionDirectory, normalizeRelativeStoragePath(params.path));
+    const objectPath = import_path5.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));
+    return import_path5.default.join(this.rootDirectory, hashPathPart(documentId), hashPathPart(revisionKey));
   }
   async readOptionalJson(params) {
     const object = await this.readObject(params);
@@ -4421,7 +4955,7 @@ function hashPathPart(value) {
   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);
+  return (0, import_crypto4.createHash)("sha256").update(normalized).digest("hex").slice(0, 24);
 }
 function normalizeRelativeStoragePath(value) {
   const normalized = value.replaceAll("\\", "/").replace(/^\.\/+/, "");
@@ -4431,8 +4965,8 @@ function normalizeRelativeStoragePath(value) {
   return normalized;
 }
 function isPathInsideDirectory2(filePath, directory) {
-  const relative = import_path4.default.relative(directory, filePath);
-  return relative === "" || !relative.startsWith("..") && !import_path4.default.isAbsolute(relative);
+  const relative = import_path5.default.relative(directory, filePath);
+  return relative === "" || !relative.startsWith("..") && !import_path5.default.isAbsolute(relative);
 }
 function toFileUrl(filePath) {
   return `file://${filePath}`;
@@ -4440,6 +4974,9 @@ function toFileUrl(filePath) {
 function isMissingFileError3(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
+
+// src/index.ts
+init_parsed_document_storage();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
@@ -4461,6 +4998,7 @@ function isMissingFileError3(error) {
   NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError,
   NotFoundError,
+  ParsedDocumentArchiveError,
   PaymentRequiredError,
   PermissionDeniedError,
   PollingTimeoutError,