@giveitsmaller/sdk 0.4.0 → 0.6.0

package/dist/client.js

@@ -1,7 +1,7 @@
-import { readFileSync, statSync } from 'node:fs';
+import { open, stat } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
-import { GislAbortError, GislApiError, GislAuthError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislTierRestrictedError, GislTimeoutError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
+import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, UploadSizeExceedsTierResponseFromJSON, UploadDurationExceedsTierResponseFromJSON, UploadConstraintsAppliedProcessingClassPreAssignmentEnum, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
+import { GislAbortError, GislApiError, GislAuthError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
 import { parseSseStream } from './sse.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 // SDK-internal aliases derived from the contract-pinned UploadThresholds enums
@@ -11,7 +11,7 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 // release that regenerates the corresponding *Enum, plus updating the literal
 // in the matching `_AssertTrue<>` line.
 const SINGLE_SHOT_MAX_BYTES = UploadThresholdsSingleShotMaxBytesEnum.NUMBER_10000000;
-const MULTIPART_CHUNK_SIZE = UploadThresholdsMultipartChunkSizeEnum.NUMBER_5242880;
+const MULTIPART_CHUNK_SIZE = UploadThresholdsMultipartChunkSizeEnum.NUMBER_16777216;
 export const MULTIPART_CONCURRENCY_DEFAULT = UploadThresholdsMultipartConcurrencyDefaultEnum.NUMBER_4;
 const DEFAULT_MULTIPART_MAX_ATTEMPTS = 3;
 const DEFAULT_MULTIPART_RETRY_BASE_MS = 500;
@@ -23,6 +23,33 @@ const DEFAULT_MULTIPART_RETRY_BASE_MS = 500;
 // TODO(58nBQLWQ): replace with UploadThresholdsMultipartFirstChunkSizeEnum
 // once contracts ticket promotes this to a typed const (v2.3.1 follow-up).
 export const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE = 8 * 1024 * 1024; // 8 MB
+// The ~2 GB wall on a single Node file read is NOT a Buffer-size limit
+// (modern 64-bit `buffer.constants.MAX_LENGTH` is ~8 PiB). It is libuv's
+// hard-coded INT32_MAX (2 147 483 647) ceiling on one `uv_fs_read` — some
+// platforms reject I/O larger than INT32_MAX bytes per call, so libuv caps
+// every read at it (github.com/nodejs/node/issues/55864). The streaming
+// upload path never approaches this (server chunk size is bounded to
+// <=100 MiB and the first chunk is fixed 8 MiB), but `fileByteSource`
+// asserts it per read so any future caller that requests an oversized range
+// fails loudly here instead of getting a silently short read from libuv.
+const LIBUV_MAX_SINGLE_READ_BYTES = 0x7fffffff; // INT32_MAX
+// S3 hard limit: a multipart upload may have at most 10 000 parts. The
+// server computes the part plan and returns `total_parts`; the SDK trusts
+// that value (Model A) but guards the ceiling so an out-of-contract server
+// response or a chunk-size regression surfaces as a typed error rather than
+// a doomed run of presigned PUTs ending in a rejected /multipart/complete.
+const S3_MAX_MULTIPART_PARTS = 10_000;
+// Contract bound on `MultipartInitiateResponse.recommended_chunk_size`
+// (compression_contracts/openapi api.yaml — `maximum: 104857600`). The
+// minimum is `multipart_chunk_size` (== MULTIPART_CHUNK_SIZE, drift-guarded
+// above). The generated TS `FromJSON` does NO runtime validation (unlike the
+// strict PHP generated model, which rejects out-of-range values at
+// deserialize), so the TS SDK must enforce this range itself — otherwise a
+// malformed/hostile server `recommended_chunk_size` would pass the
+// part-count guard and drive `fileByteSource` into an unbounded
+// `Buffer.allocUnsafe(length)` (the exact memory-blowup class this SDK
+// exists to prevent). codex review (high).
+const RECOMMENDED_CHUNK_SIZE_MAX_BYTES = 104_857_600; // 100 MiB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
 // Statuses that waitForWorkflow() returns immediately on. Per ticket I24,
@@ -176,6 +203,69 @@ function bindAbortSignal(external, internal, onExternalAbort) {
     external.addEventListener('abort', onAbort, { once: true });
     return () => external.removeEventListener('abort', onAbort);
 }
+// Blob/File input is already lazy: `Blob.slice()` is a zero-copy view and a
+// `File` from a browser picker is disk-backed, so this branch never buffered
+// the whole file. Left structurally identical to the pre-streaming-rewrite
+// behaviour.
+function blobByteSource(blob) {
+    return {
+        size: blob.size,
+        // Pass `blob.type` as the 3rd arg: `Blob.slice()` defaults the slice's
+        // content-type to '' otherwise, which would strip the MIME type off the
+        // single-shot FormData part (the pre-streaming code appended the original
+        // typed Blob directly). Parity fixtures pin this content-type.
+        slice: (start, end) => Promise.resolve(blob.slice(start, end, blob.type)),
+    };
+}
+// File-path input. The pre-rewrite code did `readFileSync(path)` →
+// `new Blob([whole file])`, which (a) OOMs on multi-GB files and (b) cannot
+// even be attempted above ~2 GB because a single libuv `uv_fs_read` is capped
+// at INT32_MAX (see LIBUV_MAX_SINGLE_READ_BYTES). This source instead does a
+// positioned (POSIX pread-semantics) read of ONLY the requested range, with a
+// fresh fd per call so concurrent multipart workers never share a FileHandle
+// (overlapping reads on one handle are unsafe per the Node fs contract) and
+// the fd is always closed in `finally`.
+//
+// Divergence from the old Blob-from-readFileSync behaviour (deliberate, in
+// scope only for streaming): the old path snapshotted the whole file at t0,
+// so every part was point-in-time consistent. Streaming reads each part at
+// the time it is uploaded, so a file truncated/rewritten mid-upload now
+// yields parts from different instants. Truncation is caught by the
+// short-read guard below; full point-in-time snapshotting would require
+// resumable/staged upload and is out of scope (SDK-3, Wb6ebOMM).
+function fileByteSource(path, size) {
+    return {
+        size,
+        async slice(start, end) {
+            const length = end - start;
+            if (length <= 0)
+                return new Blob([]);
+            // Per-read tripwire for the libuv INT32_MAX ceiling. Unreachable on the
+            // normal path (chunk size <=100 MiB) — exists so a future oversized
+            // caller fails here loudly instead of getting a silent short read.
+            if (length > LIBUV_MAX_SINGLE_READ_BYTES) {
+                throw new GislError(`Refusing to read ${length} bytes in one operation: exceeds the ` +
+                    `libuv single-read ceiling (${LIBUV_MAX_SINGLE_READ_BYTES}). ` +
+                    'Reads must be chunked below INT32_MAX.');
+            }
+            const handle = await open(path, 'r');
+            try {
+                const buffer = Buffer.allocUnsafe(length);
+                const { bytesRead } = await handle.read(buffer, 0, length, start);
+                if (bytesRead !== length) {
+                    // Short read = the file shrank/was truncated under us. Mirrors the
+                    // PHP SDK's readChunk short-read guard (GislClient.php readChunk).
+                    throw new GislError(`Short read on ${path}: expected ${length} bytes at offset ` +
+                        `${start}, got ${bytesRead}. File changed during upload.`);
+                }
+                return new Blob([buffer]);
+            }
+            finally {
+                await handle.close();
+            }
+        },
+    };
+}
 export class GislClient {
     baseUrl;
     headers;
@@ -373,6 +463,63 @@ export class GislClient {
             if (status === 422 && errorType === 'workflow_expired') {
                 tryThrowStructured(WorkflowExpiredResponseFromJSON, GislWorkflowExpiredError, (p) => isValidDate(p.expiredAt));
             }
+            // Upload cap errors. `GislUploadCapExceededError` takes an extra `kind`
+            // arg so it cannot use `tryThrowStructured` (whose ErrorClass signature
+            // is fixed) — this local helper applies the SAME defense-in-depth
+            // discipline: construct via FromJSON, validate required typed fields,
+            // fall through to the generic `GislApiError` on any malformed envelope.
+            const tryThrowCap = (construct, kind, validate) => {
+                let payload;
+                try {
+                    payload = construct(json);
+                }
+                catch {
+                    return undefined;
+                }
+                if (!validate(payload)) {
+                    return undefined;
+                }
+                throw new GislUploadCapExceededError(status, errorMessage, kind, payload, path, i18n);
+            };
+            if (status === 422 && errorType === 'upload_size_exceeds_tier') {
+                tryThrowCap(UploadSizeExceedsTierResponseFromJSON, 'size_tier', (p) => isInEnum(p.currentTier, UserTier) &&
+                    typeof p.maxSizeBytes === 'number');
+            }
+            if (status === 422 && errorType === 'upload_duration_exceeds_tier') {
+                tryThrowCap(UploadDurationExceedsTierResponseFromJSON, 'duration_tier', (p) => isInEnum(p.currentTier, UserTier) &&
+                    typeof p.maxDurationSeconds === 'number');
+            }
+            // 413 = the absolute across-tier cap. The contract models 413 as a
+            // plain `ErrorEnvelope` (no `error_type` discriminator, no typed
+            // payload — api.yaml), so dispatch purely on status with no FromJSON
+            // and an undefined payload (the `absolute_413` kind tells the caller
+            // there is intentionally no structured envelope to read).
+            if (status === 413) {
+                throw new GislUploadCapExceededError(status, errorMessage, 'absolute_413', undefined, path, i18n);
+            }
+            // SDK-3 (Wb6ebOMM) resume-support endpoint error codes. API-2 / PR
+            // #283 specced these as plain `ErrorEnvelope` envelopes with the
+            // discriminating string on `error_type`. No typed payload to build —
+            // dispatch on the (status, error_type) tuple. The HxUmVr3Y contract
+            // regen will produce typed responses for these; today the 3 typed
+            // subclasses carry only the localisation triple + raw envelope.
+            if (status === 404 && errorType === 'MULTIPART_SESSION_NOT_FOUND') {
+                throw new GislMultipartSessionNotFoundError(status, errorMessage, path, i18n);
+            }
+            if (status === 403 && errorType === 'MULTIPART_SESSION_OWNERSHIP') {
+                throw new GislMultipartSessionOwnershipError(status, errorMessage, path, i18n);
+            }
+            if (status === 403 && errorType === 'MULTIPART_SESSION_AUTH_REQUIRED') {
+                throw new GislMultipartSessionAuthRequiredError(status, errorMessage, path, i18n);
+            }
+            // 422 `FILE_TOO_LARGE_FOR_MULTIPART` — pre-S3 capacity reject on the
+            // resume-support presign endpoint (more parts than the manifest can
+            // ever accept). No typed payload today (the contract carries no
+            // structured response for this code); `cap_v2_multipart` discriminant
+            // is documented on `GislUploadCapKind`.
+            if (status === 422 && errorType === 'FILE_TOO_LARGE_FOR_MULTIPART') {
+                throw new GislUploadCapExceededError(status, errorMessage, 'cap_v2_multipart', undefined, path, i18n);
+            }
             throw new GislApiError(status, errorMessage, path, json.details, { ...i18n, payload: json });
         }
         const data = json.data ?? json;
@@ -395,34 +542,55 @@ export class GislClient {
      * @param options  Upload options including progress callback.
      */
     async uploadFile(file, options) {
-        // Pre-abort check: bail before statSync/readFileSync buffers the whole
-        // file into memory when the caller has already cancelled.
+        // Pre-abort check: bail before touching the filesystem when the caller
+        // has already cancelled.
         if (options?.signal?.aborted) {
             throw new GislAbortError('Upload aborted before start');
         }
-        let blob;
+        let source;
         let fileName;
-        let fileSize;
         if (typeof file === 'string') {
-            const stat = statSync(file);
-            fileSize = stat.size;
+            // `stat` for the size only — the bytes are NEVER read up front. The old
+            // path did `readFileSync(file)` which OOMs on multi-GB files and is
+            // impossible above the libuv INT32_MAX single-read ceiling regardless
+            // of available memory (see fileByteSource / LIBUV_MAX_SINGLE_READ_BYTES).
+            const stats = await stat(file);
             fileName = basename(file);
-            const content = readFileSync(file);
-            blob = new Blob([content]);
+            source = fileByteSource(file, stats.size);
         }
         else {
-            blob = file;
             fileName = file.name ?? 'upload';
-            fileSize = file.size;
+            source = blobByteSource(file);
         }
-        if (fileSize > this.multipartThreshold) {
-            return this.multipartUpload(blob, fileName, fileSize, options);
+        if (typeof options?.resumeUploadId === 'string' && options.resumeUploadId !== '') {
+            // SDK-3 (Wb6ebOMM): resume path takes the durable session's
+            // `recommended_chunk_size` from the /status envelope rather than
+            // the initiate envelope (initiate is skipped). Below the multipart
+            // threshold a resume is still meaningful — the original session was
+            // started as multipart, so a sub-threshold file CAN'T be a "resume
+            // target" in practice. Guard explicitly so a confused caller gets a
+            // clear error rather than a 404 on /status.
+            if (source.size <= this.multipartThreshold) {
+                throw new GislError('uploadFile: resumeUploadId set but file size is at-or-below the multipart ' +
+                    `threshold (${this.multipartThreshold} bytes); resume targets must be multipart sessions.`);
+            }
+            return this.multipartResume(source, fileName, source.size, options.resumeUploadId, options);
+        }
+        if (source.size > this.multipartThreshold) {
+            return this.multipartUpload(source, fileName, source.size, options);
         }
-        return this.singleUpload(blob, fileName, options);
+        return this.singleUpload(source, fileName, options);
     }
-    async singleUpload(blob, fileName, options) {
+    async singleUpload(source, fileName, options) {
         const form = new FormData();
-        form.append('file', blob, fileName);
+        // Single-shot is gated to <= single_shot_max_bytes (10 MB) by the router
+        // above, so this one bounded read is trivially under the libuv ceiling
+        // and a non-issue for memory. `slice` returns a Blob (the file-path
+        // source wraps the bounded Buffer) so FormData.append is unchanged —
+        // multipart never wraps a whole-file Blob, only this <=10 MB single-shot
+        // path ever holds a full payload Blob.
+        const body = await source.slice(0, source.size);
+        form.append('file', body, fileName);
         return this.request('POST', '/api/uploads', {
             body: form,
             json: false,
@@ -441,10 +609,10 @@ export class GislClient {
      * comes from the initiate response's first-chunk detection; for authoritative
      * post-upload metadata callers should use getMetadata(fileId).
      */
-    async multipartUpload(blob, fileName, totalSize, options) {
+    async multipartUpload(source, fileName, totalSize, options) {
         // Step 1: Initiate with first chunk
         const firstChunkSize = Math.min(totalSize, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
-        const firstChunk = blob.slice(0, firstChunkSize);
+        const firstChunk = await source.slice(0, firstChunkSize);
         const initiateForm = new FormData();
         initiateForm.append('file', firstChunk, fileName);
         initiateForm.append('filename', fileName);
@@ -473,6 +641,88 @@ export class GislClient {
         const etags = [];
         const presignedUrls = initResponse.presignedUrls;
         const chunkSize = initResponse.recommendedChunkSize;
+        // MultipartInitiateResponseFromJSON does NO runtime validation (unlike
+        // the strict PHP generated model, which rejects these at deserialize —
+        // the documented lax-TS-vs-strict-PHP divergence). The TS SDK must
+        // therefore enforce, before any chunk read/PUT, what PHP gets for free
+        // from its generated model + its explicit pre-loop guards (codex review):
+        //
+        // (a) uploadId must be a non-empty string. `FromJSON` assigns
+        //     `json['upload_id']` directly, so a malformed initiate could
+        //     otherwise produce a typed GislMultipartPartError whose `uploadId`
+        //     is `undefined` and synthesise a bogus UploadResponse.fileId —
+        //     mirrors the PHP pre-loop `is_string && !== ''` guard.
+        if (typeof initResponse.uploadId !== 'string' ||
+            initResponse.uploadId === '') {
+            throw new GislError('Multipart initiate response missing or empty upload_id.');
+        }
+        // (b) recommendedChunkSize must be a finite number INSIDE the contract
+        //     range [MULTIPART_CHUNK_SIZE, RECOMMENDED_CHUNK_SIZE_MAX_BYTES]. The
+        //     old `>= 1` check let a malformed/hostile huge value pass the
+        //     part-count guard and drive `fileByteSource` into an unbounded
+        //     `Buffer.allocUnsafe(length)` — the memory-blowup class this SDK
+        //     exists to prevent. PHP's strict generated model already rejects
+        //     out-of-range values at deserialize; this is the TS equivalent.
+        if (typeof chunkSize !== 'number' ||
+            !Number.isInteger(chunkSize) ||
+            chunkSize < MULTIPART_CHUNK_SIZE ||
+            chunkSize > RECOMMENDED_CHUNK_SIZE_MAX_BYTES) {
+            // `Number.isInteger` also rejects NaN/Infinity and a fractional
+            // `recommended_chunk_size` (e.g. 5242880.5) that would otherwise
+            // reach `Buffer.allocUnsafe(fractional)` and fail later as a
+            // misleading part-read error (codex review).
+            throw new GislError('Multipart initiate response recommendedChunkSize is missing or ' +
+                `outside the contract range [${MULTIPART_CHUNK_SIZE}, ` +
+                `${RECOMMENDED_CHUNK_SIZE_MAX_BYTES}]: got ${String(chunkSize)}.`);
+        }
+        // S3 <=10 000-part ceiling guard (Model A). The server computes and
+        // returns `totalParts`; we trust it (consistent with how the SDK already
+        // trusts `recommendedChunkSize`/`presignedUrls` from the same envelope)
+        // but assert the ceiling, cross-checked against a client-side recompute
+        // from the same `chunkSize`. This necessarily fires AFTER the initiate
+        // round-trip + 8 MiB first-chunk upload — `totalParts` and `chunkSize`
+        // only exist on the initiate response, so a pure pre-flight check is
+        // impossible under Model A (this is the card-mandated trade-off).
+        const remainingBytes = Math.max(0, totalSize - firstChunkSize);
+        const computedParts = 1 + Math.ceil(remainingBytes / chunkSize);
+        const serverParts = initResponse.totalParts;
+        // `FromJSON` passes `total_parts` through unvalidated. Reject a
+        // missing/non-integer value here so the ≤10k guard's
+        // `Math.max(serverParts, computedParts)` cannot surface `NaN` in the
+        // GislMultipartPartCountError (codex review). Mirrors the uploadId /
+        // chunkSize guards above (the lax-TS-vs-strict-PHP-model divergence).
+        if (typeof serverParts !== 'number' ||
+            !Number.isInteger(serverParts) ||
+            serverParts < 1) {
+            throw new GislError('Multipart initiate response missing or invalid total_parts: ' +
+                `got ${String(serverParts)}.`);
+        }
+        if (serverParts > S3_MAX_MULTIPART_PARTS ||
+            computedParts > S3_MAX_MULTIPART_PARTS) {
+            throw new GislMultipartPartCountError(`Upload requires ${Math.max(serverParts, computedParts)} parts, ` +
+                `exceeding the S3 ${S3_MAX_MULTIPART_PARTS}-part multipart limit ` +
+                `(server reported ${serverParts}, client computed ${computedParts} ` +
+                `at ${chunkSize}-byte chunks). A larger chunk size is required ` +
+                'server-side to upload a file this large.', Math.max(serverParts, computedParts), S3_MAX_MULTIPART_PARTS);
+        }
+        // Plan-consistency guard (codex review). The ≤10k ceiling above only
+        // bounds the count; it does NOT catch an initiate plan that is internally
+        // inconsistent BELOW the cap. Under Model A a contract-compliant server
+        // computes `total_parts` from the same `recommended_chunk_size` it
+        // returns, and emits exactly one presigned URL per remaining part (part 1
+        // is the initiate first chunk). If `total_parts`, the client recompute,
+        // and `presigned_urls.length` disagree, proceeding would PUT the wrong
+        // number of byte ranges (or wrong offsets) and only fail opaquely at
+        // /multipart/complete. Fail fast here with the discrepancy instead.
+        if (!Number.isFinite(serverParts) ||
+            serverParts !== computedParts ||
+            presignedUrls.length !== computedParts - 1) {
+            throw new GislError('Multipart initiate plan is internally inconsistent: server ' +
+                `total_parts=${serverParts}, client computed ${computedParts} ` +
+                `from ${chunkSize}-byte chunks, presigned_urls.length=` +
+                `${presignedUrls.length} (expected ${computedParts - 1}). ` +
+                'Refusing to upload a mismatched part plan.');
+        }
         // Internal abort signal that workers use to short-circuit each others'
         // backoff sleeps. When any worker hits a terminal failure it aborts this
         // controller, which races the caller's signal inside sleepWithSignal so
@@ -536,11 +786,33 @@ export class GislClient {
             const part = presignedUrls[index];
             const start = firstChunkSize + index * chunkSize;
             const end = Math.min(start + chunkSize, totalSize);
-            // Blob.slice() returns a new Blob view; the underlying bytes are
-            // immutable so the same `chunk` may be re-sent across retry attempts.
-            // S3 multipart parts are idempotent by partNumber — a re-PUT overwrites,
-            // there is no duplicate-data risk.
-            const chunk = blob.slice(start, end);
+            // Read this part's bytes ONCE here, then reuse the captured chunk
+            // across every retry attempt below — so a retry never re-reads the
+            // file and the re-PUT is byte-identical (S3 parts are idempotent by
+            // partNumber; a re-PUT overwrites, no duplicate-data risk).
+            //
+            // Live-file caveat (streaming divergence from the old
+            // readFileSync→Blob path): the old code snapshotted the whole file at
+            // t0 so every part was point-in-time consistent. Streaming reads each
+            // part at the instant it is first uploaded, so a file mutated
+            // mid-upload yields parts from different instants. Truncation is
+            // caught by fileByteSource's short-read guard; full point-in-time
+            // snapshotting is resumable/staged-upload territory (SDK-3, Wb6ebOMM).
+            // Surface a read failure for THIS part as the typed
+            // GislMultipartPartError (with partNumber + uploadId), consistent with
+            // the PUT-failure path below — a bare GislError from fileByteSource
+            // (short read / libuv ceiling) would otherwise lose the per-part
+            // context (codex review). An abort must stay GislAbortError.
+            let chunk;
+            try {
+                chunk = await source.slice(start, end);
+            }
+            catch (err) {
+                if (err instanceof GislAbortError)
+                    throw err;
+                throw new GislMultipartPartError(`Failed to read bytes for part ${part.partNumber}: ` +
+                    (err instanceof Error ? err.message : String(err)), part.partNumber, initResponse.uploadId);
+            }
             const contentLength = end - start;
             let lastErr = null;
             for (let attempt = 0; attempt < this.multipartMaxAttempts; attempt++) {
@@ -576,8 +848,8 @@ export class GislClient {
                 // forcing them to wait out their backoff timer.
                 await sleepWithEitherSignal(delay, options?.signal, failureController.signal);
             }
-            throw new GislError(`S3 chunk upload failed for part ${part.partNumber} after ${this.multipartMaxAttempts} attempts: ` +
-                (lastErr instanceof Error ? lastErr.message : String(lastErr)));
+            throw new GislMultipartPartError(`S3 chunk upload failed for part ${part.partNumber} after ${this.multipartMaxAttempts} attempts: ` +
+                (lastErr instanceof Error ? lastErr.message : String(lastErr)), part.partNumber, initResponse.uploadId);
         };
         // Upload with concurrency limit. Workers check the signal before pulling
         // the next queue item so a mid-upload abort drains fast without
@@ -639,7 +911,9 @@ export class GislClient {
             fileId: completeResp.uploadId,
             originalName: fileName,
             mimeType: initResponse.mimeType,
-            sizeBytes: blob.size,
+            // `totalSize` (from fs.stat / Blob.size) — the streaming path no longer
+            // holds a whole-file Blob to read `.size` off.
+            sizeBytes: totalSize,
             // Preserved from the initiate response: v2 contract makes
             // `constraintsApplied` a REQUIRED field on UploadResponse, and the
             // multipart/complete endpoint does not re-emit it. The first-chunk probe
@@ -647,6 +921,549 @@ export class GislClient {
             constraintsApplied: initResponse.constraintsApplied,
         };
     }
+    /**
+     * SDK-3 (Wb6ebOMM): resume an in-progress multipart upload.
+     *
+     * Skips `/multipart/initiate` entirely (the original initiate happened in a
+     * prior process). Walks `/status` for the authoritative list of recorded
+     * parts, re-presigns the missing ones in batches of <=100, PUTs only those,
+     * and finalises with `/complete`. Caller's `source` MUST be byte-identical
+     * to the originally-uploaded file at the same offsets (parts whose etags
+     * don't match server state will fail `/complete`).
+     *
+     * Re-runs the same `uploadId` / `chunkSize` / `totalParts` / plan-consistency
+     * guards as the fresh-upload path (`multipartUpload`), using the /status
+     * envelope as the equivalent of the initiate envelope. Reuses the same
+     * `failureController` sibling-wake + `drainResponseBody` cleanup discipline
+     * as the fresh-upload PUT loop. `onProgress` fires on entry seeded from
+     * (uploadedPartNumbers.length * chunkSize) and again after every successful
+     * PUT. `onCheckpoint` fires OUTSIDE the retry-scoped path after every
+     * successful PUT — a callback-throw must not trigger a duplicate PUT.
+     *
+     * TODO(HxUmVr3Y): replace inline hand-coded request body marshalling on regen.
+     */
+    async multipartResume(source, fileName, totalSize, resumeUploadId, options) {
+        // Step 1: Walk /status for the authoritative session state.
+        const status = await this.walkUploadStatus(resumeUploadId, {
+            signal: options?.signal,
+        });
+        // Validate the /status envelope shape, mirroring the fresh-upload
+        // post-initiate guards (`multipartUpload` lines around the
+        // total_parts / recommendedChunkSize / uploadId validation block).
+        if (typeof status.uploadId !== 'string' ||
+            status.uploadId === '' ||
+            status.uploadId !== resumeUploadId) {
+            throw new GislError('multipartResume: /status response uploadId does not match resumeUploadId.');
+        }
+        const chunkSize = status.recommendedChunkSize;
+        if (typeof chunkSize !== 'number' ||
+            !Number.isInteger(chunkSize) ||
+            chunkSize < MULTIPART_CHUNK_SIZE ||
+            chunkSize > RECOMMENDED_CHUNK_SIZE_MAX_BYTES) {
+            throw new GislError('multipartResume: /status recommendedChunkSize missing or outside the contract ' +
+                `range [${MULTIPART_CHUNK_SIZE}, ${RECOMMENDED_CHUNK_SIZE_MAX_BYTES}]: got ${String(chunkSize)}.`);
+        }
+        if (typeof status.totalParts !== 'number' ||
+            !Number.isInteger(status.totalParts) ||
+            status.totalParts < 1) {
+            throw new GislError(`multipartResume: /status totalParts missing or invalid: got ${String(status.totalParts)}.`);
+        }
+        if (status.totalParts > S3_MAX_MULTIPART_PARTS) {
+            throw new GislMultipartPartCountError(`multipartResume: /status totalParts=${status.totalParts} exceeds the S3 ` +
+                `${S3_MAX_MULTIPART_PARTS}-part multipart limit.`, status.totalParts, S3_MAX_MULTIPART_PARTS);
+        }
+        // Sanity-check the caller's byte source against the server's recorded
+        // plan. Mirrors the fresh-upload chunk-plan: part 1 = firstChunkSize
+        // (8 MiB), parts 2..totalParts each consume chunkSize bytes (last part
+        // may be a short tail). Reject a wrong-file resume here — /complete
+        // would otherwise fail on etag mismatch.
+        const firstChunkSize = Math.min(totalSize, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
+        const expectedMinBytes = firstChunkSize + Math.max(0, status.totalParts - 2) * chunkSize + (status.totalParts > 1 ? 1 : 0);
+        const expectedMaxBytes = firstChunkSize + Math.max(0, status.totalParts - 1) * chunkSize;
+        if (totalSize < expectedMinBytes || totalSize > expectedMaxBytes) {
+            throw new GislError(`multipartResume: caller file size (${totalSize}) does not match the resumed ` +
+                `session's recorded plan (totalParts=${status.totalParts}, chunkSize=${chunkSize}, ` +
+                `expected ${expectedMinBytes}-${expectedMaxBytes} bytes). Wrong file for this uploadId?`);
+        }
+        // Step 2: Compute missing parts. Server records `uploadedParts` as the
+        // authoritative set; everything in [1, totalParts] not in that set is
+        // still-to-upload. Part 1 was uploaded inline at initiate — if it is
+        // missing from /status the session is unrecoverable (the server rejects
+        // re-presigning part 1 to preserve the recorded etag for /complete).
+        const uploaded = new Map();
+        for (const p of status.uploadedParts) {
+            uploaded.set(p.partNumber, p);
+        }
+        if (!uploaded.has(1)) {
+            throw new GislError('multipartResume: part 1 (initiate first chunk) is missing from /status. ' +
+                'Part 1 is sealed at initiate and cannot be re-presigned; this session is unrecoverable. ' +
+                'Start a fresh upload (call uploadFile without resumeUploadId).');
+        }
+        const missingParts = [];
+        for (let n = 2; n <= status.totalParts; n++) {
+            if (!uploaded.has(n))
+                missingParts.push(n);
+        }
+        // Seed uploadedBytes from already-uploaded parts so onProgress reflects
+        // the true resumption point. Server reports authoritative part sizes
+        // via `sizeBytes`; sum those rather than guessing chunkSize * count
+        // (the last part may be a short tail).
+        let uploadedBytes = 0;
+        for (const p of status.uploadedParts) {
+            uploadedBytes += p.sizeBytes;
+        }
+        options?.onProgress?.(uploadedBytes, totalSize);
+        const fireCheckpoint = (extraPartNumber) => {
+            const all = [...uploaded.keys()];
+            if (extraPartNumber !== undefined)
+                all.push(extraPartNumber);
+            all.sort((a, b) => a - b);
+            const state = {
+                uploadId: status.uploadId,
+                totalParts: status.totalParts,
+                uploadedPartNumbers: all,
+                manifestExpiresAt: status.manifestExpiresAt,
+            };
+            // Callback fires OUTSIDE retry-scope. A throw here propagates and
+            // fails the upload but cannot trigger a duplicate PUT.
+            options?.onCheckpoint?.(state);
+        };
+        // Fire an entry checkpoint so callers can persist the resumed state
+        // even before any new PUT lands. Useful when the missing-parts list is
+        // empty (everything already uploaded except /complete) — see below.
+        fireCheckpoint();
+        // Short-circuit: every part is already uploaded. Skip presign + PUT
+        // and go straight to /complete with the etags the server has on file.
+        const newEtags = [];
+        if (missingParts.length === 0) {
+            // No PUTs to run; proceed to /complete below with just the recorded parts.
+        }
+        else {
+            // Step 3: For each batch of <=100 missing parts, re-presign + PUT.
+            // We process batches sequentially (presign call) but PUTs within each
+            // batch run concurrently up to multipartConcurrency, mirroring the
+            // fresh-upload worker-pool semantics.
+            const failureController = new AbortController();
+            const putOne = async (part) => {
+                // Offset math mirrors the fresh-upload path
+                // (`multipartUpload`'s `uploadChunk`): part 1 is the initiate's 8 MiB
+                // first chunk, parts 2..N each consume chunkSize bytes starting at
+                // firstChunkSize. The resume path never PUTs part 1 (rejected
+                // earlier as unrecoverable), so partNumber here is always >= 2.
+                const firstChunkSize = Math.min(totalSize, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
+                const start = firstChunkSize + (part.partNumber - 2) * chunkSize;
+                const end = Math.min(start + chunkSize, totalSize);
+                const contentLength = end - start;
+                let chunk;
+                try {
+                    chunk = await source.slice(start, end);
+                }
+                catch (err) {
+                    if (err instanceof GislAbortError)
+                        throw err;
+                    throw new GislMultipartPartError(`multipartResume: failed to read bytes for part ${part.partNumber}: ` +
+                        (err instanceof Error ? err.message : String(err)), part.partNumber, status.uploadId);
+                }
+                let lastErr = null;
+                for (let attempt = 0; attempt < this.multipartMaxAttempts; attempt++) {
+                    if (options?.signal?.aborted) {
+                        throw new GislAbortError(`multipartResume: S3 part ${part.partNumber} upload aborted`);
+                    }
+                    if (failureController.signal.aborted) {
+                        throw new GislError(`multipartResume: S3 part ${part.partNumber} upload abandoned after sibling failure`);
+                    }
+                    let s3Response;
+                    try {
+                        s3Response = await fetch(part.url, {
+                            method: 'PUT',
+                            body: chunk,
+                            headers: { 'Content-Length': contentLength.toString() },
+                            signal: options?.signal,
+                        });
+                    }
+                    catch (err) {
+                        if (isAbortError(err) && options?.signal?.aborted) {
+                            throw new GislAbortError(`multipartResume: S3 part ${part.partNumber} upload aborted`);
+                        }
+                        // Non-user-abort AbortError (e.g. transport cleanup) must still
+                        // surface as a typed GislError subclass — never as a raw
+                        // DOMException — to preserve the "every multipart failure is a
+                        // typed GislError" contract (code-reviewer P7).
+                        if (isAbortError(err)) {
+                            throw new GislMultipartPartError(`multipartResume: S3 part ${part.partNumber} aborted by transport: ` +
+                                (err instanceof Error ? err.message : String(err)), part.partNumber, status.uploadId);
+                        }
+                        if (isRetryableNetworkError(err)) {
+                            lastErr = err;
+                            if (attempt + 1 >= this.multipartMaxAttempts)
+                                break;
+                            const delay = fullJitterDelay(this.multipartRetryBaseMs, attempt);
+                            await sleepWithEitherSignal(delay, options?.signal, failureController.signal);
+                            continue;
+                        }
+                        throw err;
+                    }
+                    if (s3Response.ok) {
+                        const etag = s3Response.headers.get('etag');
+                        if (!etag) {
+                            await drainResponseBody(s3Response);
+                            throw new GislError(`multipartResume: S3 response missing ETag for part ${part.partNumber}`);
+                        }
+                        // Successful PUT — record etag, apply progress + checkpoint side
+                        // effects OUTSIDE the retry-scoped path (mirrors the fresh-upload
+                        // discipline at multipartUpload's ok-branch).
+                        newEtags.push({ partNumber: part.partNumber, etag });
+                        uploaded.set(part.partNumber, {
+                            partNumber: part.partNumber,
+                            etag,
+                            sizeBytes: contentLength,
+                            lastModified: new Date().toISOString(),
+                        });
+                        uploadedBytes = Math.min(uploadedBytes + contentLength, totalSize);
+                        options?.onProgress?.(uploadedBytes, totalSize);
+                        fireCheckpoint();
+                        return;
+                    }
+                    await drainResponseBody(s3Response);
+                    if (!isRetryableStatus(s3Response.status)) {
+                        throw new GislError(`multipartResume: S3 chunk upload failed for part ${part.partNumber}: HTTP ${s3Response.status} (non-retryable)`);
+                    }
+                    lastErr = new GislError(`multipartResume: S3 chunk upload failed for part ${part.partNumber}: HTTP ${s3Response.status}`);
+                    if (attempt + 1 >= this.multipartMaxAttempts)
+                        break;
+                    const delay = fullJitterDelay(this.multipartRetryBaseMs, attempt);
+                    await sleepWithEitherSignal(delay, options?.signal, failureController.signal);
+                }
+                throw new GislMultipartPartError(`multipartResume: S3 chunk upload failed for part ${part.partNumber} after ${this.multipartMaxAttempts} attempts: ` +
+                    (lastErr instanceof Error ? lastErr.message : String(lastErr)), part.partNumber, status.uploadId);
+            };
+            // Drive batches of <=100 part numbers.
+            const PRESIGN_BATCH_SIZE = 100;
+            for (let i = 0; i < missingParts.length; i += PRESIGN_BATCH_SIZE) {
+                if (options?.signal?.aborted) {
+                    throw new GislAbortError('multipartResume aborted');
+                }
+                const batch = missingParts.slice(i, i + PRESIGN_BATCH_SIZE);
+                const presigned = await this.presignParts(status.uploadId, batch, status.totalParts, { signal: options?.signal });
+                // Concurrent PUTs within the batch.
+                const queue = [...presigned.presignedUrls];
+                const workers = Array.from({ length: Math.min(this.multipartConcurrency, queue.length) }, async () => {
+                    while (queue.length > 0 && !failureController.signal.aborted) {
+                        if (options?.signal?.aborted) {
+                            throw new GislAbortError('multipartResume aborted');
+                        }
+                        const part = queue.shift();
+                        try {
+                            await putOne(part);
+                        }
+                        catch (err) {
+                            failureController.abort();
+                            throw err;
+                        }
+                    }
+                });
+                await Promise.all(workers);
+            }
+        }
+        // Step 4: /complete with the FULL parts list = (server-recorded etags
+        // from /status) ∪ (newly-PUT etags this run). Sort ascending by
+        // partNumber (the wire shape pin in fresh-upload mirrors this).
+        const allParts = [];
+        for (const p of status.uploadedParts) {
+            allParts.push({ partNumber: p.partNumber, etag: p.etag });
+        }
+        for (const e of newEtags)
+            allParts.push(e);
+        allParts.sort((a, b) => a.partNumber - b.partNumber);
+        if (allParts.length !== status.totalParts) {
+            throw new GislError(`multipartResume: assembled parts list has ${allParts.length} entries, ` +
+                `expected ${status.totalParts}. Refusing to /complete with an incomplete part set.`);
+        }
+        // Marshal via the generator's `*ToJSON` helper so the contracts-drift
+        // guard test (`contract-drift-fields.test.ts`) covers BOTH the fresh and
+        // resume paths uniformly (code-reviewer P7). If a future regen adds a
+        // required field to `MultipartCompleteRequest`, tsc fails here at the
+        // typed object literal — same as the fresh path.
+        const completeRequest = {
+            uploadId: status.uploadId,
+            parts: allParts.map((p) => ({ partNumber: p.partNumber, etag: p.etag })),
+        };
+        const wireCompleteBody = MultipartCompleteRequestToJSON(completeRequest);
+        if (typeof wireCompleteBody?.upload_id !== 'string' ||
+            !Array.isArray(wireCompleteBody?.parts)) {
+            throw new GislError('multipartResume: MultipartCompleteRequestToJSON returned an unexpected shape.');
+        }
+        const completeResp = await this.request('POST', '/api/uploads/multipart/complete', {
+            body: wireCompleteBody,
+            deserialize: MultipartCompleteResponseFromJSON,
+            signal: options?.signal,
+        });
+        if (completeResp.status !== 'completed') {
+            throw new GislError(`multipartResume: completed with unexpected status: ${completeResp.status}`);
+        }
+        // Resume-path information loss: the /status envelope (and /complete)
+        // do NOT carry `mime_type` or `constraints_applied` — those were
+        // emitted on the original initiate envelope, which the resume path
+        // skipped. Fall back to caller-supplied `fileName` for `originalName`;
+        // emit `mimeType` as `''` and `constraintsApplied` as a sentinel
+        // populated with the only fact we DO know on resume: `maxSizeBytes =
+        // totalSize` (the upload was permitted at this size when initiated),
+        // `processingClassPreAssignment = 'unknown'`. Consumers needing
+        // authoritative post-upload metadata SHOULD call `getMetadata(fileId)`
+        // (the fresh-upload path's docblock already says the same).
+        // TODO(HxUmVr3Y): when contracts ships the resume-support schemas,
+        // extend `/status` (or add `/multipart/{id}/manifest`) to carry
+        // mime_type + constraints_applied so this sentinel can go away.
+        return {
+            fileId: completeResp.uploadId,
+            originalName: fileName,
+            mimeType: '',
+            sizeBytes: totalSize,
+            constraintsApplied: {
+                maxSizeBytes: totalSize,
+                // `maxDurationSeconds` deliberately omitted (not `null`): parity
+                // comparator filters `undefined` keys from both sides; cross-SDK
+                // upload_small precedent.
+                processingClassPreAssignment: UploadConstraintsAppliedProcessingClassPreAssignmentEnum.unknown,
+            },
+        };
+    }
+    // -----------------------------------------------------------------------
+    // SDK-3 (Wb6ebOMM) — resume-support endpoints
+    // -----------------------------------------------------------------------
+    /**
+     * Fetch the durable status of an in-progress multipart upload session.
+     *
+     * Walks every page of `GET /api/uploads/multipart/{uploadId}/status`
+     * (paginated via `next_part_number_marker` + `is_truncated`) and returns
+     * the aggregated state. Callers see the complete set of recorded parts
+     * across pages without driving the cursor themselves.
+     *
+     * Anonymous-initiated sessions return 403 → `GislMultipartSessionAuthRequiredError`.
+     * Non-existent / expired sessions return 404 → `GislMultipartSessionNotFoundError`.
+     * Authed-but-non-owning callers return 403 → `GislMultipartSessionOwnershipError`.
+     *
+     * TODO(HxUmVr3Y): replace hand-coded response shape on regen.
+     */
+    async getUploadStatus(uploadId, opts = {}) {
+        if (typeof uploadId !== 'string' || uploadId === '') {
+            throw new GislError('getUploadStatus: uploadId must be a non-empty string.');
+        }
+        return this.walkUploadStatus(uploadId, opts);
+    }
+    /**
+     * Re-presign a batch of missing part numbers on an in-progress multipart
+     * session.
+     *
+     * Validates client-side BEFORE the HTTP round-trip:
+     * - `partNumbers` non-empty
+     * - length <=100 (server raw-body cap is 8 KiB before json_decode)
+     * - every entry an integer in `[2, totalParts]` — part 1 is sealed at
+     *   initiate (re-presigning it would break the etag recorded server-side
+     *   for /complete)
+     * - entries unique
+     * - `totalParts` <=10 000 (S3 hard limit; mirrors the SDK-1 ceiling guard)
+     *
+     * TODO(HxUmVr3Y): replace hand-coded request/response shapes on regen.
+     */
+    async presignParts(uploadId, partNumbers, totalParts, opts = {}) {
+        if (typeof uploadId !== 'string' || uploadId === '') {
+            throw new GislError('presignParts: uploadId must be a non-empty string.');
+        }
+        if (typeof totalParts !== 'number' ||
+            !Number.isInteger(totalParts) ||
+            totalParts < 1) {
+            throw new GislError(`presignParts: totalParts must be a positive integer, got ${String(totalParts)}.`);
+        }
+        if (totalParts > S3_MAX_MULTIPART_PARTS) {
+            throw new GislMultipartPartCountError(`presignParts: totalParts=${totalParts} exceeds the S3 ${S3_MAX_MULTIPART_PARTS}-part ` +
+                'multipart limit. Refusing to re-presign on a session that cannot complete.', totalParts, S3_MAX_MULTIPART_PARTS);
+        }
+        if (!Array.isArray(partNumbers) || partNumbers.length === 0) {
+            throw new GislError('presignParts: partNumbers must be a non-empty array.');
+        }
+        if (partNumbers.length > 100) {
+            throw new GislError(`presignParts: partNumbers has ${partNumbers.length} entries — server caps batches at 100.`);
+        }
+        const seen = new Set();
+        for (const n of partNumbers) {
+            if (typeof n !== 'number' ||
+                !Number.isInteger(n) ||
+                n < 2 ||
+                n > totalParts) {
+                throw new GislError(`presignParts: partNumbers entry ${String(n)} is not an integer in [2, ${totalParts}]. ` +
+                    'Part 1 is sealed at initiate; re-presigning it would invalidate the recorded etag for /complete.');
+            }
+            if (seen.has(n)) {
+                throw new GislError(`presignParts: partNumbers contains duplicate ${n}.`);
+            }
+            seen.add(n);
+        }
+        const path = `/api/uploads/multipart/${encodeURIComponent(uploadId)}/presign`;
+        return this.request('POST', path, {
+            // Hand-coded snake_case wire body. TODO(HxUmVr3Y): replace with
+            // generated `*RequestToJSON` helper on regen.
+            body: { part_numbers: [...partNumbers] },
+            deserialize: (raw) => {
+                // Hand-coded snake_case -> camelCase. TODO(HxUmVr3Y): replace with
+                // generated FromJSON helper on regen.
+                const r = raw;
+                if (typeof r.upload_id !== 'string' || !Array.isArray(r.presigned_urls)) {
+                    throw new GislError('presignParts: malformed response envelope.');
+                }
+                return {
+                    uploadId: r.upload_id,
+                    presignedUrls: r.presigned_urls.map((p) => ({
+                        partNumber: p.part_number,
+                        url: p.url,
+                        expiresAt: p.expires_at,
+                    })),
+                };
+            },
+            signal: opts.signal,
+        });
+    }
+    /**
+     * Extend the manifest TTL of an in-progress multipart upload session.
+     *
+     * The durable session manifest defaults to a 48 h TTL (decoupled from the
+     * shorter presigned-URL TTL). For a long-running resume that spans days
+     * (e.g. an upload paused overnight on flaky Wi-Fi), callers SHOULD invoke
+     * `keepaliveUpload` every **12-24 h** while resuming — the 12-24 h band
+     * leaves >=24 h of slack against the 48 h ceiling even with worst-case
+     * clock skew between client and server. The server atomically refreshes
+     * the Redis EXPIRE for the manifest key; the call is idempotent.
+     *
+     * TODO(HxUmVr3Y): replace hand-coded response shape on regen.
+     */
+    async keepaliveUpload(uploadId, opts = {}) {
+        if (typeof uploadId !== 'string' || uploadId === '') {
+            throw new GislError('keepaliveUpload: uploadId must be a non-empty string.');
+        }
+        const path = `/api/uploads/multipart/${encodeURIComponent(uploadId)}/keepalive`;
+        return this.request('POST', path, {
+            // Server expects an empty body; pass an empty object so the `request`
+            // helper sets `Content-Type: application/json` for symmetry with the
+            // other JSON-bodied POSTs. The endpoint ignores any fields if present.
+            body: {},
+            deserialize: (raw) => {
+                // Hand-coded snake_case -> camelCase. TODO(HxUmVr3Y): replace with
+                // generated FromJSON helper on regen.
+                const r = raw;
+                if (typeof r.upload_id !== 'string' ||
+                    typeof r.manifest_expires_at !== 'string') {
+                    throw new GislError('keepaliveUpload: malformed response envelope.');
+                }
+                return {
+                    uploadId: r.upload_id,
+                    manifestExpiresAt: r.manifest_expires_at,
+                };
+            },
+            signal: opts.signal,
+        });
+    }
+    /**
+     * Private walk-pagination helper for /status. Aggregates every page into
+     * a single `_Sdk3HandCodedMultipartStatusResult`. AbortSignal short-circuits
+     * the loop between page fetches AND propagates into each fetch.
+     *
+     * Limit pinned to 1000 (max per page) so we make the minimum number of
+     * round-trips even for the worst-case ~10 pages on a 10 000-part upload.
+     */
+    async walkUploadStatus(uploadId, opts) {
+        const PAGE_LIMIT = 1000;
+        // Slow-path DoS guard (code-reviewer minor 6). The cursor-advance check
+        // already prevents an infinite loop; this cap additionally prevents a
+        // pathological server that advances by 1 each page from forcing
+        // O(totalParts) round-trips for a 10 000-part upload. PAGE_LIMIT=1000
+        // means a healthy server completes in <=10 round-trips; 50 leaves
+        // generous slack.
+        const MAX_PAGES = 50;
+        const collected = [];
+        let cursor = 0;
+        let totalParts = 0;
+        let multipartUploadId = '';
+        let cloudKey = '';
+        let manifestExpiresAt = '';
+        let recommendedChunkSize = 0;
+        let pageCount = 0;
+        while (true) {
+            if (opts.signal?.aborted) {
+                throw new GislAbortError('getUploadStatus aborted');
+            }
+            if (pageCount >= MAX_PAGES) {
+                throw new GislError(`getUploadStatus: server returned more than ${MAX_PAGES} pages — refusing to ` +
+                    'continue. The /status endpoint should advance the cursor in 1000-part strides.');
+            }
+            pageCount += 1;
+            const query = `?cursor=${cursor}&limit=${PAGE_LIMIT}`;
+            // String-concat the query OUTSIDE the path backtick so the contract-drift
+            // scanner (tests/unit/contract-drift.test.ts) sees the bare path
+            // `/api/uploads/multipart/{id}/status`. Embedding `${query}` in the
+            // template collapses to `/status{id}` and false-drifts — same reason
+            // getSchema and getCreditsUsage concatenate their querystrings.
+            const path = `/api/uploads/multipart/${encodeURIComponent(uploadId)}/status` + query;
+            const page = await this.request('GET', path, { signal: opts.signal });
+            // Defensive: server contract pins these fields. Strict-validate every
+            // top-level field on each page (code-reviewer P7) so a malformed wire
+            // envelope cannot silently coerce a missing key to '' / 0 / NaN and
+            // flow it into MultipartCheckpointState.manifestExpiresAt or downstream
+            // chunkSize guards.
+            if (typeof page.total_parts !== 'number' || page.total_parts < 1) {
+                throw new GislError('getUploadStatus: server page missing or invalid total_parts.');
+            }
+            if (typeof page.upload_id !== 'string' ||
+                page.upload_id !== uploadId ||
+                typeof page.multipart_upload_id !== 'string' ||
+                page.multipart_upload_id === '' ||
+                typeof page.cloud_key !== 'string' ||
+                page.cloud_key === '' ||
+                typeof page.manifest_expires_at !== 'string' ||
+                page.manifest_expires_at === '' ||
+                typeof page.recommended_chunk_size !== 'number') {
+                throw new GislError('getUploadStatus: server page missing required fields or returned a ' +
+                    `mismatching upload_id (expected ${uploadId}, got ` +
+                    `${String(page.upload_id)}).`);
+            }
+            totalParts = page.total_parts;
+            multipartUploadId = page.multipart_upload_id;
+            cloudKey = page.cloud_key;
+            manifestExpiresAt = page.manifest_expires_at;
+            recommendedChunkSize = page.recommended_chunk_size;
+            for (const p of page.uploaded_parts ?? []) {
+                collected.push({
+                    partNumber: p.part_number,
+                    etag: p.etag,
+                    sizeBytes: p.size_bytes,
+                    lastModified: p.last_modified,
+                });
+            }
+            if (!page.is_truncated)
+                break;
+            // Advance cursor; guard against a contract-violating non-advancing
+            // marker that would loop forever.
+            if (typeof page.next_part_number_marker !== 'number' ||
+                page.next_part_number_marker <= cursor) {
+                throw new GislError('getUploadStatus: server is_truncated=true but next_part_number_marker ' +
+                    `did not advance (was ${cursor}, got ${String(page.next_part_number_marker)}).`);
+            }
+            cursor = page.next_part_number_marker;
+        }
+        // Sort ascending by partNumber — server SHOULD already deliver in order
+        // page-by-page, but a defensive sort keeps the aggregated shape's
+        // contract simple to consume (resume-branch missing-parts compute scans
+        // it linearly).
+        collected.sort((a, b) => a.partNumber - b.partNumber);
+        return {
+            uploadId,
+            multipartUploadId,
+            cloudKey,
+            totalParts,
+            uploadedParts: collected,
+            manifestExpiresAt,
+            recommendedChunkSize,
+        };
+    }
     // -----------------------------------------------------------------------
     // Workflows
     // -----------------------------------------------------------------------
@@ -740,13 +1557,105 @@ export class GislClient {
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
      */
-    async streamEvents(workflowId) {
+    async streamEvents(workflowId, opts = {}) {
         const eventsPath = `/api/workflows/${encodeURIComponent(workflowId)}/events`;
-        const response = await this.request('GET', eventsPath, { rawResponse: true });
+        // SSE-lifetime AbortController. `request()` builds its own controller
+        // and tears it down (`clearTimeout(timer); unbind()`) in its `finally`
+        // the instant the response headers arrive — BEFORE the SSE body
+        // streams — so that controller cannot cancel a long-lived stream.
+        // `streamEvents` must own a controller for the stream's whole lifetime.
+        // We pass its signal to `request()` too, so a pre-aborted signal /
+        // connect-phase abort still fast-fails. After headers, the live socket
+        // is freed only by `reader.cancel()` inside `parseSseStream` — driven
+        // by aborting this controller from the iterator wrapper's
+        // `return()`/`throw()` (a generator's own `return()` is unreachable
+        // while suspended at `await reader.read()`; canonical pattern:
+        // openai-node `Stream[Symbol.asyncIterator]` + PR #1314).
+        const controller = new AbortController();
+        // Compose an optional consumer-supplied signal onto our controller.
+        // The teardown MUST run (normal completion, error, OR early return)
+        // or a long-lived consumer AbortController leaks listeners.
+        const releaseConsumerSignal = bindAbortSignal(opts.signal, controller);
+        let response;
+        try {
+            response = await this.request('GET', eventsPath, {
+                rawResponse: true,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            releaseConsumerSignal();
+            throw err;
+        }
         if (!response.ok) {
-            await this.handleResponse(response, eventsPath);
+            try {
+                await this.handleResponse(response, eventsPath); // always throws
+            }
+            finally {
+                releaseConsumerSignal();
+            }
         }
-        return parseSseStream(response);
+        const inner = parseSseStream(response, { signal: controller.signal });
+        let started = false;
+        let settled = false;
+        // Idempotent teardown. `abort` only on consumer-driven early
+        // termination (return/throw) — NOT on normal completion or stream
+        // error, where aborting would be a spurious "aborted though it
+        // wasn't" signal (openai-node#194). If the consumer disposes the
+        // iterator before ever pulling an event, the inner generator never
+        // ran, so its `finally` won't cancel the body — cancel it here as a
+        // backstop (the body is still unlocked: no reader was acquired).
+        const cleanup = (abort) => {
+            if (settled)
+                return;
+            settled = true;
+            if (abort)
+                controller.abort();
+            if (!started)
+                void response.body?.cancel().catch(() => { });
+            releaseConsumerSignal();
+        };
+        // Abort-before-first-pull backstop. If the consumer aborts (their
+        // signal, composed onto `controller`) and then drops the iterator
+        // WITHOUT ever calling next()/return()/throw(), nothing else frees the
+        // already-fetched body: `request()` unbound its fetch controller at
+        // header receipt, and `parseSseStream` only attaches its reader +
+        // abort listener once iteration starts. `cleanup`'s `!started` branch
+        // only runs from the wrapper methods, so it never fires on a pure
+        // abort-and-drop. Cancel the (still-unlocked) body directly here.
+        // Once started, `parseSseStream` owns the locked reader and cancels
+        // via its own abort listener, so this no-ops.
+        controller.signal.addEventListener('abort', () => {
+            if (!started)
+                void response.body?.cancel().catch(() => { });
+        }, { once: true });
+        const wrapper = {
+            async next(...args) {
+                started = true;
+                try {
+                    const result = await inner.next(...args);
+                    if (result.done)
+                        cleanup(false);
+                    return result;
+                }
+                catch (err) {
+                    cleanup(false);
+                    throw err;
+                }
+            },
+            async return(value) {
+                cleanup(true);
+                return inner.return(value);
+            },
+            async throw(err) {
+                cleanup(true);
+                return inner.throw(err);
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+        return wrapper;
     }
     // -----------------------------------------------------------------------
     // File metadata