@sparkvault/sdk-mobile 7.0.0 → 7.0.1

package/src/app-sdk/transfer-retry.js

@@ -0,0 +1,563 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/transfer-retry.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The transfer retry policy: what every first-party client does with the
+ * answer to a Forge transfer request (a tus chunk PATCH, an offset HEAD, the
+ * receipt PATCH at the final offset), in one place, so the Node uploader
+ * (forge-tus), the browser SDK (sdk-js bundles this module) and the mobile SDK
+ * (sdk-mobile carries a generated copy) read every answer the same way.
+ *
+ * It encodes what Google Drive, Google Cloud Storage, OneDrive, Dropbox and
+ * AWS document for resumable transfers:
+ * - only a request that got no answer, 408, 425, 429 or a 5xx is retried;
+ *   every other 4xx is the server's verdict on the request;
+ * - `Retry-After` is a floor, never a ceiling;
+ * - retries back off exponentially, capped, with jitter;
+ * - before a chunk is sent again the server is asked for the offset it
+ *   committed, because a request whose answer was lost may have landed;
+ * - a session that is gone (404, 410) is never resumed: only a new upload
+ *   from byte 0 can succeed;
+ * - a transfer's retries are bounded in time and in failures in a row, and
+ *   both bounds start over whenever the server confirms progress.
+ *
+ * Forge's own answers beyond the general rule:
+ * - the 409, in two kinds: one carrying `Upload-Offset` names where the
+ *   session stands (continue from there), and one without it means another
+ *   request holds the session's write lease, a chunk or the finalization
+ *   (retry after its `Retry-After`);
+ * - a terminal answer (a 404, 410 or 412) names the code Core ended the
+ *   upload with: its error envelope in `error.details.coreCode` for the
+ *   refusals it words itself, and every one of them in `X-Upload-Refusal`,
+ *   which is all a HEAD's answer, having no body, can carry; the body's code
+ *   wins when both name one. The code decides the verdict: a full storage
+ *   pool or a later upload that replaced this one is a refusal no new upload
+ *   of the same file remedies, and any other code (the file the upload was
+ *   for gone, a retired contract, a replacement base that moved on, a code
+ *   this policy does not know) ends the session, which a new upload can
+ *   start over;
+ * - a 503 carrying `Retry-After` to the receipt (the PATCH at the final
+ *   offset) is a deferral: Forge holds every byte and is still publishing,
+ *   and finishes without the client, so it is asked again, each time after a
+ *   longer backoff, for as long as the idle limit allows, and never counts as
+ *   a failure. Forge's deferral always names when to ask again; a 503 that
+ *   does not is an ordinary failure.
+ *
+ * Isomorphic: no Node imports, no host APIs, no randomness. The jitter only
+ * has to spread retries, so it hashes the transfer and the attempt
+ * (docs/CONVENTIONS.md → Randomness).
+ */
+
+import { isTransientHttpStatus } from './transient.js';
+import { UPLOAD_FINAL_REFUSAL_CODES, UPLOAD_REFUSAL_HEADER } from './upload-publication.js';
+
+/** What a client does after a transfer request, read from its answer. */
+export const TRANSFER_VERDICT = Object.freeze({
+  /** 2xx: the request did what it asked. */
+  OK: 'ok',
+  /**
+   * No answer (a reset, a timeout), 408, 425, 429, a 5xx, or a 409 without
+   * `Upload-Offset` (another request holds the session's lease): back off,
+   * never sooner than `Retry-After`, then ask the server's offset before
+   * sending a chunk again.
+   */
+  RETRY: 'retry',
+  /** 409 with `Upload-Offset`: the session stands elsewhere; continue from that offset at once. */
+  RESYNC: 'resync',
+  /**
+   * 503 with `Retry-After` to the receipt: every byte is received and the
+   * publication is still running. Ask again after a backoff that grows with
+   * each deferral, never sooner than `Retry-After`; only the idle limit ends
+   * the asking, never the failures in a row.
+   */
+  DEFERRED: 'deferred',
+  /**
+   * 404 or 410 naming no code, or a 404, 410 or 412 naming a code of Core's
+   * that is not a final refusal (`coreCode` carries it): the session no
+   * longer exists; only a new upload from byte 0 can succeed.
+   */
+  GONE: 'gone',
+  /**
+   * Any other status, or a 404, 410 or 412 naming a final refusal of Core's
+   * (`coreCode`: UPLOAD_POOL_FULL, UPLOAD_SUPERSEDED): the server's verdict on
+   * this request, which repeating it, or a new upload of the same file,
+   * earns again.
+   */
+  REFUSED: 'refused'
+});
+
+/** The failures a transfer recovers from by trying again: the verdicts a budget's `failed` records. */
+const RETRYABLE_VERDICTS = new Set([TRANSFER_VERDICT.RETRY, TRANSFER_VERDICT.RESYNC]);
+
+/** RFC 8470: the server refused a request sent in TLS early data; the same request succeeds once the handshake completes. */
+const TOO_EARLY = 425;
+
+/** Forge's answer to a receipt whose publication it deferred. */
+const SERVICE_UNAVAILABLE = 503;
+
+/**
+ * The statuses a terminal answer naming Core's code arrives with: Forge's 410
+ * (UPLOAD_GONE, or Core's own relayed), a relayed 404, and Core's own 412.
+ */
+const TERMINAL_STATUSES = new Set([404, 410, 412]);
+
+/** Core's error codes are upper-case words joined by underscores; anything else names no code. */
+const CORE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+
+
+const UPLOAD_OFFSET_HEADER = 'Upload-Offset';
+const RETRY_AFTER_HEADER = 'Retry-After';
+
+/** The tus `expiration` extension's header: when the session lapses, as an HTTP-date. */
+export const UPLOAD_EXPIRES_HEADER = 'Upload-Expires';
+
+/**
+ * How long a client waits for the answer to an offset HEAD or a receipt
+ * PATCH, whatever its other requests get: on a received upload, Forge answers
+ * either only after its own call to Core (up to 30 s) has published the
+ * upload or deferred it, so each gets twice that.
+ */
+export const HEAD_AND_RECEIPT_TIMEOUT_MS = 60_000;
+
+/** How a retry's delay spreads past its backoff: up to this much more. */
+const JITTER_SPAN_MS = 1000;
+
+/** How long a transfer may sit without progress or a sign of life by default. */
+const DEFAULT_IDLE_LIMIT_MS = 10 * 60 * 1000;
+
+/** How many failures in a row, without progress between them, end a transfer by default. */
+const DEFAULT_MAX_CONSECUTIVE_FAILURES = 8;
+
+/**
+ * @typedef {'ok'|'retry'|'resync'|'deferred'|'gone'|'refused'} TransferVerdict
+ */
+
+/**
+ * The verdicts a transfer recovers from by trying again that count as
+ * failures: the ones a budget's `failed` records.
+ * @typedef {'retry'|'resync'} RetryableTransferVerdict
+ */
+
+/**
+ * @typedef {Object} TransferOutcome
+ * @property {TransferVerdict} verdict - What the client does next
+ * @property {number|null} retryAfterMs - The answer's `Retry-After`, in ms from
+ *   the answer (an HTTP-date already past reads as 0); null when absent or unreadable
+ * @property {number|null} offset - The answer's `Upload-Offset`; null when absent or unreadable
+ * @property {string|null} coreCode - The code Core ended the upload with, as a
+ *   terminal answer named it (a 404, 410 or 412: its body's details or, those
+ *   naming none, its `X-Upload-Refusal`): REFUSED for a final refusal
+ *   (`UPLOAD_POOL_FULL`, `UPLOAD_SUPERSEDED`), GONE for any other code
+ *   (`NOT_FOUND`, `UPLOAD_PROTOCOL_RETIRED`, a 412's, one this policy does not
+ *   know); null when the answer names none
+ */
+
+/**
+ * Read the answer to a transfer request the way the policy does.
+ *
+ * @param {Object} response
+ * @param {number} response.status - The HTTP status; 0 when the request got no answer
+ * @param {((name: string) => string|null)|null} [response.headers] - Reads a
+ *   response header by name: a fetch `Headers`' `get` or an XHR's
+ *   `getResponseHeader`, bound to its owner (`(name) => xhr.getResponseHeader(name)`)
+ * @param {unknown} [response.details] - The `details` of the error envelope the
+ *   answer's body carries (`{ error: { code, message, details } }`), as the
+ *   runtime's one reader of a failed answer parsed it from the whole body;
+ *   where Forge names the refusal Core decided (`coreCode`), ahead of the
+ *   answer's `X-Upload-Refusal`. Anything that is not an object names none.
+ * @param {boolean} [response.receipt] - The request was the receipt: the PATCH
+ *   at the final offset, whose 503 carrying `Retry-After` is a deferral
+ * @param {number} [response.now] - When the answer arrived (epoch ms), which an
+ *   HTTP-date `Retry-After` counts from
+ * @returns {TransferOutcome}
+ * @throws {TypeError} When the status is not a whole number, headers is not a
+ *   function, or receipt is not a boolean
+ */
+export function classifyTransferResponse({ status, headers = null, details = null, receipt = false, now = Date.now() }) {
+  if (!Number.isSafeInteger(status) || status < 0) {
+    throw new TypeError(`A transfer answer's status is a whole number (0 for no answer), not ${status}`);
+  }
+  if (headers !== null && typeof headers !== 'function') {
+    throw new TypeError('A transfer answer\'s headers are read through a function from a header name to its value');
+  }
+  if (typeof receipt !== 'boolean') {
+    throw new TypeError(`Whether a transfer request was the receipt is a boolean, not ${receipt}`);
+  }
+  if (status === 0) {
+    return { verdict: TRANSFER_VERDICT.RETRY, retryAfterMs: null, offset: null, coreCode: null };
+  }
+  const header = (name) => (headers === null ? null : headers(name));
+  const offset = readCount(header(UPLOAD_OFFSET_HEADER));
+  const coreCode = TERMINAL_STATUSES.has(status)
+    ? coreCodeIn(details) ?? coreCodeOf(header(UPLOAD_REFUSAL_HEADER))
+    : null;
+  const retryAfterMs = readRetryAfterMs(header(RETRY_AFTER_HEADER), now);
+  return {
+    verdict: verdictFor(status, { offset, coreCode, deferral: receipt && retryAfterMs !== null }),
+    retryAfterMs,
+    offset,
+    coreCode
+  };
+}
+
+/**
+ * The verdict on a status that came with an answer: `offset` its readable
+ * `Upload-Offset`, `coreCode` the code of Core's a terminal answer names,
+ * `deferral` whether it answered the receipt with a readable `Retry-After`.
+ */
+function verdictFor(status, { offset, coreCode, deferral }) {
+  if (status >= 200 && status < 300) return TRANSFER_VERDICT.OK;
+  if (status === 409) return offset === null ? TRANSFER_VERDICT.RETRY : TRANSFER_VERDICT.RESYNC;
+  if (coreCode !== null) return UPLOAD_FINAL_REFUSAL_CODES.includes(coreCode) ? TRANSFER_VERDICT.REFUSED : TRANSFER_VERDICT.GONE;
+  if (status === 404 || status === 410) return TRANSFER_VERDICT.GONE;
+  if (deferral && status === SERVICE_UNAVAILABLE) return TRANSFER_VERDICT.DEFERRED;
+  if (status === TOO_EARLY || isTransientHttpStatus(status)) return TRANSFER_VERDICT.RETRY;
+  return TRANSFER_VERDICT.REFUSED;
+}
+
+/** The code an error envelope's details name (`coreCode`), or null. */
+function coreCodeIn(details) {
+  return details && typeof details === 'object' ? coreCodeOf(details.coreCode) : null;
+}
+
+/** A value that is one of Core's codes (surrounding whitespace allowed), or null. */
+function coreCodeOf(value) {
+  if (typeof value !== 'string') return null;
+  const code = value.trim();
+  return CORE_CODE.test(code) ? code : null;
+}
+
+/** A header's non-negative whole number (surrounding whitespace allowed), or null. */
+function readCount(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!/^\d+$/.test(text)) return null;
+  const count = Number(text);
+  return Number.isSafeInteger(count) ? count : null;
+}
+
+/** RFC 9110 §10.2.3: `Retry-After` is delay-seconds or an HTTP-date. */
+function readRetryAfterMs(value, now) {
+  const seconds = readCount(value);
+  if (seconds !== null) {
+    const ms = seconds * 1000;
+    return Number.isSafeInteger(ms) ? ms : null;
+  }
+  const at = typeof value === 'string' ? parseHttpDate(value.trim(), now) : null;
+  return at === null ? null : Math.max(0, at - now);
+}
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const DAY_NAME = '(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)';
+const LONG_DAY_NAME = '(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)';
+const MONTH = `(${MONTHS.join('|')})`;
+const TIME_OF_DAY = '(\\d{2}):(\\d{2}):(\\d{2})';
+
+/** IMF-fixdate, what every current server sends: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const IMF_FIXDATE = new RegExp(`^${DAY_NAME}, (\\d{2}) ${MONTH} (\\d{4}) ${TIME_OF_DAY} GMT$`);
+/** The obsolete RFC 850 form a recipient still accepts: `Sunday, 06-Nov-94 08:49:37 GMT`. */
+const RFC850_DATE = new RegExp(`^${LONG_DAY_NAME}, (\\d{2})-${MONTH}-(\\d{2}) ${TIME_OF_DAY} GMT$`);
+/** The obsolete asctime form a recipient still accepts: `Sun Nov  6 08:49:37 1994`. */
+const ASCTIME_DATE = new RegExp(`^${DAY_NAME} ${MONTH} ( \\d|\\d{2}) ${TIME_OF_DAY} (\\d{4})$`);
+
+/**
+ * An HTTP-date (RFC 9110 §5.6.7, all three forms a recipient must accept) as
+ * epoch ms, or null when it is not one or names no real moment.
+ *
+ * @param {string} text
+ * @param {number} now - epoch ms, which places an RFC 850 two-digit year
+ * @returns {number|null}
+ */
+function parseHttpDate(text, now) {
+  let match = IMF_FIXDATE.exec(text);
+  if (match) {
+    const [, day, month, year, hours, minutes, seconds] = match;
+    return utcMs(Number(year), month, Number(day), hours, minutes, seconds);
+  }
+  match = RFC850_DATE.exec(text);
+  if (match) {
+    const [, day, month, shortYear, hours, minutes, seconds] = match;
+    return utcMs(rfc850Year(Number(shortYear), now), month, Number(day), hours, minutes, seconds);
+  }
+  match = ASCTIME_DATE.exec(text);
+  if (match) {
+    const [, month, day, hours, minutes, seconds, year] = match;
+    return utcMs(Number(year), month, Number(day.trim()), hours, minutes, seconds);
+  }
+  return null;
+}
+
+/** RFC 9110: a two-digit year more than 50 years ahead is the latest past year with those digits. */
+function rfc850Year(shortYear, now) {
+  const currentYear = new Date(now).getUTCFullYear();
+  const year = currentYear - (currentYear % 100) + shortYear;
+  return year > currentYear + 50 ? year - 100 : year;
+}
+
+/** The UTC instant of a calendar date and time of day, or null for a date or time that does not exist. */
+function utcMs(year, monthName, day, hours, minutes, seconds) {
+  const monthIndex = MONTHS.indexOf(monthName);
+  const [h, m, s] = [Number(hours), Number(minutes), Number(seconds)];
+  // A leap second (60) is a real time of day; the instant rolls into the next minute.
+  if (h > 23 || m > 59 || s > 60) return null;
+  const date = new Date(0);
+  date.setUTCFullYear(year, monthIndex, day);
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== monthIndex || date.getUTCDate() !== day) {
+    return null;
+  }
+  return date.getTime() + ((h * 60 + m) * 60 + s) * 1000;
+}
+
+/**
+ * When a session lapses, read from its `Upload-Expires` (an HTTP-date).
+ *
+ * @param {unknown} headerValue - The header as received (null when absent)
+ * @param {number} [now] - epoch ms, which places an obsolete two-digit year
+ * @returns {number|null} epoch ms, or null when absent or not an HTTP-date
+ */
+export function parseUploadExpires(headerValue, now = Date.now()) {
+  return typeof headerValue === 'string' ? parseHttpDate(headerValue.trim(), now) : null;
+}
+
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+
+/**
+ * 32-bit FNV-1a over the text's UTF-8 bytes: the jitter's hash. A retry's
+ * delay only has to spread, so it hashes what identifies the retry and draws
+ * nothing (docs/CONVENTIONS.md → Randomness).
+ *
+ * @param {string} text
+ * @returns {number} An unsigned 32-bit integer
+ * @throws {TypeError} When the text is not a string
+ */
+export function fnv1a32(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError(`fnv1a32 hashes a string, not ${typeof text}`);
+  }
+  let hash = FNV_OFFSET_BASIS;
+  const mix = (byte) => {
+    hash = Math.imul(hash ^ byte, FNV_PRIME) >>> 0;
+  };
+  for (const character of text) {
+    let point = character.codePointAt(0);
+    // A lone surrogate has no UTF-8 form; it encodes as U+FFFD, as TextEncoder does.
+    if (point >= 0xd800 && point <= 0xdfff) point = 0xfffd;
+    if (point < 0x80) {
+      mix(point);
+    } else if (point < 0x800) {
+      mix(0xc0 | (point >> 6));
+      mix(0x80 | (point & 0x3f));
+    } else if (point < 0x10000) {
+      mix(0xe0 | (point >> 12));
+      mix(0x80 | ((point >> 6) & 0x3f));
+      mix(0x80 | (point & 0x3f));
+    } else {
+      mix(0xf0 | (point >> 18));
+      mix(0x80 | ((point >> 12) & 0x3f));
+      mix(0x80 | ((point >> 6) & 0x3f));
+      mix(0x80 | (point & 0x3f));
+    }
+  }
+  return hash;
+}
+
+/** Transfers this runtime has keyed by `transferJitterKey`: with the start time, what tells them apart. */
+let transfersKeyed = 0;
+
+/**
+ * What a transfer's retries spread by when no session URL keys them yet (a
+ * session create) or ever (a download, whose link carries its token): the
+ * scope (the create endpoint, or the kind of transfer), when the transfer
+ * started, and this runtime's count of keyed transfers, which tell
+ * concurrent transfers apart. A transfer's token is a credential and never
+ * feeds anything observable such as a delay, so no part of the key derives
+ * from it (docs/CONVENTIONS.md → Randomness).
+ *
+ * @param {string} scope - The endpoint or the kind of transfer
+ * @returns {string} The key, for every retry of this one transfer
+ * @throws {TypeError} For a scope that is not a non-empty string
+ */
+export function transferJitterKey(scope) {
+  if (typeof scope !== 'string' || scope.length === 0) {
+    throw new TypeError('A transfer jitter key needs the scope its transfer runs in');
+  }
+  transfersKeyed += 1;
+  return `${scope}#${Date.now()}-${transfersKeyed}`;
+}
+
+/**
+ * How long to wait before retry `attempt` of a transfer: `baseMs` doubling per
+ * attempt, capped at `capMs`, plus a jitter in [0, 1000) ms hashed from the
+ * transfer and the attempt, and never less than the server's `Retry-After`.
+ * The same transfer and attempt always wait the same; different transfers
+ * failing together spread out.
+ *
+ * @param {Object} options
+ * @param {number} options.attempt - Which retry this is, from 1
+ * @param {number|null} [options.retryAfterMs] - The answer's `Retry-After`: a floor
+ * @param {number} [options.baseMs] - The first retry's backoff
+ * @param {number} [options.capMs] - The longest backoff, before jitter
+ * @param {string} options.jitterKey - What identifies the transfer (its session
+ *   URL, or a `transferJitterKey`)
+ * @returns {number} ms
+ * @throws {TypeError} For an attempt that is not a whole number from 1, a
+ *   missing jitter key, or a delay bound that is not a positive number of ms
+ */
+export function retryDelayMs({ attempt, retryAfterMs = null, baseMs = 1000, capMs = 32000, jitterKey }) {
+  if (!Number.isSafeInteger(attempt) || attempt < 1) {
+    throw new TypeError(`A retry's attempt is a whole number from 1, not ${attempt}`);
+  }
+  if (typeof jitterKey !== 'string' || jitterKey.length === 0) {
+    throw new TypeError('A retry delay needs the key its transfer spreads by');
+  }
+  if (!isDuration(baseMs) || baseMs === 0 || !isDuration(capMs) || capMs < baseMs) {
+    throw new TypeError(`A retry backs off from a positive base (${baseMs} ms) up to a cap no smaller (${capMs} ms)`);
+  }
+  if (retryAfterMs !== null && !isDuration(retryAfterMs)) {
+    throw new TypeError(`A Retry-After floor is a non-negative number of ms, not ${retryAfterMs}`);
+  }
+  const backoff = Math.min(capMs, baseMs * 2 ** (attempt - 1));
+  const jitter = Math.floor((fnv1a32(`${jitterKey}|${attempt}`) / 2 ** 32) * JITTER_SPAN_MS);
+  return Math.max(backoff + jitter, retryAfterMs ?? 0);
+}
+
+function isDuration(ms) {
+  return Number.isFinite(ms) && ms >= 0;
+}
+
+/**
+ * @typedef {Object} TransferBudget
+ * @property {() => void} progressed - The server confirmed progress (bytes
+ *   landed, or the offset it names moved forward): the failures in a row and
+ *   the idle clock start over
+ * @property {() => void} alive - A sign of life the server has not confirmed
+ *   (bytes are leaving, or the device is back online): the idle clock starts
+ *   over and the failures in a row stand, so attempts that die before the
+ *   server confirms anything still end the transfer
+ * @property {(verdict: RetryableTransferVerdict, retryAfterMs?: number|null) => boolean} failed -
+ *   Records a retryable answer (RETRY or RESYNC) and says whether another
+ *   attempt is allowed: the failures in a row stay under the max, and the
+ *   attempt `retryAfterMs` allows would start inside the idle limit, so a
+ *   transfer never sleeps on a Retry-After longer than its budget. The limit
+ *   bounds when a retry is decided; a retry decided inside it still waits its
+ *   own backoff, so a transfer ends within one backoff of the limit.
+ * @property {(retryAfterMs?: number|null) => boolean} deferred - Records a
+ *   DEFERRED answer and says whether to ask again: only the idle limit bounds
+ *   it, as `failed` applies it, because a deferral is the server at work,
+ *   never a failure, so the failures in a row stand
+ * @property {number} consecutiveFailures - Retryable failures since the last progress
+ * @property {number} attempt - Failures and deferrals since the last progress:
+ *   the attempt the next wait's delay is computed for, so each deferral backs
+ *   the next ask off as a failure does, sparing a Core that is struggling to
+ *   publish
+ * @property {number} msSinceProgress - ms since the last progress or sign of life
+ */
+
+/**
+ * The retry budget of one transfer: retries are bounded by failures in a row
+ * and by time without progress, deferrals by time alone, and both bounds
+ * start 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.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.idleLimitMs] - How long the transfer may go without
+ *   progress or a sign of life
+ * @param {number} [options.maxConsecutiveFailures] - Failures in a row that end the transfer
+ * @param {() => number} [options.now] - The clock, epoch ms
+ * @returns {TransferBudget}
+ * @throws {TypeError} For a limit that is not a positive number, or a clock that is not a function
+ */
+export function createTransferBudget({
+  idleLimitMs = DEFAULT_IDLE_LIMIT_MS,
+  maxConsecutiveFailures = DEFAULT_MAX_CONSECUTIVE_FAILURES,
+  now = () => Date.now()
+} = {}) {
+  if (!isDuration(idleLimitMs) || idleLimitMs === 0) {
+    throw new TypeError(`A transfer's idle limit is a positive number of ms, not ${idleLimitMs}`);
+  }
+  if (!Number.isSafeInteger(maxConsecutiveFailures) || maxConsecutiveFailures < 1) {
+    throw new TypeError(`A transfer's failure limit is a whole number from 1, not ${maxConsecutiveFailures}`);
+  }
+  if (typeof now !== 'function') {
+    throw new TypeError('A transfer budget reads time from a clock function');
+  }
+
+  let consecutiveFailures = 0;
+  let deferrals = 0;
+  let lastSignOfLifeAt = now();
+  const msIdle = () => now() - lastSignOfLifeAt;
+  const startsInsideIdleLimit = (retryAfterMs) => {
+    if (retryAfterMs !== null && !isDuration(retryAfterMs)) {
+      throw new TypeError(`A Retry-After floor is a non-negative number of ms, not ${retryAfterMs}`);
+    }
+    return msIdle() + (retryAfterMs ?? 0) < idleLimitMs;
+  };
+
+  return Object.freeze({
+    progressed() {
+      consecutiveFailures = 0;
+      deferrals = 0;
+      lastSignOfLifeAt = now();
+    },
+    alive() {
+      lastSignOfLifeAt = now();
+    },
+    failed(verdict, retryAfterMs = null) {
+      if (!RETRYABLE_VERDICTS.has(verdict)) {
+        throw new TypeError(`A transfer budget records retryable answers only, not '${verdict}'`);
+      }
+      const allowed = startsInsideIdleLimit(retryAfterMs);
+      consecutiveFailures += 1;
+      return allowed && consecutiveFailures < maxConsecutiveFailures;
+    },
+    deferred(retryAfterMs = null) {
+      const allowed = startsInsideIdleLimit(retryAfterMs);
+      deferrals += 1;
+      return allowed;
+    },
+    get consecutiveFailures() {
+      return consecutiveFailures;
+    },
+    get attempt() {
+      return consecutiveFailures + deferrals;
+    },
+    get msSinceProgress() {
+      return msIdle();
+    }
+  });
+}
+
+/** Why an offset the server names cannot be resumed from. */
+export const RESUME_OFFSET_PROBLEM = Object.freeze({
+  /** Not a non-negative whole number of bytes. */
+  INVALID: 'invalid',
+  /** Past the upload's length: resuming from it would report a partial upload complete. */
+  BEYOND_TOTAL: 'beyond_total',
+  /** Inside a chunk: a session commits whole chunks only, so the answer is corrupt. */
+  MISALIGNED: 'misaligned'
+});
+
+/**
+ * Why a session offset the server named (a HEAD's, or a 409's `Upload-Offset`)
+ * cannot be resumed from, or null when it can. Forge commits whole chunks, so
+ * a session stands at a multiple of its chunk size or at its total.
+ *
+ * @param {number|null} offset
+ * @param {Object} geometry
+ * @param {number} geometry.totalSize - The upload's length (a non-negative whole number)
+ * @param {number} geometry.chunkSize - The session's chunk size (a positive whole number)
+ * @returns {'invalid'|'beyond_total'|'misaligned'|null}
+ * @throws {TypeError} When the length is not a non-negative whole number or
+ *   the chunk size not a positive one
+ */
+export function resumeOffsetProblem(offset, { totalSize, chunkSize }) {
+  if (!Number.isSafeInteger(totalSize) || totalSize < 0 || !Number.isSafeInteger(chunkSize) || chunkSize < 1) {
+    throw new TypeError(`An upload's geometry is a whole length and a positive chunk size, not ${totalSize} and ${chunkSize}`);
+  }
+  if (!Number.isSafeInteger(offset) || offset < 0) return RESUME_OFFSET_PROBLEM.INVALID;
+  if (offset > totalSize) return RESUME_OFFSET_PROBLEM.BEYOND_TOTAL;
+  if (offset !== totalSize && offset % chunkSize !== 0) return RESUME_OFFSET_PROBLEM.MISALIGNED;
+  return null;
+}

