@scalebun-release/react-native 2.5.0

package/lib/typescript/features/ota/OtaOrchestrator.d.ts

@@ -0,0 +1,287 @@
+import type { OtaCheckResponse, OtaBundlePayload } from './OtaTypes';
+export interface SyncResult {
+    /**
+     * `WITHHELD` means the device reported root/jailbreak indicators and the host
+     * configured `onCompromisedDevice: 'withhold'`. It is NOT `UP_TO_DATE`: the
+     * device may well be behind, we simply declined to find out. Collapsing the
+     * two would make a withheld fleet indistinguishable from a current one.
+     */
+    status: 'UP_TO_DATE' | 'UPDATE_INSTALLED' | 'ROLLED_BACK' | 'ERROR' | 'WITHHELD';
+    bundle?: OtaBundlePayload;
+    error?: string;
+    /** True when the server-side release has isMandatory set */
+    isMandatory?: boolean;
+}
+/** Boot-guard configuration */
+export interface BootGuardConfig {
+    /**
+     * Milliseconds the app must run without crashing after an OTA update
+     * before the boot-guard marker is cleared. Default: 10_000 (10s).
+     */
+    healthyAfterMs?: number;
+    /**
+     * @deprecated Not honoured, and never was — nothing in JS reads this field.
+     *
+     * The boot-attempt limit lives in native code, where the counter it bounds is
+     * incremented (`MAX_BOOT_ATTEMPTS` in `SlotManager.kt` / `OtaSlotManager.swift`,
+     * both 2). Setting it here has no effect; the field is kept only so existing
+     * call sites keep compiling. Change the limit natively, or file a request for
+     * it to be plumbed through `initOutbox`-style native config.
+     */
+    maxRevertAttempts?: number;
+    /**
+     * What to do when the device reports root/jailbreak indicators.
+     *
+     *   'allow'    — DEFAULT. Check, download and install as normal. The
+     *                indicators are still detected, still logged, and still sent
+     *                with the check request as telemetry.
+     *   'withhold' — Do not check for or install updates on this device. The
+     *                device stays on whatever bundle it is already running.
+     *
+     * The default is `'allow'` and must stay `'allow'`. Flipping it would
+     * silently stop updates for every existing host app — including the ones
+     * whose "indicators" are a developer's test-keys build or a false positive —
+     * which is a far worse outcome than the risk it mitigates. Withholding is an
+     * opt-in a security-sensitive host makes with knowledge of its own users.
+     *
+     * What this is and is not: root defeats any check made from inside the app,
+     * so this is a POLICY, not a security boundary. A rooted device can patch the
+     * check out. What it does buy is that the SDK stops handing fresh, signed
+     * bundles to a device whose OTA slot other privileged processes can rewrite,
+     * and that the decision is auditable — an `UPDATE_WITHHELD` OTA event is
+     * emitted every time it fires, so the host never has to infer it from
+     * silence.
+     *
+     * Mobile only by nature. The web SDK ships no OTA lane at all — there is no
+     * bundle slot on a device to protect and no web counterpart to this flag.
+     */
+    onCompromisedDevice?: 'allow' | 'withhold';
+}
+export declare class OtaOrchestrator {
+    private enabled;
+    private currentBundle;
+    /**
+     * The bundle this process is running, once hydrated from the native slots.
+     * Read-only view for integrations (e.g. the CodePush shim's
+     * getUpdateMetadata) that need to report the running version.
+     */
+    getCurrentBundle(): OtaBundlePayload | null;
+    private isRestartRequiredState;
+    /**
+     * The sync currently running, if any. sync() had NO concurrency control:
+     * every caller started a full check/download/stage/apply cycle against the
+     * SAME slot directories. Two of them overlapping is not a wasted request,
+     * it is a corrupted install — native stage() ends with "remove next/,
+     * rename tmp -> next/" while apply() is doing "move next/ -> current/", so
+     * one racing the other throws and apply() can leave NO current/ slot at
+     * all. A host with a screen that syncs on mount and another that syncs on
+     * foreground reproduces this in seconds; on 2026-09-21 it cost two devices
+     * that could only be recovered by reinstalling.
+     */
+    private syncInFlight;
+    /** When the last network check actually went out (see MIN_CHECK_INTERVAL_MS). */
+    private lastCheckAt;
+    /**
+     * A bundle that is staged and waiting for its restart.
+     *
+     * Kept SEPARATE from `currentBundle`, which must keep naming the bundle
+     * this process is actually executing. Overwriting `currentBundle` at apply
+     * time told the server the device was already running code it had never
+     * run, so the next check was answered with the NEXT release instead of
+     * "up to date" — which is how a single launch chained three installs. It
+     * also mis-attributed every CHECK and BOOT_SUCCESS event to a bundle the
+     * device had not booted.
+     */
+    private pendingBundle;
+    /** Root/jailbreak indicators observed at init; empty when none found. */
+    private integrityIndicators;
+    /**
+     * The native detector was actually asked and answered on this launch.
+     *
+     * Kept separate from an empty `integrityIndicators` because the two are not
+     * the same fact: `false` means never measured (no native module, or the read
+     * threw), `true` with an empty list means measured and clean. Reporting the
+     * first as the second would show an unmeasured fleet as a clean one.
+     */
+    private integrityMeasured;
+    private healthyTimer;
+    private bootGuardConfig;
+    private environment;
+    /** One-time boot checks have run in this process (init is idempotent). */
+    private initialized;
+    private storageBackend;
+    /**
+     * Initialize the orchestrator. Checks for boot-guard recovery state.
+     *
+     * Signature enforcement is no longer a JS concern: signed releases are
+     * verified and staged in NATIVE code against RSA keys embedded in the app
+     * package (SB-OTA-RSA-SHA256-V1), and unsigned releases keep working on
+     * SHA-256 integrity alone. There is nothing for the host to configure here.
+     */
+    init(config?: BootGuardConfig): void;
+    /**
+     * Read the active slot back into `currentBundle` so the next check reports
+     * what this device is genuinely running.
+     */
+    /**
+     * Parse the native slot state once. Returns null when the module is absent or
+     * the payload is unreadable — every caller treats that as "factory bundle".
+     */
+    private readSlotState;
+    private hydrateCurrentBundleFromSlots;
+    /**
+     * Compare the bundle the slot manager believes is active against the identity
+     * marker compiled into the bundle that actually loaded.
+     *
+     * A mismatch means the install path reported success while the runtime kept
+     * executing different code — the silent no-op this whole guard exists for.
+     * It is reported as APPLY_FAILED, because that is what happened, regardless
+     * of what the previous session's telemetry claimed.
+     *
+     * The expectation recorded at install time is what makes this conclusive.
+     * Without it, a missing marker is ambiguous — it could be a bundle published
+     * before markers existed, or an install that never took effect. Having
+     * written down "this bundle definitely carries marker X" before restarting,
+     * a missing marker afterwards can only mean the second.
+     */
+    private verifyRunningBundleIdentity;
+    private static readonly INSTALL_EXPECTATION_KEY;
+    private recordInstallExpectation;
+    private readInstallRecord;
+    /**
+     * Drop the identity token once the install has been proven, keeping the rest
+     * of the record.
+     *
+     * The record does two jobs: it proves an install took effect (once), and it
+     * maps the native slot's sha256 back to a bundle id (for the life of that
+     * bundle). Only the first job is finished after a successful verification, so
+     * only the token is retired.
+     */
+    private retireIdentityToken;
+    private clearInstallExpectation;
+    private storage;
+    /**
+     * Sprint 5 (S5-NAT-1): Check if the native boot guard reverted us on this cold start.
+     * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
+     * and no 'current' OTA bundle, the native layer already reverted.
+     */
+    private checkBootGuardRecovery;
+    isEnabled(): boolean;
+    /**
+     * Root/jailbreak indicators detected on this device, as stable reason strings.
+     * Empty means nothing was detected — not proof the device is clean.
+     */
+    deviceIntegrityIndicators(): string[];
+    /**
+     * Should this device be refused an update?
+     *
+     * TRUE only when BOTH are so: the host opted into `'withhold'`, and the native
+     * detector actually found something. An empty indicator list is never a reason
+     * to withhold — "nothing detected" is the normal state of every healthy
+     * device, and treating it as a reason would brick updates for the whole fleet
+     * the moment a host set the flag.
+     */
+    private shouldWithhold;
+    /**
+     * Announce the refusal, once per decision point.
+     *
+     * A withheld update must be visible as a decision, not as an absence. The
+     * event carries the indicators that drove it so the host can log WHY, and it
+     * names the bundle the device stays on (`'unknown'` for a device still on the
+     * factory bundle, which owns no OTA bundle id).
+     */
+    private emitWithheld;
+    isRestartRequired(): boolean;
+    /**
+     * Perform an OTA check against the backend endpoint.
+     */
+    checkForUpdate(requestParams: {
+        apiUrl: string;
+        clientKey: string;
+        appVersion: string;
+        installationId: string;
+        channelName?: string;
+        country?: string;
+        attributes?: Record<string, string | number>;
+        segmentIds?: string[];
+        lifecycleStage?: string;
+    }): Promise<OtaCheckResponse>;
+    /**
+     * Downloads, stage, and apply an update in one step.
+     * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
+     */
+    /**
+     * Minimum gap between network checks. Not a policy, a stampede guard: an
+     * app that syncs on mount AND on every foreground transition can otherwise
+     * issue a burst of identical checks. Small enough not to get in the way of
+     * publishing and testing a release.
+     */
+    private static readonly MIN_CHECK_INTERVAL_MS;
+    /**
+     * Check, download, stage and apply — at most ONE at a time.
+     *
+     * Concurrent callers join the sync already running rather than starting a
+     * second one, and a call made while an update is already staged returns
+     * without touching the slots: the staged bundle has to be activated by a
+     * restart before anything else can usefully happen, and re-checking here
+     * is what used to chain a second install onto the first.
+     */
+    sync(rawParams: Parameters<OtaOrchestrator['runSync']>[0]): Promise<SyncResult>;
+    private runSync;
+    /**
+     * Sprint 5 (S5-NAT-1): Boot-guard heartbeat.
+     *
+     * After booting from an OTA bundle, start a timer. If the app survives
+     * `healthyAfterMs` without crashing, call `markHealthy()` to clear the
+     * native boot-guard marker. If JS crashes before the timer fires, the
+     * marker stays set and native code reverts on next cold start.
+     */
+    private startBootGuardHeartbeat;
+    private bootFailedThisLaunch;
+    /**
+     * A render error was caught while a freshly-applied bundle is still inside its health window.
+     *
+     * WHY. The boot guard's only evidence of a bad bundle is that the process died before
+     * `healthyAfterMs`. An error boundary with a fallback keeps the process ALIVE: the user sees the
+     * fallback, the timer fires, `markHealthy()` runs, and a bundle that cannot render its first
+     * screen is recorded as healthy and never reverted. ScaleBunErrorBoundary calls this so the
+     * marker stays set: the next cold start counts toward the bundle's revert exactly as a crash
+     * would have.
+     *
+     * No-op outside the window (the bundle already proved itself, or this launch is not an OTA
+     * bundle's first run), so a boundary catching an ordinary bug later in the session never
+     * condemns a healthy release.
+     *
+     * @returns true when the window was open and `markHealthy` has been withheld.
+     */
+    noteBootFailure(): boolean;
+    /** One-shot guard so repeated syncs cannot stack resume listeners. */
+    private resumeRestartArmed;
+    /**
+     * ON_NEXT_RESUME: restart the JS runtime the next time the app returns to
+     * the foreground after genuinely being in the background.
+     *
+     * The staged bundle is already applied at this point — the restart is purely
+     * about WHEN the user experiences the reload. Two deliberate choices:
+     *
+     *  - Armed only after a real background→active transition, never on the
+     *    initial 'active' state, so installing while the user is mid-session
+     *    does not instantly yank the screen out from under them.
+     *  - One-shot. The listener removes itself after firing (or after the
+     *    restart makes the whole question moot).
+     */
+    private armResumeRestart;
+    /**
+     * Reload the JS app bundle to apply the new update immediately.
+     *
+     * Order matters: the native `restartApp()` is the only path that works in
+     * RELEASE builds. `DevSettings.reload()` looks callable there too — it
+     * logged, returned, and reloaded nothing when tested live on a release APK,
+     * which made every "restart" this SDK ever promised a silent no-op in
+     * production. DevSettings remains as the dev-build fallback for hosts that
+     * have not rebuilt native yet.
+     */
+    restart(): void;
+}
+export declare const otaOrchestrator: OtaOrchestrator;
+//# sourceMappingURL=OtaOrchestrator.d.ts.map

