@scalebun/react-native 1.0.3 → 1.0.4

package/src/features/crash/nativeCrashBridge.ts

@@ -1,7 +1,5 @@
 import { NativeModules } from 'react-native';
 import { nativeModuleVia } from '../../core/architecture';
-import { createEnvelope } from '../../pipeline/envelope/envelope';
-import { memoryQueue } from '../../pipeline/queue/memoryQueue';
 import { logger } from '../../core/logger/internalLogger';
 import { getCrashReporter } from './CrashReporter';
 
@@ -45,6 +43,27 @@ function getCrashModule(): any {
  * NSSetUncaughtExceptionHandler + signal handlers on iOS).
  * Safe to call multiple times — native side is idempotent.
  */
+/**
+ * Tell native which session is live, so a crash that happens next can name it.
+ *
+ * Called once per session — never per event. Native writes it to crash-safe storage immediately,
+ * because a fatal handler cannot call back into JS to ask, and by the time it runs the JS thread may
+ * already be gone.
+ *
+ * Fire-and-forget and no-throw: losing this degrades a recovered crash to unattributed, which is the
+ * old behaviour. It must never be able to fail a session start.
+ */
+export async function setNativeActiveSession(sessionId: string): Promise<void> {
+    try {
+        const mod = getCrashModule();
+        if (!mod?.setActiveSessionId || !sessionId) return;
+        await mod.setActiveSessionId(sessionId);
+        logger.debug(`[NativeCrash] Active session → ${sessionId}`);
+    } catch {
+        // No-throw
+    }
+}
+
 export async function installNativeCrashHandler(): Promise<void> {
     try {
         const mod = getCrashModule();
@@ -60,34 +79,68 @@ export async function installNativeCrashHandler(): Promise<void> {
 }
 
 /**
- * Drain a crash record left from the previous process run.
- * If found, enqueues a crash.native envelope and returns true.
- * Returns false when no pending crash is found.
+ * How many pending crashes one launch will deliver.
+ *
+ * The native spool holds three (a device that crashes, restarts offline, and crashes again), but
+ * `drainPendingCrash` hands back the OLDEST ONE ONLY. Draining once per launch therefore needed three
+ * launches to clear three crashes — and a fourth crash evicts the oldest, so on a device crashing in a
+ * loop the spool loses faster than a one-per-launch drain empties it.
+ *
+ * Bounded, not `while (true)`: this loop is driven by native state and stops the moment delivery
+ * fails, but the bound is what makes it impossible for a native bug — a clear that silently does
+ * nothing — to spin the drain forever at startup.
+ */
+const MAX_DRAIN_PER_LAUNCH = 4;
+
+/**
+ * Drain the crash records left from previous process runs.
+ * Returns true if at least one pending crash was found.
+ *
+ * Stops early the first time delivery fails: if the network is down for one crash it is down for the
+ * next, and every extra attempt is a request that cannot succeed made during app startup.
  */
 export async function drainNativeCrash(): Promise<boolean> {
+    let found = false;
+    const seen = new Set<string>();
+    for (let i = 0; i < MAX_DRAIN_PER_LAUNCH; i++) {
+        const outcome = await drainOne(seen);
+        if (outcome === 'none') break;
+        found = true;
+        // 'kept' means the backend did not take it. The rest of the spool is behind the same
+        // network, so stop rather than fail three more times.
+        if (outcome === 'kept') break;
+    }
+    return found;
+}
+
+/** One record: read → report → clear if the backend took it. */
+async function drainOne(seen: Set<string>): Promise<'none' | 'cleared' | 'kept'> {
     try {
         const mod = getCrashModule();
-        if (!mod?.drainPendingCrash) return false;
+        if (!mod?.drainPendingCrash) return 'none';
 
         const crash = await mod.drainPendingCrash();
-        if (!crash) return false;
+        if (!crash) return 'none';
+
+        /*
+         * The same record twice means the previous clear did not take effect — a native failure we
+         * cannot fix from here. Reporting it again would deliver a duplicate on every iteration, so
+         * treat it as the end of the spool.
+         */
+        const seenKey = typeof crash.crashId === 'string' ? crash.crashId : '';
+        // `''` is a deliberate sentinel for the single legacy record, which has no id. Tracking it
+        // too means a legacy clear that silently fails stops the loop instead of redelivering the
+        // same crash on every one of the remaining iterations.
+        if (seen.has(seenKey)) return 'none';
+        seen.add(seenKey);
 
         const stackArr: string[] = Array.isArray(crash.stackTrace) ? crash.stackTrace : [];
 
         // 1) Desktop debug stream — keep the rich native-crash envelope.
-        const envelope = createEnvelope('crash', {
-            name: crash.name ?? 'crash.native',
-            exceptionType: crash.exceptionType,
-            message: crash.message,
-            stackTrace: stackArr,
-            threadName: crash.threadName,
-            timestamp: crash.timestamp,
-            platform: crash.platform,
-            ...(crash.signal !== undefined ? { signal: crash.signal } : {}),
-            ...(crash.cause !== undefined ? { cause: crash.cause } : {}),
-            ...(crash.userInfo !== undefined ? { userInfo: crash.userInfo } : {}),
-        });
-        memoryQueue.add(envelope);
+        // D2: a rich envelope used to be written here into memoryQueue — a queue
+        // whose drain was never wired, so the native crash's forensic detail was
+        // captured and then discarded. The flattened report below now carries the
+        // same fields in `metadata` (D12), through the pipeline that actually lands.
 
         // 2) SaaS backend errors endpoint (dashboard Crashes view) — route the
         // same normalized report through the central reporter. This is what
@@ -99,6 +152,26 @@ export async function drainNativeCrash(): Promise<boolean> {
             message: crash.message ?? crash.exceptionType ?? 'Native crash',
             stack: stackArr.length ? stackArr.join('\n') : undefined,
             platform: crash.platform,
+            /**
+             * THE ORIGINAL SESSION — the entire point of the recovery path.
+             *
+             * This crash happened in a process that no longer exists, so it does NOT belong to the
+             * session running now. Passing it explicitly is what stops the reporter routing it
+             * through the current SessionManager and attributing it to the session created after
+             * the restart.
+             *
+             * Undefined on records written before this shipped, and on a crash that beat the first
+             * session. The sink then keeps the legacy behaviour rather than guessing an owner.
+             */
+            ...(crash.sessionId ? { sessionId: String(crash.sessionId) } : {}),
+            /**
+             * The stable id, carried through so it becomes the backend's dedupe key.
+             *
+             * Written once when the crash was first persisted — never regenerated here. If this were
+             * minted per attempt, every retry would arrive as a brand-new crash and at-least-once
+             * delivery would turn into duplicate-every-time.
+             */
+            ...(crash.crashId ? { crashId: String(crash.crashId) } : {}),
             metadata: {
                 exceptionType: crash.exceptionType,
                 threadName: crash.threadName,
@@ -106,8 +179,69 @@ export async function drainNativeCrash(): Promise<boolean> {
             },
         });
 
-        logger.info('[NativeCrash] Previous crash drained → desktop + backend');
-        return true;
+        /**
+         * DELETE ONLY AFTER THE BACKEND HAS IT.
+         *
+         * The read above is non-destructive, so the crash is still on disk right now. It is removed
+         * only once delivery has actually succeeded — previously the record was destroyed at read
+         * time, so a failed upload lost the crash permanently: the app had proof of a crash, deleted
+         * it, and then failed to send it.
+         *
+         * On failure we simply do NOT clear. The crash stays pending and is retried on the next
+         * launch, which is what makes this at-least-once. Duplicate delivery is safe because the
+         * crash carries a stable `crashId` that the backend dedupes on — a retry produces no second
+         * record.
+         *
+         * A record with no `crashId` is legacy: it predates stable ids, so it cannot be safely
+         * retried (a redelivery WOULD duplicate) and is cleared immediately, preserving exactly the
+         * old at-most-once behaviour for old data rather than silently changing it.
+         */
+        const crashId = seenKey;
+        if (!crashId) {
+            await mod.clearPendingCrash?.('');
+            logger.info('[NativeCrash] Legacy crash (no id) drained and cleared');
+            return 'cleared';
+        }
+
+        const delivered = await confirmDelivery();
+        if (delivered) {
+            await mod.clearPendingCrash?.(crashId);
+            logger.info(`[NativeCrash] Crash ${crashId} delivered → cleared`);
+            return 'cleared';
+        }
+        logger.info(`[NativeCrash] Crash ${crashId} not yet delivered → kept for retry`);
+        return 'kept';
+    } catch {
+        // Unknown state — stop the loop rather than risk spinning on a failure we cannot diagnose.
+        return 'none';
+    }
+}
+
+/**
+ * Has the crash actually reached the backend?
+ *
+ * The reporter's sinks are fire-and-forget by design (a crash report must never block or throw), so
+ * "delivered" is asked of the transport rather than inferred from `report()` returning. If the
+ * transport is not up yet — the drain can win the race against SessionManager — the answer is NO and
+ * the crash stays on disk for the next launch. That is strictly better than the old behaviour, where
+ * exactly that race deleted the record and dropped the crash silently.
+ */
+async function confirmDelivery(): Promise<boolean> {
+    try {
+        const { SessionManager } = await import('../session/SessionManager');
+        const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+        // No transport yet — the drain can win the startup race. That is a delivery FAILURE, not a
+        // reason to give up: the record stays on disk and the next launch retries it. This exact
+        // path used to delete the crash and send nothing.
+        if (!transport) return false;
+        /**
+         * The BOOLEAN, not merely "it resolved".
+         *
+         * flushErrors used to return void and swallow its own errors, so awaiting it proved only
+         * that the call finished. Deleting a crash on that basis would have thrown away crashes
+         * that never reached the backend — the failure this whole change exists to prevent.
+         */
+        return (await transport.flushErrors()) === true;
     } catch {
         return false;
     }

package/src/features/engage/EngagePromptProvider.tsx

@@ -609,7 +609,47 @@ export function EngagePromptProvider({
                       };
 
                 const drafts = result.attachments ?? [];
-                if (engage.submitResponseConfirmed) {
+
+                /**
+                 * Bug-report lane — opt in per campaign via `fileAsBugReport`.
+                 *
+                 * A FEEDBACK campaign fired by `shake_device` is almost always "something is
+                 * broken", not "how do you feel", and those are different products: a bug report
+                 * gets a status, a priority and an assignee on /diagnose/bug-reports, while a survey
+                 * response is counted in aggregate and cannot be triaged.
+                 *
+                 * Routed INSTEAD of submitResponse rather than in addition — a dual write would
+                 * create two rows for one submission and double-count the campaign on the Engage
+                 * side.
+                 *
+                 * `responseId` doubles as the idempotency key so a retried submit cannot file the
+                 * same report twice (BugReport.clientReportId is @unique).
+                 *
+                 * Falls through to the normal lane when the host facade predates `reportBugDetailed`
+                 * — an older app bundling a newer config degrades to existing behaviour instead of
+                 * dropping the user's report on the floor.
+                 */
+                const bugLane =
+                    campaign.fileAsBugReport && typeof (engage as any).reportBugDetailed === 'function'
+                        ? ((engage as any).reportBugDetailed as (i: {
+                              message: string;
+                              title?: string;
+                              clientReportId?: string;
+                          }) => Promise<unknown>)
+                        : null;
+
+                if (bugLane) {
+                    const outcome = await bugLane({
+                        message: result.reason ?? '',
+                        title: campaign.name,
+                        clientReportId: responseId,
+                    });
+                    // Surface a refusal as a throw so the existing retry/error UI handles it; a
+                    // silent success here would tell the user their report was filed when it wasn't.
+                    if (outcome && typeof outcome === 'object' && 'e' in (outcome as object)) {
+                        throw new Error(`bug report failed: ${(outcome as { e: string }).e}`);
+                    }
+                } else if (engage.submitResponseConfirmed) {
                     // Confirmed lane: awaits real persistence (presign+PUT bytes → response
                     // POST), reports stages, idempotent on responseId, throws on failure.
                     await engage.submitResponseConfirmed(input, drafts, {
@@ -676,7 +716,13 @@ export function EngagePromptProvider({
                     action: options?.action,
                 });
                 if (!campaign) {
-                    logger.debug('[Engage] no eligible campaign to render');
+                    // Name the inputs so a silent mismatch (wrong trigger name, throttle
+                    // suppression, type filter) is diagnosable from device logs alone.
+                    logger.debug(
+                        `[Engage] no eligible campaign to render (trigger=${options?.trigger ?? '—'} ` +
+                            `candidates=${config.campaigns.length} ` +
+                            `[${config.campaigns.map((c) => `${c.type}:${c.trigger ?? '—'}`).join(', ')}])`,
+                    );
                     return false;
                 }
 

package/src/features/engage/EngagePromptView.tsx

@@ -241,7 +241,21 @@ function RatingPrompt({ campaign, onSubmit, onDismiss, onStart, rating }: Prompt
 
 // ─── FEEDBACK render branch (free text + optional category/tags) ─────────────
 
-function FeedbackPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchProps): ReactElement {
+function FeedbackPrompt(props: PromptBranchProps): ReactElement {
+    // A FEEDBACK campaign authored with structured questions (voice, scale, emoji,
+    // screenshot, multiple prompts) IS a survey — this branch only knows how to draw
+    // one text box plus category chips, and used to silently render a voice question
+    // as text (found live: "it was supposed to be a voice input but showed text").
+    // Anything beyond chips delegates to the full survey renderer, which owns the
+    // record → transcribe → approve voice flow.
+    const structured = (props.campaign.questions ?? []).some(
+        (q) => q.kind !== 'choice' && q.kind !== 'single' && q.kind !== 'multi',
+    );
+    if (structured) return <SurveyPrompt {...props} />;
+    return <FeedbackTextPrompt {...props} />;
+}
+
+function FeedbackTextPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchProps): ReactElement {
     const [text, setText] = useState('');
     const [selectedTags, setSelectedTags] = useState<string[]>([]);
 
@@ -500,7 +514,14 @@ function SurveyPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchPr
                 return result;
             }, []);
 
+    // A survey where every question is optional could be submitted with nothing
+    // answered and nothing attached — an empty response row polluting analytics
+    // (found live: voice question, Submit tapped without ever recording). Content
+    // is what gates the final Submit; "Not now" remains the way out.
+    const hasAnyContent = (): boolean => questions.some((q) => isAnswered(q));
+
     const submit = (): void => {
+        if (!hasAnyContent()) return;
         const drafts = Object.values(attachments);
         onSubmit({
             answers: assemble(),
@@ -739,17 +760,25 @@ function SurveyPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchPr
                     <Pressable accessibilityRole="button" accessibilityLabel="Start survey" onPress={() => { onStart?.(); setStep(0); }} style={styles.submitBtn}>
                         <Text style={styles.submitText}>Start</Text>
                     </Pressable>
-                ) : current ? (
-                    <Pressable
-                        accessibilityRole="button"
-                        accessibilityLabel={step === questions.length - 1 || current.skipTo === 'end' ? 'Submit survey' : 'Continue survey'}
-                        disabled={current.required === true && !isAnswered(current)}
-                        onPress={advance}
-                        style={[styles.submitBtn, current.required === true && !isAnswered(current) ? styles.submitBtnDisabled : null]}
-                    >
-                        <Text style={styles.submitText}>{step === questions.length - 1 || current.skipTo === 'end' ? 'Submit' : 'Continue'}</Text>
-                    </Pressable>
-                ) : null}
+                ) : current ? (() => {
+                    const isSubmitStep = step === questions.length - 1 || current.skipTo === 'end';
+                    // A required question blocks its own step; the submit step
+                    // additionally requires the survey to carry ANY content at all.
+                    const blocked =
+                        (current.required === true && !isAnswered(current)) ||
+                        (isSubmitStep && !hasAnyContent());
+                    return (
+                        <Pressable
+                            accessibilityRole="button"
+                            accessibilityLabel={isSubmitStep ? 'Submit survey' : 'Continue survey'}
+                            disabled={blocked}
+                            onPress={advance}
+                            style={[styles.submitBtn, blocked ? styles.submitBtnDisabled : null]}
+                        >
+                            <Text style={styles.submitText}>{isSubmitStep ? 'Submit' : 'Continue'}</Text>
+                        </Pressable>
+                    );
+                })() : null}
             </View>
         </View>
     );
@@ -845,12 +874,19 @@ function VoiceQuestion({
                 🎙 Voice note recorded · {formatElapsed(draft.durationMs ?? 0)}
             </Text>
             <Text style={styles.voiceHint}>
-                Review the transcript below — edit it, then approve to send. Nothing is
-                sent until you approve.
+                {(draft.transcript ?? '').trim().length > 0
+                    ? 'Review the transcript below — edit it, then approve to send. Nothing is sent until you approve.'
+                    : // An empty prefill is a device limitation (on many phones the recorder
+                      // holds the microphone, so the on-device engine hears silence) — the
+                      // recording itself was captured fine. Say so, or the blank field reads
+                      // as a bug and the typed-transcript path goes undiscovered.
+                      'Your recording was captured, but automatic transcription wasn’t available on this device. Type what you said (optional), then approve to send.'}
             </Text>
             <TextInput
                 style={styles.reasonInput}
-                placeholder="Transcript (edit before approving)"
+                placeholder={(draft.transcript ?? '').trim().length > 0
+                    ? 'Transcript (edit before approving)'
+                    : 'Type what you said (optional)'}
                 placeholderTextColor="#9097A3"
                 value={draft.transcript ?? ''}
                 onChangeText={onEditTranscript}

package/src/features/engage/engageTriggerEngine.ts

@@ -106,6 +106,21 @@ export function installEngageTriggerEngine(deps: EngageTriggerEngineDeps): () =>
 
     const fire = (options: ShowEngagePromptOptions): void => {
         try {
+            // A fire while the app is not foregrounded renders behind the lock
+            // screen (or into a backgrounded activity), records the impression,
+            // and permanently consumes a showOnce campaign that no human saw.
+            // Found live: a cold start with the screen off burned both a survey
+            // and an in-app message before the phone was ever unlocked.
+            if (appLifecycle.getCurrentState() !== 'active') {
+                logger.debug(
+                    `[Engage] trigger suppressed (app ${appLifecycle.getCurrentState()}): ${options.trigger ?? 'manual'}`,
+                );
+                return;
+            }
+            logger.debug(
+                `[Engage] trigger fire: ${options.trigger ?? 'manual'}` +
+                    (options.screen ? ` screen=${options.screen}` : ''),
+            );
             deps.fire(options);
         } catch (err) {
             logger.debug('[Engage] trigger fire failed:', (err as Error)?.message);

package/src/features/engage/engageTypes.ts

@@ -110,6 +110,21 @@ export interface EngageCampaignConfig {
     storeUrl?: string;
     highRatingThreshold?: number;
     routeLowToFeedback?: boolean;
+    /**
+     * Route this campaign's submission to BUG REPORTS instead of Engage responses.
+     *
+     * Engage responses and bug reports are different products: a survey response measures sentiment
+     * in aggregate, while a bug report is a single item that gets a status, a priority and an
+     * assignee on /diagnose/bug-reports. A FEEDBACK campaign triggered by `shake_device` is almost
+     * always the second kind — someone shook the phone because something is broken.
+     *
+     * Opt-IN per campaign rather than rerouting every FEEDBACK campaign, because rerouting would
+     * silently break existing sentiment surveys, and because the destination should be visible to
+     * whoever configures the campaign rather than inferred from its trigger.
+     *
+     * Absent/false keeps the existing behaviour exactly.
+     */
+    fileAsBugReport?: boolean;
     enabled: boolean;
 }
 

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -30,6 +30,7 @@ import React, {
 import { View, NativeEventEmitter, NativeModules } from 'react-native';
 import { emitAutomaticEvent } from '../../analytics/automaticEvents';
 import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
+import { resolvePlatformOS } from '../../core/context/device';
 
 // ─── Lazy imports to avoid native module cascade at load time ────────────────
 // We only import TYPE references at the top level; actual modules are require()'d
@@ -159,7 +160,7 @@ export function ScaleBunDebugRoot({
                                         byteSize: result.sizeBytes || Math.round(result.base64.length * 0.75),
                                         format: (result.format ?? 'jpeg') as string,
                                         frameHash: (result as any).frameHash as string | undefined,
-                                        platform: (Platform.OS === 'ios' ? 'ios' : 'android') as 'android' | 'ios',
+                                        platform: resolvePlatformOS() as 'android' | 'ios',
                                     };
                                 } catch {
                                     return null;

package/src/features/ota/OtaOrchestrator.ts

@@ -11,10 +11,14 @@ import { noThrow } from '../../core/lifecycle/crashSafe';
 import NativeScaleBunOta from '../../specs/NativeScaleBunOta';
 import type { OtaCheckRequest, OtaCheckResponse, OtaBundlePayload } from './OtaTypes';
 import { otaEventEmitter } from './OtaEventEmitter';
+import { getDeviceCountry, prefetchDeviceCountry } from './geoCountry';
+import { deviceTargetingAttributes } from './deviceAttributes';
+import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
 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';
+import { resolveMobileOS } from '../../core/context/device';
 
 /**
  * Identity marker injected into the bundle by `scalebun ota publish` before
@@ -67,6 +71,36 @@ function subscribeNativeProgress(
 /** POST at most once per this interval; first and terminal ticks always go. */
 const PROGRESS_POST_INTERVAL_MS = 1_000;
 
+/**
+ * P8 — the SDK's canonical per-install id, shared with the analytics lane.
+ *
+ * OTA used to REQUIRE a caller-supplied `installationId`, and the documented
+ * example passed `deviceId` — so OTA telemetry lived in its own identity
+ * namespace, disconnected from the id every other lane reports. Every join
+ * from OTA data to CDP data (blast radius, MRR-at-risk, churn bands) was a
+ * cross-namespace join that matched by luck.
+ *
+ * Reads (or mints, for OTA-only apps that never initialize analytics) the same
+ * persisted value `EventTracker` uses, via the same storage backend and the
+ * same exported key — one install, one id, every lane.
+ */
+function resolveInstallationId(): string {
+  try {
+    const storage = createStorageBackend();
+    const existing = storage.get(K_INSTALLATION_ID);
+    if (existing) return existing;
+    const id = `inst-${Math.random().toString(36).slice(2, 10)}${Math.random()
+      .toString(36)
+      .slice(2, 10)}`;
+    storage.set(K_INSTALLATION_ID, id);
+    return id;
+  } catch {
+    // Storage unavailable (tests, exotic hosts): a per-process id keeps sync
+    // functional; it will stabilize on the first run where storage works.
+    return `inst-ephemeral-${Math.random().toString(36).slice(2, 10)}`;
+  }
+}
+
 /**
  * Deliver queued OTA lifecycle events to the backend's batch endpoint.
  *
@@ -93,13 +127,18 @@ async function deliverOtaEvents(params: {
 }): Promise<void> {
   const events = otaEventEmitter.flush();
   if (!events.length) return;
+  // A platform OTA cannot serve is not reported as Android — it is not reported at all.
+  const mobileOS = resolveMobileOS();
+  if (!mobileOS) return;
 
   const items = events.map((e) => ({
     kind: 'ota_event' as const,
     type: e.type,
     bundleId: e.bundleId,
     installationId: params.installationId,
-    platform: Platform.OS === 'ios' ? 'ios' : 'android',
+    // 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.
+    platform: mobileOS,
     appVersion: params.appVersion,
     durationMs: e.durationMs,
     errorCode: e.error ?? e.reason,
@@ -244,6 +283,11 @@ export class OtaOrchestrator {
       // no way to know what the device was actually on.
       this.hydrateCurrentBundleFromSlots();
 
+      // 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();
+
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
 
@@ -472,15 +516,24 @@ export class OtaOrchestrator {
       // never carried it — so every device resolved to `default` no matter what
       // the host app asked for. Undefined fields are omitted by JSON.stringify,
       // so an app that supplies nothing behaves exactly as before.
+      // 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');
       const payload: OtaCheckRequest = {
         appVersion: requestParams.appVersion,
-        platform: Platform.OS === 'ios' ? 'ios' : 'android',
+        platform: mobileOS,
         installationId: requestParams.installationId,
         currentBundleId: this.currentBundle?.id,
         currentBundleHash: this.currentBundle?.sha256,
         channelName: requestParams.channelName,
-        country: requestParams.country,
-        attributes: requestParams.attributes,
+        // Host-supplied country wins; otherwise the cached edge-Worker lookup
+        // fills in (see geoCountry.ts). Undefined when neither knows — the
+        // server renders unknown as unknown rather than guessing.
+        country: requestParams.country ?? getDeviceCountry() ?? undefined,
+        // Hardware/OS context under the host's own attributes (host wins on
+        // collision) — this is what lets ATTRIBUTE rules target device classes
+        // (deviceModel / manufacturer / brand / osVersion / formFactor).
+        attributes: { ...deviceTargetingAttributes(), ...requestParams.attributes },
         segmentIds: requestParams.segmentIds,
         lifecycleStage: requestParams.lifecycleStage,
         // Runtime compatibility context. Without these the backend cannot tell
@@ -529,13 +582,29 @@ export class OtaOrchestrator {
    * Downloads, stage, and apply an update in one step.
    * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
    */
-  async sync(params: {
+  async sync(rawParams: {
     apiUrl: string;
     clientKey: string;
     appVersion: string;
-    installationId: string;
+    /** Omit to use the SDK's canonical per-install id (recommended — P8). */
+    installationId?: string;
+    // P1: these five existed on checkForUpdate and on the wire contract, but
+    // sync() — the only caller that matters — never accepted them, so they
+    // were structurally undefined on every real device: every install pinned
+    // to the `default` channel and the whole targeting engine matched nothing.
+    // The C1 comment in OtaTypes.ts claimed this was fixed; the plumbing had
+    // stopped exactly one function short of true.
+    channelName?: string;
+    country?: string;
+    attributes?: Record<string, string | number>;
+    segmentIds?: string[];
+    lifecycleStage?: string;
     autoRestart?: boolean;
   }): Promise<SyncResult> {
+    const params = {
+      ...rawParams,
+      installationId: rawParams.installationId ?? resolveInstallationId(),
+    };
     try {
       if (!this.enabled || !NativeScaleBunOta) {
         return { status: 'ERROR', error: 'OTA native module disabled or missing' };

package/src/features/ota/deviceAttributes.ts

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