@ontos-ai/knowhere-sdk 2.4.2 → 2.6.0-beta.20261026172248

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 });
@@ -27,205 +30,92 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  APIError: () => APIError,
-  AuthenticationError: () => AuthenticationError,
-  BadRequestError: () => BadRequestError,
-  ChecksumError: () => ChecksumError,
-  ConflictError: () => ConflictError,
-  DiskParsedDocumentStorage: () => DiskParsedDocumentStorage,
-  Documents: () => Documents,
-  GatewayTimeoutError: () => GatewayTimeoutError,
-  InternalServerError: () => InternalServerError,
-  InvalidStateError: () => InvalidStateError,
-  JobFailedError: () => JobFailedError,
-  Jobs: () => Jobs,
-  Knowhere: () => Knowhere,
-  KnowhereError: () => KnowhereError,
-  Knowledge: () => Knowledge,
-  LocalKnowledgeStore: () => LocalKnowledgeStore,
-  NODE_SDK_DOCUMENT_METADATA_DEFAULTS: () => NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
-  NetworkError: () => NetworkError,
-  NotFoundError: () => NotFoundError,
-  PaymentRequiredError: () => PaymentRequiredError,
-  PermissionDeniedError: () => PermissionDeniedError,
-  PollingTimeoutError: () => PollingTimeoutError,
-  RateLimitError: () => RateLimitError,
-  Retrieval: () => Retrieval,
-  ServiceUnavailableError: () => ServiceUnavailableError,
-  TimeoutError: () => TimeoutError,
-  VERSION: () => VERSION,
-  ValidationError: () => ValidationError,
-  default: () => Knowhere,
-  mergeDocumentMetadataDefaults: () => mergeDocumentMetadataDefaults,
-  storeParseResultAssets: () => storeParseResultAssets,
-  syncParseResultToParsedDocumentStorage: () => syncParseResultToParsedDocumentStorage
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/client.ts
-var import_path3 = __toESM(require("path"));
-
-// src/lib/http-client.ts
-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"
-};
+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 = 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";
+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/api-errors.ts
-var APIError = class extends KnowhereError {
-  constructor(message, statusCode, code, requestId, details, body) {
-    super(message);
-    this.statusCode = statusCode;
-    this.code = code;
-    this.requestId = requestId;
-    this.details = details;
-    this.body = body;
-    this.name = "APIError";
-  }
-  statusCode;
-  code;
-  requestId;
-  details;
-  body;
-};
-var BadRequestError = class extends APIError {
-  constructor(message, code, requestId, details, body) {
-    super(message, 400, code, requestId, details, body);
-    this.name = "BadRequestError";
-  }
-};
-var AuthenticationError = class extends APIError {
-  constructor(message = "Authentication failed", code, requestId, details, body) {
-    super(message, 401, code, requestId, details, body);
-    this.name = "AuthenticationError";
-  }
-};
-var PaymentRequiredError = class extends APIError {
-  constructor(message = "Payment required", code, requestId, details, body) {
-    super(message, 402, code, requestId, details, body);
-    this.name = "PaymentRequiredError";
-  }
-};
-var PermissionDeniedError = class extends APIError {
-  constructor(message = "Permission denied", code, requestId, details, body) {
-    super(message, 403, code, requestId, details, body);
-    this.name = "PermissionDeniedError";
-  }
-};
-var NotFoundError = class extends APIError {
-  constructor(message = "Resource not found", code, requestId, details, body) {
-    super(message, 404, code, requestId, details, body);
-    this.name = "NotFoundError";
-  }
-};
-var ConflictError = class extends APIError {
-  constructor(message = "Conflict", code, requestId, details, body) {
-    super(message, 409, code, requestId, details, body);
-    this.name = "ConflictError";
-  }
-};
-var RateLimitError = class extends APIError {
-  constructor(message = "Rate limit exceeded", code, requestId, details, body, retryAfter) {
-    super(message, 429, code, requestId, details, body);
-    this.retryAfter = retryAfter;
-    this.name = "RateLimitError";
-  }
-  retryAfter;
-};
-var InternalServerError = class extends APIError {
-  constructor(message = "Internal server error", code, requestId, details, body) {
-    super(message, 500, code, requestId, details, body);
-    this.name = "InternalServerError";
-  }
-};
-var ServiceUnavailableError = class extends APIError {
-  constructor(message = "Service unavailable", statusCode = 503, code, requestId, details, body) {
-    super(message, statusCode, code, requestId, details, body);
-    this.name = "ServiceUnavailableError";
-  }
-};
-var GatewayTimeoutError = class extends APIError {
-  constructor(message = "Gateway timeout", code, requestId, details, body) {
-    super(message, 504, code, requestId, details, body);
-    this.name = "GatewayTimeoutError";
-  }
-};
 function createAPIError(statusCode, message, code, requestId, details, body, retryAfter) {
   switch (statusCode) {
     case 400:
@@ -253,18 +143,141 @@ function createAPIError(statusCode, message, code, requestId, details, body, ret
       return new APIError(message, statusCode, code, requestId, details, body);
   }
 }
+var APIError, BadRequestError, AuthenticationError, PaymentRequiredError, PermissionDeniedError, NotFoundError, ConflictError, RateLimitError, InternalServerError, ServiceUnavailableError, GatewayTimeoutError;
+var init_api_errors = __esm({
+  "src/errors/api-errors.ts"() {
+    "use strict";
+    init_base();
+    APIError = class extends KnowhereError {
+      constructor(message, statusCode, code, requestId, details, body) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.requestId = requestId;
+        this.details = details;
+        this.body = body;
+        this.name = "APIError";
+      }
+      statusCode;
+      code;
+      requestId;
+      details;
+      body;
+    };
+    BadRequestError = class extends APIError {
+      constructor(message, code, requestId, details, body) {
+        super(message, 400, code, requestId, details, body);
+        this.name = "BadRequestError";
+      }
+    };
+    AuthenticationError = class extends APIError {
+      constructor(message = "Authentication failed", code, requestId, details, body) {
+        super(message, 401, code, requestId, details, body);
+        this.name = "AuthenticationError";
+      }
+    };
+    PaymentRequiredError = class extends APIError {
+      constructor(message = "Payment required", code, requestId, details, body) {
+        super(message, 402, code, requestId, details, body);
+        this.name = "PaymentRequiredError";
+      }
+    };
+    PermissionDeniedError = class extends APIError {
+      constructor(message = "Permission denied", code, requestId, details, body) {
+        super(message, 403, code, requestId, details, body);
+        this.name = "PermissionDeniedError";
+      }
+    };
+    NotFoundError = class extends APIError {
+      constructor(message = "Resource not found", code, requestId, details, body) {
+        super(message, 404, code, requestId, details, body);
+        this.name = "NotFoundError";
+      }
+    };
+    ConflictError = class extends APIError {
+      constructor(message = "Conflict", code, requestId, details, body) {
+        super(message, 409, code, requestId, details, body);
+        this.name = "ConflictError";
+      }
+    };
+    RateLimitError = class extends APIError {
+      constructor(message = "Rate limit exceeded", code, requestId, details, body, retryAfter) {
+        super(message, 429, code, requestId, details, body);
+        this.retryAfter = retryAfter;
+        this.name = "RateLimitError";
+      }
+      retryAfter;
+    };
+    InternalServerError = class extends APIError {
+      constructor(message = "Internal server error", code, requestId, details, body) {
+        super(message, 500, code, requestId, details, body);
+        this.name = "InternalServerError";
+      }
+    };
+    ServiceUnavailableError = class extends APIError {
+      constructor(message = "Service unavailable", statusCode = 503, code, requestId, details, body) {
+        super(message, statusCode, code, requestId, details, body);
+        this.name = "ServiceUnavailableError";
+      }
+    };
+    GatewayTimeoutError = class extends APIError {
+      constructor(message = "Gateway timeout", code, requestId, details, body) {
+        super(message, 504, code, requestId, details, body);
+        this.name = "GatewayTimeoutError";
+      }
+    };
+  }
+});
 
 // 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;
