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

package/dist/{chunk-DIONXJWK.mjs → chunk-OCR7IDYL.mjs}

@@ -175,9 +175,7 @@ var 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."
-    );
+    super("Parsed result ZIP temporary storage is unavailable.");
     this.name = "ParsedDocumentArchiveError";
     this.cause = cause;
   }
@@ -770,17 +768,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") ?? ""
@@ -847,10 +843,7 @@ function isPositiveInteger(value) {
 }
 
 // src/storage/streamed-parsed-document-sync.ts
-import {
-  HttpRangeReader,
-  ZipReader
-} from "@zip.js/zip.js";
+import { HttpRangeReader, ZipReader } from "@zip.js/zip.js";
 async function syncRemoteResultArchive(params) {
   params.signal?.throwIfAborted();
   validateArchiveSyncLimits(params.limits);
@@ -861,14 +854,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;
@@ -895,6 +884,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,
@@ -933,10 +924,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();
@@ -954,7 +973,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();
@@ -968,9 +992,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,
@@ -989,6 +1020,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,
@@ -1009,6 +1042,7 @@ async function syncRemoteResultArchive(params) {
       documentId: params.documentId,
       revisionKey: params.revisionKey,
       completed: true,
+      snapshot: params.snapshot,
       commit
     };
   } catch (error) {
@@ -1024,6 +1058,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),
@@ -1113,6 +1149,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",
@@ -1121,50 +1159,6 @@ async function persistArchiveCacheBypass(params, previous) {
   await params.storage.writeSyncProgress(progress, { signal: params.signal });
   return progress;
 }
