@procedures/store 0.2.3 → 0.4.0

package/dist/storage/hybrid.js

@@ -1,36 +1,111 @@
 /**
  * Hybrid Storage Implementation
  *
- * Combines local cache (InMemoryStorage) with remote persistence (ApiStorage).
- * Provides fast local reads with remote backup and sync.
+ * A local copy (an `InMemoryStorage`, or the `local` storage that the application gives) in
+ * front of a remote `CollectionStorage` (often an `ApiStorage`). The storage has four modes, and
+ * `setMode()` changes the mode while the storage operates (roadmap R28):
  *
- * Features:
- * - Local cache for fast reads, with a remote read on a miss
- * - Write-through or write-back strategies
- * - Automatic sync on initialization
- * - Conflict resolution
- * - Offline operation queue
+ * | Mode | Reads | Writes | Remote calls |
+ * |---|---|---|---|
+ * | `local-only` | the local copy | the local copy and the queue | none |
+ * | `write-through` | the local copy, the remote on a miss | the local copy, then the remote | yes |
+ * | `write-back` | the local copy, the remote on a miss | the local copy and the queue, a timer sends it | yes |
+ * | `remote-only` | the remote | the remote | yes, and no local copy |
+ *
+ * - The queue is durable through the `queueStore` that the application gives.
+ * - A sync asks for the changes since a version when the remote has `getChangesSince`.
+ * - With `versionOf`, a conflict is a change on both sides, and `conflictResolution` decides.
+ * - `pullInterval` keeps the local copy fresh.
  */
 import { InMemoryStorage } from "@procedures/collections";
