@usergist/feedback-react-native 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/internal/engine.js

@@ -1,18 +1,20 @@
-// The engine owns all singleton state and orchestrates the modules.
-// `UserGist.ts` wraps these functions in a thin, try/catch-guarded public API.
-import { APP_OPEN_EVENT_NAME, APP_VERSION_CHANGED_EVENT_NAME } from '@usergist/sdk-core/mobile';
+import { rememberRevocation, drainRevocations } from './session-revocations.js';
+import { identityChanged, recoverIdentity } from './identity-lifecycle.js';
+import { PresentationGate } from '@usergist/sdk-core/mobile';
+import { APP_OPEN_EVENT_NAME, APP_VERSION_CHANGED_EVENT_NAME, } from '@usergist/sdk-core/mobile';
 import { STORAGE_KEYS, createStorageScope, } from './storage.js';
-import { createIdentityManager, generateEventId } from './identity.js';
+import { createIdentityManager, generateEventId, } from './identity.js';
 import { createConsentManager } from './consent.js';
 import { createEventQueue } from './queue.js';
-import { createTransport, PermanentHttpError } from './transport.js';
+import { createTransport, PermanentHttpError, } from './transport.js';
 import { createRulesCache } from './rules-cache.js';
 import { createSurveyRulesCache, } from './survey-rules-cache.js';
-import { createFrequencyCapManager } from './frequency-cap.js';
+import { createFrequencyCapManager, } from './frequency-cap.js';
 import { createUserStateStore } from './user-state.js';
 import { createTriggerMatcher } from './trigger-matcher.js';
 import { createSurveyMatcher } from './survey-matcher.js';
-import { createInAppRulesCache } from './inapp-rules-cache.js';
+import { createSurveyInvitations } from './survey-invitations.js';
+import { createInAppRulesCache, } from './inapp-rules-cache.js';
 import { createInAppMatcher } from './inapp-matcher.js';
 import { createLifecycleManager } from './lifecycle.js';
 import { createContextProvider } from './context.js';
