@scalebun/react-native 1.13.0 → 2.0.1

package/src/features/ota/OtaOrchestrator.ts

@@ -14,7 +14,6 @@ import { otaEventEmitter } from './OtaEventEmitter';
 import { getDeviceCountry, prefetchDeviceCountry } from './geoCountry';
 import { deviceTargetingAttributes } from './deviceAttributes';
 import { resolveInstallationId } from '../../core/id/installationId';
-import { verifyBundleSignature, type SignatureConfig } from './signature';
 import { detectOtaEnvironment, type OtaEnvironment } from './environment';
 import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
 import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
@@ -138,12 +137,12 @@ async function deliverOtaEvents(params: {
       },
     );
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    __DEV__ && logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
+    logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
   } catch (err: any) {
     // Failed delivery must not fail the update — but the events must not be
     // lost either: requeue so the next sync retries them.
     for (const e of events) otaEventEmitter.emit(e);
-    __DEV__ && logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
+    logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
   }
 }
 
@@ -189,9 +188,10 @@ export class OtaOrchestrator {
     return this.currentBundle;
   }
   private isRestartRequiredState = false;
+  /** Root/jailbreak indicators observed at init; empty when none found. */
+  private integrityIndicators: string[] = [];
   private healthyTimer: ReturnType<typeof setTimeout> | null = null;
   private bootGuardConfig: BootGuardConfig = {};
-  private signatureConfig: SignatureConfig | undefined;
   private environment: OtaEnvironment | null = null;
   /** One-time boot checks have run in this process (init is idempotent). */
   private initialized = false;
