@weasel-js/labkit 1.4.3 → 1.5.0

package/src/state/adapters.ts

@@ -1,56 +1,104 @@
 import { decodeUrlHash, encodeUrlHash } from './helpers';
-import type { StorageAdapter } from './types';
-
-/** Persist to `localStorage` — state survives a reload and a new tab. Falls
- *  back to no-ops when storage is unavailable. */
-export const localStorageAdapter: StorageAdapter = {
-  read: (key) => {
-    try {
-      return localStorage.getItem(key);
-    } catch {
-      return null;
-    }
-  },
-  write: (key, value) => {
-    try {
-      localStorage.setItem(key, value);
-    } catch (e) {
-      console.warn('[labkit] localStorage write failed:', e);
-    }
-  },
-  delete: (key) => {
-    try {
-      localStorage.removeItem(key);
-    } catch {
-      /* ignore */
-    }
-  },
-};
+import type { StorageAdapter, StorageChange } from './types';
 
-/** Persist to `sessionStorage` — state survives a reload but not a new tab. */
-export const sessionStorageAdapter: StorageAdapter = {
-  read: (key) => {
-    try {
-      return sessionStorage.getItem(key);
-    } catch {
-      return null;
-    }
-  },
-  write: (key, value) => {
-    try {
-      sessionStorage.setItem(key, value);
-    } catch (e) {
-      console.warn('[labkit] sessionStorage write failed:', e);
-    }
-  },
-  delete: (key) => {
-    try {
-      sessionStorage.removeItem(key);
-    } catch {
-      /* ignore */
+/** JSON-backed substrates held raw strings before records existed — a theme
+ *  bucket stored `dark`, not `"dark"` — so an unparseable value comes back as
+ *  the string it is. */
+function parse(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/** Whether `JSON.stringify` would keep `value` exactly. An object key holding
+ *  `undefined` counts as kept: JSON drops the key, and reading back an absent
+ *  key yields the same `undefined`. */
+function isJsonSafe(value: unknown, seen: Set<object> = new Set()): boolean {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'string':
+    case 'boolean':
+      return true;
+    case 'number':
+      return Number.isFinite(value);
+    case 'object': {
+      if (seen.has(value)) return false;
+      seen.add(value);
+      const proto = Object.getPrototypeOf(value);
+      const ok = Array.isArray(value)
+        ? value.every((v) => isJsonSafe(v, seen))
+        : (proto === Object.prototype || proto === null) &&
+          Object.values(value).every((v) => v === undefined || isJsonSafe(v, seen));
+      seen.delete(value);
+      return ok;
     }
-  },
-};
+    default:
+      return false;
+  }
+}
+
+function webStorageAdapter(area: () => Storage, name: string, crossTab: boolean): StorageAdapter {
+  const warned = new Set<string>();
+  const adapter: StorageAdapter = {
+    get: async (key) => {
+      const raw = area().getItem(key);
+      return raw === null ? undefined : parse(raw);
+    },
+    list: async (prefix) => {
+      const store = area();
+      const out: [string, unknown][] = [];
+      for (let i = 0; i < store.length; i++) {
+        const key = store.key(i);
+        if (key === null || !key.startsWith(prefix)) continue;
+        const raw = store.getItem(key);
+        if (raw !== null) out.push([key, parse(raw)]);
+      }
+      return out;
+    },
+    set: async (key, value) => {
+      if (!warned.has(key) && !isJsonSafe(value)) {
+        warned.add(key);
+        console.warn(
+          `[labkit] "${key}" holds a value JSON cannot keep exactly; ${name} stores what JSON keeps. Use IndexedDB for binary or non-JSON state.`,
+        );
+      }
+      area().setItem(key, JSON.stringify(value));
+    },
+    delete: async (key) => {
+      area().removeItem(key);
+    },
+  };
+  if (crossTab) {
+    adapter.subscribe = (prefix, on) => {
+      if (typeof window === 'undefined') return () => {};
+      const handler = (e: StorageEvent): void => {
+        if (e.key === null || !e.key.startsWith(prefix)) return;
+        if (e.storageArea !== area()) return;
+        on([[e.key, e.newValue === null ? undefined : parse(e.newValue)]]);
+      };
+      window.addEventListener('storage', handler);
+      return () => window.removeEventListener('storage', handler);
+    };
+  }
+  return adapter;
+}
+
+/** Persist to `localStorage`, one JSON value per record. Survives a reload and
+ *  reaches other tabs through the `storage` event. */
+export const localStorageAdapter: StorageAdapter = webStorageAdapter(
+  () => localStorage,
+  'localStorage',
+  true,
+);
+
+/** Persist to `sessionStorage` — survives a reload but not a new tab. */
+export const sessionStorageAdapter: StorageAdapter = webStorageAdapter(
+  () => sessionStorage,
+  'sessionStorage',
+  false,
+);
 
 const URL_HASH_GUARD = typeof window !== 'undefined';
 
@@ -65,46 +113,257 @@ function readHashMap(): Record<string, string> {
   }
 }
 
