@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/ota/OtaTypes.ts

@@ -1,62 +1,118 @@
-/**
- * OTA contract types — SDK-side mirror of the backend's ota.contracts.ts.
- *
- * These types are hand-maintained here AND mirrored in the backend.
- * Golden JSON fixtures in packages/protocol/fixtures/ota/ are the SINGLE source
- * of truth; conformance tests in both repos assert against them to prevent drift.
- */
-
-// ── SDK → backend (POST /sdk/ota/check) ──────────────────────────────────────
-export interface OtaCheckRequest {
-  appVersion: string;
-  platform: 'android' | 'ios';
-  arch?: string;
-  installationId: string;
-  currentBundleId?: string;
-  currentBundleHash?: string;
-}
-
-// ── backend → SDK ────────────────────────────────────────────────────────────
-export interface OtaCheckResponse {
-  action: 'NONE' | 'DOWNLOAD' | 'ROLLBACK';
-  bundle?: OtaBundlePayload;
-}
-
-export interface OtaBundlePayload {
-  id: string;
-  version: number;
-  url: string;         // presigned GET — short-TTL
-  size: number;
-  sha256: string;
-  signature?: string;  // ed25519 detached signature (hex)
-  isMandatory: boolean;
-  releaseNote?: string;
-  patch?: OtaPatchPayload;
-}
-
-export interface OtaPatchPayload {
-  url: string;
-  size: number;
-  sha256: string;
-  baseBundleId: string;
-}
-
-// ── Adoption telemetry (rides the unified batch envelope as kind:'ota_event') ──
-export type OtaEventType =
-  | 'CHECK'
-  | 'DOWNLOAD_STARTED'
-  | 'DOWNLOAD_COMPLETE'
-  | 'INSTALLED'
-  | 'APPLY_FAILED'
-  | 'AUTO_ROLLBACK'
-  | 'MANUAL_ROLLBACK';
-
-export interface OtaEventItem {
-  kind: 'ota_event';
-  bundleId: string;
-  releaseId?: string;
-  type: OtaEventType;
-  durationMs?: number;
-  errorCode?: string;
-  patchUsed?: boolean;
-}
+/**
+ * OTA contract types — SDK-side mirror of the backend's ota.contracts.ts.
+ *
+ * These types are hand-maintained here AND mirrored in the backend.
+ * Golden JSON fixtures in packages/protocol/fixtures/ota/ are the SINGLE source
+ * of truth; conformance tests in both repos assert against them to prevent drift.
+ */
+
+// ── SDK → backend (POST /sdk/ota/check) ──────────────────────────────────────
+export interface OtaCheckRequest {
+  appVersion: string;
+  platform: 'android' | 'ios';
+  arch?: string;
+  installationId: string;
+  currentBundleId?: string;
+  currentBundleHash?: string;
+
+  // ── C1: channel + targeting context ────────────────────────────────────────
+  // The backend DTO has accepted all of these since Sprint 9. The SDK declared
+  // none of them and `checkForUpdate` sent none, so every device in the field
+  // resolved to the `default` channel with an empty targeting context: beta
+  // channels were unreachable and the entire targeting-rule engine — country,
+  // segment, lifecycle, attributes — could never match. Sending them is what
+  // turns that already-built subsystem on.
+  /** Channel to pull from. Omitted means `default`. */
+  channelName?: string;
+  /** ISO 3166-1 alpha-2. The server fills this from the edge when absent. */
+  country?: string;
+  /** Free-form device attributes evaluated by ATTRIBUTE rules. */
+  attributes?: Record<string, string | number>;
+  /** CDP segment ids this installation belongs to. */
+  segmentIds?: string[];
+  /** Lifecycle stage (e.g. 'onboarding', 'activated', 'churned'). */
+  lifecycleStage?: string;
+
+  // ── Runtime compatibility context ──────────────────────────────────────────
+  // `appVersion` is a marketing string; these are the actual runtime contract.
+  // Serving a bundle built for a different runtime is the most common way an
+  // OTA product bricks an app, and without these fields the backend cannot
+  // even detect the mismatch, let alone refuse to serve it.
+  /** React Native version of the host binary, e.g. `"0.81.5"`. */
+  rnVersion?: string;
+  /** True when the JS engine is Hermes. */
+  hermes?: boolean;
+  /**
+   * Hermes bytecode (HBC) format version of the running engine. Independent of
+   * the RN release number. A mismatch either fails to load outright ("Wrong
+   * bytecode version. Expected 96 but got 98") or — worse — loads and crashes
+   * later on a path the older runtime does not expose.
+   */
+  hermesBytecodeVersion?: number;
+  /** True when running the New Architecture's bridgeless runtime. */
+  bridgeless?: boolean;
+}
+
+// ── backend → SDK ────────────────────────────────────────────────────────────
+export interface OtaCheckResponse {
+  action: 'NONE' | 'DOWNLOAD' | 'ROLLBACK';
+  bundle?: OtaBundlePayload;
+}
+
+export interface OtaBundlePayload {
+  id: string;
+  version: number;
+  url: string;         // presigned GET — short-TTL
+  size: number;
+  sha256: string;
+  signature?: string;  // ed25519 detached signature (hex)
+  isMandatory: boolean;
+  /**
+   * How to activate the bundle after install:
+   *   ON_NEXT_RESTART — nothing to do now; next cold start loads it (default)
+   *   ON_NEXT_RESUME  — restart the JS runtime when the app next returns to
+   *                     the foreground after a background stay
+   *   IMMEDIATE       — restart the JS runtime right after install
+   * Absent means ON_NEXT_RESTART, which is what every pre-installMode release
+   * actually did.
+   */
+  installMode?: 'ON_NEXT_RESTART' | 'ON_NEXT_RESUME' | 'IMMEDIATE';
+  releaseNote?: string;
+  patch?: OtaPatchPayload;
+  /**
+   * Identity marker compiled into this bundle at publish time.
+   *
+   * Recorded at install; compared after restart against the marker the RUNNING
+   * bundle carries. Its PRESENCE is the important part — knowing a bundle
+   * definitely has a marker is what turns "no marker after restart" from
+   * ambiguous into proof that the install never took effect.
+   */
+  identityToken?: string;
+}
+
+export interface OtaPatchPayload {
+  url: string;
+  size: number;
+  sha256: string;
+  baseBundleId: string;
+}
+
+// ── Adoption telemetry (rides the unified batch envelope as kind:'ota_event') ──
+export type OtaEventType =
+  | 'CHECK'
+  | 'DOWNLOAD_STARTED'
+  | 'DOWNLOAD_COMPLETE'
+  | 'INSTALLED'
+  | 'APPLY_FAILED'
+  | 'AUTO_ROLLBACK'
+  | 'MANUAL_ROLLBACK';
+
+export interface OtaEventItem {
+  kind: 'ota_event';
+  bundleId: string;
+  releaseId?: string;
+  type: OtaEventType;
+  durationMs?: number;
+  errorCode?: string;
+  patchUsed?: boolean;
+}

