@switchlabs/verify-ai-react-native 2.5.4 → 2.5.6

package/lib/components/VerifyAIScanner.js

@@ -272,6 +272,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
     const scannerSessionIdRef = useRef(createScannerSessionId());
     const captureSequenceRef = useRef(0);
+    const captureIntentPendingRef = useRef(false);
     const torchRetrySuppressedRef = useRef(false);
     const [torchRetrySuppressed, setTorchRetrySuppressed] = useState(false);
     const buildScannerTelemetryMetadata = useCallback((extra = {}) => compactTelemetryMetadata({
@@ -294,6 +295,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         device_os_version: String(Platform.Version),
         route_name: telemetryContext?.routeName,
         is_portrait_locked: telemetryContext?.isPortraitLocked,
+        host_reference_id: telemetryContext?.hostReferenceId,
         window_width: windowWidth,
         window_height: windowHeight,
         interface_orientation: isLandscape ? 'landscape' : 'portrait',
@@ -350,6 +352,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         policy,
         status,
         telemetryContext?.isPortraitLocked,
+        telemetryContext?.hostReferenceId,
         telemetryContext?.routeName,
         terminated,
         windowHeight,
@@ -437,6 +440,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             device_os_version: String(Platform.Version),
             route_name: telemetryContext?.routeName,
             is_portrait_locked: telemetryContext?.isPortraitLocked,
+            host_reference_id: telemetryContext?.hostReferenceId,
             android_native_orientation_subscription_active: 0,
             android_native_orientation_event_count: 0,
             android_native_orientation_change_count: 0,
@@ -615,7 +619,13 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 trackAndroidOrientationEvent('camera_android_accelerometer_stopped', 'android_accelerometer_tracking_stopped', { accelerometer_stop_reason: 'orientation_tracking_stopped' });
             }
         };
-    }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
+    }, [
+        policy,
+        telemetry,
+        telemetryContext?.hostReferenceId,
+        telemetryContext?.isPortraitLocked,
+        telemetryContext?.routeName,
+    ]);
     // Detect orientation changes and remount camera after rotation settles.
     // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
     // animation — the native preview layer initializes with transitional bounds.
@@ -901,28 +911,47 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         const captureSequence = captureSequenceRef.current + 1;
         captureSequenceRef.current = captureSequence;
         const captureAttemptId = `${scannerSessionIdRef.current}_cap_${captureSequence}`;
-        const blockedReason = !cameraRef.current
-            ? 'camera_ref_null'
-            : !cameraReadyRef.current
-                ? 'camera_not_ready'
-                : status === 'capturing'
-                    ? 'already_capturing'
-                    : status === 'processing'
-                        ? 'already_processing'
-                        : terminated
-                            ? 'terminated'
-                            : exhausted
-                                ? 'exhausted'
-                                : null;
-        telemetry?.track('camera_capture_request', {
-            component: 'scanner',
-            error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
-            metadata: buildScannerTelemetryMetadata({
-                capture_attempt_id: captureAttemptId,
-                capture_sequence: captureSequence,
-                capture_blocked_reason: blockedReason,
-            }),
-        });
+        const blockedReason = captureIntentPendingRef.current
+            ? 'capture_intent_pending'
+            : !cameraRef.current
+                ? 'camera_ref_null'
+                : !cameraReadyRef.current
+                    ? 'camera_not_ready'
+                    : status === 'capturing'
+                        ? 'already_capturing'
+                        : status === 'processing'
+                            ? 'already_processing'
+                            : terminated
+                                ? 'terminated'
+                                : exhausted
+                                    ? 'exhausted'
+                                    : null;
+        if (blockedReason == null)
+            captureIntentPendingRef.current = true;
+        if (telemetry) {
+            // Do not begin native capture until the user's shutter intent is on disk.
+            // If the process is force-closed during capture or delivery, the next SDK
+            // initialization recovers and sends this exact capture_attempt_id.
+            const persisted = await telemetry.trackDurably('camera_capture_request', {
+                component: 'scanner',
+                error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+                metadata: buildScannerTelemetryMetadata({
+                    capture_attempt_id: captureAttemptId,
+                    capture_sequence: captureSequence,
+                    capture_blocked_reason: blockedReason,
+                }),
+            });
+            if (!persisted) {
+                telemetry.track('telemetry_persist_failure', {
+                    component: 'scanner',
+                    error: 'capture_intent_persist_failed',
+                    metadata: buildScannerTelemetryMetadata({
+                        capture_attempt_id: captureAttemptId,
+                        capture_sequence: captureSequence,
+                    }),
+                });
+            }
+        }
         if (blockedReason && blockedReason !== 'camera_not_ready')
             return;
         if (blockedReason === 'camera_not_ready') {
@@ -1223,6 +1252,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             }
         }
         finally {
+            captureIntentPendingRef.current = false;
             setTorchSuppressedForRetry(false);
         }
     }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg, enableTorch, setTorchSuppressedForRetry]);

package/lib/telemetry/TelemetryReporter.d.ts

