@scalebun/react-native 1.11.0 → 1.13.0

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

@@ -7,42 +7,38 @@
  */
 /**
  * ═══════════════════════════════════════════════════════════════════════════
- * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * OTA-TELEMETRY-SPEC — status (spec §84-86)
  * ═══════════════════════════════════════════════════════════════════════════
- * These close the SDK half of spec §84-86. All are ADDITIVE + backward-compatible
- * (new optional fields, new enum members, new no-throw emit calls); old installed
- * clients omit them and the backend ingests nullable/unknown fields. Each ALTERS
- * DEVICE RUNTIME BEHAVIOR, so land them behind a real RN build + device/kill-test
- * (Metro cannot exercise the boot-guard) — this file only carries the contract
- * types + this spec, not the runtime wiring.
+ * 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  (CRITICAL — root of the dashboard funnel mismatch)
- *    Backend already serves it: OtaBundlePayload.releaseId (done, this file +
- *    ota-check.service.ts). SDK TODO:
- *      - store payload.releaseId on the downloaded/installed bundle state, and
- *      - set `releaseId: bundle.releaseId` in the delivery mapper
- *        OtaOrchestrator.ts deliverOtaEvents (~:105) — currently only bundleId.
- *      Then ota_events carry releaseId and the funnel keys by release.
+ * 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. Emit CHECK + OFFERED  (funnel top is currently unmeasurable)
- *    - CHECK: emit at the start of checkForUpdate (OtaOrchestrator.ts ~:480),
- *      before the fetch. ('CHECK' type already exists — no emit site today.)
- *    - OFFERED: add 'OFFERED' to OtaEventType, emit when checkRes.action ===
- *      'DOWNLOAD' (~:619) before download begins.
+ * 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. Emit BOOT_SUCCESS  (honest activation signal)
- *    Add 'BOOT_SUCCESS' to OtaEventType and emit it from the boot-guard
- *    markHealthy path (OtaOrchestrator.ts ~:863). INSTALLED (~:794) is emitted
- *    optimistically BEFORE the bundle boots; keep it (it means "staged+swapped")
- *    but let the dashboard measure real activation on BOOT_SUCCESS. Optionally
- *    add 'VERIFIED' after signature check (~:635).
+ * 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
- *    SessionMetadata.bundleId is the NATIVE app package id, not the OTA bundle.
- *    Add optional otaBundleId?/otaBundleVersion? (distinct fields — do NOT
- *    overload bundleId) sourced from otaOrchestrator.getCurrentBundle() at
- *    session start (SessionManager.ts ~:451), so crashes attribute to the
- *    running bundle/version (release-health crash impact).
+ * 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.
@@ -126,7 +122,8 @@ export interface OtaPatchPayload {
     sha256: string;
     baseBundleId: string;
 }
-export type OtaEventType = 'CHECK' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_COMPLETE' | 'INSTALLED' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK';
+import type { OtaEventType as EmittedOtaEventType } from './OtaEventEmitter';
+export type OtaEventType = Exclude<EmittedOtaEventType, 'DOWNLOAD_PROGRESS'>;
 export interface OtaEventItem {
     kind: 'ota_event';
     bundleId: string;

package/lib/typescript/public/ScaleBunFacade.d.ts

@@ -82,6 +82,33 @@ declare class ScaleBunFacade {
      * than letting the app discover it as a silent no-update condition.
      */
     private _maybeStartOta;