package/src/features/ota/deviceAttributes.ts

@@ -0,0 +1,46 @@
+import { Dimensions, Platform } from 'react-native';
+
+/**
+ * Hardware/OS context auto-attached to OTA check payloads so ATTRIBUTE targeting
+ * rules can address device classes without any host-app wiring:
+ *
+ *   deviceModel  — 'SM-A155F', '23129RAA4G'… (Android; iOS does not expose it in JS)
+ *   manufacturer — 'samsung', 'xiaomi'… (lowercased: rules shouldn't fail on casing)
+ *   brand        — 'redmi' vs manufacturer 'xiaomi' — sub-brands are real segments
+ *   osVersion    — Android Release ('14') / iOS version ('17.5')
+ *   formFactor   — 'phone' | 'tablet' | 'tv' (Android tablets via the 600dp
+ *                  smallest-width convention — the same line AndroidX draws)
+ *
+ * Host-supplied attributes always win on key collision: an app that knows better
+ * (e.g. its own device tiering) must not be overridden by generic detection.
+ * Everything here is best-effort — a missing constant yields a missing key,
+ * never a guessed value.
+ */
+export function deviceTargetingAttributes(): Record<string, string> {
+    const out: Record<string, string> = {};
+    try {
+        const c = (Platform.constants ?? {}) as Record<string, unknown>;
+        if (Platform.OS === 'android') {
+            if (typeof c.Model === 'string' && c.Model) out.deviceModel = c.Model;
+            if (typeof c.Manufacturer === 'string' && c.Manufacturer) {
+                out.manufacturer = c.Manufacturer.toLowerCase();
+            }
+            if (typeof c.Brand === 'string' && c.Brand) out.brand = c.Brand.toLowerCase();
+            if (typeof c.Release === 'string' && c.Release) out.osVersion = c.Release;
+            const screen = Dimensions.get('screen');
+            const smallestDp = Math.min(screen.width, screen.height);
+            out.formFactor = Platform.isTV ? 'tv' : smallestDp >= 600 ? 'tablet' : 'phone';
+        } else {
+            const osVersion = typeof c.osVersion === 'string' ? c.osVersion : String(Platform.Version ?? '');
+            if (osVersion) out.osVersion = osVersion;
+            out.formFactor = Platform.isTV
+                ? 'tv'
+                : (c as { interfaceIdiom?: string }).interfaceIdiom === 'pad'
+                  ? 'tablet'
+                  : 'phone';
+        }
+    } catch {
+        // Targeting enrichment must never break a check. Missing keys are honest.
+    }
+    return out;
+}