@@ -37,7 +39,9 @@ const DEFAULTS = {
     debug: false,
 };
 export function resolveConfig(config) {
-    if (!config || typeof config.writeKey !== 'string' || config.writeKey.length === 0) {
+    if (!config ||
+        typeof config.writeKey !== 'string' ||
+        config.writeKey.length === 0) {
         throw new Error('UserGist.init requires a writeKey');
     }
     const environment = config.environment ?? DEFAULTS.environment;
@@ -57,22 +61,28 @@ export function resolveConfig(config) {
         appVersion: config.appVersion?.trim() || null,
     };
 }
-export function createEngine(config) {
+export function createEngine(config, prepareSurveys) {
     const resolved = resolveConfig(config);
     setDebugEnabled(resolved.debug);
     const storage = createStorageScope(resolved.writeKey);
     const identity = createIdentityManager(storage);
+    const surveyInvitations = createSurveyInvitations(storage, () => identity.get());
     const consent = createConsentManager(storage);
     const queue = createEventQueue(storage, resolved.maxQueueSize);
     const mutations = createMutationQueue(storage);
     const localInstructionDedupe = createLocalInstructionDedupe(storage);
-    const transport = createTransport({ writeKey: resolved.writeKey, apiUrl: resolved.apiUrl });
+    const transport = createTransport({
+        writeKey: resolved.writeKey,
+        apiUrl: resolved.apiUrl,
+        prepareSurveys,
+    });
     const rules = createRulesCache(storage, transport, resolved.triggerSyncIntervalMs);
     const surveyRules = createSurveyRulesCache(storage, transport, resolved.triggerSyncIntervalMs);
     const inAppRules = createInAppRulesCache(storage, transport, resolved.triggerSyncIntervalMs);
     const caps = createFrequencyCapManager(storage);
     const userState = createUserStateStore(storage);
-    const events = createEventBus();
+    const presentation = new PresentationGate(config.presentationPaused ?? false);
+    const events = createEventBus(presentation);
     const matcher = createTriggerMatcher({
         rulesCache: rules,
         frequencyCaps: caps,
@@ -117,6 +127,7 @@ export function createEngine(config) {
         },
         onSyncTick: () => {
             const e = eng();
+            void drainRevocations(e).catch(error => reportError('session cleanup deferred', error));
             void refreshTargetingRules(e);
             void flushMutations(e);
             void pollSurveyOffers(e);
@@ -139,10 +150,12 @@ export function createEngine(config) {
         userState,
         matcher,
         surveyMatcher,
+        surveyInvitations,
         inAppMatcher,
         lifecycle,
         context,
         events,
+        presentation,
         hydrated: false,
         hydratingPromise: null,
         flushTimer: null,
@@ -151,6 +164,7 @@ export function createEngine(config) {
         subjectToken: null,
         sessionPromise: null,
         instructionPollPromise: null,
+        instructionDispatchPromise: null,
         resetGeneration: 0,
         resetting: false,
         localInstructionDedupe,
@@ -161,6 +175,10 @@ export function createEngine(config) {
         lastPushRegistrationAt: 0,
     };
     ref.value = engine;
+    transport.setAuthenticationHandler(() => { void recoverIdentity(engine).then(ok => { if (ok) {
+        void flushNow(engine);
+        void flushMutations(engine);
+    } }); });
     queue.onOverflow((dropped) => {
         debugLog('queue overflow', { dropped, queueSize: queue.size() });
     });
@@ -168,8 +186,10 @@ export function createEngine(config) {
         matcher.recordShown(payload.promptId, payload.shownAt);
     });
     consent.subscribe((s) => {
-        if (!s.analytics)
+        if (!s.analytics) {
             engine.queue.removePurpose('analytics');
+            void engine.mutations.removePurpose('analytics');
+        }
         if (!s.feedback) {
             engine.queue.removePurpose('feedback');
             void engine.mutations.removePurpose('feedback');
@@ -177,6 +197,7 @@ export function createEngine(config) {
         }
         if (!s.survey) {
             void engine.mutations.removePurpose('survey');
+            void engine.surveyInvitations.clear().catch((error) => reportError('clear survey invitations failed', error));
             engine.surveyMatcher.resetPending();
         }
         if (s.feedback || s.analytics)
@@ -202,8 +223,10 @@ export async function ensureHydrated(engine) {
                 engine.surveyRules.hydrate(),
                 engine.inAppRules.hydrate(),
                 engine.localInstructionDedupe.hydrate(),
-                engine.storage.getJson(STORAGE_KEYS.pushToken).then(token => { if (typeof token === 'string')
-                    engine.lastPushToken = token; }),
+                engine.storage.getJson(STORAGE_KEYS.pushToken).then((token) => {
+                    if (typeof token === 'string')
+                        engine.lastPushToken = token;
+                }),
             ]);
             await ensureSubjectSession(engine);
             engine.hydrated = true;
@@ -222,10 +245,14 @@ export async function ensureHydrated(engine) {
     return engine.hydratingPromise;
 }
 export async function ensureSubjectSession(engine) {
+    if (engine.resetting)
+        return;
+    void drainRevocations(engine).catch(error => reportError('session cleanup deferred', error));
     if (engine.subjectToken)
         return;
     if (engine.sessionPromise)
         return engine.sessionPromise;
+    const generation = engine.resetGeneration;
     engine.sessionPromise = (async () => {
         const id = engine.identity.get();
         const persisted = await engine.storage.getJson(STORAGE_KEYS.subjectToken);
@@ -234,13 +261,25 @@ export async function ensureSubjectSession(engine) {
                 anonymousId: id.anonymousId,
                 ...(persisted ? { currentToken: persisted } : {}),
             });
+            if (generation !== engine.resetGeneration)
+                return;
+            identityChanged(engine, id.externalId ? 'identified' : 'anonymous');
+            if (generation !== engine.resetGeneration)
+                return;
             engine.subjectToken = session.subjectToken;
             engine.transport.setSubjectToken(session.subjectToken);
             await engine.storage.setJson(STORAGE_KEYS.subjectToken, session.subjectToken);
         }
         catch (error) {
+            if (generation !== engine.resetGeneration)
+                return;
             const mayRotate = error instanceof PermanentHttpError &&
                 (error.status === 401 || error.status === 403 || error.status === 409);
+            if (id.externalId) {
+                if (await recoverIdentity(engine))
+                    return;
+                throw error;
+            }
             if (!mayRotate)
                 throw error;
             // A lost/expired credential must never be replaced for the same known
@@ -248,8 +287,14 @@ export async function ensureSubjectSession(engine) {
             // new server-bound subject instead.
             if (persisted)
                 await engine.storage.remove(STORAGE_KEYS.subjectToken);
+            if (generation !== engine.resetGeneration)
+                return;
             const rotated = await engine.identity.rotate();
-            const session = await engine.transport.session({ anonymousId: rotated.anonymousId });
+            const session = await engine.transport.session({
+                anonymousId: rotated.anonymousId,
+            });
+            if (generation !== engine.resetGeneration)
+                return;
             engine.subjectToken = session.subjectToken;
             engine.transport.setSubjectToken(session.subjectToken);
             await engine.storage.setJson(STORAGE_KEYS.subjectToken, session.subjectToken);
@@ -337,6 +382,11 @@ function instructionKey(type, refId, eventId) {
 function rememberLocalInstruction(engine, key) {
     engine.localInstructionDedupe.remember(key);
 }
+function needsImmediateDelivery(engine, eventName) {
+    return !!(engine.rules?.needsServer?.(eventName) ||
+        engine.surveyRules?.needsServer?.(eventName) ||
+        engine.inAppRules?.needsServer?.(eventName));
+}
 export function scheduleFlush(engine) {
     if (engine.flushTimer)
         return;
@@ -356,11 +406,17 @@ export async function flushNow(engine) {
     return engine.flushPromise;
 }
 async function performFlush(engine) {
+    void engine.retryPushRegistration?.().catch(error => reportError('push registration deferred', error));
+    let requestedImmediateDelivery = false;
     try {
         await ensureHydrated(engine);
-        while (engine.queue.size() > 0) {
+        while (!engine.resetting && engine.queue.size() > 0) {
             const consent = engine.consent.get();
-            const allowed = engine.queue.snapshot().filter((event) => event.purpose === 'analytics' ? consent.analytics : consent.feedback);
+            const allowed = engine.queue
+                .snapshot()
+                .filter((event) => event.purpose === 'analytics'
+                ? consent.analytics
+                : consent.feedback);
             const firstAllowed = allowed[0];
             if (!firstAllowed)
                 break;
@@ -368,8 +424,15 @@ async function performFlush(engine) {
             // post-identify events. The API deliberately rejects a batch whose
             // event identities differ from its context, so drain one identity at a
             // time while retaining FIFO order within that identity.
-            const batch = allowed.filter((event) => event.anonymousId === firstAllowed.anonymousId &&
-                event.externalId === firstAllowed.externalId).slice(0, engine.config.flushBatchSize);
+            const candidates = allowed
+                .filter((event) => event.anonymousId === firstAllowed.anonymousId &&
+                event.externalId === firstAllowed.externalId)
+                .slice(0, engine.config.flushBatchSize);
+            let deliveryCount = 0;
+            const overflow = candidates.findIndex(event => needsImmediateDelivery(engine, event.name) && ++deliveryCount > 20);
+            // Limit authorization work, not ordinary analytics rows. Keep earlier
+            // watch/property events in order without shrinking every batch to 20.
+            const batch = overflow < 0 ? candidates : candidates.slice(0, overflow);
             if (batch.length === 0)
                 break;
             const ingestEvents = batch.map((e) => ({
@@ -383,7 +446,16 @@ async function performFlush(engine) {
                 sdkVersion: engine.context.sdkVersion(),
                 platform: engine.context.platform(),
             }));
+            const deliveryEventIds = batch
+                .filter((event) => needsImmediateDelivery(engine, event.name))
+                .map((event) => event.eventId);
+            requestedImmediateDelivery ||= deliveryEventIds.length > 0;
+            const deliveryGeneration = engine.resetGeneration;
+            const deliverySubjectToken = engine.subjectToken;
             const payload = {
+                ...(deliveryEventIds.length
+                    ? { delivery: { eventIds: deliveryEventIds } }
+                    : {}),
                 events: ingestEvents,
                 context: engine.context.build({
                     anonymousId: batch[0].anonymousId,
@@ -391,11 +463,18 @@ async function performFlush(engine) {
                 }),
             };
             try {
-                await engine.transport.ingest(payload);
+                const result = await engine.transport.ingest(payload);
+                if (engine.resetting ||
+                    engine.resetGeneration !== deliveryGeneration ||
+                    engine.subjectToken !== deliverySubjectToken)
+                    return;
                 engine.queue.remove(batch.map((event) => event.eventId));
+                if (result.instructions?.length) {
+                    await consumeInstructions(engine, result.instructions, false, deliveryGeneration, deliverySubjectToken);
+                }
             }
             catch (e) {
-                if (e instanceof PermanentHttpError) {
+                if (e instanceof PermanentHttpError && e.status !== 401) {
                     if (batch.length === 1) {
                         engine.queue.remove([batch[0].eventId]);
                         reportError('ingest event quarantined after permanent rejection', {
@@ -418,7 +497,7 @@ async function performFlush(engine) {
                         engine.queue.remove([first.eventId]);
                     }
                     catch (singleError) {
-                        if (singleError instanceof PermanentHttpError) {
+                        if (singleError instanceof PermanentHttpError && singleError.status !== 401) {
                             engine.queue.remove([first.eventId]);
                             reportError('ingest event quarantined after permanent rejection', {
                                 eventId: first.eventId,
@@ -436,14 +515,14 @@ async function performFlush(engine) {
             }
         }
         // After draining the queue, opportunistically pull pending survey offers.
-        await flushMutations(engine);
+        void flushMutations(engine);
         // Triggered surveys appear in the offer ledger after the server processes
         // the event; the small delay gives NATS + the trigger engine time to
         // run before we ask.
         setTimeout(() => {
             void pollSurveyOffers(engine);
             void pollInstructions(engine);
-        }, 1500);
+        }, requestedImmediateDelivery ? 100 : 1500);
     }
     catch (e) {
         reportError('flushNow failed', e);
@@ -469,14 +548,48 @@ async function performMutationFlush(engine) {
             break;
         const deliveryGeneration = engine.resetGeneration;
         const consent = engine.consent.get();
+        if (mutation.purpose === 'analytics' && !consent.analytics)
+            break;
         if (mutation.purpose === 'feedback' && !consent.feedback)
             break;
         if (mutation.purpose === 'survey' && !consent.survey)
             break;
         try {
-            if (mutation.kind === 'feedback-response') {
+            if (consent.analytics && (mutation.kind === 'identify' || mutation.kind === 'user-properties')) {
+                const current = engine.identity.get();
+                await engine.transport.consent({ anonymousId: current.anonymousId, externalId: current.externalId,
+                    purposes: { analytics: consent.analytics, feedback: consent.feedback, push: consent.push, survey: consent.survey },
+                    version: consent.version, effectiveAt: consent.updatedAt ?? new Date().toISOString(),
+                }, current.externalId && mutation.kind === 'identify' ? String(mutation.payload.subjectToken) : undefined);
+                if (engine.resetting || engine.resetGeneration !== deliveryGeneration)
+                    break;
+                if (mutation.kind === 'user-properties' && !engine.consent.allowsAnalytics())
+                    continue;
+            }
+            if (mutation.kind === 'instruction-ack') {
+                await engine.transport.acknowledgeInstructions(mutation.payload.ids);
+            }
+            else if (mutation.kind === 'user-properties') {
+                const result = await engine.transport.userProperties(mutation.payload);
+                if (engine.resetting || engine.resetGeneration !== deliveryGeneration)
+                    break;
+                const set = mutation.payload.set;
+                const unset = mutation.payload.unset;
+                engine.userState.mergeProperties(Object.fromEntries(Object.entries(set ?? {}).filter(([key]) => !result.filteredKeys.includes(key))), unset);
+                if (result.filteredKeys.length)
+                    reportError('User properties filtered by app privacy settings', result.filteredKeys);
+            }
+            else if (mutation.kind === 'feedback-response') {
                 await engine.transport.submitResponse(mutation.payload);
             }
+            else if (mutation.kind === 'survey-start') {
+                await engine.transport.surveyCreateAttempt(String(mutation.payload.surveyId), mutation.payload
+                    .body);
+            }
+            else if (mutation.kind === 'survey-progress') {
+                await engine.transport.surveyUpdateProgress(String(mutation.payload.attemptId), mutation.payload
+                    .body);
+            }
             else if (mutation.kind === 'survey-complete') {
                 const attemptId = mutation.payload.attemptId;
                 if (typeof attemptId !== 'string')
@@ -499,30 +612,49 @@ async function performMutationFlush(engine) {
                     typeof externalId !== 'string')
                     throw new Error('invalid-identify-mutation');
                 try {
-                    await engine.transport.identify({
+                    const accepted = await engine.transport.identify({
                         anonymousId,
                         externalId,
-                        ...(properties && typeof properties === 'object'
-                            ? { properties: properties }
+                        ...(engine.subjectToken ? { previousSubjectToken: engine.subjectToken } : {}),
+                        ...(engine.consent.allowsAnalytics() && properties && typeof properties === 'object'
+                            ? {
+                                properties: properties,
+                            }
                             : {}),
                     }, subjectToken);
                     if (engine.resetting || engine.resetGeneration !== deliveryGeneration)
                         break;
-                    await engine.storage.setJsonStrict(STORAGE_KEYS.subjectToken, subjectToken);
+                    const sessionToken = accepted.subjectToken ?? subjectToken;
+                    await engine.storage.setJsonStrict(STORAGE_KEYS.subjectToken, sessionToken);
                     if (engine.resetting || engine.resetGeneration !== deliveryGeneration)
                         break;
-                    engine.subjectToken = subjectToken;
-                    engine.transport.setSubjectToken(subjectToken);
+                    engine.subjectToken = sessionToken;
+                    engine.transport.setSubjectToken(sessionToken);
+                    if (engine.identity.get().externalId !== externalId)
+                        engine.presentation.invalidate();
                     await engine.identity.setExternalId(externalId);
+                    if (engine.resetting || engine.resetGeneration !== deliveryGeneration)
+                        break;
+                    identityChanged(engine, 'identified');
+                    void engine.retryPushRegistration?.().catch(error => reportError('push registration deferred', error));
                     if (properties && typeof properties === 'object') {
-                        const clean = properties;
-                        engine.userState.mergeProperties(clean);
+                        const supplied = properties;
+                        const clean = accepted.filteredKeys
+                            ? Object.fromEntries(Object.entries(supplied).filter(([key]) => !accepted.filteredKeys.includes(key)))
+                            : asEventProps(supplied) ?? {};
+                        if (accepted.properties)
+                            engine.userState.replaceProperties(accepted.properties);
+                        else
+                            engine.userState.mergeProperties(clean);
                         if (engine.consent.allowsAnalytics()) {
-                            enqueueAndEvaluate(engine, '$identify', clean);
+                            enqueueAndEvaluate(engine, '$identify', asEventProps(clean));
                         }
                     }
-                    else if (engine.consent.allowsAnalytics()) {
-                        enqueueAndEvaluate(engine, '$identify', undefined);
+                    else {
+                        if (accepted.properties)
+                            engine.userState.replaceProperties(accepted.properties);
+                        if (engine.consent.allowsAnalytics())
+                            enqueueAndEvaluate(engine, '$identify', undefined);
                     }
                 }
                 catch (error) {
@@ -536,7 +668,9 @@ async function performMutationFlush(engine) {
         catch (error) {
             if (engine.resetting || engine.resetGeneration !== deliveryGeneration)
                 break;
-            if (error instanceof PermanentHttpError) {
+            if (error instanceof PermanentHttpError && error.status === 401 && mutation.kind === 'identify')
+                identityChanged(engine, 'authentication-required');
+            if (error instanceof PermanentHttpError && error.status !== 401) {
                 await engine.mutations.remove(mutation.id);
                 permanentlyRejectedIds.add(mutation.id);
                 reportError('mutation quarantined after permanent rejection', {
@@ -570,6 +704,7 @@ export async function pollSurveyOffers(engine) {
         lastPollAt = now;
         if (!engine.consent.get().survey)
             return;
+        const presentationIsValid = engine.presentation.validator('survey');
         const id = engine.identity.get();
         const res = await engine.transport.surveysAvailable({
             anonymousId: id.anonymousId,
@@ -578,7 +713,8 @@ export async function pollSurveyOffers(engine) {
         const surveys = res.surveys ?? [];
         if (surveys.length === 0)
             return;
-        const seen = (await engine.storage.getJson(SEEN_OFFERS_KEY)) ?? [];
+        const seen = (await engine.storage.getJson(SEEN_OFFERS_KEY)) ??
+            [];
         const seenSet = new Set(seen);
         const localIds = surveys
             .map((survey) => survey.id)
@@ -587,6 +723,8 @@ export async function pollSurveyOffers(engine) {
             !engine.locallyHandledSurveyIds.has(survey.id));
         if (fresh.length === 0 && localIds.length === 0)
             return;
+        if (!presentationIsValid() || !engine.consent.allowsSurvey())
+            return;
         for (const s of fresh) {
             engine.events.emit('surveyInvite', {
                 surveyId: s.id,
@@ -620,27 +758,82 @@ async function performInstructionPoll(engine) {
     try {
         await ensureHydrated(engine);
         const after = (await engine.storage.getJson(STORAGE_KEYS.instructionCursor)) ?? 0;
-        const seen = (await engine.storage.getJson(STORAGE_KEYS.seenInstructions)) ?? [];
-        const seenSet = new Set(seen);
-        const result = await engine.transport.instructions(after, { anonymousId: engine.identity.get().anonymousId, platform: engine.context.platform(), sdkVersion: engine.context.sdkVersion() });
-        if (result.instructions.length === 0)
-            return;
-        const handledIds = [];
-        for (const instruction of result.instructions) {
-            handledIds.push(instruction.id);
-            if (seenSet.has(instruction.id))
-                continue;
-            dispatchInstruction(engine, instruction.type, instruction.payload);
-            seenSet.add(instruction.id);
-            await engine.storage.setJsonStrict(STORAGE_KEYS.seenInstructions, [...seenSet].slice(-200));
-        }
-        await engine.storage.setJsonStrict(STORAGE_KEYS.instructionCursor, Math.max(after, ...handledIds));
-        await engine.transport.acknowledgeInstructions(handledIds);
+        const generation = engine.resetGeneration;
+        const subjectToken = engine.subjectToken;
+        const result = await engine.transport.instructions(after, {
+            anonymousId: engine.identity.get().anonymousId,
+            platform: engine.context.platform(),
+            sdkVersion: engine.context.sdkVersion(),
+        });
+        await consumeInstructions(engine, result.instructions, true, generation, subjectToken);
     }
     catch (error) {
         reportError('instruction poll failed', error);
     }
 }
+/** Serializes HTTP responses and polling. Event-scoped responses must never
+ * advance the global inbox cursor past older, still-undelivered instructions. */
+export function consumeInstructions(engine, instructions, advanceCursor, generation = engine.resetGeneration, subjectToken = engine.subjectToken) {
+    const isCurrent = () => !engine.resetting &&
+        engine.resetGeneration === generation &&
+        engine.subjectToken === subjectToken;
+    const work = (engine.instructionDispatchPromise ?? Promise.resolve())
+        .catch(() => undefined)
+        .then(async () => {
+        if (!instructions.length || !isCurrent())
+            return;
+        const seen = new Set((await engine.storage.getJson(STORAGE_KEYS.seenInstructions)) ?? []);
+        if (!isCurrent())
+            return;
+        const handled = [];
+        for (const instruction of instructions) {
+            if (!isCurrent())
+                return;
+            handled.push(instruction.id);
+            if (seen.has(instruction.id))
+                continue;
+            const payload = instruction.payload;
+            if (instruction.type === 'survey.offer' && engine.consent.allowsSurvey() &&
+                typeof payload.surveyId === 'string' && typeof payload.name === 'string' &&
+                typeof payload.presentationId === 'string' && payload.survey && typeof payload.survey === 'object') {
+                // Persist before invoking the host callback or acknowledging delivery.
+                // A storage failure leaves the instruction available for retry.
+                await engine.surveyInvitations.remember({
+                    surveyId: payload.surveyId,
+                    presentationId: payload.presentationId,
+                    source: typeof payload.source === 'string' ? payload.source : 'triggered',
+                    survey: { ...payload.survey, presentationId: payload.presentationId },
+                    attempt: payload.attempt,
+                    expiresAt: Math.min(Date.parse(instruction.expiresAt), Date.now() + 24 * 60 * 60 * 1000),
+                });
+                if (!isCurrent())
+                    return;
+            }
+            dispatchInstruction(engine, instruction.type, instruction.payload);
+            seen.add(instruction.id);
+            await engine.storage.setJsonStrict(STORAGE_KEYS.seenInstructions, [...seen].slice(-200));
+        }
+        if (!isCurrent())
+            return;
+        // Persist receipts before advancing the cursor. Network retries must not
+        // hold the display/ingest lane or lose cap accounting after a restart.
+        await engine.mutations.enqueue('instruction-ack', 'essential', {
+            ids: handled,
+        });
+        if (!isCurrent())
+            return;
+        if (advanceCursor) {
+            const after = (await engine.storage.getJson(STORAGE_KEYS.instructionCursor)) ?? 0;
+            if (!isCurrent())
+                return;
+            await engine.storage.setJsonStrict(STORAGE_KEYS.instructionCursor, Math.max(after, ...handled));
+        }
+        if (isCurrent())
+            void flushMutations(engine);
+    });
+    engine.instructionDispatchPromise = work;
+    return work;
+}
 function dispatchInstruction(engine, type, payload) {
     if (type === 'prompt.show') {
         if (!engine.consent.allowsFeedback())
@@ -675,7 +868,8 @@ function dispatchInstruction(engine, type, payload) {
     if (type === 'survey.offer') {
         if (!engine.consent.allowsSurvey())
             return;
-        if (typeof payload.surveyId !== 'string' || typeof payload.name !== 'string')
+        if (typeof payload.surveyId !== 'string' ||
+            typeof payload.name !== 'string')
             return;
         const triggerEventId = payload.triggerEventId;
         if (typeof triggerEventId === 'string' &&
@@ -687,6 +881,13 @@ function dispatchInstruction(engine, type, payload) {
             return;
         }
         engine.events.emit('surveyInvite', {
+            attempt: payload.attempt,
+            survey: payload.survey && typeof payload.survey === 'object'
+                ? {
+                    ...payload.survey,
+                    presentationId: payload.presentationId,
+                }
+                : undefined,
             surveyId: payload.surveyId,
             name: payload.name,
             source: typeof payload.source === 'string' ? payload.source : 'triggered',
@@ -760,7 +961,8 @@ export function enqueueAndEvaluate(engine, eventName, properties, purpose = 'ana
         engine.queue.enqueue(base);
         engine.userState.recordEvent(eventName, now);
         evaluateLocally(engine, eventName, base.eventId);
-        if (engine.queue.size() >= engine.config.flushBatchSize)
+        if (needsImmediateDelivery(engine, eventName) ||
+            engine.queue.size() >= engine.config.flushBatchSize)
             void flushNow(engine);
         else
             scheduleFlush(engine);
@@ -776,7 +978,8 @@ export function enqueueAndEvaluate(engine, eventName, properties, purpose = 'ana
         engine.queue.enqueue(withId);
         engine.userState.recordEvent(eventName, now);
         evaluateLocally(engine, eventName, withId.eventId);
-        if (engine.queue.size() >= engine.config.flushBatchSize)
+        if (needsImmediateDelivery(engine, eventName) ||
+            engine.queue.size() >= engine.config.flushBatchSize)
             void flushNow(engine);
         else
             scheduleFlush(engine);
@@ -806,14 +1009,21 @@ function evaluateLocally(engine, eventName, eventId) {
 }
 export async function submitResponse(engine, payload, triggerEventName, trackInternal) {
     const id = engine.identity.get();
+    const context = engine.context.build(id);
     const submitPayload = {
         idempotencyKey: generateEventId(),
         promptId: payload.promptId,
         anonymousId: id.anonymousId,
         externalId: id.externalId,
-        answers: payload.answers.map((a) => ({ questionId: a.questionId, value: a.value })),
+        answers: payload.answers.map((a) => ({
+            questionId: a.questionId,
+            value: a.value,
+        })),
         dismissed: payload.dismissed,
         latencyMs: payload.latencyMs,
+        platform: context.platform,
+        sdkVersion: context.sdkVersion,
+        appVersion: context.appVersion,
     };
     engine.events.emit('response', payload);
     trackInternal('$feedback_response', {
@@ -837,28 +1047,15 @@ export async function clearAllState(engine) {
     pendingAppOpenConsent.delete(engine);
     engine.events.emit('resetSurfaces', undefined);
     engine.transport.cancelAll();
+    engine.transport.setSubjectToken(null);
     await Promise.allSettled([
         engine.mutationFlushPromise ?? Promise.resolve(),
         engine.flushPromise ?? Promise.resolve(),
         engine.sessionPromise ?? Promise.resolve(),
         engine.instructionPollPromise ?? Promise.resolve(),
+        engine.instructionDispatchPromise ?? Promise.resolve(),
     ]);
-    // Reset is a local privacy operation and must not wait on network retries.
-    // Revoke the old credential through an isolated transport so failures cannot
-    // open the live engine's circuit or delay the new anonymous session.
-    const subjectToken = engine.subjectToken;
-    if (subjectToken) {
-        const revocationTransport = createTransport({
-            writeKey: engine.config.writeKey,
-            apiUrl: engine.config.apiUrl,
-        });
-        revocationTransport.setSubjectToken(subjectToken);
-        void revocationTransport.revokeSession().catch((error) => {
-            debugLog('subject session revoke deferred', {
-                reason: error instanceof Error ? error.message : String(error),
-            });
-        });
-    }
+    await rememberRevocation(engine);
     if (engine.flushTimer) {
         clearTimeout(engine.flushTimer);
         engine.flushTimer = null;
@@ -875,9 +1072,9 @@ export async function clearAllState(engine) {
         engine.userState.clear(),
         engine.consent.clear(),
         engine.localInstructionDedupe.clear(),
+        engine.surveyInvitations.clear(),
     ]);
     await engine.storage.clearAll([
-        STORAGE_KEYS.identity,
         STORAGE_KEYS.consent,
         STORAGE_KEYS.queue,
         STORAGE_KEYS.rulesCache,
@@ -894,6 +1091,7 @@ export async function clearAllState(engine) {
         STORAGE_KEYS.pushToken,
         SEEN_OFFERS_KEY,
     ]);
+    await engine.storage.setJsonStrict(STORAGE_KEYS.subjectToken, null);
     engine.subjectToken = null;
     engine.transport.setSubjectToken(null);
     engine.locallyHandledSurveyIds.clear();
@@ -904,6 +1102,10 @@ export async function clearAllState(engine) {
     engine.lastPushRegistrationAt = 0;
     lastPollAt = 0;
     await engine.identity.hydrate();
-    await ensureSubjectSession(engine);
+    engine.pendingReset = undefined;
+    identityChanged(engine, 'anonymous');
+    void drainRevocations(engine).catch(error => reportError('session cleanup deferred', error));
+    // Local logout completes independently of network availability.
+    setTimeout(() => { void ensureSubjectSession(engine).catch(error => reportError('anonymous session deferred', error)); }, 0);
 }
 //# sourceMappingURL=engine.js.map