package/src/app-sdk/upload-publication.js

@@ -0,0 +1,102 @@
+// GENERATED FILE — do not edit by hand.
+// Source of truth: packages/app-sdk/src/upload-publication.js
+// Regenerate with: pnpm --filter @sparkvault/sdk-mobile build
+
+/**
+ * The upload publication contract between Forge and Core's activation.
+ *
+ * Forge stamps UPLOAD_PUBLICATION_PROTOCOL on every upload session it creates
+ * and on the final state it hands Core's activation (POST
+ * /v1/vaults/:vault_id/ingots/:ingot_id/activate); activation refuses any
+ * other version. The two services deploy separately, so a change to what
+ * either side sends or expects moves this number: a session or a finalize
+ * from the other side's contract then fails closed ("restart the upload")
+ * instead of publishing under a contract the other side does not hold.
+ *
+ * Version 2: an upload's own metadata (content type, original file name,
+ * uploader, content HMAC) travels on its upload token and its session, and
+ * activation publishes it from the session; the final state Forge sends
+ * carries only the storage facts Forge owns.
+ *
+ * Isomorphic: no Node imports.
+ */
+
+export const UPLOAD_PUBLICATION_PROTOCOL = 2;
+
+/**
+ * An upload's id as both services spell it: `tus_` and the 32 lowercase hex
+ * digits of 16 random bytes. An encrypt token that names one (`upload_id`)
+ * was staged by Core under it, and Forge keys the upload's session, its chunk
+ * prefix and its VAK wrapping by it, so Core finds and settles the upload by
+ * the session's id.
+ */
+export const UPLOAD_ID_PATTERN = /^tus_[0-9a-f]{32}$/;
+
+/**
+ * How much of an ISTK names a transfer's charge on the usage ledger: enough to
+ * be unique to the token, never the whole bearer credential.
+ */
+export const TRANSFER_REFERENCE_ISTK_CHARS = 24;
+
+/**
+ * The ledger reference of an upload's transfer charge,
+ * `forge_ingot_transfer_upload_<first 24 ISTK chars>`: every charge of one
+ * upload carries it — Core's activation, Core's charge of an upload that never
+ * publishes, Forge's cancel — so whichever lands first is the upload's one
+ * ledger row and the others are duplicates.
+ *
+ * @param {string} istk - The upload's ISTK, as its session carries it
+ * @returns {string}
+ * @throws {TypeError} When the ISTK is not a string of at least
+ *   TRANSFER_REFERENCE_ISTK_CHARS characters
+ */
+export function uploadTransferReference(istk) {
+  if (typeof istk !== 'string' || istk.length < TRANSFER_REFERENCE_ISTK_CHARS) {
+    throw new TypeError(
+      `An upload's transfer reference is named from its ISTK, a string of at least ${TRANSFER_REFERENCE_ISTK_CHARS} characters`
+    );
+  }
+  return `forge_ingot_transfer_upload_${istk.slice(0, TRANSFER_REFERENCE_ISTK_CHARS)}`;
+}
+
+/**
+ * The codes Core's activation refuses an upload with, which Forge's refusal
+ * map reads (the status is Core's):
+ * - UPLOAD_CONTRACT_MISMATCH (409): a finalize or session from another
+ *   publication contract than Core's, a mixed deployment that converges — the
+ *   upload is kept and its finalize tried again.
+ * - UPLOAD_PROTOCOL_RETIRED (410): a session from a contract Core no longer
+ *   publishes, which never can be.
+ * - UPLOAD_SUPERSEDED (410): a session a later staging of its ingot
+ *   superseded, which never can be.
+ * - UPLOAD_POOL_FULL (402): an upload the owner's storage pool cannot take at
+ *   publication, which is final.
+ */
+export const UPLOAD_REFUSAL_CODES = Object.freeze({
+  UPLOAD_CONTRACT_MISMATCH: 'UPLOAD_CONTRACT_MISMATCH',
+  UPLOAD_PROTOCOL_RETIRED: 'UPLOAD_PROTOCOL_RETIRED',
+  UPLOAD_SUPERSEDED: 'UPLOAD_SUPERSEDED',
+  UPLOAD_POOL_FULL: 'UPLOAD_POOL_FULL'
+});
+
+/**
+ * The refusals of Core's that a new upload of the same file cannot remedy:
+ * the owner's storage pool cannot take it (UPLOAD_POOL_FULL), or a later
+ * upload of its ingot replaced it (UPLOAD_SUPERSEDED). Any other code Core
+ * ends an upload with ends its session alone, which a new upload starts
+ * over. Every client reads a terminal answer's code by it
+ * (transfer-retry.js): one of these is a refusal it reports in Core's words,
+ * any other a gone session.
+ */
+export const UPLOAD_FINAL_REFUSAL_CODES = Object.freeze([
+  UPLOAD_REFUSAL_CODES.UPLOAD_POOL_FULL,
+  UPLOAD_REFUSAL_CODES.UPLOAD_SUPERSEDED
+]);
+
+/**
+ * The response header that names the code Core refused an upload with for
+ * good: Forge sends it on every terminal answer to a tus request, a HEAD's
+ * (which has no body) included, so a client tells an upload the owner's pool
+ * cannot take from one a later upload superseded without reading a body.
+ */
+export const UPLOAD_REFUSAL_HEADER = 'X-Upload-Refusal';