@@ -200,11 +200,12 @@ export class OtaOrchestrator {
   /**
    * Initialize the orchestrator. Checks for boot-guard recovery state.
    *
-   * `signature` is optional: an app that has not adopted signing keeps working
-   * on SHA-256 integrity alone. Once a public key IS configured, a bundle that
-   * cannot be verified is refused rather than installed (OTA-03).
+   * 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 & { signature?: SignatureConfig }): void {
+  init(config?: BootGuardConfig): void {
     noThrow(() => {
       // Idempotent: init() runs its one-time checks ONCE per process. Found
       // live — a host that calls init() again after installing an update (any
@@ -215,7 +216,6 @@ export class OtaOrchestrator {
       // them. Config is still refreshed so late signature setup works.
       if (this.initialized) {
         this.bootGuardConfig = config ?? this.bootGuardConfig;
-        this.signatureConfig = config?.signature ?? this.signatureConfig;
         return;
       }
 
@@ -249,7 +249,7 @@ export class OtaOrchestrator {
         // We cannot see which form the host used — the identity check after
         // restart is what proves it — but naming the right fix up front turns
         // a confusing silent failure into a one-line correction.
-        __DEV__ && logger.debug(
+        logger.debug(
           '[OTA] React Native >= 0.82 detected. The only valid Android integration is ' +
             'getDefaultReactHost(..., jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(ctx)) — ' +
             'ReactNativeHost and its getJSBundleFile() override no longer exist.',
@@ -258,9 +258,30 @@ export class OtaOrchestrator {
 
       this.initialized = true;
       this.enabled = true;
+
+      // Device integrity signal.
+      //
+      // Reported, not enforced. Root defeats any check made from inside the app,
+      // so this is not a boundary — it is context. It tells an operator that a
+      // device's OTA slot is writable by other processes, which is what makes the
+      // launch-time hash re-check in SlotManager meaningful rather than paranoid.
+      // A host app that wants to withhold updates on such devices can read
+      // `deviceIntegrityIndicators()` and decide for itself.
+      try {
+        const raw = NativeScaleBunOta?.getDeviceIntegrity?.();
+        this.integrityIndicators = raw ? (JSON.parse(raw) as string[]) : [];
+        if (this.integrityIndicators.length > 0) {
+          logger.warn(
+            `[OTA] Device integrity indicators present: ${this.integrityIndicators.join(', ')}. ` +
+              'Updates still install and are still signature-verified, but an installed ' +
+              'bundle on this device can be modified by other privileged processes.',
+          );
+        }
+      } catch {
+        this.integrityIndicators = [];
+      }
       this.bootGuardConfig = config ?? {};
-      this.signatureConfig = config?.signature;
-      __DEV__ && logger.debug(
+      logger.debug(
         `[OTA] Orchestrator initialized (RN ${this.environment.rnVersionString ?? 'unknown'}` +
           `${this.environment.bridgeless ? ', bridgeless' : ''}` +
           `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`,
@@ -295,6 +316,22 @@ export class OtaOrchestrator {
 
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
+
+      // Boot-guard health is a LOCAL fact: this process booted from the staged
+      // bundle and did not crash. The heartbeat used to start only on the
+      // `action === 'NONE'` branch of sync(), so confirming a good bundle needed
+      // a successful network round-trip that returned exactly that answer — a
+      // device offline, rate-limited, or still being offered an update could
+      // never clear its marker, and the guard reverted a bundle that was working.
+      //
+      // It runs HERE, last, and is handed the slot state that was already read.
+      // Starting it earlier made it call getSlotState() itself, and that read is
+      // consume-on-read for the revert record — it swallowed the revert before
+      // checkBootGuardRecovery() could name the bundle that failed, so a
+      // crash-rollback went unreported. It also read bootGuardConfig before
+      // init() had assigned it, so healthyAfterMs silently fell back to the
+      // default.
+      this.startBootGuardHeartbeat(slotState);
     });
   }
 
@@ -334,7 +371,7 @@ export class OtaOrchestrator {
           releaseId: record.releaseId ?? undefined,
           sha256: record.sha256,
         } as OtaBundlePayload;
-        __DEV__ && logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
+        logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
         return;
       }
 
@@ -342,7 +379,7 @@ export class OtaOrchestrator {
       // a reinstall of the app, cleared storage, or a bundle staged by an
       // older SDK. Report the hash so the server can still recognise it.
       this.currentBundle = { sha256: current.sha256 } as OtaBundlePayload;
-      __DEV__ && logger.debug(
+      logger.debug(
         `[OTA] Running an OTA bundle (sha ${String(current.sha256).slice(0, 12)}…) with no local install record.`,
       );
     } catch {
@@ -394,7 +431,7 @@ export class OtaOrchestrator {
     if (!record.identityToken) return;
 
     if (running === record.identityToken) {
-      __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+      logger.debug('[OTA] Install verified — running bundle matches what was installed.');
       this.retireIdentityToken(record);
       return;
     }
@@ -566,6 +603,14 @@ export class OtaOrchestrator {
     return this.enabled;
   }
 
+  /**
+   * Root/jailbreak indicators detected on this device, as stable reason strings.
+   * Empty means nothing was detected — not proof the device is clean.
+   */
+  deviceIntegrityIndicators(): string[] {
+    return [...this.integrityIndicators];
+  }
+
   isRestartRequired(): boolean {
     return this.isRestartRequiredState;
   }
@@ -595,12 +640,27 @@ export class OtaOrchestrator {
       // OTA has no bundle for a non-mobile target; claiming Android there would install the wrong one.
       const mobileOS = resolveMobileOS();
       if (!mobileOS) throw new Error('OTA is not supported on this platform');
+      // SDK trust coverage (CICDPAGE §12): report which trusted key IDs are
+      // embedded in this binary so the dashboard can measure key-rotation
+      // adoption. Telemetry only — the server never trusts a key a device claims.
+      // Defensive: optional native method, never let it break a check.
+      let trustedKeyIds: string[] | undefined;
+      try {
+        const raw = NativeScaleBunOta?.getTrustedKeyIds?.();
+        if (raw) {
+          const arr = JSON.parse(raw);
+          if (Array.isArray(arr) && arr.length) trustedKeyIds = arr.slice(0, 16);
+        }
+      } catch {
+        /* trust reporting is best-effort — never break the update check */
+      }
       const payload: OtaCheckRequest = {
         appVersion: requestParams.appVersion,
         platform: mobileOS,
         installationId: requestParams.installationId,
         currentBundleId: this.currentBundle?.id,
         currentBundleHash: this.currentBundle?.sha256,
+        trustedKeyIds,
         channelName: requestParams.channelName,
         // Host-supplied country wins; otherwise the cached edge-Worker lookup
         // fills in (see geoCountry.ts). Undefined when neither knows — the
@@ -686,7 +746,7 @@ export class OtaOrchestrator {
         return { status: 'ERROR', error: 'OTA native module disabled or missing' };
       }
 
-      __DEV__ && logger.debug('[OTA] Sync started…');
+      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
@@ -707,7 +767,7 @@ export class OtaOrchestrator {
       const checkRes = await this.checkForUpdate(params);
 
       if (checkRes.action === 'NONE') {
-        __DEV__ && logger.debug('[OTA] App is up to date');
+        logger.debug('[OTA] App is up to date');
         // If we booted from an OTA bundle and it's healthy, clear the boot guard
         this.startBootGuardHeartbeat();
         return { status: 'UP_TO_DATE' };
@@ -747,35 +807,18 @@ export class OtaOrchestrator {
         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
-      // staging would mean writing unverified code to the slot directory first.
-      const signatureOutcome = await verifyBundleSignature(
-        bundle.sha256,
-        bundle.signature,
-        this.signatureConfig,
-      );
-      if (!signatureOutcome.ok) {
-        otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
-          releaseId: bundle.releaseId,
-          error: `Signature check failed: ${signatureOutcome.reason}`,
-          version: bundle.version,
-        });
-        return {
-          status: 'ERROR',
-          error: `Bundle signature check failed (${signatureOutcome.reason})`,
-          bundle,
-        };
-      }
-
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
+      // Authenticity is enforced NATIVELY now (see the envelope branch below):
+      // SHA-256 proves the bytes arrived intact, and for signed releases the
+      // RSA signature — checked in native code against keys embedded in the app
+      // package — proves they came from you. JS neither pins keys nor verifies
+      // signatures.
       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}…`);
+      logger.debug(`[OTA] Downloading update v${bundle.version}…`);
 
       // Live progress: native tick → DOWNLOAD_PROGRESS (feeds useOtaUpdate) →
       // throttled POST to the live tracker. `bundle.size` is the authoritative
@@ -824,51 +867,102 @@ export class OtaOrchestrator {
 
       let staged = false;
 
-      // Sprint 7: Try patch first if offered, fall back to full bundle
-      if (bundle.patch && NativeScaleBunOta.stagePatch) {
-        __DEV__ && logger.debug(
-          `[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` +
-            `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`,
-        );
+      if (bundle.envelope) {
+        // ── NATIVE-ENFORCED VERIFY + STAGE (SB-OTA-RSA-SHA256-V1) ───────────
+        // Hand the whole envelope to native code, which verifies the RSA
+        // signature against the keys EMBEDDED in the app package, then downloads
+        // the artifact, enforces the SIGNED size + SHA-256, and stages it into
+        // the `next` slot — all outside JS. JavaScript never stages bytes it has
+        // not proven authentic. No patch path here: a signed offer is always a
+        // full verified download (native patch is a documented follow-up).
+        const envelopeJson = JSON.stringify({ ...bundle.envelope, downloadUrl: bundle.url });
+        let verdict: {
+          ok?: boolean;
+          code?: string;
+          message?: string;
+        };
         try {
-          staged = await NativeScaleBunOta.stagePatch(
-            bundle.patch.url,
-            bundle.patch.sha256,
-            bundle.sha256, // expected full-bundle hash after patching
+          const verdictJson = await NativeScaleBunOta.verifyAndStageRelease(envelopeJson);
+          verdict = JSON.parse(verdictJson);
+        } catch (err: any) {
+          // A rejected promise (or an unparseable verdict) is machinery failure,
+          // never a valid result — treat it as a hard failure.
+          verdict = { ok: false, code: 'verify_stage_threw', message: err?.message ?? String(err) };
+        }
+
+        if (!verdict.ok) {
+          unsubscribeProgress();
+          postProgress(0, 'FAILED');
+          logger.error(
+            `[OTA] Native verify/stage refused the release: ${verdict.code ?? 'unknown'}` +
+              `${verdict.message ? ` — ${verdict.message}` : ''}`,
           );
-          if (staged) {
-            patchUsed = true;
-            __DEV__ && logger.debug('[OTA] Patch applied successfully');
-          } else {
-            logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
-          }
-        } catch (patchErr: any) {
-          logger.warn(`[OTA] Patch staging failed: ${patchErr.message} — falling back to full bundle`);
+          otaEventEmitter.emitSimple('APPLY_FAILED', bundle.id, {
+            releaseId: bundle.releaseId,
+            // `error` is mapped onto the wire `errorCode` by deliverOtaEvents —
+            // carry the stable native verdict code there.
+            error: verdict.code ?? 'verify_and_stage_release_failed',
+            version: bundle.version,
+          });
+          return {
+            status: 'ERROR',
+            error: `Release verification failed (${verdict.code ?? 'unknown'})`,
+            bundle,
+          };
         }
-      }
 
-      // Full-bundle fallback (or primary path when no patch is available).
-      // Retried with backoff: on a mobile network a transient drop mid-download
-      // is the common case, and previously one failure meant waiting for the
-      // next cold start — often hours away, sometimes never.
-      if (!staged) {
-        try {
-          staged = await retryWithBackoff(
-            async () => {
-              const ok = await NativeScaleBunOta!.stageBundle(bundle.url, bundle.sha256);
-              if (!ok) {
-                // Native returns a bare boolean, so a hash mismatch and a
-                // dropped connection are indistinguishable here. Retrying a
-                // genuine mismatch a couple of times is cheap; not retrying a
-                // dropped connection costs the whole update.
-                throw new Error('stageBundle returned false');
-              }
-              return ok;
-            },
-            { label: `download v${bundle.version}`, attempts: 3 },
+        staged = true;
+      } else {
+        // ── LEGACY / UNSIGNED (SHA-256 integrity only) ─────────────────────
+        // No envelope means the app embeds no trusted keys and the release is
+        // unsigned: keep the pre-RSA behaviour so those apps still update.
+
+        // Sprint 7: Try patch first if offered, fall back to full bundle
+        if (bundle.patch && NativeScaleBunOta.stagePatch) {
+          logger.debug(
+            `[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` +
+              `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`,
           );
-        } catch {
-          staged = false;
+          try {
+            staged = await NativeScaleBunOta.stagePatch(
+              bundle.patch.url,
+              bundle.patch.sha256,
+              bundle.sha256, // expected full-bundle hash after patching
+            );
+            if (staged) {
+              patchUsed = true;
+              logger.debug('[OTA] Patch applied successfully');
+            } else {
+              logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
+            }
+          } catch (patchErr: any) {
+            logger.warn(`[OTA] Patch staging failed: ${patchErr.message} — falling back to full bundle`);
+          }
+        }
+
+        // Full-bundle fallback (or primary path when no patch is available).
+        // Retried with backoff: on a mobile network a transient drop mid-download
+        // is the common case, and previously one failure meant waiting for the
+        // next cold start — often hours away, sometimes never.
+        if (!staged) {
+          try {
+            staged = await retryWithBackoff(
+              async () => {
+                const ok = await NativeScaleBunOta!.stageBundle(bundle.url, bundle.sha256);
+                if (!ok) {
+                  // Native returns a bare boolean, so a hash mismatch and a
+                  // dropped connection are indistinguishable here. Retrying a
+                  // genuine mismatch a couple of times is cheap; not retrying a
+                  // dropped connection costs the whole update.
+                  throw new Error('stageBundle returned false');
+                }
+                return ok;
+              },
+              { label: `download v${bundle.version}`, attempts: 3 },
+            );
+          } catch {
+            staged = false;
+          }
         }
       }
 
@@ -926,7 +1020,7 @@ export class OtaOrchestrator {
         releaseId: bundle.releaseId,
         version: bundle.version,
       });
-      __DEV__ && logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
+      logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
 
       // Deliver telemetry BEFORE a restart tears the JS runtime down —
       // an INSTALLED event queued but not sent would vanish with the process.
@@ -970,7 +1064,7 @@ export class OtaOrchestrator {
    * 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(): void {
+  private startBootGuardHeartbeat(preRead?: Record<string, any> | null): void {
     if (!NativeScaleBunOta) return;
 
     // Cancel any existing timer
@@ -980,22 +1074,28 @@ export class OtaOrchestrator {
     }
 
     try {
-      const stateJson = NativeScaleBunOta.getSlotState();
-      const state = JSON.parse(stateJson);
+      // getSlotState() is CONSUME-ON-READ for the revert record, so a caller that
+      // has already read it passes the parsed result down rather than letting
+      // this read again and swallow a rollback. `null` is a real answer (module
+      // absent or payload unreadable) — only `undefined` means "nobody read it".
+      const state =
+        preRead !== undefined
+          ? preRead
+          : (JSON.parse(NativeScaleBunOta.getSlotState()) as Record<string, any>);
 
       // Only run the heartbeat if boot-guard marker is present
       // (meaning we're running from a freshly-applied OTA bundle)
-      if (!state.bootMarkerPresent) {
+      if (!state?.bootMarkerPresent) {
         return;
       }
 
       const healthyMs = this.bootGuardConfig.healthyAfterMs ?? DEFAULT_HEALTHY_AFTER_MS;
-      __DEV__ && logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
+      logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
 
       this.healthyTimer = setTimeout(() => {
         noThrow(() => {
           NativeScaleBunOta?.markHealthy();
-          __DEV__ && logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
+          logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
           this.healthyTimer = null;
 
           // The honest activation signal. INSTALLED is emitted optimistically,
@@ -1051,11 +1151,11 @@ export class OtaOrchestrator {
             /* the restart below makes cleanup moot */
           }
           this.resumeRestartArmed = false;
-          __DEV__ && logger.info('[OTA] App resumed — activating the staged update now');
+          logger.info('[OTA] App resumed — activating the staged update now');
           this.restart();
         }
       });
-      __DEV__ && logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
+      logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
     } catch {
       // AppState unavailable (tests, exotic hosts): the update still activates
       // on the next cold start, which is the documented fallback behaviour.
@@ -1075,7 +1175,7 @@ export class OtaOrchestrator {
    */
   restart(): void {
     noThrow(() => {
-      __DEV__ && logger.info('[OTA] Triggering app restart…');
+      logger.info('[OTA] Triggering app restart…');
       if (NativeScaleBunOta && typeof NativeScaleBunOta.restartApp === 'function') {
         NativeScaleBunOta.restartApp();
       } else if (DevSettings && typeof DevSettings.reload === 'function') {

package/src/features/ota/OtaTypes.ts

@@ -54,6 +54,11 @@ export interface OtaCheckRequest {
   installationId: string;
   currentBundleId?: string;
   currentBundleHash?: 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[];
 
   // ── C1: channel + targeting context ────────────────────────────────────────
   // The backend DTO has accepted all of these since Sprint 9. The SDK declared
@@ -112,7 +117,24 @@ export interface OtaBundlePayload {
   url: string;         // presigned GET — short-TTL
   size: number;
   sha256: string;
-  signature?: string;  // ed25519 detached signature (hex)
+  signature?: string;  // ed25519 detached signature (hex) — legacy, unused by native RSA path
+  /**
+   * 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:

package/src/features/session/SessionManager.ts

@@ -1105,6 +1105,56 @@ export class SessionManager {
         targetId?: string;
         screenName?: string;
         emitAutomaticAnalytics?: boolean;
+        /**
+         * RN-6 — the native↔JS join's own verdict, and it MUST be declared here.
+         *
+         * This signature ENUMERATES its fields rather than spreading, and the only caller
+         * (ScaleBunDebugRoot's native listener) invokes it through `(sm as any)`. So a field
+         * added at the call site and not added here is dropped in silence, with no type
+         * error anywhere — which is precisely how these three nearly shipped as a no-op.
+         *
+         * 'exact' = one JS start was clearly closest. 'ambiguous' = two were within
+         * CORRELATION_MARGIN_MS of each other, so target/ui/screenName were deliberately
+         * withheld rather than guessed. 'none' = no start within tolerance, meaning the JS
+         * handler never fired. The last two are kept distinct because they have different
+         * fixes and collapsing them would hide which is happening in production.
+         */
+        correlation?: 'exact' | 'ambiguous' | 'none';
+        correlationDeltaMs?: number | null;
+        correlationRunnerUpDeltaMs?: number | null;
+        /**
+         * RN-1/RN-2 — which kind of identity `targetId` is. Declared here for the same reason as
+         * the correlation fields above: this signature enumerates, and its only caller goes
+         * through `(sm as any)`, so an undeclared field is dropped in silence.
+         */
+        targetSource?: 'testID' | 'path' | 'component' | 'none';
+        /** RN-8: where the screen name came from. Declared here because this signature enumerates. */
+        screenSource?: 'manual' | 'navigation' | 'none';
+        /**
+         * RN-13: the target control's rectangle in capture-base fractions. Declared here because
+         * this signature ENUMERATES — the sixth field to need it, after three correlation fields,
+         * targetSource and screenSource.
+         */
+        targetRect?: { x: number; y: number; width: number; height: number };
+        /**
+         * RN-3: content offset of the nearest ancestor scroller. Declared here because this
+         * signature ENUMERATES — the seventh field to need it.
+         */
+        scrollX?: number;
+        scrollY?: number;
+        scrollSource?: 'wrapper' | 'none';
+        /**
+         * RN-4: list row identity. Declared here because this signature ENUMERATES — the eighth
+         * and ninth fields to need it.
+         */
+        itemKey?: string;
+        itemIndex?: number;
+        /**
+         * RN-15: tap position within the target control. Declared here because this signature
+         * ENUMERATES — the tenth and eleventh fields to need it.
+         */
+        localU?: number;
+        localV?: number;
     }): void {
         // Exact-duplicate suppression — see _lastGestureSig. Signature is the gesture type plus
         // raw coordinates verbatim; String() keeps undefined coords distinct from 0 (a payload
@@ -1136,6 +1186,69 @@ export class SessionManager {
             state_status: stateStatus,
             ui: details?.ui,
             target_id: details?.targetId,
+            /**
+             * RN-6 — shipped with the row so the join is auditable instead of assumed.
+             *
+             * Without it, an interaction with no `target_id` is ambiguous in the worst way:
+             * it could mean the control genuinely had no identity, or that the correlation
+             * refused and the identity exists but could not be attributed. Those are
+             * different defects with different owners, and the accounting lane cannot give
+             * an honest unplaceable REASON without knowing which.
+             *
+             * Undefined on the JS-fallback path (no native event, so nothing was joined),
+             * which is itself the correct answer there rather than a fabricated 'exact'.
+             */
+            correlation: details?.correlation,
+            correlation_delta_ms: details?.correlationDeltaMs,
+            correlation_runner_up_delta_ms: details?.correlationRunnerUpDeltaMs,
+            /**
+             * RN-1/RN-2 — stored alongside `target_id` so a reader can tell an authored
+             * identifier from a structural inference. 'path' means the app authored no testID
+             * and the identity was derived from component names, which is useful but will
+             * change under refactoring; a dashboard that presents the two identically invites
+             * someone to trust a key that is about to move.
+             */
+            target_source: details?.targetSource,
+            /**
+             * RN-8 — stored so "13.8% of interactions have a screen" becomes answerable.
+             * 'none' means the app instrumented nothing the SDK could see; 'manual' means a
+             * <ScaleBunScreen> beacon; 'navigation' means the React Navigation hook. Three
+             * different owners behind one number that today has none.
+             */
+            screen_source: details?.screenSource,
+            /**
+             * RN-13 — what makes "the heat is on this control" checkable instead of assumed.
+             * Absent when the control could not be measured synchronously, which is a fact worth
+             * storing: an unmeasurable control and a mis-placed tap are different findings.
+             */
+            target_rect: details?.targetRect,
+            /**
+             * RN-3 — the backend already reads scrollX/scrollY off the payload into the fact
+             * table's own columns (it has done since the web SDK, which sends `sx`/`sy`), so
+             * these need no migration. Mobile simply never sent them.
+             *
+             * `scroll_source` says whether an offset was available at all: 'none' means the app
+             * uses a plain <ScrollView> rather than the SDK's wrapper, which is a coverage gap in
+             * the integration and not a tap at the top of a list.
+             */
+            scrollX: details?.scrollX,
+            scrollY: details?.scrollY,
+            scroll_source: details?.scrollSource,
+            /**
+             * RN-4 — what stops a recycled native view merging two different rows into one
+             * hotspot. The key is the app's own keyExtractor output, so it is stable across
+             * scrolling and across sessions; the index is carried so a recycled slot (same index,
+             * different key) can be proven rather than inferred.
+             */
+            item_key: details?.itemKey,
+            item_index: details?.itemIndex,
+            /**
+             * RN-15 — where in the control, not just which control. Turns "they tapped Add to
+             * Cart" into "they tapped its left edge", which is what tells you whether a hit area
+             * is right. Outside 0..1 is a hitSlop tap and is kept as such.
+             */
+            local_u: details?.localU,
+            local_v: details?.localV,
             gestureType,
             x: details?.x,
             y: details?.y,