-var AbortableHttpRangeReader = class extends 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;
-    }
-  }
-};
 async function openArchiveTransport(params, previous, prepared) {
   const resultUrl = prepared?.resultUrl ?? params.resultUrl;
   const archiveCacheBypassed = prepared?.archiveCacheBypassed ?? previous?.archiveCacheBypassed;
@@ -1181,7 +1175,7 @@ async function openArchiveTransport(params, previous, prepared) {
   const supportsRange = probe.status === 206 && probe.headers.has("content-range");
   await probe.body?.cancel();
   if (!supportsRange) {
-    const { openSequentialArchive } = await import("./sequential-parsed-document-archive-W7HPYIKA.mjs");
+    const { openSequentialArchive } = await import("./sequential-parsed-document-archive-AIRFKO52.mjs");
     const source = await openSequentialArchive(
       { ...params, resultUrl },
       identity,
@@ -1189,43 +1183,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 ZipReader(new AbortableHttpRangeReader(resultUrl, options, rangeController), {
+  const reader = new ZipReader(new HttpRangeReader(resultUrl, options), {
     useWebWorkers: false,
     checkCrc32: true
   });
@@ -1241,11 +1224,17 @@ async function openArchiveTransport(params, previous, prepared) {
       )
     ).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) {
@@ -1254,7 +1243,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()
@@ -1267,7 +1256,6 @@ async function openArchiveTransport(params, previous, prepared) {
       }
     };
   } catch (error) {
-    rangeController.abort(error);
     await reader.close();
     throw error;
   }
@@ -1279,16 +1267,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);
@@ -1325,6 +1307,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 : isRecord(payload) ? payload.chunks : void 0;
   if (!Array.isArray(chunks)) throw new Error("Invalid parsed result chunks.json.");
   if (isRecord(manifest.files)) {
@@ -1349,7 +1334,49 @@ async function validateRequiredObjects(params, paths) {
   for (const path of required)
     if (!paths.has(path)) throw new Error(`Required parsed result file missing: ${path}`);
 }
+async function verifyArchiveChecksum(params, identity, expectedEntryHashes, retainResultArchive = false, validateResponse) {
+  const { openSequentialArchive } = await import("./sequential-parsed-document-archive-AIRFKO52.mjs");
+  const source = await openSequentialArchive(params, identity, validateResponse);
+  let entryIndex = 0;
+  try {
+    for await (const entry of source.entries) {
+      const hash = createHash2("sha256");
+      for await (const part of entry.read()) {
+        params.signal?.throwIfAborted();
+        hash.update(part);
+      }
+      const entryHash = createHash2("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}).`);

package/dist/index.d.mts

@@ -74,6 +74,9 @@ interface JobError {
  * Job status response with full details
  */
 interface JobResult {
+    enhancement?: JobEnhancement;
+    snapshots?: readonly JobSnapshot[];
+    currentSnapshotId?: string;
     /** Unique job identifier */
     jobId: string;
     /** Current job status */
@@ -117,6 +120,28 @@ interface JobResult {
     /** Whether the job failed */
     readonly isFailed: boolean;
 }
+/** Background work does not change an already completed ingestion job. */
+interface JobEnhancement {
+    readonly status: 'pending' | 'running' | 'complete' | 'failed';
+    readonly canRetry: boolean;
+    readonly attempt: number;
+    readonly error?: string | null;
+}
+/** Immutable archive generation; signed URL capabilities may be refreshed. */
+interface JobSnapshot {
+    readonly snapshotId: string;
+    readonly stage: 'baseline' | 'final';
+    readonly jobId: string;
+    readonly jobResultId: string;
+    readonly documentId: string;
+    readonly checksum: string;
+    readonly resultUrl: string;
+    readonly resultUrlExpiresAt: Date;
+}
+interface JobEnhancementRetryResult {
+    readonly jobId: string;
+    readonly enhancement: JobEnhancement;
+}
 
 /**
  * Statistics about the parsed document
@@ -455,6 +480,10 @@ interface ParsedDocumentWriteObjectResult extends ParsedDocumentObjectParams {
 }
 type ParsedDocumentCommitSource = 'resultZip' | 'remoteReconstruction';
 interface ParsedDocumentCommit {
+    readonly snapshotId?: string;
+    readonly jobResultId?: string;
+    readonly checksum?: string;
+    readonly stage?: 'baseline' | 'final';
     readonly version: 1;
     readonly documentId: string;
     readonly revisionKey: string;
@@ -464,6 +493,8 @@ interface ParsedDocumentCommit {
 interface ParsedDocumentSyncProgress {
     readonly documentId: string;
     readonly revisionKey: string;
+    readonly snapshotChecksum?: string;
+    readonly upstreamJobResultId?: string;
     readonly nextChunkPage?: number;
     readonly pinnedRevisionKey?: string;
     readonly archiveIdentity?: string;
@@ -830,6 +861,8 @@ declare class Jobs extends BaseResource {
      * Get job status
      */
     get(jobId: string): Promise<JobResult>;
+    /** Renew unfinished enhancement without creating another ingestion. */
+    retryEnhancement(jobId: string): Promise<JobEnhancementRetryResult>;
     /**
      * Upload file for a job
      */
@@ -924,6 +957,10 @@ interface RetrievalSource {
     sourceFileName?: string | null;
     /** Human-readable section path */
     sectionPath?: string | null;
+    /** Physical source pages, stable across progressive parsing snapshots. */
+    pageNums?: number[];
+    /** Original ingestion revision, shared by its baseline and final snapshots. */
+    jobResultId?: string | null;
 }
 /**
  * One composed evidence part. Tables stay in text as HTML; images are inline bytes.
@@ -981,6 +1018,10 @@ interface RetrievalReferencedChunk {
     filePath?: string | null;
     /** Published job identifier for the referenced chunk */
     jobId?: string | null;
+    /** Original ingestion revision, shared by its baseline and final snapshots. */
+    jobResultId?: string | null;
+    /** All physical source pages supporting this evidence. */
+    pageNums?: number[];
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string | null;
     /** Chunk metadata returned by the API */
@@ -1332,7 +1373,7 @@ interface KnowledgeDocumentReference {
     documentId?: string;
     /** Server parse job identifier whose completed result should be cached before reading. */
     jobId?: string;
-    /** Current parsed revision key when the caller already has it. */
+    /** Opaque snapshot ID for progressive archives; upstream Job Result ID for legacy results. */
     revisionKey?: string;
 }
 type KnowledgeParsedStorageOptions = ParsedDocumentStorageConfig;
@@ -1344,6 +1385,8 @@ interface KnowledgeSyncParsedDocumentParams extends KnowledgeDocumentReference {
     readonly cacheResultArchive?: boolean;
 }
 interface KnowledgeSyncParsedDocumentResponse {
+    /** Selected immutable descriptor; reuse revisionKey for each segmented continuation. */
+    readonly snapshot?: JobSnapshot;
     documentId: string;
     revisionKey: string;
     completed: boolean;
@@ -1491,6 +1534,9 @@ declare class Knowledge {
     /** @deprecated Use importJobResult for local cache imports or loadJobResult for server-safe loads. */
     cacheJobResult(params: KnowledgeCacheJobResultParams): Promise<LocalKnowledgeParseResponse>;
     syncParsedDocument(params: KnowledgeSyncParsedDocumentParams): Promise<KnowledgeSyncParsedDocumentResponse>;
+    private performParsedDocumentSync;
+    private syncJobSnapshot;
+    private resolveStoredSnapshotKey;
     private syncParseResultToConfiguredStorage;
     private parseWithoutClientStorageAdapter;
     cacheDocument(params: KnowledgeCacheDocumentParams): Promise<LocalKnowledgeParseResponse>;
@@ -1794,7 +1840,7 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-/** The sequential ZIP fallback could not access its SDK-owned temporary storage. */
+/** Sequential ZIP extraction or snapshot verification could not access temporary storage. */
 declare class ParsedDocumentArchiveError extends KnowhereError {
     readonly code: "ARCHIVE_SPOOL_FAILED";
     readonly cause: unknown;

package/dist/index.d.ts

@@ -74,6 +74,9 @@ interface JobError {
  * Job status response with full details
  */
 interface JobResult {
+    enhancement?: JobEnhancement;
+    snapshots?: readonly JobSnapshot[];
+    currentSnapshotId?: string;
     /** Unique job identifier */
     jobId: string;
     /** Current job status */
@@ -117,6 +120,28 @@ interface JobResult {
     /** Whether the job failed */
     readonly isFailed: boolean;
 }
+/** Background work does not change an already completed ingestion job. */
+interface JobEnhancement {
+    readonly status: 'pending' | 'running' | 'complete' | 'failed';
+    readonly canRetry: boolean;
+    readonly attempt: number;
+    readonly error?: string | null;
+}
+/** Immutable archive generation; signed URL capabilities may be refreshed. */
+interface JobSnapshot {
+    readonly snapshotId: string;
+    readonly stage: 'baseline' | 'final';
+    readonly jobId: string;
+    readonly jobResultId: string;
+    readonly documentId: string;
+    readonly checksum: string;
+    readonly resultUrl: string;
+    readonly resultUrlExpiresAt: Date;
+}
+interface JobEnhancementRetryResult {
+    readonly jobId: string;
+    readonly enhancement: JobEnhancement;
+}
 
 /**
  * Statistics about the parsed document
@@ -455,6 +480,10 @@ interface ParsedDocumentWriteObjectResult extends ParsedDocumentObjectParams {
 }
 type ParsedDocumentCommitSource = 'resultZip' | 'remoteReconstruction';
 interface ParsedDocumentCommit {
+    readonly snapshotId?: string;
+    readonly jobResultId?: string;
+    readonly checksum?: string;
+    readonly stage?: 'baseline' | 'final';
     readonly version: 1;
     readonly documentId: string;
     readonly revisionKey: string;
@@ -464,6 +493,8 @@ interface ParsedDocumentCommit {
 interface ParsedDocumentSyncProgress {
     readonly documentId: string;
     readonly revisionKey: string;
+    readonly snapshotChecksum?: string;
+    readonly upstreamJobResultId?: string;
     readonly nextChunkPage?: number;
     readonly pinnedRevisionKey?: string;
     readonly archiveIdentity?: string;
@@ -830,6 +861,8 @@ declare class Jobs extends BaseResource {
      * Get job status
      */
     get(jobId: string): Promise<JobResult>;
+    /** Renew unfinished enhancement without creating another ingestion. */
+    retryEnhancement(jobId: string): Promise<JobEnhancementRetryResult>;
     /**
      * Upload file for a job
      */
@@ -924,6 +957,10 @@ interface RetrievalSource {
     sourceFileName?: string | null;
     /** Human-readable section path */
     sectionPath?: string | null;
+    /** Physical source pages, stable across progressive parsing snapshots. */
+    pageNums?: number[];
+    /** Original ingestion revision, shared by its baseline and final snapshots. */
+    jobResultId?: string | null;
 }
 /**
  * One composed evidence part. Tables stay in text as HTML; images are inline bytes.
@@ -981,6 +1018,10 @@ interface RetrievalReferencedChunk {
     filePath?: string | null;
     /** Published job identifier for the referenced chunk */
     jobId?: string | null;
+    /** Original ingestion revision, shared by its baseline and final snapshots. */
+    jobResultId?: string | null;
+    /** All physical source pages supporting this evidence. */
+    pageNums?: number[];
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string | null;
     /** Chunk metadata returned by the API */
@@ -1332,7 +1373,7 @@ interface KnowledgeDocumentReference {
     documentId?: string;
     /** Server parse job identifier whose completed result should be cached before reading. */
     jobId?: string;
-    /** Current parsed revision key when the caller already has it. */
+    /** Opaque snapshot ID for progressive archives; upstream Job Result ID for legacy results. */
     revisionKey?: string;
 }
 type KnowledgeParsedStorageOptions = ParsedDocumentStorageConfig;
@@ -1344,6 +1385,8 @@ interface KnowledgeSyncParsedDocumentParams extends KnowledgeDocumentReference {
     readonly cacheResultArchive?: boolean;
 }
 interface KnowledgeSyncParsedDocumentResponse {
+    /** Selected immutable descriptor; reuse revisionKey for each segmented continuation. */
+    readonly snapshot?: JobSnapshot;
     documentId: string;
     revisionKey: string;
     completed: boolean;
@@ -1491,6 +1534,9 @@ declare class Knowledge {
     /** @deprecated Use importJobResult for local cache imports or loadJobResult for server-safe loads. */
     cacheJobResult(params: KnowledgeCacheJobResultParams): Promise<LocalKnowledgeParseResponse>;
     syncParsedDocument(params: KnowledgeSyncParsedDocumentParams): Promise<KnowledgeSyncParsedDocumentResponse>;
+    private performParsedDocumentSync;
+    private syncJobSnapshot;
+    private resolveStoredSnapshotKey;
     private syncParseResultToConfiguredStorage;
     private parseWithoutClientStorageAdapter;
     cacheDocument(params: KnowledgeCacheDocumentParams): Promise<LocalKnowledgeParseResponse>;
@@ -1794,7 +1840,7 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-/** The sequential ZIP fallback could not access its SDK-owned temporary storage. */
+/** Sequential ZIP extraction or snapshot verification could not access temporary storage. */
 declare class ParsedDocumentArchiveError extends KnowhereError {
     readonly code: "ARCHIVE_SPOOL_FAILED";
     readonly cause: unknown;