package/src/features/ota/environment.ts

@@ -0,0 +1,199 @@
+import { Platform } from 'react-native';
+
+/**
+ * OTA runtime environment detection.
+ *
+ * ── Why this file exists ────────────────────────────────────────────────────
+ *
+ * Our Android OTA resolves the active bundle through
+ * `MainApplication.getJSBundleFile()`. That is a *bridge-mode* API.
+ *
+ * Under the New Architecture (bridgeless), the app is built by
+ * `DefaultReactHost` instead — and until React Native 0.76.1,
+ * `DefaultReactNativeHost.toReactHost()` never forwarded `jsBundleFile`:
+ *
+ *     // RN 0.74.1 — DefaultReactNativeHost.kt
+ *     public fun toReactHost(context: Context): ReactHost =
+ *         DefaultReactHost.getDefaultReactHost(
+ *             context, packages, jsMainModuleName,
+ *             bundleAssetName ?: "index",   // <- jsBundleFile is NEVER passed
+ *             isHermesEnabled ?: true)
+ *
+ *     // RN 0.74.1 — DefaultReactHost.kt
+ *     val jsBundleLoader =
+ *         JSBundleLoader.createAssetLoader(context, "assets://$jsBundleAssetPath", true)
+ *
+ * The loader is hardcoded to the APK asset. `getJSBundleFile()` is never
+ * consulted, so an update stages, applies, reports INSTALLED, restarts — and
+ * the app loads the bundle baked into the APK. Every signal says success and
+ * nothing happened. This is the same failure that killed CodePush on modern RN.
+ *
+ * Fixed upstream in 0.76.1 (`jsBundleFile` is threaded through). Verified
+ * present in 0.81.5.
+ *
+ * We refuse to run rather than pretend to work. A loud failure at startup is
+ * recoverable; a silent no-op that reports success is not — it corrupts the
+ * adoption metrics, the guard thresholds, and every rollout decision made
+ * from them.
+ */
+
+/** First React Native version where bridgeless honours `getJSBundleFile()`. */
+export const MIN_BRIDGELESS_RN = { major: 0, minor: 76, patch: 1 } as const;
+
+/**
+ * React Native 0.82 REMOVED `ReactNativeHost`. The New Architecture became
+ * mandatory and `newArchEnabled=false` was withdrawn, so the legacy
+ * `override fun getJSBundleFile()` integration does not merely stop working —
+ * it does not compile. From 0.82 the only correct integration is passing
+ * `jsBundleFilePath` straight to `getDefaultReactHost(...)`.
+ *
+ * We cannot see which integration a host app used, so this is not a block. It
+ * drives a startup hint, and the post-restart identity check is what actually
+ * catches a host that got it wrong.
+ */
+export const REACT_HOST_ONLY_RN = { major: 0, minor: 82, patch: 0 } as const;
+
+export interface RnVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+export interface OtaEnvironment {
+  /** Parsed React Native version, or null when it could not be determined. */
+  rnVersion: RnVersion | null;
+  /** `"0.76.1"`, or null. Sent to the backend for compatibility gating. */
+  rnVersionString: string | null;
+  /** True when running on the New Architecture's bridgeless runtime. */
+  bridgeless: boolean;
+  /** True when the JS engine is Hermes. */
+  hermes: boolean;
+  /**
+   * Hermes bytecode (HBC) format version of the *running* engine. This is the
+   * file-format compatibility number, NOT a React Native release number — the
+   * two move independently. A bundle compiled by a different hermesc can be
+   * rejected outright ("Wrong bytecode version. Expected 96 but got 98") or,
+   * worse, load fine and crash later on a path the older runtime lacks.
+   */
+  hermesBytecodeVersion: number | null;
+  /** False when OTA cannot work on this runtime and must not be enabled. */
+  supported: boolean;
+  /** Human-readable explanation when `supported` is false. */
+  blockReason: string | null;
+  /**
+   * True on RN >= 0.82, where `ReactNativeHost` no longer exists and the only
+   * valid integration is `getDefaultReactHost(..., jsBundleFilePath = …)`.
+   * Used to make the startup diagnostic name the right fix.
+   */
+  requiresReactHostIntegration: boolean;
+}
+
+function compare(a: RnVersion, b: { major: number; minor: number; patch: number }): number {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return a.patch - b.patch;
+}
+
+function readRnVersion(): RnVersion | null {
+  // `Platform.constants.reactNativeVersion` is public API and present on both
+  // platforms since 0.62. Preferred over the deep `Libraries/Core/...` import,
+  // which is private and has moved between releases.
+  try {
+    const v = (Platform as unknown as { constants?: { reactNativeVersion?: RnVersion } })
+      .constants?.reactNativeVersion;
+    if (v && typeof v.major === 'number' && typeof v.minor === 'number') {
+      return { major: v.major, minor: v.minor, patch: v.patch ?? 0 };
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+function readBridgeless(): boolean {
+  // Set by the runtime itself when the bridgeless host is in use. Absent on
+  // the old architecture, so `=== true` is the correct test.
+  try {
+    return (globalThis as unknown as { RN$Bridgeless?: boolean }).RN$Bridgeless === true;
+  } catch {
+    return false;
+  }
+}
+
+interface HermesInternalShape {
+  getRuntimeProperties?: () => Record<string, unknown>;
+}
+
+function readHermes(): { hermes: boolean; bytecodeVersion: number | null } {
+  try {
+    const h = (globalThis as unknown as { HermesInternal?: HermesInternalShape }).HermesInternal;
+    if (!h) return { hermes: false, bytecodeVersion: null };
+
+    let bytecodeVersion: number | null = null;
+    const props = h.getRuntimeProperties?.();
+    if (props) {
+      // Hermes reports this as "Bytecode Version"; the value has been both a
+      // number and a numeric string across releases, so coerce and validate.
+      const raw = props['Bytecode Version'];
+      const n = typeof raw === 'string' ? Number(raw) : raw;
+      if (typeof n === 'number' && Number.isFinite(n)) bytecodeVersion = n;
+    }
+    return { hermes: true, bytecodeVersion };
+  } catch {
+    return { hermes: false, bytecodeVersion: null };
+  }
+}
+
+let cached: OtaEnvironment | null = null;
+
+/**
+ * Detect the runtime environment and decide whether OTA can function at all.
+ * Result is cached — none of these values change during a process lifetime.
+ */
+export function detectOtaEnvironment(): OtaEnvironment {
+  if (cached) return cached;
+
+  const rnVersion = readRnVersion();
+  const bridgeless = readBridgeless();
+  const { hermes, bytecodeVersion } = readHermes();
+
+  let supported = true;
+  let blockReason: string | null = null;
+
+  if (bridgeless && rnVersion) {
+    if (compare(rnVersion, MIN_BRIDGELESS_RN) < 0) {
+      supported = false;
+      blockReason =
+        `React Native ${rnVersion.major}.${rnVersion.minor}.${rnVersion.patch} is running ` +
+        `bridgeless (New Architecture), but jsBundleFile was not threaded through ` +
+        `DefaultReactHost until RN 0.76.1. getJSBundleFile() is ignored on this runtime, ` +
+        `so an OTA bundle would install successfully and never actually load. ` +
+        `Upgrade to React Native >= 0.76.1, or disable the New Architecture.`;
+    }
+  } else if (bridgeless && !rnVersion) {
+    // Can't prove it's broken, and blocking every app whose version we failed
+    // to read would be worse than the bug. Warn instead of blocking.
+    blockReason = null;
+  }
+
+  cached = {
+    rnVersion,
+    rnVersionString: rnVersion
+      ? `${rnVersion.major}.${rnVersion.minor}.${rnVersion.patch}`
+      : null,
+    bridgeless,
+    hermes,
+    hermesBytecodeVersion: bytecodeVersion,
+    supported,
+    blockReason,
+    requiresReactHostIntegration: rnVersion
+      ? compare(rnVersion, REACT_HOST_ONLY_RN) >= 0
+      : false,
+  };
+  return cached;
+}
+
+/** Test seam — the detection result is process-lifetime cached. */
+export function _resetOtaEnvironmentCache(): void {
+  cached = null;
+}

package/src/features/ota/geoCountry.ts

@@ -0,0 +1,85 @@
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Device country via an edge Worker — the workaround for an API that is not
+ * behind a geo-stamping CDN.
+ *
+ * The clean architecture is the API itself resolving `cf-ipcountry` at its own
+ * edge (see backend `resolveCountry`) — the device can't forge it and every
+ * request carries it. When the API record isn't proxied, that header never
+ * exists, so this module asks a Cloudflare Worker (which DOES see the device's
+ * edge geo) and attaches the answer to the OTA check payload. Host-supplied
+ * country always wins; the server treats a client country as locale-grade, not
+ * proof of location.
+ *
+ * Failure-soft by design: a dead Worker, a timeout, or a bad payload leaves the
+ * country unset — an unknown country must render as unknown, never be guessed.
+ */
+
+/** Default lookup endpoint. Overridable via {@link setGeoEndpoint}. */
+const DEFAULT_GEO_ENDPOINT = 'https://get-location.imohamadfahmy.workers.dev/';
+
+const K_COUNTRY = 'scalebun.ota.geoCountry';
+const K_FETCHED_AT = 'scalebun.ota.geoCountryAt';
+const TTL_MS = 24 * 60 * 60 * 1000; // countries change when people travel — daily is plenty
+const TIMEOUT_MS = 2500;
+
+/** Cloudflare's non-countries: Tor exits and internal probes. Unknown, not a place. */
+const NON_COUNTRIES = new Set(['XX', 'T1', 'ZZ']);
+
+let endpoint = DEFAULT_GEO_ENDPOINT;
+let memory: string | null = null;
+let inFlight: Promise<void> | null = null;
+const storage = createStorageBackend();
+
+/** Override the lookup endpoint (e.g. a self-hosted Worker). */
+export function setGeoEndpoint(url: string): void {
+    endpoint = url;
+}
+
+/**
+ * Synchronous read of the cached country (uppercase ISO 3166-1 alpha-2), or
+ * null when no fresh lookup has ever succeeded. Never triggers network.
+ */
+export function getDeviceCountry(): string | null {
+    if (memory) return memory;
+    const stored = storage.get(K_COUNTRY);
+    const at = parseInt(storage.get(K_FETCHED_AT) ?? '0', 10) || 0;
+    if (stored && Date.now() - at < TTL_MS) {
+        memory = stored;
+        return stored;
+    }
+    return null;
+}
+
+/**
+ * Refresh the cache from the Worker if stale. Fire-and-forget: call it at
+ * orchestrator init; the first check of a cold install may go out without a
+ * country (the server stores the country per device on later checks anyway).
+ */
+export function prefetchDeviceCountry(): Promise<void> {
+    if (getDeviceCountry()) return Promise.resolve(); // fresh — nothing to do
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(endpoint, { signal: controller.signal });
+            if (!res.ok) return;
+            const body = (await res.json()) as { country?: unknown };
+            const raw = typeof body?.country === 'string' ? body.country.trim().toUpperCase() : '';
+            if (!/^[A-Z]{2}$/.test(raw) || NON_COUNTRIES.has(raw)) return;
+            memory = raw;
+            storage.set(K_COUNTRY, raw);
+            storage.set(K_FETCHED_AT, String(Date.now()));
+            logger.debug(`[OTA] Device country resolved: ${raw}`);
+        } catch (err: any) {
+            logger.debug(`[OTA] Geo lookup skipped: ${err?.message ?? err}`);
+        } finally {
+            clearTimeout(timer);
+            inFlight = null;
+        }
+    })();
+    return inFlight;
+}

