@ontos-ai/knowhere-sdk 2.6.1-beta.20261027152313 → 2.7.0

package/dist/index.js

@@ -258,9 +258,7 @@ var init_parsed_document_archive_error = __esm({
       code = "ARCHIVE_SPOOL_FAILED";
       cause;
       constructor(cause) {
-        super(
-          "Parsed result ZIP temporary storage is unavailable. Range-enabled object storage avoids temporary disk usage."
-        );
+        super("Parsed result ZIP temporary storage is unavailable.");
         this.name = "ParsedDocumentArchiveError";
         this.cause = cause;
       }
@@ -856,17 +854,15 @@ function readObjectVersion(object) {
   return { entityTag: object.entityTag, contentLength: object.contentLength };
 }
 function validateCachedResponse(response, marker, signal) {
-  if (response.status !== 206 || !response.body)
+  if (response.headers.get("etag") !== marker.storageEntityTag)
     rejectResponse(
       response,
-      new ArchiveCacheTransportError(
-        `Parsed result archive cache requires a ranged response (HTTP ${response.status}).`
-      )
+      new ArchiveCacheTransportError("Parsed result archive cache response version changed.")
     );
-  if (response.headers.get("etag") !== marker.storageEntityTag)
+  if (response.status !== 206 || !response.body)
     rejectResponse(
       response,
-      new ArchiveCacheTransportError("Parsed result archive cache response version changed.")
+      new ArchiveCacheTransportError("Parsed result archive cache requires a ranged response.")
     );
   const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(
     response.headers.get("content-range") ?? ""
@@ -949,7 +945,10 @@ __export(sequential_parsed_document_archive_exports, {
   openSequentialArchive: () => openSequentialArchive
 });
 async function openSequentialArchive(params, identity, validateResponse) {
-  let response = await fetch(params.resultUrl, { signal: params.signal });
+  let response = await fetch(params.resultUrl, {
+    signal: params.signal,
+    headers: validateResponse ? { Range: "bytes=0-" } : void 0
+  });
   if (!response.ok || !response.body)
     throw new Error(`Parsed result download failed (HTTP ${response.status}).`);
   if (validateResponse) response = validateResponse(response);
@@ -978,9 +977,11 @@ async function openSequentialArchive(params, identity, validateResponse) {
   const parser = (0, import_parse.default)({ forceStream: true });
   const checksums = /* @__PURE__ */ new Map();
   let archiveSize = 0;
+  const archiveHash = (0, import_crypto2.createHash)("sha256");
   const spool = new import_stream.Transform({
     transform(chunk, _encoding, callback) {
       archiveSize += chunk.length;
+      archiveHash.update(chunk);
       void file.writeFile(chunk).then(
         () => {
           callback(null, chunk);
@@ -997,6 +998,23 @@ async function openSequentialArchive(params, identity, validateResponse) {
     identity,
     downloadIdentity: identity,
     canSkipEntries: false,
+    readArchive: () => {
+      let position = 0;
+      return new ReadableStream({
+        async pull(controller) {
+          params.signal?.throwIfAborted();
+          if (position >= archiveSize) {
+            controller.close();
+            return;
+          }
+          const body2 = new Uint8Array(Math.min(65536, archiveSize - position));
+          const { bytesRead } = await file.read(body2, 0, body2.length, position);
+          if (bytesRead !== body2.length) throw new Error("Truncated verified archive spool.");
+          position += bytesRead;
+          controller.enqueue(body2);
+        }
+      });
+    },
     entries: (async function* () {
       for await (const value of parser) {
         const entry = value;
@@ -1027,6 +1045,8 @@ async function openSequentialArchive(params, identity, validateResponse) {
         };
       }
       await completed;
+      if (params.snapshot && archiveHash.digest("hex") !== params.snapshot.checksum)
+        throw new Error("Parsed snapshot archive checksum mismatch for extracted bytes.");
       const reader = new import_zip.ZipReader(new DiskArchiveReader(file, archiveSize), {
         useWebWorkers: false
       });
@@ -1058,10 +1078,11 @@ async function openSequentialArchive(params, identity, validateResponse) {
     }
   };
 }
-var import_stream, import_promises, import_promises2, import_os, import_path2, import_zlib, import_zip, import_parse, DiskArchiveReader;
+var import_crypto2, 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_crypto2 = require("crypto");
     import_stream = require("stream");
     import_promises = require("stream/promises");
     import_promises2 = require("fs/promises");
@@ -1101,14 +1122,10 @@ async function syncRemoteResultArchive(params) {
   const checkpointIntervalMs = params.limits?.checkpointIntervalMs ?? 2e3;
   const controller = new AbortController();
   const signal = params.signal ? AbortSignal.any([params.signal, controller.signal]) : controller.signal;
-  const openingParams = { ...params, signal };
+  const transferParams = { ...params, signal };
   const previous = await params.storage.readSyncProgress(params);
-  const openedSource = await openArchive(openingParams, previous);
+  const openedSource = await openArchive(transferParams, previous);
   const source = !openedSource.canSkipEntries && previous?.archiveIdentity && previous.archiveDownloadIdentity === openedSource.downloadIdentity ? { ...openedSource, identity: previous.archiveIdentity } : openedSource;
-  const transferParams = {
-    ...openingParams,
-    signal: source.signal ?? signal
-  };
   const archiveDownloadIdentity = source.isCached ? source.downloadIdentity : previous?.archiveDownloadIdentity;
   const concurrency = source.canSkipEntries ? params.limits?.maxConcurrentFiles ?? 1 : 1;
   const nextEntry = previous?.status === "completed" ? 0 : previous?.nextArchiveEntry ?? 0;
@@ -1135,6 +1152,8 @@ async function syncRemoteResultArchive(params) {
         documentId: params.documentId,
         revisionKey: params.revisionKey,
         pinnedRevisionKey: params.revisionKey,
+        snapshotChecksum: params.snapshot?.checksum,
+        upstreamJobResultId: params.snapshot?.jobResultId,
         archiveIdentity: source.identity,
         archiveDownloadIdentity,
         archiveCacheBypassed,
@@ -1173,10 +1192,38 @@ async function syncRemoteResultArchive(params) {
     signal.throwIfAborted();
   }
   try {
-    if (previous?.archiveIdentity && previous.archiveIdentity !== source.identity)
+    if (previous?.snapshotChecksum && previous.snapshotChecksum !== params.snapshot?.checksum)
+      throw new Error("Parsed snapshot checksum changed within one generation.");
+    if (previous?.upstreamJobResultId && previous.upstreamJobResultId !== params.snapshot?.jobResultId)
+      throw new Error("Parsed snapshot upstream revision changed within one generation.");
+    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)
+    }
+    if (previous?.pinnedRevisionKey && previous.pinnedRevisionKey !== params.revisionKey) {
       throw new Error("Parsed result revision changed while resuming archive sync.");
+    }
+    if (params.snapshot && previous?.status === "completed") {
+      const committed = await readParsedDocumentCommit(params);
+      if (committed) {
+        if (source.verifyArchiveChecksum) {
+          await source.verifyArchiveChecksum(previous.archiveEntryHashes ?? []);
+        } else {
+          await verifyArchiveChecksum(
+            params,
+            source.downloadIdentity,
+            previous.archiveEntryHashes ?? [],
+            params.retainResultArchive
+          );
+        }
+        return {
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          snapshot: params.snapshot,
+          completed: true,
+          commit: committed
+        };
+      }
+    }
     for await (const entry of source.entries) {
       if (failure !== void 0) throw failure;
       signal.throwIfAborted();
@@ -1194,7 +1241,12 @@ async function syncRemoteResultArchive(params) {
       if (startedEntries > 0 && (startedEntries >= maxEntries || Date.now() - startedAt >= deadlineMs)) {
         await drainEntries();
         await flushProgress(true);
-        return { documentId: params.documentId, revisionKey: params.revisionKey, completed: false };
+        return {
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          snapshot: params.snapshot,
+          completed: false
+        };
       }
       if (successfulEntries >= checkpointFileInterval || Date.now() - checkpointAt >= checkpointIntervalMs) {
         await drainEntries();
@@ -1208,9 +1260,16 @@ async function syncRemoteResultArchive(params) {
     await drainEntries();
     await flushProgress(true);
     await validateRequiredObjects(params, paths);
+    if (params.snapshot && source.canSkipEntries)
+      if (source.verifyArchiveChecksum) await source.verifyArchiveChecksum(entryHashes);
+      else await verifyArchiveChecksum(params, source.downloadIdentity, entryHashes);
     await params.verifyRevision?.();
     signal.throwIfAborted();
     const commit = {
+      snapshotId: params.snapshot?.snapshotId,
+      jobResultId: params.snapshot?.jobResultId,
+      checksum: params.snapshot?.checksum,
+      stage: params.snapshot?.stage,
       version: 1,
       documentId: params.documentId,
       revisionKey: params.revisionKey,
@@ -1229,6 +1288,8 @@ async function syncRemoteResultArchive(params) {
         documentId: params.documentId,
         revisionKey: params.revisionKey,
         pinnedRevisionKey: params.revisionKey,
+        snapshotChecksum: params.snapshot?.checksum,
+        upstreamJobResultId: params.snapshot?.jobResultId,
         archiveIdentity: source.identity,
         archiveDownloadIdentity,
         archiveCacheBypassed,
@@ -1249,6 +1310,7 @@ async function syncRemoteResultArchive(params) {
       documentId: params.documentId,
       revisionKey: params.revisionKey,
       completed: true,
+      snapshot: params.snapshot,
       commit
     };
   } catch (error) {
@@ -1264,6 +1326,8 @@ async function syncRemoteResultArchive(params) {
           documentId: params.documentId,
           revisionKey: params.revisionKey,
           pinnedRevisionKey: params.revisionKey,
+          snapshotChecksum: params.snapshot?.checksum,
+          upstreamJobResultId: params.snapshot?.jobResultId,
           archiveIdentity: source.identity,
           archiveDownloadIdentity,
           archiveEntryHashes: entryHashes.slice(0, checkpointEntry),
@@ -1305,7 +1369,7 @@ function validateArchiveSyncLimits(limits) {
   }
 }
 async function copyEntry(params, entry, isVerification = false) {
-  const hash = (0, import_crypto2.createHash)("sha256");
+  const hash = (0, import_crypto3.createHash)("sha256");
   const body = entry.read().pipeThrough(
     new TransformStream({
       transform(chunk, controller) {
@@ -1328,7 +1392,7 @@ async function copyEntry(params, entry, isVerification = false) {
       signal: params.signal
     });
   await entry.waitForRead?.();
-  return (0, import_crypto2.createHash)("sha256").update(entry.path).update(hash.digest()).digest("hex");
+  return (0, import_crypto3.createHash)("sha256").update(entry.path).update(hash.digest()).digest("hex");
 }
 async function openArchive(params, previous) {
   const prepared = params.cacheResultArchive ? await prepareCachedArchive({
@@ -1353,6 +1417,8 @@ async function persistArchiveCacheBypass(params, previous) {
     documentId: params.documentId,
     revisionKey: params.revisionKey,
     pinnedRevisionKey: params.revisionKey,
+    snapshotChecksum: params.snapshot?.checksum,
+    upstreamJobResultId: params.snapshot?.jobResultId,
     archiveDownloadIdentity: previous?.archiveDownloadIdentity,
     archiveCacheBypassed: true,
     status: "running",
@@ -1385,43 +1451,32 @@ async function openArchiveTransport(params, previous, prepared) {
     );
     return { ...source, archiveCacheBypassed };
   }
-  const rangeController = new AbortController();
-  const rangeSignal = params.signal ? AbortSignal.any([params.signal, rangeController.signal]) : rangeController.signal;
   const options = {
     forceRangeRequests: true,
     preventHeadRequest: true,
     // Cached reads already pin a strong ETag and exact lengths; CDN timestamps can drift.
     checkResourceChanges: !prepared?.isCached,
     fetch: async (input, init) => {
+      let response;
       try {
-        let response;
-        try {
-          response = await fetch(input, { ...init, signal: rangeSignal });
-        } catch (error) {
-          rangeSignal.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) {
-          const error = new Error(
-            `Parsed result Range request failed (HTTP ${response.status}).`
-          );
-          rangeController.abort(error);
-          await response.body?.cancel(error).catch(() => void 0);
-          throw error;
-        }
-        return prepared ? prepared.validateResponse(response) : response;
+        response = await fetch(input, { ...init, signal: params.signal });
       } catch (error) {
-        rangeController.abort(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 AbortableHttpRangeReader(resultUrl, options, rangeController), {
+  const reader = new import_zip2.ZipReader(new import_zip2.HttpRangeReader(resultUrl, options), {
     useWebWorkers: false,
     checkCrc32: true
   });
@@ -1431,17 +1486,23 @@ async function openArchiveTransport(params, previous, prepared) {
     const files = entries.filter(
       (entry) => !entry.directory && isSnapshotPath(entry.filename)
     );
-    const archiveIdentity = (0, import_crypto2.createHash)("sha256").update(identity).update(
+    const archiveIdentity = (0, import_crypto3.createHash)("sha256").update(identity).update(
       JSON.stringify(
         files.map((entry) => [entry.filename, entry.uncompressedSize, entry.signature])
       )
     ).digest("hex");
     return {
-      signal: rangeSignal,
       identity: previous?.archiveIdentity === identity ? identity : archiveIdentity,
       downloadIdentity: identity,
       archiveCacheBypassed,
       isCached: prepared?.isCached,
+      verifyArchiveChecksum: prepared?.isCached ? (entryHashes) => verifyArchiveChecksum(
+        { ...params, resultUrl },
+        identity,
+        entryHashes,
+        false,
+        prepared.validateResponse
+      ) : void 0,
       canSkipEntries: previous?.archiveIdentity !== identity,
       entries: (function* () {
         for (const entry of files) {
@@ -1450,7 +1511,7 @@ async function openArchiveTransport(params, previous, prepared) {
             path: normalizeResultPath(entry.filename),
             contentLength: entry.uncompressedSize,
             read: () => {
-              entryRead = readRangeEntry(entry, rangeSignal, producers);
+              entryRead = readRangeEntry(entry, params.signal, producers);
               return entryRead.body;
             },
             waitForRead: () => entryRead?.completed ?? Promise.resolve()
@@ -1463,7 +1524,6 @@ async function openArchiveTransport(params, previous, prepared) {
       }
     };
   } catch (error) {
-    rangeController.abort(error);
     await reader.close();
     throw error;
   }
@@ -1475,16 +1535,10 @@ function readRangeEntry(entry, signal, producers) {
       streamController = controller;
     }
   });
-  const cancelOutput = () => {
-    streamController?.error(signal?.reason);
-  };
-  signal?.addEventListener("abort", cancelOutput, { once: true });
-  if (signal?.aborted) cancelOutput();
   const completed = entry.getData(stream.writable, { signal, checkCrc32: true, useWebWorkers: false }).then(() => void 0);
   const producer = completed.catch((error) => {
     streamController?.error(error);
   }).finally(() => {
-    signal?.removeEventListener("abort", cancelOutput);
     producers.delete(producer);
   });
   producers.add(producer);
@@ -1521,6 +1575,9 @@ async function validateRequiredObjects(params, paths) {
   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 manifestRevision = manifest.job_result_id ?? manifest.jobResultId;
+  if (params.snapshot && manifestRevision !== void 0 && manifestRevision !== params.snapshot.jobResultId)
+    throw new Error("Parsed result manifest revision differs from the snapshot upstream revision.");
   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)) {
@@ -1545,7 +1602,49 @@ async function validateRequiredObjects(params, paths) {
   for (const path4 of required)
     if (!paths.has(path4)) throw new Error(`Required parsed result file missing: ${path4}`);
 }
+async function verifyArchiveChecksum(params, identity, expectedEntryHashes, retainResultArchive = false, validateResponse) {
+  const { openSequentialArchive: openSequentialArchive2 } = await Promise.resolve().then(() => (init_sequential_parsed_document_archive(), sequential_parsed_document_archive_exports));
+  const source = await openSequentialArchive2(params, identity, validateResponse);
+  let entryIndex = 0;
+  try {
+    for await (const entry of source.entries) {
+      const hash = (0, import_crypto3.createHash)("sha256");
+      for await (const part of entry.read()) {
+        params.signal?.throwIfAborted();
+        hash.update(part);
+      }
+      const entryHash = (0, import_crypto3.createHash)("sha256").update(entry.path).update(hash.digest()).digest("hex");
+      if (expectedEntryHashes[entryIndex] !== entryHash)
+        throw new Error(
+          "Parsed snapshot archive entry changed between extraction and checksum verification."
+        );
+      entryIndex += 1;
+    }
+    if (entryIndex !== expectedEntryHashes.length)
+      throw new Error("Parsed snapshot archive entry count changed during checksum verification.");
+    if (retainResultArchive && source.readArchive) {
+      try {
+        await writeStream(params.storage, {
+          documentId: params.documentId,
+          revisionKey: params.revisionKey,
+          path: "result.zip",
+          body: source.readArchive(),
+          contentType: "application/zip",
+          signal: params.signal
+        });
+      } catch {
+      }
+    }
+  } finally {
+    await source.close();
+  }
+}
 async function retainArchive(params, expectedIdentity) {
+  if (params.snapshot) {
+    const progress = await params.storage.readSyncProgress(params);
+    await verifyArchiveChecksum(params, expectedIdentity, progress?.archiveEntryHashes ?? [], true);
+    return;
+  }
   const response = await fetch(params.resultUrl, { signal: params.signal });
   if (!response.ok || !response.body)
     throw new Error(`Optional archive download failed (HTTP ${response.status}).`);
@@ -1570,7 +1669,7 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function createDownloadIdentity(jobId, response) {
-  return (0, import_crypto2.createHash)("sha256").update(
+  return (0, import_crypto3.createHash)("sha256").update(
     JSON.stringify([
       jobId,
       response.headers.get("etag"),
@@ -1579,60 +1678,16 @@ function createDownloadIdentity(jobId, response) {
     ])
   ).digest("hex");
 }
-var import_crypto2, import_zip2, AbortableHttpRangeReader;
+var import_crypto3, import_zip2;
 var init_streamed_parsed_document_sync = __esm({
   "src/storage/streamed-parsed-document-sync.ts"() {
     "use strict";
-    import_crypto2 = require("crypto");
+    import_crypto3 = 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();
-    AbortableHttpRangeReader = class extends import_zip2.HttpRangeReader {
-      constructor(url, options, controller) {
-        super(url, options);
-        this.controller = controller;
-      }
-      controller;
-      createReadable(options) {
-        const reader = super.createReadable(options).getReader();
-        const cancellation = this.controller;
-        return new ReadableStream(
-          {
-            async pull(output) {
-              try {
-                const chunk = await reader.read();
-                if (chunk.done) {
-                  reader.releaseLock();
-                  output.close();
-                } else output.enqueue(chunk.value);
-              } catch (error) {
-                cancellation.abort(error);
-                reader.releaseLock();
-                output.error(error);
-              }
-            },
-            async cancel(reason) {
-              try {
-                await reader.cancel(reason);
-              } finally {
-                reader.releaseLock();
-              }
-            }
-          },
-          { highWaterMark: 0 }
-        );
-      }
-      async readUint8Array(index, length) {
-        try {
-          return await super.readUint8Array(index, length);
-        } catch (error) {
-          this.controller.abort(error);
-          throw error;
-        }
-      }
-    };
   }
 });
 
@@ -2707,6 +2762,12 @@ var Jobs = class extends BaseResource {
     enrichJobResult(jobResult);
     return jobResult;
   }
+  /** Renew unfinished enhancement without creating another ingestion. */
+  async retryEnhancement(jobId) {
+    return this.httpClient.post(
+      this.endpoint(`/jobs/${jobId}/enrichment/retry`)
+    );
+  }
   /**
    * Upload file for a job
    */
@@ -2917,7 +2978,7 @@ var Documents = class extends BaseResource {
 };
 
 // src/knowledge/knowledge.ts
-var import_crypto4 = require("crypto");
+var import_crypto5 = require("crypto");
 init_errors();
 
 // src/storage/asset-storage.ts
@@ -3188,7 +3249,7 @@ init_utils();
 init_streamed_parsed_document_sync();
 
 // src/knowledge/local-store.ts
-var import_crypto3 = require("crypto");
+var import_crypto4 = require("crypto");
 var import_os2 = __toESM(require("os"));
 var import_fs3 = require("fs");
 var import_path3 = __toESM(require("path"));
@@ -3372,7 +3433,7 @@ function isPathInsideDirectory(targetPath, parentDirectory) {
   return relativePath.length === 0 || !relativePath.startsWith("..") && !import_path3.default.isAbsolute(relativePath);
 }
 function createLocalDocumentId(result) {
-  const hash = (0, import_crypto3.createHash)("sha256").update(result.jobId).update("\0").update(result.manifest.sourceFileName).digest("hex").slice(0, 16);
+  const hash = (0, import_crypto4.createHash)("sha256").update(result.jobId).update("\0").update(result.manifest.sourceFileName).digest("hex").slice(0, 16);
   return `local_${hash}`;
 }
 function countChunkTypes(result) {
@@ -3409,6 +3470,21 @@ function isMissingFileError2(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 
+// src/knowledge/serialize-snapshot-publication.ts
+var pendingPublications = /* @__PURE__ */ new WeakMap();
+async function serializeSnapshotPublication(storage, documentId, publish) {
+  const publications = pendingPublications.get(storage) ?? /* @__PURE__ */ new Map();
+  pendingPublications.set(storage, publications);
+  const previous = publications.get(documentId) ?? Promise.resolve();
+  const current = previous.catch(() => void 0).then(publish);
+  publications.set(documentId, current);
+  try {
+    return await current;
+  } finally {
+    if (publications.get(documentId) === current) publications.delete(documentId);
+  }
+}
+
 // src/knowledge/knowledge.ts
 var DEFAULT_READ_LIMIT = 12;
 var MAX_READ_LIMIT = 40;
@@ -3526,11 +3602,37 @@ var Knowledge = class _Knowledge {
     return this.importJobResult(params);
   }
   async syncParsedDocument(params) {
+    const response = await this.performParsedDocumentSync(params);
+    if (response.completed && !response.snapshot) {
+      const storage = this.requireParsedStorageConfig().storage;
+      await serializeSnapshotPublication(storage, response.documentId, async () => {
+        if (params.documentId || params.jobId) {
+          const current = await this.client.documents.listChunks(
+            response.documentId,
+            { page: 1, pageSize: 1 }
+          );
+          if (params.jobId && current.jobId !== params.jobId) return;
+          if (!params.jobId && current.jobResultId !== response.revisionKey) return;
+        }
+        await storage.writeObject({
+          documentId: response.documentId,
+          revisionKey: "current",
+          path: ".knowhere-sdk/current-snapshot.json",
+          body: Buffer.from(
+            JSON.stringify({ snapshotId: response.revisionKey, jobResultId: response.revisionKey })
+          ),
+          contentType: "application/json; charset=utf-8"
+        });
+      });
+    }
+    return response;
+  }
+  async performParsedDocumentSync(params) {
     params.signal?.throwIfAborted();
     const normalized = normalizeDocumentReference(params);
     const parsedStorageConfig = this.requireParsedStorageConfig();
     validateArchiveSyncLimits(parsedStorageConfig.limits);
-    if (normalized.documentId) {
+    if (normalized.documentId && !normalized.jobId) {
       return this.syncRemoteDocumentToParsedStorage({
         documentId: normalized.documentId,
         revisionKey: params.revisionKey,
@@ -3542,6 +3644,25 @@ var Knowledge = class _Knowledge {
     }
     if (normalized.jobId) {
       const job = await this.client.jobs.get(normalized.jobId);
+      if (job.snapshots?.length) {
+        return this.syncJobSnapshot({
+          job,
+          documentId: normalized.documentId ?? job.documentId ?? normalized.localDocumentId ?? normalized.jobId,
+          revisionKey: params.revisionKey,
+          parsedStorageConfig,
+          signal: params.signal,
+          retainResultArchive: params.retainResultArchive
+        });
+      }
+      if (normalized.documentId) {
+        return this.syncRemoteDocumentToParsedStorage({
+          documentId: normalized.documentId,
+          revisionKey: params.revisionKey,
+          parsedStorageConfig,
+          signal: params.signal,
+          retainResultArchive: params.retainResultArchive
+        });
+      }
       if (!job.isDone || !job.resultUrl)
         throw new ValidationError("Completed job result archive is unavailable");
       return syncRemoteResultArchive({
@@ -3573,6 +3694,89 @@ var Knowledge = class _Knowledge {
       commit: synced.commit
     };
   }
+  async syncJobSnapshot(params) {
+    const snapshotId = params.revisionKey ?? params.job.currentSnapshotId;
+    const snapshot = params.job.snapshots?.find(
+      (candidate) => candidate.snapshotId === snapshotId
+    );
+    if (!params.job.isDone || !snapshot)
+      throw new ValidationError("Requested immutable parsed snapshot is unavailable");
+    if (snapshot.jobId !== params.job.jobId || snapshot.documentId !== params.documentId)
+      throw new ValidationError(
+        "Parsed snapshot document or job identity differs from the request"
+      );
+    const response = await syncRemoteResultArchive({
+      documentId: params.documentId,
+      revisionKey: snapshot.snapshotId,
+      jobId: snapshot.jobId,
+      snapshot,
+      resultUrl: snapshot.resultUrl,
+      storage: params.parsedStorageConfig.storage,
+      limits: params.parsedStorageConfig.limits,
+      signal: params.signal,
+      retainResultArchive: params.retainResultArchive
+    });
+    if (response.completed && snapshot.snapshotId === params.job.currentSnapshotId) {
+      await serializeSnapshotPublication(
+        params.parsedStorageConfig.storage,
+        params.documentId,
+        async () => {
+          const current = await this.client.documents.listChunks(
+            params.documentId,
+            { page: 1, pageSize: 1 }
+          );
+          if (current.jobResultId !== snapshot.jobResultId) return;
+          const pointer = Buffer.from(
+            JSON.stringify({
+              snapshotId: snapshot.snapshotId,
+              jobResultId: snapshot.jobResultId
+            })
+          );
+          if (snapshot.stage === "final") {
+            await params.parsedStorageConfig.storage.writeObject({
+              documentId: params.documentId,
+              revisionKey: "current",
+              path: ".knowhere-sdk/final-snapshot.json",
+              body: pointer,
+              contentType: "application/json; charset=utf-8"
+            });
+          }
+          await params.parsedStorageConfig.storage.writeObject({
+            documentId: params.documentId,
+            revisionKey: "current",
+            path: ".knowhere-sdk/current-snapshot.json",
+            body: pointer,
+            contentType: "application/json; charset=utf-8"
+          });
+        }
+      );
+    }
+    return response;
+  }
+  async resolveStoredSnapshotKey(documentId) {
+    const object = await this.parsedStorageConfig?.storage.readObject({
+      documentId,
+      revisionKey: "current",
+      path: ".knowhere-sdk/current-snapshot.json"
+    });
+    if (!object) return void 0;
+    const payload = JSON.parse(Buffer.from(object.body).toString("utf8"));
+    if (typeof payload !== "object" || payload === null || !("snapshotId" in payload))
+      throw new ValidationError("Invalid current parsed snapshot pointer");
+    if (typeof payload.snapshotId !== "string")
+      throw new ValidationError("Invalid current parsed snapshot identity");
+    const finalObject = await this.parsedStorageConfig?.storage.readObject({
+      documentId,
+      revisionKey: "current",
+      path: ".knowhere-sdk/final-snapshot.json"
+    });
+    if (finalObject && "jobResultId" in payload) {
+      const finalPayload = JSON.parse(Buffer.from(finalObject.body).toString("utf8"));
+      if (typeof finalPayload === "object" && finalPayload !== null && "snapshotId" in finalPayload && typeof finalPayload.snapshotId === "string" && "jobResultId" in finalPayload && finalPayload.jobResultId === payload.jobResultId)
+        return finalPayload.snapshotId;
+    }
+    return payload.snapshotId;
+  }
   async syncParseResultToConfiguredStorage(result) {
     const parsedStorageConfig = this.parsedStorageConfig;
     if (!parsedStorageConfig) {
@@ -3808,7 +4012,7 @@ var Knowledge = class _Knowledge {
     throw new Error(`Local Knowhere document not found: ${normalized.localDocumentId}`);
   }
   async readRemoteDocumentChunks(documentId, params) {
-    const explicitRevisionKey = params.revisionKey ?? params.jobId;
+    const explicitRevisionKey = params.revisionKey ?? params.jobId ?? await this.resolveStoredSnapshotKey(documentId);
     if (explicitRevisionKey) {
       const stored2 = await this.tryReadChunksFromParsedStorage({
         documentId,
@@ -3818,6 +4022,8 @@ var Knowledge = class _Knowledge {
       if (stored2) {
         return stored2;
       }
+      if (params.revisionKey && await this.resolveStoredSnapshotKey(documentId))
+        throw new ValidationError("Requested parsed snapshot is not committed locally");
     }
     if (hasScanReadFilters(params)) {
       return this.scanRemoteDocumentChunks(documentId, params);
@@ -3830,6 +4036,8 @@ var Knowledge = class _Knowledge {
       includeAssetUrls: true
     });
     const revisionKey = getRemoteRevisionKey(remotePage);
+    if (params.revisionKey && params.revisionKey !== revisionKey)
+      throw new ValidationError("Requested parsed snapshot revision is not committed locally");
     const stored = await this.tryReadChunksFromParsedStorage({
       documentId,
       revisionKey,
@@ -3854,7 +4062,7 @@ var Knowledge = class _Knowledge {
     };
   }
   async scanRemoteDocumentChunks(documentId, params) {
-    const explicitRevisionKey = params.revisionKey ?? params.jobId;
+    const explicitRevisionKey = params.revisionKey ?? params.jobId ?? await this.resolveStoredSnapshotKey(documentId);
     if (explicitRevisionKey) {
       const stored2 = await this.tryReadChunksFromParsedStorage({
         documentId,
@@ -3864,6 +4072,8 @@ var Knowledge = class _Knowledge {
       if (stored2) {
         return stored2;
       }
+      if (params.revisionKey && await this.resolveStoredSnapshotKey(documentId))
+        throw new ValidationError("Requested parsed snapshot is not committed locally");
     }
     const limit = clampLimit(params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT);
     const limits = getParsedStorageLimits(this.parsedStorageConfig?.limits);
@@ -3874,6 +4084,8 @@ var Knowledge = class _Knowledge {
       includeAssetUrls: true
     });
     const revisionKey = getRemoteRevisionKey(firstPage);
+    if (params.revisionKey && params.revisionKey !== revisionKey)
+      throw new ValidationError("Requested parsed snapshot revision is not committed locally");
     const stored = await this.tryReadChunksFromParsedStorage({
       documentId,
       revisionKey,
@@ -3916,7 +4128,7 @@ var Knowledge = class _Knowledge {
     };
   }
   async grepRemoteDocumentChunks(documentId, params) {
-    const explicitRevisionKey = params.revisionKey ?? params.jobId;
+    const explicitRevisionKey = params.revisionKey ?? params.jobId ?? await this.resolveStoredSnapshotKey(documentId);
     if (explicitRevisionKey && !params.continuationCursor) {
       const stored2 = await this.tryGrepChunksFromParsedStorage({
         documentId,
@@ -3926,6 +4138,8 @@ var Knowledge = class _Knowledge {
       if (stored2) {
         return stored2;
       }
+      if (params.revisionKey && await this.resolveStoredSnapshotKey(documentId))
+        throw new ValidationError("Requested parsed snapshot is not committed locally");
     }
     const maxResults = clampLimit(params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
     const contextChars = params.contextChars ?? DEFAULT_CONTEXT_CHARS;
@@ -3940,6 +4154,8 @@ var Knowledge = class _Knowledge {
       includeAssetUrls: true
     });
     const revisionKey = getRemoteRevisionKey(firstPage);
+    if (params.revisionKey && params.revisionKey !== revisionKey)
+      throw new ValidationError("Requested parsed snapshot revision is not committed locally");
     const stored = startPage === 1 ? await this.tryGrepChunksFromParsedStorage({
       documentId,
       revisionKey,
@@ -4025,11 +4241,14 @@ var Knowledge = class _Knowledge {
     }
   }
   async getRemoteDocumentOutline(documentId, revisionKeyOverride) {
-    if (revisionKeyOverride) {
-      const stored2 = await this.tryReadOutlineFromParsedStorage(documentId, revisionKeyOverride);
+    const storedRevisionKey = revisionKeyOverride ?? await this.resolveStoredSnapshotKey(documentId);
+    if (storedRevisionKey) {
+      const stored2 = await this.tryReadOutlineFromParsedStorage(documentId, storedRevisionKey);
       if (stored2) {
         return stored2;
       }
+      if (revisionKeyOverride && await this.resolveStoredSnapshotKey(documentId))
+        throw new ValidationError("Requested parsed snapshot is not committed locally");
     }
     const limits = getParsedStorageLimits(this.parsedStorageConfig?.limits);
     const firstPage = await this.client.documents.listChunks(documentId, {
@@ -4038,6 +4257,8 @@ var Knowledge = class _Knowledge {
       includeAssetUrls: true
     });
     const revisionKey = getRemoteRevisionKey(firstPage);
+    if (revisionKeyOverride && revisionKeyOverride !== revisionKey)
+      throw new ValidationError("Requested parsed snapshot revision is not committed locally");
     const stored = await this.tryReadOutlineFromParsedStorage(documentId, revisionKey);
     if (stored) {
       return stored;
@@ -4246,11 +4467,7 @@ var Knowledge = class _Knowledge {
     const scheduler = parsedStorageConfig.scheduler ?? defaultParsedStorageScheduler;
     const task = async () => {
       try {
-        await this.syncRemoteDocumentToParsedStorage({
-          documentId,
-          revisionKey,
-          parsedStorageConfig
-        });
+        await this.syncParsedDocument({ documentId, revisionKey });
       } catch (error) {
         const previous = await parsedStorageConfig.storage.readSyncProgress({
           documentId,
@@ -4276,14 +4493,25 @@ var Knowledge = class _Knowledge {
       includeAssetUrls: true
     });
     const revisionKey = params.revisionKey ?? getRemoteRevisionKey(firstPage);
-    if (params.revisionKey && getRemoteRevisionKey(firstPage) !== params.revisionKey) {
-      throw new ValidationError("Published document revision changed before parsed snapshot sync");
-    }
     if (firstPage.jobId) {
       const job = await this.client.jobs.get(firstPage.jobId).catch((error) => {
         if (error instanceof NotFoundError) return null;
         throw error;
       });
+      if (job?.snapshots?.length) {
+        const snapshot = job.snapshots.find(
+          (candidate) => candidate.snapshotId === (params.revisionKey ?? job.currentSnapshotId)
+        );
+        if (snapshot && snapshot.jobResultId !== getRemoteRevisionKey(firstPage))
+          throw new ValidationError(
+            "Parsed snapshot upstream revision differs from the published document"
+          );
+        return this.syncJobSnapshot({ ...params, job });
+      }
+      if (params.revisionKey && getRemoteRevisionKey(firstPage) !== params.revisionKey)
+        throw new ValidationError(
+          "Published document revision changed before parsed snapshot sync"
+        );
       if (job?.isDone && job.resultUrl) {
         if (job.documentId && job.documentId !== params.documentId)
           throw new ValidationError("Parsed job document identity differs from requested document");
@@ -4492,7 +4720,7 @@ function createLocalDocumentIdForRemote(documentId) {
   if (SAFE_LOCAL_DOCUMENT_ID_PATTERN.test(documentId) && !documentId.includes("..") && !documentId.includes("/") && !documentId.includes("\\")) {
     return documentId;
   }
-  const hash = (0, import_crypto4.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
+  const hash = (0, import_crypto5.createHash)("sha256").update(documentId).digest("hex").slice(0, 16);
   return `remote_${hash}`;
 }
 var defaultParsedStorageScheduler = {
@@ -5450,7 +5678,7 @@ var Knowhere = class {
 };
 
 // src/storage/disk-parsed-document-storage.ts
-var import_crypto5 = require("crypto");
+var import_crypto6 = require("crypto");
 var import_fs4 = require("fs");
 var import_path5 = __toESM(require("path"));
 var syncProgressPath = ".knowhere-sdk/sync-progress.json";
@@ -5583,7 +5811,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_crypto5.createHash)("sha256").update(normalized).digest("hex").slice(0, 24);
+  return (0, import_crypto6.createHash)("sha256").update(normalized).digest("hex").slice(0, 24);
 }
 function normalizeRelativeStoragePath(value) {
   const normalized = value.replaceAll("\\", "/").replace(/^\.\/+/, "");