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

package/dist/index.mjs

@@ -1,3 +1,54 @@
+import {
+  APIError,
+  AuthenticationError,
+  BadRequestError,
+  ChecksumError,
+  ConflictError,
+  DEFAULT_BASE_URL,
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_POLL_INTERVAL,
+  DEFAULT_POLL_TIMEOUT,
+  DEFAULT_TIMEOUT,
+  ENV,
+  GatewayTimeoutError,
+  INITIAL_RETRY_DELAY,
+  InternalServerError,
+  InvalidStateError,
+  JobFailedError,
+  KnowhereError,
+  MAX_POLL_INTERVAL,
+  MAX_RETRY_DELAY,
+  NetworkError,
+  NotFoundError,
+  POLL_INTERVAL_INCREASE_THRESHOLD,
+  POLL_INTERVAL_MULTIPLIER,
+  ParsedDocumentArchiveError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  PollingTimeoutError,
+  RETRYABLE_STATUS_CODES,
+  RETRY_DELAY_BASE,
+  RateLimitError,
+  ServiceUnavailableError,
+  TimeoutError,
+  ValidationError,
+  createAPIError,
+  enrichJobResult,
+  enrichParseResult,
+  getFileExtension,
+  jitter,
+  keysToCamel,
+  keysToSnake,
+  parseDates,
+  readJsonObject,
+  readParsedDocumentCommit,
+  sanitizePath,
+  sleep,
+  syncParseResultToParsedDocumentStorage,
+  syncRemoteResultArchive,
+  validateArchiveSyncLimits
+} from "./chunk-FESTKAG6.mjs";
+
 // src/client.ts
 import path2 from "path";
 
