@sparkvault/sdk-mobile 7.0.0 → 7.0.1

package/src/tus.ts

@@ -1,6 +1,19 @@
-import type { ResolvedMobileConfig } from './config.js';
+import type { MobileConnectivity, ResolvedMobileConfig } from './config.js';
 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 type { TransferBudget, TransferOutcome } from './app-sdk/transfer-retry.js';
+import { UPLOAD_REFUSAL_CODES } from './app-sdk/upload-publication.js';
 import {
   BackgroundTransferError,
   gateErrorFromBody,
@@ -35,15 +48,23 @@ export interface ParsedForgeUrl {
  *
  * A resume that cannot use the session throws a `TusUploadError` whose
  * `sessionLost` is true exactly when the session is worthless for this file
- * and the caller should drop it and start fresh: Forge no longer has it
+ * and the caller should drop it and start fresh: the expiry the caller holds
+ * for it has passed (refused before any request), Forge no longer has it
  * (404/410), or its `Upload-Length` is not this file's size (it belongs to a
- * different file). A transient HEAD failure (5xx, timeout) is NOT
- * `sessionLost`; the session is intact and the same resume can be retried.
+ * different file). A HEAD that keeps failing transiently (5xx, timeouts) past
+ * the upload's retry budget is NOT `sessionLost`; the session is intact and
+ * the same resume can be retried.
  */
 export interface TusResumeSession {
   uploadUrl: string;
   /** The session's ISTK. Falls back to the one in `forgeUrl` when omitted. */
   istk?: string;
+  /**
+   * The session's expiry as the caller holds it (`expiresAt` from
+   * `onSessionCreated`, kept current through `onSessionExpiry`). Null or
+   * omitted is unknown, and Forge's HEAD decides.
+   */
+  expiresAt?: number | null;
 }
 
 /** Where a tus session stands server-side, as reported by HEAD. */
