selfstore 1.0.0

package/dist/chunk-N4RPMX3Y.js

@@ -0,0 +1,1908 @@
+import { createNode, createMeta, gcTombstones, stamp, merge, unsyncableCounts, idPathFor, detectConflicts, changes } from './chunk-IBIEKK36.js';
+import { inspect, checkPasswordPolicy, writeBox, BACKUP_MIME, readBoxWithSync, asBytes } from './chunk-JB4JHM7V.js';
+import { openManifest, GROUP_KEYING } from './chunk-OWLX6PNT.js';
+import { seal, isEnvelope, unseal, newDeviceKey } from './chunk-QBCU7OOP.js';
+import { mintSlot, MAX_KEY_SLOTS, mintExternalSlot, openSlot } from './chunk-FDPAKHQS.js';
+import { SelfstoreError, isAuthExpired, errorLabelKey, isSelfstoreError } from './chunk-VBFMMR7Q.js';
+import { openDB } from 'idb';
+
+// src/persistence/target.ts
+var RESERVED_STORE_MODES = ["device", "file-manual"];
+function isReservedStoreMode(kind) {
+  return RESERVED_STORE_MODES.includes(kind);
+}
+
+// src/persistence/status.ts
+var isDurableKind = (kind) => !isReservedStoreMode(kind);
+function deriveStatus(input) {
+  if (!input.persistent) {
+    return {
+      state: "ephemeral",
+      severity: "warn",
+      actionable: true,
+      action: "choose-destination",
+      labelKey: "status.ephemeral"
+    };
+  }
+  if (isDurableKind(input.targetKind) && input.needsAttention) {
+    return {
+      state: "needs-attention",
+      severity: "danger",
+      actionable: true,
+      action: input.locked ? "unlock" : "reconnect",
+      labelKey: input.locked ? "status.locked" : "status.needsAttention"
+    };
+  }
+  if (input.saving) {
+    return { state: "saving", severity: "info", actionable: false, labelKey: "status.saving" };
+  }
+  if (input.targetKind === "file-manual" && input.pendingDownload) {
+    return {
+      state: "pending-download",
+      severity: "info",
+      actionable: true,
+      action: "download",
+      labelKey: "status.pendingDownload"
+    };
+  }
+  if (input.targetKind === "device") {
+    return {
+      state: "cache-only",
+      severity: "warn",
+      actionable: true,
+      action: "choose-destination",
+      labelKey: "status.cacheOnly"
+    };
+  }
+  return { state: "saved", severity: "ok", actionable: false, labelKey: "status.saved" };
+}
+
+// src/persistence/store.ts
+var storeError = (code, message) => ({
+  code,
+  labelKey: errorLabelKey(code),
+  message
+});
+var RESERVED = "__store";
+var KEY = {
+  mode: "mode",
+  version: "version",
+  syncMeta: "syncMeta",
+  lastSavedAt: "lastSavedAt",
+  enc: "enc",
+  targetKind: "targetKind",
+  remoteVersion: "remoteVersion",
+  syncJournal: "syncJournal",
+  baseMeta: "baseMeta",
+  // Bumped on every cache write: one cheap kv read tells a tab whether
+  // someone else wrote since it last looked (multi-tab fold).
+  epoch: "writeEpoch",
+  // SHA-256 of the content last pushed. Identical content skips the save (no
+  // "saving" flash, no redundant upload); an unpushed local edit hashes
+  // differently and still saves.
+  savedHash: "savedHash",
+  // The KV has no key enumeration, so forget() needs this index to preserve
+  // every group's anti-replay counter.
+  groupSeqIds: "groupSeqIds"
+};
+var JOURNAL_MAX = 20;
+var STALE_CHECK_MS = 2e4;
+function createLocalStore(opts) {
+  const { app, schemaVersion: version, appVersion, gather, apply, cache, readme, debounceMs = 800 } = opts;
+  const logger = opts.logger ?? console;
+  const requireEncryption = opts.requireEncryption ?? false;
+  const passwordPolicy = opts.passwordPolicy;
+  function assertPasswordPolicy(pw) {
+    if (!passwordPolicy) return;
+    const { ok, unmet } = checkPasswordPolicy(pw, passwordPolicy);
+    if (!ok) {
+      throw new SelfstoreError("WEAK_PASSWORD", `Password does not meet the policy: ${unmet.join(", ")}.`);
+    }
+  }
+  const journalSilent = new Set(opts.journalSilent ?? []);
+  const sync = opts.sync ?? {};
+  const kv = cache.kv;
+  const multiTab = opts.multiTab ?? (typeof window !== "undefined" && typeof BroadcastChannel !== "undefined");
+  const tabId = createNode();
+  const channel = multiTab && typeof BroadcastChannel !== "undefined" ? new BroadcastChannel(`selfstore:${app}`) : null;
+  const locks = multiTab && typeof navigator !== "undefined" && navigator.locks ? navigator.locks : null;
+  const lockName = `selfstore:${app}`;
+  let mode = "persistent";
+  let targetKind = "device";
+  let durable = null;
+  let label = null;
+  let encrypted = false;
+  let needsAttention = false;
+  let lastError = null;
+  let pendingDownload = false;
+  let lastSavedAt = null;
+  let ready = false;
+  let saving = false;
+  let lastSavedContentHash = null;
+  let pass = null;
+  let pendingExternalSecret = null;
+  let envelope = null;
+  let group = null;
+  let meta = createMeta();
+  let timer;
+  let idleTimer;
+  let remoteVersion = null;
+  let journal = [];
+  let lastSync = null;
+  let baseMeta = null;
+  let lastStaleCheck = 0;
+  const warnedNoId = /* @__PURE__ */ new Set();
+  let seenEpoch;
+  let pendingEdit = false;
+  let editSeq = 0;
+  let queuedKind = null;
+  let prefetched = null;
+  const PREFETCH_TTL_MS = 6e4;
+  const peerList = [];
+  const mirrorList = [];
+  const replicaList = [];
+  let chain = Promise.resolve();
+  function serialize(fn) {
+    const exec = locks ? () => locks.request(lockName, fn) : fn;
+    const run = chain.then(exec, exec);
+    chain = run.catch(() => void 0);
+    return run;
+  }
+  const IDLE_LOCK_MS = 30 * 60 * 1e3;
+  const durableKind = () => !isReservedStoreMode(targetKind);
+  const subs = /* @__PURE__ */ new Set();
+  let stateSnapshot;
+  const notify = () => {
+    stateSnapshot = buildState();
+    subs.forEach((f) => f());
+  };
+  const locked = () => durableKind() && encrypted && !pass && !envelope && !group;
+  const ownGroupRead = () => group ? { identity: group.identity, authors: [group.identity.sigPub] } : void 0;
+  const peerGroupRead = () => group ? { identity: group.identity, authors: group.manifest.members.map((m) => m.sig) } : void 0;
+  const groupSeqKey = (id) => `groupSeq:${id}`;
+  async function persistGroupSeq(id, seq) {
+    await kv.set(groupSeqKey(id), seq);
+    const ids = await kv.get(KEY.groupSeqIds) ?? [];
+    if (!ids.includes(id)) await kv.set(KEY.groupSeqIds, [...ids, id]);
+  }
+  function raiseGate(code, message) {
+    needsAttention = true;
+    lastError = storeError(code, message);
+    notify();
+  }
+  const transient = (message) => storeError("TARGET_UNAVAILABLE", message);
+  function kvSetSafe(key, value, what) {
+    kv.set(key, value).catch((e) => logger.error(`[selfstore] ${what} write failed`, e));
+  }
+  function armIdleLock() {
+    clearTimeout(idleTimer);
+    if (encrypted && (pass || envelope)) idleTimer = setTimeout(() => lockNow(), IDLE_LOCK_MS);
+  }
+  function lockNow() {
+    clearTimeout(idleTimer);
+    if (!pass && !envelope) return;
+    setPass(null);
+    needsAttention = true;
+    notify();
+  }
+  function setPass(p) {
+    pass = p;
+    if (p === null) envelope = null;
+    armIdleLock();
+  }
+  const toCachedFiles = (snap) => snap.files.map((f) => ({
+    id: f.id,
+    name: f.name,
+    mime: f.mime,
+    blob: new Blob([f.bytes], { type: f.mime })
+  }));
+  async function cachedToSnapshot(local) {
+    return {
+      collections: local.collections,
+      files: await Promise.all(
+        local.files.map(async (f) => ({
+          id: f.id,
+          name: f.name,
+          mime: f.mime,
+          bytes: new Uint8Array(await f.blob.arrayBuffer())
+        }))
+      )
+    };
+  }
+  async function buildBlob(pre) {
+    if (requireEncryption && !encrypted && !group) {
+      throw new SelfstoreError(
+        "ENCRYPTION_REQUIRED",
+        "requireEncryption is set: refusing to build a plaintext backup."
+      );
+    }
+    const snap = pre ?? await gather();
+    let env;
+    if (encrypted && !group) {
+      if (!envelope && pass) {
+        const dataKey = crypto.getRandomValues(new Uint8Array(32));
+        envelope = { dataKey, slots: [await mintSlot(pass, dataKey)] };
+      }
+      env = envelope ?? void 0;
+      if (!env) {
+        throw new SelfstoreError(
+          "PASSWORD_REQUIRED",
+          "Cannot write the encrypted backup while locked - unlock first."
+        );
+      }
+    }
+    const stampV = Math.max(version, schemaCeiling);
+    const sidecar = { schemaVersion: stampV, meta };
+    const groupOpts = group ? {
+      recipients: [
+        .../* @__PURE__ */ new Set([...group.manifest.members.map((m) => m.enc), group.identity.encPub])
+      ],
+      sign: { pub: group.identity.sigPub, priv: group.identity.sigPriv }
+    } : void 0;
+    const bytes = await writeBox(
+      { collections: snap.collections, files: snap.files },
+      { app, appVersion, schemaVersion: stampV, envelope: env, group: groupOpts, readme },
+      sidecar
+    );
+    return new Blob([bytes], { type: BACKUP_MIME });
+  }
+  async function publishMirrors() {
+    if (mirrorList.length === 0 || locked() || needsAttention) return;
+    const snap = await gather();
+    for (const m of mirrorList) {
+      try {
+        if (!m.envelope) {
+          const dataKey = crypto.getRandomValues(new Uint8Array(32));
+          m.envelope = { dataKey, slots: [await mintSlot(m.password, dataKey)] };
+        }
+        const sidecar = { schemaVersion: version, meta };
+        const bytes = await writeBox(
+          { collections: snap.collections, files: snap.files },
+          { app, appVersion, schemaVersion: version, envelope: m.envelope, readme },
+          sidecar
+        );
+        await m.target.save(new Blob([bytes], { type: BACKUP_MIME }));
+        m.lastPublishAt = Date.now();
+        m.lastError = null;
+      } catch (e) {
+        m.lastError = isAuthExpired(e) ? storeError("AUTH_EXPIRED", "Write access to the mirror expired or was revoked.") : isSelfstoreError(e) ? storeError(e.code, e.message) : transient("Mirror momentarily unreachable.");
+        logger.warn(`[selfstore] mirror "${m.id}" publish failed`, e);
+      }
+    }
+    notify();
+  }
+  async function publishReplicas() {
+    if (replicaList.length === 0 || locked() || needsAttention) return;
+    let blob;
+    try {
+      blob = await buildBlob();
+    } catch (e) {
+      logger.warn("[selfstore] replica publish skipped (cannot build backup)", e);
+      return;
+    }
+    for (const r of replicaList) {
+      try {
+        await r.target.save(blob);
+        r.lastPublishAt = Date.now();
+        r.lastError = null;
+      } catch (e) {
+        r.lastError = isAuthExpired(e) ? storeError("AUTH_EXPIRED", "Write access to the replica expired or was revoked.") : isSelfstoreError(e) ? storeError(e.code, e.message) : transient("Replica momentarily unreachable.");
+        logger.warn(`[selfstore] replica "${r.id}" publish failed`, e);
+      }
+    }
+    notify();
+  }
+  function readBookkeeping(snap, sidecar) {
+    if (RESERVED in snap.collections) delete snap.collections[RESERVED];
+    const s = sidecar;
+    return { fromVersion: s?.schemaVersion ?? 0, sync: s?.meta ?? null };
+  }
+  const migrated = (snap, fromV) => opts.migrate && fromV < version ? opts.migrate(fromV, snap) : snap;
+  function mergeFiles(local, remote) {
+    const byId = /* @__PURE__ */ new Map();
+    for (const f of remote) byId.set(f.id, f);
+    for (const f of local) byId.set(f.id, f);
+    return [...byId.values()];
+  }
+  function warnUnsyncable(collections) {
+    const counts = unsyncableCounts(collections, sync);
+    for (const [name, n] of Object.entries(counts)) {
+      if (warnedNoId.has(name)) continue;
+      warnedNoId.add(name);
+      const path = idPathFor(sync, name);
+      logger.warn(
+        `[selfstore] ${n} record(s) in collection "${name}" have no string id at "${path}" and will NOT sync or persist reliably. selfstore identifies records by a string id. Give each record a string id, or map this collection's id field with createLocalStore({ sync: { ids: { ${JSON.stringify(name)}: 'yourIdField' } } }).`
+      );
+    }
+  }
+  async function persistLocal() {
+    if (!await foldTabWrites()) return;
+    const snap = await gather();
+    warnUnsyncable(snap.collections);
+    if (opts.tombstoneHorizonMs) meta = gcTombstones(meta, Date.now() - opts.tombstoneHorizonMs);
+    meta = stamp(meta, snap.collections, sync);
+    await cache.saveCollections(snap.collections);
+    await cache.saveFiles(toCachedFiles(snap));
+    await kv.set(KEY.syncMeta, meta);
+    await kv.set(KEY.version, Math.max(version, schemaCeiling));
+    lastSavedAt = Date.now();
+    await kv.set(KEY.lastSavedAt, lastSavedAt);
+    await publishWrite("change");
+  }
+  async function publishWrite(kind) {
+    seenEpoch = createNode();
+    await kv.set(KEY.epoch, seenEpoch);
+    channel?.postMessage({ tab: tabId, kind });
+  }
+  async function foldTabWrites() {
+    const current = await kv.get(KEY.epoch);
+    if (current === void 0 || current === seenEpoch) return true;
+    const local = await cache.load();
+    if (!local) {
+      seenEpoch = current;
+      return true;
+    }
+    const storedV = await kv.get(KEY.version) ?? version;
+    if (isNewerSchema(storedV)) {
+      gateNewerSchema(storedV);
+      seenEpoch = current;
+      return false;
+    }
+    const tabMeta = await kv.get(KEY.syncMeta);
+    if (!tabMeta) {
+      seenEpoch = current;
+      return true;
+    }
+    const snap = migrated(await cachedToSnapshot(local), storedV);
+    const live = await gather();
+    meta = stamp(meta, live.collections, sync);
+    const merged = merge(
+      { collections: live.collections, meta },
+      { collections: snap.collections, meta: tabMeta },
+      sync
+    );
+    meta = merged.meta;
+    apply({ collections: merged.collections, files: mergeFiles(live.files, snap.files) });
+    seenEpoch = current;
+    return true;
+  }
+  async function adoptTabState() {
+    const current = await kv.get(KEY.epoch);
+    if (current === seenEpoch) return;
+    const local = await cache.load();
+    const storedV = await kv.get(KEY.version) ?? version;
+    if (isNewerSchema(storedV)) gateNewerSchema(storedV);
+    if (local) apply(migrated(await cachedToSnapshot(local), storedV));
+    else apply({ collections: {}, files: [] });
+    meta = await kv.get(KEY.syncMeta) ?? createMeta();
+    baseMeta = await kv.get(KEY.baseMeta) ?? null;
+    lastSavedAt = await kv.get(KEY.lastSavedAt) ?? null;
+    remoteVersion = await kv.get(KEY.remoteVersion) ?? null;
+    lastSavedContentHash = await kv.get(KEY.savedHash) ?? null;
+    if (durable) {
+      encrypted = await kv.get(KEY.enc) === true;
+      needsAttention = needsAttention || locked();
+    }
+    seenEpoch = current;
+    notify();
+  }
+  function onTabMessage(kind) {
+    if (!ready || mode !== "persistent") return;
+    if (queuedKind) {
+      if (kind === "forget") queuedKind = "forget";
+      return;
+    }
+    queuedKind = kind;
+    serialize(async () => {
+      const k = queuedKind;
+      queuedKind = null;
+      if (k === "forget") {
+        clearTimeout(timer);
+        pendingEdit = false;
+        mode = await kv.get(KEY.mode) === "ephemeral" ? "ephemeral" : "persistent";
+        const savedKind = await kv.get(KEY.targetKind) ?? "device";
+        if (durable) {
+          await dropDurable({ keepSession: true });
+        }
+        targetKind = savedKind;
+        pendingDownload = false;
+        seenEpoch = void 0;
+        await adoptTabState();
+      } else if (pendingEdit) {
+        clearTimeout(timer);
+        await doSave();
+      } else {
+        await adoptTabState();
+      }
+    }).catch((e) => logger.error("[selfstore] cross-tab refresh failed", e));
+  }
+  if (channel) {
+    channel.onmessage = (ev) => {
+      const msg = ev.data;
+      if (msg && msg.tab !== tabId && (msg.kind === "change" || msg.kind === "forget")) {
+        onTabMessage(msg.kind);
+      }
+    };
+  }
+  async function takeFreshPrefetch(t) {
+    const p = prefetched;
+    prefetched = null;
+    if (!p || p.target !== t || p.marker === null) return null;
+    if (Date.now() - p.at > PREFETCH_TTL_MS) return null;
+    let now;
+    try {
+      now = t.stat ? await t.stat() : null;
+    } catch {
+      return null;
+    }
+    return now !== null && now === p.marker ? p.blob : null;
+  }
+  async function statRemote() {
+    if (!durable?.stat) return null;
+    try {
+      return await durable.stat();
+    } catch {
+      return null;
+    }
+  }
+  async function requireReady(where) {
+    let ok = false;
+    try {
+      ok = await durable.isReady();
+    } catch (e) {
+      if (isAuthExpired(e)) {
+        raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+      }
+      throw e;
+    }
+    if (!ok) {
+      throw new SelfstoreError(
+        "TARGET_WRITE_FAILED",
+        `${where}(): the destination is unreachable; try again online.`
+      );
+    }
+  }
+  async function setRemoteVersion(v) {
+    remoteVersion = v;
+    if (v === null) await kv.del(KEY.remoteVersion);
+    else await kv.set(KEY.remoteVersion, v);
+  }
+  function redactForStorage(entries) {
+    return entries.map(
+      (e) => e.conflicts ? { ...e, conflicts: e.conflicts.map(({ collection, id, kept }) => ({ collection, id, kept })) } : e
+    );
+  }
+  function recordJournal(delta, source, conflicts = []) {
+    const visible = Object.fromEntries(
+      Object.entries(delta).filter(([name]) => !journalSilent.has(name))
+    );
+    if (Object.keys(visible).length === 0) return null;
+    const entry = { at: Date.now(), source, changes: visible };
+    if (conflicts.length > 0) entry.conflicts = conflicts;
+    journal = [entry, ...journal].slice(0, JOURNAL_MAX);
+    lastSync = entry;
+    kvSetSafe(KEY.syncJournal, redactForStorage(journal), "journal");
+    return entry;
+  }
+  async function pushDurable(source = "push") {
+    if (!durable || locked() || needsAttention) return false;
+    try {
+      if (!await durable.isReady()) {
+        lastError = transient("Save deferred: destination momentarily unreachable.");
+        return false;
+      }
+      const seen = await statRemote();
+      if (seen !== null && remoteVersion !== null && seen !== remoteVersion) {
+        await pullRemoteIntoLocal(source, seen);
+        if (locked() || needsAttention) return false;
+      }
+      const snap = await gather();
+      const digest = await contentDigest(snap);
+      if (digest === lastSavedContentHash) {
+        lastError = null;
+        return true;
+      }
+      const written = await durable.save(await buildBlob(snap));
+      await setRemoteVersion(typeof written === "string" ? written : await statRemote());
+      lastSavedContentHash = digest;
+      kvSetSafe(KEY.savedHash, digest, "savedHash");
+      lastError = null;
+      return true;
+    } catch (e) {
+      if (isAuthExpired(e)) {
+        raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+      } else if (isSelfstoreError(e) && e.code === "TARGET_GONE") {
+        raiseGate("TARGET_GONE", e.message);
+      } else {
+        lastError = transient("Save deferred: destination momentarily unreachable.");
+      }
+      logger.error("[selfstore] push to durable failed", e);
+      return false;
+    }
+  }
+  async function contentDigest(snap) {
+    const enc = new TextEncoder();
+    const parts = [enc.encode(JSON.stringify(snap.collections))];
+    for (const f of [...snap.files].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+      parts.push(enc.encode(`${f.id}${f.mime}`), f.bytes);
+    }
+    let len = 0;
+    for (const p of parts) len += p.length;
+    const buf = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+      buf.set(p, off);
+      off += p.length;
+    }
+    const digest = await crypto.subtle.digest("SHA-256", buf);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  async function doSave() {
+    if (mode !== "persistent") return;
+    const seq = editSeq;
+    const digest = await contentDigest(await gather());
+    if (digest === lastSavedContentHash) {
+      if (editSeq === seq) pendingEdit = false;
+      return;
+    }
+    saving = true;
+    notify();
+    try {
+      await persistLocal();
+      if (editSeq === seq) pendingEdit = false;
+      if (targetKind === "file-manual") {
+        lastSavedContentHash = digest;
+        kvSetSafe(KEY.savedHash, digest, "savedHash");
+        pendingDownload = true;
+        return;
+      }
+      await pushDurable();
+      await publishMirrors();
+      await publishReplicas();
+    } finally {
+      saving = false;
+      notify();
+    }
+  }
+  const save = () => serialize(doSave);
+  async function isDowngraded(remote) {
+    if (!encrypted) return false;
+    try {
+      const h = await inspect(remote);
+      if (group) return h.keying !== GROUP_KEYING;
+      return h.encryption === "none";
+    } catch {
+      return false;
+    }
+  }
+  async function importLocked(remote) {
+    if (await isDowngraded(remote)) {
+      raiseGate(
+        "UNEXPECTEDLY_UNENCRYPTED",
+        group ? "Expected a signed group copy - found something else. Refused for safety." : "Unexpected unencrypted backup - refused for safety."
+      );
+      return "locked";
+    }
+    try {
+      const r = await readBoxWithSync(
+        await asBytes(remote),
+        pass ?? void 0,
+        ownGroupRead(),
+        envelope?.dataKey,
+        // Only during a passkey unlock (a user gesture) is a secret in hand for
+        // an external slot; a background converge has none and reads via the held
+        // data key or gates for the user to unlock.
+        pendingExternalSecret ? async () => pendingExternalSecret : void 0
+      );
+      if (!group) envelope = r.envelope ?? null;
+      return r;
+    } catch (e) {
+      if (isSelfstoreError(e) && (e.code === "PASSWORD_REQUIRED" || e.code === "DECRYPT_FAILED")) {
+        if (!encrypted) {
+          encrypted = true;
+          kvSetSafe(KEY.enc, true, "enc");
+        }
+        setPass(null);
+        raiseGate(e.code, e.message);
+        return "locked";
+      }
+      if (isSelfstoreError(e) && (e.code === "IDENTITY_REQUIRED" || e.code === "SIGNATURE_INVALID" || e.code === "NOT_A_RECIPIENT")) {
+        raiseGate(e.code, e.message);
+        return "locked";
+      }
+      throw e;
+    }
+  }
+  let schemaCeiling = version;
+  const isNewerSchema = (fromVersion) => fromVersion > version;
+  function gateNewerSchema(fromVersion) {
+    schemaCeiling = Math.max(schemaCeiling, fromVersion);
+    raiseGate(
+      "SCHEMA_TOO_NEW",
+      `Backup written by schema v${fromVersion}; this app reads v${version}. Update the app.`
+    );
+  }
+  async function convergeRemote(snap, sidecar, source) {
+    const { fromVersion, sync: remoteMeta } = readBookkeeping(snap, sidecar);
+    if (isNewerSchema(fromVersion)) {
+      gateNewerSchema(fromVersion);
+      return null;
+    }
+    const snapM = migrated(snap, fromVersion);
+    if (!remoteMeta) {
+      await adoptForeign(snapM);
+      return null;
+    }
+    const local = await gather();
+    meta = stamp(meta, local.collections, sync);
+    const localState = { collections: local.collections, meta };
+    const remoteState = { collections: snapM.collections, meta: remoteMeta };
+    const result = merge(localState, remoteState, sync);
+    const conflicts = detectConflicts(localState, remoteState, sync, baseMeta ?? void 0);
+    const delta = changes(local.collections, result.collections, sync);
+    meta = result.meta;
+    baseMeta = meta;
+    kvSetSafe(KEY.baseMeta, meta, "baseMeta");
+    apply({ collections: result.collections, files: mergeFiles(local.files, snapM.files) });
+    lastSavedContentHash = await contentDigest({
+      collections: snapM.collections,
+      files: snapM.files
+    });
+    kvSetSafe(KEY.savedHash, lastSavedContentHash, "savedHash");
+    await persistLocal();
+    if (conflicts.length) {
+      logger.warn(
+        "[selfstore] concurrent edits auto-resolved (latest kept): " + conflicts.map((c) => `${c.collection}/${c.id}`).join(", ")
+      );
+    }
+    return recordJournal(delta, source, conflicts);
+  }
+  async function pullRemoteIntoLocal(source, seen) {
+    if (!durable) return null;
+    const marker = seen === void 0 ? await statRemote() : seen;
+    let remote = null;
+    try {
+      remote = await takeFreshPrefetch(durable) ?? await durable.load();
+    } catch {
+    }
+    if (!remote) return null;
+    const decoded = await importLocked(remote);
+    if (decoded === "locked") return "locked";
+    const entry = await convergeRemote(decoded.snapshot, decoded.sidecar, source);
+    if (needsAttention) return "locked";
+    await setRemoteVersion(marker);
+    return entry;
+  }
+  async function foldPeers(source) {
+    if (peerList.length === 0 || locked() || needsAttention) return null;
+    let entry = null;
+    let folded = false;
+    for (const p of peerList) {
+      try {
+        let marker = null;
+        if (p.source.stat) {
+          try {
+            marker = await p.source.stat();
+          } catch (e) {
+            if (isAuthExpired(e)) throw e;
+            marker = null;
+          }
+          if (marker !== null && marker === p.lastSeen) {
+            p.lastError = null;
+            continue;
+          }
+        }
+        const remote = await p.source.load();
+        if (!remote) {
+          p.lastError = null;
+          p.lastSyncAt = Date.now();
+          continue;
+        }
+        if (p.password !== void 0) {
+          try {
+            if ((await inspect(remote)).encryption === "none") {
+              p.lastError = storeError(
+                "UNEXPECTEDLY_UNENCRYPTED",
+                "Peer copy unexpectedly unencrypted - refused for safety."
+              );
+              continue;
+            }
+          } catch {
+          }
+        } else if (await isDowngraded(remote)) {
+          p.lastError = storeError(
+            "UNEXPECTEDLY_UNENCRYPTED",
+            group ? "Peer copy is not a signed group copy - refused for safety." : "Peer copy unexpectedly unencrypted - refused for safety."
+          );
+          continue;
+        }
+        const { snapshot, sidecar, author, envelope: peerEnv } = await readBoxWithSync(
+          await asBytes(remote),
+          p.password ?? pass ?? void 0,
+          peerGroupRead(),
+          p.envelope?.dataKey
+          // reuse the data key: skip the Argon2 KDF unless rotated
+        );
+        if (peerEnv) p.envelope = peerEnv;
+        const { fromVersion, sync: peerMeta } = readBookkeeping(snapshot, sidecar);
+        if (isNewerSchema(fromVersion)) {
+          p.lastError = storeError(
+            "SCHEMA_TOO_NEW",
+            `Peer copy written by schema v${fromVersion}; this app reads v${version}.`
+          );
+          continue;
+        }
+        if (!peerMeta) {
+          p.lastError = storeError(
+            "BAD_FORMAT",
+            "Peer copy carries no sync metadata; not a published copy."
+          );
+          continue;
+        }
+        const snapM = migrated(snapshot, fromVersion);
+        const local = await gather();
+        meta = stamp(meta, local.collections, sync);
+        const localState = { collections: local.collections, meta };
+        const remoteState = { collections: snapM.collections, meta: peerMeta };
+        const result = merge(localState, remoteState, sync);
+        const conflicts = detectConflicts(localState, remoteState, sync, baseMeta ?? void 0);
+        const delta = changes(local.collections, result.collections, sync);
+        meta = result.meta;
+        baseMeta = meta;
+        kvSetSafe(KEY.baseMeta, meta, "baseMeta");
+        apply({ collections: result.collections, files: mergeFiles(local.files, snapM.files) });
+        folded = true;
+        entry = recordJournal(delta, source, conflicts) ?? entry;
+        p.lastError = null;
+        p.lastSyncAt = Date.now();
+        p.lastSeen = marker;
+        p.author = author ? group?.manifest.members.find((m) => m.sig === author)?.id ?? null : null;
+      } catch (e) {
+        p.lastError = isAuthExpired(e) ? storeError("AUTH_EXPIRED", "Read access to the peer copy expired or was revoked.") : isSelfstoreError(e) ? storeError(e.code, e.message) : transient("Peer momentarily unreachable.");
+        logger.warn(`[selfstore] peer "${p.id}" fold failed`, e);
+      }
+    }
+    if (folded) await persistLocal();
+    return entry;
+  }
+  async function anyPeerMoved() {
+    for (const p of peerList) {
+      if (!p.source.stat) return true;
+      try {
+        const marker = await p.source.stat();
+        if (marker === null || marker !== p.lastSeen) return true;
+      } catch {
+        return true;
+      }
+    }
+    return false;
+  }
+  async function doPull(source) {
+    if (!durable && peerList.length === 0 && mirrorList.length === 0) return null;
+    let entry = null;
+    if (durable) {
+      const r = await pullRemoteIntoLocal(source);
+      if (r === "locked") return null;
+      entry = r;
+    }
+    entry = await foldPeers(source) ?? entry;
+    if (durable) await pushDurable(source);
+    if (entry !== null || source === "connect") {
+      await publishMirrors();
+      await publishReplicas();
+    }
+    notify();
+    return entry;
+  }
+  const pull = (source) => serialize(() => doPull(source));
+  async function loadFromRemote() {
+    if (!durable) return;
+    const remote = await takeFreshPrefetch(durable) ?? await durable.load();
+    if (remote) {
+      const decoded = await importLocked(remote);
+      if (decoded === "locked") return;
+      const { fromVersion } = readBookkeeping(decoded.snapshot, decoded.sidecar);
+      if (isNewerSchema(fromVersion)) {
+        gateNewerSchema(fromVersion);
+        return;
+      }
+      apply(migrated(decoded.snapshot, fromVersion));
+      await persistLocal();
+    }
+    await pushDurable();
+  }
+  async function adoptForeign(snap) {
+    const local = await cache.load();
+    if (local) return;
+    apply(snap);
+    await persistLocal();
+  }
+  async function becomePersistent() {
+    if (mode !== "persistent") {
+      mode = "persistent";
+      await kv.set(KEY.mode, "persistent");
+    }
+    await cache.requestPersistent?.();
+  }
+  async function dropDurable({ keepSession = false } = {}) {
+    if (durable && !keepSession) await durable.disconnect();
+    durable = null;
+    label = null;
+    encrypted = false;
+    needsAttention = false;
+    pendingDownload = false;
+    setPass(null);
+    group = null;
+    await kv.del(KEY.enc);
+    await setRemoteVersion(null);
+    lastSavedContentHash = null;
+    await kv.del(KEY.savedHash);
+  }
+  async function doForget() {
+    apply({ collections: {}, files: [] });
+    if (durable && !locked() && !needsAttention) {
+      await persistLocal();
+      await pushDurable();
+    } else {
+      const seqIds = await kv.get(KEY.groupSeqIds) ?? [];
+      const savedSeqs = [];
+      for (const id of seqIds) {
+        const v = await kv.get(groupSeqKey(id));
+        if (v !== void 0) savedSeqs.push([id, v]);
+      }
+      meta = createMeta();
+      await cache.clear();
+      await dropDurable();
+      for (const [id, v] of savedSeqs) await persistGroupSeq(id, v);
+      mode = "persistent";
+      targetKind = "device";
+      lastSavedAt = null;
+      await kv.set(KEY.mode, "persistent");
+      await kv.set(KEY.targetKind, "device");
+      await kv.set(KEY.syncMeta, meta);
+      await kv.del(KEY.lastSavedAt);
+      await publishWrite("forget");
+    }
+    notify();
+  }
+  function buildState() {
+    return {
+      ready,
+      mode,
+      targetKind,
+      label,
+      encrypted,
+      locked: locked(),
+      saving,
+      lastSavedAt,
+      status: deriveStatus({
+        persistent: mode === "persistent",
+        targetKind,
+        saving,
+        needsAttention,
+        locked: locked(),
+        pendingDownload
+      }),
+      lastError,
+      journal,
+      lastSync,
+      peers: peerList.map(({ id, label: l, lastSyncAt, author, lastError: err }) => ({
+        id,
+        label: l,
+        lastSyncAt,
+        author,
+        lastError: err
+      })),
+      mirrors: mirrorList.map(({ id, label: l, lastPublishAt, lastError: err }) => ({
+        id,
+        label: l,
+        lastPublishAt,
+        lastError: err
+      })),
+      replicas: replicaList.map(({ id, label: l, lastPublishAt, lastError: err }) => ({
+        id,
+        label: l,
+        lastPublishAt,
+        lastError: err
+      }))
+    };
+  }
+  stateSnapshot = buildState();
+  return {
+    get state() {
+      return stateSnapshot;
+    },
+    subscribe(fn) {
+      subs.add(fn);
+      return () => subs.delete(fn);
+    },
+    async init() {
+      mode = await kv.get(KEY.mode) === "ephemeral" ? "ephemeral" : "persistent";
+      if (mode === "ephemeral") {
+        ready = true;
+        notify();
+        return;
+      }
+      void Promise.resolve(cache.requestPersistent?.()).catch(() => void 0);
+      const local = await cache.load();
+      if (local) {
+        const snap = await cachedToSnapshot(local);
+        const storedV = await kv.get(KEY.version) ?? version;
+        if (isNewerSchema(storedV)) gateNewerSchema(storedV);
+        apply(migrated(snap, storedV));
+      }
+      lastSavedAt = await kv.get(KEY.lastSavedAt) ?? null;
+      lastSavedContentHash = await kv.get(KEY.savedHash) ?? null;
+      meta = await kv.get(KEY.syncMeta) ?? createMeta();
+      await kv.set(KEY.syncMeta, meta);
+      baseMeta = await kv.get(KEY.baseMeta) ?? null;
+      remoteVersion = await kv.get(KEY.remoteVersion) ?? null;
+      journal = await kv.get(KEY.syncJournal) ?? [];
+      seenEpoch = await kv.get(KEY.epoch);
+      const savedKind = await kv.get(KEY.targetKind) ?? "device";
+      if (!isReservedStoreMode(savedKind)) {
+        encrypted = await kv.get(KEY.enc) === true;
+        targetKind = savedKind;
+        notify();
+        let t = null;
+        let restoreThrew = false;
+        try {
+          t = opts.restoreTarget ? await opts.restoreTarget(savedKind) : null;
+        } catch (e) {
+          restoreThrew = true;
+          lastError = transient("Could not restore the destination; will retry.");
+          logger.error("[selfstore] restoreTarget failed", e);
+        }
+        if (t) {
+          durable = t;
+          targetKind = savedKind;
+          label = t.label;
+          let ok = false;
+          try {
+            ok = await t.isReady();
+          } catch {
+            raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+          }
+          needsAttention = needsAttention || locked();
+          if (ok && !locked()) {
+            try {
+              await pull("boot");
+            } catch (e) {
+              lastError = transient("Boot sync failed; will retry.");
+              logger.error("[selfstore] boot sync failed", e);
+            }
+          }
+        } else if (!restoreThrew) {
+          targetKind = "device";
+          await kv.set(KEY.targetKind, "device");
+        }
+      } else if (savedKind === "file-manual") {
+        targetKind = "file-manual";
+        pendingDownload = false;
+      }
+      if (!durable && peerList.length > 0) {
+        try {
+          await pull("boot");
+        } catch (e) {
+          lastError = transient("Boot sync failed; will retry.");
+          logger.error("[selfstore] boot sync failed", e);
+        }
+      }
+      ready = true;
+      notify();
+    },
+    schedule() {
+      if (!ready) return;
+      pendingEdit = true;
+      editSeq++;
+      clearTimeout(timer);
+      timer = setTimeout(
+        () => save().catch((e) => logger.error("[selfstore] scheduled save failed", e)),
+        debounceMs
+      );
+      armIdleLock();
+    },
+    lock: lockNow,
+    async flush() {
+      if (!ready) return;
+      clearTimeout(timer);
+      if (mode === "persistent") await save();
+    },
+    syncIfStale(source) {
+      return serialize(async () => {
+        if (locked() || needsAttention || mode !== "persistent") return;
+        if (!durable?.stat && peerList.length === 0) return;
+        const nowMs = Date.now();
+        if (nowMs - lastStaleCheck < STALE_CHECK_MS) return;
+        lastStaleCheck = nowMs;
+        let moved = false;
+        if (durable?.stat) {
+          const seen = await statRemote();
+          moved = seen !== null && seen !== remoteVersion;
+        }
+        if (!moved) moved = await anyPeerMoved();
+        if (!moved) return;
+        try {
+          await doPull(source);
+        } catch (e) {
+          lastError = transient("Background sync failed; will retry.");
+          logger.error("[selfstore] background sync failed", e);
+          notify();
+        }
+      });
+    },
+    syncNow() {
+      return serialize(() => {
+        lastStaleCheck = Date.now();
+        return doPull("manual");
+      });
+    },
+    attachTarget(target, attachOpts) {
+      if (isReservedStoreMode(target.kind)) {
+        throw new TypeError(
+          `attachTarget(): kind "${target.kind}" is a reserved store mode, not a target kind - pick any other string`
+        );
+      }
+      const cfg = attachOpts?.group ?? null;
+      if (cfg && attachOpts?.password) {
+        throw new TypeError(
+          "attachTarget(): `group` and `password` are mutually exclusive - a group is keyed by member identities."
+        );
+      }
+      if (requireEncryption && !attachOpts?.password && !cfg) {
+        throw new SelfstoreError(
+          "ENCRYPTION_REQUIRED",
+          "attachTarget(): this store requires encryption - attach with a password or a group."
+        );
+      }
+      if (attachOpts?.password) assertPasswordPolicy(attachOpts.password);
+      return serialize(async () => {
+        const g = cfg ? {
+          identity: cfg.identity,
+          admin: cfg.admin,
+          manifest: await openManifest(cfg.manifest, cfg.admin)
+        } : null;
+        if (g && !g.manifest.members.some((m) => m.sig === g.identity.sigPub)) {
+          throw new TypeError(
+            "attachTarget(): this identity is not a member of the manifest - the admin must add it first."
+          );
+        }
+        await becomePersistent();
+        const strategy = attachOpts?.strategy ?? "merge";
+        if (strategy === "replace-local" && durable && !locked() && !needsAttention) {
+          try {
+            await persistLocal();
+            await pushDurable("push");
+          } catch {
+          }
+        }
+        if (g) {
+          const stored = await kv.get(groupSeqKey(g.manifest.group));
+          if (stored !== void 0 && g.manifest.seq < stored) {
+            throw new SelfstoreError(
+              "MANIFEST_ROLLBACK",
+              `Manifest seq ${g.manifest.seq} is older than the last applied (${stored}).`
+            );
+          }
+          await persistGroupSeq(g.manifest.group, Math.max(stored ?? 0, g.manifest.seq));
+        }
+        await dropDurable({ keepSession: attachOpts?.keepSession });
+        if (attachOpts?.wipe) {
+          apply({ collections: {}, files: [] });
+          meta = createMeta();
+          baseMeta = null;
+          await kv.set(KEY.syncMeta, meta);
+          await kv.del(KEY.baseMeta);
+        }
+        durable = target;
+        targetKind = target.kind;
+        label = target.label;
+        const next = attachOpts?.password ?? null;
+        group = g;
+        encrypted = !!next || !!g;
+        setPass(next);
+        envelope = null;
+        await kv.set(KEY.enc, encrypted);
+        await kv.set(KEY.targetKind, target.kind);
+        needsAttention = false;
+        notify();
+        if (strategy === "replace-local") await loadFromRemote();
+        else if (strategy === "replace-remote") await doSave();
+        else await doPull("connect");
+        notify();
+      });
+    },
+    async inspectTarget(target) {
+      const blob = await target.load();
+      if (!blob || blob.size === 0) return { hasBackup: false, date: null, encrypted: false };
+      let marker = null;
+      try {
+        marker = target.stat ? await target.stat() : null;
+      } catch {
+        marker = null;
+      }
+      prefetched = { target, blob, marker, at: Date.now() };
+      const header = await inspect(blob);
+      return {
+        hasBackup: true,
+        date: header.createdAt ?? null,
+        encrypted: header.encryption !== "none"
+      };
+    },
+    setManualFile() {
+      return serialize(async () => {
+        await becomePersistent();
+        await dropDurable();
+        targetKind = "file-manual";
+        pendingDownload = false;
+        await kv.set(KEY.targetKind, "file-manual");
+        await persistLocal();
+        notify();
+      });
+    },
+    async unlock(password) {
+      if (!locked() || !password) return false;
+      setPass(password);
+      needsAttention = schemaCeiling > version;
+      await pull("manual");
+      return !needsAttention;
+    },
+    async reconnect() {
+      if (locked() || !durable) return false;
+      if (await durable.reconnect()) {
+        needsAttention = schemaCeiling > version;
+        if (!needsAttention) lastError = null;
+        await pull("manual");
+        return !needsAttention;
+      }
+      return false;
+    },
+    detachTarget(opts2) {
+      return serialize(async () => {
+        await dropDurable({ keepSession: opts2?.keepSession });
+        targetKind = "device";
+        await kv.set(KEY.targetKind, "device");
+        notify();
+      });
+    },
+    setGroup(next) {
+      if (!group) {
+        throw new TypeError("setGroup(): no group attached - attachTarget with { group } first.");
+      }
+      return serialize(async () => {
+        const manifest = await openManifest(next, group.admin, group.manifest.group);
+        const key = groupSeqKey(manifest.group);
+        const stored = await kv.get(key) ?? 0;
+        const floor = Math.max(stored, group.manifest.seq);
+        if (manifest.seq < floor) {
+          throw new SelfstoreError(
+            "MANIFEST_ROLLBACK",
+            `Manifest seq ${manifest.seq} is older than the last applied (${floor}).`
+          );
+        }
+        await persistGroupSeq(manifest.group, Math.max(stored, manifest.seq));
+        group = { ...group, manifest };
+        notify();
+        lastSavedContentHash = null;
+        await doSave();
+      });
+    },
+    attachPeer(source, peerOpts) {
+      const id = peerOpts?.id ?? createNode();
+      if (peerList.some((p) => p.id === id)) {
+        throw new TypeError(`attachPeer(): a peer with id "${id}" is already attached`);
+      }
+      peerList.push({
+        id,
+        source,
+        password: peerOpts?.password,
+        label: source.label ?? id,
+        lastSyncAt: null,
+        author: null,
+        lastError: null,
+        lastSeen: null,
+        envelope: null
+      });
+      notify();
+      if (ready) {
+        void serialize(() => doPull("connect")).catch(
+          (e) => logger.error("[selfstore] peer converge failed", e)
+        );
+      }
+      return id;
+    },
+    detachPeer(id) {
+      const i = peerList.findIndex((p) => p.id === id);
+      if (i >= 0) {
+        peerList.splice(i, 1);
+        notify();
+      }
+    },
+    attachMirror(target, mirrorOpts) {
+      const id = mirrorOpts.id ?? createNode();
+      if (mirrorList.some((m) => m.id === id)) {
+        throw new TypeError(`attachMirror(): a mirror with id "${id}" is already attached`);
+      }
+      mirrorList.push({
+        id,
+        target,
+        password: mirrorOpts.password,
+        envelope: null,
+        label: target.label ?? id,
+        lastPublishAt: null,
+        lastError: null
+      });
+      notify();
+      if (ready) {
+        void serialize(publishMirrors).catch(
+          (e) => logger.error("[selfstore] mirror publish failed", e)
+        );
+      }
+      return id;
+    },
+    detachMirror(id) {
+      const i = mirrorList.findIndex((m) => m.id === id);
+      if (i >= 0) {
+        mirrorList.splice(i, 1);
+        notify();
+      }
+    },
+    attachReplica(target, replicaOpts) {
+      const id = replicaOpts?.id ?? createNode();
+      if (replicaList.some((r) => r.id === id)) {
+        throw new TypeError(`attachReplica(): a replica with id "${id}" is already attached`);
+      }
+      replicaList.push({ id, target, label: target.label ?? id, lastPublishAt: null, lastError: null });
+      notify();
+      if (ready) {
+        void serialize(publishReplicas).catch(
+          (e) => logger.error("[selfstore] replica publish failed", e)
+        );
+      }
+      return id;
+    },
+    detachReplica(id) {
+      const i = replicaList.findIndex((r) => r.id === id);
+      if (i >= 0) {
+        replicaList.splice(i, 1);
+        notify();
+      }
+    },
+    exportBlob() {
+      return buildBlob();
+    },
+    markDownloaded() {
+      pendingDownload = false;
+      notify();
+    },
+    setEphemeral() {
+      mode = "ephemeral";
+      kvSetSafe(KEY.mode, "ephemeral", "mode");
+      notify();
+    },
+    async leaveEphemeral() {
+      await becomePersistent();
+      await save();
+    },
+    forget() {
+      return serialize(doForget);
+    },
+    async setEncryption(password) {
+      if (group) {
+        throw new TypeError(
+          "setEncryption(): the store is in group mode - encryption is keyed by the membership manifest (setGroup), not a password."
+        );
+      }
+      if (requireEncryption && !password) {
+        throw new SelfstoreError(
+          "ENCRYPTION_REQUIRED",
+          "setEncryption(): this store requires encryption - the password cannot be removed."
+        );
+      }
+      if (password) assertPasswordPolicy(password);
+      if (!durable) {
+        throw new SelfstoreError("NOT_CONNECTED", "setEncryption(): no destination is connected.");
+      }
+      if (locked() || needsAttention) {
+        throw new SelfstoreError(
+          "TARGET_WRITE_FAILED",
+          "setEncryption(): the store needs attention; resolve it before changing encryption."
+        );
+      }
+      return serialize(async () => {
+        await requireReady("setEncryption");
+        const seen = await statRemote();
+        if (seen !== null && remoteVersion !== null && seen !== remoteVersion) {
+          await pullRemoteIntoLocal("push", seen);
+          if (locked() || needsAttention) {
+            throw new SelfstoreError(
+              "TARGET_WRITE_FAILED",
+              "setEncryption(): the pre-rewrite converge needs attention; resolve it first."
+            );
+          }
+        }
+        const prevEncrypted = encrypted;
+        const prevPass = pass;
+        const prevEnvelope = envelope;
+        encrypted = !!password;
+        setPass(password || null);
+        envelope = null;
+        try {
+          await persistLocal();
+          pendingEdit = false;
+          const written = await durable.save(await buildBlob());
+          await setRemoteVersion(typeof written === "string" ? written : await statRemote());
+          lastError = null;
+          await kv.set(KEY.enc, encrypted);
+        } catch (e) {
+          encrypted = prevEncrypted;
+          setPass(prevPass);
+          envelope = prevEnvelope;
+          await persistLocal().catch(() => void 0);
+          if (isAuthExpired(e)) {
+            raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+          }
+          throw e;
+        } finally {
+          notify();
+        }
+      });
+    },
+    async addEncryptionKey(password, id) {
+      if (group) {
+        throw new TypeError(
+          "addEncryptionKey(): the store is in group mode - keys come from the membership manifest (setGroup), not passwords."
+        );
+      }
+      if (!password) {
+        throw new TypeError("addEncryptionKey(): a non-empty password is required.");
+      }
+      assertPasswordPolicy(password);
+      if (!durable) {
+        throw new SelfstoreError("NOT_CONNECTED", "addEncryptionKey(): no destination is connected.");
+      }
+      if (locked() || needsAttention) {
+        throw new SelfstoreError(
+          "TARGET_WRITE_FAILED",
+          "addEncryptionKey(): the store needs attention; resolve it before changing keys."
+        );
+      }
+      if (!encrypted || !pass) {
+        throw new TypeError(
+          "addEncryptionKey(): the backup has no password yet - setEncryption(password) first."
+        );
+      }
+      return serialize(async () => {
+        await requireReady("addEncryptionKey");
+        const seen = await statRemote();
+        if (seen !== null && remoteVersion !== null && seen !== remoteVersion) {
+          await pullRemoteIntoLocal("push", seen);
+          if (locked() || needsAttention) {
+            throw new SelfstoreError(
+              "TARGET_WRITE_FAILED",
+              "addEncryptionKey(): the pre-rewrite converge needs attention; resolve it first."
+            );
+          }
+        }
+        if (!envelope) {
+          const dataKey = crypto.getRandomValues(new Uint8Array(32));
+          envelope = { dataKey, slots: [await mintSlot(pass, dataKey)] };
+        }
+        if (envelope.slots.length >= MAX_KEY_SLOTS) {
+          throw new TypeError(`addEncryptionKey(): this backup already has ${MAX_KEY_SLOTS} key slots.`);
+        }
+        if (id && envelope.slots.some((s) => s.id === id)) {
+          throw new TypeError(`addEncryptionKey(): a key slot named "${id}" already exists.`);
+        }
+        const prevEnvelope = envelope;
+        const slot = await mintSlot(password, envelope.dataKey, id);
+        envelope = { dataKey: envelope.dataKey, slots: [...envelope.slots, slot] };
+        try {
+          const blob = await buildBlob();
+          await readBoxWithSync(await asBytes(blob), password);
+          const written = await durable.save(blob);
+          await setRemoteVersion(typeof written === "string" ? written : await statRemote());
+          lastError = null;
+          return slot.id;
+        } catch (e) {
+          envelope = prevEnvelope;
+          if (isAuthExpired(e)) {
+            raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+          }
+          throw e;
+        } finally {
+          notify();
+        }
+      });
+    },
+    async removeEncryptionKey(id) {
+      if (group) {
+        throw new TypeError(
+          "removeEncryptionKey(): the store is in group mode - keys come from the membership manifest (setGroup), not passwords."
+        );
+      }
+      if (!durable) {
+        throw new SelfstoreError("NOT_CONNECTED", "removeEncryptionKey(): no destination is connected.");
+      }
+      if (locked() || needsAttention) {
+        throw new SelfstoreError(
+          "TARGET_WRITE_FAILED",
+          "removeEncryptionKey(): the store needs attention; resolve it before changing keys."
+        );
+      }
+      if (!encrypted || !pass) {
+        throw new TypeError("removeEncryptionKey(): the backup has no password.");
+      }
+      return serialize(async () => {
+        await requireReady("removeEncryptionKey");
+        const seen = await statRemote();
+        if (seen !== null && remoteVersion !== null && seen !== remoteVersion) {
+          await pullRemoteIntoLocal("push", seen);
+          if (locked() || needsAttention) {
+            throw new SelfstoreError(
+              "TARGET_WRITE_FAILED",
+              "removeEncryptionKey(): the pre-rewrite converge needs attention; resolve it first."
+            );
+          }
+        }
+        if (!envelope) {
+          throw new TypeError(
+            "removeEncryptionKey(): no key slots known - the file predates the envelope or has not been read yet."
+          );
+        }
+        const remaining = envelope.slots.filter((s) => s.id !== id);
+        if (remaining.length === envelope.slots.length) {
+          throw new TypeError(`removeEncryptionKey(): no key slot named "${id}".`);
+        }
+        if (remaining.length === 0) {
+          throw new TypeError(
+            "removeEncryptionKey(): cannot remove the last key - setEncryption(null) decrypts instead."
+          );
+        }
+        let stillOpens = remaining.some((s) => s.kind === "external");
+        for (const s of remaining) {
+          if (stillOpens) break;
+          if (s.kind === "external") continue;
+          if (await openSlot(s, pass)) {
+            stillOpens = true;
+            break;
+          }
+        }
+        if (!stillOpens) {
+          throw new TypeError(
+            "removeEncryptionKey(): removing this slot would lock this session out - rotate with setEncryption(password) instead."
+          );
+        }
+        const prevEnvelope = envelope;
+        envelope = { dataKey: envelope.dataKey, slots: remaining };
+        try {
+          const blob = await buildBlob();
+          await readBoxWithSync(await asBytes(blob), pass);
+          const written = await durable.save(blob);
+          await setRemoteVersion(typeof written === "string" ? written : await statRemote());
+          lastError = null;
+        } catch (e) {
+          envelope = prevEnvelope;
+          if (isAuthExpired(e)) {
+            raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+          }
+          throw e;
+        } finally {
+          notify();
+        }
+      });
+    },
+    async setExternalEncryption(secret, keyRef) {
+      if (group) {
+        throw new TypeError(
+          "setExternalEncryption(): the store is in group mode - keys come from the membership manifest (setGroup), not an external key."
+        );
+      }
+      if (!durable) {
+        throw new SelfstoreError("NOT_CONNECTED", "setExternalEncryption(): no destination is connected.");
+      }
+      if (locked() || needsAttention) {
+        throw new SelfstoreError(
+          "TARGET_WRITE_FAILED",
+          "setExternalEncryption(): the store needs attention; resolve it before changing encryption."
+        );
+      }
+      return serialize(async () => {
+        await requireReady("setExternalEncryption");
+        const seen = await statRemote();
+        if (seen !== null && remoteVersion !== null && seen !== remoteVersion) {
+          await pullRemoteIntoLocal("push", seen);
+          if (locked() || needsAttention) {
+            throw new SelfstoreError(
+              "TARGET_WRITE_FAILED",
+              "setExternalEncryption(): the pre-rewrite converge needs attention; resolve it first."
+            );
+          }
+        }
+        const prevEncrypted = encrypted;
+        const prevPass = pass;
+        const prevEnvelope = envelope;
+        const dataKey = crypto.getRandomValues(new Uint8Array(32));
+        const slot = await mintExternalSlot(secret, keyRef, dataKey);
+        encrypted = true;
+        pass = null;
+        envelope = { dataKey, slots: [slot] };
+        armIdleLock();
+        try {
+          await persistLocal();
+          pendingEdit = false;
+          const blob = await buildBlob();
+          await readBoxWithSync(await asBytes(blob), void 0, void 0, void 0, async () => secret);
+          const written = await durable.save(blob);
+          await setRemoteVersion(typeof written === "string" ? written : await statRemote());
+          lastError = null;
+          await kv.set(KEY.enc, true);
+        } catch (e) {
+          encrypted = prevEncrypted;
+          pass = prevPass;
+          envelope = prevEnvelope;
+          armIdleLock();
+          await persistLocal().catch(() => void 0);
+          if (isAuthExpired(e)) {
+            raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+          }
+          throw e;
+        } finally {
+          notify();
+        }
+      });
+    },
+    async addExternalKey(secret, keyRef, id) {
+      if (group) {
+        throw new TypeError(
+          "addExternalKey(): the store is in group mode - keys come from the membership manifest (setGroup)."
+        );
+      }
+      if (!durable) {
+        throw new SelfstoreError("NOT_CONNECTED", "addExternalKey(): no destination is connected.");
+      }
+      if (locked() || needsAttention) {
+        throw new SelfstoreError(
+          "TARGET_WRITE_FAILED",
+          "addExternalKey(): the store needs attention; resolve it before changing keys."
+        );
+      }
+      if (!encrypted) {
+        throw new TypeError(
+          "addExternalKey(): the backup is not encrypted yet - setEncryption(password) or setExternalEncryption(secret, ref) first."
+        );
+      }
+      return serialize(async () => {
+        await requireReady("addExternalKey");
+        const seen = await statRemote();
+        if (seen !== null && remoteVersion !== null && seen !== remoteVersion) {
+          await pullRemoteIntoLocal("push", seen);
+          if (locked() || needsAttention) {
+            throw new SelfstoreError(
+              "TARGET_WRITE_FAILED",
+              "addExternalKey(): the pre-rewrite converge needs attention; resolve it first."
+            );
+          }
+        }
+        if (!envelope && pass) {
+          const dataKey = crypto.getRandomValues(new Uint8Array(32));
+          envelope = { dataKey, slots: [await mintSlot(pass, dataKey)] };
+        }
+        if (!envelope) {
+          throw new TypeError("addExternalKey(): no data key in hand - unlock the backup first.");
+        }
+        if (envelope.slots.length >= MAX_KEY_SLOTS) {
+          throw new TypeError(`addExternalKey(): this backup already has ${MAX_KEY_SLOTS} key slots.`);
+        }
+        if (id && envelope.slots.some((s) => s.id === id)) {
+          throw new TypeError(`addExternalKey(): a key slot named "${id}" already exists.`);
+        }
+        const prevEnvelope = envelope;
+        const slot = await mintExternalSlot(secret, keyRef, envelope.dataKey, id);
+        envelope = { dataKey: envelope.dataKey, slots: [...envelope.slots, slot] };
+        try {
+          const blob = await buildBlob();
+          await readBoxWithSync(await asBytes(blob), void 0, void 0, void 0, async () => secret);
+          const written = await durable.save(blob);
+          await setRemoteVersion(typeof written === "string" ? written : await statRemote());
+          lastError = null;
+          return slot.id;
+        } catch (e) {
+          envelope = prevEnvelope;
+          if (isAuthExpired(e)) {
+            raiseGate("AUTH_EXPIRED", "Access to the destination expired or was revoked.");
+          }
+          throw e;
+        } finally {
+          notify();
+        }
+      });
+    },
+    async unlockWithExternal(secret) {
+      if (!locked() || !durable) return false;
+      pendingExternalSecret = secret;
+      needsAttention = schemaCeiling > version;
+      try {
+        await pull("manual");
+      } finally {
+        pendingExternalSecret = null;
+      }
+      return !locked() && !needsAttention;
+    },
+    listEncryptionKeys() {
+      return (envelope?.slots ?? []).map((s) => ({
+        id: s.id,
+        kind: s.kind === "external" ? "external" : "password"
+      }));
+    },
+    dispose() {
+      clearTimeout(timer);
+      clearTimeout(idleTimer);
+      channel?.close();
+      subs.clear();
+    }
+  };
+}
+function isLockableCache(cache) {
+  return typeof cache.unlock === "function";
+}
+function memoryCache() {
+  const kvMap = /* @__PURE__ */ new Map();
+  let collections;
+  const files = /* @__PURE__ */ new Map();
+  return {
+    kv: {
+      async get(key) {
+        return kvMap.get(key);
+      },
+      async set(key, value) {
+        kvMap.set(key, value);
+      },
+      async del(key) {
+        kvMap.delete(key);
+      }
+    },
+    async load() {
+      if (collections === void 0) return null;
+      return { collections: structuredClone(collections), files: [...files.values()] };
+    },
+    async saveCollections(c) {
+      collections = structuredClone(c);
+    },
+    async saveFiles(fs) {
+      files.clear();
+      for (const f of fs) files.set(f.id, f);
+    },
+    async clear() {
+      kvMap.clear();
+      collections = void 0;
+      files.clear();
+    }
+  };
+}
+var COLLECTIONS_KEY = "__collections";
+var DEVICE_KEY = "__deviceKey";
+var CACHE_KDF = "__cacheKdf";
+function indexedDbCache(name, opts) {
+  let _db = null;
+  const db = () => _db ??= openDB(name, 1, {
+    upgrade(d) {
+      d.createObjectStore("kv");
+      d.createObjectStore("files");
+    }
+  });
+  const lockMode = opts?.lock === true;
+  let sealKey = null;
+  let _key = null;
+  function key() {
+    if (lockMode) {
+      return sealKey ? Promise.resolve(sealKey) : Promise.reject(
+        new SelfstoreError("PASSWORD_REQUIRED", "The local cache is locked - unlock() it first.")
+      );
+    }
+    return _key ??= loadOrCreateKey();
+  }
+  async function loadOrCreateKey() {
+    const d = await db();
+    const existing = await d.get("kv", DEVICE_KEY);
+    if (existing) return existing;
+    const fresh = await newDeviceKey();
+    const tx = d.transaction("kv", "readwrite");
+    if (!await tx.store.get(DEVICE_KEY)) await tx.store.put(fresh, DEVICE_KEY);
+    await tx.done;
+    return await d.get("kv", DEVICE_KEY);
+  }
+  async function decodeFile(v) {
+    if (!isEnvelope(v)) {
+      throw new SelfstoreError("BAD_FORMAT", "Unrecognized cache record (not a sealed envelope).");
+    }
+    const bytes = await unseal(await key(), v);
+    return { name: v.name, mime: v.mime, blob: new Blob([bytes], { type: v.mime }) };
+  }
+  const kv = {
+    async get(key2) {
+      return await (await db()).get("kv", `m:${key2}`);
+    },
+    async set(key2, value) {
+      await (await db()).put("kv", value, `m:${key2}`);
+    },
+    async del(key2) {
+      await (await db()).delete("kv", `m:${key2}`);
+    }
+  };
+  const base = {
+    kv,
+    async load() {
+      const d = await db();
+      const rawCollections = await d.get("kv", COLLECTIONS_KEY);
+      if (rawCollections === void 0) return null;
+      if (!isEnvelope(rawCollections)) {
+        throw new SelfstoreError("BAD_FORMAT", "Unrecognized cache record (not a sealed envelope).");
+      }
+      const collections = JSON.parse(
+        new TextDecoder().decode(await unseal(await key(), rawCollections))
+      );
+      const files = [];
+      for (const fileKey of await d.getAllKeys("files")) {
+        const v = await d.get("files", fileKey);
+        if (v) files.push({ id: String(fileKey), ...await decodeFile(v) });
+      }
+      return { collections, files };
+    },
+    async saveCollections(collections) {
+      const bytes = new TextEncoder().encode(JSON.stringify(collections));
+      const env = await seal(await key(), bytes);
+      await (await db()).put("kv", env, COLLECTIONS_KEY);
+    },
+    async saveFiles(files) {
+      const d = await db();
+      const have = new Set((await d.getAllKeys("files")).map(String));
+      const want = new Set(files.map((f) => f.id));
+      const k = await key();
+      const fresh = await Promise.all(
+        files.filter((f) => !have.has(f.id)).map(async (f) => {
+          const env = await seal(k, new Uint8Array(await f.blob.arrayBuffer()));
+          return { id: f.id, rec: { name: f.name, mime: f.mime, ...env } };
+        })
+      );
+      const tx = d.transaction("files", "readwrite");
+      for (const { id, rec } of fresh) tx.store.put(rec, id);
+      for (const id of have) if (!want.has(id)) tx.store.delete(id);
+      await tx.done;
+    },
+    async clear() {
+      const d = await db();
+      await d.clear("kv");
+      await d.clear("files");
+      _key = null;
+      sealKey = null;
+    },
+    async requestPersistent() {
+      if (typeof navigator === "undefined" || !navigator.storage?.persist) return false;
+      try {
+        if (await navigator.storage.persisted()) return true;
+        return await navigator.storage.persist();
+      } catch {
+        return false;
+      }
+    }
+  };
+  if (!lockMode) return base;
+  const lockable = {
+    ...base,
+    get locked() {
+      return sealKey === null;
+    },
+    lockNow() {
+      sealKey = null;
+    },
+    async unlock(secret) {
+      const { keyFromPassword, freshCacheKdf, opens } = await import('./cache-lock-LZILZNLP.js');
+      const d = await db();
+      let candidate;
+      if (typeof secret === "string") {
+        let kdf = await d.get("kv", CACHE_KDF);
+        if (!kdf) {
+          const fresh = freshCacheKdf();
+          const tx = d.transaction("kv", "readwrite");
+          if (!await tx.store.get(CACHE_KDF)) await tx.store.put(fresh, CACHE_KDF);
+          await tx.done;
+          kdf = await d.get("kv", CACHE_KDF);
+        }
+        candidate = await keyFromPassword(secret, kdf);
+      } else {
+        candidate = secret;
+      }
+      const raw = await d.get("kv", COLLECTIONS_KEY);
+      if (isEnvelope(raw) && !await opens(candidate, raw)) return false;
+      sealKey = candidate;
+      return true;
+    }
+  };
+  return lockable;
+}
+
+// src/persistence/targets/drive-auth-gis.ts
+var DRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
+var TOKEN_TIMEOUT_MS = 12e4;
+var EXPIRY_MARGIN_MS = 6e4;
+var DEFAULT_TOKEN_TTL_S = 3600;
+var gisLoading = null;
+function loadGIS() {
+  if (typeof globalThis.window === "undefined") return Promise.resolve();
+  if (globalThis.window.google?.accounts) return Promise.resolve();
+  gisLoading ??= new Promise((resolve, reject) => {
+    const s = document.createElement("script");
+    s.src = "https://accounts.google.com/gsi/client";
+    s.async = true;
+    s.onload = () => resolve();
+    s.onerror = () => reject(new Error("GIS failed to load"));
+    document.head.appendChild(s);
+  });
+  return gisLoading;
+}
+function requestToken(clientId, scope, prompt, onToken) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const timer = setTimeout(() => finish(() => reject(new Error("timeout"))), TOKEN_TIMEOUT_MS);
+    const client = globalThis.window.google.accounts.oauth2.initTokenClient({
+      client_id: clientId,
+      scope,
+      callback(resp) {
+        if (resp.error || !resp.access_token) {
+          finish(() => reject(new Error(resp.error ?? "token_failed")));
+          return;
+        }
+        onToken(resp.access_token, Date.now() + (resp.expires_in ?? DEFAULT_TOKEN_TTL_S) * 1e3);
+        finish(() => resolve(resp.access_token));
+      },
+      error_callback(err) {
+        finish(() => reject(new Error(err?.type ?? "gis_error")));
+      }
+    });
+    client.requestAccessToken({ prompt });
+  });
+}
+function gisDriveAuth(opts) {
+  const scope = opts.scope ?? DRIVE_SCOPE;
+  let token = null;
+  let expiry = 0;
+  const fresh = () => !!token && Date.now() < expiry - EXPIRY_MARGIN_MS;
+  function cache(t, exp) {
+    token = t;
+    expiry = exp;
+  }
+  function clear() {
+    token = null;
+    expiry = 0;
+  }
+  return {
+    async token(tokenOpts) {
+      if (!tokenOpts?.forceRefresh && fresh()) return token;
+      await loadGIS();
+      return requestToken(opts.clientId, scope, "", cache);
+    },
+    async reconnect() {
+      await loadGIS();
+      try {
+        await requestToken(opts.clientId, scope, "consent", cache);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async forget() {
+      clear();
+    }
+  };
+}
+
+export { RESERVED_STORE_MODES, createLocalStore, deriveStatus, gisDriveAuth, indexedDbCache, isLockableCache, isReservedStoreMode, memoryCache };
+//# sourceMappingURL=chunk-N4RPMX3Y.js.map
+//# sourceMappingURL=chunk-N4RPMX3Y.js.map