+    /** Guards against overlapping config-driven OTA checks. */
+    private _otaCheckInFlight;
+    /** Wall clock of the last config-driven check, for the foreground floor. */
+    private _otaLastCheckAt;
+    private _otaForegroundListener;
+    /**
+     * Minimum gap between config-driven checks.
+     *
+     * A foreground transition is cheap to trigger — app switchers, permission
+     * dialogs and share sheets all produce one — so an unthrottled check would
+     * put a request on the hot path every time the user glanced away. Ten
+     * minutes is well below any realistic release cadence and well above that
+     * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+     * which is never throttled.
+     */
+    private static readonly OTA_MIN_CHECK_INTERVAL_MS;
+    /**
+     * Drive OTA checks from init config: once at startup, then on each
+     * foreground when `checkOnForeground` is on (the schema default).
+     *
+     * `appVersion` is resolved from the native bridge rather than asked of the
+     * integrator, because it gates the server's `targetAppVersion` semver check
+     * — sending a wrong or invented value is worse than sending none, and there
+     * is no honest default. If it cannot be resolved, the check is skipped with
+     * a warning instead of guessing.
+     */
+    private _startOtaChecks;
     private _autoEnableDebug;
     /** Boot the Phase 1 envelope tracking lane if an appId is configured. */
     private _maybeStartEventTracker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -121,7 +121,7 @@
     "@babel/runtime": "^7.25.0",
     "@jridgewell/sourcemap-codec": "1.5.5",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@scalebun/cli": "^1.10.2"