@@ -9,321 +60,6 @@ import 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/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/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:
-      return new BadRequestError(message, code, requestId, details, body);
-    case 401:
-      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);
-  }
-  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);
-}
-
 // src/lib/retry.ts
 function getErrorCode(error) {
   const errorWithResponse = error;
@@ -1806,215 +1542,6 @@ function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 
-// src/storage/parsed-document-storage.ts
-import JSZip3 from "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 JSZip3.loadAsync(rawZip);
-    const objects = [];
-    for (const entry of Object.values(zip.files)) {
-      if (entry.dir || entry.name === "result.zip") {
-        continue;
-      }
-      objects.push({
-        path: normalizeResultPath(entry.name),
-        body: new Uint8Array(await entry.async("nodebuffer")),
-        contentType: inferContentTypeFromPath(entry.name)
-      });
-    }
-    return objects;
-  } catch {
-    return [];
-  }
-}
-function collectGeneratedResultObjects(result) {
-  const objects = [
-    createJsonObject("manifest.json", result.manifest),
-    createJsonObject("chunks.json", keysToSnake(serializeChunks2(result.chunks)))
-  ];
-  if (result.docNav) {
-    objects.push(createJsonObject("doc_nav.json", result.docNav));
-  }
-  if (result.fullMarkdown) {
-    objects.push(createTextObject("full.md", result.fullMarkdown, markdownContentType));
-  }
-  if (result.chunksSlim) {
-    objects.push(createJsonObject("chunks_slim.json", { chunks: result.chunksSlim }));
-  }
-  if (result.hierarchy) {
-    objects.push(createJsonObject("hierarchy.json", result.hierarchy));
-  }
-  if (result.tocHierarchies) {
-    objects.push(createJsonObject("toc_hierarchies.json", result.tocHierarchies));
-  }
-  if (result.kbCsv) {
-    objects.push(createTextObject("kb.csv", result.kbCsv, csvContentType));
-  }
-  if (result.hierarchyViewHtml) {
-    objects.push(
-      createTextObject("hierarchy_view.html", result.hierarchyViewHtml, htmlContentType)
-    );
-  }
-  for (const chunk of result.imageChunks) {
-    objects.push({
-      path: normalizeResultPath(chunk.filePath),
-      body: new Uint8Array(chunk.data),
-      contentType: inferContentTypeFromPath(chunk.filePath),
-      metadata: {
-        chunkId: chunk.chunkId,
-        chunkType: chunk.type,
-        sourcePath: chunk.filePath
-      }
-    });
-  }
-  for (const chunk of result.tableChunks) {
-    objects.push({
-      path: normalizeResultPath(chunk.filePath),
-      body: Buffer.from(chunk.html, "utf8"),
-      contentType: htmlContentType,
-      metadata: {
-        chunkId: chunk.chunkId,
-        chunkType: chunk.type,
-        sourcePath: chunk.filePath
-      }
-    });
-  }
-  return objects;
-}
-function serializeChunks2(chunks) {
-  return {
-    chunks: chunks.map((chunk) => {
-      const rawChunk = {
-        chunkId: chunk.chunkId,
-        type: chunk.type,
-        contentSource: chunk.contentSource,
-        content: chunk.content,
-        path: chunk.path,
-        metadata: chunk.metadata
-      };
-      if (chunk.type === "image" || chunk.type === "table") {
-        return {
-          ...rawChunk,
-          filePath: chunk.filePath,
-          assetUrl: chunk.assetUrl
-        };
-      }
-      return rawChunk;
-    })
-  };
-}
-async function writeParsedDocumentJsonObject(storage, params) {
-  await storage.writeObject({
-    documentId: params.documentId,
-    revisionKey: params.revisionKey,
-    path: params.path,
-    body: Buffer.from(JSON.stringify(params.value, null, 2), "utf8"),
-    contentType: jsonContentType
-  });
-}
-function createJsonObject(path4, value) {
-  return {
-    path: path4,
-    body: Buffer.from(JSON.stringify(value, null, 2), "utf8"),
-    contentType: jsonContentType
-  };
-}
-function createTextObject(path4, value, contentType) {
-  return {
-    path: path4,
-    body: Buffer.from(value, "utf8"),
-    contentType
-  };
-}
-function inferContentTypeFromPath(filePath) {
-  const lower = filePath.toLowerCase();
-  if (lower.endsWith(".json")) return jsonContentType;
-  if (lower.endsWith(".md")) return markdownContentType;
-  if (lower.endsWith(".csv")) return csvContentType;
-  if (lower.endsWith(".html") || lower.endsWith(".htm")) return htmlContentType;
-  if (lower.endsWith(".png")) return "image/png";
-  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
-  if (lower.endsWith(".gif")) return "image/gif";
-  if (lower.endsWith(".webp")) return "image/webp";
-  if (lower.endsWith(".svg")) return "image/svg+xml";
-  return binaryContentType;
-}
-function normalizeResultPath(value) {
-  const normalized = value.replaceAll("\\", "/").replace(/^\.\/+/, "");
-  if (normalized.length === 0 || normalized.includes("\0") || normalized.startsWith("/") || normalized.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
-    throw new Error(`Invalid parsed result path: ${value}`);
-  }
-  return normalized;
-}
-function isSdkMetadataPath(path4) {
-  return path4 === ".knowhere-sdk" || path4.startsWith(".knowhere-sdk/");
-}
-
 // src/knowledge/local-store.ts
 import { createHash } from "crypto";
 import os from "os";
@@ -2354,29 +1881,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");
@@ -3074,10 +2607,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)
@@ -3087,6 +2624,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,
@@ -3094,55 +2632,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();
@@ -3154,6 +2705,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,
@@ -3201,7 +2759,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,
@@ -3401,7 +2975,7 @@ function toMinimalChunkFromRemoteChunk(chunk) {
       filePath: chunk.filePath ?? "",
       assetUrl: chunk.assetUrl ?? void 0,
       data: Buffer.alloc(0),
-      format: inferContentTypeFromPath2(chunk.filePath ?? "").replace("image/", ""),
+      format: inferContentTypeFromPath(chunk.filePath ?? "").replace("image/", ""),
       save: () => Promise.resolve(chunk.filePath ?? "")
     };
   }
@@ -3753,7 +3327,7 @@ function cloneMetadata(metadata) {
 function toUnknownArray(value) {
   return Array.isArray(value) ? value : null;
 }
-function inferContentTypeFromPath2(filePath) {
+function inferContentTypeFromPath(filePath) {
   const extension = filePath.split(".").at(-1)?.toLowerCase();
   if (extension === "png") return "image/png";
   if (extension === "jpg" || extension === "jpeg") return "image/jpeg";
@@ -4067,6 +3641,11 @@ 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
 function inferFileName(file, explicitFileName) {
@@ -4395,6 +3974,7 @@ export {
   NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError,
   NotFoundError,
+  ParsedDocumentArchiveError,
   PaymentRequiredError,
   PermissionDeniedError,
   PollingTimeoutError,