@procedures/store 0.7.0 → 0.8.1

package/dist/storage/hybrid.js

@@ -19,12 +19,124 @@
  * - Each write takes a copy of the value (`structuredClone`), for the local copy, the queue and the
  *   remote. The reads give the copies of the local copy, or of the remote in `remote-only` mode.
  * - A full sync reads the local ids with `getIds()`, so it does not copy each local item.
+ * - A pull reads a local item only when the result depends on it. With `versionOf`, the storage
+ *   knows the version of each local item that it wrote or read.
+ * - The timers run on the clock of the options. After a failed push, pull or send of the queue,
+ *   the next delay grows with `backoffDelay` of `@mark1russell7/service/backoff` (roadmap CLI-13).
+ * - `getStatus()` and `onStatus()` give the state of the sync and its errors. Before, the errors
+ *   went to the console.
+ * - `query()` runs a selector on the local copy, or on the remote in `remote-only` mode.
  * - After `close()`, each operation rejects, and a second `close()` does nothing.
+ *
+ * The sync engine of roadmap CLI-21 (decision D9: a SignalDB collection is one strategy of the local copy):
+ * - `observe()` gives the batches of the changes of the storage, with their origins.
+ * - `capture: "observe"` queues the changes that the application writes to the local copy itself.
+ * - `syncState` keeps the cursor and the base versions after a reload.
+ * - `feed` pushes the remote deltas. A delta whose `since` is the cursor applies without a read.
+ * - A pull never erases a delta that came during it, and the echo of an older own write never
+ *   writes over a newer local write.
+ * - The syncs of one storage run one at a time, in their order: the deltas and the hints of the
+ *   feed, the pulls, the pushes, the reads after an own write, and the mode switches. Thus a
+ *   remote delta and a full sync never run at the same time (Graph R18).
  */
-import { InMemoryStorage } from "@procedures/collections";
-import { optionalMs } from "@procedures/client";
+import { InMemoryStorage, StorageListeners } from "@procedures/collections";
+import { queryEntries, queryOptionsProblems, selectorProblems, } from "@procedures/client/query";
+import { optionalMs, realClock } from "@procedures/client";
+import { backoffDelay } from "@mark1russell7/service/backoff";
 import { MemoryQueueStore, idsOf, withoutId } from "./queue.js";
+import { isSyncState } from "./sync-state.js";
 const MODES = new Set(["local-only", "write-through", "write-back", "remote-only"]);
+/**
+ * A timer of a `HybridStorage` on a clock. It runs `work` after its interval. After a failed run,
+ * the next delay grows with `backoffDelay` (roadmap CLI-13). The timer does not keep a Node
+ * process alive.
+ */
+class SyncTimer {
+    options;
+    cancel;
+    active = false;
+    /** True while `work` runs */
+    running = false;
+    /** True when `start()` came during a run: the timer waits again after the run */
+    again = false;
+    failures = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * This method starts the timer. A timer that waits does not start again. A start during a run
+     * makes the timer wait again after the run, also when it does not repeat.
+     */
+    start() {
+        if (this.running) {
+            this.again = true;
+            if (this.active)
+                return;
+            this.active = true;
+            this.failures = 0;
+            return;
+        }
+        if (this.active)
+            return;
+        this.active = true;
+        this.failures = 0;
+        this.arm();
+    }
+    /** This method stops the timer. A run that is on its way ends, and no next run starts. */
+    stop() {
+        this.active = false;
+        this.again = false;
+        this.cancel?.();
+        this.cancel = undefined;
+    }
+    /** The delay of the next run: the interval, or the backoff after failures. */
+    delay() {
+        const { interval, factor, maxDelay, jitter, random } = this.options;
+        if (this.failures === 0)
+            return interval;
+        return backoffDelay({
+            base: interval,
+            factor,
+            cap: Math.max(maxDelay, interval),
+            jitter: jitter > 0 ? { kind: "subtract", fraction: jitter } : { kind: "none" },
+        }, this.failures + 1, random);
+    }
+    arm() {
+        const cancel = this.options.clock.after(this.delay(), () => {
+            this.cancel = undefined;
+            void this.run();
+        });
+        // The timer must not keep the process alive (deep dive DATA-9)
+        cancel.unref?.();
+        this.cancel = cancel;
+    }
+    async run() {
+        if (!this.active)
+            return;
+        this.running = true;
+        let failed = false;
+        try {
+            await this.options.work();
+            this.failures = 0;
+        }
+        catch {
+            // The work reports its error in the status of the storage
+            failed = true;
+            this.failures++;
+        }
+        finally {
+            this.running = false;
+        }
+        if (!this.active)
+            return;
+        const again = this.again;
+        this.again = false;
+        if (failed || again || this.options.repeat)
+            this.arm();
+        else
+            this.active = false;
+    }
+}
 /**
  * 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.
@@ -92,6 +204,17 @@ export class ModeSwitchError extends Error {
         this.to = to;
     }
 }
+/**
+ * The sync state store failed (roadmap CLI-21). The storage goes on: after a failed load, the first
+ * pull reads all items, and after a failed write, the next write gives the whole state.
+ */
+export class SyncStateError extends Error {
+    name = "SyncStateError";
+    code = "SYNC_STATE";
+    constructor(action, cause) {
+        super(`The sync state store could not ${action === "load" ? "load the state" : "keep the state"}`, { cause });
+    }
+}
 const defaultIsUnavailable = (error) => {
     if (typeof error !== "object" || error === null)
         return true;
@@ -110,6 +233,184 @@ function checkMode(mode) {
     }
     return mode;
 }
