@mentra/engine 0.1.0-dev.0 → 3.1.0-dev.4

package/src/services/AudioCloudUplink.ts

@@ -18,11 +18,32 @@ import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 import {cloudClientService} from "./CloudClientService"
 
 let sub: {remove: () => void} | null = null
+const suppressionSources = new Set<string>()
+
+/**
+ * Keep the glasses LC3 transport alive while dropping mic audio before cloud
+ * STT. Sources are reference-counted by id so overlapping playback cannot
+ * reopen the uplink until every active source has released.
+ *
+ * Suppression is global to the uplink: one source silences STT for every app.
+ * That is why no platform path arms it any more (spoken TTS used to, which made
+ * every assistant reply punch a hole in Live Translation and Captions). The
+ * mechanism stays because it is the right primitive for an explicit,
+ * caller-scoped mute; see OS-1741 for the per-app opt-in that will use it.
+ */
+export function setAudioCloudUplinkSuppressed(sourceId: string, suppressed: boolean): void {
+  if (suppressed) suppressionSources.add(sourceId)
+  else suppressionSources.delete(sourceId)
+}
 
 export function startAudioCloudUplink(): void {
   if (sub) return
   sub = BluetoothSdk.addListener("mic_lc3", (event) => {
-    if (cloudClientService.isConnected() && cloudClientService.hasAudioSubscriptions()) {
+    if (
+      suppressionSources.size === 0 &&
+      cloudClientService.isConnected() &&
+      cloudClientService.hasAudioSubscriptions()
+    ) {
       cloudClientService.sendAudioFrame(new Uint8Array(event.lc3))
     }
   })
@@ -31,4 +52,5 @@ export function startAudioCloudUplink(): void {
 export function stopAudioCloudUplink(): void {
   sub?.remove()
   sub = null
+  suppressionSources.clear()
 }

package/src/services/AudioPlaybackService.ts

@@ -1,6 +1,9 @@
 import {createAudioPlayer, AudioPlayer, AudioStatus, setAudioModeAsync} from "expo-audio"
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {AppState, Platform} from "react-native"
 import {BgTimer} from "../utils/timers"
+import {setAudioCloudUplinkSuppressed} from "./AudioCloudUplink"
+import {SILENT_AUDIO_SOURCE} from "./audioPlaybackAssets"
 
 const RESTORE_GLASSES_VOLUME_AFTER_PLAYBACK = false
 
@@ -10,14 +13,41 @@ interface AudioPlayRequest {
   appId?: string
   volume?: number
   stopOtherAudio?: boolean
+  /**
+   * Suppress microphone audio sent to cloud STT while this audio is audible.
+   * Opt-in and off by default: the suppression is global to the uplink, so a
+   * caller that sets this silences STT for every running app, not just itself.
+   * No platform path sets it today (see AudioCloudUplink and OS-1741).
+   */
+  suppressCloudUplink?: boolean
 }
 
+export type AudioPlaybackCompletionReason = "completed" | "interrupted" | "error"
+
+type AudioPlaybackCompletion = (
+  requestId: string,
+  success: boolean,
+  error: string | null,
+  duration: number | null,
+  reason: AudioPlaybackCompletionReason,
+) => void
+
 interface PlaybackState {
   requestId: string
+  audioUrl: string
+  uplinkSuppressionId: string
   appId?: string
   startTime: number
   completed: boolean // Guard against double callbacks
-  onComplete: (requestId: string, success: boolean, error: string | null, duration: number | null) => void
+  suppressCloudUplink: boolean
+  onComplete: AudioPlaybackCompletion
+}
+
+interface PendingPlaybackState {
+  cancelled: boolean
+  audioUrl: string
+  appId?: string
+  createdAt: number
 }
 
 /** Open request for a live PCM output stream (miniapp speaker.createStream). */
@@ -51,7 +81,14 @@ class AudioPlaybackService {
   // Reuse a single AudioPlayer to avoid AudioTrack exhaustion
   // Creating new ExoPlayer instances per request leads to -12 ENOMEM errors
   private player: AudioPlayer | null = null
+  // The source currently loaded into the reusable player. Keep object identity
+  // so a delayed tail cleanup from an older request cannot unload a newer one.
+  private loadedPlayback: PlaybackState | null = null
   private currentPlayback: PlaybackState | null = null
+  // Requests that entered play() but have not yet reached the native player.
+  // Keeping these addressable prevents a cancelled request from starting after
+  // an async audio-mode or stream-cleanup step finishes.
+  private pendingPlaybacks = new Map<string, PendingPlaybackState>()
   // Live PCM streams (speaker.createStream), keyed by streamId. The runtime
   // enforces one per app; stopOtherAudio interrupts across apps.
   private streams = new Map<string, StreamState>()
@@ -60,10 +97,30 @@ class AudioPlaybackService {
   // Prevents mic toggle flicker when playing back-to-back audio
   // Uses BgTimer to work reliably when app is backgrounded on Android
   private audioStopDebounceTimer: number | null = null
+  // Mentra Live's A2DP route may go idle between prompts. Keep a short warm
+  // window after actual audio so we only pre-roll the first sound after idle.
+  private audioRouteWarmUntil = 0
+  private audioRouteWarmupPromise: Promise<void> | null = null
+  // Playback that opted into suppression stays suppressed briefly while its
+  // A2DP tail drains. Track those completed sources so a later unsuppressed
+  // sound can resume listening immediately instead of inheriting that gate.
+  private tailUplinkSuppressions = new Set<string>()
   // Original glasses media volume captured before we bump it for A2DP playback.
   private glassesVolumeRestoreLevel: number | null = null
   private static readonly AUDIO_STOP_DEBOUNCE_MS = 1500
-  private static readonly A2DP_TAIL_DRAIN_MS = 900
+  private static readonly A2DP_TAIL_DRAIN_MS = 700
+  private static readonly AUDIO_ROUTE_WARM_WINDOW_MS = 1500
+  private static readonly AUDIO_ROUTE_PREWARM_MS = 200
+  private static readonly AUDIO_ROUTE_PREWARM_SAMPLE_RATE = 16_000
+  /** Break accidental same-app replay storms without affecting deliberate later replays. */
+  private static readonly DUPLICATE_PLAY_WINDOW_MS = 750
+  private static readonly AUDIO_ROUTE_PREWARM_PCM_BASE64 =
+    "AAAA".repeat(
+      Math.floor(
+        (AudioPlaybackService.AUDIO_ROUTE_PREWARM_MS * AudioPlaybackService.AUDIO_ROUTE_PREWARM_SAMPLE_RATE * 2) /
+          (1000 * 3),
+      ),
+    ) + "AA=="
   /** If glasses report step volume at or below this, bump to FLOOR before A2DP playback. */
   private static readonly GLASSES_VOLUME_LOW_THRESHOLD = 2
   private static readonly GLASSES_VOLUME_FLOOR = 9
@@ -126,6 +183,64 @@ class AudioPlaybackService {
     return this.player
   }
 
+  private markAudioRouteWarm(): void {
+    this.audioRouteWarmUntil = Date.now() + AudioPlaybackService.AUDIO_ROUTE_WARM_WINDOW_MS
+  }
+
+  private isAudioRouteWarm(): boolean {
+    return this.currentPlayback !== null || this.streams.size > 0 || Date.now() < this.audioRouteWarmUntil
+  }
+
+  /**
+   * Wake a cold Android A2DP route with silent PCM before a user-facing sound.
+   *
+   * Do not call pcmStreamClose here: some Bluetooth routes do not advance an
+   * idle AudioTrack playback head, so close waits for its drain timeout. After
+   * exactly 200ms of silence we abort the stream instead, which releases the
+   * pre-roll immediately and lets the real URL playback begin.
+   */
+  private async prewarmAudioRouteIfCold(): Promise<void> {
+    if (Platform.OS !== "android" || this.isAudioRouteWarm()) return
+    // This silent PCM pre-roll is only an anti-clipping optimization. Some
+    // Android devices defer opening its AudioTrack until the host Activity
+    // resumes even though the real URL player supports background playback.
+    // Never let that optional pre-roll block a glasses-initiated prompt.
+    if (AppState.currentState !== "active") {
+      console.log(`AUDIO: Skipping cold-route prewarm while app is ${AppState.currentState}`)
+      return
+    }
+    if (this.audioRouteWarmupPromise) return this.audioRouteWarmupPromise
+
+    const streamId = `audio-route-prewarm-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    const warmup = (async () => {
+      let opened = false
+      const startedAt = Date.now()
+      try {
+        console.log(`AUDIO: Cold route; prewarming with ${AudioPlaybackService.AUDIO_ROUTE_PREWARM_MS}ms silence`)
+        await BluetoothSdk.pcmStreamOpen(streamId, AudioPlaybackService.AUDIO_ROUTE_PREWARM_SAMPLE_RATE, 1, 1)
+        opened = true
+        await BluetoothSdk.pcmStreamWrite(streamId, AudioPlaybackService.AUDIO_ROUTE_PREWARM_PCM_BASE64)
+        await new Promise<void>((resolve) => {
+          BgTimer.setTimeout(resolve, AudioPlaybackService.AUDIO_ROUTE_PREWARM_MS)
+        })
+        await BluetoothSdk.pcmStreamAbort(streamId)
+        opened = false
+        this.markAudioRouteWarm()
+        console.log(`AUDIO: Cold-route prewarm completed in ${Date.now() - startedAt}ms`)
+      } catch (error) {
+        console.warn("AUDIO: Cold-route prewarm failed; continuing with requested audio:", error)
+      } finally {
+        if (opened) await BluetoothSdk.pcmStreamAbort(streamId).catch(() => {})
+      }
+    })()
+    this.audioRouteWarmupPromise = warmup
+    try {
+      await warmup
+    } finally {
+      if (this.audioRouteWarmupPromise === warmup) this.audioRouteWarmupPromise = null
+    }
+  }
+
   private async getGlassesMediaVolumeWithTiming() {
     const startedAt = Date.now()
     try {
@@ -226,46 +341,120 @@ class AudioPlaybackService {
     }
   }
 
-  private pauseFinishedPlayerAfterTail(playback: PlaybackState): void {
+  private unloadPlaybackSource(playback: PlaybackState, reason: string): void {
+    if (this.loadedPlayback !== playback) return
+    const player = this.player
+    if (!player) {
+      this.loadedPlayback = null
+      return
+    }
+
+    try {
+      player.pause()
+    } catch (e) {
+      console.warn(`AUDIO: Error pausing ${playback.requestId} during ${reason}:`, e)
+    }
+
+    try {
+      // replace(null) fails native argument casting on iOS, while remove()
+      // destroys the ExoPlayer that Android must reuse to avoid AudioTrack
+      // exhaustion. Replacing with bundled silence detaches the previous media
+      // item on both platforms and leaves the native player alive.
+      player.replace(SILENT_AUDIO_SOURCE)
+      console.log(`AUDIO: Cleared source for ${playback.requestId} during ${reason}`)
+    } catch (e) {
+      console.warn(`AUDIO: Error clearing ${playback.requestId} during ${reason}:`, e)
+    } finally {
+      if (this.loadedPlayback === playback) this.loadedPlayback = null
+    }
+  }
+
+  private clearFinishedPlayerAfterTail(playback: PlaybackState): void {
+    if (playback.suppressCloudUplink) {
+      this.tailUplinkSuppressions.add(playback.uplinkSuppressionId)
+    }
     BgTimer.setTimeout(() => {
-      if (this.currentPlayback) return
-      if (!this.player) return
-      try {
-        this.player.pause()
-        console.log(
-          `AUDIO: Paused finished player for ${playback.requestId} after ${AudioPlaybackService.A2DP_TAIL_DRAIN_MS}ms tail drain`,
-        )
-      } catch (e) {
-        console.warn("AUDIO: Error pausing player after tail drain:", e)
+      // ExoPlayer's completion event precedes the final A2DP audio reaching the
+      // glasses. Keep cloud STT gated until that audible tail has drained, then
+      // accept fresh microphone audio immediately without restarting LC3.
+      if (playback.suppressCloudUplink && this.tailUplinkSuppressions.delete(playback.uplinkSuppressionId)) {
+        setAudioCloudUplinkSuppressed(playback.uplinkSuppressionId, false)
       }
+      this.unloadPlaybackSource(playback, `${AudioPlaybackService.A2DP_TAIL_DRAIN_MS}ms A2DP tail drain`)
     }, AudioPlaybackService.A2DP_TAIL_DRAIN_MS)
   }
 
+  private releaseTailUplinkSuppressions(): void {
+    for (const sourceId of this.tailUplinkSuppressions) {
+      setAudioCloudUplinkSuppressed(sourceId, false)
+    }
+    this.tailUplinkSuppressions.clear()
+  }
+
   /**
    * Play audio from a URL.
    * Returns a promise that resolves with playback result when audio finishes or errors.
    */
-  public async play(
-    request: AudioPlayRequest,
-    onComplete: (requestId: string, success: boolean, error: string | null, duration: number | null) => void,
-  ): Promise<void> {
-    const {requestId, audioUrl, appId, volume = 1.0, stopOtherAudio = true} = request
+  public async play(request: AudioPlayRequest, onComplete: AudioPlaybackCompletion): Promise<void> {
+    const {requestId, audioUrl, appId, volume = 1.0, stopOtherAudio = true, suppressCloudUplink = false} = request
+    const now = Date.now()
+    const activeDuplicate =
+      this.currentPlayback &&
+      !this.currentPlayback.completed &&
+      this.currentPlayback.appId === appId &&
+      this.currentPlayback.audioUrl === audioUrl &&
+      now - this.currentPlayback.startTime < AudioPlaybackService.DUPLICATE_PLAY_WINDOW_MS
+    const pendingDuplicate = [...this.pendingPlaybacks.values()].some(
+      (candidate) =>
+        !candidate.cancelled &&
+        candidate.appId === appId &&
+        candidate.audioUrl === audioUrl &&
+        now - candidate.createdAt < AudioPlaybackService.DUPLICATE_PLAY_WINDOW_MS,
+    )
+    if (activeDuplicate || pendingDuplicate) {
+      console.warn(`AUDIO: Suppressed duplicate play request ${requestId}${appId ? ` from ${appId}` : ""}`)
+      onComplete(requestId, false, "Duplicate audio request suppressed", 0, "error")
+      return
+    }
+
+    const pending: PendingPlaybackState = {cancelled: false, audioUrl, appId, createdAt: now}
+    this.pendingPlaybacks.set(requestId, pending)
 
     console.log(`AUDIO: Play request ${requestId}${appId ? ` from ${appId}` : ""}: ${audioUrl}`)
 
     try {
       // Ensure audio mode is configured for background playback
       await this.ensureAudioModeConfigured()
+      if (pending.cancelled) {
+        onComplete(requestId, true, null, 0, "interrupted")
+        return
+      }
+      await this.prewarmAudioRouteIfCold()
+      if (pending.cancelled) {
+        onComplete(requestId, true, null, 0, "interrupted")
+        return
+      }
 
-      // Stop current playback if any (notify previous callback)
-      if (stopOtherAudio && this.currentPlayback && !this.currentPlayback.completed) {
-        console.log(`AUDIO: Interrupting current playback for new request`)
+      // URL playback reuses one native player, so replacing its source always
+      // interrupts the previous URL even when stopOtherAudio is false. Notify
+      // that request before replacing it so its promise cannot hang. The option
+      // still controls whether separate PCM streams are interrupted below.
+      if (this.currentPlayback && !this.currentPlayback.completed) {
+        console.log(`AUDIO: Interrupting current URL playback for new request`)
         this.interruptCurrentPlayback(true)
       }
       // Live PCM streams count as "other audio" too.
       if (stopOtherAudio) {
         await this.abortAllStreams()
       }
+      if (pending.cancelled) {
+        onComplete(requestId, true, null, 0, "interrupted")
+        return
+      }
+
+      if (!suppressCloudUplink) {
+        this.releaseTailUplinkSuppressions()
+      }
 
       // Get or create the reusable player
       const player = this.ensurePlayer()
@@ -276,16 +465,25 @@ class AudioPlaybackService {
       // Store the new playback state
       const playback: PlaybackState = {
         requestId,
+        audioUrl,
+        uplinkSuppressionId: `url:${requestId}`,
         appId,
         startTime: Date.now(),
         completed: false,
+        suppressCloudUplink,
         onComplete,
       }
       this.currentPlayback = playback
+      this.pendingPlaybacks.delete(requestId)
+      this.markAudioRouteWarm()
+      if (playback.suppressCloudUplink) {
+        setAudioCloudUplinkSuppressed(playback.uplinkSuppressionId, true)
+      }
 
       // Replace the source and play
       // Using replace() reuses the existing ExoPlayer/AudioTrack instead of creating new ones
       player.replace({uri: audioUrl})
+      this.loadedPlayback = playback
       player.play()
 
       // Mentra Live volume reads can block up to 5s when the glasses don't
@@ -307,10 +505,41 @@ class AudioPlaybackService {
 
       console.log(`AUDIO: Started playback for ${requestId}`)
     } catch (error) {
+      if (suppressCloudUplink) {
+        setAudioCloudUplinkSuppressed(`url:${requestId}`, false)
+      }
+      const failedPlayback = this.currentPlayback?.requestId === requestId ? this.currentPlayback : null
+      if (failedPlayback) {
+        failedPlayback.completed = true
+        this.currentPlayback = null
+        this.unloadPlaybackSource(failedPlayback, "playback start failure")
+      }
+      if (pending.cancelled) {
+        onComplete(requestId, true, null, 0, "interrupted")
+        return
+      }
       const errorMessage = error instanceof Error ? error.message : "Unknown error loading audio"
       console.error(`AUDIO: Failed to play ${requestId}:`, errorMessage)
       void this.restoreGlassesMediaVolume()
-      onComplete(requestId, false, errorMessage, null)
+      onComplete(requestId, false, errorMessage, null, "error")
+    } finally {
+      if (this.pendingPlaybacks.get(requestId) === pending) {
+        this.pendingPlaybacks.delete(requestId)
+      }
+    }
+  }
+
+  /**
+   * Cancel one URL playback without touching audio owned by another request.
+   * Pending requests are prevented from reaching the native player; active
+   * requests are paused synchronously before their completion callback fires.
+   */
+  public cancelPlayback(requestId: string): void {
+    const pending = this.pendingPlaybacks.get(requestId)
+    if (pending) pending.cancelled = true
+
+    if (this.currentPlayback?.requestId === requestId && !this.currentPlayback.completed) {
+      this.interruptCurrentPlayback()
     }
   }
 
@@ -323,15 +552,14 @@ class AudioPlaybackService {
     const playback = this.currentPlayback
     playback.completed = true
     this.currentPlayback = null
-
-    // Stop the player
-    if (this.player) {
-      try {
-        this.player.pause()
-      } catch (error) {
-        console.error("AUDIO: Error pausing player:", error)
-      }
+    if (playback.suppressCloudUplink) {
+      setAudioCloudUplinkSuppressed(playback.uplinkSuppressionId, false)
     }
+    this.markAudioRouteWarm()
+
+    // Pausing alone leaves the URI available to OS/Bluetooth media Play.
+    // Unload it unless a newer request has already replaced this source.
+    this.unloadPlaybackSource(playback, "interruption")
 
     // Notify native that our app stopped playing audio (debounced)
     this.notifyAudioStopDebounced()
@@ -341,7 +569,7 @@ class AudioPlaybackService {
 
     // Notify that playback was interrupted
     const elapsedMs = Date.now() - playback.startTime
-    playback.onComplete(playback.requestId, true, null, elapsedMs)
+    playback.onComplete(playback.requestId, true, null, elapsedMs, "interrupted")
     console.log(`AUDIO: Interrupted ${playback.requestId} after ${elapsedMs}ms`)
   }
 
@@ -364,11 +592,12 @@ class AudioPlaybackService {
 
       // ExoPlayer can report finished before an A2DP sink has audibly drained
       // the last buffered audio. Pausing immediately can clip the tail on
-      // Mentra Live; defer cleanup unless another playback has started.
-      this.pauseFinishedPlayerAfterTail(playback)
+      // Mentra Live; defer cleanup and guard it against a newer loaded source.
+      this.clearFinishedPlayerAfterTail(playback)
 
-      playback.onComplete(playback.requestId, true, null, durationMs)
       this.currentPlayback = null
+      playback.onComplete(playback.requestId, true, null, durationMs, "completed")
+      this.markAudioRouteWarm()
 
       // Notify native that our app stopped playing audio (debounced)
       this.notifyAudioStopDebounced()
@@ -385,8 +614,13 @@ class AudioPlaybackService {
       if (elapsedMs > 1500) {
         console.error(`AUDIO: Playback failed for ${playback.requestId} (player went idle after ${elapsedMs}ms)`)
         playback.completed = true
-        playback.onComplete(playback.requestId, false, "Playback failed (player went idle)", null)
         this.currentPlayback = null
+        if (playback.suppressCloudUplink) {
+          setAudioCloudUplinkSuppressed(playback.uplinkSuppressionId, false)
+        }
+        this.unloadPlaybackSource(playback, "playback failure")
+        playback.onComplete(playback.requestId, false, "Playback failed (player went idle)", null, "error")
+        this.markAudioRouteWarm()
         this.notifyAudioStopDebounced()
         void this.restoreGlassesMediaVolume()
       }
@@ -407,6 +641,10 @@ class AudioPlaybackService {
     // Uses BgTimer to work reliably when app is backgrounded on Android
     this.audioStopDebounceTimer = BgTimer.setTimeout(() => {
       this.audioStopDebounceTimer = null
+      // URL playback and live PCM streams may overlap when stopOtherAudio is false.
+      // A URL that ends must not clear the native playback signal while another
+      // source is still active, or the mic watchdog can interrupt that source.
+      if (this.isPlaying()) return
       BluetoothSdk.setOwnAppAudioPlaying(false).catch((e) => {
         console.warn("AUDIO: Failed to notify native of audio stop:", e)
       })
@@ -425,6 +663,7 @@ class AudioPlaybackService {
     console.log(`AUDIO: Stream open ${streamId} from ${appId}: rate=${sampleRate} ch=${channels}`)
 
     await this.ensureAudioModeConfigured()
+    await this.prewarmAudioRouteIfCold()
 
     if (stopOtherAudio) {
       if (this.currentPlayback && !this.currentPlayback.completed) {
@@ -435,12 +674,20 @@ class AudioPlaybackService {
     }
 
     await BluetoothSdk.pcmStreamOpen(streamId, sampleRate, channels, Math.max(0, Math.min(1, volume)))
-
-    const stream: StreamState = {streamId, appId, startTime: Date.now(), ended: false, onEnded: request.onEnded}
+    this.releaseTailUplinkSuppressions()
+
+    const stream: StreamState = {
+      streamId,
+      appId,
+      startTime: Date.now(),
+      ended: false,
+      onEnded: request.onEnded,
+    }
     this.streams.set(streamId, stream)
+    this.markAudioRouteWarm()
 
-    // Same LC3-mic-suspend dance as play(): cancel any pending "stopped"
-    // notification and mark our app as playing audio.
+    // Cancel any pending "stopped" notification and mark our app as playing
+    // audio. PCM streams intentionally do not suppress cloud STT.
     if (this.audioStopDebounceTimer !== null) {
       BgTimer.clearTimeout(this.audioStopDebounceTimer)
       this.audioStopDebounceTimer = null
@@ -513,6 +760,7 @@ class AudioPlaybackService {
     if (stream.ended) return
     stream.ended = true
     this.streams.delete(stream.streamId)
+    this.markAudioRouteWarm()
     // Only signal "audio stopped" when nothing else is making noise.
     if (this.streams.size === 0 && (!this.currentPlayback || this.currentPlayback.completed)) {
       this.notifyAudioStopDebounced()
@@ -616,6 +864,7 @@ class AudioPlaybackService {
         console.error("AUDIO: Error releasing player:", error)
       }
       this.player = null
+      this.loadedPlayback = null
     }
   }
 }

package/src/services/BlobStore.ts

@@ -97,22 +97,33 @@ interface ActiveReader {
 export class BlobStore {
   private readonly uploads = new Map<string, ActiveUpload>() // key: `${pkg} ${key}`
   private readonly readers = new Map<string, ActiveReader>() // key: host handle id
-  /** packageName → committed usage bytes, cached; invalidated on commit/delete/clear. */
+  /** user + package → committed usage bytes, cached; invalidated on commit/delete/clear. */
   private readonly usageCache = new Map<string, number>()
 
   constructor(private readonly hooks: BlobStoreHooks) {}
 
   // ---- path / meta helpers -------------------------------------------------
 
+  private currentIdentity(packageName: string): {userId: string; scope: string} {
+    const userId = this.hooks.getUserId().trim()
+    if (!userId) throw new Error("Mentra user identity is unavailable")
+    const scope = `${userId}\0${packageName}`
+    return {userId, scope}
+  }
+
   private dirFor(packageName: string): Directory {
-    const userId = sanitizeSegment(this.hooks.getUserId())
-    const dir = new Directory(Paths.document, ROOT_DIR_NAME, userId, sanitizeSegment(packageName))
+    const dir = new Directory(
+      Paths.document,
+      ROOT_DIR_NAME,
+      sanitizeSegment(this.currentIdentity(packageName).userId),
+      sanitizeSegment(packageName),
+    )
     if (!dir.exists) dir.create({intermediates: true})
     return dir
   }
 
   private metaPrefix(packageName: string): string {
-    return `${META_KEY_ROOT}${sanitizeSegment(this.hooks.getUserId())}_${packageName}_`
+    return `${META_KEY_ROOT}${sanitizeSegment(this.currentIdentity(packageName).userId)}_${packageName}_`
   }
 
   private metaKey(packageName: string, key: string): string {
@@ -163,17 +174,19 @@ export class BlobStore {
   }
 
   private committedUsage(packageName: string): number {
-    const cached = this.usageCache.get(packageName)
+    const {scope} = this.currentIdentity(packageName)
+    const cached = this.usageCache.get(scope)
     if (cached !== undefined) return cached
     let total = 0
     for (const m of this.allMeta(packageName)) total += m.bytes || 0
-    this.usageCache.set(packageName, total)
+    this.usageCache.set(scope, total)
     return total
   }
 
   private bumpUsage(packageName: string, delta: number): void {
-    const cur = this.usageCache.get(packageName)
-    if (cur !== undefined) this.usageCache.set(packageName, Math.max(0, cur + delta))
+    const {scope} = this.currentIdentity(packageName)
+    const cur = this.usageCache.get(scope)
+    if (cur !== undefined) this.usageCache.set(scope, Math.max(0, cur + delta))
   }
 
   private safeMd5(file: File, bytes: number): string | undefined {
@@ -509,7 +522,7 @@ export class BlobStore {
       } catch {
         /* best-effort */
       }
-      this.usageCache.set(packageName, 0)
+      this.usageCache.set(this.currentIdentity(packageName).scope, 0)
       this.hooks.sendResult(packageName, requestId, true)
     } catch (err) {
       this.fail(packageName, requestId, MiniappErrorCode.INTERNAL, err)

package/src/services/CloudAudioSubscriptionSync.ts

@@ -19,7 +19,19 @@ export class CloudAudioSubscriptionSync {
   private pendingKey = ""
 
   public begin(nextKey: string): boolean {
-    if (nextKey === this.lastAppliedKey || nextKey === this.pendingKey) {
+    // Exact duplicate of the write already in flight — nothing to do.
+    if (nextKey === this.pendingKey) {
+      return false
+    }
+    // Matches the last successfully applied set, but ONLY skip when nothing
+    // else is in flight. If a different write is pending (e.g. desired went
+    // fr-FR -> [] -> fr-FR while the [] write is still on the wire),
+    // lastAppliedKey is stale: it names what was applied BEFORE the in-flight
+    // write lands. Skipping here would drop the re-subscribe and strand the
+    // cloud on the intermediate (empty) set — captions silently die on any
+    // rapid A -> B -> A subscription churn. The cloud's own version counter
+    // resolves ordering between the concurrent writes, so sending both is safe.
+    if (nextKey === this.lastAppliedKey && this.pendingKey === "") {
       return false
     }
     this.pendingKey = nextKey