+    "@scalebun/cli": "^1.13.0"
   },
   "codegenConfig": {
     "name": "ScaleBunSpec",

package/src/core/constants/version.ts

@@ -8,4 +8,4 @@
  * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
  * version was introduced to solve.
  */
-export const SDK_VERSION = '1.11.0';
+export const SDK_VERSION = '1.13.0';

package/src/features/ota/OtaEventEmitter.ts

@@ -9,11 +9,17 @@
 // ── Event types ───────────────────────────────────────────────────────────────
 
 export type OtaEventType =
+  /** A check was made against the server. The denominator of the funnel. */
   | 'CHECK'
+  /** The server answered with a bundle for this device — the offer, before any bytes move. */
+  | 'OFFERED'
   | 'DOWNLOAD_STARTED'
   | 'DOWNLOAD_PROGRESS'
   | 'DOWNLOAD_COMPLETE'
+  /** Staged and swapped. Emitted optimistically, BEFORE the bundle has booted. */
   | 'INSTALLED'
+  /** The bundle booted and survived to the healthy mark — the honest activation signal. */
+  | 'BOOT_SUCCESS'
   | 'APPLY_FAILED'
   | 'AUTO_ROLLBACK'
   | 'MANUAL_ROLLBACK';
@@ -21,6 +27,12 @@ export type OtaEventType =
 export interface OtaEvent {
   type: OtaEventType;
   bundleId: string;
+  /**
+   * The release this bundle was served as. Optional because a bundle installed
+   * by an older SDK has no recorded release; present on everything emitted by a
+   * current one, so the delivery funnel can key by release rather than bundle.
+   */
+  releaseId?: string;
   version?: number;
   /** 0–100 for DOWNLOAD_PROGRESS */
   progress?: number;

package/src/features/ota/OtaOrchestrator.ts

@@ -106,6 +106,11 @@ async function deliverOtaEvents(params: {
     kind: 'ota_event' as const,
     type: e.type,
     bundleId: e.bundleId,
+    // Without this the backend stored a null releaseId on every row it ingested,
+    // while serving the release id on every check — so the delivery funnel could
+    // only ever be grouped by bundle, and a bundle re-promoted under a second
+    // release merged the two into one indistinguishable series.
+    releaseId: e.releaseId,
     installationId: params.installationId,
     // OTA bundles are compiled per platform, so this genuinely is ios|android. Narrowed via
     // resolveMobileOS so a non-mobile RN target is skipped rather than served an Android bundle.
@@ -158,14 +163,18 @@ export interface BootGuardConfig {
    */
   healthyAfterMs?: number;
   /**
-   * Maximum consecutive boot-guard reverts before the SDK stops trying
-   * OTA bundles and pins to the factory bundle. Default: 2.
+   * @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;
 }
 
 const DEFAULT_HEALTHY_AFTER_MS = 10_000;
-const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 
 export class OtaOrchestrator {
   private enabled = false;
@@ -257,22 +266,35 @@ export class OtaOrchestrator {
           `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`,
       );
 
+      // ONE read of the slot state, shared by both boot-time consumers.
+      //
+      // `getSlotState()` is CONSUME-ON-READ for the revert record: both native
+      // implementations delete it as they serialise, so that a rollback is
+      // reported exactly once instead of on every launch forever. Calling it
+      // twice therefore means the second caller never sees the revert — which is
+      // precisely what happened, since hydration ran first and swallowed it. It
+      // is also a blocking synchronous bridge call, so one read is cheaper.
+      const slotState = this.readSlotState();
+
       // Rehydrate which bundle we are running from the native slot state.
       // Without this `currentBundle` stays null for the whole process after a
       // restart, so every check reported no current bundle and the backend had
       // no way to know what the device was actually on.
-      this.hydrateCurrentBundleFromSlots();
+      this.hydrateCurrentBundleFromSlots(slotState);
 
       // Warm the device-country cache (edge Worker lookup) so checks can carry
       // a country when the API itself sits behind no geo-stamping CDN.
       // Fire-and-forget and failure-soft — a check without a country is valid.
       void prefetchDeviceCountry();
 
+      // Check if the boot guard fired on this launch (native reverted before JS
+      // loaded). BEFORE the identity check, because both read the install record
+      // and the identity check retires it — a revert must get its chance to name
+      // the bundle that failed while the record still describes it.
+      this.checkBootGuardRecovery(slotState);
+
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
-
-      // Check if the boot guard fired on this launch (native reverted before JS loaded)
-      this.checkBootGuardRecovery();
     });
   }
 
@@ -280,10 +302,21 @@ export class OtaOrchestrator {
    * Read the active slot back into `currentBundle` so the next check reports
    * what this device is genuinely running.
    */
-  private hydrateCurrentBundleFromSlots(): void {
-    if (!NativeScaleBunOta) return;
+  /**
+   * 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(): Record<string, any> | null {
+    if (!NativeScaleBunOta) return null;
+    try {
+      return JSON.parse(NativeScaleBunOta.getSlotState());
+    } catch {
+      return null;
+    }
+  }
+
+  private hydrateCurrentBundleFromSlots(state: Record<string, any> | null): void {
     try {
-      const state = JSON.parse(NativeScaleBunOta.getSlotState());
       const current = state?.current;
       if (!current?.sha256) return;
 
@@ -298,6 +331,7 @@ export class OtaOrchestrator {
         this.currentBundle = {
           id: record.bundleId,
           version: record.version,
+          releaseId: record.releaseId ?? undefined,
           sha256: record.sha256,
         } as OtaBundlePayload;
         __DEV__ && logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
@@ -335,49 +369,50 @@ export class OtaOrchestrator {
     if (!this.currentBundle) return;
 
     const running = readRunningBundleMarker();
-    const expected = this.readInstallExpectation();
+    const record = this.readInstallRecord();
 
-    // Stale record from an earlier install — the slot has moved on since.
-    if (expected && expected.bundleId !== this.currentBundle.id) {
+    // No record at all — installed by an SDK that predates install records, or
+    // local storage was cleared. NOTHING can be concluded here and nothing is
+    // reported: the marker is a random per-publish token, never the bundle id,
+    // so comparing the two would flag a false mismatch on every healthy launch.
+    if (!record) return;
+
+    // The record describes a bundle that is no longer the active one (a revert,
+    // or a bundle staged by another path). It cannot verify this launch, and
+    // keeping it would make the next launch mis-report what is running.
+    if (record.sha256 !== this.currentBundle.sha256) {
       this.clearInstallExpectation();
       return;
     }
 
-    if (expected) {
-      if (running === expected.identityToken) {
-        // Proven: the bundle we installed is the bundle executing.
-        __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
-        this.clearInstallExpectation();
-        return;
-      }
-
-      logger.error(
-        `[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` +
-          `carries a known identity marker, but the running bundle reports ` +
-          `${running ?? 'no marker at all'}. The app is executing different code than the slot ` +
-          'manager believes. Check that the host app resolves the OTA bundle path at launch ' +
-          '(see the ScaleBunOta integration for your React Native version).',
-      );
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `install_not_effective — expected ${expected.identityToken}, running ${running ?? 'none'}`,
-      });
-      // Deliberately NOT cleared: the condition is still true on the next boot
-      // and should keep reporting until the integration is fixed. Clearing here
-      // would make a permanently broken install look like a one-off.
+    // Already proven on an earlier launch. The token is retired once verified
+    // while the REST of the record stays — it is also the sha256 -> bundleId map
+    // that `hydrateCurrentBundleFromSlots` reads to report what this device is
+    // running. Wiping the whole record here is what made every launch after the
+    // first send `currentBundleId: undefined`, which the server reads as "not on
+    // this bundle" and answers by serving the same bundle again, forever.
+    if (!record.identityToken) return;
+
+    if (running === record.identityToken) {
+      __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      this.retireIdentityToken(record);
       return;
     }
 
-    if (running && running !== this.currentBundle.id) {
-      // No recorded expectation (installed by an older SDK), but the running
-      // marker disagrees with the active slot outright. Still conclusive.
-      logger.error(
-        `[OTA] BUNDLE MISMATCH — slot says ${this.currentBundle.id} is active but the ` +
-          `running bundle identifies as ${running}.`,
-      );
-      otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
-        error: `bundle_identity_mismatch — running ${running}`,
-      });
-    }
+    logger.error(
+      `[OTA] INSTALL DID NOT TAKE EFFECT — bundle ${this.currentBundle.id} was installed and ` +
+        `carries a known identity marker, but the running bundle reports ` +
+        `${running ?? 'no marker at all'}. The app is executing different code than the slot ` +
+        'manager believes. Check that the host app resolves the OTA bundle path at launch ' +
+        '(see the ScaleBunOta integration for your React Native version).',
+    );
+    otaEventEmitter.emitSimple('APPLY_FAILED', this.currentBundle.id, {
+      releaseId: this.currentBundle.releaseId,
+      error: `install_not_effective — expected ${record.identityToken}, running ${running ?? 'none'}`,
+    });
+    // Deliberately NOT retired: the condition is still true on the next boot and
+    // should keep reporting until the integration is fixed. Retiring the token
+    // here would make a permanently broken install look like a one-off.
   }
 
   // ── Install expectation ────────────────────────────────────────────────────
@@ -394,6 +429,11 @@ export class OtaOrchestrator {
         JSON.stringify({
           bundleId: bundle.id,
           version: bundle.version,
+          // Carried so telemetry emitted on a LATER launch (a boot-guard
+          // rollback, an ineffective install) can still be attributed to the
+          // release, not merely the bundle. The check response is long gone by
+          // then; this record is the only thing that remembers.
+          releaseId: bundle.releaseId ?? null,
           // The join key back to the native slot, which records sha256 and
           // nothing else identifying.
           sha256: bundle.sha256,
@@ -408,6 +448,7 @@ export class OtaOrchestrator {
   private readInstallRecord(): {
     bundleId: string;
     version: number;
+    releaseId?: string | null;
     sha256: string;
     identityToken: string | null;
   } | null {
@@ -423,11 +464,35 @@ export class OtaOrchestrator {
     }
   }
 
-  private readInstallExpectation(): { bundleId: string; identityToken: string } | null {
-    const record = this.readInstallRecord();
-    return record && record.identityToken
-      ? { bundleId: record.bundleId, identityToken: record.identityToken }
-      : null;
+  /**
+   * 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(record: {
+    bundleId: string;
+    version: number;
+    releaseId?: string | null;
+    sha256: string;
+  }): void {
+    try {
+      this.storage().set(
+        OtaOrchestrator.INSTALL_EXPECTATION_KEY,
+        JSON.stringify({
+          bundleId: record.bundleId,
+          version: record.version,
+          releaseId: record.releaseId ?? null,
+          sha256: record.sha256,
+          identityToken: null,
+        }),
+      );
+    } catch {
+      /* non-fatal */
+    }
   }
 
   private clearInstallExpectation(): void {
@@ -448,19 +513,50 @@ export class OtaOrchestrator {
    * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
    * and no 'current' OTA bundle, the native layer already reverted.
    */
-  private checkBootGuardRecovery(): void {
-    if (!NativeScaleBunOta) return;
-
+  private checkBootGuardRecovery(state: Record<string, any> | null): void {
     try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
+      if (!state?.bootGuardReverted) return;
+
+      // WHICH bundle was rolled back, and it has to come from the install
+      // record. The obvious source — `state.previous` — is wrong twice over:
+      // slot meta.json carries only `{sha256, installedAt}` so it has no bundle
+      // id to read, and `revert()` deletes the previous slot as its last step,
+      // so by the time this runs there is no previous meta at all. The event
+      // therefore reported `bundleId: 'unknown'` on every rollback, and the
+      // backend drops any ota_event whose bundleId does not resolve to a bundle
+      // the app owns — so the crash-guard's own rollback signal never arrived.
+      //
+      // Native now stamps the sha256 of the bundle it reverted AWAY FROM into
+      // the revert record; the install record maps that back to a bundle id.
+      const record = this.readInstallRecord();
+      const revertedSha: string | undefined = state.bootGuardRevertedSha256;
+      const matchesRecord = !!record && (!revertedSha || record.sha256 === revertedSha);
+
+      // Report the reason native actually determined — a hash mismatch and a
+      // crash loop are different incidents and were being collapsed into one.
+      const reason: string = state.bootGuardRevertReason || 'boot_crash_guard';
 
-      if (state.bootGuardReverted) {
-        logger.warn('[OTA] Boot guard fired — app was reverted to previous bundle');
-        otaEventEmitter.emitSimple('AUTO_ROLLBACK', state.previous?.bundleId ?? 'unknown', {
-          reason: 'boot_guard_crash_loop_detected',
+      if (matchesRecord && record) {
+        logger.warn(
+          `[OTA] Boot guard fired — reverted away from bundle ${record.bundleId} ` +
+            `(v${record.version}); reason: ${reason}`,
+        );
+        otaEventEmitter.emitSimple('AUTO_ROLLBACK', record.bundleId, {
+          releaseId: record.releaseId ?? undefined,
+          version: record.version,
+          reason,
         });
+        // The record describes a bundle this device is no longer running.
+        this.clearInstallExpectation();
+        return;
       }
+
+      // No usable record (older SDK, cleared storage). Say so rather than
+      // emitting an event the server is obliged to discard.
+      logger.warn(
+        `[OTA] Boot guard fired (reason: ${reason}) but the rolled-back bundle could not be ` +
+          'identified locally — no install record. The rollback is not reported to the server.',
+      );
     } catch {
       // Slot state parsing failed — non-fatal
     }
@@ -591,6 +687,23 @@ export class OtaOrchestrator {
       }
 
       __DEV__ && logger.debug('[OTA] Sync started…');
+
+      // The funnel's denominator, for devices already on an OTA bundle. Emitted
+      // before the request, so a check that fails outright still counts as a
+      // check — the only CHECK rows before this came from a server-side geo
+      // side-effect that is skipped whenever the request carries no country.
+      //
+      // Only when a current bundle is known: every ota_event must name a bundle
+      // the app owns or the server drops it, and a device still on the binary's
+      // factory bundle has no such id to give. Those devices are counted
+      // server-side when they are offered something.
+      if (this.currentBundle?.id) {
+        otaEventEmitter.emitSimple('CHECK', this.currentBundle.id, {
+          releaseId: this.currentBundle.releaseId,
+          version: this.currentBundle.version,
+        });
+      }
+
       const checkRes = await this.checkForUpdate(params);
 
       if (checkRes.action === 'NONE') {
@@ -603,7 +716,9 @@ export class OtaOrchestrator {
       // Handle server-initiated rollback (Sprint 4)
       if (checkRes.action === 'ROLLBACK') {
         logger.warn('[OTA] Server requested ROLLBACK — reverting to previous bundle');
-        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown');
+        otaEventEmitter.emitSimple('MANUAL_ROLLBACK', this.currentBundle?.id ?? 'unknown', {
+          releaseId: this.currentBundle?.releaseId,
+        });
         const reverted = await NativeScaleBunOta.revertToPrevious();
         if (reverted) {
           this.currentBundle = null;
@@ -623,6 +738,15 @@ export class OtaOrchestrator {
       const bundle = checkRes.bundle;
       let patchUsed = false;
 
+      // The offer itself. Everything downstream (download, install, activation)
+      // is a conversion against this, so without it the top of the funnel was
+      // unmeasurable and a rollout that never reached devices looked identical
+      // to one whose devices all declined to download.
+      otaEventEmitter.emitSimple('OFFERED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
+
       // ── VERIFY AUTHENTICITY (OTA-03) ─────────────────────────────────────
       // Before anything touches the disk. SHA-256 proves the bytes arrived
       // intact; only the signature proves they came from you. Checking after
@@ -634,6 +758,7 @@ export class OtaOrchestrator {
       );
       if (!signatureOutcome.ok) {
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: `Signature check failed: ${signatureOutcome.reason}`,
           version: bundle.version,
         });
@@ -645,7 +770,10 @@ export class OtaOrchestrator {
       }
 
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
-      otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, { version: bundle.version });
+      otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
       const downloadStart = Date.now();
       __DEV__ && logger.debug(`[OTA] Downloading update v${bundle.version}…`);
 
@@ -750,6 +878,7 @@ export class OtaOrchestrator {
         postProgress(0, 'FAILED');
         logger.error('[OTA] Staging bundle failed after retries');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Staging failed — SHA-256 mismatch or download error',
           version: bundle.version,
         });
@@ -760,6 +889,7 @@ export class OtaOrchestrator {
 
       const downloadDuration = Date.now() - downloadStart;
       otaEventEmitter.emitSimple('DOWNLOAD_COMPLETE', bundle.id, {
+        releaseId: bundle.releaseId,
         version: bundle.version,
         durationMs: downloadDuration,
         patchUsed,
@@ -771,6 +901,7 @@ export class OtaOrchestrator {
       if (!applied) {
         logger.error('[OTA] Applying update failed');
         otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+          releaseId: bundle.releaseId,
           error: 'Atomic slot swap failed',
           version: bundle.version,
         });
@@ -791,7 +922,10 @@ export class OtaOrchestrator {
       // it is skipped when there is no marker to compare.
       this.recordInstallExpectation(bundle);
 
-      otaEventEmitter.emitSimple('INSTALLED', bundle.id, { version: bundle.version });
+      otaEventEmitter.emitSimple('INSTALLED', bundle.id, {
+        releaseId: bundle.releaseId,
+        version: bundle.version,
+      });
       __DEV__ && logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
 
       // Deliver telemetry BEFORE a restart tears the JS runtime down —
@@ -863,6 +997,19 @@ export class OtaOrchestrator {
           NativeScaleBunOta?.markHealthy();
           __DEV__ && logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
           this.healthyTimer = null;
+
+          // The honest activation signal. INSTALLED is emitted optimistically,
+          // BEFORE the bundle has ever executed, so counting it as adoption
+          // credits bundles that were installed and then crash-reverted. This
+          // fires only once the bundle has actually booted and survived.
+          const running = this.currentBundle;
+          if (running?.id) {
+            otaEventEmitter.emitSimple('BOOT_SUCCESS', running.id, {
+              releaseId: running.releaseId,
+              version: running.version,
+              durationMs: healthyMs,
+            });
+          }
         });
       }, healthyMs);
     } catch {