@sparkvault/sdk-mobile 7.0.0 → 7.0.1

package/dist/tus.js

@@ -1,5 +1,7 @@
 import { FORGE_URL_REFUSAL, readForgeSessionUrl, readForgeTransferUrl, resolveForgeSessionUrl } from './app-sdk/forge-url.js';
 import { SPARKVAULT_OWNED_HOST_PATTERNS } from './app-sdk/platform-domains.js';
+import { HEAD_AND_RECEIPT_TIMEOUT_MS, TRANSFER_VERDICT, UPLOAD_EXPIRES_HEADER, classifyTransferResponse, createTransferBudget, parseUploadExpires, resumeOffsetProblem, retryDelayMs, transferJitterKey, } from './app-sdk/transfer-retry.js';
+import { UPLOAD_REFUSAL_CODES } from './app-sdk/upload-publication.js';
 import { BackgroundTransferError, gateErrorFromBody, SparkVaultMobileError, SparkVaultValidationError, TusUploadError, } from './errors.js';
 const TUS_VERSION = '1.0.0';
 /** What a refused Forge URL was refused for, in the words this SDK's errors use. */
@@ -64,9 +66,12 @@ export function allowsHost(allowedHostPatterns) {
     return hostname => allowedHostPatterns.some(pattern => pattern.test(hostname));
 }
 /**
- * Parse a Forge error response body (JSON text) into the shared ApiErrorBody
- * shape so gate mapping can read its `error.code` / `error.details.resource`.
- * Returns an empty body on non-JSON text, which simply matches no gate.
+ * Parse a Forge error response body (JSON text), whole, into the shared
+ * ApiErrorBody shape: the one reader of a failed answer's body, so gate
+ * mapping reads its `error.code` / `error.details.resource` and the transfer
+ * policy the refusal Core decided (`error.details.coreCode`) from the same
+ * parse. Returns an empty body on non-JSON text, which matches no gate and
+ * names no refusal.
  */
 function parseErrorBody(text) {
     if (!text)
@@ -85,9 +90,13 @@ function getErrorName(err) {
 function getErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** What every path the caller's abort stops reports: the one cancellation the outer catch terminates or keeps by. */
+function cancelledError() {
+    return new TusUploadError('Upload cancelled', { phase: 'cancelled' });
+}
 function ensureNotAborted(signal) {
     if (signal?.aborted) {
-        throw new TusUploadError('Upload cancelled', { phase: 'cancelled' });
+        throw cancelledError();
     }
 }
 /**
@@ -101,28 +110,231 @@ function parseIntegerHeader(raw, minimum) {
     const value = Number(raw);
     return Number.isSafeInteger(value) && value >= minimum ? value : null;
 }
-/**
- * Forge's answers that mean the tus session no longer exists: it expired,
- * or a DELETE terminated it. One list, so every request that can meet a
- * dead session (HEAD, the finalization PATCH, the OS engine's PATCHes,
- * DELETE) and the app's own session bookkeeping agree on what "gone" is.
- */
-const SESSION_GONE_STATUSES = new Set([404, 410]);
 /**
  * True when a Forge status says the tus session is gone (expired or
  * terminated): the persisted session is worthless, and a caller starts a
- * fresh upload instead of retrying it.
+ * fresh upload instead of retrying it. It is the transfer policy's GONE
+ * verdict, so every request that can meet a dead session (HEAD, a PATCH, the
+ * OS engine's PATCHes, DELETE) and the app's own session bookkeeping agree on
+ * what "gone" is.
  */
 export function isSessionGone(status) {
-    return SESSION_GONE_STATUSES.has(status);
+    return Number.isSafeInteger(status) && status > 0 && classifyTransferResponse({ status }).verdict === TRANSFER_VERDICT.GONE;
 }
-function sessionLostError(status, context, phase, cause = null) {
+/**
+ * Forge no longer has the session: `coreCode` names the code Core ended it
+ * with when the answer named one (`NOT_FOUND`, `UPLOAD_PROTOCOL_RETIRED`, a
+ * 412's), none of them a refusal a new upload cannot remedy.
+ */
+function sessionLostError(status, context, phase, cause = null, coreCode = null) {
     return new TusUploadError(`TUS session no longer exists on the server (${status})`, {
         cause,
         httpStatus: status,
         ...context,
         phase,
         sessionLost: true,
+        coreCode,
+    });
+}
+/**
+ * How far past the expiry Forge named a session still counts as live: the
+ * allowance for a device clock running ahead of Forge's. `Upload-Expires` is
+ * read off Forge's clock and compared with the device's; a phone on automatic
+ * time is within seconds of Forge, one set by hand is typically minutes fast.
+ * The two mistakes cost very differently: a live session judged expired is
+ * dropped and its file sent again from byte 0, an expired one judged live
+ * costs a single HEAD (Forge answers 410, `sessionLost`). So the margin errs
+ * long, and stays small against the 72 h idle window a session lives from its
+ * last commit (`@sparkvault/app-sdk/upload-expiry`): a session the clock says
+ * lapsed hours ago is still dropped without a request.
+ */
+export const SESSION_EXPIRY_CLOCK_MARGIN_MS = 5 * 60 * 1000;
+/**
+ * True when the expiry Forge named for a session (`TusSessionInfo.expiresAt`,
+ * kept current through `onSessionExpiry`) is past by more than the clock
+ * margin: Forge refuses every request to a session past its expiry, so a
+ * caller drops it without asking. Within the margin the session is live for
+ * all the device clock can tell, and Forge's HEAD decides. An unknown expiry
+ * (null) never has passed: only Forge's HEAD can say.
+ */
+export function isSessionExpired(expiresAt, now = Date.now()) {
+    return typeof expiresAt === 'number' && now > expiresAt + SESSION_EXPIRY_CLOCK_MARGIN_MS;
+}
+/** An answer that arrived: its status, its headers and the body of one that is not a 2xx. */
+function answerOf(status, header, body) {
+    return { status, header, body, envelope: parseErrorBody(body), unanswered: null };
+}
+function noAnswer(error) {
+    return { status: 0, header: () => null, body: '', envelope: {}, unanswered: error };
+}
+/**
+ * The transfer policy's reading of an answer to `request`: what to do next,
+ * its `Retry-After`, its `Upload-Offset`, and the refusal Core decided when
+ * the answer is one.
+ */
+function readOutcome(answer, request) {
+    return classifyTransferResponse({
+        status: answer.status,
+        headers: answer.header,
+        details: answer.envelope.error?.details ?? null,
+        receipt: request.receipt,
+    });
+}
+const CREATE_REQUEST = { label: 'TUS create', phase: 'create', gonePhase: null, receipt: false };
+const RESUME_HEAD_REQUEST = { label: 'TUS HEAD', phase: 'create', gonePhase: 'create', receipt: false };
+const OFFSET_HEAD_REQUEST = { label: 'TUS HEAD', phase: 'upload', gonePhase: 'create', receipt: false };
+const CHUNK_REQUEST = { label: 'Chunk upload', phase: 'upload', gonePhase: 'upload', receipt: false };
+const RECEIPT_REQUEST = { label: 'TUS finalization', phase: 'upload', gonePhase: 'create', receipt: true };
+/** What a caller hears once Forge kept deferring the publication until the upload's idle limit. */
+const RECEIVED_PUBLISHING_MESSAGE = 'Upload received: Forge holds every byte and is still saving the file; it finishes without this device';
+/**
+ * What a caller reads for a final refusal whose answer carried no sentence of
+ * Core's (a HEAD's, which has no body, naming Core's code in
+ * `X-Upload-Refusal` alone): this SDK's own words for each code.
+ */
+const REFUSAL_WORDING = new Map([
+    [UPLOAD_REFUSAL_CODES.UPLOAD_POOL_FULL, 'This upload could not be saved: the owner\'s storage cannot take the file'],
+    [UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED, 'This upload was not saved: a newer upload of this file replaced it'],
+]);
+/**
+ * Core refused the upload for good, in its own words (the answer's body,
+ * `details.coreCode` naming Core's code) or, for an answer with no body (a
+ * HEAD's, naming the code in `X-Upload-Refusal`), in this SDK's: the
+ * account's storage pool cannot take it, or a later upload replaced it. Not
+ * `sessionLost`: a new upload of the same file is no remedy.
+ */
+function refusedError(status, envelope, coreCode, context, phase, cause = null) {
+    const coreMessage = envelope.error?.message;
+    const message = typeof coreMessage === 'string' && coreMessage
+        ? coreMessage
+        : REFUSAL_WORDING.get(coreCode) ?? `Forge did not save this upload: Core refused it for good (${coreCode})`;
+    return new TusUploadError(message, { cause, httpStatus: status, code: 'upload_refused', coreCode, ...context, phase });
+}
+/**
+ * The failure a request's answer amounts to: the no-answer error as it was
+ * classified, a gone session as `sessionLost`, the refusal Core decided in
+ * Core's words (`upload_refused`), the receipt's deferral as the
+ * received-publishing outcome a caller resumes later (`retryLater`; thrown
+ * only once the idle limit ends the asking), a 402 as the typed gate error
+ * the JSON HTTP path throws (so callers run their subscribe / add-on UX off
+ * one set of types), and every other status as a `TusUploadError` carrying
+ * it and its `Retry-After`.
+ */
+function failureOf(answer, outcome, request, context) {
+    return { error: errorOf(answer, outcome, request, context), outcome, unanswered: answer.unanswered !== null };
+}
+function errorOf(answer, outcome, request, context) {
+    if (answer.unanswered)
+        return answer.unanswered;
+    if (outcome.verdict === TRANSFER_VERDICT.REFUSED && outcome.coreCode !== null) {
+        return refusedError(answer.status, answer.envelope, outcome.coreCode, context, request.phase);
+    }
+    if (outcome.verdict === TRANSFER_VERDICT.GONE && request.gonePhase !== null) {
+        return sessionLostError(answer.status, context, request.gonePhase, null, outcome.coreCode);
+    }
+    if (outcome.verdict === TRANSFER_VERDICT.DEFERRED) {
+        return new TusUploadError(RECEIVED_PUBLISHING_MESSAGE, {
+            httpStatus: answer.status,
+            code: 'upload_received_publishing',
+            retryAfterMs: outcome.retryAfterMs,
+            ...context,
+            phase: 'finalize',
+            retryLater: true,
+        });
+    }
+    const gateError = gateErrorFromBody(answer.status, answer.envelope);
+    if (gateError)
+        return gateError;
+    return new TusUploadError(`${request.label} failed: ${answer.status} - ${answer.body.substring(0, 200)}`, {
+        httpStatus: answer.status,
+        retryAfterMs: outcome.retryAfterMs,
+        ...context,
+        phase: request.phase,
+    });
+}
+/**
+ * The session's expiry as its latest answer named it, reported to the
+ * caller (`onSessionExpiry`) each time it changes. An answer that names none
+ * leaves it unknown: the request may have moved it unread (a commit whose
+ * answer was lost, a deferred finalization), and a caller that dropped a
+ * session on an expiry Forge has since moved on would re-send a whole file.
+ * A request cut short by the caller's abort keeps the last named value: it
+ * can only have slid the expiry by that one request's duration.
+ */
+class SessionExpiry {
+    constructor(known, report) {
+        this.known = known;
+        this.report = report;
+    }
+    /** Forge answered (or did not): the expiry is what the answer names. */
+    read(answer) {
+        this.become(parseUploadExpires(answer.header(UPLOAD_EXPIRES_HEADER)));
+    }
+    /**
+     * A request the OS carries on without JS is about to leave: it may commit
+     * chunks, each sliding the expiry, whose answers this upload never reads,
+     * possibly while the app is not running.
+     */
+    forget() {
+        this.become(null);
+    }
+    become(expiresAt) {
+        if (expiresAt === this.known)
+            return;
+        this.known = expiresAt;
+        this.report?.(expiresAt);
+    }
+}
+/** A backoff the caller's abort cuts short: resolves after `ms`, rejects as cancelled the moment the signal fires. */
+function abortableDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(cancelledError());
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(cancelledError());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Resolve once the device is back online; reject as cancelled the moment the
+ * caller aborts, the wait's only other end.
+ */
+function waitUntilOnline(connectivity, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let unsubscribe = null;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubscribe?.();
+            signal?.removeEventListener('abort', onAbort);
+            outcome();
+        };
+        const onAbort = () => settle(() => reject(cancelledError()));
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        unsubscribe = connectivity.onOnline(() => settle(resolve));
+        if (settled) {
+            // The listener fired inside the subscribe, before its unsubscribe existed.
+            unsubscribe();
+        }
+        else if (connectivity.isOnline()) {
+            // The network came back between the caller's check and the subscribe,
+            // so its event would never arrive.
+            settle(resolve);
+        }
     });
 }
 /**
@@ -156,6 +368,28 @@ async function tusRequest(config, url, init, label, context = {}) {
         throw new TusUploadError(`${label} failed: ${getErrorMessage(err)}`, { cause, ...context, phase: 'network' });
     }
 }
+/**
+ * Send a tus request through `tusRequest` and resolve with its answer: a
+ * response of any status, or no answer (a network failure or a timeout, as
+ * `tusRequest` classified it). The caller's abort and an SDK error still
+ * throw, because no retry follows either.
+ */
+async function fetchAnswer(config, url, init, label, context) {
+    let response;
+    try {
+        response = await tusRequest(config, url, init, label, context);
+    }
+    catch (err) {
+        if (err instanceof TusUploadError && (err.phase === 'network' || err.phase === 'timeout')) {
+            return noAnswer(err);
+        }
+        throw err;
+    }
+    if (response.status === 0) {
+        return noAnswer(new TusUploadError(`${label} got no answer`, { ...context, phase: 'network' }));
+    }
+    return answerOf(response.status, name => response.headers.get(name), response.ok ? '' : await response.text().catch(() => ''));
+}
 /**
  * Case-insensitive header lookup for adapter results. Native HTTP stacks
  * hand headers back in whatever case they please (iOS lower-cases them),
@@ -179,50 +413,27 @@ function resolveSessionSource(options, allowedHostPatterns) {
         if (!istk) {
             throw new SparkVaultValidationError('resume.istk or forgeUrl is required to resume a TUS upload session');
         }
-        return { mode: 'resume', uploadUrl, istk };
+        const expiresAt = options.resume.expiresAt ?? null;
+        if (expiresAt !== null && !Number.isFinite(expiresAt)) {
+            throw new SparkVaultValidationError('resume.expiresAt is an epoch-ms expiry or null', { received: expiresAt });
+        }
+        return { mode: 'resume', uploadUrl, istk, expiresAt };
     }
     if (!options.forgeUrl) {
         throw new SparkVaultValidationError('forgeUrl is required to create a TUS upload session');
     }
     return { mode: 'create', parsed: parseForgeUrl(options.forgeUrl, allowedHostPatterns) };
 }
-async function createTusUpload(config, parsed, fileSize, filename, signal) {
-    ensureNotAborted(signal);
-    // Forge's create contract is these three headers: the ingot's name and type
-    // were set by Core when the ingot was created, and Forge publishes Core's.
-    const response = await tusRequest(config, parsed.tusEndpoint, {
-        method: 'POST',
-        headers: {
-            'Tus-Resumable': TUS_VERSION,
-            'Upload-Length': String(fileSize),
-            'X-ISTK': parsed.istk,
-        },
-        signal,
-        timeoutMs: config.tusPostTimeoutMs,
-    }, 'TUS POST request', { filename, fileSize });
-    if (!response.ok) {
-        const errorText = await response.text().catch(() => '');
-        // A 402 here is a billable gate hit mid-create (e.g. storage/bandwidth pool
-        // exhausted). Route it through the same typed-gate mapping as the JSON HTTP
-        // path so callers handle subscribe / add-on UX off one set of error types.
-        const gateError = gateErrorFromBody(response.status, parseErrorBody(errorText));
-        if (gateError) {
-            throw gateError;
-        }
-        throw new TusUploadError(`TUS create failed: ${response.status} - ${errorText}`, {
-            httpStatus: response.status,
-            filename,
-            fileSize,
-            phase: 'create',
-        });
-    }
-    // Every chunk carries the file's bytes, so the session must live under the
-    // endpoint it was created at.
-    const uploadUrl = resolveForgeSessionUrl(response.headers.get('Location'), parsed.tusEndpoint);
+/**
+ * The session a create's 2xx opened: where it lives, its chunk geometry and
+ * its expiry. Every chunk carries the file's bytes, so the session must live
+ * under the endpoint it was created at.
+ */
+function readCreatedSession(answer, endpoint, context) {
+    const uploadUrl = resolveForgeSessionUrl(answer.header('Location'), endpoint);
     if (!uploadUrl) {
         throw new TusUploadError('TUS create response Location header is missing or outside the upload endpoint', {
-            filename,
-            fileSize,
+            ...context,
             phase: 'create',
         });
     }
@@ -230,111 +441,46 @@ async function createTusUpload(config, parsed, fileSize, filename, signal) {
     // that is not exactly the negotiated size, so the chunk size is the server's
     // to dictate via `X-Chunk-Size` (mirrors sdk-js). A client-side guess could
     // only ever be rejected, so a missing header is a contract violation.
-    const chunkSizeHeader = response.headers.get('X-Chunk-Size');
+    const chunkSizeHeader = answer.header('X-Chunk-Size');
     const chunkSize = parseIntegerHeader(chunkSizeHeader, 1);
     if (chunkSize === null) {
         throw new TusUploadError(`TUS create response missing or invalid X-Chunk-Size header (received ${JSON.stringify(chunkSizeHeader)})`, {
-            filename,
-            fileSize,
+            ...context,
             phase: 'create',
         });
     }
-    return { uploadUrl, chunkSize };
+    return { uploadUrl, chunkSize, expiresAt: parseUploadExpires(answer.header(UPLOAD_EXPIRES_HEADER)) };
 }
 /**
- * Ask Forge where a session stands (tus HEAD). This is the only way to learn
- * what a background URLSession delivered after the process was killed, and
- * what a failed attempt left behind — so resume never re-sends bytes the
- * server holds. A status `isSessionGone` recognises means the session
- * expired or was terminated: the error carries `sessionLost` so the caller
- * drops its persisted session and creates a fresh one rather than retrying
- * a dead URL. Any other failure (a 5xx, an auth rejection, a timeout)
- * leaves `sessionLost` false: the
- * session may well be intact, and treating it as dead would re-upload a
- * whole file over a blip.
+ * Where a HEAD's 2xx says the session stands: offset, length and chunk
+ * geometry, all required (a 2xx without them is not Forge, a captive
+ * portal's page being the classic case), and the expiry when named. An
+ * offset past the length can only be a corrupt session.
  */
-async function headTusSession(config, uploadUrl, istk, signal, context = {}) {
-    ensureNotAborted(signal);
-    const response = await tusRequest(config, uploadUrl, {
-        method: 'HEAD',
-        headers: {
-            'Tus-Resumable': TUS_VERSION,
-            'X-ISTK': istk,
-        },
-        signal,
-        timeoutMs: config.tusPostTimeoutMs,
-    }, 'TUS HEAD request', context);
-    if (isSessionGone(response.status)) {
-        throw sessionLostError(response.status, context, 'create');
-    }
-    if (!response.ok) {
-        const errorText = await response.text().catch(() => '');
-        const gateError = gateErrorFromBody(response.status, parseErrorBody(errorText));
-        if (gateError) {
-            throw gateError;
-        }
-        throw new TusUploadError(`TUS HEAD failed: ${response.status} - ${errorText}`, {
-            httpStatus: response.status,
-            ...context,
-            phase: 'create',
-        });
-    }
-    const offset = parseIntegerHeader(response.headers.get('Upload-Offset'), 0);
-    const length = parseIntegerHeader(response.headers.get('Upload-Length'), 0);
-    const chunkSize = parseIntegerHeader(response.headers.get('X-Chunk-Size'), 1);
+function readSessionProbe(answer, phase, context) {
+    const offset = parseIntegerHeader(answer.header('Upload-Offset'), 0);
+    const length = parseIntegerHeader(answer.header('Upload-Length'), 0);
+    const chunkSize = parseIntegerHeader(answer.header('X-Chunk-Size'), 1);
     if (offset === null || length === null || chunkSize === null || offset > length) {
-        throw new TusUploadError('TUS HEAD response missing or invalid Upload-Offset / Upload-Length / X-Chunk-Size headers', { ...context, phase: 'create' });
+        throw new TusUploadError('TUS HEAD response missing or invalid Upload-Offset / Upload-Length / X-Chunk-Size headers', { ...context, phase });
     }
-    return { offset, length, chunkSize };
+    return { offset, length, chunkSize, expiresAt: parseUploadExpires(answer.header(UPLOAD_EXPIRES_HEADER)) };
 }
 /**
- * Confirm finalization of a session Forge already holds every byte of: a
- * zero-length PATCH at `Upload-Offset: fileSize`. Forge treats any PATCH at
- * or past the declared size as "finalize (again) and acknowledge" - it
- * re-runs a finalization that failed transiently after the last chunk
- * (Core/DynamoDB/billing), and answers 204 for one that already completed.
- * Without this a resume that finds the transfer complete would skip straight
- * to the status poll and could report a never-activated ingot as done.
- *
- * 409 means another finalizer holds the lease right now: retry later, the
- * session is intact. A status `isSessionGone` recognises means the session
- * is gone (`sessionLost`).
+ * A session offset the server named (a HEAD's, or a 409's `Upload-Offset`),
+ * checked before anything is sent from it: Forge commits whole chunks, so a
+ * session stands at a chunk boundary or at the total, never past it, and an
+ * answer that says otherwise is not one to resume from.
  */
-async function confirmTusFinalization(config, uploadUrl, istk, fileSize, signal, context = {}) {
-    ensureNotAborted(signal);
-    const response = await tusRequest(config, uploadUrl, {
-        method: 'PATCH',
-        headers: {
-            'Tus-Resumable': TUS_VERSION,
-            'Upload-Offset': String(fileSize),
-            'Content-Type': 'application/offset+octet-stream',
-            'X-ISTK': istk,
-        },
-        signal,
-        timeoutMs: config.tusChunkTimeoutMs,
-    }, 'TUS finalization request', context);
-    if (isSessionGone(response.status)) {
-        throw sessionLostError(response.status, context, 'create');
-    }
-    if (response.status === 409) {
-        throw new TusUploadError('TUS finalization is already in progress on the server; retry shortly', {
-            httpStatus: 409,
+function checkedServerOffset(offset, geometry, phase, context) {
+    const problem = resumeOffsetProblem(offset, { totalSize: geometry.fileSize, chunkSize: geometry.chunkSize });
+    if (offset === null || problem !== null) {
+        throw new TusUploadError(`Forge named an upload offset this upload cannot continue from (${offset}: ${problem})`, {
             ...context,
-            phase: 'upload',
-        });
-    }
-    if (!response.ok) {
-        const errorText = await response.text().catch(() => '');
-        const gateError = gateErrorFromBody(response.status, parseErrorBody(errorText));
-        if (gateError) {
-            throw gateError;
-        }
-        throw new TusUploadError(`TUS finalization failed: ${response.status} - ${errorText.substring(0, 200)}`, {
-            httpStatus: response.status,
-            ...context,
-            phase: 'upload',
+            phase,
         });
     }
+    return offset;
 }
 /**
  * Hard ceiling on a single chunk PATCH regardless of progress. The stall
@@ -343,18 +489,23 @@ async function confirmTusFinalization(config, uploadUrl, istk, fileSize, signal,
  */
 const CHUNK_ABSOLUTE_CAP_MS = 60 * 60000;
 /**
- * PATCH one chunk. `stallTimeoutMs` is a STALL watchdog, not a deadline: it
- * fires only when no upload progress (and no response) arrives for that long.
- * Forge fixes non-final chunks at 50 MB and the client cannot shrink them, so
- * an absolute per-request timeout would kill every legitimately slow uplink
- * (a 50 MB chunk needs ~3.5 Mbps sustained to beat 120 s) and restart the
- * file from byte 0. The final PATCH also waits for Forge to finalize after the
- * last byte is sent; a progress-based watchdog gives that the same patience.
+ * PATCH one chunk over XHR and resolve with Forge's answer, or with no answer
+ * when the connection drops, the request times out or the chunk stalls. Only
+ * the caller's abort rejects. `stallTimeoutMs` is a STALL watchdog, not a
+ * deadline: it fires only when no upload progress (and no response) arrives
+ * for that long. Forge fixes non-final chunks at 50 MB and the client cannot
+ * shrink them, so an absolute per-request timeout would kill every
+ * legitimately slow uplink (a 50 MB chunk needs ~3.5 Mbps sustained to beat
+ * 120 s). The final PATCH also waits for Forge to finalize after the last
+ * byte is sent; a progress-based watchdog gives that the same patience.
+ * Bytes leaving are a sign of life: they restart the transfer's idle clock
+ * (never its failure count, which only the server's confirmation resets).
  */
-function uploadChunk(uploadUrl, istk, chunk, offset, stallTimeoutMs, signal, onChunkProgress) {
+function sendChunkOverXhr(transfer, chunk, offset, stallTimeoutMs, onChunkProgress) {
     if (typeof XMLHttpRequest === 'undefined') {
         throw new SparkVaultValidationError('XMLHttpRequest is required for mobile TUS uploads');
     }
+    const { uploadUrl, istk, signal, context } = transfer;
     return new Promise((resolve, reject) => {
         const xhr = new XMLHttpRequest();
         let settled = false;
@@ -376,17 +527,18 @@ function uploadChunk(uploadUrl, istk, chunk, offset, stallTimeoutMs, signal, onC
         };
         const abort = () => {
             xhr.abort();
-            finish(() => reject(new TusUploadError('Upload cancelled', { phase: 'cancelled' })));
+            finish(() => reject(cancelledError()));
         };
         if (signal?.aborted) {
             abort();
             return;
         }
         signal?.addEventListener('abort', abort, { once: true });
+        const unanswered = (message, phase) => finish(() => resolve(noAnswer(new TusUploadError(message, { ...context, phase }))));
         // Settle BEFORE aborting: the abort handler below would otherwise report
         // the stall as a user cancellation.
         const stall = (message) => {
-            finish(() => reject(new TusUploadError(message, { phase: 'timeout' })));
+            unanswered(message, 'timeout');
             xhr.abort();
         };
         const armWatchdog = () => {
@@ -396,37 +548,22 @@ function uploadChunk(uploadUrl, istk, chunk, offset, stallTimeoutMs, signal, onC
         };
         xhr.upload.onprogress = event => {
             armWatchdog();
+            transfer.budget.alive();
             if (event.lengthComputable) {
                 onChunkProgress?.(event.loaded);
             }
         };
         xhr.onload = () => {
-            if (xhr.status >= 200 && xhr.status < 300) {
-                // Forge answers every PATCH with Upload-Offset, so a 2xx without a
-                // readable one is not Forge (a captive portal's 200 page is the
-                // classic case): report no advance and let the stall guard fail the
-                // attempt, rather than crediting bytes that may never have arrived.
-                // parseInt would also turn a garbage header into NaN, which slips
-                // through that guard (every comparison with NaN is false) and ends
-                // the upload loop as a success.
-                const newOffset = parseIntegerHeader(xhr.getResponseHeader('Upload-Offset'), 0) ?? offset;
-                finish(() => resolve(newOffset));
-            }
-            else {
-                const gateError = gateErrorFromBody(xhr.status, parseErrorBody(xhr.responseText));
-                if (gateError) {
-                    finish(() => reject(gateError));
-                    return;
-                }
-                finish(() => reject(new TusUploadError(`Chunk upload failed: ${xhr.status} - ${xhr.responseText.substring(0, 200)}`, {
-                    httpStatus: xhr.status,
-                    phase: 'upload',
-                })));
+            if (xhr.status === 0) {
+                unanswered('Chunk upload got no answer', 'network');
+                return;
             }
+            const answered = xhr.status >= 200 && xhr.status < 300;
+            finish(() => resolve(answerOf(xhr.status, name => xhr.getResponseHeader(name), answered ? '' : xhr.responseText)));
         };
-        xhr.onerror = () => finish(() => reject(new TusUploadError('Chunk upload network error', { phase: 'network' })));
-        xhr.onabort = () => finish(() => reject(new TusUploadError('Chunk upload aborted', { phase: 'cancelled' })));
-        xhr.ontimeout = () => finish(() => reject(new TusUploadError('Chunk upload timed out', { phase: 'timeout' })));
+        xhr.onerror = () => unanswered('Chunk upload network error', 'network');
+        xhr.onabort = () => finish(() => reject(new TusUploadError('Chunk upload aborted', { ...context, phase: 'cancelled' })));
+        xhr.ontimeout = () => unanswered('Chunk upload timed out', 'timeout');
         xhr.open('PATCH', uploadUrl);
         xhr.setRequestHeader('Tus-Resumable', TUS_VERSION);
         xhr.setRequestHeader('Upload-Offset', String(offset));
@@ -443,56 +580,50 @@ function uploadChunk(uploadUrl, istk, chunk, offset, stallTimeoutMs, signal, onC
 }
 /**
  * PATCH a whole file as the session's only chunk on the app's background
- * URLSession. The OS owns the transfer, so it finishes even if iOS suspends
- * the app; the trade is no progress events and no abort. The result is mapped
- * exactly like the XHR path so callers see one error taxonomy.
+ * URLSession and resolve with Forge's answer, or with no answer when the
+ * adapter got none. The OS owns the transfer, so it finishes even if iOS
+ * suspends the app; the trade is no progress events and no abort. Its answer
+ * is read exactly like the XHR path's, so callers see one error taxonomy.
  */
-async function uploadWholeFileInBackground(uploader, uploadUrl, istk, fileUri, offset) {
+async function sendWholeFileInBackground(uploader, transfer, fileUri, offset) {
     let result;
     try {
-        result = await uploader.uploadFile(uploadUrl, fileUri, {
+        result = await uploader.uploadFile(transfer.uploadUrl, fileUri, {
             method: 'PATCH',
             headers: {
                 'Tus-Resumable': TUS_VERSION,
                 'Upload-Offset': String(offset),
                 'Content-Type': 'application/offset+octet-stream',
-                'X-ISTK': istk,
+                'X-ISTK': transfer.istk,
             },
         });
     }
     catch (err) {
         // The adapter only throws when no HTTP response came back (offline, DNS,
         // the OS cancelled the task); an HTTP failure is a status below.
-        throw new TusUploadError(`Background chunk upload failed: ${getErrorMessage(err)}`, {
+        return noAnswer(new TusUploadError(`Background chunk upload failed: ${getErrorMessage(err)}`, {
             cause: err instanceof Error ? err : null,
+            ...transfer.context,
             phase: 'network',
-        });
+        }));
     }
-    const body = typeof result.body === 'string' ? result.body : '';
-    if (result.status >= 200 && result.status < 300) {
-        // Forge always answers a PATCH with a readable Upload-Offset. A 2xx
-        // without one is not Forge (a captive portal's 200 page is the classic
-        // case), so report no advance: the stall guard fails the attempt and the
-        // next one asks Forge (HEAD) instead of marking bytes uploaded that may
-        // never have arrived. Same strict parse as the XHR path (uploadChunk).
-        return parseIntegerHeader(getHeaderIgnoreCase(result.headers, 'Upload-Offset'), 0) ?? offset;
-    }
-    const gateError = gateErrorFromBody(result.status, parseErrorBody(body));
-    if (gateError) {
-        throw gateError;
-    }
-    throw new TusUploadError(`Chunk upload failed: ${result.status} - ${body.substring(0, 200)}`, {
-        httpStatus: result.status,
-        phase: 'upload',
-    });
+    if (!Number.isSafeInteger(result.status) || result.status <= 0) {
+        return noAnswer(new TusUploadError(`Background chunk upload got no answer (status ${String(result.status)})`, {
+            ...transfer.context,
+            phase: 'network',
+        }));
+    }
+    const answered = result.status >= 200 && result.status < 300;
+    return answerOf(result.status, name => getHeaderIgnoreCase(result.headers, name), !answered && typeof result.body === 'string' ? result.body : '');
 }
 /**
  * Translate what the OS transfer adapter reports into the SDK's one error
  * taxonomy, so a caller sees the same `TusUploadError` phases and typed gate
  * errors whichever engine carried the bytes. Forge's status and body ride
- * through untouched: a 402 becomes the gate error the XHR path throws, a
- * status `isSessionGone` recognises marks the session lost exactly as HEAD
- * would, and any other status keeps its number for the caller's own policy
+ * through untouched: the refusal Core decided is `upload_refused` in Core's
+ * words as on the XHR path, a 402 becomes the gate error the XHR path
+ * throws, a status `isSessionGone` recognises marks the session lost exactly
+ * as HEAD would, and any other status keeps its number for the caller's own policy
  * (a 409 during finalize is a retry-later, not a lost session). The
  * remaining kinds are transport
  * outcomes: the caller's own abort is `cancelled`; an OS-ended task
@@ -514,11 +645,19 @@ export function mapBackgroundTransferError(err, context = {}) {
             const status = err.httpStatus;
             const body = err.body ?? '';
             if (status !== undefined) {
-                const gateError = gateErrorFromBody(status, parseErrorBody(body));
+                const envelope = parseErrorBody(body);
+                const outcome = Number.isSafeInteger(status) && status > 0
+                    ? classifyTransferResponse({ status, details: envelope.error?.details ?? null })
+                    : null;
+                if (outcome?.verdict === TRANSFER_VERDICT.REFUSED && outcome.coreCode !== null) {
+                    return refusedError(status, envelope, outcome.coreCode, context, 'upload', err);
+                }
+                const gateError = gateErrorFromBody(status, envelope);
                 if (gateError)
                     return gateError;
-                if (isSessionGone(status))
-                    return sessionLostError(status, context, 'upload', err);
+                if (outcome?.verdict === TRANSFER_VERDICT.GONE) {
+                    return sessionLostError(status, context, 'upload', err, outcome.coreCode);
+                }
             }
             return new TusUploadError(`Background chunk upload failed: ${status ?? 'unknown status'} - ${body.substring(0, 200)}`, { cause: err, httpStatus: status ?? null, ...context, phase: 'upload' });
         }
@@ -571,6 +710,29 @@ export class MobileTusUploader {
     constructor(config) {
         this.config = config;
     }
+    /**
+     * Upload a file over tus: create the session (or resume a kept one), send
+     * the bytes Forge does not hold, and resolve once Forge has confirmed the
+     * ingot published.
+     *
+     * Every answer is read through the platform's transfer policy
+     * (`@sparkvault/app-sdk/transfer-retry`), and one budget per call bounds
+     * every retry, the create's included: a request that got no answer, 408,
+     * 425, 429, a 5xx or a lease-held 409 waits its backoff (never shorter than
+     * `Retry-After`), then asks Forge where the session stands (HEAD) and sends
+     * from there; a 409 carrying `Upload-Offset` continues from that offset at
+     * once; a receipt Forge defers (503 with `Retry-After`) is asked again,
+     * each time after a longer backoff, without spending a failure until the
+     * idle limit ends the upload as `upload_received_publishing`
+     * (`retryLater`); a gone session is `sessionLost` (`coreCode` naming the
+     * code Core ended it with, when the answer named one); a final refusal of
+     * Core's (`UPLOAD_POOL_FULL`, `UPLOAD_SUPERSEDED`) is `upload_refused` in
+     * Core's words (`coreCode`); any other 4xx ends the upload with the
+     * server's answer. No chunk is ever sent at an offset the server did not just name. While the device is offline (`isOnline`), a request that got
+     * no answer spends nothing: the upload waits for the network. The OS
+     * transfer engine's range is the exception: the engine chains its own
+     * requests, and its failure ends the call for the caller's own retry.
+     */
     async uploadFromUri(options) {
         const fileReader = this.config.fileReader;
         if (!fileReader) {
@@ -580,52 +742,65 @@ export class MobileTusUploader {
         const istk = source.mode === 'create' ? source.parsed.istk : source.istk;
         const debug = options.debug;
         const cleanUri = options.fileUri.split('#')[0];
-        let bytesUploaded = 0;
+        const signal = options.abortSignal;
+        const fileSize = options.fileSize;
+        const context = { filename: options.filename, fileSize };
+        const budget = createTransferBudget();
         // Known up front on resume so a cancel during the HEAD still terminates
         // the (existing) session.
         let uploadUrl = source.mode === 'resume' ? source.uploadUrl : null;
+        // The last offset the caller heard, so the end of the upload reports 100%
+        // exactly once however the last byte was confirmed.
+        let reported = null;
+        const report = (uploaded) => {
+            reported = uploaded;
+            options.onProgress?.(uploaded, fileSize);
+        };
         try {
-            let chunkSize;
-            let sessionUrl;
+            let transfer;
+            let position;
             if (source.mode === 'resume') {
-                sessionUrl = source.uploadUrl;
                 debug?.log(`Resuming TUS upload for ${options.filename}`);
-                const probe = await headTusSession(this.config, source.uploadUrl, istk, options.abortSignal, {
-                    filename: options.filename,
-                    fileSize: options.fileSize,
-                });
-                // A session is bound to one file: a different length means the
-                // persisted session belongs to another file (or this file changed),
-                // and PATCHing into it would corrupt the ingot. That makes the
-                // session worthless for this file, which is exactly what
-                // `sessionLost` means: the caller drops it and starts fresh, the same
-                // as for a 404/410, instead of retrying a resume that can never work.
-                if (probe.length !== options.fileSize) {
-                    throw new TusUploadError(`TUS session Upload-Length (${probe.length}) does not match the file size (${options.fileSize}); the session belongs to a different file`, { filename: options.filename, fileSize: options.fileSize, phase: 'create', sessionLost: true });
-                }
-                chunkSize = probe.chunkSize;
-                bytesUploaded = probe.offset;
-                debug?.log(`TUS session for ${options.filename} is at offset ${bytesUploaded}/${options.fileSize}`);
-                if (bytesUploaded >= options.fileSize) {
-                    // Every byte is there, but the finalization the last chunk should
-                    // have triggered may not have happened (that is often why the
-                    // previous attempt failed): ask Forge to finalize and acknowledge.
-                    await confirmTusFinalization(this.config, sessionUrl, istk, options.fileSize, options.abortSignal, {
-                        filename: options.filename,
-                        fileSize: options.fileSize,
+                // A session past the expiry Forge named for it is gone: Forge refuses
+                // every request to it, so asking would only spend one to learn that.
+                const heldExpiry = source.expiresAt;
+                if (heldExpiry !== null && isSessionExpired(heldExpiry)) {
+                    throw new TusUploadError(`TUS session expired at ${new Date(heldExpiry).toISOString()}`, {
+                        ...context,
+                        phase: 'create',
+                        sessionLost: true,
                     });
-                    options.onProgress?.(bytesUploaded, options.fileSize);
                 }
+                const expiry = new SessionExpiry(source.expiresAt, options.onSessionExpiry);
+                const link = { uploadUrl: source.uploadUrl, istk, context, expiry, signal };
+                const probe = await this.readResumePoint(link, budget, fileSize);
+                transfer = { ...link, expiry, fileSize, chunkSize: probe.chunkSize, budget };
+                position = { offset: checkedServerOffset(probe.offset, transfer, 'create', context), published: false };
+                debug?.log(`TUS session for ${options.filename} is at offset ${position.offset}/${fileSize}`);
             }
             else {
                 debug?.log(`Starting TUS upload for ${options.filename}`);
-                const created = await createTusUpload(this.config, source.parsed, options.fileSize, options.filename, options.abortSignal);
-                sessionUrl = created.uploadUrl;
-                uploadUrl = sessionUrl;
-                chunkSize = created.chunkSize;
+                const created = await this.createSession(source.parsed, fileSize, budget, context, signal);
+                uploadUrl = created.uploadUrl;
+                transfer = {
+                    uploadUrl: created.uploadUrl,
+                    istk,
+                    context,
+                    expiry: new SessionExpiry(created.expiresAt, options.onSessionExpiry),
+                    signal,
+                    fileSize,
+                    chunkSize: created.chunkSize,
+                    budget,
+                };
+                position = { offset: 0, published: false };
                 // Before the first PATCH: once bytes are in flight the session is
                 // worth resuming, so the caller must already hold it.
-                options.onSessionCreated?.({ uploadUrl: sessionUrl, istk, chunkSize });
+                options.onSessionCreated?.({
+                    uploadUrl: created.uploadUrl,
+                    istk,
+                    chunkSize: created.chunkSize,
+                    expiresAt: created.expiresAt,
+                });
             }
             // The OS transfer engine, when the app provides one, takes the whole
             // remaining range in a single hand-off: it chains the chunks itself and
@@ -636,65 +811,53 @@ export class MobileTusUploader {
             // that resumes the same session re-joins the job the OS is still
             // running instead of PATCHing over it.
             const backgroundTransfer = options.transport === 'background' ? this.config.backgroundTransfer : undefined;
-            if (backgroundTransfer && bytesUploaded < options.fileSize) {
-                ensureNotAborted(options.abortSignal);
+            if (backgroundTransfer && position.offset < fileSize) {
+                ensureNotAborted(signal);
+                transfer.expiry.forget();
                 const policy = options.transferPolicy ?? {};
                 const finalOffset = await transferRemainderInBackground(backgroundTransfer, {
-                    uploadUrl: sessionUrl,
+                    uploadUrl: transfer.uploadUrl,
                     istk,
                     fileUri: cleanUri,
-                    fileSize: options.fileSize,
-                    chunkSize,
-                    offset: bytesUploaded,
+                    fileSize,
+                    chunkSize: transfer.chunkSize,
+                    offset: position.offset,
                     allowsCellularAccess: policy.allowsCellularAccess ?? true,
                     allowsConstrainedNetworkAccess: policy.allowsConstrainedNetworkAccess ?? true,
-                }, { filename: options.filename, abortSignal: options.abortSignal, onProgress: options.onProgress });
+                }, { filename: options.filename, abortSignal: signal, onProgress: offset => report(offset) });
                 // The engine only resolves at the end of the file; anything else is
                 // an engine that gave up quietly, and an offset past the file is as
                 // untrustworthy as one short of it. Same treatment as a non-advancing
                 // PATCH: fail, and let the next attempt ask Forge (HEAD) where the
                 // session really stands.
-                if (finalOffset !== options.fileSize) {
-                    throw new TusUploadError(`Upload stalled: background transfer ended at offset ${finalOffset} of ${options.fileSize}`, { phase: 'stalled', filename: options.filename, fileSize: options.fileSize });
+                if (finalOffset !== fileSize) {
+                    throw new TusUploadError(`Upload stalled: background transfer ended at offset ${finalOffset} of ${fileSize}`, { ...context, phase: 'stalled' });
                 }
-                // An abort that lands after the OS delivered the last byte changes
-                // nothing: the transfer is complete, and the loop below (with its
-                // abort check) has nothing left to do. Same rule as the single-chunk
-                // adapter: a finished upload is never reported as cancelled.
-                bytesUploaded = finalOffset;
-                options.onProgress?.(bytesUploaded, options.fileSize);
+                // The engine's last PATCH was answered 2xx at the final offset, which
+                // Forge answers only once the ingot is published. An abort that lands
+                // after the OS delivered the last byte changes nothing: the transfer
+                // is complete, and the loop below (with its abort check) has nothing
+                // left to do. Same rule as the single-chunk adapter: a finished
+                // upload is never reported as cancelled.
+                position = { offset: fileSize, published: true };
             }
-            while (bytesUploaded < options.fileSize) {
-                ensureNotAborted(options.abortSignal);
-                const chunkStart = bytesUploaded;
-                const chunkLength = Math.min(chunkSize, options.fileSize - chunkStart);
-                let newOffset;
-                const backgroundUploader = options.transport === 'background' ? this.config.backgroundUploader : undefined;
-                if (backgroundUploader && this.fitsOneBackgroundRequest(chunkStart, options.fileSize, chunkSize)) {
-                    // The OS owns this request, so an abort that fires while it is in
-                    // flight cannot stop it. It only ever carries a whole single-chunk
-                    // file, so a 2xx here means the transfer is complete: the loop
-                    // ends and the upload finishes normally (the caller verifies the
-                    // ingot), because a finished upload must never be reported as
-                    // cancelled, and a DELETE now would drop bytes Forge has already
-                    // finalized. Only a response that leaves bytes missing reaches
-                    // the `ensureNotAborted` at the top of the next iteration.
-                    newOffset = await uploadWholeFileInBackground(backgroundUploader, sessionUrl, istk, cleanUri, chunkStart);
-                }
-                else {
-                    const chunk = await this.readChunk(fileReader, cleanUri, chunkStart, chunkLength);
-                    newOffset = await uploadChunk(sessionUrl, istk, chunk, chunkStart, this.config.tusChunkTimeoutMs, options.abortSignal, chunkUploaded => options.onProgress?.(chunkStart + chunkUploaded, options.fileSize));
-                }
-                if (newOffset <= chunkStart || newOffset > options.fileSize) {
-                    throw new TusUploadError('Upload stalled: server offset did not advance', {
-                        phase: 'stalled',
-                        filename: options.filename,
-                        fileSize: options.fileSize,
-                    });
-                }
-                bytesUploaded = newOffset;
-                options.onProgress?.(bytesUploaded, options.fileSize);
+            const chunks = {
+                reader: fileReader,
+                uri: cleanUri,
+                transport: options.transport,
+                onChunkProgress: (offset, chunkBytesUploaded) => report(offset + chunkBytesUploaded),
+            };
+            while (!position.published) {
+                ensureNotAborted(signal);
+                const before = position.offset;
+                position = position.offset < fileSize
+                    ? await this.sendChunkAt(transfer, position.offset, chunks)
+                    : await this.confirmReceipt(transfer);
+                if (position.offset > before)
+                    report(position.offset);
             }
+            if (reported !== fileSize)
+                report(fileSize);
             debug?.success(`TUS upload completed for ${options.filename}`);
         }
         catch (err) {
@@ -723,39 +886,314 @@ export class MobileTusUploader {
             // in a generic TusUploadError.
             if (err instanceof SparkVaultMobileError)
                 throw err;
-            // Only a fileReader read or an onSessionCreated hook can throw anything
-            // else here: every request classifies its own failure (tusRequest,
-            // uploadChunk, the adapters). Those are the caller's errors, wrapped
-            // with the file context and nothing inferred about them.
+            // Only a fileReader read or a caller's hook (onSessionCreated,
+            // onSessionExpiry, onProgress) can throw anything else here: every
+            // request classifies its own failure (tusRequest, the chunk senders,
+            // the adapters). Those are the caller's errors, wrapped with the file
+            // context and nothing inferred about them.
             throw TusUploadError.fromError(error, {
                 filename: options.filename,
                 fileSize: options.fileSize,
             });
         }
     }
+    /**
+     * Open the upload's session. A create the transfer policy calls RETRY (no
+     * answer, 408, 425, 429, a 5xx) is sent again under the upload's budget,
+     * its backoff never shorter than `Retry-After`: Forge refuses such a create
+     * before it claims the token, or hands the claim back on a transient
+     * key-service failure (503), so the same ISTK opens the session on a later
+     * attempt. Every other answer is final and never a lost session, a 401
+     * included: the token was already used, by an earlier create whose answer
+     * was lost, and no Location survives to continue that session from. No
+     * session URL exists yet to spread the retries by, and the ISTK never feeds
+     * one, so they spread by a key of the endpoint (`transferJitterKey`).
+     */
+    async createSession(parsed, fileSize, budget, context, signal) {
+        const jitterKey = transferJitterKey(parsed.tusEndpoint);
+        for (;;) {
+            ensureNotAborted(signal);
+            // Forge's create contract is these three headers: the ingot's name and
+            // type were set by Core when the ingot was created, and Forge publishes
+            // Core's.
+            const answer = await fetchAnswer(this.config, parsed.tusEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Tus-Resumable': TUS_VERSION,
+                    'Upload-Length': String(fileSize),
+                    'X-ISTK': parsed.istk,
+                },
+                signal,
+                timeoutMs: this.config.tusPostTimeoutMs,
+            }, 'TUS POST request', context);
+            const outcome = readOutcome(answer, CREATE_REQUEST);
+            if (outcome.verdict === TRANSFER_VERDICT.OK) {
+                const created = readCreatedSession(answer, parsed.tusEndpoint, context);
+                // The session exists: the server confirmed progress.
+                budget.progressed();
+                return created;
+            }
+            const failure = failureOf(answer, outcome, CREATE_REQUEST, context);
+            if (outcome.verdict !== TRANSFER_VERDICT.RETRY)
+                throw failure.error;
+            await this.waitToRetry(budget, failure, jitterKey, signal);
+        }
+    }
+    /**
+     * Where a kept session stands, asked of Forge (HEAD) under the upload's
+     * budget, so resume never re-sends bytes the server holds: it is the only
+     * way to learn what a background transfer delivered after the process was
+     * killed, and what a failed attempt left behind. A HEAD that gets no
+     * answer or a transient one is asked again after its backoff; a gone
+     * session is `sessionLost`, so the caller drops it and creates a fresh one
+     * rather than retrying a dead URL. A session is bound to one file: a length that
+     * is not this file's means the persisted session belongs to another file
+     * (or this file changed), and PATCHing into it would corrupt the ingot.
+     * That makes it as worthless as a gone one: `sessionLost` too.
+     */
+    async readResumePoint(link, budget, fileSize) {
+        for (;;) {
+            const head = await this.headSession(link, RESUME_HEAD_REQUEST);
+            if ('failure' in head) {
+                await this.waitToRetry(budget, head.failure, link.uploadUrl, link.signal);
+                continue;
+            }
+            if (head.probe.length !== fileSize) {
+                throw new TusUploadError(`TUS session Upload-Length (${head.probe.length}) does not match the file size (${fileSize}); the session belongs to a different file`, { ...link.context, phase: 'create', sessionLost: true });
+            }
+            return head.probe;
+        }
+    }
+    /**
+     * Ask Forge once where the session stands (tus HEAD): the probe on a 2xx,
+     * or the failure its answer amounts to. Forge re-drives a received
+     * upload's publication on its HEAD and answers the full offset whatever the
+     * re-drive came to, so an offset at the total proves receipt only: the
+     * receipt PATCH (`confirmReceipt`) is what says published.
+     */
+    async headSession(link, request) {
+        ensureNotAborted(link.signal);
+        const answer = await fetchAnswer(this.config, link.uploadUrl, {
+            method: 'HEAD',
+            headers: {
+                'Tus-Resumable': TUS_VERSION,
+                'X-ISTK': link.istk,
+            },
+            signal: link.signal,
+            timeoutMs: HEAD_AND_RECEIPT_TIMEOUT_MS,
+        }, 'TUS HEAD request', link.context);
+        link.expiry?.read(answer);
+        const outcome = readOutcome(answer, request);
+        if (outcome.verdict === TRANSFER_VERDICT.OK) {
+            return { probe: readSessionProbe(answer, request.phase, link.context) };
+        }
+        return { failure: failureOf(answer, outcome, request, link.context) };
+    }
+    /**
+     * Send the chunk that starts at `offset`. Answers where the upload stands
+     * next: past the chunk on its 2xx, which for the last chunk is also the
+     * publication receipt (Forge answers it only once the ingot is published),
+     * or wherever the server says after a failure.
+     */
+    async sendChunkAt(transfer, offset, chunks) {
+        const answer = await this.sendChunk(transfer, offset, chunks);
+        transfer.expiry.read(answer);
+        const outcome = readOutcome(answer, CHUNK_REQUEST);
+        if (outcome.verdict !== TRANSFER_VERDICT.OK) {
+            return this.positionAfterFailure(transfer, failureOf(answer, outcome, CHUNK_REQUEST, transfer.context), offset);
+        }
+        // Forge answers every PATCH with Upload-Offset, so a 2xx without a
+        // readable one is not Forge (a captive portal's 200 page is the classic
+        // case): it reports no advance, and the stall guard fails the attempt
+        // rather than crediting bytes that may never have arrived. The parse is
+        // strict because parseInt would turn a garbage header into NaN, which
+        // slips through the guard (every comparison with NaN is false) and would
+        // end the upload as a success; an offset past the file is as
+        // untrustworthy as one short of it.
+        const confirmed = parseIntegerHeader(answer.header('Upload-Offset'), 0) ?? offset;
+        if (confirmed <= offset || confirmed > transfer.fileSize) {
+            throw new TusUploadError('Upload stalled: server offset did not advance', {
+                ...transfer.context,
+                phase: 'stalled',
+            });
+        }
+        transfer.budget.progressed();
+        return { offset: confirmed, published: confirmed === transfer.fileSize };
+    }
+    /** PATCH the chunk at `offset` on the transport the upload rides, resolving with Forge's answer. */
+    async sendChunk(transfer, offset, chunks) {
+        const backgroundUploader = chunks.transport === 'background' ? this.config.backgroundUploader : undefined;
+        if (backgroundUploader && this.fitsOneBackgroundRequest(offset, transfer.fileSize, transfer.chunkSize)) {
+            // The OS owns this request, so an abort that fires while it is in
+            // flight cannot stop it, and it may finish while the app is away. It
+            // only ever carries a whole single-chunk file, so a 2xx here means the
+            // transfer is complete: the loop ends and the upload finishes normally
+            // (the caller verifies the ingot), because a finished upload must never
+            // be reported as cancelled, and a DELETE now would drop bytes Forge has
+            // already finalized. Only an answer that leaves bytes missing reaches
+            // the abort check before the next request.
+            transfer.expiry.forget();
+            return sendWholeFileInBackground(backgroundUploader, transfer, chunks.uri, offset);
+        }
+        const chunkLength = Math.min(transfer.chunkSize, transfer.fileSize - offset);
+        const chunk = await this.readChunk(chunks.reader, chunks.uri, offset, chunkLength);
+        return sendChunkOverXhr(transfer, chunk, offset, this.config.tusChunkTimeoutMs, chunkBytesUploaded => chunks.onChunkProgress(offset, chunkBytesUploaded));
+    }
+    /**
+     * Where the upload stands after a failed chunk PATCH, in the server's
+     * words: a 409's own `Upload-Offset` at once, otherwise the session's HEAD
+     * after the backoff, the HEAD itself retried the same way out of the same
+     * budget. A PATCH whose answer was lost may have landed, and one sent at a
+     * stale offset is refused, so no chunk is ever sent again at an offset the
+     * server did not just name.
+     */
+    async positionAfterFailure(transfer, failure, sentOffset) {
+        let current = failure;
+        for (;;) {
+            if (current.outcome.verdict === TRANSFER_VERDICT.RESYNC) {
+                return this.resyncedPosition(transfer, current, sentOffset);
+            }
+            await this.waitToRetry(transfer.budget, current, transfer.uploadUrl, transfer.signal);
+            const head = await this.headSession(transfer, OFFSET_HEAD_REQUEST);
+            if ('failure' in head) {
+                current = head.failure;
+                continue;
+            }
+            if (head.probe.length !== transfer.fileSize) {
+                throw new TusUploadError(`TUS session Upload-Length (${head.probe.length}) does not match the file size (${transfer.fileSize}); the session belongs to a different file`, { ...transfer.context, phase: 'upload', sessionLost: true });
+            }
+            const offset = checkedServerOffset(head.probe.offset, transfer, 'upload', transfer.context);
+            // Bytes reached the server despite the failure, so the transfer is
+            // alive: the budget starts over rather than being spent down across
+            // the many chunks of a large file.
+            if (offset > sentOffset)
+                transfer.budget.progressed();
+            return { offset, published: false };
+        }
+    }
+    /**
+     * Continue from the offset a 409 named, at once and without a HEAD: the
+     * server just said where the session stands. Past what this upload sent,
+     * the server holds more than it knew, which is progress; anywhere else the
+     * answer contradicts the request, so it spends the budget like any failure
+     * and repeating it ends the upload.
+     */
+    resyncedPosition(transfer, failure, sentOffset) {
+        const offset = checkedServerOffset(failure.outcome.offset, transfer, 'upload', transfer.context);
+        if (offset > sentOffset) {
+            transfer.budget.progressed();
+        }
+        else if (!transfer.budget.failed(TRANSFER_VERDICT.RESYNC)) {
+            throw failure.error;
+        }
+        return { offset, published: false };
+    }
+    /**
+     * Every byte is on the server but publication is unconfirmed: the final
+     * chunk's answer was lost or deferred, or a HEAD's offset proved receipt
+     * only. A zero-length PATCH at the final offset re-drives publication if it
+     * did not finish (a transient Core or billing failure after the last chunk)
+     * and answers 204 once the ingot is published, which is the receipt every
+     * upload resolves on. While another request finalizes it answers 409 with
+     * `Retry-After`, asked again as a failure; while the publication is
+     * deferred, 503 with `Retry-After`, asked again, each time after a longer
+     * backoff, without spending a failure until the idle limit ends the upload
+     * as `upload_received_publishing` (`retryLater`); a 503 naming no
+     * `Retry-After` is no deferral of Forge's, asked again as a failure. A 409
+     * naming an earlier offset means bytes are missing, and the upload
+     * continues from there. Forge answers it only after its own call to Core,
+     * so it waits `HEAD_AND_RECEIPT_TIMEOUT_MS`, as a HEAD does.
+     */
+    async confirmReceipt(transfer) {
+        ensureNotAborted(transfer.signal);
+        const answer = await fetchAnswer(this.config, transfer.uploadUrl, {
+            method: 'PATCH',
+            headers: {
+                'Tus-Resumable': TUS_VERSION,
+                'Upload-Offset': String(transfer.fileSize),
+                'Content-Type': 'application/offset+octet-stream',
+                'X-ISTK': transfer.istk,
+            },
+            signal: transfer.signal,
+            timeoutMs: HEAD_AND_RECEIPT_TIMEOUT_MS,
+        }, 'TUS finalization request', transfer.context);
+        transfer.expiry.read(answer);
+        const outcome = readOutcome(answer, RECEIPT_REQUEST);
+        if (outcome.verdict === TRANSFER_VERDICT.OK) {
+            return { offset: transfer.fileSize, published: true };
+        }
+        const failure = failureOf(answer, outcome, RECEIPT_REQUEST, transfer.context);
+        if (outcome.verdict === TRANSFER_VERDICT.RESYNC) {
+            return this.resyncedPosition(transfer, failure, transfer.fileSize);
+        }
+        await this.waitToRetry(transfer.budget, failure, transfer.uploadUrl, transfer.signal);
+        return { offset: transfer.fileSize, published: false };
+    }
+    /**
+     * Wait out the backoff of a failed request, spending a retry of the
+     * upload's budget, or of a deferred receipt, spending none for as long as
+     * the idle limit allows; never shorter than the answer's `Retry-After`.
+     * Throws the failure no retry follows (a gone session, the server's
+     * verdict), and the last one, or the deferral, once the budget is spent. A
+     * request that got no answer while the device is offline spends nothing:
+     * the upload waits for the network (or the caller's abort), the idle clock
+     * starts over when it is back, and the next request asks again at once.
+     */
+    async waitToRetry(budget, failure, jitterKey, signal) {
+        const { verdict, retryAfterMs } = failure.outcome;
+        if (verdict === TRANSFER_VERDICT.DEFERRED) {
+            if (!budget.deferred(retryAfterMs))
+                throw failure.error;
+            await abortableDelay(retryDelayMs({ attempt: budget.attempt, retryAfterMs, jitterKey }), signal);
+            return;
+        }
+        if (verdict !== TRANSFER_VERDICT.RETRY) {
+            throw failure.error;
+        }
+        const connectivity = this.config.connectivity;
+        if (failure.unanswered && connectivity && !connectivity.isOnline()) {
+            await waitUntilOnline(connectivity, signal);
+            budget.alive();
+            return;
+        }
+        if (!budget.failed(verdict, retryAfterMs)) {
+            throw failure.error;
+        }
+        const delayMs = retryDelayMs({
+            attempt: budget.attempt,
+            retryAfterMs,
+            jitterKey,
+        });
+        await abortableDelay(delayMs, signal);
+    }
     /**
      * Where a persisted session stands, or `null` when Forge no longer has it
-     * (404/410 — expired or terminated). Any other failure throws with
-     * `sessionLost` false (a 5xx or timeout says nothing about the session).
-     * The probe reports the session's own length; whether that length is the
-     * caller's file is for the caller (or `uploadFromUri`'s resume, which
-     * throws `sessionLost` on a mismatch) to judge. Lets a caller reconcile
-     * sessions on relaunch (a completed one just needs its ingot verified; a
-     * lost one needs a fresh create) before spending an upload slot on it.
+     * (404/410 — expired or terminated), from one HEAD and no retry. Any other
+     * failure throws with `sessionLost` false (a 5xx or a timeout says nothing
+     * against the session), carrying the answer's `retryAfterMs`; a final
+     * refusal Core decided on the HEAD's re-drive (`UPLOAD_POOL_FULL` or
+     * `UPLOAD_SUPERSEDED` in `X-Upload-Refusal`) throws as `upload_refused`,
+     * which no fresh create remedies, and any other code Core ended the session
+     * with reads as gone (null). An offset at
+     * the session's length proves every byte received, not published: a
+     * resume of it sends the receipt. The probe reports the session's own length;
+     * whether that length is the caller's file is for the caller (or
+     * `uploadFromUri`'s resume, which throws `sessionLost` on a mismatch) to
+     * judge. Lets a caller reconcile sessions on relaunch (a completed one just
+     * needs its ingot verified; a lost one needs a fresh create) before
+     * spending an upload slot on it.
      *
      * @throws SparkVaultValidationError, before any request, when `uploadUrl`
      *   is not an upload session on an allowed transfer host.
      */
     async probeSession(session) {
         const uploadUrl = readKeptSessionUrl(session.uploadUrl, this.config.allowedDownloadHostPatterns);
-        try {
-            return await headTusSession(this.config, uploadUrl, session.istk);
-        }
-        catch (err) {
-            if (err instanceof TusUploadError && err.sessionLost)
-                return null;
-            throw err;
-        }
+        const head = await this.headSession({ uploadUrl, istk: session.istk, context: {}, expiry: null }, RESUME_HEAD_REQUEST);
+        if ('probe' in head)
+            return head.probe;
+        if (head.failure.outcome.verdict === TRANSFER_VERDICT.GONE)
+            return null;
+        throw head.failure.error;
     }
     /**
      * Whether the remaining transfer is ONE PATCH the background adapter can