store.js

import { openDb, openTransaction, awaitTransactionComplete, requestToPromise } from './db.js';

import { LIMITS } from './constants.js';
import { createStamp, migrateNoteStamps, computeTextHash } from './sync-engine.js';

let conn = null;
let listeners = new Set();
let memoryFallback = null;
let persistRequested = false;

function emit(event) {
  for (const handler of listeners) {
    // A faulty subscriber must not be able to break a save: emit() is on
    // saveDraft's synchronous path, which is required never to throw.
    try {
      handler(event);
    } catch (error) {
      console.error('heldnote: event subscriber threw', error);
    }
  }
}

export function __emitForTests(event) {
  emit(event);
}

export function subscribe(handler) {
  listeners.add(handler);
  return () => listeners.delete(handler);
}

export async function open({ dbName } = {}) {
  const result = await openDb({
    name: dbName,
    onVersionChange: handleVersionChange,
  });

  if (result.outcome === 'version-error') {
    throw Object.assign(new Error('This browser holds newer data than this page. Reload to update.'), { code: 'version-mismatch' });
  }

  if (result.outcome !== 'ok') {
    // Reused, not rebuilt: if some caller retries open() after a first failure,
    // rebuilding would throw away everything typed into the memory session so
    // far — which is the one thing this mode exists to hold on to.
    memoryFallback = memoryFallback || newMemoryStore();
    const reason = result.outcome === 'blocked' ? 'blocked' : result.outcome === 'corrupt' ? 'corrupt' : 'unavailable';
    emit({ type: 'storage-unavailable', reason });
    return { available: false, retention: 'unknown', schemaVersion: 1, reason };
  }

  conn = result.db;
  // A previous open() may have failed and left a memory session holding text
  // the user has already typed. Storage working now does not make that text
  // less real, so it is written through to disk before memory mode is turned
  // off — clearing the flag first would strand every one of those notes behind
  // a guard nothing reads any more. A migration that fails leaves memory mode
  // on rather than dropping the notes: honest degradation beats a silent loss.
  if (memoryFallback) {
    try {
      await migrateMemorySessionToDisk();
      memoryFallback = null;
    } catch (error) {
      console.error('heldnote: could not migrate the memory session to storage', error);
      // Close before dropping the handle. Left open and unreachable, this
      // connection would block another tab's upgrade and block deleteDatabase
      // — able to cause the very `blocked` outcome that forces memory mode.
      // close() cannot clean it up later either: it is guarded on `conn`.
      result.db.close();
      conn = null;
      emit({ type: 'storage-unavailable', reason: 'migration-failed' });
      return { available: false, retention: 'unknown', schemaVersion: 1, reason: 'migration-failed' };
    }
  }
  // Fire-and-forget: store-api.md says maintenance is "called at startup", but
  // it was previously only ever reached from a quota-failure retry, so pruning
  // happened exclusively AFTER a write had already failed. open() must not wait
  // for it (boot latency is the whole point of an app that opens instantly),
  // and must not be able to fail because of it — a pruning pass that throws is
  // logged and otherwise ignored, exactly as it is on the retry paths.
  runMaintenance().catch((error) => {
    console.error('heldnote: startup maintenance failed', error);
  });
  return { available: true, retention: 'unknown', schemaVersion: 1 };
}

// Runs when another tab's upgrade forces this connection closed. db.js has
// already called db.close() by the time this is reached, so the handle in
// `conn` is dead. Dropping it is what makes every subsequent call fail through
// activeConn()'s typed `storage-unavailable` error instead of a raw TypeError
// (null) or InvalidStateError (closed handle) from deep inside a transaction.
//
// This deliberately does NOT fail over to memoryFallback: the notes that exist
// are on disk, and an empty in-memory store would make the whole list appear to
// vanish — a far more alarming lie than an honest "storage is not available,
// reload". The event tells the UI to say exactly that.
function handleVersionChange() {
  conn = null;
  emit({ type: 'storage-unavailable', reason: 'version-change' });
}

// The browser fires versionchange only when a second connection requests a
// higher version, which a single-page test cannot stage portably. This calls
// the very handler db.js is wired to, so what the test exercises is the
// production path, not a re-implementation of it.
export function __simulateVersionChangeForTests() {
  handleVersionChange();
}

// Every persisted-path transaction goes through this instead of touching `conn`
// directly. Before open(), and after the connection is force-closed by another
// tab's upgrade (see onVersionChange above), `conn` is null — and
// openTransaction(null, ...) throws a raw TypeError from db.js that no caller
// can branch on. This turns that into the documented StoreError code.
function activeConn() {
  if (!conn) {
    throw Object.assign(new Error('storage is not available'), { code: 'storage-unavailable' });
  }
  return conn;
}


export function isMemoryFallback() {
  return Boolean(memoryFallback);
}

export function hasMemoryOnlyNotes() {
  return memoryOnlyText.size > 0;
}

function metaValue(record) {
  if (!record) return undefined;
  return Object.prototype.hasOwnProperty.call(record, 'value') ? record.value : record;
}

export async function getMeta(key) {
  if (memoryFallback) return metaValue(memoryFallback.meta.get(key));
  const tx = openTransaction(activeConn(), ['meta'], 'readonly');
  return metaValue(await requestToPromise(tx.objectStore('meta').get(key)));
}

export async function setMeta(key, value) {
  if (memoryFallback) {
    memoryFallback.meta.set(key, { key, value });
    return;
  }
  const tx = openTransaction(activeConn(), ['meta'], 'readwrite', { durability: 'strict' });
  tx.objectStore('meta').put({ key, value });
  await awaitTransactionComplete(tx);
}

export async function batchSetMeta(entries) {
  if (memoryFallback) {
    for (const entry of entries) memoryFallback.meta.set(entry.key, { ...entry });
    return;
  }
  const tx = openTransaction(activeConn(), ['meta'], 'readwrite', { durability: 'strict' });
  for (const entry of entries) tx.objectStore('meta').put({ ...entry });
  await awaitTransactionComplete(tx);
}

export async function deleteMeta(key) {
  if (memoryFallback) {
    memoryFallback.meta.delete(key);
    return;
  }
  const tx = openTransaction(activeConn(), ['meta'], 'readwrite', { durability: 'strict' });
  tx.objectStore('meta').delete(key);
  await awaitTransactionComplete(tx);
}

async function ensureDeviceIdInStore(metaStore) {
  const existing = await requestToPromise(metaStore.get('deviceId'));
  const value = metaValue(existing);
  if (typeof value === 'string' && value) return value;
  const id = crypto && typeof crypto.randomUUID === 'function'
    ? crypto.randomUUID()
    : synchronousFallbackDeviceId();
  metaStore.put({ key: 'deviceId', value: id });
  return id;
}

export async function getDeviceId() {
  if (memoryFallback) {
    const existing = metaValue(memoryFallback.meta.get('deviceId'));
    if (existing) return existing;
    const id = crypto && typeof crypto.randomUUID === 'function'
      ? crypto.randomUUID()
      : synchronousFallbackDeviceId();
    memoryFallback.meta.set('deviceId', { key: 'deviceId', value: id });
    return id;
  }
  const tx = openTransaction(activeConn(), ['meta'], 'readwrite', { durability: 'strict' });
  const id = await ensureDeviceIdInStore(tx.objectStore('meta'));
  await awaitTransactionComplete(tx);
  return id;
}

export async function getHLCState() {
  const deviceId = await getDeviceId();
  const existing = await getMeta('hlc');
  if (existing && Number.isFinite(existing.w) && Number.isFinite(existing.c)) {
    return { w: existing.w, c: existing.c, d: deviceId };
  }
  return { w: 0, c: 0, d: deviceId };
}


export async function absorbRemoteStamps(stamps) {
  if (memoryFallback) return { clockWarning: false };
  const tx = openTransaction(activeConn(), ['meta'], 'readwrite', { durability: 'strict' });
  const metaStore = tx.objectStore('meta');
  const deviceId = await ensureDeviceIdInStore(metaStore);
  const stored = metaValue(await requestToPromise(metaStore.get('hlc')));
  const state = stored && Number.isFinite(stored.w) && Number.isFinite(stored.c)
    ? { w: stored.w, c: stored.c, d: deviceId }
    : { w: 0, c: 0, d: deviceId };
  let clockWarning = false;
  const now = Date.now();

  for (const stamp of stamps) {
    if (!stamp || !Number.isFinite(stamp.w) || !Number.isFinite(stamp.c)) continue;
    if (stamp.w - now > 24 * 60 * 60 * 1000) clockWarning = true;
    if (stamp.w > state.w) {
      state.w = stamp.w;
      state.c = stamp.c;
    } else if (stamp.w === state.w) {
      state.c = Math.max(state.c, stamp.c);
    }
  }

  metaStore.put({ key: 'hlc', value: state });
  await awaitTransactionComplete(tx);
  return { clockWarning };
}

async function mutationStamp(metaStore) {
  const deviceId = await ensureDeviceIdInStore(metaStore);
  const storedHlc = metaValue(await requestToPromise(metaStore.get('hlc')));
  const state = storedHlc && Number.isFinite(storedHlc.w) && Number.isFinite(storedHlc.c)
    ? { w: storedHlc.w, c: storedHlc.c, d: deviceId }
    : { w: 0, c: 0, d: deviceId };
  const stamp = createStamp(state);
  metaStore.put({ key: 'hlc', value: state });

  const storedDirty = metaValue(await requestToPromise(metaStore.get('dirtyGen')));
  metaStore.put({ key: 'dirtyGen', value: (Number.isFinite(storedDirty) ? storedDirty : 0) + 1 });
  return stamp;
}

function ensureNoteStamps(record, deviceId) {
  if (!record.stamps) record.stamps = migrateNoteStamps(record.updatedAt, deviceId);
  return record.stamps;
}

export async function close() {
  if (conn) {
    conn.close();
    conn = null;
  }
  memoryFallback = null;
  listeners = new Set();
  // Revision bookkeeping describes the connection that is going away. Keeping
  // it would let flush() answer "already durable" from a previous database
  // after a delete/reopen or an import that reuses note ids.
  draftQueues.clear();
  revCounters.clear();
  durableRevs.clear();
  lastVersionText.clear();
  memoryOnlyText.clear();
  versionCommitsStopped = false;
  persistRequested = false;
}

async function requestPersistenceOnce() {
  if (persistRequested) return;
  persistRequested = true;
  if (!navigator.storage || !navigator.storage.persist) return;
  const granted = await navigator.storage.persist().catch(() => false);
  emit({ type: 'retention-changed', retention: granted ? 'persistent' : 'best-effort' });
}


let fallbackDeviceId = null;

function synchronousFallbackDeviceId() {
  if (fallbackDeviceId) return fallbackDeviceId;
  try {
    fallbackDeviceId = localStorage.getItem('heldnote-device-id-fallback');
    if (!fallbackDeviceId) {
      fallbackDeviceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
      localStorage.setItem('heldnote-device-id-fallback', fallbackDeviceId);
    }
  } catch (_e) {
    fallbackDeviceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
  }
  return fallbackDeviceId;
}