package/lib/typescript/features/ota/OtaTypes.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * OTA-TELEMETRY-SPEC — status (spec §84-86)
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Items 1-3 are DONE. All were additive and backward-compatible: old installed
+ * clients simply omit the new fields and never emit the new types, and the
+ * backend ingests nullable columns. Because they alter device runtime behaviour,
+ * verify against a real RN build + device kill-test before release — Metro
+ * cannot exercise the boot guard.
+ *
+ * 1. releaseId end-to-end — DONE. `recordInstallExpectation` persists the
+ *    release id (so a rollback reported launches later can still name it),
+ *    `hydrateCurrentBundleFromSlots` restores it, every emit site passes it, and
+ *    `deliverOtaEvents` maps it onto the wire item.
+ *
+ * 2. CHECK + OFFERED — DONE. CHECK is emitted at the top of `sync()` for devices
+ *    already on an OTA bundle (a device on the factory bundle has no owned
+ *    bundle id to name, and the server drops rows it cannot resolve — those are
+ *    counted server-side instead). OFFERED is emitted on `action === 'DOWNLOAD'`
+ *    before any bytes move.
+ *
+ * 3. BOOT_SUCCESS — DONE. Emitted from the boot-guard heartbeat once the bundle
+ *    has actually booted and survived to `healthyAfterMs`. INSTALLED is kept and
+ *    still means "staged + swapped", but activation should be measured on
+ *    BOOT_SUCCESS: INSTALLED fires before the bundle has run, so it credits
+ *    bundles that installed and then crash-reverted.
+ *
+ * 4. Stamp the running OTA bundle onto session/crash telemetry — NOT DONE.
+ *    `SessionMetadata.bundleId` is the NATIVE app package id, not the OTA bundle,
+ *    so crashes cannot currently be attributed to the bundle that produced them
+ *    (release-health crash impact). Needs optional otaBundleId?/otaBundleVersion?
+ *    (distinct fields — do NOT overload bundleId) sourced from
+ *    `otaOrchestrator.getCurrentBundle()` at session start, plus the matching
+ *    backend columns and a Prisma migration.
+ *
+ * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
+ * reason); add a new optional field if the two must be distinguished.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+export interface OtaCheckRequest {
+    appVersion: string;
+    platform: 'android' | 'ios';
+    arch?: string;
+    installationId: string;
+    currentBundleId?: string;
+    currentBundleHash?: string;
+    /**
+     * What this build can do with an offer. `signed_patch_v1`: the native module
+     * has `verifyAndStagePatch`, so a SIGNED release can be applied from a patch.
+     * The server offers signed patches only to devices that say so — every older
+     * build would download the patch URL for nothing. Absent = no capabilities.
+     * Additive and optional (the backend DTO does not whitelist-strip).
+     */
+    otaCapabilities?: string[];
+    /**
+     * Trusted key IDs embedded in this app binary, for SDK trust coverage
+     * (CICDPAGE §12). Telemetry only — never a source of server-side trust.
+     */
+    trustedKeyIds?: string[];
+    /**
+     * Root/jailbreak indicator strings observed on this device at init, verbatim
+     * from the native detectors (`DeviceIntegrity.kt` / `DeviceIntegrity.swift`).
+     * Absent — not `[]` — when the native module could not be asked, so "not
+     * measured" stays distinguishable from "measured, nothing found".
+     *
+     * TELEMETRY ONLY, exactly like `trustedKeyIds`: never a source of server-side
+     * trust. Root defeats any check made from inside the app, so a device can
+     * always send `[]`; the value of the field is fleet-level ("what share of
+     * installs report indicators?"), never per-device enforcement.
+     *
+     * ADDITIVE AND OPTIONAL, deliberately. As of 2026-09-21 the backend's
+     * `OtaCheckDto` declares no such field, and the global ValidationPipe runs
+     * with `whitelist: false, forbidNonWhitelisted: false` — so sending it is
+     * safe (no 400, no stripping of the fields around it) but the value is
+     * IGNORED server-side until the backend adds the property and a column. The
+     * withholding decision itself is therefore entirely client-side and does not
+     * wait on a backend deploy. Mobile only: the web SDK has no OTA lane at all,
+     * so there is no web counterpart to keep in step.
+     */
+    integrityIndicators?: string[];
+    /** 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;
+    /** 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;
+}
+export interface OtaCheckResponse {
+    action: 'NONE' | 'DOWNLOAD' | 'ROLLBACK';
+    bundle?: OtaBundlePayload;
+}
+export interface OtaBundlePayload {
+    id: string;
+    version: number;
+    /**
+     * The release this bundle is served AS (the backend now includes it — see
+     * ota.contracts.ts / ota-check.service.ts). Optional, for backward-compat with
+     * older backends. Carry it onto the emitted OtaEventItem.releaseId so telemetry
+     * is attributable by RELEASE, not just bundle. See OTA-TELEMETRY-SPEC below.
+     */
+    releaseId?: string;
+    url: string;
+    size: number;
+    sha256: string;
+    signature?: string;
+    /**
+     * SB-OTA-RSA-SHA256-V1 release envelope. Present on signed releases; carries
+     * the protocol id, the id of the trusted RSA key the release was signed with,
+     * the canonical signed payload, and its signature. When present, the SDK hands
+     * the whole envelope to the native module (`verifyAndStageRelease`), which
+     * verifies the signature against the RSA public keys EMBEDDED in the app
+     * package and then downloads + integrity-checks + stages the artifact — JS
+     * never stages bytes it has not proven authentic, and never pins or verifies a
+     * key itself. Absent on legacy/unsigned releases, which fall back to
+     * `stageBundle` on SHA-256 integrity alone.
+     */
+    envelope?: {
+        protocol: string;
+        keyId: string;
+        signedPayload: string;
+        signature: string;
+    };
+    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;
+    /**
+     * SHA-256 of the bundle this patch was made FROM. When present, native refuses
+     * the patch unless the installed bundle hashes to it (a bundle id alone does
+     * not prove the bytes). Optional: older servers do not send it.
+     */
+    baseSha256?: string;
+}
+import type { OtaEventType as EmittedOtaEventType } from './OtaEventEmitter';
+export type OtaEventType = Exclude<EmittedOtaEventType, 'DOWNLOAD_PROGRESS' | 'UPDATE_WITHHELD'>;
+export interface OtaEventItem {
+    kind: 'ota_event';
+    bundleId: string;
+    releaseId?: string;
+    type: OtaEventType;
+    durationMs?: number;
+    errorCode?: string;
+    patchUsed?: boolean;
+}
+//# sourceMappingURL=OtaTypes.d.ts.map