package/src/features/ota/retry.ts

@@ -0,0 +1,123 @@
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Retry with exponential backoff and full jitter.
+ *
+ * ── Why ─────────────────────────────────────────────────────────────────────
+ *
+ * The OTA path had no retry at all. A download that failed on a flaky mobile
+ * connection returned an error and the device then waited for the next cold
+ * start to try again — which on a phone is often hours, and on a device that
+ * is never fully restarted, effectively never. On mobile networks a single
+ * transient failure is the common case, not the exception.
+ *
+ * Full jitter (`random(0, backoff)` rather than `backoff`) matters more here
+ * than in most clients: every device on a release checks in against the same
+ * schedule, so a fixed backoff would retry the whole fleet in lockstep and
+ * turn one origin blip into a synchronised thundering herd.
+ */
+
+export interface RetryOptions {
+  /** Total attempts including the first. Default 3. */
+  attempts?: number;
+  /** Base delay in ms for the first backoff. Default 1000. */
+  baseDelayMs?: number;
+  /** Upper bound on any single delay. Default 30_000. */
+  maxDelayMs?: number;
+  /** Label used in log lines. */
+  label?: string;
+  /**
+   * Decides whether a given failure is worth retrying. Default: retry
+   * everything. Callers should pass a predicate that returns false for
+   * failures that will never succeed on a retry (4xx, hash mismatch), so a
+   * device does not burn battery re-requesting something already rejected.
+   */
+  isRetryable?: (err: unknown) => boolean;
+}
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** Exposed for tests; `Math.random` is the only nondeterminism in the schedule. */
+export function backoffDelay(
+  attemptIndex: number,
+  baseDelayMs: number,
+  maxDelayMs: number,
+  random: () => number = Math.random,
+): number {
+  const exponential = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attemptIndex));
+  return Math.floor(random() * exponential);
+}
+
+/**
+ * Run `fn`, retrying on failure with exponential backoff.
+ * Rethrows the last error once attempts are exhausted.
+ */
+export async function retryWithBackoff<T>(
+  fn: (attempt: number) => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+  const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const label = options.label ?? 'operation';
+  const isRetryable = options.isRetryable ?? (() => true);
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+
+      if (!isRetryable(err)) {
+        logger.debug(`[OTA] ${label} failed with a non-retryable error — not retrying`);
+        throw err;
+      }
+
+      const isLast = attempt === attempts - 1;
+      if (isLast) break;
+
+      const delay = backoffDelay(attempt, baseDelayMs, maxDelayMs);
+      logger.debug(
+        `[OTA] ${label} failed (attempt ${attempt + 1}/${attempts}) — retrying in ${delay}ms`,
+      );
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * True for failures that a later attempt could plausibly survive.
+ *
+ * Network errors and 5xx/429 are retryable. A 4xx other than 429 is the server
+ * telling us the request itself is wrong — retrying it just wastes battery.
+ */
+export function isRetryableNetworkError(err: unknown): boolean {
+  const status = (err as { status?: number } | undefined)?.status;
+  if (typeof status === 'number') {
+    if (status === 429) return true;
+    if (status >= 500) return true;
+    if (status >= 400) return false;
+  }
+  // fetch() rejects with a TypeError on DNS failure, connection refused, and
+  // airplane mode — all of which are exactly what we want to retry.
+  return true;
+}
+
+/** Error carrying an HTTP status so `isRetryableNetworkError` can classify it. */
+export class HttpStatusError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+  ) {
+    super(message);
+    this.name = 'HttpStatusError';
+  }
+}