-/** The ids that an operation changes ("*" for clear). */
-function idsOf(op) {
-    const data = op.data;
-    switch (op.type) {
-        case "set":
-        case "delete":
-            return data.id === undefined ? [] : [data.id];
-        case "setBatch":
-            return (data.items ?? []).map(([id]) => id);
-        case "deleteBatch":
-            return data.ids ?? [];
-        case "clear":
-            return ["*"];
+import { optionalMs } from "@procedures/client";
+import { MemoryQueueStore, idsOf, withoutId } from "./queue.js";
+const MODES = new Set(["local-only", "write-through", "write-back", "remote-only"]);
+/**
+ * The remote did not take a write of the write-through mode. The write is in the local cache and
+ * in the queue, and the storage sends it later (roadmap R2). `cause` is the error of the remote.
+ */
+export class PendingWriteError extends Error {
+    name = "PendingWriteError";
+    code = "WRITE_PENDING";
+    pending = true;
+    constructor(operation, cause) {
+        super(`The remote did not take the ${operation}: it waits in the queue`, { cause });
+    }
+}
+/** The queue of operations is full, so the storage refuses the write (roadmap R2). */
+export class QueueFullError extends Error {
+    name = "QueueFullError";
+    code = "QUEUE_FULL";
+    constructor(max) {
+        super(`The queue of operations is full (${max} operations): the storage refuses the write`);
+    }
+}
+/** The remote gave items without a key, so a sync cannot know which local items to keep. */
+export class MissingKeysError extends Error {
+    name = "MissingKeysError";
+    code = "MISSING_KEYS";
+    constructor(count) {
+        super(`${count} remote items have no key. Give the option keyOf, or a remote storage with getEntries(). The sync changed nothing.`);
+    }
+}
+/**
+ * The queue store failed (roadmap R28). A write that the store did not keep is undone and not
+ * acknowledged. A storage whose store cannot load refuses each operation.
+ */
+export class QueueStoreError extends Error {
+    name = "QueueStoreError";
+    code = "QUEUE_STORE";
+    constructor(action, cause) {
+        super(`The queue store could not ${action === "load" ? "load the queue" : "keep the queue"}`, { cause });
     }
 }
+/**
+ * The sync found conflicts and `conflictResolution` is "error" (roadmap R28). The local values and
+ * their queued writes stay. `ids` are the ids of the conflicts.
+ */
+export class ConflictError extends Error {
+    ids;
+    name = "ConflictError";
+    code = "SYNC_CONFLICT";
+    constructor(ids) {
+        super(`Conflict detected between local and remote versions of ${ids.length} items: ${ids.slice(0, 10).join(", ")}`);
+        this.ids = ids;
+    }
+}
+/**
+ * `setMode()` could not change the mode (roadmap R28). The mode did not change. `cause` is the
+ * error of the flush or of the sync.
+ */
+export class ModeSwitchError extends Error {
+    from;
+    to;
+    name = "ModeSwitchError";
+    code = "MODE_SWITCH_FAILED";
+    constructor(from, to, cause) {
+        super(`The storage could not change from ${from} to ${to}: the mode is still ${from}`, { cause });
+        this.from = from;
+        this.to = to;
+    }
+}
+const defaultIsUnavailable = (error) => {
+    if (typeof error !== "object" || error === null)
+        return true;
+    const { retryable, code } = error;
+    return retryable === true || code === undefined;
+};
+/** True when a remote does not know a procedure: an older server without `changes`. */
+const isNotFound = (error) => typeof error === "object" && error !== null && error.code === "NOT_FOUND";
 const defaultKeyOf = (item) => {
     const id = item?.id;
     return typeof id === "string" && id.length > 0 ? id : undefined;
 };
+function checkMode(mode) {
+    if (typeof mode !== "string" || !MODES.has(mode)) {
+        throw new TypeError(`Unknown mode ${JSON.stringify(mode)}: use local-only, write-through, write-back or remote-only`);
+    }
+    return mode;
+}
 /**
  * Hybrid storage combining local cache with remote persistence.
  *
@@ -42,9 +117,9 @@ const defaultKeyOf = (item) => {
  *
  * const remote = new ApiStorage(client, { collection: "users" });
  * const hybrid = new HybridStorage(remote, {
- *   writeStrategy: "write-through",
+ *   mode: "write-through",
  *   conflictResolution: "remote",
- *   syncInterval: 5000
+ *   syncInterval: seconds(5)
  * });
  *
  * // Fast local reads
@@ -52,20 +127,58 @@ const defaultKeyOf = (item) => {
  *
  * // Writes go to both local and remote
  * await hybrid.set("123", { name: "John" });
+ *
+ * // Offline: no remote call. The writes wait in the queue.
+ * await hybrid.setMode("local-only");
+ * // Online again: the switch sends the queue, then syncs the local copy
+ * await hybrid.setMode("write-through");
  * ```
  */
 export class HybridStorage {
     local;
     remote;
+    queueStore;
     options;
+    mode;
     offlineOps = [];
+    /** The operations in `offlineOps` that the queue store does not have yet */
+    unpersisted = new Set();
+    /** True when the queue store can differ from `offlineOps`: a failed write, or sent operations */
+    storeDirty = false;
+    /** The calls of the queue store, one at a time */
+    storeChain = Promise.resolve();
+    /** The push timer of the write-back mode */
     syncTimer = null;
+    /** The periodic pull */
+    pullTimer = null;
+    /** True while pushQueue sends the queue: the first operation can be on its way */
+    pushing = false;
+    /** The timer that sends the queue of the write-through mode after a failure */
+    drainTimer = null;
+    /** The load of the queue. The writes wait for it. */
+    loaded;
+    /** The load and the first sync. The reads wait for it, so a read never sees an empty cache by mistake. */
+    ready;
+    /** The error of the load (of the queue store, or of the local copy): the storage refuses each operation */
+    loadError;
+    /** A mode switch that runs. The operations wait for it. */
+    gate = Promise.resolve();
+    /** The operations that run, and the switches that wait for them to end */
+    active = 0;
+    idleWaiters = [];
     isOnline = true;
+    closed = false;
     /** A counter of local writes for each id, so a sync does not restore an older remote value */
     writeVersions = new Map();
     clearVersion = 0;
     /** The running sync: syncs run one at a time */
     syncChain = Promise.resolve();
+    /** The remote version of the last delta pull */
+    cursor;
+    /** True when the remote has `getChangesSince` but its server does not know `changes` */
+    changesUnsupported = false;
+    /** With `versionOf`: the last known remote version of each id. `null`: the remote has no item. */
+    bases = new Map();
     stats = {
         cacheHits: 0,
         cacheMisses: 0,
@@ -73,28 +186,135 @@ export class HybridStorage {
         conflicts: 0,
     };
     constructor(remote, options = {}) {
-        this.local = new InMemoryStorage();
+        this.local = options.local ?? new InMemoryStorage();
         this.remote = remote;
+        this.queueStore = options.queueStore ?? new MemoryQueueStore();
+        this.mode = checkMode(options.mode ?? options.writeStrategy ?? "write-through");
         this.options = {
-            writeStrategy: options.writeStrategy ?? "write-through",
             conflictResolution: options.conflictResolution ?? "remote",
             ...(options.mergeFn !== undefined && { mergeFn: options.mergeFn }),
             keyOf: options.keyOf ?? defaultKeyOf,
-            syncInterval: options.syncInterval ?? 5000,
+            ...(options.versionOf !== undefined && { versionOf: options.versionOf }),
+            syncInterval: optionalMs(options.syncInterval, "syncInterval") ?? 5000,
+            pullInterval: optionalMs(options.pullInterval, "pullInterval") ?? 0,
             syncOnInit: options.syncOnInit ?? true,
             maxOfflineOps: options.maxOfflineOps ?? 1000,
             offlineQueue: options.offlineQueue ?? true,
+            isUnavailable: options.isUnavailable ?? defaultIsUnavailable,
         };
-        // Initialize with remote data
-        if (this.options.syncOnInit) {
-            this.syncFromRemote().catch((err) => {
-                console.error("Failed to sync on init:", err);
-            });
+        // The queue first, then the first sync. The reads wait for both (roadmap R2, R28).
+        this.loaded = this.loadQueue();
+        this.ready = this.loaded.then(() => this.initialSync());
+        this.updateTimers();
+    }
+    //
+    // ═══ Modes ═══
+    //
+    /** The mode of the storage now. */
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * This method changes the mode while the storage operates (roadmap R28).
+     *
+     * - The switch waits for the operations that run. The operations that start later wait for
+     *   the switch. Switches and syncs run one at a time.
+     * - A switch to a remote mode sends the queue first. A switch to `local-only` makes no remote
+     *   call: the queue stays until the next remote mode.
+     * - A switch to `remote-only` drops the local copy, after the queue reached the remote.
+     * - A switch from `local-only` or `remote-only` to a mode with a local copy syncs the local
+     *   copy. The reads wait for the sync.
+     * - When the flush or the sync fails, the mode does not change, and the switch throws
+     *   `ModeSwitchError`.
+     */
+    async setMode(mode) {
+        const target = checkMode(mode);
+        const previous = this.gate;
+        let release;
+        this.gate = new Promise((resolve) => (release = resolve));
+        try {
+            await previous;
+            await this.loaded;
+            if (this.loadError)
+                throw this.loadError;
+            await this.idle();
+            await this.serialize(() => this.switchTo(target));
+        }
+        finally {
+            release();
+        }
+    }
+    async switchTo(target) {
+        const from = this.mode;
+        if (target === from)
+            return;
+        try {
+            if (target !== "local-only") {
+                // The queue reaches the remote before the mode changes
+                await this.pushQueue();
+                await this.ensureStoreClean();
+            }
+            if (target === "remote-only") {
+                await this.dropLocal();
+            }
+            else if (from === "remote-only" || from === "local-only") {
+                if (from === "remote-only")
+                    await this.rebuildLocal();
+                await this.pullRemote(from === "remote-only");
+            }
         }
-        // Start periodic sync for write-back mode
-        if (this.options.writeStrategy === "write-back" &&
-            this.options.syncInterval > 0) {
-            this.startPeriodicSync();
+        catch (error) {
+            throw new ModeSwitchError(from, target, error);
+        }
+        this.mode = target;
+        this.updateTimers();
+    }
+    /** This method drops the local copy. A read in flight does not fill it again. */
+    async dropLocal() {
+        this.clearVersion++;
+        this.cursor = undefined;
+        await this.local.clear();
+    }
+    /** This method makes the local copy from the queue only, before a full sync. */
+    async rebuildLocal() {
+        await this.dropLocal();
+        for (const op of this.offlineOps)
+            await this.applyToLocal(op);
+    }
+    /** This method starts and stops the timers for the mode. */
+    updateTimers() {
+        if (this.closed)
+            return;
+        const push = this.mode === "write-back" && this.options.syncInterval > 0;
+        if (push && !this.syncTimer) {
+            this.syncTimer = setInterval(() => {
+                this.syncToRemote().catch((err) => {
+                    console.error("Periodic sync failed:", err);
+                });
+            }, this.options.syncInterval);
+            // The timer must not keep the process alive (deep dive DATA-9)
+            this.syncTimer.unref?.();
+        }
+        else if (!push && this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+        }
+        const pull = this.options.pullInterval > 0 && (this.mode === "write-through" || this.mode === "write-back");
+        if (pull && !this.pullTimer) {
+            this.pullTimer = setInterval(() => {
+                this.syncFromRemote().catch((err) => {
+                    console.error("Periodic pull failed:", err);
+                });
+            }, this.options.pullInterval);
+            this.pullTimer.unref?.();
+        }
+        else if (!pull && this.pullTimer) {
+            clearInterval(this.pullTimer);
+            this.pullTimer = null;
+        }
+        if (this.mode !== "write-through" && this.drainTimer) {
+            clearTimeout(this.drainTimer);
+            this.drainTimer = null;
         }
     }
     //
@@ -102,188 +322,272 @@ export class HybridStorage {
     //
     /**
      * The local item, or else the remote item (which the cache then keeps). When the remote
-     * cannot answer, the storage is offline and the result is undefined.
+     * cannot answer, the storage is offline and the result is undefined. In `local-only` mode, a
+     * miss is undefined. In `remote-only` mode, the remote answers, and its error passes through.
      */
     async get(id) {
-        // Try local cache first
-        const cached = await this.local.get(id);
-        if (cached !== undefined) {
-            this.stats.cacheHits++;
-            return cached;
-        }
-        this.stats.cacheMisses++;
-        // A pending local delete means "no item": do not read it back from the remote
-        if (this.hasPendingOp(id)) {
-            return undefined;
-        }
-        const version = this.versionOf(id);
-        try {
-            const remote = await this.remote.get(id);
-            this.isOnline = true;
-            if (remote !== undefined && this.versionOf(id) === version) {
-                await this.local.set(id, remote);
+        return this.run(true, async () => {
+            if (this.mode === "remote-only")
+                return this.remoteRead(() => this.remote.get(id));
+            // Try local cache first
+            const cached = await this.local.get(id);
+            if (cached !== undefined) {
+                this.stats.cacheHits++;
+                return cached;
             }
-            return remote;
-        }
-        catch {
-            this.isOnline = false;
-            return undefined;
-        }
+            this.stats.cacheMisses++;
+            // A pending local delete means "no item": do not read it back from the remote
+            if (this.mode === "local-only" || this.hasPendingOp(id)) {
+                return undefined;
+            }
+            const version = this.writeKey(id);
+            try {
+                const remote = await this.remote.get(id);
+                this.isOnline = true;
+                if (this.writeKey(id) === version && !this.hasPendingOp(id)) {
+                    if (remote !== undefined)
+                        await this.local.set(id, remote);
+                    this.noteBase(id, remote);
+                }
+                return remote;
+            }
+            catch {
+                this.isOnline = false;
+                return undefined;
+            }
+        });
     }
     async getAll() {
-        // Return local cache
-        return this.local.getAll();
+        return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remote.getAll()) : this.local.getAll()));
+    }
+    /** Every item with its id. */
+    async getEntries() {
+        return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remoteEntries()) : this.local.getEntries()));
     }
     async find(predicate) {
-        // Search local cache
-        return this.local.find(predicate);
+        return this.run(true, () => this.mode === "remote-only" ? this.remoteRead(() => this.remote.find(predicate)) : this.local.find(predicate));
     }
     async has(id) {
-        return this.local.has(id);
+        return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remote.has(id)) : this.local.has(id)));
     }
     async size() {
-        return this.local.size();
+        return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remote.size()) : this.local.size()));
+    }
+    async getBatch(ids) {
+        return this.run(true, () => this.mode === "remote-only" ? this.remoteRead(() => this.remote.getBatch(ids)) : this.local.getBatch(ids));
+    }
+    /** A read of the remote-only mode. A queue that a restart loaded reaches the remote first. */
+    async remoteRead(read) {
+        if (this.offlineOps.length > 0)
+            await this.serialize(() => this.pushQueue());
+        try {
+            const result = await read();
+            this.isOnline = true;
+            return result;
+        }
+        catch (error) {
+            if (!(error instanceof MissingKeysError))
+                this.isOnline = false;
+            throw error;
+        }
     }
     //
     // ═══ Write Operations ═══
     //
     async set(id, value) {
-        this.bump(id);
-        // Always write to local immediately
-        await this.local.set(id, value);
-        if (this.options.writeStrategy === "write-through") {
-            // Write-through: sync to remote immediately
-            try {
-                await this.remote.set(id, value);
-            }
-            catch (error) {
-                this.handleRemoteFailure("set", { id, value });
-                throw error;
-            }
-        }
-        else {
-            // Write-back: queue for later sync
-            this.queueOperation({
-                type: "set",
-                data: { id, value },
-                timestamp: Date.now(),
-            });
-        }
+        await this.write("set", { id, value }, [id], async () => {
+            this.bump(id);
+            await this.local.set(id, value);
+        }, () => this.remote.set(id, value));
     }
     async delete(id) {
-        this.bump(id);
-        const existed = await this.local.delete(id);
-        if (this.options.writeStrategy === "write-through") {
-            try {
-                await this.remote.delete(id);
-            }
-            catch (error) {
-                this.handleRemoteFailure("delete", { id });
-                throw error;
-            }
-        }
-        else {
-            this.queueOperation({
-                type: "delete",
-                data: { id },
-                timestamp: Date.now(),
-            });
-        }
-        return existed;
+        return this.write("delete", { id }, [id], async () => {
+            this.bump(id);
+            return this.local.delete(id);
+        }, () => this.remote.delete(id));
     }
     async clear() {
-        this.clearVersion++;
-        await this.local.clear();
-        if (this.options.writeStrategy === "write-through") {
-            try {
-                await this.remote.clear();
-            }
-            catch (error) {
-                this.handleRemoteFailure("clear", {});
-                throw error;
-            }
-        }
-        else {
-            this.queueOperation({
-                type: "clear",
-                data: {},
-                timestamp: Date.now(),
-            });
-        }
+        await this.write("clear", {}, "*", async () => {
+            this.clearVersion++;
+            await this.local.clear();
+        }, () => this.remote.clear());
     }
     //
     // ═══ Bulk Operations ═══
     //
     async setBatch(items) {
-        for (const [id] of items)
-            this.bump(id);
-        await this.local.setBatch(items);
-        if (this.options.writeStrategy === "write-through") {
-            try {
-                await this.remote.setBatch(items);
-            }
-            catch (error) {
-                this.handleRemoteFailure("setBatch", { items });
-                throw error;
-            }
-        }
-        else {
-            this.queueOperation({
-                type: "setBatch",
-                data: { items },
-                timestamp: Date.now(),
-            });
-        }
+        await this.write("setBatch", { items }, items.map(([id]) => id), async () => {
+            for (const [id] of items)
+                this.bump(id);
+            await this.local.setBatch(items);
+        }, () => this.remote.setBatch(items));
     }
     async deleteBatch(ids) {
-        for (const id of ids)
-            this.bump(id);
-        const deleted = await this.local.deleteBatch(ids);
-        if (this.options.writeStrategy === "write-through") {
+        return this.write("deleteBatch", { ids }, ids, async () => {
+            for (const id of ids)
+                this.bump(id);
+            return this.local.deleteBatch(ids);
+        }, () => this.remote.deleteBatch(ids));
+    }
+    /**
+     * One write, in the mode of the storage. The result is the result of the local copy, or of the
+     * remote in `remote-only` mode.
+     *
+     * - `remote-only`: the remote only. Its error passes through.
+     * - `write-back` and `local-only`: the local copy and the queue. A full queue refuses the write
+     *   before the local change. The queue store keeps the operation before the write ends.
+     * - `write-through`, the remote refuses the write: the local change is undone, and the error
+     *   of the remote passes through.
+     * - `write-through`, the remote is not available: with the queue, the write waits in it, a timer
+     *   sends it later, and the write throws `PendingWriteError`. Without the queue, or with a full
+     *   queue, the local change is undone.
+     *
+     * Before, a failed write-through stayed in the local cache and in the queue, no timer sent the
+     * queue, a second try queued the operation again, and a full queue dropped the oldest operation
+     * without a word (roadmap R2).
+     */
+    write(type, data, ids, applyLocal, applyRemote) {
+        return this.run(false, async () => {
+            const op = { type, data, timestamp: Date.now() };
+            if (this.mode === "remote-only") {
+                const send = async () => {
+                    await this.ensureStoreClean();
+                    const result = await applyRemote();
+                    this.noteRemoteWrite(op);
+                    return result;
+                };
+                try {
+                    const result = this.offlineOps.length > 0
+                        ? await this.serialize(async () => {
+                            await this.pushQueue();
+                            return send();
+                        })
+                        : await send();
+                    this.isOnline = true;
+                    return result;
+                }
+                catch (error) {
+                    if (!(error instanceof QueueStoreError) && this.options.isUnavailable(error))
+                        this.isOnline = false;
+                    throw error;
+                }
+            }
+            if (this.mode === "write-back" || this.mode === "local-only") {
+                this.ensureQueueRoom(op);
+                this.attachBase(op);
+                const undo = await this.snapshot(ids);
+                const result = await applyLocal();
+                await this.enqueue(op, undo);
+                return result;
+            }
+            const undo = await this.snapshot(ids);
+            const result = await applyLocal();
             try {
-                await this.remote.deleteBatch(ids);
+                if (this.offlineOps.length > 0) {
+                    // The queued operations are older: they reach the remote first, or the older value of a
+                    // queued write replaces this one later. A failed send keeps this write behind them.
+                    await this.serialize(async () => {
+                        await this.pushQueue();
+                        await this.ensureStoreClean();
+                        await applyRemote();
+                    });
+                }
+                else {
+                    await this.ensureStoreClean();
+                    await applyRemote();
+                }
+                this.isOnline = true;
+                this.noteRemoteWrite(op);
             }
             catch (error) {
-                this.handleRemoteFailure("deleteBatch", { ids });
+                if (!(error instanceof QueueStoreError) &&
+                    this.options.offlineQueue &&
+                    this.options.isUnavailable(error) &&
+                    this.hasQueueRoom(op)) {
+                    this.isOnline = false;
+                    console.error(`Remote ${type} failed: the operation waits in the queue`);
+                    this.attachBase(op);
+                    await this.enqueue(op, undo);
+                    this.scheduleDrain();
+                    throw new PendingWriteError(type, error);
+                }
+                await undo();
                 throw error;
             }
-        }
-        else {
-            this.queueOperation({
-                type: "deleteBatch",
-                data: { ids },
-                timestamp: Date.now(),
-            });
-        }
-        return deleted;
+            return result;
+        });
     }