+/** A change with an origin, when there is one. */
+function withOrigin(change, origin) {
+    return origin === undefined ? change : { ...change, origin };
+}
+/** A `set` change with a copy of the value: an observer cannot change the stored item. */
+function setChange(id, value, origin) {
+    return withOrigin({ type: "set", id, value: structuredClone(value) }, origin);
+}
+/**
+ * The queued operations of a batch of changes of the local copy (roadmap CLI-21). The sets in a
+ * row go in one operation, and the deletes in a row too. Each value is a copy.
+ */
+function operationsOf(changes) {
+    const ops = [];
+    const timestamp = Date.now();
+    let sets = [];
+    let deletes = [];
+    const flush = () => {
+        if (sets.length === 1)
+            ops.push({ type: "set", data: { id: sets[0][0], value: sets[0][1] }, timestamp });
+        else if (sets.length > 1)
+            ops.push({ type: "setBatch", data: { items: sets }, timestamp });
+        if (deletes.length === 1)
+            ops.push({ type: "delete", data: { id: deletes[0] }, timestamp });
+        else if (deletes.length > 1)
+            ops.push({ type: "deleteBatch", data: { ids: deletes }, timestamp });
+        sets = [];
+        deletes = [];
+    };
+    for (const change of changes) {
+        if (change.type === "set") {
+            if (deletes.length > 0)
+                flush();
+            sets.push([change.id, structuredClone(change.value)]);
+        }
+        else if (change.type === "delete") {
+            if (sets.length > 0)
+                flush();
+            deletes.push(change.id);
+        }
+        else {
+            flush();
+            ops.push({ type: "clear", data: {}, timestamp });
+        }
+    }
+    flush();
+    return ops;
+}
+/**
+ * The batch of a write of the `remote-only` mode. A delete gives a change only for an id that
+ * existed: `existing` has the ids of a `deleteBatch`, or tells if a `clear` found items.
+ */
+function remoteChangesOf(op, result, existing, origin) {
+    const data = op.data;
+    switch (op.type) {
+        case "set":
+            return [setChange(data.id, data.value, origin)];
+        case "setBatch":
+            return data.items.map(([id, value]) => setChange(id, value, origin));
+        case "delete":
+            return result === true ? [withOrigin({ type: "delete", id: data.id }, origin)] : [];
+        case "deleteBatch":
+            return [...new Set(data.ids)].filter((id) => existing instanceof Set && existing.has(id)).map((id) => withOrigin({ type: "delete", id }, origin));
+        case "clear":
+            return existing === true ? [withOrigin({ type: "clear" }, origin)] : [];
+    }
+}
+/**
+ * The versions of the own writes of a `HybridStorage` that no remote change echoed yet (roadmap
+ * CLI-21, after the EchoLedger of Graph).
+ *
+ * - The ledger keeps the versions of each id in the order of the writes. It records a write when
+ *   the local copy takes it, because a stale echo can come before the push.
+ * - A remote change with a version of the ledger is an echo: that version and each older version
+ *   leave the ledger. When a newer version stays, the echo is stale: the newer echo comes later.
+ * - A remote change with another version is a write of another writer.
+ * - A version expires `window` milliseconds after its write, or after its send to the remote. Thus
+ *   a write whose echo never comes does not hold an id long.
+ */
+class EchoLedger {
+    window;
+    now;
+    maxPerId;
+    maxIds;
+    /** The versions of each id, the oldest first. The ids are in the order of their last write. */
+    entries = new Map();
+    constructor(window, now, maxPerId = 20, maxIds = 10_000) {
+        this.window = window;
+        this.now = now;
+        this.maxPerId = maxPerId;
+        this.maxIds = maxIds;
+    }
+    /** This method records the version that an own write of an id gives. `null`: a delete. */
+    wrote(id, version) {
+        const now = this.now();
+        const list = this.live(id, now);
+        list.push({ version, at: now });
+        if (list.length > this.maxPerId)
+            list.shift();
+        // The id moves to the end: the ids stay in the order of their last write
+        this.entries.delete(id);
+        this.entries.set(id, list);
+        this.prune(now);
+    }
+    /** This method records a delete of each id of the ledger: an own clear. */
+    cleared() {
+        for (const id of [...this.entries.keys()])
+            this.wrote(id, null);
+    }
+    /** This method starts the time of the versions of an id again: its write goes to the remote. */
+    sent(id) {
+        const list = this.entries.get(id);
+        if (!list)
+            return;
+        const now = this.now();
+        for (const entry of list)
+            entry.at = now;
+        this.entries.delete(id);
+        this.entries.set(id, list);
+    }
+    /**
+     * True when a remote version of an id is a stale echo: a version of the ledger, with a newer
+     * version after it. The echo takes its version and each older version out of the ledger.
+     */
+    isStale(id, version) {
+        const list = this.live(id, this.now());
+        const at = list.findIndex((entry) => entry.version === version);
+        if (at < 0)
+            return false;
+        list.splice(0, at + 1);
+        if (list.length > 0)
+            return true;
+        this.entries.delete(id);
+        return false;
+    }
+    /** The versions of an id that did not expire. */
+    live(id, now) {
+        const list = this.entries.get(id);
+        if (!list)
+            return [];
+        const kept = list.filter((entry) => now - entry.at < this.window);
+        if (kept.length === 0)
+            this.entries.delete(id);
+        else
+            this.entries.set(id, kept);
+        return kept;
+    }
+    /** This method drops the ids whose versions expired, and the oldest ids above the limit. */
+    prune(now) {
+        for (const [id, list] of this.entries) {
+            if (this.entries.size <= this.maxIds && now - list[list.length - 1].at < this.window)
+                break;
+            this.entries.delete(id);
+        }
+    }
+}
+/**
+ * The base versions of a `HybridStorage`: a map that keeps the ids that changed since the last
+ * write of the sync state (roadmap CLI-21). Without a sync state store, it keeps no ids.
+ */
+class BaseVersions extends Map {
+    /** The ids that changed since the last write of the sync state */
+    changed = new Set();
+    /** True when the storage has a sync state store */
+    tracked = false;
+    set(id, version) {
+        super.set(id, version);
+        if (this.tracked)
+            this.changed.add(id);
+        return this;
+    }
+    delete(id) {
+        const had = super.delete(id);
+        if (had && this.tracked)
+            this.changed.add(id);
+        return had;
+    }
+}
 /**
  * Hybrid storage combining local cache with remote persistence.
  *
@@ -151,14 +452,25 @@ export class HybridStorage {
     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;
+    /** The push timer of the write-back mode, or undefined without `syncInterval` */
+    pushTimer;
+    /** The periodic pull, or undefined without `pullInterval` */
+    pullTimer;
     /** 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;
+    drainTimer;
+    /** The failures that a later success did not clear, the newest last */
+    failures = new Map();
+    /** The number of pushes and pulls that run */
+    syncs = 0;
+    /** The time of the last pull that succeeded (`Date.now()`) */
+    lastSync;
+    /** The listeners of `onStatus()`, and the status that they got last */
+    statusListeners;
+    lastStatus;
+    /** The query policy of a call without a policy */
+    queryPolicy;
     /** 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. */