@@ -51,6 +72,8 @@ export interface TusSessionProbe {
   offset: number;
   length: number;
   chunkSize: number;
+  /** When the session lapses (epoch ms, Forge's `Upload-Expires`), or null when the HEAD named none. */
+  expiresAt: number | null;
 }
 
 export interface TusUploadFromUriOptions {
@@ -72,6 +95,17 @@ export interface TusUploadFromUriOptions {
    * relaunch. Not invoked on resume. A throw here fails the upload.
    */
   onSessionCreated?: (session: TusSessionInfo) => void;
+  /**
+   * Invoked whenever the session's expiry, as its latest answer named it,
+   * changes: Forge slides it forward with every committed chunk and names it
+   * on its answers (`Upload-Expires`). It is null (unknown) after an answer
+   * that named none, and from the hand-off of a request the OS carries on
+   * without JS (the transfer engine's range, the single-chunk background
+   * PATCH): either may have moved it unread. A caller that persists the
+   * session keeps its `expiresAt` current with this, so a session it judges
+   * expired (`isSessionExpired`) really is. A throw here fails the upload.
+   */
+  onSessionExpiry?: (expiresAt: number | null) => void;
   /**
    * `background` rides the best suspension-proof engine the app provides:
    * the OS transfer engine (`backgroundTransfer`) for the whole remaining
@@ -171,9 +205,12 @@ export function allowsHost(allowedHostPatterns: readonly RegExp[]): (hostname: s
 }
 
 /**
- * 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: string): ApiErrorBody {
   if (!text) return {};
@@ -193,9 +230,14 @@ function getErrorMessage(err: unknown): string {
   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(): TusUploadError {
+  return new TusUploadError('Upload cancelled', { phase: 'cancelled' });
+}
+
 function ensureNotAborted(signal?: AbortSignal): void {
   if (signal?.aborted) {
-    throw new TusUploadError('Upload cancelled', { phase: 'cancelled' });
+    throw cancelledError();
   }
 }
 
@@ -233,28 +275,29 @@ interface TusErrorContext {
   fileSize?: number;
 }
 
-/**
- * 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: ReadonlySet<number> = 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: number): boolean {
-  return SESSION_GONE_STATUSES.has(status);
+  return Number.isSafeInteger(status) && status > 0 && classifyTransferResponse({ status }).verdict === TRANSFER_VERDICT.GONE;
 }
 
+/**
+ * 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: number,
   context: TusErrorContext,
   phase: TusUploadError['phase'],
-  cause: Error | null = null
+  cause: Error | null = null,
+  coreCode: string | null = null
 ): TusUploadError {
   return new TusUploadError(`TUS session no longer exists on the server (${status})`, {
     cause,
@@ -262,6 +305,324 @@ function sessionLostError(
     ...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: number | null | undefined, now: number = Date.now()): boolean {
+  return typeof expiresAt === 'number' && now > expiresAt + SESSION_EXPIRY_CLOCK_MARGIN_MS;
+}
+
+/**
+ * One answer to a transfer request, or its absence: what the transfer policy
+ * reads (the status and the headers) and what an error built from it says
+ * (the body). Every request an upload sends resolves to one, so one place
+ * decides what the upload does next.
+ */
+interface TransferAnswer {
+  /** The HTTP status; 0 when no answer arrived (a dropped connection, a timeout, a stalled chunk). */
+  readonly status: number;
+  /** A response header by name, case-insensitively; always null for no answer. */
+  readonly header: (name: string) => string | null;
+  /** The body of an answer that is not a 2xx (Forge's error JSON); empty otherwise. */
+  readonly body: string;
+  /** That body's error envelope, parsed once and whole (`parseErrorBody`); empty for a 2xx or no answer. */
+  readonly envelope: ApiErrorBody;
+  /** Why no answer arrived (status 0): the error the caller sees when no retry follows. */
+  readonly unanswered: TusUploadError | null;
+}
+
+/** An answer that arrived: its status, its headers and the body of one that is not a 2xx. */
+function answerOf(status: number, header: (name: string) => string | null, body: string): TransferAnswer {
+  return { status, header, body, envelope: parseErrorBody(body), unanswered: null };
+}
+
+function noAnswer(error: TusUploadError): TransferAnswer {
+  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: TransferAnswer, request: TusRequestKind): TransferOutcome {
+  return classifyTransferResponse({
+    status: answer.status,
+    headers: answer.header,
+    details: answer.envelope.error?.details ?? null,
+    receipt: request.receipt,
+  });
+}
+
+/**
+ * A failed request of an upload: the error the caller sees when no retry
+ * follows, and what the transfer policy made of the answer behind it.
+ */
+interface TransferFailure {
+  readonly error: SparkVaultMobileError;
+  readonly outcome: TransferOutcome;
+  /** No answer arrived, so the device may be offline (an answer of any status proves it is not). */
+  readonly unanswered: boolean;
+}
+
+/** How a request names itself in its errors, and whether it is the receipt. */
+interface TusRequestKind {
+  /** The request in the message: `TUS HEAD failed: 503 - …`. */
+  readonly label: string;
+  readonly phase: TusUploadError['phase'];
+  /** The phase a gone session (404/410) is reported in; null for the create, which no session stands behind yet. */
+  readonly gonePhase: TusUploadError['phase'] | null;
+  /** The PATCH at the final offset, whose 503 is a deferral (the transfer policy's DEFERRED). */
+  readonly receipt: boolean;
+}
+
+const CREATE_REQUEST: TusRequestKind = { label: 'TUS create', phase: 'create', gonePhase: null, receipt: false };
+const RESUME_HEAD_REQUEST: TusRequestKind = { label: 'TUS HEAD', phase: 'create', gonePhase: 'create', receipt: false };
+const OFFSET_HEAD_REQUEST: TusRequestKind = { label: 'TUS HEAD', phase: 'upload', gonePhase: 'create', receipt: false };
+const CHUNK_REQUEST: TusRequestKind = { label: 'Chunk upload', phase: 'upload', gonePhase: 'upload', receipt: false };
+const RECEIPT_REQUEST: TusRequestKind = { 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: ReadonlyMap<string, string> = 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: number,
+  envelope: ApiErrorBody,
+  coreCode: string,
+  context: TusErrorContext,
+  phase: TusUploadError['phase'],
+  cause: Error | null = null
+): TusUploadError {
+  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: TransferAnswer,
+  outcome: TransferOutcome,
+  request: TusRequestKind,
+  context: TusErrorContext
+): TransferFailure {
+  return { error: errorOf(answer, outcome, request, context), outcome, unanswered: answer.unanswered !== null };
+}
+
+function errorOf(
+  answer: TransferAnswer,
+  outcome: TransferOutcome,
+  request: TusRequestKind,
+  context: TusErrorContext
+): SparkVaultMobileError {
+  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 {
+  private known: number | null;
+  private readonly report?: (expiresAt: number | null) => void;
+
+  constructor(known: number | null, report?: (expiresAt: number | null) => void) {
+    this.known = known;
+    this.report = report;
+  }
+
+  /** Forge answered (or did not): the expiry is what the answer names. */
+  read(answer: TransferAnswer): void {
+    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(): void {
+    this.become(null);
+  }
+
+  private become(expiresAt: number | null): void {
+    if (expiresAt === this.known) return;
+    this.known = expiresAt;
+    this.report?.(expiresAt);
+  }
+}
+
+/**
+ * What every request to one session carries: where it lives, its token, the
+ * file it is for, the expiry its answers keep current (none for a one-off
+ * probe), and the caller's abort.
+ */
+interface SessionLink {
+  readonly uploadUrl: string;
+  readonly istk: string;
+  readonly context: TusErrorContext;
+  readonly expiry: SessionExpiry | null;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * An upload in flight on its session: the file's geometry and the one retry
+ * budget every request of it spends (`@sparkvault/app-sdk/transfer-retry`):
+ * failures in a row and time without progress, both starting over whenever
+ * the server confirms progress, so a slow transfer that keeps landing bytes
+ * is never cut off while a dead one ends in bounded time.
+ */
+interface TusTransfer extends SessionLink {
+  readonly fileSize: number;
+  readonly chunkSize: number;
+  readonly budget: TransferBudget;
+  readonly expiry: SessionExpiry;
+}
+
+/** Where an upload stands: the server's offset, and whether the server confirmed the ingot published. */
+interface TransferPosition {
+  readonly offset: number;
+  readonly published: boolean;
+}
+
+/** The file a chunk is read from, and how its chunks travel. */
+interface ChunkSource {
+  readonly reader: MobileFileReader;
+  readonly uri: string;
+  readonly transport?: UploadTransport;
+  /** Bytes of the chunk at `offset` that have left the device so far. */
+  readonly onChunkProgress: (offset: number, chunkBytesUploaded: number) => void;
+}
+
+/** A backoff the caller's abort cuts short: resolves after `ms`, rejects as cancelled the moment the signal fires. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  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: MobileConnectivity, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let unsubscribe: (() => void) | null = null;
+    const settle = (outcome: () => void) => {
+      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);
+    }
   });
 }
 
@@ -308,6 +669,38 @@ async function tusRequest(
   }
 }
 
+/**
+ * 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: ResolvedMobileConfig,
+  url: string,
+  init: TusRequestInit,
+  label: string,
+  context: TusErrorContext
+): Promise<TransferAnswer> {
+  let response: 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),
@@ -329,7 +722,7 @@ function getHeaderIgnoreCase(headers: Record<string, string> | undefined, name:
  */
 type TusSessionSource =
   | { mode: 'create'; parsed: ParsedForgeUrl }
-  | { mode: 'resume'; uploadUrl: string; istk: string };
+  | { mode: 'resume'; uploadUrl: string; istk: string; expiresAt: number | null };
 
 function resolveSessionSource(options: TusUploadFromUriOptions, allowedHostPatterns: readonly RegExp[]): TusSessionSource {
   if (options.resume) {
@@ -339,7 +732,11 @@ function resolveSessionSource(options: TusUploadFromUriOptions, allowedHostPatte
     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');
@@ -347,60 +744,20 @@ function resolveSessionSource(options: TusUploadFromUriOptions, allowedHostPatte
   return { mode: 'create', parsed: parseForgeUrl(options.forgeUrl, allowedHostPatterns) };
 }
 
-async function createTusUpload(
-  config: ResolvedMobileConfig,
-  parsed: ParsedForgeUrl,
-  fileSize: number,
-  filename: string,
-  signal?: AbortSignal
-): Promise<{ uploadUrl: string; chunkSize: number }> {
-  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: TransferAnswer,
+  endpoint: string,
+  context: TusErrorContext
+): { uploadUrl: string; chunkSize: number; expiresAt: number | null } {
+  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',
     });
   }
@@ -409,149 +766,57 @@ async function createTusUpload(
   // 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: ResolvedMobileConfig,
-  uploadUrl: string,
-  istk: string,
-  signal?: AbortSignal,
-  context: TusErrorContext = {}
-): Promise<TusSessionProbe> {
-  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: TransferAnswer, phase: TusUploadError['phase'], context: TusErrorContext): TusSessionProbe {
+  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' }
+      { ...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: ResolvedMobileConfig,
-  uploadUrl: string,
-  istk: string,
-  fileSize: number,
-  signal?: AbortSignal,
-  context: TusErrorContext = {}
-): Promise<void> {
-  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,
-      ...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,
+function checkedServerOffset(
+  offset: number | null,
+  geometry: { fileSize: number; chunkSize: number },
+  phase: TusUploadError['phase'],
+  context: TusErrorContext
+): number {
+  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',
+      phase,
     });
   }
+  return offset;
 }
 
 /**
@@ -562,26 +827,29 @@ async function confirmTusFinalization(
 const CHUNK_ABSOLUTE_CAP_MS = 60 * 60_000;
 
 /**
- * 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: string,
-  istk: string,
+function sendChunkOverXhr(
+  transfer: TusTransfer,
   chunk: TusChunk,
   offset: number,
   stallTimeoutMs: number,
-  signal?: AbortSignal,
   onChunkProgress?: (chunkBytesUploaded: number) => void
-): Promise<number> {
+): Promise<TransferAnswer> {
   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();
@@ -604,7 +872,7 @@ function uploadChunk(
 
     const abort = () => {
       xhr.abort();
-      finish(() => reject(new TusUploadError('Upload cancelled', { phase: 'cancelled' })));
+      finish(() => reject(cancelledError()));
     };
 
     if (signal?.aborted) {
@@ -613,10 +881,13 @@ function uploadChunk(
     }
     signal?.addEventListener('abort', abort, { once: true });
 
+    const unanswered = (message: string, phase: 'network' | 'timeout') =>
+      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: string) => {
-      finish(() => reject(new TusUploadError(message, { phase: 'timeout' })));
+      unanswered(message, 'timeout');
       xhr.abort();
     };
     const armWatchdog = () => {
@@ -629,38 +900,24 @@ function uploadChunk(
 
     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);
@@ -682,64 +939,60 @@ function uploadChunk(
 
 /**
  * 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(
+async function sendWholeFileInBackground(
   uploader: MobileBackgroundUploader,
-  uploadUrl: string,
-  istk: string,
+  transfer: TusTransfer,
   fileUri: string,
   offset: number
-): Promise<number> {
+): Promise<TransferAnswer> {
   let result: Awaited<ReturnType<MobileBackgroundUploader['uploadFile']>>;
   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;
+  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',
+    }));
   }
-  throw new TusUploadError(`Chunk upload failed: ${result.status} - ${body.substring(0, 200)}`, {
-    httpStatus: result.status,
-    phase: 'upload',
-  });
+  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
@@ -765,9 +1018,18 @@ export function mapBackgroundTransferError(
       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)}`,
@@ -831,6 +1093,29 @@ export class MobileTusUploader {
     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: TusUploadFromUriOptions): Promise<void> {
     const fileReader = this.config.fileReader;
     if (!fileReader) {
@@ -841,61 +1126,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: TusErrorContext = { 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: string | null = 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: number | null = null;
+    const report = (uploaded: number) => {
+      reported = uploaded;
+      options.onProgress?.(uploaded, fileSize);
+    };
 
     try {
-      let chunkSize: number;
-      let sessionUrl: string;
+      let transfer: TusTransfer;
+      let position: TransferPosition;
       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: SessionLink = { 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
@@ -907,83 +1196,59 @@ 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) {
+        if (finalOffset !== fileSize) {
           throw new TusUploadError(
-            `Upload stalled: background transfer ended at offset ${finalOffset} of ${options.fileSize}`,
-            { phase: 'stalled', filename: options.filename, fileSize: options.fileSize }
+            `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: number;
-        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: ChunkSource = {
+        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) {
@@ -1012,10 +1277,11 @@ export class MobileTusUploader {
       // the caller intact so the subscribe / add-on UX fires; never bury them
       // 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,
@@ -1023,27 +1289,354 @@ export class MobileTusUploader {
     }
   }
 
+  /**
+   * 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`).
+   */
+  private async createSession(
+    parsed: ParsedForgeUrl,
+    fileSize: number,
+    budget: TransferBudget,
+    context: TusErrorContext,
+    signal?: AbortSignal
+  ): Promise<{ uploadUrl: string; chunkSize: number; expiresAt: number | null }> {
+    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.
+   */
+  private async readResumePoint(link: SessionLink, budget: TransferBudget, fileSize: number): Promise<TusSessionProbe> {
+    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.
+   */
+  private async headSession(
+    link: SessionLink,
+    request: TusRequestKind
+  ): Promise<{ probe: TusSessionProbe } | { failure: TransferFailure }> {
+    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.
+   */
+  private async sendChunkAt(transfer: TusTransfer, offset: number, chunks: ChunkSource): Promise<TransferPosition> {
+    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. */
+  private async sendChunk(transfer: TusTransfer, offset: number, chunks: ChunkSource): Promise<TransferAnswer> {
+    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.
+   */
+  private async positionAfterFailure(
+    transfer: TusTransfer,
+    failure: TransferFailure,
+    sentOffset: number
+  ): Promise<TransferPosition> {
+    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.
+   */
+  private resyncedPosition(transfer: TusTransfer, failure: TransferFailure, sentOffset: number): TransferPosition {
+    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.
+   */
+  private async confirmReceipt(transfer: TusTransfer): Promise<TransferPosition> {
+    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.
+   */
+  private async waitToRetry(
+    budget: TransferBudget,
+    failure: TransferFailure,
+    jitterKey: string,
+    signal?: AbortSignal
+  ): Promise<void> {
+    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: { uploadUrl: string; istk: string }): Promise<TusSessionProbe | null> {
     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;
   }
 
   /**