function newId() {
  if (crypto && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}-${synchronousFallbackDeviceId()}`;
}

function toNoteSummary(record) {
  return {
    id: record.id,
    title: record.title,
    updatedAt: record.updatedAt,
    pinned: record.pinKey === 1,
    deletedAt: record.isDeleted === 1 ? record.deletedAt : null,
  };
}

export async function createNote() {
  if (memoryFallback) return memoryCreateNote();
  const id = newId();
  const now = Date.now();

  const noteRecord = {
    id, title: 'Untitled.txt', createdAt: now, updatedAt: now, localRev: 0, noteRev: 1,
    pinned: false, pinKey: 0, isDeleted: 0,
  };
  const draftRecord = { noteId: id, text: '', localRev: 0, savedAt: now, byteLength: 0 };

  const tx = openTransaction(activeConn(), ['notes', 'drafts', 'meta'], 'readwrite', { durability: 'strict' });
  const stamp = await mutationStamp(tx.objectStore('meta'));
  noteRecord.stamps = {
    text: { ...stamp }, title: { ...stamp },
    pinned: { ...stamp }, lifecycle: { ...stamp },
  };
  tx.objectStore('notes').put(noteRecord);
  tx.objectStore('drafts').put(draftRecord);
  await awaitTransactionComplete(tx);
  emit({ type: 'sync-dirty', noteId: id });

  return { id, title: 'Untitled.txt', text: '', createdAt: now, updatedAt: now, pinned: false, deletedAt: null, localRev: 0 };
}

export async function listNotes({ query, includeTrashed = false, limit, before } = {}) {
  if (memoryFallback) return memoryListNotes({ query, includeTrashed, limit, before });
  const tx = openTransaction(activeConn(), ['notes', 'drafts'], 'readonly');
  const notesStore = tx.objectStore('notes');
  const draftsStore = tx.objectStore('drafts');
  const results = [];
  const lowerQuery = query ? query.toLowerCase() : null;

  await new Promise((resolve, reject) => {
    const req = notesStore.openCursor();
    req.onsuccess = async () => {
      const cursor = req.result;
      if (!cursor) { resolve(); return; }
      const record = cursor.value;
      const isTrashed = record.isDeleted === 1;
      if (!includeTrashed && isTrashed) {
        cursor.continue();
        return;
      }

      // Matching covers title AND body text (PRD requirement). The title
      // check is free (already in hand from the cursor); only fall through to
      // a second store read of the draft's body when the title alone doesn't
      // satisfy the query, so a title match never pays for a drafts lookup.
      // `record.title || ''` is belt-and-braces against a record whose title is
      // not a string. parseImportFile now rejects such a file outright, but a
      // record written before that validation existed (or by any path not yet
      // imagined) would otherwise throw here — inside an async cursor handler,
      // where the throw becomes an unhandled rejection rather than reaching the
      // surrounding reject(), leaving listNotes() pending forever. A hung note
      // list is a far worse outcome than an untitled note failing to match.
      let matchesQuery = !lowerQuery || String(record.title || '').toLowerCase().includes(lowerQuery);
      if (!matchesQuery) {
        // Explicit try/catch: this handler is async, so a rejection from the
        // awaited request would otherwise become an unhandled rejection
        // instead of reaching the surrounding Promise's reject() — leaving
        // listNotes()'s own await pending forever instead of failing loudly.
        try {
          const draftRecord = await requestToPromise(draftsStore.get(record.id));
          matchesQuery = !!draftRecord && String(draftRecord.text || '').toLowerCase().includes(lowerQuery);
        } catch (error) {
          reject(error);
          return;
        }
      }

      if (matchesQuery) {
        results.push(toNoteSummary(record));
      }
      cursor.continue();
    };
    req.onerror = () => reject(req.error);
  });

  results.sort((a, b) => {
    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
    return b.updatedAt - a.updatedAt;
  });

  const sliced = before ? results.filter((r) => r.updatedAt < before) : results;
  return typeof limit === 'number' ? sliced.slice(0, limit) : sliced;
}

const revCounters = new Map();
const durableRevs = new Map();

export async function getNote(id) {
  if (memoryFallback) return memoryGetNote(id);
  const tx = openTransaction(activeConn(), ['notes', 'drafts'], 'readonly');
  const noteRecord = await requestToPromise(tx.objectStore('notes').get(id));
  const draftRecord = await requestToPromise(tx.objectStore('drafts').get(id));
  if (!noteRecord || !draftRecord) {
    throw Object.assign(new Error(`note ${id} not found`), { code: 'not-found' });
  }
  revCounters.set(id, Math.max(revCounters.get(id) || 0, draftRecord.localRev));
  durableRevs.set(id, Math.max(durableRevs.get(id) || 0, draftRecord.localRev));
  return {
    id: noteRecord.id,
    title: noteRecord.title,
    text: draftRecord.text,
    createdAt: noteRecord.createdAt,
    updatedAt: noteRecord.updatedAt,
    pinned: noteRecord.pinKey === 1,
    deletedAt: noteRecord.isDeleted === 1 ? noteRecord.deletedAt : null,
    localRev: draftRecord.localRev,
  };
}


async function updateNoteFields(id, fields, stampField) {
  if (memoryFallback) return memoryUpdateNoteFields(id, fields);
  const tx = openTransaction(activeConn(), ['notes', 'meta'], 'readwrite', { durability: 'strict' });
  const store = tx.objectStore('notes');
  const record = await requestToPromise(store.get(id));
  if (!record) throw Object.assign(new Error(`note ${id} not found`), { code: 'not-found' });
  const stamp = await mutationStamp(tx.objectStore('meta'));
  ensureNoteStamps(record, stamp.d)[stampField] = stamp;

  Object.assign(record, fields);
  record.noteRev = (record.noteRev || 0) + 1;
  store.put(record);
  await awaitTransactionComplete(tx);
  emit({ type: 'note-changed', noteId: id });
  emit({ type: 'sync-dirty', noteId: id });
}

export async function setPinned(id, on) {
  await updateNoteFields(id, { pinned: on, pinKey: on ? 1 : 0 }, 'pinned');
}

export async function trashNote(id) {
  await updateNoteFields(id, { isDeleted: 1, deletedAt: Date.now() }, 'lifecycle');
}

// The title is a user-set filename (e.g. "notes.md") — independent of the text,
// never derived from it (see docs/filename-plan.md). This is the ONLY writer of
// title after createNote; the draft and restore paths deliberately leave it
// alone. Sanitizing here (not just in the UI) makes the store the single choke
// point: path separators and control characters can never reach a record.
export async function renameNote(id, title) {
  if (typeof title !== 'string') {
    throw Object.assign(new Error('title must be a string'), { code: 'invalid-title' });
  }
  const clean = title.replace(/[/\\\u0000-\u001F]/g, '').trim().slice(0, 200);
  if (!clean) {
    throw Object.assign(new Error('title must not be empty'), { code: 'invalid-title' });
  }
  // updatedAt bumps on purpose: a rename is a deliberate modification, and the
  // list sorts by updatedAt. localRev is NOT touched — it is the draft-revision
  // counter, and moving it here would corrupt flush()'s durability answers.

  await updateNoteFields(id, { title: clean, updatedAt: Date.now() }, 'title');
}

export async function restoreNote(id) {
  if (memoryFallback) return memoryRestoreNote(id);

  const tx = openTransaction(activeConn(), ['notes', 'meta'], 'readwrite', { durability: 'strict' });
  const noteStore = tx.objectStore('notes');
  const record = await requestToPromise(noteStore.get(id));
  if (!record) throw Object.assign(new Error(`note ${id} not found`), { code: 'not-found' });
  const stamp = await mutationStamp(tx.objectStore('meta'));
  ensureNoteStamps(record, stamp.d).lifecycle = stamp;

  record.isDeleted = 0;
  delete record.deletedAt;
  record.noteRev = (record.noteRev || 0) + 1;
  noteStore.put(record);
  await awaitTransactionComplete(tx);
  emit({ type: 'note-changed', noteId: id });
  emit({ type: 'sync-dirty', noteId: id });
}

// Purges every note currently in the trash. Deliberately a loop over
// purgeNote rather than one wide transaction: purgeNote is what writes a
// note's tombstone in the SAME transaction as its deletion, and that atomicity
// is the whole reason a purge propagates to other devices instead of the note
// resurrecting. One failure (a quota fault, a note purged from another tab
// mid-loop) must not abandon the rest, so failures are collected and the
// caller is told what actually went; a partial empty is still a correct state.
export async function emptyTrash() {
  const all = await listNotes({ includeTrashed: true, limit: 100000 });
  const trashed = all.filter((note) => note.deletedAt != null);
  const purged = [];
  const failed = [];
  for (const note of trashed) {
    try {
      await purgeNote(note.id);
      purged.push(note.id);
    } catch (error) {
      failed.push({ id: note.id, error });
    }
  }
  return { purged, failed };
}

export async function purgeNote(id) {
  if (memoryFallback) return memoryPurgeNote(id);

  const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions', 'meta'], 'readwrite', { durability: 'strict' });
  const stamp = await mutationStamp(tx.objectStore('meta'));
  tx.objectStore('notes').delete(id);
  tx.objectStore('drafts').delete(id);
  tx.objectStore('meta').put({ key: `tombstone:${id}`, id, stamp });
  const versionsStore = tx.objectStore('versions');
  await new Promise((resolve, reject) => {
    const range = IDBKeyRange.bound([id, -Infinity], [id, Infinity]);
    const req = versionsStore.openCursor(range);
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor) { resolve(); return; }
      cursor.delete();
      cursor.continue();
    };
    req.onerror = () => reject(req.error);
  });

  await awaitTransactionComplete(tx);
  emit({ type: 'note-changed', noteId: id });
  emit({ type: 'sync-dirty', noteId: id });
}

// --- draft layer: serialized, coalescing writer -----------------------------
//
// At most one draft transaction per note is in flight at any time. While one is
// running, further keystrokes only replace the queued payload, so the writer
// always persists the newest text and never a stale intermediate one. Because
// an accepted revision is written on the very next turn (no debounce), the
// wall-clock budget of LIMITS.DRAFT_FLUSH_MAX_MS covers the whole path from
// saveDraft() to the transaction's `complete` event.

const draftQueues = new Map(); // noteId -> { pendingText, pendingRev, inFlight, waiters, lastFailure }

// --- quota exhaustion: prune-retry-once, then degrade -----------------------
//
// A quota-class error (QuotaExceededError, or the AbortError the fault-
// injection seam produces) gets exactly one prune-and-retry before this code
// gives up on the attempt in front of it. The two call sites degrade
// differently because the two failures mean different things:
//
//   - the DRAFT path is the one that must never silently stop working, so a
//     draft write that still fails after prune-and-retry goes memory-only for
//     that note: the in-memory buffer (memoryOnlyText) keeps the text
//     available for copy/export, ordinary 'saved' events stop, and a
//     'memory-only' event fires instead.
//   - the VERSION-COMMIT path is expendable: drafts must keep saving even
//     after history stops. A version write that still fails after retry sets
//     versionCommitsStopped so no further commitVersion() call even attempts
//     a write (it returns null immediately), and a 'quota-warning' fires once
//     at the moment history commits stop.
//
// memoryOnlyText is connection-scoped like durableRevs etc. and is cleared in
// close(); versionCommitsStopped is a whole-connection latch (once history
// commits are known to be unsalvageable for the current storage pressure,
// there is no per-note distinction worth making) and is reset in close() too.

const memoryOnlyText = new Map(); // noteId -> last text that could not be made durable
let versionCommitsStopped = false;

export function getMemoryOnlyText(noteId) {
  return memoryOnlyText.get(noteId);
}

function isQuotaError(error) {
  return Boolean(error) && (error.name === 'QuotaExceededError' || error.name === 'AbortError');
}

// LIMITS.MAX_NOTE_SIZE_BYTES is the "tested maximum note size" the design
// adopted in place of the earlier "no size limit" position. It was defined but
// referenced nowhere, which is the worst of both worlds: a documented guarantee
// with no enforcement behind it. Enforced on the draft path only — that is the
// one path a user can drive past the cap by typing (or pasting), and it is the
// path where refusing early keeps a single oversized note from being the reason
// every other note stops saving.
function assertWithinSizeLimit(noteId, byteLength) {
  if (byteLength <= LIMITS.MAX_NOTE_SIZE_BYTES) return;
  throw Object.assign(
    new Error(`note ${noteId} is ${byteLength} bytes, over the ${LIMITS.MAX_NOTE_SIZE_BYTES}-byte maximum`),
    { code: 'note-too-large', byteLength, limit: LIMITS.MAX_NOTE_SIZE_BYTES },
  );
}

function queueFor(noteId) {
  let q = draftQueues.get(noteId);
  if (!q) {
    q = { pendingText: null, pendingRev: null, inFlight: false, restoring: false, waiters: [], lastFailure: null };
    draftQueues.set(noteId, q);
  }
  return q;
}

export function saveDraft(id, text) {
  if (memoryFallback) return memorySaveDraft(id, text);
  const nextRev = (revCounters.get(id) || 0) + 1;
  revCounters.set(id, nextRev);

  const q = queueFor(id);
  q.pendingText = text;
  q.pendingRev = nextRev;
  // A newer payload is on its way, so an earlier failure no longer decides
  // anything: the write about to run can still make this text durable.
  q.lastFailure = null;

  emit({ type: 'saving', noteId: id, requestedRev: nextRev });

  // While a restore holds the lock, the payload is only queued: restoreVersion
  // starts the write itself once its own transaction has committed, so this
  // text lands on top of the restored text instead of racing it.
  if (!q.inFlight && !q.restoring) {
    runDraftWrite(id);
  }

  return nextRev;
}

function resolveWaiters(noteId, receipt) {
  const q = queueFor(noteId);
  q.lastFailure = receipt.error ? { rev: receipt.requestedRev, error: receipt.error } : null;
  const remaining = [];
  for (const waiter of q.waiters) {
    if (receipt.durableRev >= waiter.rev) {
      // The revision this caller asked about is durable, so the promise is
      // kept even if some later revision in the same batch failed.
      waiter.resolve(receipt);
    } else if (receipt.error && receipt.requestedRev >= waiter.rev) {
      // The write that failed already carried this waiter's text (coalescing
      // means a newer payload supersedes the older one), so nothing still
      // queued can make it durable. Reject rather than wait forever.
      waiter.reject(receipt.error);
    } else {
      remaining.push(waiter);
    }
  }
  q.waiters = remaining;
}

export function flush(noteId, throughRev) {
  const q = queueFor(noteId);
  const durableRev = durableRevs.get(noteId) || 0;
  if (durableRev >= throughRev) {
    // Already durable: no future transaction is left to wait on, and waiters
    // are only ever settled by one completing.
    return Promise.resolve({ noteId, requestedRev: throughRev, durableRev, completedAt: Date.now() });
  }
  if (q.lastFailure && q.lastFailure.rev >= throughRev) {
    // The write carrying this revision already failed and no newer payload has
    // been queued since, so waiting would never end.
    return Promise.reject(q.lastFailure.error);
  }
  return new Promise((resolve, reject) => {
    q.waiters.push({ rev: throughRev, resolve, reject });
  });
}

async function runDraftWrite(noteId) {
  const q = queueFor(noteId);
  q.inFlight = true;

  // Re-checked once per iteration: an iteration that started before a restore
  // took the lock is safe (its transaction was created first, so it commits
  // ahead of the restore and its text is what the restore's draft read sees),
  // but a *new* iteration started under the lock would create its transaction
  // after that draft read and before the restore's write, which is exactly the
  // interleaving that loses text. Exiting here leaves the payload in
  // pendingText with inFlight false, which is what restoreVersion's finally
  // expects to find.
  while (q.pendingText !== null && !q.restoring) {
    const text = q.pendingText;
    const rev = q.pendingRev;
    // Read at dequeue, before any await, so it names the generation this write
    // belongs to. restoreVersion() bumps the generation before opening its own
    // transaction; the comparison below is what stops a write dequeued under
    // the old generation from publishing itself over a restore.
    const generationAtQueue = currentGeneration(noteId);
    q.pendingText = null;
    q.pendingRev = null;

    const now = Date.now();

    let receipt;
    try {
      // Kept inside the try: a throw here (a non-string payload reaching
      // TextEncoder, say) would otherwise escape the loop, skipping both
      // resolveWaiters and the inFlight reset, and wedge this note's queue.
      const byteLength = new TextEncoder().encode(text).length;

      if (currentGeneration(noteId) !== generationAtQueue) {
        throw Object.assign(new Error('stale write superseded by a restore'), { code: 'stale-generation' });
      }

      // The size cap is enforced HERE — after coalescing, before any
      // transaction is opened — so nothing partial is ever written and only
      // the newest text is ever measured. Throwing (rather than returning)
      // routes this through the one place that already owns receipt building,
      // waiter settlement and the inFlight reset for every other failure.
      //
      // It sits BELOW the generation fence deliberately: a payload a restore
      // has already superseded is not the user's current text, so stashing it
      // in memoryOnlyText and announcing "not saved" would report a problem
      // about text nobody is looking at any more.
      assertWithinSizeLimit(noteId, byteLength);

      const tx = openTransaction(activeConn(), ['notes', 'drafts', 'meta'], 'readwrite', { durability: 'strict' });
      // The note record is read BEFORE the draft is written. Issued the other
      // way round, a get() that fails (or a note deleted or replaced by an
      // import out from under this writer) still leaves the drafts.put()
      // issued, and nothing aborts the transaction — so it commits, stranding
      // a draft record for a note that no longer exists, or overwriting
      // freshly imported text with a stale pre-import draft. Throwing before
      // the put is issued means the transaction carries no change at all.
      const noteStore = tx.objectStore('notes');
      const noteRecord = await requestToPromise(noteStore.get(noteId));
      if (!noteRecord) {
        throw Object.assign(new Error(`note ${noteId} not found`), { code: 'not-found' });
      }
      tx.objectStore('drafts').put({ noteId, text, localRev: rev, savedAt: now, byteLength });
      // title is deliberately NOT touched: it is a user-set filename now
      // (renameNote is its only writer). A draft write that rewrote it would
      // silently revert a rename on the very next keystroke.

      const stamp = await mutationStamp(tx.objectStore('meta'));
      ensureNoteStamps(noteRecord, stamp.d).text = stamp;

      noteRecord.updatedAt = now;
      noteRecord.localRev = rev;
      noteRecord.noteRev = (noteRecord.noteRev || 0) + 1;
      noteStore.put(noteRecord);
      await awaitTransactionComplete(tx);

      // Monotonic: a restore may already have published a higher revision, and
      // durableRevs is what flush() trusts to answer "already on disk".
      const durableRev = Math.max(durableRevs.get(noteId) || 0, rev);
      durableRevs.set(noteId, durableRev);
      memoryOnlyText.delete(noteId);
      receipt = { noteId, requestedRev: rev, durableRev, completedAt: Date.now() };

      emit({ type: 'saved', ...receipt });
      emit({ type: 'sync-dirty', noteId });
    } catch (error) {
      if (error && error.code === 'note-too-large') {
        // Deliberately NOT truncated and NOT dropped: the text the user typed
        // stays in the visible buffer (memoryOnlyText, the same channel the
        // quota path uses, so copy/export still reach it) and the interface is
        // told plainly that it is not being stored. Silently accepting it
        // would be the dishonest option; silently cutting it would be worse.
        memoryOnlyText.set(noteId, text);
        receipt = { noteId, requestedRev: rev, durableRev: durableRevs.get(noteId) || 0, completedAt: Date.now(), error };
        emit({ type: 'quota-warning', noteId, reason: 'note-too-large' });
        emit({ type: 'memory-only', noteId, text });
      } else if (isQuotaError(error)) {
        // One prune-and-retry, then the note this text belongs to goes
        // memory-only rather than looping forever against storage that is
        // still full.
        await runMaintenance().catch(() => {});
        if (currentGeneration(noteId) !== generationAtQueue) {
          // A restore won the note while maintenance ran. That is a
          // supersession, not a quota failure: the restore's text is what is
          // now current, so this stale payload must not overwrite it, and it
          // must not be reported memory-only either (memory-only exists to
          // preserve text that is otherwise about to be lost, and this text
          // is not — the restore's checkpoint already preserved it). Falls
          // through to the same save-failed reporting the generation fence
          // uses on the first attempt.
          receipt = { noteId, requestedRev: rev, durableRev: durableRevs.get(noteId) || 0, completedAt: Date.now(), error };
          emit({ type: 'save-failed', ...receipt });
        } else {
          try {
            // Recomputed rather than reused: byteLength above is scoped to
            // the outer try block and is not visible here.
            const retryByteLength = new TextEncoder().encode(text).length;

            const retryTx = openTransaction(activeConn(), ['notes', 'drafts', 'meta'], 'readwrite', { durability: 'strict' });
            // Same read-before-write ordering as the first attempt, for the
            // same reason.
            const retryNoteStore = retryTx.objectStore('notes');
            const retryNoteRecord = await requestToPromise(retryNoteStore.get(noteId));
            if (!retryNoteRecord) {
              throw Object.assign(new Error(`note ${noteId} not found`), { code: 'not-found' });
            }
            retryTx.objectStore('drafts').put({ noteId, text, localRev: rev, savedAt: now, byteLength: retryByteLength });
            // Same rule as the first attempt: the user-set title is not touched.

            const retryStamp = await mutationStamp(retryTx.objectStore('meta'));
            ensureNoteStamps(retryNoteRecord, retryStamp.d).text = retryStamp;

            retryNoteRecord.updatedAt = now;
            retryNoteRecord.localRev = rev;
            retryNoteRecord.noteRev = (retryNoteRecord.noteRev || 0) + 1;
            retryNoteStore.put(retryNoteRecord);
            await awaitTransactionComplete(retryTx);

            const durableRev = Math.max(durableRevs.get(noteId) || 0, rev);
            durableRevs.set(noteId, durableRev);
            memoryOnlyText.delete(noteId);
            receipt = { noteId, requestedRev: rev, durableRev, completedAt: Date.now() };

            emit({ type: 'saved', ...receipt });
            emit({ type: 'sync-dirty', noteId });
          } catch (retryError) {
            memoryOnlyText.set(noteId, text);
            receipt = { noteId, requestedRev: rev, durableRev: durableRevs.get(noteId) || 0, completedAt: Date.now(), error: retryError };
            emit({ type: 'memory-only', noteId, text });
          }
        }
      } else {
        receipt = { noteId, requestedRev: rev, durableRev: durableRevs.get(noteId) || 0, completedAt: Date.now(), error };
        emit({ type: 'save-failed', ...receipt });
      }
    }

    resolveWaiters(noteId, receipt);
  }

  q.inFlight = false;
}

// --- version layer: snapshot the current draft into an immutable history ---
//
// commitVersion() flushes the draft to durability first (so sourceRev always
// names a durable revision), then snapshots the draft's current text into the
// versions store, deduping against the last-committed text so unchanged notes
// don't accumulate no-op versions. lastVersionText is connection-scoped (like
// revCounters/durableRevs) and is cleared in close().

const lastVersionText = new Map(); // noteId -> text of the newest committed version, for dedup

export async function commitVersion(id) {
  if (memoryFallback) return memoryCommitVersion(id);
  const q = queueFor(id);
  // A restore already in progress will itself commit the next version (its
  // own write, or whatever runs after it in the finally block), so there is
  // nothing useful for a routine commit to do — skip rather than contend.
  // This mirrors restoreVersion's own "restore-in-progress" check but returns
  // null instead of throwing: commitVersion is polled routinely by an idle
  // timer (Task 18) and null already means "nothing to commit right now".
  if (q.restoring) return null;
  // Once a version write has failed a prune-and-retry, history commits are
  // considered permanently unsalvageable for this connection: draft writes
  // must keep working, but there is no point contending for the lock or
  // hitting storage again on every subsequent commitVersion() call.
  if (versionCommitsStopped) return null;

  const currentRev = revCounters.get(id) || 0;
  if (currentRev > 0) {
    await flush(id, currentRev).catch(() => {});
  }
  // Second check-and-set, synchronous (no await between them), exactly like
  // restoreVersion's own lock acquisition: a restore (or another commit) may
  // have started during the flush above, and this is the point that must not
  // race it. nextSeq() + the write below are the vulnerable "allocate a seq,
  // then write a version record in a later transaction" shape restoreVersion's
  // lock exists to fence — commitVersion has the same shape and reuses the
  // same q.restoring flag rather than a second one.
  //
  // The flush() above must stay OUTSIDE the lock (it needs the draft writer to
  // keep running, which the lock suppresses), but the draft read must be INSIDE
  // it. Read before the lock, a restore could start and finish in the gap, and
  // this commit would then snapshot the pre-restore text — writing a spurious
  // duplicate of a state the restore had already checkpointed.
  if (q.restoring) return null;
  q.restoring = true;
  try {
    const draftTx = openTransaction(activeConn(), ['drafts'], 'readonly');
    const draft = await requestToPromise(draftTx.objectStore('drafts').get(id));
    // No draft record means no note: say so with a code callers can branch on
    // rather than letting draft.text raise a bare TypeError.
    if (!draft) {
      throw Object.assign(new Error(`note ${id} not found`), { code: 'not-found' });
    }

    if (lastVersionText.get(id) === draft.text) {
      return null;
    }

    // nextSeq() also opens a transaction scoped to 'versions', so it is
    // exposed to exactly the same fault (real quota pressure or the
    // fault-injection seam) as the write below — a quota-class failure can
    // surface there just as easily as on the put() itself. Both are folded
    // into one prune-and-retry-once attempt: on failure, anything already
    // computed (seq/at/byteLength) is stale relative to the post-prune state,
    // so the retry recomputes them rather than reusing values from a
    // transaction that never committed.
    let seq;
    let at;
    let byteLength;
    try {
      seq = await nextSeq(id);
      at = Date.now();
      byteLength = new TextEncoder().encode(draft.text).length;
      const writeTx = openTransaction(activeConn(), ['versions'], 'readwrite', { durability: 'strict' });
      writeTx.objectStore('versions').put({ noteId: id, seq, at, sourceRev: draft.localRev, text: draft.text, byteLength });
      await awaitTransactionComplete(writeTx);
    } catch (error) {
      if (!isQuotaError(error)) throw error;
      await runMaintenance().catch(() => {});
      try {
        seq = await nextSeq(id);
        at = Date.now();
        byteLength = new TextEncoder().encode(draft.text).length;
        const retryTx = openTransaction(activeConn(), ['versions'], 'readwrite', { durability: 'strict' });
        retryTx.objectStore('versions').put({ noteId: id, seq, at, sourceRev: draft.localRev, text: draft.text, byteLength });
        await awaitTransactionComplete(retryTx);
      } catch (retryError) {
        versionCommitsStopped = true;
        emit({ type: 'quota-warning', noteId: id, reason: 'version-commits-stopped' });
        return null;
      }
    }

    lastVersionText.set(id, draft.text);
    await requestPersistenceOnce();
    return { seq, at, sourceRev: draft.localRev, size: byteLength };
  } finally {
    // Released whether the write succeeded or threw, same discipline as
    // restoreVersion's finally: leaving it set would wedge the note's draft
    // queue (saveDraft's launch guard checks q.restoring too) permanently.
    q.restoring = false;
    // Same shape as restoreVersion's finally, and for the same reason: text
    // typed while the lock was held was accepted (coalesced into
    // pendingText) but never started, because saveDraft's launch guard
    // checks q.restoring. Left alone, it would sit stuck until some later,
    // unrelated saveDraft() call happened to arrive and re-trigger that
    // guard. This task's prune-and-retry can hold the lock across an extra
    // runMaintenance() pass plus a retried write — meaningfully longer than
    // a single write — which widens that window, so it is started here
    // rather than left to chance.
    if (q.pendingText !== null && !q.inFlight) {
      runDraftWrite(id);
    }
  }
}

// Ordered by the versions store's OWN primary key ([noteId, seq]), never by the
// by_note_at index. The index is ordered by `at`, so its newest record is the
// highest `seq` only while Date.now() happens to be monotonic for this note.
// Two ordinary events break that coincidence, and both silently destroy data,
// because a reused seq means put() overwrites an existing version record:
//   - a clock rollback (NTP correction, manual change) makes the next version's
//     `at` smaller than the previous one's, so the previous record stays
//     "newest" by index order and its seq is handed out again;
//   - importing a backup whose newest version carries an `at` ahead of the
//     local clock leaves that record permanently "newest" by index order, so
//     every subsequent local commit computes the same seq.
// The primary key range below is the seq order itself, so neither matters.
async function nextSeq(noteId) {
  const tx = openTransaction(activeConn(), ['versions'], 'readonly');
  const range = IDBKeyRange.bound([noteId, -Infinity], [noteId, Infinity]);
  let maxSeq = 0;
  await new Promise((resolve, reject) => {
    const req = tx.objectStore('versions').openCursor(range, 'prev');
    req.onsuccess = () => {
      const cursor = req.result;
      if (cursor) { maxSeq = cursor.value.seq; }
      resolve();
    };
    req.onerror = () => reject(req.error);
  });
  return maxSeq + 1;
}

export async function listVersions(id, { before, limit } = {}) {
  if (memoryFallback) return memoryListVersions(id, { before, limit });
  const tx = openTransaction(activeConn(), ['versions'], 'readonly');
  const index = tx.objectStore('versions').index('by_note_at');
  const upper = before ? [id, before.at, before.seq] : [id, Infinity, Infinity];
  const range = IDBKeyRange.bound([id, -Infinity, -Infinity], upper, false, Boolean(before));
  const results = [];

  await new Promise((resolve, reject) => {
    const req = index.openCursor(range, 'prev');
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor || (limit && results.length >= limit)) { resolve(); return; }

      const { seq, at, sourceRev, byteLength, kind, protectedUntil, lostFields } = cursor.value;
      results.push({ seq, at, sourceRev, size: byteLength, kind, protectedUntil, lostFields });
      cursor.continue();
    };
    req.onerror = () => reject(req.error);
  });

  return results;
}

export async function getVersion(id, seq) {
  if (memoryFallback) return memoryGetVersion(id, seq);
  const tx = openTransaction(activeConn(), ['versions'], 'readonly');
  const record = await requestToPromise(tx.objectStore('versions').get([id, seq]));
  if (!record) throw Object.assign(new Error(`version ${id}/${seq} not found`), { code: 'not-found' });
  return { seq: record.seq, at: record.at, sourceRev: record.sourceRev, text: record.text };
}

// --- restore: fenced, and never destructive --------------------------------
//
// Restoring is an edit, not a rewind: it adds versions and never removes one.
// Three hazards are handled here.
//
// A restore runs *two* transactions, and they are different ordering points.
// Keeping them straight is the whole safety argument:
//
//   - the DRAFT-READ transaction (readonly, in runRestore) decides what the
//     checkpoint captures: it sees every draft write committed before it;
//   - the WRITE transaction (readwrite, later in runRestore) decides what ends
//     up on disk: IndexedDB commits same-scope transactions in creation order,
//     so every draft write whose transaction was created earlier commits first
//     and is then overwritten by this one.
//
// A draft write is only safe when it is on the correct side of BOTH. Created
// before the draft read: its text is checkpointed into history, and the restore
// still wins the draft record. Created after the write transaction: it is an
// ordinary post-restore edit. Created *between* them, however, it is neither
// checkpointed nor kept — it commits, is reported as saved, and is then
// silently overwritten. That is the window this code has to keep empty.
//
// Three hazards follow from that:
//
// 1. Text drafted but never versioned would be overwritten, so the draft read
//    snapshots it as a pre-restore checkpoint version first.
// 2. A draft write already in flight when the lock is taken is safe by
//    construction: its transaction predates both of the restore's.
// 3. Any write that starts *after* the lock is taken could land in the unsafe
//    window between them. The `restoring` lock keeps that window empty from
//    both directions: saveDraft will not launch a new write while it is held,
//    and runDraftWrite's loop re-checks it each iteration so an already-running
//    loop stops draining instead of starting further transactions. Text is
//    still accepted and coalesced throughout; the finally block below runs
//    whatever accumulated once the restore is durable, so the edit becomes the
//    next revision on top of the restored text instead of racing it.
//
// The generation counter is kept as a second line of defence for a write that
// somehow reaches runDraftWrite across a restore boundary; note that with the
// current dequeue-then-check ordering it is not expected to fire (see report).

const noteGeneration = new Map(); // noteId -> generation counter, bumped by each restore

function currentGeneration(noteId) {
  return noteGeneration.get(noteId) || 0;
}

export async function restoreVersion(id, seq) {
  if (memoryFallback) return memoryRestoreVersion(id, seq);
  const target = await getVersion(id, seq);

  const currentRev = revCounters.get(id) || 0;
  if (currentRev > 0) {
    await flush(id, currentRev).catch(() => {});
  }

  const q = queueFor(id);
  // Taking the lock is the serialization point for concurrent restores. The
  // check and the set are adjacent and synchronous, so whichever restore's
  // flush() resolves first wins it outright; a second restore rejects rather
  // than racing. Two concurrent restores would otherwise both read currentRev
  // and both call nextSeq() before either opened its write transaction, so
  // they could compute the same seq and the later put() would overwrite the
  // earlier one's checkpoint — deleting the artifact this function exists to
  // create. The lock cannot be taken any earlier than this: the flush() above
  // needs the draft writer to keep running, which the lock now suppresses.
  if (q.restoring) {
    throw Object.assign(new Error('a restore is already in progress for this note'), { code: 'restore-in-progress' });
  }
  // Held from here until this restore is durable. Everything after this point
  // runs inside try/finally: leaving the lock set would wedge the note's queue
  // permanently, so a failed restore must still release it.
  q.restoring = true;
  noteGeneration.set(id, currentGeneration(id) + 1);

  try {
    // pendingText is deliberately left alone. Whatever is queued — typed before
    // the lock or during the restore — is deferred, not discarded, and the
    // finally below runs it on top of the restored text.
    return await runRestore(id, target, currentRev);
  } finally {
    q.restoring = false;
    // Text typed while the lock was held was queued but never started; run it
    // now, as the next revision on top of the restored text. Fire and forget,
    // exactly as saveDraft does. If a write is somehow still in flight, its own
    // loop will pick the payload up, so starting a second one would be wrong.
    if (q.pendingText !== null && !q.inFlight) {
      runDraftWrite(id);
    }
  }
}

async function runRestore(id, target, currentRev) {
  const draftTx = openTransaction(activeConn(), ['drafts'], 'readonly');
  const currentDraft = await requestToPromise(draftTx.objectStore('drafts').get(id));
  // A note purged out from under the restore leaves no draft record. Guarding
  // turns what would be a bare TypeError on currentDraft.text into the typed
  // error callers can branch on — matching commitVersion and the memory path.
  if (!currentDraft) {
    throw Object.assign(new Error(`note ${id} not found`), { code: 'not-found' });
  }

  const newestVersions = await listVersions(id, { limit: 1 });
  const newestVersionText = newestVersions.length ? (await getVersion(id, newestVersions[0].seq)).text : undefined;
  const needsCheckpoint = currentDraft.text !== newestVersionText;

  const nextRev = currentRev + 1;
  // Monotonic: currentRev was read before this restore's async work, so edits
  // that arrived meanwhile may already have claimed higher revisions. Writing
  // nextRev back unconditionally would hand the next saveDraft an already-used
  // number, and flush() for that number could then resolve off the fast path
  // for text that has not been written.
  revCounters.set(id, Math.max(revCounters.get(id) || 0, nextRev));
  // durableRevs is NOT set here. flush()'s fast path treats durableRevs as the
  // sole authority for "this revision is on disk", so setting it before the
  // transaction below actually commits would let a concurrent flush(id, nextRev)
  // resolve for a restore that hasn't happened yet. It is set after the
  // transaction completes instead, matching every other durableRevs write here.

  const baseSeq = await nextSeq(id);
  const checkpointSeq = needsCheckpoint ? baseSeq : null;
  const restoredSeq = needsCheckpoint ? baseSeq + 1 : baseSeq;

  const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions', 'meta'], 'readwrite', { durability: 'strict' });

  // Read the note record FIRST, for the same reason runDraftWrite does: a note
  // purged out from under this restore makes the dereference below throw, and a
  // throw from an async continuation does not abort an IndexedDB transaction —
  // so any put() already issued would still commit, writing checkpoint and
  // restored versions for a note that no longer exists. Reading first means a
  // missing note aborts with the transaction still carrying nothing.
  const noteStore = tx.objectStore('notes');
  const noteRecord = await requestToPromise(noteStore.get(id));
  if (!noteRecord) {
    throw Object.assign(new Error(`note ${id} not found`), { code: 'not-found' });
  }

  const versionsStore = tx.objectStore('versions');

  const at = Date.now();
  if (needsCheckpoint) {
    const checkpointByteLength = new TextEncoder().encode(currentDraft.text).length;
    versionsStore.put({ noteId: id, seq: checkpointSeq, at, sourceRev: currentDraft.localRev, text: currentDraft.text, byteLength: checkpointByteLength });
  }

  const byteLength = new TextEncoder().encode(target.text).length;
  versionsStore.put({ noteId: id, seq: restoredSeq, at, sourceRev: nextRev, text: target.text, byteLength });

  const draftStore = tx.objectStore('drafts');
  draftStore.put({ noteId: id, text: target.text, localRev: nextRev, savedAt: at, byteLength });

  // The user-set title survives a restore: version records carry no title, so
  // titles were never versioned — restoring text must not rename the note.

  const restoreStamp = await mutationStamp(tx.objectStore('meta'));
  ensureNoteStamps(noteRecord, restoreStamp.d).text = restoreStamp;

  noteRecord.updatedAt = at;
  noteRecord.localRev = nextRev;
  noteRecord.noteRev = (noteRecord.noteRev || 0) + 1;
  noteStore.put(noteRecord);

  await awaitTransactionComplete(tx);

  durableRevs.set(id, Math.max(durableRevs.get(id) || 0, nextRev));
  // Drain any flush() waiters this restore's own durability now covers. This
  // mirrors what every successful runDraftWrite write already does via
  // resolveWaiters(), and closes a real hang: a flush(id, rev) call that
  // registered a waiter during this restore's async window (missing the fast
  // path because durableRevs hadn't been updated yet) would otherwise sit
  // unresolved until some unrelated later draft write happened to drain it —
  // or forever, if none ever comes. Safe by construction: resolveWaiters only
  // settles waiters whose rev <= durableRev, so a waiter for a revision
  // higher than nextRev (queued during the restore, correctly deferred by
  // the generation fence, not yet actually written) is left untouched here —
  // it stays pending until its own real write completes and calls
  // resolveWaiters normally, via the deferred write this function's caller
  // (restoreVersion's finally) starts once the lock is released.
  resolveWaiters(id, { noteId: id, requestedRev: nextRev, durableRev: durableRevs.get(id), completedAt: at });
  lastVersionText.set(id, target.text);
  emit({ type: 'note-changed', noteId: id });
  emit({ type: 'sync-dirty', noteId: id });

  return { seq: restoredSeq, at, sourceRev: nextRev, size: byteLength };
}

// --- maintenance: the pruning ladder ----------------------------------------
//
// runMaintenance() walks every note and thins its version history:
//   1. the newest PROTECTED_RECENT_COUNT versions are always kept;
//   2. every version from the last PROTECTED_RECENT_MS is always kept;
//   3. the newest version is always kept, even if 1 and 2 somehow left it out
//      (an empty history is impossible, but this is the invariant the whole
//      task exists to guarantee, so it is asserted directly rather than left
//      to fall out of 1 and 2);
//   4. everything older than that is thinned to one version per UTC day
//      (ties broken by seq, i.e. the latest version written that day wins);
//   5. all of the above is bounded by PER_NOTE_HISTORY_BYTE_BUDGET. If the
//      protected set from 1–3 alone already exceeds the budget, there is
//      nothing pruning can do without deleting a protected recovery point —
//      so this note is skipped entirely for this run (nothing is deleted,
//      not even the day-thinning that would otherwise apply) and a
//      quota-warning event is emitted instead.
//
// Each note is read and deleted in its own pair of transactions, so a crash
// or reload mid-run leaves already-pruned notes pruned and resumes cleanly on
// the rest — recomputing toDelete from scratch is always safe because it is
// derived from what is still on disk, never from what was deleted last time.
//
// v1 has no automatic trash purge — design.md is explicit that trash is
// emptied only on explicit user confirmation, overriding the looser "and the
// trash purge" wording in store-api.md. purgeNote() (Task 6) already covers
// the explicit path; nothing automatic happens here, so `purged` is always 0.

async function listNoteIds() {
  const tx = openTransaction(activeConn(), ['notes'], 'readonly');
  const ids = [];
  await new Promise((resolve, reject) => {
    const req = tx.objectStore('notes').openCursor();
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor) { resolve(); return; }
      ids.push(cursor.value.id);
      cursor.continue();
    };
    req.onerror = () => reject(req.error);
  });
  return ids;
}

function utcDayKey(at) {
  const d = new Date(at);
  return `${d.getUTCFullYear()}-${d.getUTCMonth()}-${d.getUTCDate()}`;
}

async function pruneNote(noteId) {
  const all = await listVersions(noteId, {});
  if (all.length === 0) return 0;

  const now = Date.now();
  const protectedByCount = new Set(all.slice(0, LIMITS.PROTECTED_RECENT_COUNT).map((v) => v.seq));

  const protectedByAge = new Set(all.filter((v) => now - v.at <= LIMITS.PROTECTED_RECENT_MS).map((v) => v.seq));
  // Sync conflict losers carry an explicit seven-day protection fence. Count
  // and byte pressure may prune around them, but never through that fence.
  const protectedByConflict = new Set(all.filter((v) => v.protectedUntil > now).map((v) => v.seq));
  // all[0] is the newest version (listVersions is newest-first): explicitly
  // protected regardless of count/age so runMaintenance can never remove it.

  const protectedSeqs = new Set([...protectedByCount, ...protectedByAge, ...protectedByConflict, all[0].seq]);

  const protectedBytes = all.filter((v) => protectedSeqs.has(v.seq)).reduce((sum, v) => sum + v.size, 0);
  if (protectedBytes > LIMITS.PER_NOTE_HISTORY_BYTE_BUDGET) {
    emit({ type: 'quota-warning', noteId, reason: 'protected-history-over-budget' });
    return 0;
  }

  const older = all.filter((v) => !protectedSeqs.has(v.seq));
  const keepOnePerDay = new Map();
  for (const v of older) {
    const key = utcDayKey(v.at);
    const existing = keepOnePerDay.get(key);
    if (!existing || v.seq > existing.seq) keepOnePerDay.set(key, v);
  }
  const keepSeqs = new Set([...protectedSeqs, ...Array.from(keepOnePerDay.values()).map((v) => v.seq)]);
  const toDelete = all.filter((v) => !keepSeqs.has(v.seq));

  if (toDelete.length === 0) return 0;

  const tx = openTransaction(activeConn(), ['versions'], 'readwrite', { durability: 'strict' });
  const versionsStore = tx.objectStore('versions');
  for (const v of toDelete) {
    versionsStore.delete([noteId, v.seq]);
  }
  await awaitTransactionComplete(tx);
  return toDelete.length;
}

export async function runMaintenance() {
  // Nothing to prune: the in-memory maps are not under storage quota pressure,
  // and thinning them would only destroy history the session still has room
  // for. The shape of the result is kept identical so callers cannot tell.
  if (memoryFallback) return { pruned: 0, purged: 0 };
  return withGlobalLock(async () => {
    const noteIds = await listNoteIds();
    let pruned = 0;
    for (const id of noteIds) {
      pruned += await pruneNote(id);
    }
    return { pruned, purged: 0 };
  });
}


async function withGlobalLock(work) {
  return navigator.locks.request('heldnote-global', work);
}

export async function getAllTombstones() {
  if (memoryFallback) {
    return Array.from(memoryFallback.meta.values())
      .filter((entry) => entry.key.startsWith('tombstone:'))
      .map((entry) => ({ id: entry.id || entry.key.slice(10), stamp: entry.stamp }));
  }
  const tx = openTransaction(activeConn(), ['meta'], 'readonly');
  const records = await requestToPromise(tx.objectStore('meta').getAll());
  return records
    .filter((entry) => entry.key.startsWith('tombstone:'))
    .map((entry) => ({ id: entry.id || entry.key.slice(10), stamp: entry.stamp }));
}

export async function getAllSyncBases() {
  const records = memoryFallback
    ? Array.from(memoryFallback.meta.values())
    : await requestToPromise(openTransaction(activeConn(), ['meta'], 'readonly').objectStore('meta').getAll());
  const result = new Map();
  for (const entry of records) {
    if (entry.key.startsWith('sync:')) {
      result.set(entry.key.slice(5), { stamps: entry.stamps, textHash: entry.textHash });
    }
  }
  return result;
}


export async function flushAllPending() {
  if (memoryFallback) return [];
  const pending = [];
  for (const [id, rev] of revCounters) {
    if (rev > (durableRevs.get(id) || 0)) pending.push(flush(id, rev));
  }
  return Promise.all(pending);
}

export async function getAllNotesForSync() {
  if (memoryFallback) return [];
  const tx = openTransaction(activeConn(), ['notes', 'drafts', 'meta'], 'readwrite', { durability: 'strict' });
  const noteStore = tx.objectStore('notes');
  const notes = await requestToPromise(noteStore.getAll());
  const drafts = await requestToPromise(tx.objectStore('drafts').getAll());
  const draftById = new Map(drafts.map((draft) => [draft.noteId, draft]));
  const deviceId = await ensureDeviceIdInStore(tx.objectStore('meta'));
  const result = [];
  for (const note of notes) {
    const draft = draftById.get(note.id);
    if (!draft) continue;
    if (!note.stamps) {
      note.stamps = migrateNoteStamps(note.updatedAt, deviceId);
      noteStore.put(note);
    }
    result.push({
      id: note.id, title: note.title, text: draft.text,
      createdAt: note.createdAt, updatedAt: note.updatedAt,
      pinned: note.pinKey === 1, isDeleted: note.isDeleted || 0,

      deletedAt: note.isDeleted === 1 ? note.deletedAt : null,
      localRev: draft.localRev, noteRev: note.noteRev || 0, stamps: note.stamps,
    });
  }
  await awaitTransactionComplete(tx);
  return result;
}

export async function getAllVersionsForSync() {
  if (memoryFallback) return [];
  const tx = openTransaction(activeConn(), ['versions'], 'readonly');
  const records = await requestToPromise(tx.objectStore('versions').getAll());
  const result = [];
  for (const record of records) {
    result.push({
      ...record,
      textHash: record.textHash || await computeTextHash(record.text),
    });
  }
  return result;
}

function versionIdentity(version) {
  return `${version.noteId}\u0000${version.at}\u0000${version.sourceRev}\u0000${version.textHash || ''}`;
}

export async function applyMergePlan(plan) {
  if (memoryFallback) return { applied: [], skipped: [] };

  return withGlobalLock(async () => {
    // Hash/dedupe preparation happens while the global lock is held but before
    // the write transaction opens. crypto.subtle resolves on a later task and
    // would otherwise let IndexedDB auto-commit the transaction underneath it.

    const existingVersions = await getAllVersionsForSync();
    const identities = new Set(existingVersions.map(versionIdentity));

    const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions', 'meta'], 'readwrite', { durability: 'strict' });
    const notesStore = tx.objectStore('notes');
    const draftsStore = tx.objectStore('drafts');
    const versionsStore = tx.objectStore('versions');
    const metaStore = tx.objectStore('meta');
    const applied = [];
    const skipped = [];
    const touched = new Set();

    const created = new Set();
    const changes = new Map();
    const deleted = new Set();

    for (const op of plan.noteOps) {
      const currentNote = await requestToPromise(notesStore.get(op.noteId));
      const currentDraft = await requestToPromise(draftsStore.get(op.noteId));

      if (
        op.fence
        && (
          !currentDraft
          || !currentNote
          || currentDraft.localRev > op.fence.localRev
          || (currentNote.noteRev || 0) > (op.fence.noteRev || 0)
        )
      ) {
        skipped.push(op.noteId);
        continue;
      }


      if (op.action === 'purge') {
        notesStore.delete(op.noteId);
        deleted.add(op.noteId);
        draftsStore.delete(op.noteId);
        const range = IDBKeyRange.bound([op.noteId, -Infinity], [op.noteId, Infinity]);
        await new Promise((resolve, reject) => {
          const request = versionsStore.openCursor(range);
          request.onsuccess = () => {
            const cursor = request.result;
            if (!cursor) { resolve(); return; }
            cursor.delete();
            cursor.continue();
          };
          request.onerror = () => reject(request.error);
        });

      } else {
        const note = op.note;
        const localRev = currentDraft ? currentDraft.localRev : (note.localRev || 0);
        const cleanTitle = String(note.title || '').replace(/[/\\\u0000-\u001F]/g, '').trim().slice(0, 200) || 'Untitled.txt';
        const textChanged = !currentDraft || currentDraft.text !== note.text;
        changes.set(note.id, { noteId: note.id, textChanged });
        notesStore.put({
          id: note.id, title: cleanTitle, createdAt: note.createdAt,
          updatedAt: note.updatedAt, localRev, noteRev: currentNote ? (currentNote.noteRev || 0) : (note.noteRev || 0),
          pinned: Boolean(note.pinned), pinKey: note.pinned ? 1 : 0,
          isDeleted: note.isDeleted || 0,
          ...(note.isDeleted ? { deletedAt: note.deletedAt } : {}),
          stamps: note.stamps,
        });
        draftsStore.put({
          noteId: note.id, text: note.text, localRev,
          savedAt: note.updatedAt,
          byteLength: new TextEncoder().encode(note.text).length,
        });
        revCounters.set(note.id, Math.max(revCounters.get(note.id) || 0, localRev));
        durableRevs.set(note.id, Math.max(durableRevs.get(note.id) || 0, localRev));
        if (!currentNote) created.add(note.id);
      }
      applied.push(op.noteId);
      touched.add(op.noteId);
    }


    const skippedSet = new Set(skipped);
    const nextSeqByNote = new Map();
    async function maxSeqFor(noteId) {
      if (nextSeqByNote.has(noteId)) return nextSeqByNote.get(noteId);
      const range = IDBKeyRange.bound([noteId, -Infinity], [noteId, Infinity]);
      const max = await new Promise((resolve, reject) => {
        const request = versionsStore.openCursor(range, 'prev');
        request.onsuccess = () => resolve(request.result ? request.result.value.seq : 0);
        request.onerror = () => reject(request.error);
      });
      nextSeqByNote.set(noteId, max);
      return max;
    }

    for (const version of [...plan.conflictVersions, ...plan.remoteVersionsToImport]) {
      if (skippedSet.has(version.noteId)) continue;
      const identity = versionIdentity(version);
      if (identities.has(identity)) continue;
      identities.add(identity);

      const seq = (await maxSeqFor(version.noteId)) + 1;
      nextSeqByNote.set(version.noteId, seq);
      versionsStore.put({
        ...version, seq,
        byteLength: new TextEncoder().encode(version.text).length,
      });
      touched.add(version.noteId);
    }

    for (const tombstone of plan.tombstoneWrites) {
      if (!skippedSet.has(tombstone.id)) {
        metaStore.put({ key: `tombstone:${tombstone.id}`, ...tombstone });
      }
    }
    for (const id of plan.tombstoneDeletes) {
      if (!skippedSet.has(id)) metaStore.delete(`tombstone:${id}`);
    }

    await awaitTransactionComplete(tx);


    for (const id of deleted) emit({ type: 'note-deleted', noteId: id, source: 'sync' });
    for (const id of touched) {
      if (!deleted.has(id)) emit({ type: 'note-changed', noteId: id, source: 'sync', textChanged: changes.get(id)?.textChanged || false });
    }
    if (created.size > 0) emit({ type: 'imported', source: 'sync', noteIds: Array.from(created) });
    if (touched.size > 0) emit({ type: 'sync-applied', changes: Array.from(changes.values()), deletedNoteIds: Array.from(deleted) });
    return { applied, skipped };
  });
}

// --- per-note locking: cross-tab mutual exclusion via Web Locks ------------
//
// Distinct from draftQueues/q.restoring above: those serialize writes within
// a single tab/connection. acquireNoteLock/releaseNoteLock instead let one
// tab claim exclusive edit access to a note while other tabs (in a later
// task) can see the lock is held and open the note read-only. Named locks
// are per-origin, not per-tab, so a second acquireNoteLock(id) call for a
// note whose lock is still held — even one issued from this same module — is
// correctly refused by the browser: nothing here needs to track "who is
// asking", only whether the named lock is free.
//
// heldLocks intentionally does NOT short-circuit a repeat acquire for a note
// this tab already holds. ifAvailable:true reports the lock as unavailable
// until the previous holder's callback promise settles, and that is exactly
// the mutual-exclusion behaviour callers depend on.

const heldLocks = new Map(); // noteId -> release function for the lock this tab holds

export async function acquireNoteLock(id) {
  const lockName = `heldnote-note-${id}`;

  let released;
  const releasePromise = new Promise((resolve) => { released = resolve; });

  const outcome = await new Promise((resolve) => {
    let grantedFlag = false;
    navigator.locks.request(lockName, { ifAvailable: true }, (lock) => {
      if (!lock) {
        resolve({ granted: false, heldBy: 'another tab' });
        return Promise.resolve();
      }
      grantedFlag = true;
      heldLocks.set(id, released);
      resolve({ granted: true });
      // Held until releaseNoteLock() resolves this promise.
      return releasePromise;
    }).catch(() => {
      if (!grantedFlag) resolve({ granted: false, heldBy: 'another tab' });
    });
  });

  if (outcome.granted) {
    emit({ type: 'lock-changed', noteId: id, granted: true });
  }
  return outcome;
}

export async function releaseNoteLock(id) {
  const release = heldLocks.get(id);
  if (release) {
    release();
    heldLocks.delete(id);
    emit({ type: 'lock-changed', noteId: id, granted: false });
  }
}

// --- backup: export / import ------------------------------------------------
//
// exportAll()/importAll() are the app's only backup mechanism in v1 (no sync).
// exportAll flushes each note's pending revision before reading it, so an
// export immediately after typing reflects the latest text rather than
// whatever was last durable. importAll validates schemaVersion/shape entirely
// before touching anything (parseImportFile runs before withGlobalLock is even
// requested), so a malformed file changes nothing. Both of importAll's modes,
// and exportAll's read-and-build phase (but NOT its flush-wait phase — see
// the comment on exportAll itself for why that split is load-bearing, not
// stylistic), hold withGlobalLock (Task 10/12), like runMaintenance, since
// all three touch every store: without it, a concurrent replace-mode
// importAll could commit mid-export, and getNote() would throw not-found for
// a note the import just deleted out from under exportAll's loop (or, if a
// note id happens to be reused, the export could silently mix pre-/post-
// import fields into one file it reports as a successful backup).
//
// The part that isn't in the brief this was written against: keeping the
// per-note in-memory bookkeeping built up over Tasks 6-11 (revCounters,
// durableRevs, draftQueues, lastVersionText, memoryOnlyText, noteGeneration)
// consistent with what importAll just put on disk.
//
//  - replace mode deletes and rewrites every note/draft/version in one
//    transaction, so every one of those Maps is reset to empty first (an
//    entry for a note id that isn't in the import now describes a note that
//    no longer exists on disk) and then reseeded per imported note from the
//    data just written: revCounters and durableRevs both to note.localRev
//    (exactly what getNote() would derive from the draft record just
//    written), and lastVersionText to the newest imported version's text, but
//    only when that text still matches the note's current draft text
//    (mirroring commitVersion's own dedup invariant — if the draft has moved
//    on from the newest version, there is nothing to dedup against yet).
//    Skipping the reseed would leave two real bugs: a subsequent saveDraft()
//    would restart numbering at rev 1 while the record on disk already
//    carries the imported localRev (harmless by itself, since draftQueues is
//    also cleared and the next write still lands, but the numbers would no
//    longer describe real history), and — the serious one — durableRevs
//    staying at 0 for that id means flush()'s fast path can never answer
//    "already durable" for the imported revision. flush() has no other path
//    that resolves without a write in flight, so a flush() call for an
//    imported note's current revision, issued before any further edit,would
//    hang forever.
//  - copy mode assigns brand-new ids alongside the existing notes, so nothing
//    existing needs clearing (its on-disk state hasn't changed) — only the
//    fresh ids need the same seeding, for the same reason.
//
// heldLocks (Web Locks a tab holds for a note it's editing) and
// versionCommitsStopped (a whole-connection quota latch) are deliberately
// left untouched by either mode: the former is about who has editing access
// right now, not about what's on disk, and the latter describes storage
// pressure, not import data.

const SCHEMA_VERSION = 1;

// The `meta` store (db.js creates it for theme/zoom/language/last-opened-note)
// has no writer yet — settings persistence is its own feature, not this one.
// Export and import carry it anyway, so that whenever that feature arrives a
// backup round-trips settings without a second change to the file format, and
// so no backup taken in the meantime silently drops data another module wrote.
async function readAllMeta() {
  const tx = openTransaction(activeConn(), ['meta'], 'readonly');
  const entries = [];
  await new Promise((resolve, reject) => {
    const req = tx.objectStore('meta').openCursor();
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor) { resolve(); return; }
      entries.push(cursor.value);
      cursor.continue();
    };
    req.onerror = () => reject(req.error);
  });
  return entries;
}

export async function exportAll() {
  // Two phases, deliberately split across the lock boundary.
  //
  // Phase 1 (unlocked): flush every note with a pending revision, so the
  // export reflects the latest typed text. This CANNOT run inside
  // withGlobalLock: a flush() here waits on a draft write that, on a quota
  // fault, retries via runMaintenance() — which itself requests this same
  // 'heldnote-global' lock. Web Locks has no reentrancy: if exportAll were
  // already holding the lock while awaiting that flush(), the retry's
  // runMaintenance() call would queue behind exportAll's own hold, which is
  // itself waiting on that same retry to finish — a permanent deadlock, and
  // anything else queued on the lock (e.g. a subsequent importAll) hangs
  // behind it too. Running the flush loop before ever requesting the lock
  // means exportAll is never simultaneously holding it and blocked on a
  // promise that needs it.
  //
  // Phase 2 (locked): the read-and-build phase (getNote/listVersions/
  // getVersion/Blob construction) is what the original Critical finding was
  // actually about — a concurrent replace-mode importAll committing mid-read
  // would throw not-found for a note it just deleted, or mix pre-/post-import
  // fields into one file reported as a successful backup. importAll holds
  // this same lock for its entire write, so serializing just this phase
  // against it is sufficient, and re-fetching noteSummaries fresh INSIDE the
  // lock (rather than reusing phase 1's list) means this phase always reads
  // one consistent state — either fully pre-import or fully post-import,
  // never a stale summary list pointing at notes an import deleted during
  // the (unlocked) phase 1 flush-wait.
  // Memory mode needs neither phase: memorySaveDraft publishes synchronously,
  // so there is never a pending revision to flush, and no other transaction can
  // interleave with the read below. The design is explicit that this session's
  // notes must still be exportable — this is the only way anything typed in
  // memory mode leaves the tab alive.
  if (memoryFallback) return memoryExportAll();

  const pendingSummaries = await listNotes({ includeTrashed: true, limit: 100000 });
  for (const summary of pendingSummaries) {
    const rev = revCounters.get(summary.id);
    if (rev) await flush(summary.id, rev).catch(() => {});
  }

  return withGlobalLock(async () => {
    const noteSummaries = await listNotes({ includeTrashed: true, limit: 100000 });

    const notes = [];
    for (const summary of noteSummaries) {
      notes.push(await getNote(summary.id));
    }

    const versions = [];
    for (const summary of noteSummaries) {
      const infos = await listVersions(summary.id, {});
      for (const info of infos) {
        versions.push({ noteId: summary.id, ...(await getVersion(summary.id, info.seq)) });
      }
    }


    const meta = (await readAllMeta()).filter((entry) => !isSyncInternalMetaKey(entry.key));

    const payload = { schemaVersion: SCHEMA_VERSION, exportedAt: Date.now(), notes, versions, meta };
    return new Blob([JSON.stringify(payload)], { type: 'application/json' });
  });
}

// Per-record shape validation. store-api.md promises the file is validated
// "before touching anything", but only the envelope was ever checked, so a
// hand-edited or truncated backup could write records with undefined fields —
// and an undefined `title` then hangs listNotes()'s search cursor forever.
// Every field the write paths below dereference is checked here.

function isFiniteNumber(value) {
  return typeof value === 'number' && Number.isFinite(value);
}

function isValidImportedNote(note) {
  return Boolean(note) && typeof note === 'object' && !Array.isArray(note)
    && typeof note.id === 'string' && note.id.length > 0
    && typeof note.title === 'string'
    && typeof note.text === 'string'
    && isFiniteNumber(note.createdAt)
    && isFiniteNumber(note.updatedAt)
    && isFiniteNumber(note.localRev)
    && typeof note.pinned === 'boolean'
    // exportAll writes deletedAt: null for a live note; a trashed one carries a
    // timestamp; a hand-written file may omit the key entirely.
    && (note.deletedAt === undefined || note.deletedAt === null || isFiniteNumber(note.deletedAt));
}

function isValidImportedVersion(version) {
  return Boolean(version) && typeof version === 'object' && !Array.isArray(version)
    && typeof version.noteId === 'string' && version.noteId.length > 0
    && isFiniteNumber(version.seq)
    && isFiniteNumber(version.at)
    && isFiniteNumber(version.sourceRev)
    && typeof version.text === 'string';
}


function isSyncInternalMetaKey(key) {
  return key === 'deviceId'
    || key === 'hlc'
    || key === 'dirtyGen'
    || key === 'sync-retry-pending'
    || key === 'initialScanDone'
    || key === 'lastSyncAt'
    || key === 'headRevisionId'
    || key.startsWith('sync:')
    || key.startsWith('tombstone:')
    || key.startsWith('dirty:')
    || key.startsWith('journal:');
}

function isValidImportedMetaEntry(entry) {
  return Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry)
    && typeof entry.key === 'string' && entry.key.length > 0;
}

async function parseImportFile(file) {
  let text;
  try {
    text = await file.text();
  } catch (_e) {
    throw Object.assign(new Error('could not read file'), { code: 'invalid-import' });
  }
  let parsed;
  try {
    parsed = JSON.parse(text);
  } catch (_e) {
    throw Object.assign(new Error('file is not valid JSON'), { code: 'invalid-import' });
  }
  // `null` parses as valid JSON, so the object check has to come first: without
  // it, reading .schemaVersion off null throws a bare TypeError out of a
  // function whose entire contract is to reject bad files with invalid-import.
  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw Object.assign(new Error('file does not have the expected shape'), { code: 'invalid-import' });
  }
  if (typeof parsed.schemaVersion !== 'number' || !Array.isArray(parsed.notes) || !Array.isArray(parsed.versions)) {
    throw Object.assign(new Error('file does not have the expected shape'), { code: 'invalid-import' });
  }
  if (parsed.schemaVersion > SCHEMA_VERSION) {
    throw Object.assign(new Error(`file schemaVersion ${parsed.schemaVersion} is newer than this app understands`), { code: 'invalid-import' });
  }
  // `meta` is optional: files written before exportAll carried settings simply
  // do not have the key, and refusing those would break every existing backup.
  const meta = parsed.meta === undefined ? [] : parsed.meta;
  if (!Array.isArray(meta)) {
    throw Object.assign(new Error('file does not have the expected shape'), { code: 'invalid-import' });
  }

  const noteIds = new Set();
  for (const note of parsed.notes) {
    if (!isValidImportedNote(note)) {
      throw Object.assign(new Error('file contains a note that is missing required fields'), { code: 'invalid-import' });
    }
    // Two notes sharing an id do not survive the import intact: copy mode keeps
    // only the last id mapping, so every version belonging to the first is
    // silently re-parented onto the second, and replace mode simply overwrites.
    // Refusing is the only outcome that does not quietly rearrange history.
    if (noteIds.has(note.id)) {
      throw Object.assign(new Error(`file contains more than one note with id ${note.id}`), { code: 'invalid-import' });
    }
    noteIds.add(note.id);
  }
  const versionKeys = new Set();
  for (const version of parsed.versions) {
    if (!isValidImportedVersion(version)) {
      throw Object.assign(new Error('file contains a version that is missing required fields'), { code: 'invalid-import' });
    }
    // versions is keyed [noteId, seq], so a repeated pair means the second put
    // overwrites the first and one of the two snapshots is lost on import.
    const versionKey = `${version.noteId}\u0000${version.seq}`;
    if (versionKeys.has(versionKey)) {
      throw Object.assign(new Error(`file contains more than one version ${version.seq} for note ${version.noteId}`), { code: 'invalid-import' });
    }
    versionKeys.add(versionKey);
    // A version naming a note the file does not carry has nowhere to go: copy
    // mode would map it to an undefined id and abort the whole transaction on
    // a DataError, and replace mode would write an unreachable orphan record.
    if (!noteIds.has(version.noteId)) {
      throw Object.assign(new Error(`file contains a version for unknown note ${version.noteId}`), { code: 'invalid-import' });
    }
  }
  for (const entry of meta) {
    if (!isValidImportedMetaEntry(entry)) {
      throw Object.assign(new Error('file contains a settings entry that is missing required fields'), { code: 'invalid-import' });
    }
  }


  return { ...parsed, meta: meta.filter((entry) => !isSyncInternalMetaKey(entry.key)) };
}

function noteRecordFrom(note, idOverride) {
  return {
    id: idOverride || note.id, title: note.title, createdAt: note.createdAt, updatedAt: note.updatedAt,
    localRev: note.localRev, pinned: note.pinned, pinKey: note.pinned ? 1 : 0,
    isDeleted: note.deletedAt ? 1 : 0, ...(note.deletedAt ? { deletedAt: note.deletedAt } : {}),
  };
}

// noteId -> { seq, text } of the highest-seq (newest) version in `versions`,
// used to decide what lastVersionText should be seeded to after an import.
function newestVersionTextByNoteId(versions) {
  const newest = new Map();
  for (const v of versions) {
    const current = newest.get(v.noteId);
    if (!current || v.seq > current.seq) newest.set(v.noteId, { seq: v.seq, text: v.text });
  }
  return newest;
}

// Reseeds revCounters/durableRevs/lastVersionText for one just-imported note,
// exactly mirroring what getNote() would derive from the draft record
// importAll just wrote — see the comment block above this section for why
// this is required, not optional.
function seedImportedNoteState(id, note, newestVersionText) {
  revCounters.set(id, note.localRev);
  durableRevs.set(id, note.localRev);
  if (newestVersionText !== undefined && newestVersionText === note.text) {
    lastVersionText.set(id, newestVersionText);
  }
}

export async function importAll(file, { mode }) {
  // Validation is storage-independent and runs first in both modes, so a
  // malformed file is refused identically whether or not IndexedDB is there.
  const parsed = await parseImportFile(file);

  if (memoryFallback) return memoryImportAll(parsed, mode);

  return withGlobalLock(async () => {
    if (mode === 'replace') {
      const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions', 'meta'], 'readwrite', { durability: 'strict' });
      tx.objectStore('notes').clear();
      tx.objectStore('drafts').clear();
      tx.objectStore('versions').clear();
      // Replace means replace: settings from the file take over wholesale, the
      // same way notes do.
      tx.objectStore('meta').clear();
      for (const entry of parsed.meta) {
        tx.objectStore('meta').put(entry);
      }
      for (const note of parsed.notes) {
        tx.objectStore('notes').put(noteRecordFrom(note));
        tx.objectStore('drafts').put({ noteId: note.id, text: note.text, localRev: note.localRev, savedAt: note.updatedAt, byteLength: new TextEncoder().encode(note.text).length });
      }
      for (const v of parsed.versions) {
        tx.objectStore('versions').put({ noteId: v.noteId, seq: v.seq, at: v.at, sourceRev: v.sourceRev, text: v.text, byteLength: new TextEncoder().encode(v.text).length });
      }
      await awaitTransactionComplete(tx);

      // A draft write genuinely in flight for some note id right now has its
      // own waiters sitting in that note's *current* draftQueues entry.
      // draftQueues.clear() below discards that entry outright; whenever that
      // in-flight write eventually settles, its own resolveWaiters() call
      // re-fetches the queue via queueFor(), which after a clear() returns a
      // brand-new, empty queue object — not the one those waiters were
      // pushed onto. Left alone, those waiters would never resolve or
      // reject. Reject them now, before the entry describing them is thrown
      // away: requestedRev: Infinity + durableRev: -Infinity forces every
      // waiter in resolveWaiters' loop into the reject branch, regardless of
      // what revision it was waiting for.
      for (const [staleNoteId, staleQueue] of draftQueues) {
        if (staleQueue.waiters.length > 0) {
          const error = Object.assign(new Error('note was replaced by an import before this write could complete'), { code: 'import-replaced' });
          resolveWaiters(staleNoteId, { noteId: staleNoteId, requestedRev: Infinity, durableRev: -Infinity, completedAt: Date.now(), error });
        }
      }

      // Every note/draft/version that existed before this transaction is gone
      // now, except whatever id happens to be reused by the import, so every
      // per-note Map is reset to empty first...
      draftQueues.clear();
      revCounters.clear();
      durableRevs.clear();
      lastVersionText.clear();
      memoryOnlyText.clear();
      noteGeneration.clear();

      // ...then reseeded per imported note from what was just written.
      const newestText = newestVersionTextByNoteId(parsed.versions);
      for (const note of parsed.notes) {
        seedImportedNoteState(note.id, note, newestText.get(note.id)?.text);
      }

      return { notesAdded: parsed.notes.length, notesCopied: 0, versionsAdded: parsed.versions.length, skipped: 0 };
    }

    if (mode === 'merge') {
      // Reconcile by id, for restoring a backup that shares ancestry with
      // this device (e.g. the Drive copy this device itself wrote). Unlike
      // 'copy', ids are preserved so a re-import can never duplicate a note;
      // unlike 'replace', nothing local is ever overwritten or removed:
      // - a note id we do not have → inserted as-is, with its versions;
      // - a note id we already have → the local note, draft, and in-memory
      //   editor state stay untouched (local edits win), and only version
      //   snapshots we lack (by [noteId, seq]) are filled in;
      // - meta is skipped entirely — this device's settings win.
      //
      // Two phases under withGlobalLock (cross-tab exclusive): snapshot what
      // exists in a readonly transaction, then write in a second transaction.
      // The lock is what makes the gap between them safe.
      const readTx = openTransaction(activeConn(), ['notes', 'versions'], 'readonly');
      const existingNoteIds = new Set(await requestToPromise(readTx.objectStore('notes').getAllKeys()));
      const existingVersionKeys = new Set(
        (await requestToPromise(readTx.objectStore('versions').getAllKeys())).map((key) => `${key[0]} ${key[1]}`),
      );
      await awaitTransactionComplete(readTx);

      let notesAdded = 0;
      let versionsAdded = 0;
      let skipped = 0;
      const addedNotes = [];
      const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions'], 'readwrite', { durability: 'strict' });
      for (const note of parsed.notes) {
        if (existingNoteIds.has(note.id)) { skipped += 1; continue; }
        tx.objectStore('notes').put(noteRecordFrom(note));
        tx.objectStore('drafts').put({ noteId: note.id, text: note.text, localRev: note.localRev, savedAt: note.updatedAt, byteLength: new TextEncoder().encode(note.text).length });
        addedNotes.push(note);
        notesAdded += 1;
      }
      const addedIds = new Set(addedNotes.map((note) => note.id));
      for (const v of parsed.versions) {
        if (existingNoteIds.has(v.noteId)) {
          if (existingVersionKeys.has(`${v.noteId} ${v.seq}`)) { skipped += 1; continue; }
        } else if (!addedIds.has(v.noteId)) {
          // A version for a note we neither had nor added — parseImportFile
          // already guarantees this cannot happen; skip defensively rather
          // than write an orphan record.
          skipped += 1;
          continue;
        }
        tx.objectStore('versions').put({ noteId: v.noteId, seq: v.seq, at: v.at, sourceRev: v.sourceRev, text: v.text, byteLength: new TextEncoder().encode(v.text).length });
        versionsAdded += 1;
      }
      await awaitTransactionComplete(tx);

      // Only brand-new notes need in-memory state seeded; existing notes'
      // caches were deliberately left alone. For an existing note that just
      // gained newer version snapshots, lastVersionText is also left alone:
      // worst case the next commitVersion writes one redundant snapshot,
      // which is cheaper than ever guessing wrong about the newest text.
      const newestText = newestVersionTextByNoteId(parsed.versions.filter((v) => addedIds.has(v.noteId)));
      for (const note of addedNotes) {
        seedImportedNoteState(note.id, note, newestText.get(note.id)?.text);
      }

      return { notesAdded, notesCopied: 0, versionsAdded, skipped };
    }

    const idMap = new Map();
    const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions', 'meta'], 'readwrite', { durability: 'strict' });
    // Notes are copied alongside the existing ones, but settings are global and
    // have no "copy" — a key can hold one value. The file's entries win, which
    // is the only behaviour that makes a copy-mode import of a backup taken on
    // another device carry that device's settings across.
    for (const entry of parsed.meta) {
      tx.objectStore('meta').put(entry);
    }
    for (const note of parsed.notes) {
      const freshId = newId();
      idMap.set(note.id, freshId);
      tx.objectStore('notes').put(noteRecordFrom(note, freshId));
      tx.objectStore('drafts').put({ noteId: freshId, text: note.text, localRev: note.localRev, savedAt: note.updatedAt, byteLength: new TextEncoder().encode(note.text).length });
    }
    for (const v of parsed.versions) {
      const freshId = idMap.get(v.noteId);
      tx.objectStore('versions').put({ noteId: freshId, seq: v.seq, at: v.at, sourceRev: v.sourceRev, text: v.text, byteLength: new TextEncoder().encode(v.text).length });
    }
    await awaitTransactionComplete(tx);

    // Fresh ids only: every existing note's on-disk state is untouched, so
    // only the new copies need revCounters/durableRevs/lastVersionText seeded
    // to what was just written under their new id.
    const remappedVersions = parsed.versions.map((v) => ({ ...v, noteId: idMap.get(v.noteId) }));
    const newestText = newestVersionTextByNoteId(remappedVersions);
    for (const note of parsed.notes) {
      const freshId = idMap.get(note.id);
      seedImportedNoteState(freshId, note, newestText.get(freshId)?.text);
    }

    return { notesAdded: 0, notesCopied: parsed.notes.length, versionsAdded: parsed.versions.length, skipped: 0 };
  });
}

// --- memory mode: the store with no storage under it ------------------------
//
// When open() cannot get an IndexedDB connection (blocked by another tab's
// upgrade, a corrupt database, or storage switched off entirely) it returns
// available:false and switches every function above onto the implementations
// below, which hold the same records in plain Maps for the life of the tab.
//
// This is a product feature, not a test seam. design.md: "the app runs against
// an explicit in-memory store for the session, says plainly that nothing is
// being stored, and includes that session's notes in export." Before this
// existed, memoryFallback was assigned and never read, so every call after a
// failed open() reached openTransaction(null, …) and threw a raw TypeError —
// the user could not create a note, could not type, and got no explanation.
// An app about not losing things is at its least excusable when it is a dead
// page.
//
// Two rules keep the seam invisible to callers:
//
//   - the RECORD shapes are the persisted ones (isDeleted/pinKey, no deletedAt
//     key while live), normalized back to the domain shapes at the boundary by
//     the very same toNoteSummary()/getNote() field mapping — so a caller
//     cannot tell which path produced a Note, a NoteSummary, a VersionInfo or
//     a SaveReceipt;
//   - the EVENTS are the same ones in the same order (saving → saved, or
//     saving → save-failed), so the status bar needs no memory-mode branch.
//     "Nothing is being stored" is communicated once, by the
//     storage-unavailable event open() already emits, not by degrading every
//     subsequent save into a failure.
//
// Writes here are synchronous, which removes the entire class of problem the
// persisted path's machinery exists for: there is no transaction to interleave,
// so no draft queue, no q.restoring lock, and no generation fence is needed.
// memorySaveDraft publishes and settles waiters before it returns, so flush()'s
// existing durableRevs fast path answers immediately with no memory-mode branch
// of its own. durableRevs is still the honest word for it — the revision really
// is committed to the only store there is; the fact that that store dies with
// the tab is what available:false says.
//
// Not implemented in memory mode, deliberately:
//   - runMaintenance() returns {pruned:0, purged:0} (nothing is under quota);
//   - acquireNoteLock/releaseNoteLock are left on the shared Web Locks path
//     above — the API is unrelated to IndexedDB and still works, and a tab
//     that is honest about holding a note open costs nothing;
//   - persist() is never requested: there is no storage to ask about.

function newMemoryStore() {
  return {
    notes: new Map(),    // id -> note record
    drafts: new Map(),   // noteId -> draft record
    versions: new Map(), // noteId -> Map(seq -> version record)
    meta: new Map(),     // key -> meta entry
  };
}

// Writes a memory session through to a connection that has just opened, in one
// transaction so a failure partway leaves nothing behind and open() can keep
// memory mode on. Records are already stored in their on-disk shapes (indexable
// pinKey/isDeleted, deletedAt omitted while live), so they are put() as-is.
//
// Ids come from newId() and are unique per session, so a note written here
// cannot collide with one already on disk; a put() is nonetheless the right
// call rather than add(), since re-running a partially-applied migration after
// a retry should converge rather than throw.
async function migrateMemorySessionToDisk() {
  const session = memoryFallback;
  // Checked across all four maps, not just notes: a memory session that only
  // ever imported settings has meta to carry and no notes, and skipping on an
  // empty notes map alone would drop it when the flag is cleared.
  if (!session) return;
  const isEmpty = session.notes.size === 0
    && session.drafts.size === 0
    && session.versions.size === 0
    && session.meta.size === 0;
  if (isEmpty) return;

  const tx = openTransaction(activeConn(), ['notes', 'drafts', 'versions', 'meta'], 'readwrite', { durability: 'strict' });
  const notesStore = tx.objectStore('notes');
  const draftsStore = tx.objectStore('drafts');
  const versionsStore = tx.objectStore('versions');
  const metaStore = tx.objectStore('meta');

  for (const record of session.notes.values()) notesStore.put(record);
  for (const record of session.drafts.values()) draftsStore.put(record);
  for (const versions of session.versions.values()) {
    for (const record of versions.values()) versionsStore.put(record);
  }
  for (const entry of session.meta.values()) metaStore.put(entry);

  await awaitTransactionComplete(tx);

  // The revision bookkeeping was tracking the memory session; it describes the
  // same notes, which now live on disk under the same ids and localRevs, so it
  // carries over unchanged. Seeding durableRevs is what stops a flush() for
  // already-migrated text from waiting on a write that will never come.
  for (const draft of session.drafts.values()) {
    revCounters.set(draft.noteId, Math.max(revCounters.get(draft.noteId) || 0, draft.localRev));
    durableRevs.set(draft.noteId, Math.max(durableRevs.get(draft.noteId) || 0, draft.localRev));
  }
}

function memoryVersionMap(noteId, create = false) {
  let versions = memoryFallback.versions.get(noteId);
  if (!versions && create) {
    versions = new Map();
    memoryFallback.versions.set(noteId, versions);
  }
  return versions;
}

function notFound(message) {
  return Object.assign(new Error(message), { code: 'not-found' });
}

function memoryCreateNote() {
  const id = newId();
  const now = Date.now();
  memoryFallback.notes.set(id, {
    id, title: 'Untitled.txt', createdAt: now, updatedAt: now, localRev: 0, noteRev: 1,
    pinned: false, pinKey: 0, isDeleted: 0,
  });
  memoryFallback.drafts.set(id, { noteId: id, text: '', localRev: 0, savedAt: now, byteLength: 0 });
  return { id, title: 'Untitled.txt', text: '', createdAt: now, updatedAt: now, pinned: false, deletedAt: null, localRev: 0 };
}

function memoryListNotes({ query, includeTrashed = false, limit, before } = {}) {
  const lowerQuery = query ? query.toLowerCase() : null;
  const results = [];

  for (const record of memoryFallback.notes.values()) {
    if (!includeTrashed && record.isDeleted === 1) continue;
    // Title first, body second, same order and same defensive String(… || '')
    // coercion as the cursor path — a record shape that would throw there must
    // not throw here either.
    let matchesQuery = !lowerQuery || String(record.title || '').toLowerCase().includes(lowerQuery);
    if (!matchesQuery) {
      const draftRecord = memoryFallback.drafts.get(record.id);
      matchesQuery = !!draftRecord && String(draftRecord.text || '').toLowerCase().includes(lowerQuery);
    }
    if (matchesQuery) results.push(toNoteSummary(record));
  }

  results.sort((a, b) => {
    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
    return b.updatedAt - a.updatedAt;
  });

  const sliced = before ? results.filter((r) => r.updatedAt < before) : results;
  return typeof limit === 'number' ? sliced.slice(0, limit) : sliced;
}

function memoryGetNote(id) {
  const noteRecord = memoryFallback.notes.get(id);
  const draftRecord = memoryFallback.drafts.get(id);
  if (!noteRecord || !draftRecord) throw notFound(`note ${id} not found`);
  revCounters.set(id, Math.max(revCounters.get(id) || 0, draftRecord.localRev));
  durableRevs.set(id, Math.max(durableRevs.get(id) || 0, draftRecord.localRev));
  return {
    id: noteRecord.id,
    title: noteRecord.title,
    text: draftRecord.text,
    createdAt: noteRecord.createdAt,
    updatedAt: noteRecord.updatedAt,
    pinned: noteRecord.pinKey === 1,
    deletedAt: noteRecord.isDeleted === 1 ? noteRecord.deletedAt : null,
    localRev: draftRecord.localRev,
  };
}

function memoryUpdateNoteFields(id, fields) {
  const record = memoryFallback.notes.get(id);
  if (!record) throw notFound(`note ${id} not found`);
  Object.assign(record, fields);
  emit({ type: 'note-changed', noteId: id });
}

function memoryRestoreNote(id) {
  const record = memoryFallback.notes.get(id);
  if (!record) throw notFound(`note ${id} not found`);
  record.isDeleted = 0;
  delete record.deletedAt;
  emit({ type: 'note-changed', noteId: id });
}

function memoryPurgeNote(id) {
  memoryFallback.notes.delete(id);
  memoryFallback.drafts.delete(id);
  memoryFallback.versions.delete(id);
  emit({ type: 'note-changed', noteId: id });
}

// Mirrors saveDraft's contract exactly: synchronous, returns the assigned
// revision, and NEVER throws — a caller that forgot to catch must not be the
// reason a keystroke is lost. Every failure leaves through the event stream and
// through resolveWaiters (which sets q.lastFailure, so a later flush() for this
// revision rejects instead of hanging), exactly as runDraftWrite's does.
function memorySaveDraft(id, text) {
  const nextRev = (revCounters.get(id) || 0) + 1;
  revCounters.set(id, nextRev);
  emit({ type: 'saving', noteId: id, requestedRev: nextRev });

  let receipt;
  try {
    const noteRecord = memoryFallback.notes.get(id);
    if (!noteRecord) throw notFound(`note ${id} not found`);

    // TextEncoder before any mutation: a non-string payload throws here, and
    // must leave the record untouched rather than half-updated. The user-set
    // title is deliberately not touched (renameNote is its only writer).
    const now = Date.now();
    const byteLength = new TextEncoder().encode(text).length;

    memoryFallback.drafts.set(id, { noteId: id, text, localRev: nextRev, savedAt: now, byteLength });
    noteRecord.updatedAt = now;
    noteRecord.localRev = nextRev;

    const durableRev = Math.max(durableRevs.get(id) || 0, nextRev);
    durableRevs.set(id, durableRev);
    receipt = { noteId: id, requestedRev: nextRev, durableRev, completedAt: Date.now() };
    emit({ type: 'saved', ...receipt });
  } catch (error) {
    receipt = { noteId: id, requestedRev: nextRev, durableRev: durableRevs.get(id) || 0, completedAt: Date.now(), error };
    emit({ type: 'save-failed', ...receipt });
  }

  resolveWaiters(id, receipt);
  return nextRev;
}

function memoryCommitVersion(id) {
  const draft = memoryFallback.drafts.get(id);
  if (!draft) throw notFound(`note ${id} not found`);
  // Same dedup invariant as the persisted path, against the same map.
  if (lastVersionText.get(id) === draft.text) return null;

  const versions = memoryVersionMap(id, true);
  let maxSeq = 0;
  for (const seq of versions.keys()) {
    if (seq > maxSeq) maxSeq = seq;
  }
  const seq = maxSeq + 1;
  const at = Date.now();
  const byteLength = new TextEncoder().encode(draft.text).length;
  versions.set(seq, { noteId: id, seq, at, sourceRev: draft.localRev, text: draft.text, byteLength });
  lastVersionText.set(id, draft.text);
  return { seq, at, sourceRev: draft.localRev, size: byteLength };
}

// Newest-first by (at, seq), matching the by_note_at index walked in reverse,
// so `before` remains the same exclusive [at, seq] tuple cursor and paging
// behaves identically on both paths.
function memoryListVersions(id, { before, limit } = {}) {
  const versions = memoryVersionMap(id);
  if (!versions) return [];

  const ordered = Array.from(versions.values()).sort((a, b) => (b.at - a.at) || (b.seq - a.seq));
  const afterCursor = before
    ? ordered.filter((v) => v.at < before.at || (v.at === before.at && v.seq < before.seq))
    : ordered;
  const page = limit ? afterCursor.slice(0, limit) : afterCursor;
  return page.map((v) => ({ seq: v.seq, at: v.at, sourceRev: v.sourceRev, size: v.byteLength }));
}

function memoryGetVersion(id, seq) {
  const versions = memoryVersionMap(id);
  const record = versions && versions.get(seq);
  if (!record) throw notFound(`version ${id}/${seq} not found`);
  return { seq: record.seq, at: record.at, sourceRev: record.sourceRev, text: record.text };
}

// Same guarantees as the persisted restore — an uncommitted draft is
// checkpointed as a version first, no existing version is ever removed, and the
// restore itself lands as a new version — minus the locking, which exists only
// to fence transactions against each other. Nothing here awaits, so no other
// call can observe or interleave with a partially applied restore.
function memoryRestoreVersion(id, seq) {
  const target = memoryGetVersion(id, seq);
  const currentDraft = memoryFallback.drafts.get(id);
  const noteRecord = memoryFallback.notes.get(id);
  if (!currentDraft || !noteRecord) throw notFound(`note ${id} not found`);

  const newest = memoryListVersions(id, { limit: 1 });
  const newestVersionText = newest.length ? memoryGetVersion(id, newest[0].seq).text : undefined;
  const needsCheckpoint = currentDraft.text !== newestVersionText;

  const nextRev = (revCounters.get(id) || 0) + 1;
  revCounters.set(id, Math.max(revCounters.get(id) || 0, nextRev));

  const versions = memoryVersionMap(id, true);
  let maxSeq = 0;
  for (const existing of versions.keys()) {
    if (existing > maxSeq) maxSeq = existing;
  }
  const baseSeq = maxSeq + 1;
  const checkpointSeq = needsCheckpoint ? baseSeq : null;
  const restoredSeq = needsCheckpoint ? baseSeq + 1 : baseSeq;

  const at = Date.now();
  if (needsCheckpoint) {
    const checkpointByteLength = new TextEncoder().encode(currentDraft.text).length;
    versions.set(checkpointSeq, { noteId: id, seq: checkpointSeq, at, sourceRev: currentDraft.localRev, text: currentDraft.text, byteLength: checkpointByteLength });
  }

  const byteLength = new TextEncoder().encode(target.text).length;
  versions.set(restoredSeq, { noteId: id, seq: restoredSeq, at, sourceRev: nextRev, text: target.text, byteLength });

  memoryFallback.drafts.set(id, { noteId: id, text: target.text, localRev: nextRev, savedAt: at, byteLength });
  // Same rule as the persisted path: a restore never renames the note.
  noteRecord.updatedAt = at;
  noteRecord.localRev = nextRev;

  durableRevs.set(id, Math.max(durableRevs.get(id) || 0, nextRev));
  resolveWaiters(id, { noteId: id, requestedRev: nextRev, durableRev: durableRevs.get(id), completedAt: at });
  lastVersionText.set(id, target.text);
  emit({ type: 'note-changed', noteId: id });
  emit({ type: 'sync-dirty', noteId: id });

  return { seq: restoredSeq, at, sourceRev: nextRev, size: byteLength };
}

function memoryExportAll() {
  const noteSummaries = memoryListNotes({ includeTrashed: true });

  const notes = noteSummaries.map((summary) => memoryGetNote(summary.id));

  const versions = [];
  for (const summary of noteSummaries) {
    for (const info of memoryListVersions(summary.id, {})) {
      versions.push({ noteId: summary.id, ...memoryGetVersion(summary.id, info.seq) });
    }
  }

  // Always an array, empty or not, so the file shape is identical on both
  // paths and importAll's optional-meta handling never has to special-case one.

  const meta = Array.from(memoryFallback.meta.values())
    .filter((entry) => !isSyncInternalMetaKey(entry.key));

  const payload = { schemaVersion: SCHEMA_VERSION, exportedAt: Date.now(), notes, versions, meta };
  return new Blob([JSON.stringify(payload)], { type: 'application/json' });
}

function memoryImportAll(parsed, mode) {
  if (mode === 'replace') {
    // Same waiter discipline as the persisted path: an entry about to be
    // discarded may still hold flush() waiters, and a waiter whose queue object
    // is thrown away can never be settled by anything.
    for (const [staleNoteId, staleQueue] of draftQueues) {
      if (staleQueue.waiters.length > 0) {
        const error = Object.assign(new Error('note was replaced by an import before this write could complete'), { code: 'import-replaced' });
        resolveWaiters(staleNoteId, { noteId: staleNoteId, requestedRev: Infinity, durableRev: -Infinity, completedAt: Date.now(), error });
      }
    }

    memoryFallback.notes.clear();
    memoryFallback.drafts.clear();
    memoryFallback.versions.clear();
    memoryFallback.meta.clear();
    draftQueues.clear();
    revCounters.clear();
    durableRevs.clear();
    lastVersionText.clear();
    memoryOnlyText.clear();
    noteGeneration.clear();

    for (const entry of parsed.meta) {
      memoryFallback.meta.set(entry.key, entry);
    }
    for (const note of parsed.notes) {
      memoryFallback.notes.set(note.id, noteRecordFrom(note));
      memoryFallback.drafts.set(note.id, { noteId: note.id, text: note.text, localRev: note.localRev, savedAt: note.updatedAt, byteLength: new TextEncoder().encode(note.text).length });
    }
    for (const v of parsed.versions) {
      memoryVersionMap(v.noteId, true).set(v.seq, { noteId: v.noteId, seq: v.seq, at: v.at, sourceRev: v.sourceRev, text: v.text, byteLength: new TextEncoder().encode(v.text).length });
    }

    const newestText = newestVersionTextByNoteId(parsed.versions);
    for (const note of parsed.notes) {
      seedImportedNoteState(note.id, note, newestText.get(note.id)?.text);
    }

    return { notesAdded: parsed.notes.length, notesCopied: 0, versionsAdded: parsed.versions.length, skipped: 0 };
  }

  if (mode === 'merge') {
    // Same contract as the persisted merge path: ids preserved, nothing local
    // overwritten or removed, meta skipped, only missing notes and missing
    // [noteId, seq] snapshots filled in.
    let notesAdded = 0;
    let versionsAdded = 0;
    let skipped = 0;
    const addedNotes = [];
    for (const note of parsed.notes) {
      if (memoryFallback.notes.has(note.id)) { skipped += 1; continue; }
      memoryFallback.notes.set(note.id, noteRecordFrom(note));
      memoryFallback.drafts.set(note.id, { noteId: note.id, text: note.text, localRev: note.localRev, savedAt: note.updatedAt, byteLength: new TextEncoder().encode(note.text).length });
      addedNotes.push(note);
      notesAdded += 1;
    }
    const addedIds = new Set(addedNotes.map((note) => note.id));
    for (const v of parsed.versions) {
      if (!addedIds.has(v.noteId)) {
        const versionMap = memoryVersionMap(v.noteId, false);
        if (!memoryFallback.notes.has(v.noteId) || (versionMap && versionMap.has(v.seq))) { skipped += 1; continue; }
      }
      memoryVersionMap(v.noteId, true).set(v.seq, { noteId: v.noteId, seq: v.seq, at: v.at, sourceRev: v.sourceRev, text: v.text, byteLength: new TextEncoder().encode(v.text).length });
      versionsAdded += 1;
    }
    const newestText = newestVersionTextByNoteId(parsed.versions.filter((v) => addedIds.has(v.noteId)));
    for (const note of addedNotes) {
      seedImportedNoteState(note.id, note, newestText.get(note.id)?.text);
    }
    return { notesAdded, notesCopied: 0, versionsAdded, skipped };
  }

  const idMap = new Map();
  for (const entry of parsed.meta) {
    memoryFallback.meta.set(entry.key, entry);
  }
  for (const note of parsed.notes) {
    const freshId = newId();
    idMap.set(note.id, freshId);
    memoryFallback.notes.set(freshId, noteRecordFrom(note, freshId));
    memoryFallback.drafts.set(freshId, { noteId: freshId, text: note.text, localRev: note.localRev, savedAt: note.updatedAt, byteLength: new TextEncoder().encode(note.text).length });
  }
  for (const v of parsed.versions) {
    const freshId = idMap.get(v.noteId);
    memoryVersionMap(freshId, true).set(v.seq, { noteId: freshId, seq: v.seq, at: v.at, sourceRev: v.sourceRev, text: v.text, byteLength: new TextEncoder().encode(v.text).length });
  }

  const remappedVersions = parsed.versions.map((v) => ({ ...v, noteId: idMap.get(v.noteId) }));
  const newestText = newestVersionTextByNoteId(remappedVersions);
  for (const note of parsed.notes) {
    const freshId = idMap.get(note.id);
    seedImportedNoteState(freshId, note, newestText.get(freshId)?.text);
  }

  return { notesAdded: 0, notesCopied: parsed.notes.length, versionsAdded: parsed.versions.length, skipped: 0 };
}