@@ -185,7 +497,57 @@ export class HybridStorage {
     /** 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();
+    bases = new BaseVersions();
+    /**
+     * With `versionOf`: the version of each local item that the storage wrote or read. A pull does
+     * not read an item whose version it knows. The version of an id that is not here is unknown.
+     */
+    localVersions = new Map();
+    /** The number of the last local write of each id that runs: only that write records a version */
+    localWrites = new Map();
+    localWriteCount = 0;
+    /** The number of clears of the local copy: a clear cancels the records of the writes that run */
+    localClears = 0;
+    /** The observers of `observe()` */
+    observers;
+    /** The tag of the writes of this storage, and the write options that give it */
+    origin;
+    own;
+    /** The origin of the changes that the sync makes in the local copy */
+    syncOrigin;
+    /** The push feed, the stop of its subscription, and the number of the subscription */
+    feed;
+    feedStop;
+    feedToken = 0;
+    /** True while a pull that a gap asked for waits to start */
+    gapPull = false;
+    /** The stop of the capture of the local copy */
+    stopCapture;
+    /** The captured changes that came before the end of the load. Undefined after the load. */
+    captured = [];
+    /** With `versionOf`: the versions of the own writes that wait for their echo */
+    echoes;
+    /** The store of the sync state, and the state of its writes */
+    stateStore;
+    stateReset = true;
+    savedCursor;
+    stateSaving;
+    stateAgain = false;
+    /** True when the application gave the local copy */
+    localGiven;
+    /**
+     * The own writes of the `write-through` mode that wait for the remote, for each id: their number
+     * and the newest value (`undefined` for a delete). A pull does not write over these ids.
+     */
+    inFlight = new Map();
+    /** The number of own clears that wait for the remote: each id waits */
+    inFlightClears = 0;
+    /** The remote values that a pull did not apply because an own write of the id waited: `undefined` for a delete */
+    deferred = new Map();
+    /** The number of the last local write, of the last write of each id, and of the last clear */
+    writeSeq = 0;
+    lastWrite = new Map();
+    lastClear = 0;
     stats = {
         cacheHits: 0,
         cacheMisses: 0,
@@ -209,12 +571,533 @@ export class HybridStorage {
             offlineQueue: options.offlineQueue ?? true,
             isUnavailable: options.isUnavailable ?? defaultIsUnavailable,
         };
+        this.statusListeners = new StorageListeners(options.onListenerError);
+        this.queryPolicy = options.queryPolicy;
+        this.origin = options.origin ?? `hybrid-${Math.random().toString(36).slice(2, 10)}`;
+        this.own = { origin: this.origin };
+        this.syncOrigin = options.syncOrigin ?? "sync";
+        this.observers = new StorageListeners(options.onListenerError);
+        this.feed = options.feed;
+        this.stateStore = options.syncState;
+        this.bases.tracked = this.stateStore !== undefined;
+        this.localGiven = options.local !== undefined;
+        // The timers on the clock, with the backoff after a failure (roadmap CLI-13)
+        const factor = options.backoff?.factor ?? 2;
+        if (!(Number.isFinite(factor) && factor >= 1))
+            throw new RangeError(`backoff.factor must be a number of 1 or more, not ${factor}`);
+        const jitter = options.backoff?.jitter ?? 0.5;
+        if (!(jitter >= 0 && jitter <= 1))
+            throw new RangeError(`backoff.jitter must be from 0 to 1, not ${jitter}`);
+        const timing = {
+            clock: options.clock ?? realClock,
+            factor,
+            maxDelay: optionalMs(options.backoff?.maxDelay, "backoff.maxDelay") ?? 300_000,
+            jitter,
+            random: options.random ?? Math.random,
+        };
+        this.pushTimer =
+            this.options.syncInterval > 0
+                ? new SyncTimer({ ...timing, interval: this.options.syncInterval, repeat: true, work: () => (this.closed ? Promise.resolve() : this.push()) })
+                : undefined;
+        this.pullTimer =
+            this.options.pullInterval > 0
+                ? new SyncTimer({ ...timing, interval: this.options.pullInterval, repeat: true, work: () => (this.closed ? Promise.resolve() : this.pull()) })
+                : undefined;
+        this.drainTimer = new SyncTimer({
+            ...timing,
+            interval: this.options.syncInterval > 0 ? this.options.syncInterval : 5000,
+            repeat: false,
+            work: () => (this.closed ? Promise.resolve() : this.push()),
+        });
+        // The echoes of the own writes: by version, or by the JSON of the value with a feed (roadmap CLI-21)
+        this.echoes = this.options.versionOf || this.feed
+            ? new EchoLedger(optionalMs(options.echoWindow, "echoWindow") ?? 30_000, () => timing.clock.now())
+            : undefined;
+        const capture = options.capture ?? "none";
+        if (capture !== "none" && capture !== "observe")
+            throw new TypeError(`Unknown capture ${JSON.stringify(capture)}: use none or observe`);
+        if (capture === "observe") {
+            if (!this.local.observe)
+                throw new TypeError('capture: "observe" needs a local copy with observe()');
+            // The capture starts before the load: a change of the application during the load waits for it
+            this.stopCapture = this.local.observe((batch) => this.onLocalChanges(batch));
+        }
+        else {
+            this.stopCapture = undefined;
+        }
         // 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();
     }
     //
+    // ═══ The status of the sync ═══
+    //
+    /**
+     * The state of the sync now (roadmap CLI-13).
+     *
+     * - `connected` is false after a remote call failed, until a remote call succeeds.
+     * - `pendingChanges` is the number of operations in the queue.
+     * - `syncing` is true while a push or a pull runs.
+     * - `lastSync` is the time (`Date.now()`) of the last pull that succeeded.
+     * - `error` is the newest failure of a load, a push, a pull or the queue store that a later
+     *   success of the same work did not clear.
+     */
+    getStatus() {
+        const error = [...this.failures.values()].at(-1);
+        return {
+            connected: this.isOnline,
+            lastSync: this.lastSync,
+            pendingChanges: this.offlineOps.length,
+            syncing: this.syncs > 0,
+            mode: this.mode,
+            ...(error !== undefined && { error }),
+        };
+    }
+    /**
+     * This method starts to send the status to a listener at each change: a failure, a sync that
+     * starts or ends, a change of the queue, of the connection or of the mode. A failure of a timer
+     * reaches the listeners here: the storage does not write to the console.
+     *
+     * @returns The function that stops the status. A second use of it does nothing.
+     */
+    onStatus(listener) {
+        if (this.closed)
+            throw this.closedError();
+        return this.statusListeners.add(listener);
+    }
+    //
+    // ═══ The changes of the storage (roadmap CLI-21) ═══
+    //
+    /**
+     * This method starts to send the changes of the storage to an observer. Each write that changes
+     * the storage gives one batch, before the write resolves.
+     *
+     * - A write of this storage gives its batch with the origin of its options.
+     * - A pull, a delta of the feed, a fill after a read and a mode switch give their changes with
+     *   `syncOrigin`.
+     * - With `capture: "observe"`, a write of the application to the local copy gives the batch of
+     *   the local copy, with its origin.
+     * - In `remote-only` mode, the batches tell the writes of this storage to the remote.
+     *
+     * @returns The function that stops the batches. A second use of it does nothing.
+     * @throws Error after `close()`
+     */
+    observe(observer) {
+        if (this.closed)
+            throw this.closedError();
+        return this.observers.add(observer);
+    }
+    /** This method sends a batch to the observers. */
+    emit(changes) {
+        if (changes.length > 0 && this.observers.size > 0)
+            this.observers.emit(changes);
+    }
+    /**
+     * This method takes a batch of the local copy. The changes whose origin is not the origin of this
+     * storage come from the application: the storage queues them, and its observers get them.
+     */
+    onLocalChanges(batch) {
+        if (this.closed)
+            return;
+        const foreign = batch.filter((change) => change.origin !== this.origin);
+        if (foreign.length === 0)
+            return;
+        if (this.captured)
+            this.captured.push(...foreign);
+        else
+            this.captureChanges(foreign);
+        this.emit(foreign);
+    }
+    /**
+     * This method queues the changes of the application to the local copy (roadmap CLI-21). The
+     * operations go in the queue at once, in the order of the changes. The queue store keeps them
+     * later. A failure of the store keeps them in memory, and the status shows it.
+     */
+    captureChanges(changes) {
+        if (this.loadError || this.closed)
+            return;
+        for (const op of operationsOf(changes)) {
+            this.noteCaptured(op);
+            this.noteOwnWrite(op);
+            this.attachBase(op);
+            this.enqueueCaptured(op);
+        }
+        this.notify();
+        if (this.mode === "write-through" || this.mode === "remote-only") {
+            // A failed send waits for the timer of the queue
+            void this.push().catch(() => this.scheduleDrain());
+        }
+    }
+    /**
+     * This method records a captured change as a local write: a sync that runs keeps its value, and
+     * the version of the local item is known.
+     */
+    noteCaptured(op) {
+        if (op.type === "clear") {
+            this.bumpClear();
+            this.localClears++;
+            this.localVersions.clear();
+            return;
+        }
+        const data = op.data;
+        const sets = op.type === "set" ? [[data.id, data.value]] : op.type === "setBatch" ? data.items : [];
+        const deletes = op.type === "delete" ? [data.id] : op.type === "deleteBatch" ? data.ids : [];
+        for (const [id, value] of sets) {
+            this.bump(id);
+            // A local write of the storage that runs now makes the version unknown
+            const version = this.localWrites.has(id) ? undefined : this.recordedVersion(value);
+            this.localWrites.delete(id);
+            if (version === undefined)
+                this.localVersions.delete(id);
+            else
+                this.localVersions.set(id, version);
+        }
+        for (const id of deletes) {
+            this.bump(id);
+            this.localWrites.delete(id);
+            this.localVersions.delete(id);
+        }
+    }
+    /** This method puts a captured operation in the queue, and then in the queue store. */
+    enqueueCaptured(op) {
+        const index = this.replaceableIndex(op);
+        if (index >= 0) {
+            const previous = this.offlineOps[index];
+            if (previous.base)
+                op.base = previous.base;
+            else
+                delete op.base;
+            this.offlineOps[index] = op;
+        }
+        else {
+            this.offlineOps.push(op);
+        }
+        this.unpersisted.add(op);
+        // The application made the change already: a failure of the store keeps the operation, and
+        // the next write of the store gives the whole queue
+        void this.persist(op, index < 0, () => undefined).catch(() => undefined);
+    }
+    /**
+     * This method queues the changes that the application made during the load. The load wrote the
+     * loaded queue to the local copy, so the changes go to the local copy again, in order.
+     */
+    async flushCaptured() {
+        const changes = [];
+        while (this.captured && this.captured.length > 0 && !this.loadError) {
+            const batch = this.captured.splice(0);
+            changes.push(...batch);
+            for (const op of operationsOf(batch))
+                await this.applyToLocal(op, this.syncOrigin);
+        }
+        this.captured = undefined;
+        if (changes.length > 0)
+            this.captureChanges(changes);
+    }
+    /**
+     * The mark of a value in the echo ledger: its version with `versionOf`, or else its JSON. A
+     * delete is `null` in the ledger: a tombstone, so an older echo does not bring the item back.
+     */
+    echoPrint(value) {
+        if (this.options.versionOf)
+            return this.recordedVersion(value);
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** This method records the versions of an own write, for its echo (roadmap CLI-21). */
+    noteOwnWrite(op) {
+        const echoes = this.echoes;
+        if (!echoes)
+            return;
+        const data = op.data;
+        const wrote = (id, value) => {
+            const print = this.echoPrint(value);
+            if (print !== undefined)
+                echoes.wrote(id, print);
+        };
+        switch (op.type) {
+            case "set":
+                wrote(data.id, data.value);
+                break;
+            case "setBatch":
+                for (const [id, value] of data.items)
+                    wrote(id, value);
+                break;
+            case "delete":
+                echoes.wrote(data.id, null);
+                break;
+            case "deleteBatch":
+                for (const id of data.ids)
+                    echoes.wrote(id, null);
+                break;
+            case "clear":
+                echoes.cleared();
+                break;
+        }
+    }
+    /** This method starts the echo time of the ids of an operation again: it goes to the remote. */
+    echoSent(op) {
+        if (!this.echoes)
+            return;
+        for (const id of idsOf(op))
+            if (id !== "*")
+                this.echoes.sent(id);
+    }
+    //
+    // ═══ The push feed (roadmap CLI-21, CLI-15) ═══
+    //
+    /** This method subscribes to the feed in the modes with a local copy and a remote, and stops it in the others. */
+    updateFeed() {
+        const feed = this.feed;
+        if (!feed)
+            return;
+        const wanted = !this.closed && (this.mode === "write-through" || this.mode === "write-back");
+        if (wanted === (this.feedStop !== undefined))
+            return;
+        const token = ++this.feedToken;
+        if (!wanted) {
+            const stop = this.feedStop;
+            this.feedStop = undefined;
+            try {
+                stop();
+            }
+            catch {
+                // The subscription is gone
+            }
+            return;
+        }
+        const live = () => token === this.feedToken && !this.closed;
+        try {
+            const stop = feed.subscribe({
+                onChanges: (changes) => {
+                    if (live())
+                        this.onRemoteChanges(changes);
+                },
+                onHint: (hint) => {
+                    if (live())
+                        this.onRemoteHint(hint);
+                },
+                onGap: () => {
+                    if (live())
+                        this.requestPull();
+                },
+                onError: (error) => {
+                    if (live())
+                        this.fail("pull", error);
+                },
+            });
+            if (live())
+                this.feedStop = stop;
+            else
+                stop();
+        }
+        catch (error) {
+            this.fail("pull", error);
+        }
+    }
+    /**
+     * This method takes a delta of the feed. The delta applies after the syncs that run, so a pull
+     * that runs does not erase it. Each decision about it comes when it applies, at its turn in the
+     * chain of the syncs, from the local state of that time: the queue, the own writes that wait,
+     * the echo ledger and the versions. On arrival, the storage keeps only the count of the local
+     * writes: a local write after the arrival is newer than the delta, and it keeps its value.
+     */
+    onRemoteChanges(changes) {
+        const mark = this.writeSeq;
+        void this.loaded
+            .then(() => this.serialize(() => this.track("pull", () => this.applyFeed(changes, mark))))
+            .catch(() => undefined);
+    }
+    /**
+     * This method applies a delta of the feed: without a read when its `since` is the cursor. A
+     * delta of the version of the cursor changes nothing. Another delta is a gap: a pull.
+     */
+    async applyFeed(changes, mark) {
+        if (this.loadError)
+            throw this.loadError;
+        if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back"))
+            return;
+        if (changes.version === this.cursor)
+            return;
+        if (changes.since === undefined || changes.since !== this.cursor) {
+            await this.pullRemote(false);
+            return;
+        }
+        await this.applyChanges(changes, (id) => this.changedSince(mark, id));
+    }
+    /**
+     * This method takes a hint of the feed: the ids that changed, without their values (roadmap
+     * CLI-15). The hint applies after the syncs that run, against the cursor and the local state of
+     * that time, as a delta does.
+     */
+    onRemoteHint(hint) {
+        const mark = this.writeSeq;
+        void this.loaded
+            .then(() => this.serialize(() => this.track("pull", () => this.applyHint(hint, mark))))
+            .catch(() => undefined);
+    }
+    /**
+     * This method applies a hint. A hint of the version of the cursor changes nothing. A hint whose
+     * `since` is the cursor and that changed no value applies its deletes without a read. Each other
+     * hint asks for a pull: the values come through the checks of a read of the remote, and the
+     * hints that come while the pull waits join it.
+     */
+    async applyHint(hint, mark) {
+        if (this.loadError)
+            throw this.loadError;
+        if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back"))
+            return;
+        if (hint.version !== undefined && hint.version === this.cursor)
+            return;
+        if (hint.since !== undefined && hint.since === this.cursor && hint.version !== undefined && hint.changed.length === 0) {
+            await this.applyChanges({ version: hint.version, full: false, changed: [], deleted: [...hint.deleted] }, (id) => this.changedSince(mark, id));
+            return;
+        }
+        this.requestPull();
+    }
+    /** This method asks for a pull after the syncs that run. A request while a pull waits joins it. */
+    requestPull() {
+        if (this.gapPull)
+            return;
+        this.gapPull = true;
+        void this.loaded
+            .then(() => this.serialize(() => {
+            this.gapPull = false;
+            if (this.closed)
+                return Promise.resolve();
+            return this.track("pull", async () => {
+                if (this.loadError)
+                    throw this.loadError;
+                if (this.mode === "write-through" || this.mode === "write-back")
+                    await this.pullRemote(false);
+            });
+        }))
+            .catch(() => undefined);
+    }
+    //
+    // ═══ The sync state (roadmap CLI-21) ═══
+    //
+    /** This method loads the sync state: the bases, and the cursor that the load then examines. */
+    async loadState() {
+        if (!this.stateStore)
+            return undefined;
+        try {
+            const state = await this.stateStore.load();
+            if (state === undefined)
+                return undefined;
+            if (!isSyncState(state))
+                throw new TypeError("The store gave a value that is not a sync state");
+            for (const [id, version] of state.bases)
+                this.bases.set(id, version);
+            return state.cursor;
+        }
+        catch (error) {
+            // The storage goes on without the state: the first pull reads all items
+            this.fail("store", new SyncStateError("load", error));
+            return undefined;
+        }
+    }
+    /**
+     * This method writes the changes of the sync state to its store: the cursor and the bases that
+     * changed. The writes run one at a time, and a change during a write goes in the next write.
+     */
+    saveState() {
+        if (!this.stateStore || this.loadError)
+            return;
+        if (!this.stateReset && this.bases.changed.size === 0 && this.cursor === this.savedCursor)
+            return;
+        if (this.stateSaving) {
+            this.stateAgain = true;
+            return;
+        }
+        this.stateSaving = this.writeState().finally(() => {
+            this.stateSaving = undefined;
+            if (this.stateAgain) {
+                this.stateAgain = false;
+                this.saveState();
+            }
+        });
+    }
+    /** One write of the sync state. The first write, and the write after a failure, give the whole state. */
+    async writeState() {
+        const reset = this.stateReset;
+        const ids = reset ? [...this.bases.keys()] : [...this.bases.changed];
+        this.bases.changed.clear();
+        this.stateReset = false;
+        const cursor = this.cursor;
+        const bases = [];
+        const forgotten = [];
+        for (const id of ids) {
+            const version = this.bases.get(id);
+            if (version === undefined)
+                forgotten.push(id);
+            else
+                bases.push([id, version]);
+        }
+        try {
+            await this.stateStore.write({ reset, cursor, bases, forgotten: reset ? [] : forgotten });
+            this.savedCursor = cursor;
+            this.succeed("store");
+        }
+        catch (error) {
+            this.stateReset = true;
+            this.fail("store", new SyncStateError("write", error));
+        }
+    }
+    /** This method sends the status to the listeners when it changed. */
+    notify() {
+        if (this.statusListeners.size === 0)
+            return;
+        const status = this.getStatus();
+        const last = this.lastStatus;
+        if (last &&
+            last.connected === status.connected &&
+            last.lastSync === status.lastSync &&
+            last.pendingChanges === status.pendingChanges &&
+            last.syncing === status.syncing &&
+            last.mode === status.mode &&
+            last.error === status.error) {
+            return;
+        }
+        this.lastStatus = status;
+        this.statusListeners.emit(status);
+    }
+    /** This method keeps a failure for the status. The failure of an operation replaces its older one. */
+    fail(operation, error) {
+        this.failures.delete(operation);
+        this.failures.set(operation, { operation, error });
+        this.notify();
+    }
+    /** This method clears the failure of an operation after a success. */
+    succeed(operation) {
+        if (this.failures.delete(operation))
+            this.notify();
+    }
+    /** A push or a pull: the status shows it while it runs, and keeps its failure. */
+    async track(operation, work) {
+        this.syncs++;
+        this.notify();
+        try {
+            await work();
+            this.succeed(operation);
+        }
+        catch (error) {
+            // A storage whose load failed keeps the failure of the load
+            if (error !== this.loadError)
+                this.fail(operation, error);
+            throw error;
+        }
+        finally {
+            this.syncs--;
+            this.notify();
+            this.saveState();
+        }
+    }
+    //
     // ═══ Modes ═══
     //
     /** The mode of the storage now. */
@@ -277,58 +1160,40 @@ export class HybridStorage {
         }
         this.mode = target;
         this.updateTimers();
+        this.notify();
+        this.saveState();
     }
     /** This method drops the local copy. A read in flight does not fill it again. */
     async dropLocal() {
-        this.clearVersion++;
+        this.bumpClear();
         this.cursor = undefined;
-        await this.local.clear();
+        await this.localClear(this.syncOrigin);
     }
     /** 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);
+            await this.applyToLocal(op, this.syncOrigin);
     }
-    /** This method starts and stops the timers for the mode. */
+    /**
+     * This method starts and stops the timers for the mode. The push timer runs in `write-back`, the
+     * pull timer in `write-through` and `write-back`, and the send of the queue after a failure only
+     * in `write-through`. A failed run reports its error in the status, and the next delay grows.
+     */
     updateTimers() {
         if (this.closed)
             return;
-        const push = this.mode === "write-back" && this.options.syncInterval > 0;
-        if (push && !this.syncTimer) {
-            this.syncTimer = setInterval(() => {
-                if (this.closed)
-                    return;
-                this.push().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(() => {
-                if (this.closed)
-                    return;
-                this.pull().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;
-        }
+        if (this.mode === "write-back")
+            this.pushTimer?.start();
+        else
+            this.pushTimer?.stop();
+        if (this.mode === "write-through" || this.mode === "write-back")
+            this.pullTimer?.start();
+        else
+            this.pullTimer?.stop();
+        if (this.mode !== "write-through")
+            this.drainTimer.stop();
+        this.updateFeed();
     }
     //
     // ═══ Read Operations ═══
@@ -349,17 +1214,18 @@ export class HybridStorage {
                 return cached;
             }
             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)) {
+            // A pending local delete means "no item": do not read it back from the remote. An own delete
+            // that waits for the remote too (roadmap CLI-21).
+            if (this.mode === "local-only" || this.hasPendingOp(id) || this.waitsForRemote(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 (this.writeKey(id) === version && !this.hasPendingOp(id) && !this.waitsForRemote(id)) {
                     if (remote !== undefined)
-                        await this.local.set(id, remote);
+                        await this.localSet(id, remote, this.syncOrigin);
                     this.noteBase(id, remote);
                 }
                 return remote;
@@ -388,6 +1254,24 @@ export class HybridStorage {
     async find(predicate) {
         return this.run(true, () => this.mode === "remote-only" ? this.remoteRead(() => this.remote.find(predicate)) : this.local.find(predicate));
     }
+    /**
+     * The entries whose items match the selector (roadmap CLI-14): from the local copy, or from the
+     * remote in `remote-only` mode. A storage under it with `query()` runs the selector itself, for
+     * example `ApiStorage` on its server. Else this method runs `queryEntries()` on its entries. The
+     * policy of the call, or of the options, goes to the storage under it.
+     */
+    async query(selector, options, policy) {
+        return this.run(true, async () => {
+            const limits = policy ?? this.queryPolicy;
+            const problems = [...selectorProblems(selector, limits), ...queryOptionsProblems(options, limits)];
+            if (problems.length > 0)
+                throw new TypeError(`The query is not correct: ${problems.join(". ")}`);
+            if (this.mode === "remote-only") {
+                return this.remoteRead(async () => this.remote.query ? this.remote.query(selector, options, limits) : queryEntries(await this.remoteEntries(), selector, options, limits));
+            }
+            return this.local.query ? this.local.query(selector, options, limits) : queryEntries(await this.local.getEntries(), selector, options, limits);
+        });
+    }
     async has(id) {
         return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remote.has(id)) : this.local.has(id)));
     }
@@ -417,45 +1301,51 @@ export class HybridStorage {
     //
     /**
      * This method sets an item. The storage takes a copy of the value, so a later change of the
-     * value does not change the local copy, the queue or the remote write.
+     * value does not change the local copy, the queue or the remote write. The origin of the options
+     * goes to the batches of `observe()`. The local copy and the remote get the origin of the storage.
      */
-    async set(id, written) {
+    async set(id, written, options) {
         const value = structuredClone(written);
-        await this.write("set", { id, value }, [id], async () => {
+        const origin = options?.origin;
+        await this.write("set", { id, value }, [id], origin, async () => {
             this.bump(id);
-            await this.local.set(id, value);
-        }, () => this.remote.set(id, value));
+            await this.localSet(id, value, origin);
+        }, () => this.remote.set(id, value, this.own));
     }
-    async delete(id) {
-        return this.write("delete", { id }, [id], async () => {
+    async delete(id, options) {
+        const origin = options?.origin;
+        return this.write("delete", { id }, [id], origin, async () => {
             this.bump(id);
-            return this.local.delete(id);
-        }, () => this.remote.delete(id));
+            return this.localDelete(id, origin);
+        }, () => this.remote.delete(id, this.own));
     }
-    async clear() {
-        await this.write("clear", {}, "*", async () => {
-            this.clearVersion++;
-            await this.local.clear();
-        }, () => this.remote.clear());
+    async clear(options) {
+        const origin = options?.origin;
+        await this.write("clear", {}, "*", origin, async () => {
+            this.bumpClear();
+            await this.localClear(origin);
+        }, () => this.remote.clear(this.own));
     }
     //
     // ═══ Bulk Operations ═══
     //
     /** This method sets several items. The storage takes a copy of each value, as `set` does. */
-    async setBatch(written) {
+    async setBatch(written, options) {
         const items = written.map(([id, value]) => [id, structuredClone(value)]);
-        await this.write("setBatch", { items }, items.map(([id]) => id), async () => {
+        const origin = options?.origin;
+        await this.write("setBatch", { items }, items.map(([id]) => id), origin, async () => {
             for (const [id] of items)
                 this.bump(id);
-            await this.local.setBatch(items);
-        }, () => this.remote.setBatch(items));
+            await this.localSetBatch(items, origin);
+        }, () => this.remote.setBatch(items, this.own));
     }
-    async deleteBatch(ids) {
-        return this.write("deleteBatch", { ids }, ids, async () => {
+    async deleteBatch(ids, options) {
+        const origin = options?.origin;
+        return this.write("deleteBatch", { ids }, ids, origin, async () => {
             for (const id of ids)
                 this.bump(id);
-            return this.local.deleteBatch(ids);
-        }, () => this.remote.deleteBatch(ids));
+            return this.localDeleteBatch(ids, origin);
+        }, () => this.remote.deleteBatch(ids, this.own));
     }
     /**
      * One write, in the mode of the storage. The result is the result of the local copy, or of the
@@ -474,14 +1364,18 @@ export class HybridStorage {
      * 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) {
+    write(type, data, ids, origin, 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();
+                    // The observers get a delete only for an id that existed
+                    const existing = this.observers.size > 0 ? await this.remoteExisting(op) : undefined;
                     const result = await applyRemote();
                     this.noteRemoteWrite(op);
+                    if (this.observers.size > 0)
+                        this.emit(remoteChangesOf(op, result, existing, origin));
                     return result;
                 };
                 try {
@@ -503,53 +1397,188 @@ export class HybridStorage {
             if (this.mode === "write-back" || this.mode === "local-only") {
                 this.ensureQueueRoom(op);
                 this.attachBase(op);
-                const undo = await this.snapshot(ids);
+                const undo = await this.snapshot(ids, origin);
                 const result = await applyLocal();
+                this.noteOwnWrite(op);
                 await this.enqueue(op, undo);
                 return result;
             }
-            const undo = await this.snapshot(ids);
-            const result = await applyLocal();
+            const undo = await this.snapshot(ids, origin);
+            // Until the remote takes the write, or the queue or the undo replaces it, a pull does not
+            // write over its local value (roadmap CLI-21)
+            this.startFlight(op);
             try {
-                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();
+                const result = await applyLocal();
+                this.noteOwnWrite(op);
+                try {
+                    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();
+                            this.echoSent(op);
+                            await applyRemote();
+                        });
+                    }
+                    else {
                         await this.ensureStoreClean();
+                        this.echoSent(op);
                         await applyRemote();
-                    });
+                    }
+                    this.isOnline = true;
+                    this.noteRemoteWrite(op);
                 }
-                else {
-                    await this.ensureStoreClean();
-                    await applyRemote();
+                catch (error) {
+                    if (!(error instanceof QueueStoreError) &&
+                        this.options.offlineQueue &&
+                        this.options.isUnavailable(error) &&
+                        this.hasQueueRoom(op)) {
+                        // The status shows the queue and the connection. The caller gets PendingWriteError.
+                        this.isOnline = false;
+                        this.attachBase(op);
+                        await this.enqueue(op, undo);
+                        this.scheduleDrain();
+                        throw new PendingWriteError(type, error);
+                    }
+                    await undo();
+                    throw error;
                 }
-                this.isOnline = true;
-                this.noteRemoteWrite(op);
+                return result;
             }
-            catch (error) {
-                if (!(error instanceof QueueStoreError) &&
-                    this.options.offlineQueue &&
-                    this.options.isUnavailable(error) &&
-                    this.hasQueueRoom(op)) {
+            finally {
+                this.endFlight(op);
+            }
+        });
+    }
+    //
+    // ═══ The own writes that wait for the remote (roadmap CLI-21) ═══
+    //
+    /** This method records an own write of the `write-through` mode that goes to the remote. */
+    startFlight(op) {
+        if (op.type === "clear") {
+            this.inFlightClears++;
+            return;
+        }
+        const data = op.data;
+        const values = op.type === "set" ? [[data.id, data.value]] :
+            op.type === "setBatch" ? data.items :
+                op.type === "delete" ? [[data.id, undefined]] :
+                    data.ids.map((id) => [id, undefined]);
+        for (const [id, value] of values) {
+            const flight = this.inFlight.get(id);
+            if (flight) {
+                flight.count++;
+                flight.value = value;
+            }
+            else {
+                this.inFlight.set(id, { count: 1, value });
+            }
+        }
+    }
+    /**
+     * This method ends an own write that went to the remote: the remote took it, or the queue or the
+     * undo replaced it. The deferred remote values of the ids that no own write waits for now go
+     * through a new read of the remote, after the syncs that run.
+     */
+    endFlight(op) {
+        if (op.type === "clear") {
+            this.inFlightClears--;
+        }
+        else {
+            for (const id of new Set(idsOf(op))) {
+                const flight = this.inFlight.get(id);
+                if (!flight)
+                    continue;
+                if (--flight.count <= 0)
+                    this.inFlight.delete(id);
+            }
+        }
+        const ready = [...this.deferred.keys()].filter((id) => !this.waitsForRemote(id));
+        if (ready.length === 0)
+            return;
+        void this.serialize(() => this.track("pull", () => this.applyDeferred(ready))).catch(() => undefined);
+    }
+    /** True when an own write of the id waits for the remote. */
+    waitsForRemote(id) {
+        return this.inFlightClears > 0 || this.inFlight.has(id);
+    }
+    /**
+     * True when a remote value of an id is the value of the newest own write that waits for the
+     * remote: its echo. `undefined` is a delete. With `versionOf` the versions decide, else the JSON.
+     */
+    isFlightValue(id, item) {
+        const flight = this.inFlight.get(id);
+        const value = flight ? flight.value : undefined;
+        if (item === undefined || value === undefined)
+            return item === undefined && value === undefined;
+        if (this.options.versionOf) {
+            const version = this.recordedVersion(item);
+            return version !== undefined && version === this.recordedVersion(value);
+        }
+        return JSON.stringify(item) === JSON.stringify(value);
+    }
+    /**
+     * A pull keeps the local value of an id whose own write waits for the remote, and the storage
+     * keeps the remote value for later. True when the pull defers the id. The echo of the write
+     * itself is not deferred: it is the local value.
+     */
+    deferIfInFlight(id, item) {
+        if (!this.waitsForRemote(id) || this.isFlightValue(id, item))
+            return false;
+        this.deferred.set(id, { item });
+        return true;
+    }
+    /**
+     * This method applies the deferred remote values of ids whose own writes ended. The storage
+     * reads each id from the remote again: the deferred value can be older than the write, or a
+     * newer write of another writer. Then the rules of a pull decide. When the remote cannot answer,
+     * the deferred value goes through the rules.
+     */
+    async applyDeferred(ids) {
+        if (this.loadError)
+            throw this.loadError;
+        if (this.closed)
+            return;
+        const conflicts = [];
+        let queueChanged = false;
+        for (const id of ids) {
+            const deferred = this.deferred.get(id);
+            // A new own write of the id waits: its end applies the value
+            if (!deferred || this.waitsForRemote(id))
+                continue;
+            this.deferred.delete(id);
+            const mark = this.writeSeq;
+            let item = deferred.item;
+            if (this.mode === "write-through" || this.mode === "write-back") {
+                try {
+                    item = await this.remote.get(id);
+                    this.isOnline = true;
+                }
+                catch {
+                    // The deferred value is the newest value that the storage knows
                     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;
             }
-            return result;
-        });
+            const changedLocally = (other) => this.changedSince(mark, other);
+            const changed = item === undefined
+                ? await this.pullDelete(id, changedLocally, conflicts)
+                : await this.pullItem(id, item, changedLocally, conflicts);
+            if (changed)
+                queueChanged = true;
+        }
+        if (queueChanged) {
+            this.storeDirty = true;
+            await this.persistAll().catch(() => undefined);
+        }
+        if (conflicts.length > 0)
+            throw new ConflictError(conflicts);
     }
     /**
      * 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) {
+    async snapshot(ids, origin) {
         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)
@@ -563,9 +1592,9 @@ export class HybridStorage {
                     continue;
                 const value = before.get(id);
                 if (value === undefined)
-                    await this.local.delete(id);
+                    await this.localDelete(id, origin);
                 else
-                    await this.local.set(id, value);
+                    await this.localSet(id, value, origin);
             }
         };
     }
@@ -616,25 +1645,25 @@ export class HybridStorage {
         await this.syncToRemote();
         await this.syncFromRemote();
     }
-    /** The pull of `syncFromRemote()`, after the syncs that run. */
+    /** The pull of `syncFromRemote()`, after the syncs that run. The status keeps its failure. */
     pull() {
-        return this.serialize(async () => {
+        return this.serialize(() => this.track("pull", async () => {
             await this.loaded;
             if (this.loadError)
                 throw this.loadError;
             if (this.mode === "write-through" || this.mode === "write-back")
                 await this.pullRemote(false);
-        });
+        }));
     }
-    /** The push of `syncToRemote()`, after the syncs that run. */
+    /** The push of `syncToRemote()`, after the syncs that run. The status keeps its failure. */
     push() {
-        return this.serialize(async () => {
+        return this.serialize(() => this.track("push", async () => {
             await this.loaded;
             if (this.loadError)
                 throw this.loadError;
             if (this.mode !== "local-only")
                 await this.pushQueue();
-        });
+        }));
     }
     /** The error of an operation after `close()`. */
     closedError() {
@@ -662,38 +1691,39 @@ export class HybridStorage {
     }
     /** The work of `close()`. */
     async shutDown() {
-        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;
-        // The operations and the switch that started before close() end first
-        await this.gate;
-        await this.idle();
-        // After the syncs that run: send the pending operations
-        await this.serialize(async () => {
-            if (this.loadError || this.offlineOps.length === 0 || this.mode === "local-only")
-                return;
+        this.pushTimer?.stop();
+        this.pullTimer?.stop();
+        this.drainTimer.stop();
+        this.updateFeed();
+        this.stopCapture?.();
+        try {
+            await this.loaded;
+            // The operations and the switch that started before close() end first
+            await this.gate;
+            await this.idle();
+            // After the syncs that run: send the pending operations. The queue store keeps the ones that
+            // the remote did not take, and the status gets the failure.
+            await this.serialize(async () => {
+                if (this.loadError || this.offlineOps.length === 0 || this.mode === "local-only")
+                    return;
+                await this.track("push", () => this.pushQueue()).catch(() => undefined);
+            });
+            await this.storeChain;
+            // The last changes of the sync state reach its store
+            this.saveState();
+            while (this.stateSaving)
+                await this.stateSaving;
+            // Close remote storage (an ApiStorage leaves the caller's client open)
             try {
-                await this.pushQueue();
+                await this.remote.close();
             }
-            catch (error) {
-                console.error("Failed to sync before close:", error);
+            finally {
+                await this.local.close();
             }
-        });
-        await this.storeChain;
-        // Close remote storage (an ApiStorage leaves the caller's client open)
-        try {
-            await this.remote.close();
         }
         finally {
-            await this.local.close();
+            this.statusListeners.clear();
+            this.observers.clear();
         }
     }
     /**
@@ -757,6 +1787,10 @@ export class HybridStorage {
                 for (const resolve of this.idleWaiters.splice(0))
                     resolve();
             }
+            // A write changes the queue, and a remote call the connection
+            this.notify();
+            // A remote write or a read of the remote changes the bases
+            this.saveState();
         }
     }
     /** A promise that resolves when no operation runs. */
@@ -767,13 +1801,17 @@ export class HybridStorage {
     }
     /** This method loads the queue, and puts its writes in the local copy. */
     async loadQueue() {
+        // The sync state first: its bases are newer than the bases of the queued operations
+        const cursor = await this.loadState();
         let ops;
         try {
             ops = await this.queueStore.load();
         }
         catch (error) {
+            // The storage refuses each operation. The status shows the failure.
             this.loadError = new QueueStoreError("load", error);
-            console.error("The queue store could not load the queue: the storage refuses each operation", error);
+            this.fail("load", this.loadError);
+            this.captured = undefined;
             return;
         }
         this.offlineOps = ops.slice();
@@ -785,12 +1823,17 @@ export class HybridStorage {
                 }
                 // A durable local copy can hold the operation already: each operation gives the same
                 // result two times
-                await this.applyToLocal(op);
+                await this.applyToLocal(op, this.syncOrigin);
             }
+            // The cursor belongs to a durable local copy with items. Else the first pull reads all items.
+            if (cursor !== undefined && this.localGiven && (await this.local.size()) > 0)
+                this.cursor = cursor;
+            await this.flushCaptured();
         }
         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);
+            this.fail("load", this.loadError);
+            this.captured = undefined;
         }
     }
     /** The first sync: send the loaded queue, then read the remote. */
@@ -799,41 +1842,154 @@ export class HybridStorage {
         if (this.loadError || this.closed)
             return;
         if (this.options.syncOnInit && this.mode !== "local-only") {
-            if (this.offlineOps.length > 0) {
-                await this.push().catch((err) => {
-                    console.error("Failed to send the queue on init:", err);
-                });
-            }
+            // A failure goes to the status: the reads go on with the local copy
+            if (this.offlineOps.length > 0)
+                await this.push().catch(() => undefined);
             if (!this.closed && (this.mode === "write-through" || this.mode === "write-back")) {
-                await this.pull().catch((err) => {
-                    console.error("Failed to sync on init:", err);
-                });
+                await this.pull().catch(() => undefined);
             }
         }
         if (this.offlineOps.length > 0)
             this.scheduleDrain();
     }
-    /** This method applies a queued operation to the local copy. */
-    async applyToLocal(op) {
+    /** This method applies a queued operation to the local copy. The observers get the origin. */
+    async applyToLocal(op, origin) {
         const data = op.data;
         switch (op.type) {
             case "set":
-                await this.local.set(data.id, data.value);
+                await this.localSet(data.id, data.value, origin);
                 break;
             case "delete":
-                await this.local.delete(data.id);
+                await this.localDelete(data.id, origin);
                 break;
             case "setBatch":
-                await this.local.setBatch(data.items);
+                await this.localSetBatch(data.items, origin);
                 break;
             case "deleteBatch":
-                await this.local.deleteBatch(data.ids);
+                await this.localDeleteBatch(data.ids, origin);
                 break;
             case "clear":
-                await this.local.clear();
+                await this.localClear(origin);
                 break;
         }
     }
+    //
+    // ═══ The writes of the local copy ═══
+    //
+    /**
+     * This method writes to the local copy. With `versionOf`, it records the version of each item
+     * that the write gives, so a pull does not read the item to know its version.
+     *
+     * - During the write, the versions of its ids are unknown. A failed write keeps them unknown.
+     * - Only the last write of an id that started records its version, and a clear that started
+     *   after the write cancels the record.
+     */
+    writeLocal(versionsOf, write) {
+        return this.options.versionOf ? this.recordedWrite(versionsOf(), write) : write();
+    }
+    /** The write of `writeLocal` with `versionOf`. */
+    async recordedWrite(versions, write) {
+        const clears = this.localClears;
+        const numbers = versions.map(([id]) => {
+            this.localVersions.delete(id);
+            const number = ++this.localWriteCount;
+            this.localWrites.set(id, number);
+            return number;
+        });
+        let written = false;
+        try {
+            const result = await write();
+            written = true;
+            return result;
+        }
+        finally {
+            versions.forEach(([id, version], index) => {
+                if (this.localWrites.get(id) !== numbers[index])
+                    return;
+                this.localWrites.delete(id);
+                if (written && version !== undefined && clears === this.localClears)
+                    this.localVersions.set(id, version);
+            });
+        }
+    }
+    /**
+     * This method reads a local item for a pull. With `versionOf`, it records the version of the item
+     * when no local write started or ran during the read.
+     */
+    async readLocal(id) {
+        const writes = this.localWriteCount;
+        const clears = this.localClears;
+        const item = await this.local.get(id);
+        if (item !== undefined &&
+            this.options.versionOf &&
+            writes === this.localWriteCount &&
+            clears === this.localClears &&
+            !this.localWrites.has(id)) {
+            const version = this.recordedVersion(item);
+            if (version !== undefined)
+                this.localVersions.set(id, version);
+        }
+        return item;
+    }
+    /** The version of an item for the record of the local copy, or undefined when `versionOf` fails. */
+    recordedVersion(item) {
+        try {
+            return this.versionOfItem(item);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // The writes of the local copy have the origin of this storage, so the capture does not queue
+    // them. The observers get each change with the origin of the caller.
+    async localSet(id, value, origin) {
+        await this.writeLocal(() => [[id, this.recordedVersion(value)]], () => this.local.set(id, value, this.own));
+        if (this.observers.size > 0)
+            this.emit([setChange(id, value, origin)]);
+    }
+    async localDelete(id, origin) {
+        const existed = await this.writeLocal(() => [[id, undefined]], () => this.local.delete(id, this.own));
+        if (existed)
+            this.emit([withOrigin({ type: "delete", id }, origin)]);
+        return existed;
+    }
+    async localSetBatch(items, origin) {
+        await this.writeLocal(() => items.map(([id, value]) => [id, this.recordedVersion(value)]), () => this.local.setBatch(items, this.own));
+        if (this.observers.size > 0)
+            this.emit(items.map(([id, value]) => setChange(id, value, origin)));
+    }
+    async localDeleteBatch(ids, origin) {
+        // The observers get a delete for each id that existed
+        const before = this.observers.size > 0 ? await this.local.getBatch(ids) : undefined;
+        const count = await this.writeLocal(() => ids.map((id) => [id, undefined]), () => this.local.deleteBatch(ids, this.own));
+        if (before && count > 0)
+            this.emit([...new Set(ids)].filter((id) => before.has(id)).map((id) => withOrigin({ type: "delete", id }, origin)));
+        return count;
+    }
+    localClear(origin) {
+        this.localClears++;
+        this.localVersions.clear();
+        if (this.observers.size === 0)
+            return this.local.clear(this.own);
+        return this.observedClear(origin);
+    }
+    /** A clear of the local copy with observers: they get the change when the copy had items. */
+    async observedClear(origin) {
+        const had = (await this.local.size()) > 0;
+        await this.local.clear(this.own);
+        if (had)
+            this.emit([withOrigin({ type: "clear" }, origin)]);
+    }
+    /** The ids that a delete of the `remote-only` mode finds, for its batch. */
+    async remoteExisting(op) {
+        if (op.type === "deleteBatch") {
+            const ids = [...new Set(op.data.ids)];
+            return new Set((await this.remote.getBatch(ids)).keys());
+        }
+        if (op.type === "clear")
+            return (await this.remote.size()) > 0;
+        return undefined;
+    }
     /**
      * One pull. `full`: ask for all items (after the local copy was dropped).
      *
@@ -842,10 +1998,8 @@ export class HybridStorage {
      *   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);
+        // A local write after this mark keeps its value: the remote value is older
+        const mark = this.writeSeq;
         let changes;
         try {
             changes = await this.fetchChanges(full);
@@ -855,6 +2009,14 @@ export class HybridStorage {
                 this.isOnline = false;
             throw error;
         }
+        await this.applyChanges(changes, (id) => this.changedSince(mark, id));
+    }
+    /**
+     * This method applies remote changes to the local copy: the changes of a pull, or a delta of
+     * the feed. `changedLocally` tells the ids that a local write changed after the changes left the
+     * remote: they keep their local values. The cursor moves only without conflicts.
+     */
+    async applyChanges(changes, changedLocally) {
         const conflicts = [];
         let queueChanged = false;
         const remoteIds = new Set();
@@ -872,9 +2034,8 @@ export class HybridStorage {
         }
         if (queueChanged) {
             this.storeDirty = true;
-            await this.persistAll().catch((error) => {
-                console.error("The queue store could not keep the queue after the sync:", error);
-            });
+            // The status gets the failure of the queue store. A later direct write repairs the store first.
+            await this.persistAll().catch(() => undefined);
         }
         this.stats.syncCount++;
         this.isOnline = true;
@@ -882,6 +2043,7 @@ export class HybridStorage {
             throw new ConflictError(conflicts);
         if (changes.version !== undefined)
             this.cursor = changes.version;
+        this.lastSync = Date.now();
     }
     /**
      * The remote changes: since the cursor from `getChangesSince` when the remote has it, or else
@@ -901,14 +2063,29 @@ export class HybridStorage {
         }
         return { full: true, changed: await this.remoteEntries(), deleted: [] };
     }
-    /** This method applies one remote item. It gives true when the queue changed. */
+    /**
+     * This method applies one remote item. It gives true when the queue changed.
+     *
+     * The pull reads the local item only when the result depends on it (roadmap R28):
+     * - An id with a queued write: only when the remote version changed after the last known remote
+     *   version. Without versions, the queued write wins, and the pull reads nothing.
+     * - An id without a queued write: not when the storage knows the version of the local item.
+     *   Without versions, the pull compares the JSON of the two items, so it reads the local item.
+     * Before, the pull read each local item.
+     */
     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);
+        // The echo of an older own write: a newer own write of the id, or its delete (a tombstone),
+        // waits for its echo (roadmap CLI-21)
+        const print = this.echoes ? this.echoPrint(item) : undefined;
+        if (print !== undefined && this.echoes?.isStale(id, print))
+            return false;
+        // An own write of the id waits for the remote: the remote value can be older (roadmap CLI-21)
+        if (this.deferIfInFlight(id, item))
+            return false;
+        const knownVersion = remoteVersion === undefined ? undefined : this.localVersions.get(id);
         if (this.hasPendingOp(id)) {
             // Without versions, the queued write wins, as before
             if (remoteVersion === undefined)
@@ -918,20 +2095,37 @@ export class HybridStorage {
             const base = this.bases.get(id);
             if (base === undefined || base === remoteVersion)
                 return false;
+            if (knownVersion === remoteVersion) {
+                this.bases.set(id, remoteVersion);
+                return false;
+            }
+            const localItem = await this.readLocal(id);
+            if (changedLocally(id))
+                return false;
             if (localItem !== undefined && this.versionOfItem(localItem) === remoteVersion) {
                 this.bases.set(id, remoteVersion);
                 return false;
             }
             return this.resolvePending(id, localItem, item, remoteVersion, conflicts);
         }
+        if (knownVersion !== undefined) {
+            // Only the remote changed: it is not a conflict. The version of the local item is known.
+            if (knownVersion !== remoteVersion)
+                await this.localSet(id, item, this.syncOrigin);
+            this.bases.set(id, remoteVersion);
+            return false;
+        }
+        const localItem = await this.readLocal(id);
+        if (changedLocally(id))
+            return false;
         const localVersion = localItem === undefined ? undefined : this.versionOfItem(localItem);
         if (localItem === undefined) {
-            await this.local.set(id, item);
+            await this.localSet(id, item, this.syncOrigin);
         }
         else if (remoteVersion !== undefined && localVersion !== undefined) {
             // Only the remote changed: it is not a conflict
             if (localVersion !== remoteVersion)
-                await this.local.set(id, item);
+                await this.localSet(id, item, this.syncOrigin);
         }
         else if (JSON.stringify(localItem) !== JSON.stringify(item)) {
             // Conflict - resolve according to strategy
@@ -941,7 +2135,7 @@ export class HybridStorage {
                 return false;
             }
             const resolved = this.resolveConflict(localItem, item);
-            await this.local.set(id, resolved);
+            await this.localSet(id, resolved, this.syncOrigin);
             this.stats.conflicts++;
         }
         if (remoteVersion !== undefined)
@@ -952,8 +2146,14 @@ export class HybridStorage {
     async pullDelete(id, changedLocally, conflicts) {
         if (changedLocally(id))
             return false;
+        // The echo of an older own delete: a newer own write of the id waits for its echo (roadmap CLI-21)
+        if (this.echoes?.isStale(id, null))
+            return false;
+        // An own write of the id waits for the remote: the remote delete can be older (roadmap CLI-21)
+        if (this.deferIfInFlight(id, undefined))
+            return false;
         if (!this.hasPendingOp(id)) {
-            await this.local.delete(id);
+            await this.localDelete(id, this.syncOrigin);
             if (this.options.versionOf)
                 this.bases.set(id, null);
             return false;
@@ -963,7 +2163,7 @@ export class HybridStorage {
         const base = this.bases.get(id);
         if (!this.options.versionOf || base === undefined || base === null)
             return false;
-        const localItem = await this.local.get(id);
+        const localItem = await this.readLocal(id);
         if (changedLocally(id))
             return false;
         if (localItem === undefined) {
@@ -976,7 +2176,7 @@ export class HybridStorage {
             case "remote":
                 if (!this.dropQueued(id))
                     break;
-                await this.local.delete(id);
+                await this.localDelete(id, this.syncOrigin);
                 this.bases.set(id, null);
                 return true;
             case "error":
@@ -1000,7 +2200,7 @@ export class HybridStorage {
                 // 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);
+                await this.localSet(id, remoteItem, this.syncOrigin);
                 this.bases.set(id, remoteVersion);
                 return true;
             case "merge": {
@@ -1009,7 +2209,7 @@ export class HybridStorage {
                 const merged = this.resolveConflict(localItem, remoteItem);
                 if (!this.dropQueued(id))
                     break;
-                await this.local.set(id, merged);
+                await this.localSet(id, merged, this.syncOrigin);
                 this.bases.set(id, remoteVersion);
                 this.offlineOps.push({ type: "set", data: { id, value: merged }, timestamp: Date.now(), base: [[id, remoteVersion]] });
                 return true;
@@ -1091,6 +2291,7 @@ export class HybridStorage {
                     continue;
                 }
                 try {
+                    this.echoSent(op);
                     await this.executeOperation(op);
                 }
                 catch (error) {
@@ -1111,10 +2312,9 @@ export class HybridStorage {
         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);
-                });
+                // The store keeps sent operations, and the status gets the failure. A later direct write
+                // repairs the store first.
+                await this.persistAll().catch(() => undefined);
             }
         }
     }
@@ -1126,6 +2326,16 @@ export class HybridStorage {
     }
     bump(id) {
         this.writeVersions.set(id, (this.writeVersions.get(id) ?? 0) + 1);
+        this.lastWrite.set(id, ++this.writeSeq);
+    }
+    /** A local clear: each id changed. */
+    bumpClear() {
+        this.clearVersion++;
+        this.lastClear = ++this.writeSeq;
+    }
+    /** True when a local write changed the id after the mark, a value of `writeSeq`. */
+    changedSince(mark, id) {
+        return this.lastClear > mark || (this.lastWrite.get(id) ?? 0) > mark;
     }
     /** The count of local writes of an id: it changes with each write and each clear. */
     writeKey(id) {
@@ -1326,12 +2536,15 @@ export class HybridStorage {
                     this.unpersisted.delete(op);
                     this.storeDirty = false;
                 }
+                this.succeed("store");
             }
             catch (error) {
                 this.storeDirty = true;
                 this.unpersisted.delete(op);
                 rollback();
-                throw new QueueStoreError("write", error);
+                const failure = new QueueStoreError("write", error);
+                this.fail("store", failure);
+                throw failure;
             }
         });
         this.storeChain = run.catch(() => undefined);
@@ -1351,10 +2564,13 @@ export class HybridStorage {
                 for (const kept of snapshot)
                     this.unpersisted.delete(kept);
                 this.storeDirty = false;
+                this.succeed("store");
             }
             catch (error) {
                 this.storeDirty = true;
-                throw new QueueStoreError("write", error);
+                const failure = new QueueStoreError("write", error);
+                this.fail("store", failure);
+                throw failure;
             }
         });
         this.storeChain = run.catch(() => undefined);
@@ -1397,19 +2613,12 @@ export class HybridStorage {
     }
     /**
      * In write-through mode, a timer sends the queue after a failure, and again after each failed
-     * send, until the queue is empty.
+     * send, until the queue is empty. The delay after a failed send grows with the backoff.
      */
     scheduleDrain() {
-        if (this.drainTimer || this.closed || this.mode !== "write-through")
+        if (this.closed || this.mode !== "write-through")
             return;
-        const delay = this.options.syncInterval > 0 ? this.options.syncInterval : 5000;
-        this.drainTimer = setTimeout(() => {
-            this.drainTimer = null;
-            if (this.closed)
-                return;
-            this.push().catch(() => this.scheduleDrain());
-        }, delay);
-        this.drainTimer.unref?.();
+        this.drainTimer.start();
     }
     /**
      * Execute a queued operation against remote storage.
@@ -1418,19 +2627,19 @@ export class HybridStorage {
         const data = op.data;
         switch (op.type) {
             case "set":
-                await this.remote.set(data.id, data.value);
+                await this.remote.set(data.id, data.value, this.own);
                 break;
             case "delete":
-                await this.remote.delete(data.id);
+                await this.remote.delete(data.id, this.own);
                 break;
             case "setBatch":
-                await this.remote.setBatch(data.items);
+                await this.remote.setBatch(data.items, this.own);
                 break;
             case "deleteBatch":
-                await this.remote.deleteBatch(data.ids);
+                await this.remote.deleteBatch(data.ids, this.own);
                 break;
             case "clear":
-                await this.remote.clear();
+                await this.remote.clear(this.own);
                 break;
         }
     }