package/lib/typescript/features/ota/deviceAttributes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare function deviceTargetingAttributes(): Record<string, string>;
+//# sourceMappingURL=deviceAttributes.d.ts.map

package/lib/typescript/features/ota/environment.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 declare const MIN_BRIDGELESS_RN: {
+    readonly major: 0;
+    readonly minor: 76;
+    readonly patch: 1;
+};
+/**
+ * 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 declare const REACT_HOST_ONLY_RN: {
+    readonly major: 0;
+    readonly minor: 82;
+    readonly patch: 0;
+};
+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;
+}
+/**
+ * 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 declare function detectOtaEnvironment(): OtaEnvironment;
+/** Test seam — the detection result is process-lifetime cached. */
+export declare function _resetOtaEnvironmentCache(): void;
+//# sourceMappingURL=environment.d.ts.map

package/lib/typescript/features/ota/geoCountry.d.ts

@@ -0,0 +1,14 @@
+/** Override the lookup endpoint (e.g. a self-hosted Worker). */
+export declare function setGeoEndpoint(url: string): void;
+/**
+ * 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 declare function getDeviceCountry(): string | 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 declare function prefetchDeviceCountry(): Promise<void>;
+//# sourceMappingURL=geoCountry.d.ts.map

package/lib/typescript/features/ota/retry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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;
+}
+/** Exposed for tests; `Math.random` is the only nondeterminism in the schedule. */
+export declare function backoffDelay(attemptIndex: number, baseDelayMs: number, maxDelayMs: number, random?: () => number): number;
+/**
+ * Run `fn`, retrying on failure with exponential backoff.
+ * Rethrows the last error once attempts are exhausted.
+ */
+export declare function retryWithBackoff<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * 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 declare function isRetryableNetworkError(err: unknown): boolean;
+/** Error carrying an HTTP status so `isRetryableNetworkError` can classify it. */
+export declare class HttpStatusError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+//# sourceMappingURL=retry.d.ts.map