+/** What each live subscription last saw, refreshed on this page's own writes
+ *  so `hashchange` reports only somebody else's. */
+const hashSubscribers = new Set<{ last: Record<string, string> }>();
+
 function writeHashMap(map: Record<string, string>): void {
   if (!URL_HASH_GUARD) return;
   const encoded = encodeUrlHash(JSON.stringify(map));
   window.history.replaceState(null, '', `#${encoded}`);
+  for (const sub of hashSubscribers) sub.last = { ...map };
 }
 
-/** Persist into the URL fragment, so the page's link carries its state and
- *  can be shared or bookmarked. */
+/** Persist into the URL fragment, so the page's link carries its state and can
+ *  be shared or bookmarked. Changes to the fragment made elsewhere — a pasted
+ *  link, back and forward — arrive through `hashchange`. */
 export const urlHashAdapter: StorageAdapter = {
-  read: (key) => readHashMap()[key] ?? null,
-  write: (key, value) => {
+  get: async (key) => {
+    const raw = readHashMap()[key];
+    return raw === undefined ? undefined : parse(raw);
+  },
+  list: async (prefix) =>
+    Object.entries(readHashMap())
+      .filter(([key]) => key.startsWith(prefix))
+      .map(([key, raw]): [string, unknown] => [key, parse(raw)]),
+  set: async (key, value) => {
     const map = readHashMap();
-    map[key] = value;
+    map[key] = JSON.stringify(value);
     writeHashMap(map);
   },
-  delete: (key) => {
+  delete: async (key) => {
     const map = readHashMap();
     delete map[key];
     writeHashMap(map);
   },
+  subscribe: (prefix, on) => {
+    if (!URL_HASH_GUARD) return () => {};
+    const sub = { last: readHashMap() };
+    hashSubscribers.add(sub);
+    const handler = (): void => {
+      const next = readHashMap();
+      const changes: StorageChange[] = [];
+      for (const key of new Set([...Object.keys(sub.last), ...Object.keys(next)])) {
+        if (!key.startsWith(prefix) || sub.last[key] === next[key]) continue;
+        const raw = next[key];
+        changes.push([key, raw === undefined ? undefined : parse(raw)]);
+      }
+      sub.last = next;
+      if (changes.length > 0) on(changes);
+    };
+    window.addEventListener('hashchange', handler);
+    return () => {
+      hashSubscribers.delete(sub);
+      window.removeEventListener('hashchange', handler);
+    };
+  },
 };
 
-/** An in-memory store, discarded on reload. For tests, and for labs that
- *  should start fresh every time. */
-export function createMemoryAdapter(): StorageAdapter {
-  const store = new Map<string, string>();
-  return {
-    read: (key) => store.get(key) ?? null,
-    write: (key, value) => {
-      store.set(key, value);
+interface MemorySubscriber {
+  owner: StorageAdapter;
+  prefix: string;
+  on: (changes: StorageChange[]) => void;
+}
+
+const memorySubscribers = new WeakMap<Map<string, unknown>, Set<MemorySubscriber>>();
+
+/** An in-memory store, discarded on reload. Values are copied in and out, as a
+ *  real substrate would. Adapters built over one shared `backing` hear each
+ *  other's writes — two tabs, for a test. */
+export function createMemoryAdapter(backing: Map<string, unknown> = new Map()): StorageAdapter {
+  let subscribers = memorySubscribers.get(backing);
+  if (!subscribers) {
+    subscribers = new Set();
+    memorySubscribers.set(backing, subscribers);
+  }
+  const peers = subscribers;
+  const notify = (key: string, value: unknown): void => {
+    for (const sub of peers) {
+      if (sub.owner === adapter || !key.startsWith(sub.prefix)) continue;
+      const copy = value === undefined ? undefined : structuredClone(value);
+      queueMicrotask(() => sub.on([[key, copy]]));
+    }
+  };
+  const adapter: StorageAdapter = {
+    get: async (key) => (backing.has(key) ? structuredClone(backing.get(key)) : undefined),
+    list: async (prefix) =>
+      [...backing]
+        .filter(([key]) => key.startsWith(prefix))
+        .map(([key, value]): [string, unknown] => [key, structuredClone(value)]),
+    set: async (key, value) => {
+      const copy = structuredClone(value);
+      backing.set(key, copy);
+      notify(key, copy);
+    },
+    delete: async (key) => {
+      backing.delete(key);
+      notify(key, undefined);
     },
-    delete: (key) => {
-      store.delete(key);
+    subscribe: (prefix, on) => {
+      const sub = { owner: adapter, prefix, on };
+      peers.add(sub);
+      return () => {
+        peers.delete(sub);
+      };
     },
   };
+  return adapter;
 }
 
 /** Persists nothing and reads back nothing. */
 export const noneAdapter: StorageAdapter = {
-  read: () => null,
-  write: () => {},
-  delete: () => {},
+  get: async () => undefined,
+  list: async () => [],
+  set: async () => {},
+  delete: async () => {},
 };
+
+/** Options for `createIndexedDbAdapter`. */
+export interface IndexedDbAdapterOptions {
+  /** Default `'labkit'`. */
+  database?: string;
+  /** Default `'records'`. One object store per database: a store added to a
+   *  database that already exists is not created. */
+  store?: string;
+}
+
+interface NodeChannel extends BroadcastChannel {
+  unref?: () => void;
+}
+
+/** Persist to IndexedDB, which stores structured-clone values natively — typed
+ *  arrays, `Map`s, `Blob`s — and holds far more than localStorage. Other tabs
+ *  hear writes through a `BroadcastChannel`. The database opens on first use. */
+export function createIndexedDbAdapter({
+  database = 'labkit',
+  store = 'records',
+}: IndexedDbAdapterOptions = {}): StorageAdapter {
+  let opened: Promise<IDBDatabase> | null = null;
+  const open = (): Promise<IDBDatabase> => {
+    opened ??= new Promise((resolve, reject) => {
+      if (typeof indexedDB === 'undefined') {
+        reject(new Error('[labkit] IndexedDB is not available here'));
+        return;
+      }
+      const request = indexedDB.open(database, 1);
+      request.onupgradeneeded = () => {
+        if (!request.result.objectStoreNames.contains(store)) {
+          request.result.createObjectStore(store);
+        }
+      };
+      request.onsuccess = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(store)) {
+          reject(new Error(`[labkit] IndexedDB database "${database}" has no store "${store}"`));
+          return;
+        }
+        resolve(db);
+      };
+      request.onerror = () => reject(request.error);
+      request.onblocked = () => reject(new Error(`[labkit] IndexedDB "${database}" is blocked`));
+    });
+    return opened;
+  };
+
+  const run = <T>(mode: IDBTransactionMode, body: (s: IDBObjectStore) => () => T): Promise<T> =>
+    open().then(
+      (db) =>
+        new Promise<T>((resolve, reject) => {
+          const tx = db.transaction(store, mode);
+          const result = body(tx.objectStore(store));
+          tx.oncomplete = () => resolve(result());
+          tx.onerror = () => reject(tx.error);
+          tx.onabort = () => reject(tx.error);
+        }),
+    );
+
+  let channel: NodeChannel | null = null;
+  const getChannel = (): NodeChannel | null => {
+    if (typeof BroadcastChannel === 'undefined') return null;
+    if (!channel) {
+      channel = new BroadcastChannel(`labkit:${database}:${store}`) as NodeChannel;
+      // Node keeps its event loop alive for an open channel; a browser has no unref.
+      channel.unref?.();
+    }
+    return channel;
+  };
+  const announce = (changes: StorageChange[]): void => {
+    getChannel()?.postMessage(changes);
+  };
+
+  const adapter: StorageAdapter = {
+    get: (key) =>
+      run('readonly', (s) => {
+        const request = s.get(key);
+        return () => request.result as unknown;
+      }),
+    list: (prefix) =>
+      run('readonly', (s) => {
+        const range = IDBKeyRange.bound(prefix, `${prefix}￿`);
+        const keys = s.getAllKeys(range);
+        const values = s.getAll(range);
+        return () =>
+          keys.result.map((key, i): [string, unknown] => [String(key), values.result[i]]);
+      }),
+    set: async (key, value) => {
+      await run('readwrite', (s) => {
+        s.put(value, key);
+        return () => undefined;
+      });
+      announce([[key, value]]);
+    },
+    delete: async (key) => {
+      await run('readwrite', (s) => {
+        s.delete(key);
+        return () => undefined;
+      });
+      announce([[key, undefined]]);
+    },
+  };
+  if (typeof BroadcastChannel !== 'undefined') {
+    adapter.subscribe = (prefix, on) => {
+      const ch = getChannel();
+      if (!ch) return () => {};
+      const handler = (e: MessageEvent<StorageChange[]>): void => {
+        const mine = e.data.filter(([key]) => key.startsWith(prefix));
+        if (mine.length > 0) on(mine);
+      };
+      ch.addEventListener('message', handler);
+      return () => ch.removeEventListener('message', handler);
+    };
+  }
+  return adapter;
+}
+
+/** IndexedDB under the default database and store. */
+export const indexedDbAdapter: StorageAdapter = createIndexedDbAdapter();
+
+let resolvedDefault: Promise<StorageAdapter> | null = null;
+
+/** What a lab given only a `storageKey` persists to: IndexedDB, or
+ *  localStorage — with a warning — where IndexedDB will not open. */
+export function defaultStorage(): Promise<StorageAdapter> {
+  resolvedDefault ??= indexedDbAdapter.list('').then(
+    () => indexedDbAdapter,
+    (error) => {
+      console.warn('[labkit] IndexedDB would not open; persisting to localStorage instead', error);
+      return localStorageAdapter;
+    },
+  );
+  return resolvedDefault;
+}
+
+/** Forget which default was chosen. Tests only. */
+export function resetDefaultStorage(): void {
+  resolvedDefault = null;
+}

package/src/state/document.test.ts

@@ -1,14 +1,15 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { createMemoryAdapter } from './adapters';
 import {
   CURRENT_DOCUMENT_VERSION,
-  deleteLegacyKeys,
+  deleteConfirmed,
   emptyDocument,
   labDocumentKey,
   MIGRATIONS,
   migrateV0toV1,
   migrateV1toV2,
   migrateV2toV3,
+  migrateV3toV4,
   normalizeDocument,
   quarantineDocument,
   quarantineKey,
@@ -83,19 +84,24 @@ describe('runMigrations', () => {
   });
 });
 
+function reader(entries: Record<string, unknown>) {
+  const map = new Map(Object.entries(entries));
+  return async (key: string) => map.get(key);
+}
+
 describe('readLegacyDocument', () => {
-  it('returns null when no legacy key is present', () => {
-    expect(readLegacyDocument(createMemoryAdapter(), 'lab', 'auto')).toBeNull();
+  it('returns null when no legacy key is present', async () => {
+    expect(await readLegacyDocument(reader({}), 'lab', 'auto')).toBeNull();
   });
 
-  it('assembles a version-0 document from the four buckets', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labStorageKey('lab', 'saves'), JSON.stringify([{ id: 's1' }]));
-    storage.write(labStorageKey('lab', 'layout'), JSON.stringify({ w1: { h: 4 } }));
-    storage.write(labStorageKey('lab', 'theme'), 'dark');
-
-    expect(readLegacyDocument(storage, 'lab', 'auto')).toEqual({
+  it('assembles a version-0 document from the four buckets, parsed or not', async () => {
+    const read = reader({
+      [labStorageKey('lab', 'workspaces')]: JSON.stringify([{ id: 'w1' }]),
+      [labStorageKey('lab', 'saves')]: [{ id: 's1' }],
+      [labStorageKey('lab', 'layout')]: JSON.stringify({ w1: { h: 4 } }),
+      [labStorageKey('lab', 'theme')]: 'dark',
+    });
+    expect(await readLegacyDocument(read, 'lab', 'auto')).toEqual({
       version: 0,
       workspaces: [{ id: 'w1' }],
       saves: [{ id: 's1' }],
@@ -104,97 +110,54 @@ describe('readLegacyDocument', () => {
     });
   });
 
-  it('survives one unparseable bucket without losing the others', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), '{{{not json');
-    storage.write(labStorageKey('lab', 'saves'), JSON.stringify([{ id: 's1' }]));
-
-    const doc = readLegacyDocument(storage, 'lab', 'auto');
+  it('survives one unparseable bucket without losing the others', async () => {
+    const read = reader({
+      [labStorageKey('lab', 'workspaces')]: '{{{not json',
+      [labStorageKey('lab', 'saves')]: JSON.stringify([{ id: 's1' }]),
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const doc = await readLegacyDocument(read, 'lab', 'auto');
     expect(doc?.workspaces).toEqual([]);
     expect(doc?.saves).toEqual([{ id: 's1' }]);
+    warn.mockRestore();
   });
 
-  it('falls back to fallbackMode when the theme key is absent', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([]));
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('dark');
+  it('falls back to fallbackMode when the theme key is absent', async () => {
+    const read = reader({ [labStorageKey('lab', 'workspaces')]: '[]' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('dark');
   });
 
-  it('falls back to fallbackMode when the theme value is unrecognized', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'theme'), 'chartreuse');
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('dark');
+  it('falls back to fallbackMode when the theme value is unrecognized', async () => {
+    const read = reader({ [labStorageKey('lab', 'theme')]: 'chartreuse' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('dark');
   });
 
-  it('a valid theme value beats the fallback', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'theme'), 'light');
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('light');
+  it('a valid theme value beats the fallback', async () => {
+    const read = reader({ [labStorageKey('lab', 'theme')]: 'light' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('light');
   });
 
-  it('passes interstellar through untouched for migrateV0toV1 to coerce', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'theme'), 'interstellar');
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('interstellar');
+  it('passes interstellar through untouched for migrateV0toV1 to coerce', async () => {
+    const read = reader({ [labStorageKey('lab', 'theme')]: 'interstellar' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('interstellar');
   });
 });
 
-describe('deleteLegacyKeys', () => {
-  it('deletes all four legacy buckets when the document matches', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labStorageKey('lab', 'saves'), JSON.stringify([{ id: 's1' }]));
-    storage.write(labStorageKey('lab', 'layout'), JSON.stringify({ w1: { h: 4 } }));
-    storage.write(labStorageKey('lab', 'theme'), 'dark');
-    storage.write(labDocumentKey('lab'), 'the-document');
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(true);
-
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).toBeNull();
-    expect(storage.read(labStorageKey('lab', 'saves'))).toBeNull();
-    expect(storage.read(labStorageKey('lab', 'layout'))).toBeNull();
-    expect(storage.read(labStorageKey('lab', 'theme'))).toBeNull();
-  });
-
-  it('the document key itself survives deletion', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labDocumentKey('lab'), 'the-document');
-
-    deleteLegacyKeys(storage, 'lab', 'the-document');
-
-    expect(storage.read(labDocumentKey('lab'))).toBe('the-document');
-  });
-
-  it('deletes nothing and returns false when the document key is absent', () => {
+describe('deleteConfirmed', () => {
+  it('deletes the keys and confirms they are gone', async () => {
     const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(false);
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).not.toBeNull();
+    await storage.set('a', 1);
+    await storage.set('b', 2);
+    expect(await deleteConfirmed(storage, ['a', 'b'])).toBe(true);
+    expect(await storage.get('a')).toBeUndefined();
   });
 
-  it('returns false when the adapter cannot delete, and the keys survive', () => {
-    const mem = createMemoryAdapter();
-    const storage = { read: mem.read, write: mem.write };
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labDocumentKey('lab'), 'the-document');
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(false);
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).not.toBeNull();
-  });
-
-  it('deletes nothing and returns false when the document key holds different content', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labDocumentKey('lab'), 'something-else');
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(false);
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).not.toBeNull();
+  it('returns false when a delete silently does nothing', async () => {
+    const memory = createMemoryAdapter();
+    await memory.set('a', 1);
+    const storage = { ...memory, delete: async () => {} };
+    expect(await deleteConfirmed(storage, ['a'])).toBe(false);
+    expect(await memory.get('a')).toBe(1);
   });
 });
 
@@ -303,18 +266,15 @@ describe('MIGRATIONS', () => {
 });
 
 describe('quarantineDocument', () => {
-  it('copies the document aside and confirms it landed', () => {
+  it('copies the document aside and confirms it landed', async () => {
     const storage = createMemoryAdapter();
-
-    expect(quarantineDocument(storage, 'lab', 'the-bytes')).toBe(true);
-    expect(storage.read(quarantineKey('lab'))).toBe('the-bytes');
+    expect(await quarantineDocument(storage, 'lab', 'the-bytes')).toBe(true);
+    expect(await storage.get(quarantineKey('lab'))).toBe('the-bytes');
   });
 
-  it('returns false when the quarantine write silently fails', () => {
-    const storage = createMemoryAdapter();
-    storage.write = () => {};
-
-    expect(quarantineDocument(storage, 'lab', 'the-bytes')).toBe(false);
+  it('returns false when the quarantine write silently fails', async () => {
+    const storage = { ...createMemoryAdapter(), set: async () => {} };
+    expect(await quarantineDocument(storage, 'lab', 'the-bytes')).toBe(false);
   });
 });
 
@@ -390,3 +350,18 @@ describe('version 2 to version 3', () => {
     expect(out.mode).toBe('dark');
   });
 });
+
+describe('version 3 to version 4', () => {
+  it('only restamps the document, whose shape does not change', () => {
+    const doc = {
+      version: 3,
+      trials: [{ id: 'w1' }],
+      saves: [],
+      layout: {},
+      undockedPanels: {},
+      mode: 'auto',
+    };
+    expect(migrateV3toV4(doc)).toEqual({ ...doc, version: 4 });
+    expect(MIGRATIONS[3]).toBe(migrateV3toV4);
+  });
+});