-};
+var JobFailedError;
+var init_job_errors = __esm({
+  "src/errors/job-errors.ts"() {
+    "use strict";
+    init_base();
+    JobFailedError = class extends KnowhereError {
+      constructor(message, code, jobResult) {
+        super(message);
+        this.code = code;
+        this.jobResult = jobResult;
+        this.name = "JobFailedError";
+      }
+      code;
+      jobResult;
+    };
+  }
+});
+
+// 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/errors/index.ts
+var init_errors = __esm({
+  "src/errors/index.ts"() {
+    "use strict";
+    init_base();
+    init_api_errors();
+    init_job_errors();
+    init_parsed_document_archive_error();
+  }
+});
 
 // src/lib/utils.ts
 function sleep(ms) {
@@ -388,8 +401,1204 @@ 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/archive-cache-transport-error.ts
+var ArchiveCacheTransportError;
+var init_archive_cache_transport_error = __esm({
+  "src/storage/archive-cache-transport-error.ts"() {
+    "use strict";
+    ArchiveCacheTransportError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ArchiveCacheTransportError";
+      }
+    };
+  }
+});
+
+// src/storage/parsed-document-archive-cache.ts
+async function prepareCachedArchive(params) {
+  params.signal?.throwIfAborted();
+  if (params.archiveCacheBypassed) return createFallback(params);
+  if (!params.storage.writeObjectStream || !params.storage.headObject || !params.storage.getObjectUrl) {
+    await params.onBypass?.();
+    return createFallback(params);
+  }
+  const controller = new AbortController();
+  const signal = params.signal ? AbortSignal.any([params.signal, controller.signal]) : controller.signal;
+  const mutations = /* @__PURE__ */ new Set();
+  let rejectCancellation;
+  const cancellation = new Promise((_resolve, reject) => {
+    rejectCancellation = () => {
+      const reason = signal.reason;
+      reject(
+        reason instanceof Error ? reason : new Error("Parsed result archive cache was cancelled.", { cause: reason })
+      );
+    };
+    signal.addEventListener("abort", rejectCancellation, { once: true });
+  });
+  const timer = setTimeout(() => {
+    controller.abort(new Error("Parsed result archive cache exceeded its thirty-second budget."));
+  }, ARCHIVE_CACHE_TIMEOUT_MS);
+  let origin;
+  const preparation = (async () => {
+    origin = await probeArchiveOrigin({ ...params, signal });
+    signal.throwIfAborted();
+    if (!hasStrongEntityTag(origin.entityTag) || origin.contentLength === void 0)
+      throw new Error("Parsed result archive cache requires a strong origin version and length.");
+    return prepareArchiveCache(params, origin, signal, mutations);
+  })();
+  try {
+    return await Promise.race([preparation, cancellation]);
+  } catch (error) {
+    controller.abort(error);
+    await Promise.allSettled([...mutations]);
+    params.signal?.throwIfAborted();
+    if (error instanceof ArchiveOriginIntegrityError) throw error;
+    await params.onBypass?.();
+    return createFallback(params, origin);
+  } finally {
+    clearTimeout(timer);
+    if (rejectCancellation) signal.removeEventListener("abort", rejectCancellation);
+  }
+}
+function createFallback(params, origin) {
+  return {
+    resultUrl: params.resultUrl,
+    downloadIdentity: origin?.identity,
+    archiveCacheBypassed: true,
+    isCached: false,
+    validateResponse(response) {
+      if (origin && createOriginIdentity(params.jobId, response) !== origin.identity)
+        rejectResponse(
+          response,
+          new ArchiveOriginIntegrityError("Parsed result origin archive identity changed.")
+        );
+      return response;
+    }
+  };
+}
+async function probeArchiveOrigin(params) {
+  const response = await fetch(params.resultUrl, {
+    headers: { Range: "bytes=0-0" },
+    signal: params.signal
+  });
+  try {
+    if (!response.ok) throw new Error(`Parsed result download failed (HTTP ${response.status}).`);
+    return {
+      identity: createOriginIdentity(params.jobId, response),
+      contentLength: readOriginLength(response),
+      entityTag: response.headers.get("etag")
+    };
+  } finally {
+    await response.body?.cancel();
+  }
+}
+async function prepareArchiveCache(params, origin, signal, mutations) {
+  const object = { ...params, path: "result.zip" };
+  const initialHead = await params.storage.headObject(object);
+  signal.throwIfAborted();
+  let marker = null;
+  if (initialHead) {
+    const version = readObjectVersion(initialHead);
+    const stored = await params.storage.readObject({
+      ...object,
+      path: createMarkerPath(origin.identity, version.entityTag)
+    });
+    signal.throwIfAborted();
+    if (stored) marker = readMarker(stored, params, origin, version);
+  }
+  if (!marker) marker = await storeArchive(params, origin, signal, mutations);
+  signal.throwIfAborted();
+  const resultUrl = await params.storage.getObjectUrl(object);
+  signal.throwIfAborted();
+  if (!resultUrl) throw new Error("Parsed result archive cache has no readable object URL.");
+  const validateResponse = (response2) => validateCachedResponse(response2, marker, params.signal);
+  const response = await fetch(resultUrl, {
+    headers: { Range: "bytes=0-0", "If-Match": marker.storageEntityTag },
+    signal
+  });
+  try {
+    if (response.headers.get("content-range") !== `bytes 0-0/${marker.contentLength}` || response.headers.get("content-length") !== "1")
+      rejectResponse(
+        response,
+        new ArchiveCacheTransportError("Parsed result archive cache probe exceeded one byte.")
+      );
+    const validated = validateResponse(response);
+    await validated.arrayBuffer();
+  } catch (error) {
+    await response.body?.cancel().catch(() => void 0);
+    throw error;
+  }
+  signal.throwIfAborted();
+  return {
+    resultUrl,
+    downloadIdentity: origin.identity,
+    archiveCacheBypassed: false,
+    isCached: true,
+    validateResponse
+  };
+}
+async function storeArchive(params, origin, signal, mutations) {
+  const response = await fetch(params.resultUrl, {
+    headers: { "If-Match": origin.entityTag },
+    signal
+  });
+  if (signal.aborted) {
+    await response.body?.cancel();
+    signal.throwIfAborted();
+  }
+  if (!response.ok || !response.body) {
+    await response.body?.cancel();
+    if (response.status === 412)
+      throw new ArchiveOriginIntegrityError("Parsed result origin archive identity changed.");
+    throw new Error(`Parsed result archive cache download failed (HTTP ${response.status}).`);
+  }
+  if (createOriginIdentity(params.jobId, response) !== origin.identity) {
+    await response.body.cancel();
+    throw new ArchiveOriginIntegrityError("Parsed result origin archive identity changed.");
+  }
+  const hash = (0, import_crypto.createHash)("sha256");
+  let contentLength = 0;
+  let hasCompleted = false;
+  const body = response.body.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        signal.throwIfAborted();
+        contentLength += chunk.length;
+        if (contentLength > origin.contentLength)
+          throw new ArchiveOriginIntegrityError("Parsed result origin archive length changed.");
+        hash.update(chunk);
+        controller.enqueue(chunk);
+      },
+      flush() {
+        if (contentLength !== origin.contentLength)
+          throw new ArchiveOriginIntegrityError("Parsed result origin archive length changed.");
+        hasCompleted = true;
+      }
+    })
+  );
+  const object = { ...params, path: "result.zip" };
+  let write;
+  try {
+    signal.throwIfAborted();
+    write = await settleMutation(
+      params.storage.writeObjectStream({
+        ...object,
+        body,
+        contentType: "application/zip",
+        contentLength: origin.contentLength,
+        signal
+      }),
+      mutations
+    );
+  } catch (error) {
+    await body.cancel(error).catch(() => void 0);
+    throw error;
+  }
+  signal.throwIfAborted();
+  if (!hasCompleted)
+    throw new Error("Parsed result archive cache sink did not consume the stream.");
+  if (!hasStrongEntityTag(write.entityTag))
+    throw new Error("Parsed result archive cache requires a strong object version.");
+  const head = await params.storage.headObject(object);
+  signal.throwIfAborted();
+  if (!head) throw new Error("Parsed result archive cache was not persisted.");
+  const actualVersion = readObjectVersion(head);
+  if (write.entityTag !== actualVersion.entityTag || actualVersion.contentLength !== contentLength)
+    throw new Error("Parsed result archive cache object version or length changed during upload.");
+  const marker = {
+    version: 1,
+    jobId: params.jobId,
+    revisionKey: params.revisionKey,
+    originIdentity: origin.identity,
+    contentLength,
+    sha256: hash.digest("hex"),
+    storageEntityTag: actualVersion.entityTag
+  };
+  signal.throwIfAborted();
+  await settleMutation(
+    params.storage.writeObject({
+      ...object,
+      path: createMarkerPath(origin.identity, actualVersion.entityTag),
+      body: Buffer.from(JSON.stringify(marker)),
+      contentType: "application/json; charset=utf-8"
+    }),
+    mutations
+  );
+  signal.throwIfAborted();
+  return marker;
+}
+async function settleMutation(mutation, mutations) {
+  mutations.add(mutation);
+  try {
+    return await mutation;
+  } finally {
+    mutations.delete(mutation);
+  }
+}
+function readMarker(object, params, origin, version) {
+  const value = JSON.parse(Buffer.from(object.body).toString("utf8"));
+  if (typeof value !== "object" || value === null || !("version" in value) || value.version !== 1 || !("jobId" in value) || value.jobId !== params.jobId || !("revisionKey" in value) || value.revisionKey !== params.revisionKey || !("originIdentity" in value) || value.originIdentity !== origin.identity || !("contentLength" in value) || value.contentLength !== origin.contentLength || value.contentLength !== version.contentLength || !("storageEntityTag" in value) || value.storageEntityTag !== version.entityTag || !("sha256" in value) || typeof value.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.sha256))
+    throw new Error("Parsed result archive cache completion marker is invalid.");
+  return {
+    version: 1,
+    jobId: params.jobId,
+    revisionKey: params.revisionKey,
+    originIdentity: origin.identity,
+    contentLength: version.contentLength,
+    storageEntityTag: version.entityTag,
+    sha256: value.sha256
+  };
+}
+function readObjectVersion(object) {
+  if (!hasStrongEntityTag(object.entityTag) || !isPositiveInteger(object.contentLength))
+    throw new Error("Parsed result archive cache requires a strong object version and length.");
+  return { entityTag: object.entityTag, contentLength: object.contentLength };
+}
+function validateCachedResponse(response, marker, signal) {
+  if (response.headers.get("etag") !== marker.storageEntityTag)
+    rejectResponse(
+      response,
+      new ArchiveCacheTransportError("Parsed result archive cache response version changed.")
+    );
+  if (response.status !== 206 || !response.body)
+    rejectResponse(
+      response,
+      new ArchiveCacheTransportError("Parsed result archive cache requires a ranged response.")
+    );
+  const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(
+    response.headers.get("content-range") ?? ""
+  );
+  const contentLength = Number(response.headers.get("content-length"));
+  if (!range || Number(range[3]) !== marker.contentLength || Number(range[1]) > Number(range[2]) || Number(range[2]) >= marker.contentLength || contentLength !== Number(range[2]) - Number(range[1]) + 1)
+    rejectResponse(
+      response,
+      new ArchiveCacheTransportError("Parsed result archive cache response length changed.")
+    );
+  let actualLength = 0;
+  return new Response(
+    response.body.pipeThrough(
+      new TransformStream({
+        transform(chunk, controller) {
+          signal?.throwIfAborted();
+          actualLength += chunk.length;
+          if (actualLength > contentLength)
+            throw new ArchiveCacheTransportError(
+              "Parsed result archive cache response length changed."
+            );
+          controller.enqueue(chunk);
+        },
+        flush() {
+          if (actualLength !== contentLength)
+            throw new ArchiveCacheTransportError(
+              "Parsed result archive cache response length changed."
+            );
+        }
+      })
+    ),
+    { status: response.status, statusText: response.statusText, headers: response.headers }
+  );
+}
+function rejectResponse(response, error) {
+  void response.body?.cancel(error).catch(() => void 0);
+  throw error;
+}
+function createMarkerPath(originIdentity, entityTag) {
+  const identity = (0, import_crypto.createHash)("sha256").update(JSON.stringify([originIdentity, entityTag])).digest("hex");
+  return `.knowhere-sdk/archive-cache/${identity}.json`;
+}
+function createOriginIdentity(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");
+}
+function readOriginLength(response) {
+  const value = Number(
+    response.headers.get("content-range")?.split("/").at(-1) ?? response.headers.get("content-length")
+  );
+  return isPositiveInteger(value) ? value : void 0;
+}
+function hasStrongEntityTag(value) {
+  return typeof value === "string" && value.length > 0 && !value.startsWith("W/");
+}
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+var import_crypto, ARCHIVE_CACHE_TIMEOUT_MS, ArchiveOriginIntegrityError;
+var init_parsed_document_archive_cache = __esm({
+  "src/storage/parsed-document-archive-cache.ts"() {
+    "use strict";
+    import_crypto = require("crypto");
+    init_archive_cache_transport_error();
+    ARCHIVE_CACHE_TIMEOUT_MS = 3e4;
+    ArchiveOriginIntegrityError = class extends Error {
+    };
+  }
+});
+
+// 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, validateResponse) {
+  let response = await fetch(params.resultUrl, { signal: params.signal });
+  if (!response.ok || !response.body)
+    throw new Error(`Parsed result download failed (HTTP ${response.status}).`);
+  if (validateResponse) response = validateResponse(response);
+  else if (createDownloadIdentity(params.jobId, response) !== identity) {
+    await response.body.cancel();
+    throw new Error("Parsed result archive identity changed before sequential download.");
+  }
+  const body = response.body;
+  if (!body) throw new Error("Parsed result download returned an empty body.");
+  let directory;
+  try {
+    directory = await (0, import_promises2.mkdtemp)((0, import_path2.join)((0, import_os.tmpdir)(), "knowhere-sync-"));
+  } catch (error) {
+    await 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 body.cancel();
+    await (0, import_promises2.rm)(directory, { recursive: true, force: true });
+    throw new ParsedDocumentArchiveError(error);
+  }
+  const input = import_stream.Readable.fromWeb(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,
+          contentLength: !(entry.vars.flags & 8) && "uncompressedSize" in entry.vars && typeof entry.vars.uncompressedSize === "number" ? entry.vars.uncompressedSize : void 0,
+          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();
+  validateArchiveSyncLimits(params.limits);
+  const startedAt = Date.now();
+  const maxEntries = params.limits?.maxEntriesPerSync ?? 100;
+  const deadlineMs = params.limits?.archiveSyncDeadlineMs ?? 12e4;
+  const checkpointFileInterval = params.limits?.checkpointFileInterval ?? 1;
+  const checkpointIntervalMs = params.limits?.checkpointIntervalMs ?? 2e3;
+  const controller = new AbortController();
+  const signal = params.signal ? AbortSignal.any([params.signal, controller.signal]) : controller.signal;
+  const transferParams = { ...params, signal };
+  const previous = await params.storage.readSyncProgress(params);
+  const source = await openArchive(transferParams, previous);
+  const concurrency = source.canSkipEntries ? params.limits?.maxConcurrentFiles ?? 1 : 1;
+  const nextEntry = previous?.status === "completed" ? 0 : previous?.nextArchiveEntry ?? 0;
+  const entryHashes = [];
+  const successfulHashes = /* @__PURE__ */ new Map();
+  const running = /* @__PURE__ */ new Set();
+  const paths = /* @__PURE__ */ new Set();
+  let entryIndex = 0;
+  let startedEntries = 0;
+  let successfulEntries = 0;
+  let checkpointEntry = nextEntry;
+  let checkpointAt = Date.now();
+  let failure;
+  let archiveCacheBypassed = source.archiveCacheBypassed;
+  async function flushProgress(isSegmentBoundary, isRecovering = false) {
+    let contiguousEntry = checkpointEntry;
+    while (successfulHashes.has(contiguousEntry)) {
+      entryHashes[contiguousEntry] = successfulHashes.get(contiguousEntry);
+      contiguousEntry += 1;
+    }
+    if (contiguousEntry === checkpointEntry) return;
+    await params.storage.writeSyncProgress(
+      {
+        documentId: params.documentId,
+        revisionKey: params.revisionKey,
+        pinnedRevisionKey: params.revisionKey,
+        archiveIdentity: source.identity,
+        archiveCacheBypassed,
+        archiveEntryHashes: entryHashes.slice(0, contiguousEntry),
+        nextArchiveEntry: contiguousEntry,
+        status: "running",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      { signal: isRecovering ? void 0 : signal, isSegmentBoundary }
+    );
+    for (let index = checkpointEntry; index < contiguousEntry; index += 1)
+      successfulHashes.delete(index);
+    checkpointEntry = contiguousEntry;
+    successfulEntries = successfulHashes.size;
+    checkpointAt = Date.now();
+  }
+  function startEntry(entry, index) {
+    const task = copyEntry(transferParams, entry).then(
+      (hash) => {
+        successfulHashes.set(index, hash);
+        successfulEntries += 1;
+      },
+      (error) => {
+        if (failure === void 0)
+          failure = error instanceof Error ? error : new Error(String(error));
+        controller.abort(error);
+      }
+    ).finally(() => {
+      running.delete(task);
+    });
+    running.add(task);
+  }
+  async function drainEntries() {
+    await Promise.all(running);
+    if (failure !== void 0) throw failure;
+    signal.throwIfAborted();
+  }
+  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) {
+      if (failure !== void 0) throw failure;
+      signal.throwIfAborted();
+      if (paths.has(entry.path)) throw new Error(`Duplicate parsed result path: ${entry.path}`);
+      paths.add(entry.path);
+      if (entryIndex < nextEntry) {
+        const previousHash = previous?.archiveEntryHashes?.[entryIndex];
+        if (!previousHash) throw new Error("Parsed archive checkpoint is missing an entry hash.");
+        if (!source.canSkipEntries && await copyEntry(transferParams, entry, true) !== previousHash)
+          throw new Error("Parsed result archive entry changed while resuming.");
+        entryHashes.push(previousHash);
+        entryIndex += 1;
+        continue;
+      }
+      if (startedEntries > 0 && (startedEntries >= maxEntries || Date.now() - startedAt >= deadlineMs)) {
+        await drainEntries();
+        await flushProgress(true);
+        return { documentId: params.documentId, revisionKey: params.revisionKey, completed: false };
+      }
+      if (successfulEntries >= checkpointFileInterval || Date.now() - checkpointAt >= checkpointIntervalMs) {
+        await drainEntries();
+        await flushProgress(false);
+      }
+      startEntry(entry, entryIndex);
+      entryIndex += 1;
+      startedEntries += 1;
+      if (running.size >= concurrency) await Promise.race(running);
+    }
+    await drainEntries();
+    await flushProgress(true);
+    await validateRequiredObjects(params, paths);
+    await params.verifyRevision?.();
+    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,
+        archiveCacheBypassed,
+        archiveEntryHashes: entryHashes,
+        nextArchiveEntry: entryIndex,
+        status: "completed",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      { signal, isSegmentBoundary: true }
+    );
+    if (params.retainResultArchive && !source.isCached) {
+      try {
+        await retainArchive(transferParams, source.downloadIdentity);
+      } catch {
+      }
+    }
+    return {
+      documentId: params.documentId,
+      revisionKey: params.revisionKey,
+      completed: true,
+      commit
+    };
+  } catch (error) {
+    controller.abort(error);
+    await Promise.all(running);
+    const hasCacheTransportFailure = error instanceof ArchiveCacheTransportError || failure instanceof ArchiveCacheTransportError;
+    if (hasCacheTransportFailure) archiveCacheBypassed = true;
+    await flushProgress(true, true).catch(() => void 0);
+    if (hasCacheTransportFailure) {
+      await persistArchiveCacheBypass(
+        { ...params, signal: void 0 },
+        {
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          pinnedRevisionKey: params.revisionKey,
+          archiveIdentity: source.identity,
+          archiveEntryHashes: entryHashes.slice(0, checkpointEntry),
+          nextArchiveEntry: checkpointEntry,
+          status: "running",
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      ).catch(() => void 0);
+    }
+    throw failure ?? error;
+  } finally {
+    controller.abort();
+    await Promise.all(running);
+    await source.close();
+  }
+}
+function validateArchiveSyncLimits(limits) {
+  const names = [
+    "maxEntriesPerSync",
+    "archiveSyncDeadlineMs",
+    "maxConcurrentFiles",
+    "checkpointFileInterval",
+    "checkpointIntervalMs"
+  ];
+  for (const name of names) {
+    const value = limits?.[name];
+    if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0))
+      throw new ValidationError(`${name} must be a positive safe integer.`);
+  }
+}
+async function copyEntry(params, entry, isVerification = false) {
+  const hash = (0, import_crypto2.createHash)("sha256");
+  const body = entry.read().pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        params.signal?.throwIfAborted();
+        hash.update(chunk);
+        controller.enqueue(chunk);
+      }
+    })
+  );
+  if (isVerification)
+    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),
+      contentLength: entry.contentLength,
+      signal: params.signal
+    });
+  return (0, import_crypto2.createHash)("sha256").update(entry.path).update(hash.digest()).digest("hex");
+}
+async function openArchive(params, previous) {
+  const prepared = params.cacheResultArchive ? await prepareCachedArchive({
+    ...params,
+    archiveCacheBypassed: previous?.archiveCacheBypassed,
+    onBypass: async () => {
+      await persistArchiveCacheBypass(params, previous);
+    }
+  }) : void 0;
+  try {
+    return await openArchiveTransport(params, previous, prepared);
+  } catch (error) {
+    if (!prepared?.isCached) throw error;
+    params.signal?.throwIfAborted();
+    const bypass = await persistArchiveCacheBypass(params, previous);
+    return openArchive({ ...params, cacheResultArchive: false }, bypass);
+  }
+}
+async function persistArchiveCacheBypass(params, previous) {
+  const progress = {
+    ...previous?.status === "completed" ? {} : previous,
+    documentId: params.documentId,
+    revisionKey: params.revisionKey,
+    pinnedRevisionKey: params.revisionKey,
+    archiveCacheBypassed: true,
+    status: "running",
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await params.storage.writeSyncProgress(progress, { signal: params.signal });
+  return progress;
+}
+async function openArchiveTransport(params, previous, prepared) {
+  const resultUrl = prepared?.resultUrl ?? params.resultUrl;
+  const archiveCacheBypassed = prepared?.archiveCacheBypassed ?? previous?.archiveCacheBypassed;
+  let probe = await fetch(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}).`);
+  }
+  if (prepared) probe = prepared.validateResponse(probe);
+  const identity = prepared?.downloadIdentity ?? 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));
+    const source = await openSequentialArchive2(
+      { ...params, resultUrl },
+      identity,
+      prepared?.isCached ? prepared.validateResponse : void 0
+    );
+    return { ...source, archiveCacheBypassed };
+  }
+  const options = {
+    forceRangeRequests: true,
+    preventHeadRequest: true,
+    checkResourceChanges: true,
+    fetch: async (input, init) => {
+      let response;
+      try {
+        response = await fetch(input, { ...init, signal: params.signal });
+      } catch (error) {
+        params.signal?.throwIfAborted();
+        if (prepared?.isCached)
+          throw new ArchiveCacheTransportError(
+            "Parsed result archive cache transport unavailable."
+          );
+        throw error;
+      }
+      if (prepared?.isCached) return prepared.validateResponse(response);
+      if (response.status !== 206) {
+        await response.body?.cancel();
+        throw new Error(`Parsed result Range request failed (HTTP ${response.status}).`);
+      }
+      return prepared ? prepared.validateResponse(response) : response;
+    }
+  };
+  const reader = new import_zip2.ZipReader(new import_zip2.HttpRangeReader(resultUrl, options), {
+    useWebWorkers: false,
+    checkCrc32: true
+  });
+  const producers = /* @__PURE__ */ new Set();
+  try {
+    const entries = await reader.getEntries();
+    const files = entries.filter(
+      (entry) => !entry.directory && isSnapshotPath(entry.filename)
+    );
+    const archiveIdentity = (0, import_crypto2.createHash)("sha256").update(identity).update(
+      JSON.stringify(
+        files.map((entry) => [entry.filename, entry.uncompressedSize, entry.signature])
+      )
+    ).digest("hex");
+    return {
+      identity: previous?.archiveIdentity === identity ? identity : archiveIdentity,
+      downloadIdentity: identity,
+      archiveCacheBypassed,
+      isCached: prepared?.isCached,
+      canSkipEntries: previous?.archiveIdentity !== identity,
+      entries: (function* () {
+        for (const entry of files)
+          yield {
+            path: normalizeResultPath(entry.filename),
+            contentLength: entry.uncompressedSize,
+            read: () => readRangeEntry(entry, params.signal, producers)
+          };
+      })(),
+      close: async () => {
+        await Promise.all(producers);
+        await reader.close();
+      }
+    };
+  } catch (error) {
+    await reader.close();
+    throw error;
+  }
+}
+function readRangeEntry(entry, signal, producers) {
+  const stream = new TransformStream();
+  const producer = entry.getData(stream.writable, { signal, checkCrc32: true, useWebWorkers: false }).then(
+    () => void 0,
+    async (error) => {
+      try {
+        await stream.writable.abort(error);
+      } catch {
+      }
+    }
+  ).finally(() => {
+    producers.delete(producer);
+  });
+  producers.add(producer);
+  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_crypto2.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_crypto2, import_zip2;
+var init_streamed_parsed_document_sync = __esm({
+  "src/storage/streamed-parsed-document-sync.ts"() {
+    "use strict";
+    import_crypto2 = require("crypto");
+    init_errors();
+    init_archive_cache_transport_error();
+    init_parsed_document_archive_cache();
+    import_zip2 = require("@zip.js/zip.js");
+    init_parsed_document_storage();
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  AuthenticationError: () => AuthenticationError,
+  BadRequestError: () => BadRequestError,
+  ChecksumError: () => ChecksumError,
+  ConflictError: () => ConflictError,
+  DiskParsedDocumentStorage: () => DiskParsedDocumentStorage,
+  Documents: () => Documents,
+  GatewayTimeoutError: () => GatewayTimeoutError,
+  InternalServerError: () => InternalServerError,
+  InvalidStateError: () => InvalidStateError,
+  JobFailedError: () => JobFailedError,
+  Jobs: () => Jobs,
+  Knowhere: () => Knowhere,
+  KnowhereError: () => KnowhereError,
+  Knowledge: () => Knowledge,
+  LocalKnowledgeStore: () => LocalKnowledgeStore,
+  NODE_SDK_DOCUMENT_METADATA_DEFAULTS: () => NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  ParsedDocumentArchiveError: () => ParsedDocumentArchiveError,
+  PaymentRequiredError: () => PaymentRequiredError,
+  PermissionDeniedError: () => PermissionDeniedError,
+  PollingTimeoutError: () => PollingTimeoutError,
+  RateLimitError: () => RateLimitError,
+  Retrieval: () => Retrieval,
+  ServiceUnavailableError: () => ServiceUnavailableError,
+  TimeoutError: () => TimeoutError,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
+  default: () => Knowhere,
+  mergeDocumentMetadataDefaults: () => mergeDocumentMetadataDefaults,
+  storeParseResultAssets: () => storeParseResultAssets,
+  syncParseResultToParsedDocumentStorage: () => syncParseResultToParsedDocumentStorage
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_path4 = __toESM(require("path"));
+
+// src/lib/http-client.ts
+var import_axios = __toESM(require("axios"));
+
+// src/version.ts
+var VERSION = "2.1.3";
+
+// src/lib/http-client.ts
+init_constants();
+init_errors();
+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;
@@ -780,6 +1989,7 @@ function mergeDocumentMetadataDefaults(defaults, provided) {
 
 // src/lib/upload.ts
 var import_fs = require("fs");
+init_errors();
 async function uploadFile(httpClient, uploadUrl, file, options) {
   let data;
   let contentLength;
@@ -815,6 +2025,9 @@ function isReadStream(obj) {
 }
 
 // src/lib/polling.ts
+init_constants();
+init_errors();
+init_utils();
 async function pollJobStatus(httpClient, jobId, options) {
   const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL;
   const pollTimeout = options?.pollTimeout ?? DEFAULT_POLL_TIMEOUT;
@@ -865,6 +2078,8 @@ async function pollJobStatus(httpClient, jobId, options) {
 var import_jszip = __toESM(require("jszip"));
 var import_fs2 = require("fs");
 var import_path = require("path");
+init_errors();
+init_utils();
 async function parseResult(httpClient, resultUrl, options) {
   const zipBuffer = await httpClient.download(resultUrl);
   if (options?.verifyChecksum !== false) {
@@ -1367,6 +2582,8 @@ function isMissingFileError(error) {
 }
 
 // src/resources/jobs.ts
+init_utils();
+init_errors();
 var Jobs = class extends BaseResource {
   pendingUploadJobs = /* @__PURE__ */ new Map();
   /**
@@ -1607,7 +2824,8 @@ var Documents = class extends BaseResource {
 };
 
 // src/knowledge/knowledge.ts
-var import_crypto2 = require("crypto");
+var import_crypto4 = require("crypto");
+init_errors();
 
 // src/storage/asset-storage.ts
 var import_jszip2 = __toESM(require("jszip"));
@@ -1871,220 +3089,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_crypto3 = 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 +3106,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 +3232,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 +3267,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 +3275,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_crypto3.createHash)("sha256").update(result.jobId).update("\0").update(result.manifest.sourceFileName).digest("hex").slice(0, 16);
   return `local_${hash}`;
 }
 function countChunkTypes(result) {
@@ -2419,29 +3433,35 @@ var Knowledge = class _Knowledge {
     return this.importJobResult(params);
   }
   async syncParsedDocument(params) {
+    params.signal?.throwIfAborted();
     const normalized = normalizeDocumentReference(params);
     const parsedStorageConfig = this.requireParsedStorageConfig();
+    validateArchiveSyncLimits(parsedStorageConfig.limits);
     if (normalized.documentId) {
       return this.syncRemoteDocumentToParsedStorage({
         documentId: normalized.documentId,
         revisionKey: params.revisionKey,
-        parsedStorageConfig
+        parsedStorageConfig,
+        signal: params.signal,
+        retainResultArchive: params.retainResultArchive,
+        cacheResultArchive: params.cacheResultArchive
       });
     }
     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,
+        cacheResultArchive: params.cacheResultArchive
       });
-      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 +4159,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 +4176,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 +4184,68 @@ 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,
+          cacheResultArchive: params.cacheResultArchive,
+          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 +4257,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 +4311,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 +4399,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_crypto4.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
   return `remote_${hash}`;
 }
 var defaultParsedStorageScheduler = {
@@ -3558,10 +4619,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 +4642,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 +4741,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 +4770,7 @@ function getStoredPageAssets(metadata) {
   return pageAssets?.map(normalizeStoredPageAsset);
 }
 function normalizeStoredPageAsset(pageAsset) {
-  if (!isRecord2(pageAsset)) {
+  if (!isRecord3(pageAsset)) {
     return pageAsset;
   }
   const normalizedPageAsset = { ...pageAsset };
@@ -3787,7 +4848,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 +4886,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 +5193,25 @@ 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_errors();
+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 +5357,9 @@ var Knowhere = class {
 };
 
 // src/storage/disk-parsed-document-storage.ts
-var import_crypto3 = require("crypto");
+var import_crypto5 = 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 +5388,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 +5447,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 +5490,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_crypto5.createHash)("sha256").update(normalized).digest("hex").slice(0, 24);
 }
 function normalizeRelativeStoragePath(value) {
   const normalized = value.replaceAll("\\", "/").replace(/^\.\/+/, "");
@@ -4431,8 +5500,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 +5509,10 @@ 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();
+init_errors();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
@@ -4461,6 +5534,7 @@ function isMissingFileError3(error) {
   NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError,
   NotFoundError,
+  ParsedDocumentArchiveError,
   PaymentRequiredError,
   PermissionDeniedError,
   PollingTimeoutError,