@@ -1,13 +1,24 @@
+interface TelemetryTrackOptions {
+    component?: string;
+    error?: unknown;
+    errorCode?: string;
+    metadata?: Record<string, string | number>;
+}
 export declare class TelemetryReporter {
     private buffer;
+    private inFlightBuffer;
+    private dedupIndex;
     private flushTimer;
     private sessionId;
     private baseUrl;
     private apiKey;
+    private storagePrefix;
     private disposed;
     private flushing;
     private loadedPersisted;
     private loadPersistedPromise;
+    private persistenceChain;
+    private eventSequence;
     constructor(apiKey: string, baseUrl: string);
     /** Telemetry POST destination — exposed so the scanner can log an init banner
      * that helps field debugging confirm where events are being sent. */
@@ -16,12 +27,14 @@ export declare class TelemetryReporter {
     getApiKeyPrefix(): string;
     private logDeliveryFailure;
     /** Track an error event. Fire-and-forget — never throws. */
-    track(eventType: string, opts?: {
-        component?: string;
-        error?: unknown;
-        errorCode?: string;
-        metadata?: Record<string, string | number>;
-    }): void;
+    track(eventType: string, opts?: TelemetryTrackOptions): void;
+    /**
+     * Record an event and wait until it is durably stored before returning.
+     *
+     * Use this for user intent that must survive an immediate force-close. Network
+     * delivery starts after the local write, but callers do not wait on the network.
+     */
+    trackDurably(eventType: string, opts?: TelemetryTrackOptions): Promise<boolean>;
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
     flush(): Promise<void>;
     /** Dispose — flush remaining events and stop timers. */
@@ -29,14 +42,12 @@ export declare class TelemetryReporter {
     private scheduleFlush;
     private flushNow;
     private clearFlushTimer;
-    /**
-     * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
-     * Fire-and-forget — never throws or blocks.
-     *
-     * IMPORTANT: skips persist if loadPersistedBuffer() hasn't completed yet,
-     * to avoid overwriting orphaned events from a previous session before recovery.
-     */
-    private persistBuffer;
+    private recordEvent;
+    private persistAfterRecovery;
+    private createJournalKey;
+    private persistBufferAsync;
+    private removeJournalEntries;
+    private releaseClaims;
     /**
      * Load persisted events from a previous session and merge into current buffer.
      * Runs once per instance. If orphaned events are found, emits an
@@ -45,3 +56,4 @@ export declare class TelemetryReporter {
      */
     private loadPersistedBuffer;
 }
+export {};

package/lib/telemetry/TelemetryReporter.js

@@ -8,13 +8,30 @@ async function getStorage() {
     }
     return _storage;
 }
-const TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const LEGACY_TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const TELEMETRY_EVENT_KEY_PREFIX = '@verifyai/telemetry_event/';
+const MAX_EVENTS_PER_REQUEST = 25;
+// Per-event journal keys avoid shared full-buffer replacement. Claims prevent
+// two reporters in the same process from recovering/sending the same event.
+const claimedEventKeys = new Set();
+let legacyBufferClaimed = false;
+function telemetryTargetId(apiKey, baseUrl) {
+    let hash = 2166136261;
+    const input = `${baseUrl}|${apiKey}`;
+    for (let index = 0; index < input.length; index++) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(36);
+}
 /** Event types that flush immediately (critical init failures). */
 const CRITICAL_EVENTS = new Set([
     'camera_init_failure',
     'camera_preview_timeout',
     'camera_startup_slow',
     'camera_permission_denied',
+    'camera_capture_request',
+    'telemetry_persist_failure',
     'camera_scanner_mounted',
     'camera_scanner_disposed',
     'camera_android_native_orientation_started',
@@ -30,13 +47,18 @@ const CRITICAL_EVENTS = new Set([
 export class TelemetryReporter {
     constructor(apiKey, baseUrl) {
         this.buffer = new Map();
+        this.inFlightBuffer = new Map();
+        this.dedupIndex = new Map();
         this.flushTimer = null;
         this.disposed = false;
         this.flushing = false;
         this.loadedPersisted = false;
         this.loadPersistedPromise = null;
+        this.persistenceChain = Promise.resolve();
+        this.eventSequence = 0;
         this.apiKey = apiKey;
         this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.storagePrefix = `${TELEMETRY_EVENT_KEY_PREFIX}${telemetryTargetId(apiKey, this.baseUrl)}/`;
         this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
         // Load any persisted events left behind by a previous session
         this.loadPersistedBuffer();
@@ -60,61 +82,44 @@ export class TelemetryReporter {
         if (this.disposed)
             return;
         try {
-            const now = new Date().toISOString();
-            const errorObj = opts.error instanceof Error ? opts.error : null;
-            const errorMessage = errorObj?.message
-                ?? (typeof opts.error === 'string' ? opts.error : undefined);
-            const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}`;
-            const existing = this.buffer.get(dedupKey);
-            if (existing) {
-                existing.event_count++;
-                existing.last_occurred_at = now;
-                // If the new occurrence is critical, flush immediately
-                if (CRITICAL_EVENTS.has(eventType)) {
-                    this.flushNow();
-                }
-                return;
-            }
-            const event = {
-                event_type: eventType,
-                component: opts.component,
-                error_message: errorMessage?.slice(0, 1000),
-                error_stack: errorObj?.stack?.slice(0, 2000),
-                error_code: opts.errorCode,
-                metadata: opts.metadata,
-                sdk_platform: Platform.OS,
-                sdk_version: SDK_VERSION,
-                os_name: Platform.OS,
-                os_version: String(Platform.Version),
-                session_id: this.sessionId,
-                event_count: 1,
-                first_occurred_at: now,
-                last_occurred_at: now,
-            };
-            this.buffer.set(dedupKey, event);
+            this.recordEvent(eventType, opts);
             if (CRITICAL_EVENTS.has(eventType)) {
-                this.flushNow();
+                // Critical events are written locally before delivery starts. This keeps
+                // them recoverable if the process is killed while the POST is in flight.
+                void this.persistAfterRecovery().then(() => this.flushNow());
             }
             else {
                 this.scheduleFlush();
-            }
-            // Persist immediately once prior-session recovery has completed. If startup
-            // recovery is still in flight, write the merged buffer back afterwards.
-            if (this.loadedPersisted) {
-                this.persistBuffer();
-            }
-            else {
-                void this.loadPersistedBuffer().then(() => {
-                    if (!this.disposed && this.buffer.size > 0) {
-                        this.persistBuffer();
-                    }
-                });
+                void this.persistAfterRecovery();
             }
         }
         catch {
             // Never throw from telemetry
         }
     }
+    /**
+     * Record an event and wait until it is durably stored before returning.
+     *
+     * Use this for user intent that must survive an immediate force-close. Network
+     * delivery starts after the local write, but callers do not wait on the network.
+     */
+    async trackDurably(eventType, opts = {}) {
+        if (this.disposed)
+            return false;
+        try {
+            await this.loadPersistedBuffer();
+            if (this.disposed)
+                return false;
+            this.recordEvent(eventType, opts);
+            const persisted = await this.persistBufferAsync();
+            this.flushNow();
+            return persisted;
+        }
+        catch {
+            // Never throw from telemetry or block the host capture flow.
+            return false;
+        }
+    }
     /** Flush all buffered events immediately. Returns a promise but never rejects. */
     async flush() {
         // Merge any persisted events from a previous session before flushing
@@ -122,13 +127,16 @@ export class TelemetryReporter {
         if (this.buffer.size === 0 || this.flushing)
             return;
         this.flushing = true;
-        const bufferedEntries = Array.from(this.buffer.entries());
+        const bufferedEntries = Array.from(this.buffer.entries()).slice(0, MAX_EVENTS_PER_REQUEST);
         const events = bufferedEntries.map(([, event]) => event);
-        this.buffer.clear();
+        for (const [key] of bufferedEntries)
+            this.buffer.delete(key);
+        this.inFlightBuffer = new Map(bufferedEntries);
         this.clearFlushTimer();
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 10000);
         let loggedDeliveryFailure = false;
+        let delivered = false;
         try {
             const response = await fetch(`${this.baseUrl}/telemetry`, {
                 method: 'POST',
@@ -151,8 +159,19 @@ export class TelemetryReporter {
                 loggedDeliveryFailure = true;
                 throw new Error(`Telemetry request failed with status ${response.status}`);
             }
-            // Success — clear persisted buffer since events are now server-side
-            this.persistBuffer(); // buffer is empty at this point, so this clears the key
+            const acknowledgedKeys = bufferedEntries.map(([key]) => key);
+            const acknowledgedKeySet = new Set(acknowledgedKeys);
+            const removed = await this.removeJournalEntries(acknowledgedKeys);
+            if (removed) {
+                for (const key of acknowledgedKeys)
+                    claimedEventKeys.delete(key);
+            }
+            this.inFlightBuffer.clear();
+            for (const [dedupKey, journalKey] of this.dedupIndex) {
+                if (acknowledgedKeySet.has(journalKey))
+                    this.dedupIndex.delete(dedupKey);
+            }
+            delivered = true;
         }
         catch (error) {
             if (!loggedDeliveryFailure) {
@@ -175,6 +194,7 @@ export class TelemetryReporter {
                     this.buffer.set(dedupKey, event);
                 }
             }
+            this.inFlightBuffer.clear();
         }
         finally {
             clearTimeout(timeout);
@@ -183,12 +203,17 @@ export class TelemetryReporter {
                 this.scheduleFlush();
             }
         }
+        // Drain oversized recovered journals in API-sized chunks. A failed chunk is
+        // rebuffered and left for the normal retry timer instead of spinning.
+        if (delivered && this.buffer.size > 0 && !this.disposed) {
+            await this.flush();
+        }
     }
     /** Dispose — flush remaining events and stop timers. */
     dispose() {
         this.disposed = true;
         this.clearFlushTimer();
-        this.flush();
+        void this.flush().finally(() => this.releaseClaims());
     }
     scheduleFlush() {
         if (this.flushTimer)
@@ -208,34 +233,105 @@ export class TelemetryReporter {
             this.flushTimer = null;
         }
     }
-    /**
-     * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
-     * Fire-and-forget — never throws or blocks.
-     *
-     * IMPORTANT: skips persist if loadPersistedBuffer() hasn't completed yet,
-     * to avoid overwriting orphaned events from a previous session before recovery.
-     */
-    persistBuffer() {
+    recordEvent(eventType, opts) {
+        const now = new Date().toISOString();
+        const errorObj = opts.error instanceof Error ? opts.error : null;
+        const errorMessage = errorObj?.message
+            ?? (typeof opts.error === 'string' ? opts.error : undefined);
+        const occurrenceId = opts.metadata?.capture_attempt_id;
+        const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}|${occurrenceId ?? ''}`;
+        const existingJournalKey = this.dedupIndex.get(dedupKey);
+        const existing = existingJournalKey
+            ? this.buffer.get(existingJournalKey)
+            : undefined;
+        if (existing) {
+            existing.event_count++;
+            existing.last_occurred_at = now;
+            if (opts.metadata)
+                existing.metadata = { ...existing.metadata, ...opts.metadata };
+            return;
+        }
+        const journalKey = this.createJournalKey();
+        this.dedupIndex.set(dedupKey, journalKey);
+        claimedEventKeys.add(journalKey);
+        const eventMetadata = {
+            ...opts.metadata,
+            telemetry_event_id: journalKey.slice(this.storagePrefix.length),
+        };
+        this.buffer.set(journalKey, {
+            event_type: eventType,
+            component: opts.component,
+            error_message: errorMessage?.slice(0, 1000),
+            error_stack: errorObj?.stack?.slice(0, 2000),
+            error_code: opts.errorCode,
+            metadata: eventMetadata,
+            sdk_platform: Platform.OS,
+            sdk_version: SDK_VERSION,
+            os_name: Platform.OS,
+            os_version: String(Platform.Version),
+            session_id: this.sessionId,
+            event_count: 1,
+            first_occurred_at: now,
+            last_occurred_at: now,
+        });
+    }
+    async persistAfterRecovery() {
+        await this.loadPersistedBuffer();
+        await this.persistBufferAsync();
+    }
+    createJournalKey() {
+        this.eventSequence++;
+        return `${this.storagePrefix}${this.sessionId}:${this.eventSequence.toString(36)}`;
+    }
+    async persistBufferAsync() {
         if (!this.loadedPersisted)
-            return; // Don't overwrite orphaned prior-session data before it's loaded
+            return Promise.resolve(false);
         try {
-            const entries = {};
-            for (const [key, event] of this.buffer) {
-                entries[key] = event;
-            }
-            getStorage().then(s => {
-                if (Object.keys(entries).length > 0) {
-                    s.setItem(TELEMETRY_PERSIST_KEY, JSON.stringify(entries));
-                }
-                else {
-                    s.removeItem(TELEMETRY_PERSIST_KEY);
+            const entries = [
+                ...this.inFlightBuffer.entries(),
+                ...this.buffer.entries(),
+            ];
+            const operation = this.persistenceChain
+                .catch(() => { })
+                .then(async () => {
+                const storage = await getStorage();
+                if (entries.length > 0) {
+                    await storage.multiSet(entries.map(([key, event]) => [key, JSON.stringify(event)]));
                 }
-            }).catch(() => { });
+            });
+            this.persistenceChain = operation.catch(() => { });
+            await operation;
+            return true;
         }
         catch {
             // Never throw from telemetry
+            return false;
+        }
+    }
+    async removeJournalEntries(keys) {
+        if (keys.length === 0)
+            return true;
+        try {
+            const operation = this.persistenceChain
+                .catch(() => { })
+                .then(async () => {
+                const storage = await getStorage();
+                await storage.multiRemove(keys);
+            });
+            this.persistenceChain = operation.catch(() => { });
+            await operation;
+            return true;
+        }
+        catch {
+            return false;
         }
     }
+    releaseClaims() {
+        for (const key of this.buffer.keys())
+            claimedEventKeys.delete(key);
+        for (const key of this.inFlightBuffer.keys())
+            claimedEventKeys.delete(key);
+    }
     /**
      * Load persisted events from a previous session and merge into current buffer.
      * Runs once per instance. If orphaned events are found, emits an
@@ -250,65 +346,89 @@ export class TelemetryReporter {
             return;
         }
         this.loadPersistedPromise = (async () => {
+            const claimedDuringRecovery = [];
             try {
                 const storage = await getStorage();
-                const raw = await storage.getItem(TELEMETRY_PERSIST_KEY);
-                if (!raw)
-                    return;
-                const entries = JSON.parse(raw);
                 let orphanedCount = 0;
                 const orphanedTypes = [];
-                for (const [key, event] of Object.entries(entries)) {
-                    if (event.session_id === this.sessionId)
-                        continue; // Same session, skip
-                    orphanedCount++;
-                    orphanedTypes.push(event.event_type);
-                    // Merge orphaned events into the current buffer
-                    const existing = this.buffer.get(key);
-                    if (existing) {
-                        existing.event_count += event.event_count;
-                        if (event.first_occurred_at < existing.first_occurred_at) {
-                            existing.first_occurred_at = event.first_occurred_at;
-                        }
-                        if (event.last_occurred_at > existing.last_occurred_at) {
-                            existing.last_occurred_at = event.last_occurred_at;
-                        }
+                const allKeys = await storage.getAllKeys();
+                const recoverableKeys = allKeys.filter((key) => {
+                    if (!key.startsWith(this.storagePrefix))
+                        return false;
+                    if (claimedEventKeys.has(key))
+                        return false;
+                    claimedEventKeys.add(key);
+                    claimedDuringRecovery.push(key);
+                    return true;
+                });
+                const recoveredPairs = recoverableKeys.length > 0
+                    ? await storage.multiGet(recoverableKeys)
+                    : [];
+                for (const [key, raw] of recoveredPairs) {
+                    if (!raw) {
+                        claimedEventKeys.delete(key);
+                        continue;
                     }
-                    else {
+                    try {
+                        const event = JSON.parse(raw);
+                        orphanedCount++;
+                        orphanedTypes.push(event.event_type);
                         this.buffer.set(key, event);
                     }
+                    catch {
+                        claimedEventKeys.delete(key);
+                    }
+                }
+                // Migrate the pre-2.5.6 shared snapshot without a remove/rewrite gap:
+                // write each event journal entry first, then delete the legacy key.
+                if (!legacyBufferClaimed && allKeys.includes(LEGACY_TELEMETRY_PERSIST_KEY)) {
+                    legacyBufferClaimed = true;
+                    let migrated = false;
+                    try {
+                        const legacyRaw = await storage.getItem(LEGACY_TELEMETRY_PERSIST_KEY);
+                        if (legacyRaw) {
+                            const legacyEntries = JSON.parse(legacyRaw);
+                            const migrationPairs = [];
+                            for (const event of Object.values(legacyEntries)) {
+                                const key = this.createJournalKey();
+                                claimedEventKeys.add(key);
+                                this.buffer.set(key, event);
+                                orphanedCount++;
+                                orphanedTypes.push(event.event_type);
+                                migrationPairs.push([key, JSON.stringify(event)]);
+                            }
+                            if (migrationPairs.length > 0)
+                                await storage.multiSet(migrationPairs);
+                        }
+                        await storage.removeItem(LEGACY_TELEMETRY_PERSIST_KEY);
+                        migrated = true;
+                    }
+                    finally {
+                        if (!migrated)
+                            legacyBufferClaimed = false;
+                    }
                 }
                 // Emit sdk_session_recovered if we recovered orphaned events from a previous session
                 if (orphanedCount > 0) {
-                    const now = new Date().toISOString();
                     const uniqueTypes = [...new Set(orphanedTypes)];
-                    const crashEvent = {
-                        event_type: 'sdk_session_recovered',
+                    this.recordEvent('sdk_session_recovered', {
                         component: 'TelemetryReporter',
-                        error_message: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
-                        sdk_platform: Platform.OS,
-                        sdk_version: SDK_VERSION,
-                        os_name: Platform.OS,
-                        os_version: String(Platform.Version),
-                        session_id: this.sessionId,
-                        event_count: 1,
-                        first_occurred_at: now,
-                        last_occurred_at: now,
-                    };
-                    this.buffer.set(`sdk_session_recovered|recovered|${this.sessionId}`, crashEvent);
+                        error: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
+                    });
                 }
-                // Clear persisted data now that it's loaded into memory. The merged
-                // buffer will be re-persisted below until a flush succeeds.
-                await storage.removeItem(TELEMETRY_PERSIST_KEY);
             }
             catch {
                 // Never throw from telemetry
+                for (const key of claimedDuringRecovery) {
+                    if (!this.buffer.has(key))
+                        claimedEventKeys.delete(key);
+                }
             }
             finally {
                 this.loadedPersisted = true;
                 this.loadPersistedPromise = null;
                 if (this.buffer.size > 0 && !this.disposed) {
-                    this.persistBuffer();
+                    await this.persistBufferAsync();
                     this.scheduleFlush();
                 }
             }

package/lib/types/index.d.ts

@@ -87,6 +87,8 @@ export interface ScannerTelemetryContext {
     routeName?: string;
     /** Whether the host app keeps this screen portrait-locked. */
     isPortraitLocked?: boolean;
+    /** Host-owned identifier used to correlate scanner telemetry with its workflow. */
+    hostReferenceId?: string;
 }
 /**
  * Theme customization for the scanner overlay.

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.5.4";
+export declare const SDK_VERSION = "2.5.6";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.5.4';
+export const SDK_VERSION = '2.5.6';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "repository": {
     "type": "git",

package/src/components/VerifyAIScanner.tsx

@@ -384,6 +384,7 @@ export function VerifyAIScanner({
   const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
   const scannerSessionIdRef = useRef(createScannerSessionId());
   const captureSequenceRef = useRef(0);
+  const captureIntentPendingRef = useRef(false);
   const torchRetrySuppressedRef = useRef(false);
   const [torchRetrySuppressed, setTorchRetrySuppressed] = useState(false);
 
@@ -409,6 +410,7 @@ export function VerifyAIScanner({
     device_os_version: String(Platform.Version),
     route_name: telemetryContext?.routeName,
     is_portrait_locked: telemetryContext?.isPortraitLocked,
+    host_reference_id: telemetryContext?.hostReferenceId,
     window_width: windowWidth,
     window_height: windowHeight,
     interface_orientation: isLandscape ? 'landscape' : 'portrait',
@@ -465,6 +467,7 @@ export function VerifyAIScanner({
     policy,
     status,
     telemetryContext?.isPortraitLocked,
+    telemetryContext?.hostReferenceId,
     telemetryContext?.routeName,
     terminated,
     windowHeight,
@@ -578,6 +581,7 @@ export function VerifyAIScanner({
       device_os_version: String(Platform.Version),
       route_name: telemetryContext?.routeName,
       is_portrait_locked: telemetryContext?.isPortraitLocked,
+      host_reference_id: telemetryContext?.hostReferenceId,
       android_native_orientation_subscription_active: 0,
       android_native_orientation_event_count: 0,
       android_native_orientation_change_count: 0,
@@ -786,7 +790,13 @@ export function VerifyAIScanner({
         );
       }
     };
-  }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
+  }, [
+    policy,
+    telemetry,
+    telemetryContext?.hostReferenceId,
+    telemetryContext?.isPortraitLocked,
+    telemetryContext?.routeName,
+  ]);
 
   // Detect orientation changes and remount camera after rotation settles.
   // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
@@ -1111,7 +1121,9 @@ export function VerifyAIScanner({
     captureSequenceRef.current = captureSequence;
     const captureAttemptId = `${scannerSessionIdRef.current}_cap_${captureSequence}`;
     const blockedReason =
-      !cameraRef.current
+      captureIntentPendingRef.current
+        ? 'capture_intent_pending'
+        : !cameraRef.current
         ? 'camera_ref_null'
         : !cameraReadyRef.current
           ? 'camera_not_ready'
@@ -1125,15 +1137,32 @@ export function VerifyAIScanner({
                   ? 'exhausted'
                   : null;
 
-    telemetry?.track('camera_capture_request', {
-      component: 'scanner',
-      error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
-      metadata: buildScannerTelemetryMetadata({
-        capture_attempt_id: captureAttemptId,
-        capture_sequence: captureSequence,
-        capture_blocked_reason: blockedReason,
-      }),
-    });
+    if (blockedReason == null) captureIntentPendingRef.current = true;
+
+    if (telemetry) {
+      // Do not begin native capture until the user's shutter intent is on disk.
+      // If the process is force-closed during capture or delivery, the next SDK
+      // initialization recovers and sends this exact capture_attempt_id.
+      const persisted = await telemetry.trackDurably('camera_capture_request', {
+        component: 'scanner',
+        error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+        metadata: buildScannerTelemetryMetadata({
+          capture_attempt_id: captureAttemptId,
+          capture_sequence: captureSequence,
+          capture_blocked_reason: blockedReason,
+        }),
+      });
+      if (!persisted) {
+        telemetry.track('telemetry_persist_failure', {
+          component: 'scanner',
+          error: 'capture_intent_persist_failed',
+          metadata: buildScannerTelemetryMetadata({
+            capture_attempt_id: captureAttemptId,
+            capture_sequence: captureSequence,
+          }),
+        });
+      }
+    }
 
     if (blockedReason && blockedReason !== 'camera_not_ready') return;
     if (blockedReason === 'camera_not_ready') {
@@ -1488,6 +1517,7 @@ export function VerifyAIScanner({
         setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
       }
     } finally {
+      captureIntentPendingRef.current = false;
       setTorchSuppressedForRetry(false);
     }
   }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg, enableTorch, setTorchSuppressedForRetry]);

package/src/telemetry/TelemetryReporter.ts

@@ -10,7 +10,24 @@ async function getStorage() {
   return _storage;
 }
 
-const TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const LEGACY_TELEMETRY_PERSIST_KEY = '@verifyai/telemetry_buffer';
+const TELEMETRY_EVENT_KEY_PREFIX = '@verifyai/telemetry_event/';
+const MAX_EVENTS_PER_REQUEST = 25;
+
+// Per-event journal keys avoid shared full-buffer replacement. Claims prevent
+// two reporters in the same process from recovering/sending the same event.
+const claimedEventKeys = new Set<string>();
+let legacyBufferClaimed = false;
+
+function telemetryTargetId(apiKey: string, baseUrl: string): string {
+  let hash = 2166136261;
+  const input = `${baseUrl}|${apiKey}`;
+  for (let index = 0; index < input.length; index++) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
 
 interface TelemetryEvent {
   event_type: string;
@@ -29,9 +46,11 @@ interface TelemetryEvent {
   last_occurred_at: string;
 }
 
-interface BufferedEvent {
-  event: TelemetryEvent;
-  dedupKey: string;
+interface TelemetryTrackOptions {
+  component?: string;
+  error?: unknown;
+  errorCode?: string;
+  metadata?: Record<string, string | number>;
 }
 
 /** Event types that flush immediately (critical init failures). */
@@ -40,6 +59,8 @@ const CRITICAL_EVENTS = new Set([
   'camera_preview_timeout',
   'camera_startup_slow',
   'camera_permission_denied',
+  'camera_capture_request',
+  'telemetry_persist_failure',
   'camera_scanner_mounted',
   'camera_scanner_disposed',
   'camera_android_native_orientation_started',
@@ -55,18 +76,24 @@ const CRITICAL_EVENTS = new Set([
 
 export class TelemetryReporter {
   private buffer: Map<string, TelemetryEvent> = new Map();
+  private inFlightBuffer: Map<string, TelemetryEvent> = new Map();
+  private dedupIndex: Map<string, string> = new Map();
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
   private sessionId: string;
   private baseUrl: string;
   private apiKey: string;
+  private storagePrefix: string;
   private disposed = false;
   private flushing = false;
   private loadedPersisted = false;
   private loadPersistedPromise: Promise<void> | null = null;
+  private persistenceChain: Promise<void> = Promise.resolve();
+  private eventSequence = 0;
 
   constructor(apiKey: string, baseUrl: string) {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.storagePrefix = `${TELEMETRY_EVENT_KEY_PREFIX}${telemetryTargetId(apiKey, this.baseUrl)}/`;
     this.sessionId = Math.random().toString(36).slice(2) + Date.now().toString(36);
     // Load any persisted events left behind by a previous session
     this.loadPersistedBuffer();
@@ -94,75 +121,51 @@ export class TelemetryReporter {
   /** Track an error event. Fire-and-forget — never throws. */
   track(
     eventType: string,
-    opts: {
-      component?: string;
-      error?: unknown;
-      errorCode?: string;
-      metadata?: Record<string, string | number>;
-    } = {},
+    opts: TelemetryTrackOptions = {},
   ): void {
     if (this.disposed) return;
 
     try {
-      const now = new Date().toISOString();
-      const errorObj = opts.error instanceof Error ? opts.error : null;
-      const errorMessage = errorObj?.message
-        ?? (typeof opts.error === 'string' ? opts.error : undefined);
-
-      const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}`;
-
-      const existing = this.buffer.get(dedupKey);
-      if (existing) {
-        existing.event_count++;
-        existing.last_occurred_at = now;
-        // If the new occurrence is critical, flush immediately
-        if (CRITICAL_EVENTS.has(eventType)) {
-          this.flushNow();
-        }
-        return;
-      }
-
-      const event: TelemetryEvent = {
-        event_type: eventType,
-        component: opts.component,
-        error_message: errorMessage?.slice(0, 1000),
-        error_stack: errorObj?.stack?.slice(0, 2000),
-        error_code: opts.errorCode,
-        metadata: opts.metadata,
-        sdk_platform: Platform.OS,
-        sdk_version: SDK_VERSION,
-        os_name: Platform.OS,
-        os_version: String(Platform.Version),
-        session_id: this.sessionId,
-        event_count: 1,
-        first_occurred_at: now,
-        last_occurred_at: now,
-      };
-
-      this.buffer.set(dedupKey, event);
+      this.recordEvent(eventType, opts);
 
       if (CRITICAL_EVENTS.has(eventType)) {
-        this.flushNow();
+        // Critical events are written locally before delivery starts. This keeps
+        // them recoverable if the process is killed while the POST is in flight.
+        void this.persistAfterRecovery().then(() => this.flushNow());
       } else {
         this.scheduleFlush();
-      }
-
-      // Persist immediately once prior-session recovery has completed. If startup
-      // recovery is still in flight, write the merged buffer back afterwards.
-      if (this.loadedPersisted) {
-        this.persistBuffer();
-      } else {
-        void this.loadPersistedBuffer().then(() => {
-          if (!this.disposed && this.buffer.size > 0) {
-            this.persistBuffer();
-          }
-        });
+        void this.persistAfterRecovery();
       }
     } catch {
       // Never throw from telemetry
     }
   }
 
+  /**
+   * Record an event and wait until it is durably stored before returning.
+   *
+   * Use this for user intent that must survive an immediate force-close. Network
+   * delivery starts after the local write, but callers do not wait on the network.
+   */
+  async trackDurably(
+    eventType: string,
+    opts: TelemetryTrackOptions = {},
+  ): Promise<boolean> {
+    if (this.disposed) return false;
+
+    try {
+      await this.loadPersistedBuffer();
+      if (this.disposed) return false;
+      this.recordEvent(eventType, opts);
+      const persisted = await this.persistBufferAsync();
+      this.flushNow();
+      return persisted;
+    } catch {
+      // Never throw from telemetry or block the host capture flow.
+      return false;
+    }
+  }
+
   /** Flush all buffered events immediately. Returns a promise but never rejects. */
   async flush(): Promise<void> {
     // Merge any persisted events from a previous session before flushing
@@ -171,14 +174,16 @@ export class TelemetryReporter {
     if (this.buffer.size === 0 || this.flushing) return;
 
     this.flushing = true;
-    const bufferedEntries = Array.from(this.buffer.entries());
+    const bufferedEntries = Array.from(this.buffer.entries()).slice(0, MAX_EVENTS_PER_REQUEST);
     const events = bufferedEntries.map(([, event]) => event);
-    this.buffer.clear();
+    for (const [key] of bufferedEntries) this.buffer.delete(key);
+    this.inFlightBuffer = new Map(bufferedEntries);
     this.clearFlushTimer();
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 10000);
 
     let loggedDeliveryFailure = false;
+    let delivered = false;
     try {
       const response = await fetch(`${this.baseUrl}/telemetry`, {
         method: 'POST',
@@ -202,8 +207,17 @@ export class TelemetryReporter {
         throw new Error(`Telemetry request failed with status ${response.status}`);
       }
 
-      // Success — clear persisted buffer since events are now server-side
-      this.persistBuffer(); // buffer is empty at this point, so this clears the key
+      const acknowledgedKeys = bufferedEntries.map(([key]) => key);
+      const acknowledgedKeySet = new Set(acknowledgedKeys);
+      const removed = await this.removeJournalEntries(acknowledgedKeys);
+      if (removed) {
+        for (const key of acknowledgedKeys) claimedEventKeys.delete(key);
+      }
+      this.inFlightBuffer.clear();
+      for (const [dedupKey, journalKey] of this.dedupIndex) {
+        if (acknowledgedKeySet.has(journalKey)) this.dedupIndex.delete(dedupKey);
+      }
+      delivered = true;
     } catch (error) {
       if (!loggedDeliveryFailure) {
         const kind = error instanceof Error ? error.name : typeof error;
@@ -224,6 +238,7 @@ export class TelemetryReporter {
           this.buffer.set(dedupKey, event);
         }
       }
+      this.inFlightBuffer.clear();
     } finally {
       clearTimeout(timeout);
       this.flushing = false;
@@ -231,13 +246,19 @@ export class TelemetryReporter {
         this.scheduleFlush();
       }
     }
+
+    // Drain oversized recovered journals in API-sized chunks. A failed chunk is
+    // rebuffered and left for the normal retry timer instead of spinning.
+    if (delivered && this.buffer.size > 0 && !this.disposed) {
+      await this.flush();
+    }
   }
 
   /** Dispose — flush remaining events and stop timers. */
   dispose(): void {
     this.disposed = true;
     this.clearFlushTimer();
-    this.flush();
+    void this.flush().finally(() => this.releaseClaims());
   }
 
   private scheduleFlush(): void {
@@ -260,32 +281,110 @@ export class TelemetryReporter {
     }
   }
 
-  /**
-   * Persist the current buffer to AsyncStorage so events survive abrupt app exits.
-   * Fire-and-forget — never throws or blocks.
-   *
-   * IMPORTANT: skips persist if loadPersistedBuffer() hasn't completed yet,
-   * to avoid overwriting orphaned events from a previous session before recovery.
-   */
-  private persistBuffer(): void {
-    if (!this.loadedPersisted) return; // Don't overwrite orphaned prior-session data before it's loaded
+  private recordEvent(eventType: string, opts: TelemetryTrackOptions): void {
+    const now = new Date().toISOString();
+    const errorObj = opts.error instanceof Error ? opts.error : null;
+    const errorMessage = errorObj?.message
+      ?? (typeof opts.error === 'string' ? opts.error : undefined);
+    const occurrenceId = opts.metadata?.capture_attempt_id;
+    const dedupKey = `${eventType}|${errorMessage ?? ''}|${opts.component ?? ''}|${occurrenceId ?? ''}`;
+
+    const existingJournalKey = this.dedupIndex.get(dedupKey);
+    const existing = existingJournalKey
+      ? this.buffer.get(existingJournalKey)
+      : undefined;
+    if (existing) {
+      existing.event_count++;
+      existing.last_occurred_at = now;
+      if (opts.metadata) existing.metadata = { ...existing.metadata, ...opts.metadata };
+      return;
+    }
+
+    const journalKey = this.createJournalKey();
+    this.dedupIndex.set(dedupKey, journalKey);
+    claimedEventKeys.add(journalKey);
+    const eventMetadata = {
+      ...opts.metadata,
+      telemetry_event_id: journalKey.slice(this.storagePrefix.length),
+    };
+    this.buffer.set(journalKey, {
+      event_type: eventType,
+      component: opts.component,
+      error_message: errorMessage?.slice(0, 1000),
+      error_stack: errorObj?.stack?.slice(0, 2000),
+      error_code: opts.errorCode,
+      metadata: eventMetadata,
+      sdk_platform: Platform.OS,
+      sdk_version: SDK_VERSION,
+      os_name: Platform.OS,
+      os_version: String(Platform.Version),
+      session_id: this.sessionId,
+      event_count: 1,
+      first_occurred_at: now,
+      last_occurred_at: now,
+    });
+  }
+
+  private async persistAfterRecovery(): Promise<void> {
+    await this.loadPersistedBuffer();
+    await this.persistBufferAsync();
+  }
+
+  private createJournalKey(): string {
+    this.eventSequence++;
+    return `${this.storagePrefix}${this.sessionId}:${this.eventSequence.toString(36)}`;
+  }
+
+  private async persistBufferAsync(): Promise<boolean> {
+    if (!this.loadedPersisted) return Promise.resolve(false);
+
     try {
-      const entries: Record<string, TelemetryEvent> = {};
-      for (const [key, event] of this.buffer) {
-        entries[key] = event;
-      }
-      getStorage().then(s => {
-        if (Object.keys(entries).length > 0) {
-          s.setItem(TELEMETRY_PERSIST_KEY, JSON.stringify(entries));
-        } else {
-          s.removeItem(TELEMETRY_PERSIST_KEY);
-        }
-      }).catch(() => { /* never throw from telemetry */ });
+      const entries = [
+        ...this.inFlightBuffer.entries(),
+        ...this.buffer.entries(),
+      ];
+
+      const operation = this.persistenceChain
+        .catch(() => { /* keep the write queue alive */ })
+        .then(async () => {
+          const storage = await getStorage();
+          if (entries.length > 0) {
+            await storage.multiSet(
+              entries.map(([key, event]): [string, string] => [key, JSON.stringify(event)]),
+            );
+          }
+        });
+      this.persistenceChain = operation.catch(() => { /* keep queue alive */ });
+      await operation;
+      return true;
     } catch {
       // Never throw from telemetry
+      return false;
+    }
+  }
+
+  private async removeJournalEntries(keys: string[]): Promise<boolean> {
+    if (keys.length === 0) return true;
+    try {
+      const operation = this.persistenceChain
+        .catch(() => { /* keep the write queue alive */ })
+        .then(async () => {
+          const storage = await getStorage();
+          await storage.multiRemove(keys);
+        });
+      this.persistenceChain = operation.catch(() => { /* keep queue alive */ });
+      await operation;
+      return true;
+    } catch {
+      return false;
     }
   }
 
+  private releaseClaims(): void {
+    for (const key of this.buffer.keys()) claimedEventKeys.delete(key);
+    for (const key of this.inFlightBuffer.keys()) claimedEventKeys.delete(key);
+  }
+
   /**
    * Load persisted events from a previous session and merge into current buffer.
    * Runs once per instance. If orphaned events are found, emits an
@@ -300,64 +399,84 @@ export class TelemetryReporter {
     }
 
     this.loadPersistedPromise = (async () => {
+      const claimedDuringRecovery: string[] = [];
       try {
         const storage = await getStorage();
-        const raw = await storage.getItem(TELEMETRY_PERSIST_KEY);
-        if (!raw) return;
-
-        const entries = JSON.parse(raw) as Record<string, TelemetryEvent>;
         let orphanedCount = 0;
         const orphanedTypes: string[] = [];
 
-        for (const [key, event] of Object.entries(entries)) {
-          if (event.session_id === this.sessionId) continue; // Same session, skip
-          orphanedCount++;
-          orphanedTypes.push(event.event_type);
-          // Merge orphaned events into the current buffer
-          const existing = this.buffer.get(key);
-          if (existing) {
-            existing.event_count += event.event_count;
-            if (event.first_occurred_at < existing.first_occurred_at) {
-              existing.first_occurred_at = event.first_occurred_at;
-            }
-            if (event.last_occurred_at > existing.last_occurred_at) {
-              existing.last_occurred_at = event.last_occurred_at;
-            }
-          } else {
+        const allKeys = await storage.getAllKeys();
+        const recoverableKeys = allKeys.filter((key) => {
+          if (!key.startsWith(this.storagePrefix)) return false;
+          if (claimedEventKeys.has(key)) return false;
+          claimedEventKeys.add(key);
+          claimedDuringRecovery.push(key);
+          return true;
+        });
+        const recoveredPairs = recoverableKeys.length > 0
+          ? await storage.multiGet(recoverableKeys)
+          : [];
+
+        for (const [key, raw] of recoveredPairs) {
+          if (!raw) {
+            claimedEventKeys.delete(key);
+            continue;
+          }
+          try {
+            const event = JSON.parse(raw) as TelemetryEvent;
+            orphanedCount++;
+            orphanedTypes.push(event.event_type);
             this.buffer.set(key, event);
+          } catch {
+            claimedEventKeys.delete(key);
+          }
+        }
+
+        // Migrate the pre-2.5.6 shared snapshot without a remove/rewrite gap:
+        // write each event journal entry first, then delete the legacy key.
+        if (!legacyBufferClaimed && allKeys.includes(LEGACY_TELEMETRY_PERSIST_KEY)) {
+          legacyBufferClaimed = true;
+          let migrated = false;
+          try {
+            const legacyRaw = await storage.getItem(LEGACY_TELEMETRY_PERSIST_KEY);
+            if (legacyRaw) {
+              const legacyEntries = JSON.parse(legacyRaw) as Record<string, TelemetryEvent>;
+              const migrationPairs: Array<[string, string]> = [];
+              for (const event of Object.values(legacyEntries)) {
+                const key = this.createJournalKey();
+                claimedEventKeys.add(key);
+                this.buffer.set(key, event);
+                orphanedCount++;
+                orphanedTypes.push(event.event_type);
+                migrationPairs.push([key, JSON.stringify(event)]);
+              }
+              if (migrationPairs.length > 0) await storage.multiSet(migrationPairs);
+            }
+            await storage.removeItem(LEGACY_TELEMETRY_PERSIST_KEY);
+            migrated = true;
+          } finally {
+            if (!migrated) legacyBufferClaimed = false;
           }
         }
 
         // Emit sdk_session_recovered if we recovered orphaned events from a previous session
         if (orphanedCount > 0) {
-          const now = new Date().toISOString();
           const uniqueTypes = [...new Set(orphanedTypes)];
-          const crashEvent: TelemetryEvent = {
-            event_type: 'sdk_session_recovered',
+          this.recordEvent('sdk_session_recovered', {
             component: 'TelemetryReporter',
-            error_message: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
-            sdk_platform: Platform.OS,
-            sdk_version: SDK_VERSION,
-            os_name: Platform.OS,
-            os_version: String(Platform.Version),
-            session_id: this.sessionId,
-            event_count: 1,
-            first_occurred_at: now,
-            last_occurred_at: now,
-          };
-          this.buffer.set(`sdk_session_recovered|recovered|${this.sessionId}`, crashEvent);
+            error: `Recovered ${orphanedCount} unflushed event(s) from a previous session that ended without a clean telemetry flush: ${uniqueTypes.join(', ')}`,
+          });
         }
-
-        // Clear persisted data now that it's loaded into memory. The merged
-        // buffer will be re-persisted below until a flush succeeds.
-        await storage.removeItem(TELEMETRY_PERSIST_KEY);
       } catch {
         // Never throw from telemetry
+        for (const key of claimedDuringRecovery) {
+          if (!this.buffer.has(key)) claimedEventKeys.delete(key);
+        }
       } finally {
         this.loadedPersisted = true;
         this.loadPersistedPromise = null;
         if (this.buffer.size > 0 && !this.disposed) {
-          this.persistBuffer();
+          await this.persistBufferAsync();
           this.scheduleFlush();
         }
       }

package/src/types/index.ts

@@ -98,6 +98,8 @@ export interface ScannerTelemetryContext {
   routeName?: string;
   /** Whether the host app keeps this screen portrait-locked. */
   isPortraitLocked?: boolean;
+  /** Host-owned identifier used to correlate scanner telemetry with its workflow. */
+  hostReferenceId?: string;
 }
 
 /**

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '2.5.4';
+export const SDK_VERSION = '2.5.6';