fix(storage): cross-tab admission for protected writes vs. active migrations

services/ai/aiInferenceCacheService.ts

@@ -1,5 +1,6 @@
 // QNBS-v3: Two-layer inference cache keeps hot reads in memory while the durable layer is encrypted.
 import { logger } from '../logger';
+import { withProtectedWriteAdmission } from '../storage/protectedWriteAdmission';
 import {
   assertSecureStorageReadable,
   assertSecureStorageWritableForMutation,
@@ -168,8 +169,11 @@ export class AiInferenceCacheService {
   ): Promise<void> {
     if (!this.db) return;
     try {
-      const encoded = await this.encodeEntry(key, result, timestamp);
-      await this.persistEntry(encoded);
+      // QNBS-v3: shares the writer-admission lock so this opportunistic write cannot land mid-migration-batch either.
+      await withProtectedWriteAdmission(async () => {
+        const encoded = await this.encodeEntry(key, result, timestamp);
+        await this.persistEntry(encoded);
+      });
     } catch {
       // QNBS-v3: best-effort; a failed opportunistic re-encrypt is not user-visible and TTL still bounds exposure.
     }
@@ -254,9 +258,12 @@ export class AiInferenceCacheService {
     await this.dbReady;
     if (!this.db) return;
     try {
-      const entry = await this.encodeEntry(key, result, Date.now());
-      await this.idbEvictOldest();
-      await this.persistEntry(entry);
+      // QNBS-v3: shares the writer-admission lock so eviction/persist cannot run mid-migration-batch and produce a false verification shortfall (#338).
+      await withProtectedWriteAdmission(async () => {
+        const entry = await this.encodeEntry(key, result, Date.now());
+        await this.idbEvictOldest();
+        await this.persistEntry(entry);
+      });
     } catch {
       // QNBS-v3: The encrypted durable cache is non-authoritative; lock or migration state must not fail inference.
     }

services/sceneRevisionService.ts

@@ -1,6 +1,7 @@
 // QNBS-v3: Standalone IDB for scene revisions avoids a shared schema upgrade and keeps history bounded.
 import type { SceneRevision } from '../types';
 import { createLogger } from './logger';
+import { withProtectedWriteAdmission } from './storage/protectedWriteAdmission';
 import {
   assertSecureStorageReadable,
   assertSecureStorageWritableForMutation,
@@ -228,10 +229,14 @@ export async function saveRevision(
     ...(authorName !== undefined ? { authorName } : {}),
   };
 
-  // QNBS-v3: Encrypt before IDB work so WebCrypto cannot make a write transaction inactive.
-  const stored = await encodeRevision(revision);
-  const db = await getDb();
-  await saveStoredRevisionWithRetention(db, stored);
+  // QNBS-v3: shares the writer-admission lock with primary-store writes so encode-through-commit
+  //          cannot straddle a migration batch and land under a superseded key/generation (#338).
+  await withProtectedWriteAdmission(async () => {
+    // QNBS-v3: Encrypt before IDB work so WebCrypto cannot make a write transaction inactive.
+    const stored = await encodeRevision(revision);
+    const db = await getDb();
+    await saveStoredRevisionWithRetention(db, stored);
+  });
   return revision;
 }
 
@@ -266,9 +271,12 @@ export async function listRevisions(sectionId: string): Promise<SceneRevision[]>
 
 /** Deletes a single revision by ID. */
 export async function deleteRevision(id: string): Promise<void> {
-  await assertSecureStorageWritableForMutation();
-  const db = await getDb();
-  await deleteRevisions(db, [id]);
+  // QNBS-v3: shares the writer-admission lock so this delete cannot land mid-migration-batch either.
+  await withProtectedWriteAdmission(async () => {
+    await assertSecureStorageWritableForMutation();
+    const db = await getDb();
+    await deleteRevisions(db, [id]);
+  });
 }
 
 /** Reset the singleton and close its handle so tests cannot retain a stale database connection. */

services/storage/idbAssetStore.ts

@@ -9,6 +9,7 @@ import type { BinderAssetMeta, BinderAssetPayload } from '../storageBackend';
 import { makeBinderAssetIdsPrefix, makeBinderAssetStorageKey } from '../storageBackend';
 import { getUserFriendlyDbError, retryDb } from './idbCore';
 import { IdbSnapshotStore } from './idbSnapshotStore';
+import { withProtectedWriteAdmission } from './protectedWriteAdmission';
 import {
   assertIdbProtectedWriteAllowed,
   assertNoActiveEncryptionMigration,
@@ -23,19 +24,21 @@ export class IdbAssetStore extends IdbSnapshotStore {
   // --- Image Store Methods ---
 
   async saveImage(id: string, base64: string): Promise<void> {
-    // QNBS-v3: Resolve the write key BEFORE opening the transaction — `await idbEncryptWithKey`
-    //          yields the event loop, which auto-commits an already-open IDB transaction
-    //          (TransactionInactiveError on put), and re-reading isIdbEncryptionReady() after any
-    //          later await could race with Lock Session and silently fall back to plaintext.
-    const writeKey = await resolveProtectedWriteKey();
-    const payload = writeKey ? await idbEncryptWithKey(writeKey, base64) : base64;
-    // QNBS-v3: only the migration guard is re-checked here — resolveProtectedWriteKey() already made its own lock check atomically with the key snapshot, so re-running that too would wrongly reject an already-safely-encrypted write if the session locks mid-write.
-    await assertNoActiveEncryptionMigration();
-    const store = await this.getObjectStore(IMAGES_STORE, 'readwrite');
-    return new Promise((resolve, reject) => {
-      const request = store.put(payload, id);
-      request.onsuccess = () => resolve();
-      request.onerror = () => reject(request.error);
+    return withProtectedWriteAdmission(async () => {
+      // QNBS-v3: Resolve the write key BEFORE opening the transaction — `await idbEncryptWithKey`
+      //          yields the event loop, which auto-commits an already-open IDB transaction
+      //          (TransactionInactiveError on put), and re-reading isIdbEncryptionReady() after any
+      //          later await could race with Lock Session and silently fall back to plaintext.
+      const writeKey = await resolveProtectedWriteKey();
+      const payload = writeKey ? await idbEncryptWithKey(writeKey, base64) : base64;
+      // QNBS-v3: only the migration guard is re-checked here — resolveProtectedWriteKey() already made its own lock check atomically with the key snapshot, so re-running that too would wrongly reject an already-safely-encrypted write if the session locks mid-write.
+      await assertNoActiveEncryptionMigration();
+      const store = await this.getObjectStore(IMAGES_STORE, 'readwrite');
+      return new Promise<void>((resolve, reject) => {
+        const request = store.put(payload, id);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+      });
     });
   }
 
@@ -66,13 +69,15 @@ export class IdbAssetStore extends IdbSnapshotStore {
   }
 
   async deleteImage(id: string): Promise<void> {
-    // QNBS-v3: A locked session must not be able to destroy protected images it cannot read.
-    await assertIdbProtectedWriteAllowed();
-    const store = await this.getObjectStore(IMAGES_STORE, 'readwrite');
-    return new Promise((resolve, reject) => {
-      const request = store.delete(id);
-      request.onsuccess = () => resolve();
-      request.onerror = () => reject(request.error);
+    return withProtectedWriteAdmission(async () => {
+      // QNBS-v3: A locked session must not be able to destroy protected images it cannot read.
+      await assertIdbProtectedWriteAllowed();
+      const store = await this.getObjectStore(IMAGES_STORE, 'readwrite');
+      return new Promise<void>((resolve, reject) => {
+        const request = store.delete(id);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+      });
     });
   }
 
@@ -84,30 +89,32 @@ export class IdbAssetStore extends IdbSnapshotStore {
     data: ArrayBuffer,
     meta: BinderAssetMeta,
   ): Promise<void> {
-    return retryDb(async () => {
-      const writeKey = await resolveProtectedWriteKey();
-      const key = makeBinderAssetStorageKey(projectId, assetId);
-      const fullMeta = { ...meta, byteSize: data.byteLength };
-      // QNBS-v3: idbEncrypt serialises via JSON.stringify, which silently drops a Blob ({} → no data).
-      //          When encrypting, persist the raw bytes; otherwise store a structured-clone-friendly Blob.
-      const payload = writeKey
-        ? await idbEncryptWithKey(writeKey, {
-            meta: fullMeta,
-            bytes: Array.from(new Uint8Array(data)),
-          })
-        : {
-            meta: fullMeta,
-            blob: new Blob([data], { type: meta.mimeType || 'application/octet-stream' }),
-          };
-      // QNBS-v3: only the migration guard is re-checked here — resolveProtectedWriteKey() already made its own lock check atomically with the key snapshot, so re-running that too would wrongly reject an already-safely-encrypted write if the session locks mid-write.
-      await assertNoActiveEncryptionMigration();
-      const store = await this.getObjectStore(BINDER_ASSETS_STORE, 'readwrite');
-      return new Promise<void>((resolve, reject) => {
-        const req = store.put(payload, key);
-        req.onsuccess = () => resolve();
-        req.onerror = () => reject(getUserFriendlyDbError(req.error));
-      });
-    });
+    return retryDb(() =>
+      withProtectedWriteAdmission(async () => {
+        const writeKey = await resolveProtectedWriteKey();
+        const key = makeBinderAssetStorageKey(projectId, assetId);
+        const fullMeta = { ...meta, byteSize: data.byteLength };
+        // QNBS-v3: idbEncrypt serialises via JSON.stringify, which silently drops a Blob ({} → no data).
+        //          When encrypting, persist the raw bytes; otherwise store a structured-clone-friendly Blob.
+        const payload = writeKey
+          ? await idbEncryptWithKey(writeKey, {
+              meta: fullMeta,
+              bytes: Array.from(new Uint8Array(data)),
+            })
+          : {
+              meta: fullMeta,
+              blob: new Blob([data], { type: meta.mimeType || 'application/octet-stream' }),
+            };
+        // QNBS-v3: only the migration guard is re-checked here — resolveProtectedWriteKey() already made its own lock check atomically with the key snapshot, so re-running that too would wrongly reject an already-safely-encrypted write if the session locks mid-write.
+        await assertNoActiveEncryptionMigration();
+        const store = await this.getObjectStore(BINDER_ASSETS_STORE, 'readwrite');
+        return new Promise<void>((resolve, reject) => {
+          const req = store.put(payload, key);
+          req.onsuccess = () => resolve();
+          req.onerror = () => reject(getUserFriendlyDbError(req.error));
+        });
+      }),
+    );
   }
 
   async getBinderAsset(projectId: string, assetId: string): Promise<BinderAssetPayload | null> {
@@ -136,17 +143,19 @@ export class IdbAssetStore extends IdbSnapshotStore {
   }
 
   async deleteBinderAsset(projectId: string, assetId: string): Promise<void> {
-    return retryDb(async () => {
-      // QNBS-v3: A locked session must not be able to destroy protected binder assets it cannot read.
-      await assertIdbProtectedWriteAllowed();
-      const key = makeBinderAssetStorageKey(projectId, assetId);
-      const store = await this.getObjectStore(BINDER_ASSETS_STORE, 'readwrite');
-      return new Promise<void>((resolve, reject) => {
-        const req = store.delete(key);
-        req.onsuccess = () => resolve();
-        req.onerror = () => reject(getUserFriendlyDbError(req.error));
-      });
-    });
+    return retryDb(() =>
+      withProtectedWriteAdmission(async () => {
+        // QNBS-v3: A locked session must not be able to destroy protected binder assets it cannot read.
+        await assertIdbProtectedWriteAllowed();
+        const key = makeBinderAssetStorageKey(projectId, assetId);
+        const store = await this.getObjectStore(BINDER_ASSETS_STORE, 'readwrite');
+        return new Promise<void>((resolve, reject) => {
+          const req = store.delete(key);
+          req.onsuccess = () => resolve();
+          req.onerror = () => reject(getUserFriendlyDbError(req.error));
+        });
+      }),
+    );
   }
 
   async listBinderAssetIds(projectId: string): Promise<string[]> {
@@ -176,6 +185,13 @@ export class IdbAssetStore extends IdbSnapshotStore {
   }
 
   async deleteAllBinderAssetsForProject(projectId: string): Promise<void> {
+    return withProtectedWriteAdmission(() =>
+      this.deleteAllBinderAssetsForProjectUnadmitted(projectId),
+    );
+  }
+
+  // QNBS-v3: unwrapped core for deleteProject() to call inside its own single outer admission — nesting withProtectedWriteAdmission (same shared lock name, same call stack) can deadlock if an exclusive migration request queues between the outer and inner acquisition.
+  protected async deleteAllBinderAssetsForProjectUnadmitted(projectId: string): Promise<void> {
     return retryDb(async () => {
       await assertIdbProtectedWriteAllowed();
       const ids = await this.listBinderAssetIds(projectId);