-    getBatch(ids) {
-        return this.local.getBatch(ids);
+    /**
+     * The local values of the ids before a write, and a function that puts them back. It puts back
+     * only the ids that no later write changed.
+     */
+    async snapshot(ids) {
+        const before = ids === "*" ? new Map(await this.local.getEntries()) : await this.local.getBatch(ids);
+        const touched = ids === "*" ? [...before.keys()] : ids;
+        // The versions after the write: this write adds one to each id (clear adds to clearVersion)
+        const versions = new Map(touched.map((id) => [id, (this.writeVersions.get(id) ?? 0) + (ids === "*" ? 0 : 1)]));
+        const clearVersion = this.clearVersion + (ids === "*" ? 1 : 0);
+        return async () => {
+            if (this.clearVersion !== clearVersion)
+                return;
+            for (const id of touched) {
+                if ((this.writeVersions.get(id) ?? 0) !== versions.get(id))
+                    continue;
+                const value = before.get(id);
+                if (value === undefined)
+                    await this.local.delete(id);
+                else
+                    await this.local.set(id, value);
+            }
+        };
     }
     //
     // ═══ Sync Operations ═══
     //
     /**
-     * Sync all data from remote to local.
-     * Handles conflicts according to conflict resolution strategy.
+     * Sync from the remote to the local copy, in the modes `write-through` and `write-back`. The
+     * other modes have no local copy to sync (`remote-only`) or make no remote call (`local-only`):
+     * the call does nothing.
      *
-     * - Each remote item goes into the cache under `keyOf(item)`.
+     * - The sync asks for the changes since the version of the last sync when the remote has
+     *   `getChangesSince`. Else it reads all entries.
+     * - Each remote item goes into the cache under its id.
      * - A local item that the remote does not have is removed, unless a queued local operation
-     *   changes it (the remote deleted it).
+     *   changes it.
      * - An id that a local write changed during the sync keeps the local value: the remote value
      *   is older.
      * - Syncs run one at a time.
      */
     syncFromRemote() {
-        return this.serialize(() => this.pullRemote());
+        return this.serialize(async () => {
+            await this.loaded;
+            if (this.loadError)
+                throw this.loadError;
+            if (this.mode === "write-through" || this.mode === "write-back")
+                await this.pullRemote(false);
+        });
     }
     /**
      * Sync all pending offline operations to remote.
      * Processes queued operations in order. When one fails, it and the later operations stay in
-     * the queue: the operations that reached the remote are not sent again.
+     * the queue: the operations that reached the remote are not sent again. In `local-only` mode,
+     * the call does nothing.
      */
     syncToRemote() {
-        return this.serialize(() => this.pushQueue());
+        return this.serialize(async () => {
+            await this.loaded;
+            if (this.loadError)
+                throw this.loadError;
+            if (this.mode !== "local-only")
+                await this.pushQueue();
+        });
+    }
+    /**
+     * This method sends the queue to the remote (roadmap R28). `ProcedureServer.useStorage` uses it. In
+     * `local-only` mode, it sends nothing: the queue waits for a remote mode.
+     */
+    flush() {
+        return this.syncToRemote();
     }
     /**
      * Force a full sync (both directions).
@@ -295,14 +599,26 @@ export class HybridStorage {
     //
     // ═══ Lifecycle & Metadata ═══
     //
+    /**
+     * This method stops the timers, sends the queue (not in `local-only` mode), and closes the remote and the
+     * local copy. The queue store keeps the operations that the remote did not take. A durable local
+     * copy keeps its items.
+     */
     async close() {
-        // Stop periodic sync
-        if (this.syncTimer) {
-            clearInterval(this.syncTimer);
-            this.syncTimer = null;
+        this.closed = true;
+        for (const timer of [this.syncTimer, this.pullTimer]) {
+            if (timer)
+                clearInterval(timer);
+        }
+        this.syncTimer = null;
+        this.pullTimer = null;
+        if (this.drainTimer) {
+            clearTimeout(this.drainTimer);
+            this.drainTimer = null;
         }
+        await this.loaded;
         // Sync pending operations before closing
-        if (this.offlineOps.length > 0) {
+        if (this.offlineOps.length > 0 && this.mode !== "local-only") {
             try {
                 await this.syncToRemote();
             }
@@ -310,17 +626,31 @@ export class HybridStorage {
                 console.error("Failed to sync before close:", error);
             }
         }
+        await this.storeChain;
         // Close remote storage (an ApiStorage leaves the caller's client open)
-        await this.remote.close();
+        try {
+            await this.remote.close();
+        }
+        finally {
+            await this.local.close();
+        }
     }
+    /**
+     * The metadata of the storage. `size` is the result of `size()`: the number of items of the
+     * storage, also in `remote-only` mode. `stats.localSize` is the number of items of the local
+     * copy. Before, `size` was the size of the local copy, which `remote-only` keeps empty (found by
+     * the contract suite of `@procedures/collections/testing`).
+     */
     async getMetadata() {
+        const currentSize = await this.size();
+        const localSize = await this.local.size();
         const totalOps = this.stats.cacheHits + this.stats.cacheMisses;
         const hitRate = totalOps > 0 ? (this.stats.cacheHits / totalOps) * 100 : 0;
-        const currentSize = await this.local.size();
         return {
             type: "hybrid",
             size: currentSize,
             stats: {
+                localSize,
                 hitRate: Math.round(hitRate * 100) / 100,
                 cacheHits: this.stats.cacheHits,
                 cacheMisses: this.stats.cacheMisses,
@@ -328,7 +658,8 @@ export class HybridStorage {
                 conflicts: this.stats.conflicts,
                 pendingOps: this.offlineOps.length,
                 isOnline: this.isOnline,
-                writeStrategy: this.options.writeStrategy,
+                mode: this.mode,
+                writeStrategy: this.mode,
                 conflictResolution: this.options.conflictResolution,
             },
         };
@@ -336,68 +667,378 @@ export class HybridStorage {
     //
     // ═══ Internal Helpers ═══
     //
-    async pullRemote() {
+    /**
+     * This method starts a public operation: after the load of the queue (a write) or the first sync (a read),
+     * and never during a mode switch.
+     */
+    async run(read, work) {
+        await (read ? this.ready : this.loaded);
+        for (;;) {
+            const gate = this.gate;
+            await gate;
+            // No new switch started while this operation waited
+            if (this.gate === gate)
+                break;
+        }
+        if (this.loadError)
+            throw this.loadError;
+        this.active++;
+        try {
+            return await work();
+        }
+        finally {
+            if (--this.active === 0) {
+                for (const resolve of this.idleWaiters.splice(0))
+                    resolve();
+            }
+        }
+    }
+    /** A promise that resolves when no operation runs. */
+    idle() {
+        if (this.active === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.push(resolve));
+    }
+    /** This method loads the queue, and puts its writes in the local copy. */
+    async loadQueue() {
+        let ops;
+        try {
+            ops = await this.queueStore.load();
+        }
+        catch (error) {
+            this.loadError = new QueueStoreError("load", error);
+            console.error("The queue store could not load the queue: the storage refuses each operation", error);
+            return;
+        }
+        this.offlineOps = ops.slice();
+        try {
+            for (const op of this.offlineOps) {
+                for (const [id, version] of op.base ?? []) {
+                    if (!this.bases.has(id))
+                        this.bases.set(id, version);
+                }
+                // A durable local copy can hold the operation already: each operation gives the same
+                // result two times
+                await this.applyToLocal(op);
+            }
+        }
+        catch (error) {
+            this.loadError = new Error("The local copy could not take the loaded queue: the storage refuses each operation", { cause: error });
+            console.error(this.loadError.message, error);
+        }
+    }
+    /** The first sync: send the loaded queue, then read the remote. */
+    async initialSync() {
+        if (this.loadError)
+            return;
+        if (this.options.syncOnInit && this.mode !== "local-only") {
+            if (this.offlineOps.length > 0) {
+                await this.syncToRemote().catch((err) => {
+                    console.error("Failed to send the queue on init:", err);
+                });
+            }
+            if (this.mode === "write-through" || this.mode === "write-back") {
+                await this.syncFromRemote().catch((err) => {
+                    console.error("Failed to sync on init:", err);
+                });
+            }
+        }
+        if (this.offlineOps.length > 0)
+            this.scheduleDrain();
+    }
+    /** This method applies a queued operation to the local copy. */
+    async applyToLocal(op) {
+        const data = op.data;
+        switch (op.type) {
+            case "set":
+                await this.local.set(data.id, data.value);
+                break;
+            case "delete":
+                await this.local.delete(data.id);
+                break;
+            case "setBatch":
+                await this.local.setBatch(data.items);
+                break;
+            case "deleteBatch":
+                await this.local.deleteBatch(data.ids);
+                break;
+            case "clear":
+                await this.local.clear();
+                break;
+        }
+    }
+    /**
+     * One pull. `full`: ask for all items (after the local copy was dropped).
+     *
+     * - The versions of the local writes at the start: a write during the pull keeps its value.
+     * - The cursor moves only after a pull without conflicts, so a conflict of the "error" policy
+     *   comes again at the next pull.
+     */
+    async pullRemote(full) {
         const versions = new Map(this.writeVersions);
         const clearVersion = this.clearVersion;
         // True when a local write changed the id after the sync started
         const changedLocally = (id) => this.clearVersion !== clearVersion || (this.writeVersions.get(id) ?? 0) !== (versions.get(id) ?? 0);
-        let remoteData;
+        let changes;
         try {
-            remoteData = await this.remote.getAll();
+            changes = await this.fetchChanges(full);
         }
         catch (error) {
-            this.isOnline = false;
+            if (!(error instanceof MissingKeysError))
+                this.isOnline = false;
             throw error;
         }
+        const conflicts = [];
+        let queueChanged = false;
         const remoteIds = new Set();
-        for (const item of remoteData) {
-            const id = this.options.keyOf(item);
-            if (!id) {
-                console.warn("Item has no key, skipping:", item);
-                continue;
-            }
+        for (const [id, item] of changes.changed) {
             remoteIds.add(id);
-            if (changedLocally(id) || this.hasPendingOp(id)) {
-                continue;
+            if (await this.pullItem(id, item, changedLocally, conflicts))
+                queueChanged = true;
+        }
+        // The remote deleted these items
+        const gone = changes.full
+            ? (await this.local.getEntries()).map(([id]) => id).filter((id) => !remoteIds.has(id))
+            : changes.deleted;
+        for (const id of gone) {
+            if (await this.pullDelete(id, changedLocally, conflicts))
+                queueChanged = true;
+        }
+        if (queueChanged) {
+            this.storeDirty = true;
+            await this.persistAll().catch((error) => {
+                console.error("The queue store could not keep the queue after the sync:", error);
+            });
+        }
+        this.stats.syncCount++;
+        this.isOnline = true;
+        if (conflicts.length > 0)
+            throw new ConflictError(conflicts);
+        if (changes.version !== undefined)
+            this.cursor = changes.version;
+    }
+    /**
+     * The remote changes: since the cursor from `getChangesSince` when the remote has it, or else
+     * all entries.
+     */
+    async fetchChanges(full) {
+        if (this.remote.getChangesSince && !this.changesUnsupported) {
+            try {
+                return await this.remote.getChangesSince(full ? undefined : this.cursor);
             }
-            const localItem = await this.local.get(id);
-            if (localItem === undefined) {
-                // No local version - just store remote
-                await this.local.set(id, item);
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+                // A server without the procedure `changes`: read all entries from now on
+                this.changesUnsupported = true;
             }
-            else if (JSON.stringify(localItem) !== JSON.stringify(item)) {
-                // Conflict - resolve according to strategy
-                const resolved = this.resolveConflict(localItem, item);
-                await this.local.set(id, resolved);
+        }
+        return { full: true, changed: await this.remoteEntries(), deleted: [] };
+    }
+    /** This method applies one remote item. It gives true when the queue changed. */
+    async pullItem(id, item, changedLocally, conflicts) {
+        if (changedLocally(id))
+            return false;
+        const localItem = await this.local.get(id);
+        if (changedLocally(id))
+            return false;
+        const remoteVersion = this.versionOfItem(item);
+        if (this.hasPendingOp(id)) {
+            // Without versions, the queued write wins, as before
+            if (remoteVersion === undefined)
+                return false;
+            // The remote did not change since the last sync, or the storage never saw a remote version
+            // of the id: the queued write wins
+            const base = this.bases.get(id);
+            if (base === undefined || base === remoteVersion)
+                return false;
+            if (localItem !== undefined && this.versionOfItem(localItem) === remoteVersion) {
+                this.bases.set(id, remoteVersion);
+                return false;
+            }
+            return this.resolvePending(id, localItem, item, remoteVersion, conflicts);
+        }
+        const localVersion = localItem === undefined ? undefined : this.versionOfItem(localItem);
+        if (localItem === undefined) {
+            await this.local.set(id, item);
+        }
+        else if (remoteVersion !== undefined && localVersion !== undefined) {
+            // Only the remote changed: it is not a conflict
+            if (localVersion !== remoteVersion)
+                await this.local.set(id, item);
+        }
+        else if (JSON.stringify(localItem) !== JSON.stringify(item)) {
+            // Conflict - resolve according to strategy
+            if (this.options.conflictResolution === "error") {
                 this.stats.conflicts++;
+                conflicts.push(id);
+                return false;
             }
+            const resolved = this.resolveConflict(localItem, item);
+            await this.local.set(id, resolved);
+            this.stats.conflicts++;
         }
-        // The remote deleted these items
-        for (const id of await this.localIds()) {
-            if (!remoteIds.has(id) && !changedLocally(id) && !this.hasPendingOp(id)) {
+        if (remoteVersion !== undefined)
+            this.bases.set(id, remoteVersion);
+        return false;
+    }
+    /** This method applies one remote delete. It gives true when the queue changed. */
+    async pullDelete(id, changedLocally, conflicts) {
+        if (changedLocally(id))
+            return false;
+        if (!this.hasPendingOp(id)) {
+            await this.local.delete(id);
+            if (this.options.versionOf)
+                this.bases.set(id, null);
+            return false;
+        }
+        // Without versions, the queued write wins, as before. With versions, the remote deleted the
+        // item only if the last sync saw a version of it.
+        const base = this.bases.get(id);
+        if (!this.options.versionOf || base === undefined || base === null)
+            return false;
+        const localItem = await this.local.get(id);
+        if (changedLocally(id))
+            return false;
+        if (localItem === undefined) {
+            // Both sides deleted the item
+            this.bases.set(id, null);
+            return false;
+        }
+        this.stats.conflicts++;
+        switch (this.options.conflictResolution) {
+            case "remote":
+                if (!this.dropQueued(id))
+                    break;
                 await this.local.delete(id);
+                this.bases.set(id, null);
+                return true;
+            case "error":
+                conflicts.push(id);
+                return false;
+            default:
+                // "local", and "merge" with one deleted side: the queued write wins
+                break;
+        }
+        this.bases.set(id, null);
+        return false;
+    }
+    /**
+     * A queued local write of an id whose remote version changed: a conflict, and the policy
+     * decides. True when the queue changed.
+     */
+    async resolvePending(id, localItem, remoteItem, remoteVersion, conflicts) {
+        this.stats.conflicts++;
+        switch (this.options.conflictResolution) {
+            case "remote":
+                // The remote value replaces the queued write. A queued clear cannot lose one id.
+                if (!this.dropQueued(id))
+                    break;
+                await this.local.set(id, remoteItem);
+                this.bases.set(id, remoteVersion);
+                return true;
+            case "merge": {
+                if (localItem === undefined)
+                    break;
+                const merged = this.resolveConflict(localItem, remoteItem);
+                if (!this.dropQueued(id))
+                    break;
+                await this.local.set(id, merged);
+                this.bases.set(id, remoteVersion);
+                this.offlineOps.push({ type: "set", data: { id, value: merged }, timestamp: Date.now(), base: [[id, remoteVersion]] });
+                return true;
             }
+            case "error":
+                conflicts.push(id);
+                return false;
+            default:
+                break;
         }
-        this.stats.syncCount++;
-        this.isOnline = true;
+        // "local": the queued write wins, and it replaces this remote version
+        this.bases.set(id, remoteVersion);
+        return false;
+    }
+    /**
+     * This method removes an id from the queued operations. It gives false when a queued clear touches it: nothing
+     * changes then.
+     */
+    dropQueued(id) {
+        if (this.offlineOps.some((op) => op.type === "clear"))
+            return false;
+        const next = [];
+        for (const op of this.offlineOps) {
+            const kept = withoutId(op, id);
+            if (kept)
+                next.push(kept);
+        }
+        this.offlineOps = next;
+        return true;
+    }
+    /**
+     * The remote items with their ids: from `getEntries()` when the remote has it, or else from
+     * `getAll()` and `keyOf`. An item without a key stops the sync before any change. Before, the
+     * sync skipped such items and then deleted each local item that the remote list did not have,
+     * so the remote list without ids emptied the cache (roadmap R2).
+     */
+    async remoteEntries() {
+        if (this.remote.getEntries)
+            return this.remote.getEntries();
+        const items = await this.remote.getAll();
+        const entries = [];
+        let missing = 0;
+        for (const item of items) {
+            const id = this.options.keyOf(item);
+            if (id)
+                entries.push([id, item]);
+            else
+                missing++;
+        }
+        if (missing > 0)
+            throw new MissingKeysError(missing);
+        return entries;
     }
+    /**
+     * This method sends the queue. The operations that reached the remote leave the queue. The queue store
+     * gets the change at the end.
+     */
     async pushQueue() {
-        while (this.offlineOps.length > 0) {
-            const op = this.offlineOps[0];
-            try {
-                await this.executeOperation(op);
-            }
-            catch (error) {
-                // This operation and the later ones stay queued
-                this.isOnline = false;
-                throw error;
+        this.pushing = true;
+        let sent = 0;
+        try {
+            while (this.offlineOps.length > 0) {
+                const op = this.offlineOps[0];
+                if (this.unpersisted.has(op)) {
+                    // The write of this operation waits for the queue store
+                    await this.storeChain;
+                    continue;
+                }
+                try {
+                    await this.executeOperation(op);
+                }
+                catch (error) {
+                    // This operation and the later ones stay queued
+                    this.isOnline = false;
+                    throw error;
+                }
+                this.noteRemoteWrite(op);
+                // Remove the operation only after it reached the remote
+                if (this.offlineOps[0] === op) {
+                    this.offlineOps.shift();
+                    sent++;
+                    this.storeDirty = true;
+                }
             }
-            // Remove the operation only after it reached the remote
-            if (this.offlineOps[0] === op) {
-                this.offlineOps.shift();
+            this.isOnline = true;
+        }
+        finally {
+            this.pushing = false;
+            if (sent > 0) {
+                await this.persistAll().catch((error) => {
+                    // The store keeps sent operations. A later direct write repairs it first.
+                    console.error("The queue store could not remove the sent operations:", error);
+                });
             }
         }
-        this.isOnline = true;
     }
     /** Run syncs one at a time. */
     serialize(run) {
@@ -405,15 +1046,105 @@ export class HybridStorage {
         this.syncChain = next.catch(() => undefined);
         return next;
     }
-    async localIds() {
-        return [...this.local.keys()];
-    }
     bump(id) {
         this.writeVersions.set(id, (this.writeVersions.get(id) ?? 0) + 1);
     }
-    versionOf(id) {
+    /** The count of local writes of an id: it changes with each write and each clear. */
+    writeKey(id) {
         return `${this.clearVersion}:${this.writeVersions.get(id) ?? 0}`;
     }
+    versionOfItem(item) {
+        return this.options.versionOf?.(item);
+    }
+    /** This method records the remote version of an id that the storage read. */
+    noteBase(id, item) {
+        if (!this.options.versionOf)
+            return;
+        if (item === undefined) {
+            this.bases.set(id, null);
+            return;
+        }
+        const version = this.versionOfItem(item);
+        if (version === undefined)
+            this.bases.delete(id);
+        else
+            this.bases.set(id, version);
+    }
+    /** This method records the remote versions after a write reached the remote. */
+    noteRemoteWrite(op) {
+        if (!this.options.versionOf)
+            return;
+        const data = op.data;
+        switch (op.type) {
+            case "set":
+                this.noteBase(data.id, data.value);
+                break;
+            case "delete":
+                this.bases.set(data.id, null);
+                break;
+            case "setBatch":
+                for (const [id, value] of data.items)
+                    this.noteBase(id, value);
+                break;
+            case "deleteBatch":
+                for (const id of data.ids)
+                    this.bases.set(id, null);
+                break;
+            case "clear":
+                for (const id of this.bases.keys())
+                    this.bases.set(id, null);
+                break;
+        }
+    }
+    /**
+     * This method puts in the operation the remote version that it changes, for each id: the version that an
+     * older queued operation of the id writes, or else the known remote version. A storage that
+     * loads the queue after a restart takes the version of the first operation of each id.
+     */
+    attachBase(op) {
+        if (!this.options.versionOf)
+            return;
+        const base = [];
+        for (const id of idsOf(op)) {
+            if (id === "*")
+                continue;
+            const version = this.expectedBase(id);
+            if (version !== undefined)
+                base.push([id, version]);
+        }
+        if (base.length > 0)
+            op.base = base;
+    }
+    /** The remote version of an id after the queued operations, or undefined when it is not known. */
+    expectedBase(id) {
+        for (let index = this.offlineOps.length - 1; index >= 0; index--) {
+            const op = this.offlineOps[index];
+            const data = op.data;
+            switch (op.type) {
+                case "set":
+                    if (data.id === id)
+                        return this.versionOfItem(data.value);
+                    break;
+                case "delete":
+                    if (data.id === id)
+                        return null;
+                    break;
+                case "setBatch": {
+                    const item = (data.items ?? []).findLast(([itemId]) => itemId === id);
+                    if (item)
+                        return this.versionOfItem(item[1]);
+                    break;
+                }
+                case "deleteBatch":
+                    if ((data.ids ?? []).includes(id))
+                        return null;
+                    break;
+                case "clear":
+                    return null;
+            }
+        }
+        return this.bases.get(id);
+    }
     hasPendingOp(id) {
         return this.offlineOps.some((op) => {
             const ids = idsOf(op);
@@ -440,18 +1171,165 @@ export class HybridStorage {
                 return remote;
         }
     }
+    //
+    // ═══ The queue and its store ═══
+    //
     /**
-     * Queue operation for later sync.
+     * This method puts an operation in the queue, then in the queue store. The write ends only after the store
+     * kept it. When the store fails, the operation leaves the queue, the local change is undone,
+     * and the write throws `QueueStoreError`.
+     *
+     * A set or a delete of one id replaces the queued set or delete of that id, when no later
+     * operation touches the id: a second try of a write does not queue it two times.
      */
-    queueOperation(op) {
-        if (!this.options.offlineQueue) {
-            return;
+    async enqueue(op, undo) {
+        const index = this.replaceableIndex(op);
+        let rollback;
+        if (index >= 0) {
+            const previous = this.offlineOps[index];
+            // The new operation changes the same remote version as the operation that it replaces
+            if (previous.base)
+                op.base = previous.base;
+            else
+                delete op.base;
+            this.offlineOps[index] = op;
+            rollback = () => {
+                const at = this.offlineOps.indexOf(op);
+                if (at >= 0)
+                    this.offlineOps[at] = previous;
+            };
+        }
+        else {
+            try {
+                this.ensureQueueRoom(op);
+            }
+            catch (error) {
+                await undo();
+                throw error;
+            }
+            this.offlineOps.push(op);
+            rollback = () => {
+                const at = this.offlineOps.indexOf(op);
+                if (at >= 0)
+                    this.offlineOps.splice(at, 1);
+            };
         }
-        this.offlineOps.push(op);
-        // Enforce max queue size
-        if (this.offlineOps.length > this.options.maxOfflineOps) {
-            this.offlineOps.shift(); // Remove oldest
+        this.unpersisted.add(op);
+        try {
+            await this.persist(op, index < 0, rollback);
+        }
+        catch (error) {
+            await undo();
+            throw error;
+        }
+    }
+    /**
+     * This method writes one operation to the queue store: an append when the store holds each operation
+     * before it, or else the whole queue. On a failure, `rollback` removes the operation from the
+     * queue before the next call of the store.
+     */
+    persist(op, appended, rollback) {
+        const run = this.storeChain.then(async () => {
+            // An earlier write of the whole queue kept it already
+            if (!this.unpersisted.has(op))
+                return;
+            const at = this.offlineOps.indexOf(op);
+            const canAppend = appended && !this.storeDirty && at >= 0 && this.offlineOps.slice(0, at).every((other) => !this.unpersisted.has(other));
+            const snapshot = this.offlineOps.slice();
+            try {
+                if (canAppend) {
+                    await this.queueStore.append(op);
+                    this.unpersisted.delete(op);
+                }
+                else {
+                    await this.queueStore.replace(snapshot);
+                    for (const kept of snapshot)
+                        this.unpersisted.delete(kept);
+                    this.unpersisted.delete(op);
+                    this.storeDirty = false;
+                }
+            }
+            catch (error) {
+                this.storeDirty = true;
+                this.unpersisted.delete(op);
+                rollback();
+                throw new QueueStoreError("write", error);
+            }
+        });
+        this.storeChain = run.catch(() => undefined);
+        return run;
+    }
+    /** This method writes the whole queue to the queue store when the store can differ from the queue. */
+    persistAll() {
+        const run = this.storeChain.then(async () => {
+            if (!this.storeDirty && this.unpersisted.size === 0)
+                return;
+            const snapshot = this.offlineOps.slice();
+            try {
+                if (snapshot.length === 0)
+                    await this.queueStore.clear();
+                else
+                    await this.queueStore.replace(snapshot);
+                for (const kept of snapshot)
+                    this.unpersisted.delete(kept);
+                this.storeDirty = false;
+            }
+            catch (error) {
+                this.storeDirty = true;
+                throw new QueueStoreError("write", error);
+            }
+        });
+        this.storeChain = run.catch(() => undefined);
+        return run;
+    }
+    /**
+     * Before a write goes to the remote directly, the queue store must not hold a sent operation:
+     * after a restart, it would replace this newer write.
+     */
+    async ensureStoreClean() {
+        if (this.storeDirty)
+            await this.persistAll();
+    }
+    /** The index of the queued operation that `op` replaces, or -1. */
+    replaceableIndex(op) {
+        if (op.type !== "set" && op.type !== "delete")
+            return -1;
+        const [id] = idsOf(op);
+        if (id === undefined)
+            return -1;
+        for (let index = this.offlineOps.length - 1; index >= 0; index--) {
+            const queued = this.offlineOps[index];
+            const ids = idsOf(queued);
+            if (!ids.includes(id) && !ids.includes("*"))
+                continue;
+            // pushQueue can be sending the first operation now: do not change it
+            const sending = index === 0 && this.pushing;
+            return !sending && (queued.type === "set" || queued.type === "delete") ? index : -1;
         }
+        return -1;
+    }
+    /** True when the queue can take the operation. */
+    hasQueueRoom(op) {
+        return this.replaceableIndex(op) >= 0 || this.offlineOps.length < this.options.maxOfflineOps;
+    }
+    /** A full queue refuses the write. Before, it dropped the oldest operation (roadmap R2). */
+    ensureQueueRoom(op) {
+        if (!this.hasQueueRoom(op))
+            throw new QueueFullError(this.options.maxOfflineOps);
+    }
+    /**
+     * In write-through mode, a timer sends the queue after a failure, and again after each failed
+     * send, until the queue is empty.
+     */
+    scheduleDrain() {
+        if (this.drainTimer || this.closed || this.mode !== "write-through")
+            return;
+        const delay = this.options.syncInterval > 0 ? this.options.syncInterval : 5000;
+        this.drainTimer = setTimeout(() => {
+            this.drainTimer = null;
+            this.syncToRemote().catch(() => this.scheduleDrain());
+        }, delay);
+        this.drainTimer.unref?.();
     }
     /**
      * Execute a queued operation against remote storage.
@@ -476,33 +1354,6 @@ export class HybridStorage {
                 break;
         }
     }
-    /**
-     * Handle remote operation failure.
-     */
-    handleRemoteFailure(operation, data) {
-        console.error(`Remote ${operation} failed, marking offline`);
-        this.isOnline = false;
-        // Queue operation if offline queue enabled
-        if (this.options.offlineQueue) {
-            this.queueOperation({
-                type: operation,
-                data,
-                timestamp: Date.now(),
-            });
-        }
-    }
-    /**
-     * Start periodic background sync.
-     */
-    startPeriodicSync() {
-        this.syncTimer = setInterval(() => {
-            this.syncToRemote().catch((err) => {
-                console.error("Periodic sync failed:", err);
-            });
-        }, this.options.syncInterval);
-        // The timer must not keep the process alive (deep dive DATA-9)
-        this.syncTimer.unref?.();
-    }
     /**
      * Get current online status.
      */