@ny4n/durable 0.0.0-stage → 1.0.0

package/dist/session/session.js

@@ -0,0 +1,811 @@
+import { replicatedState } from "@ny4n/chord";
+import { awaitWithContext, BACKGROUND_CONTEXT, withoutAbortSignal } from "@ny4n/chord/context";
+import { track } from "@ny4n/chord/delta";
+import { addressId, checkRecordScope, checkRecordVersion, materializeDocument, resolveAddress, } from "../documents.js";
+import { SessionFailed, StorageRequestError } from "../errors.js";
+import { idFromNumber } from "../ids.js";
+import { CommittedStateSource, CommittedWatch, RETIREMENT_OPERATIONS, } from "./observation.js";
+import { Transaction } from "./transaction.js";
+/**
+ * Open a Session kernel over one storage backend. `now` is the wall clock for task times; default `Date.now`. The first
+ * error a Storage method throws fails the Session (`SessionFailed`); see `SessionImpl`.
+ */
+export function createSession(storage, options) {
+    const retention = options?.documentRetentionMs;
+    return new SessionImpl(storage, options?.now, retention === undefined ? undefined : () => retention);
+}
+/** Default document retention: ten minutes, as for kept contexts. */
+let defaultRetention = 600_000;
+/** Internal, for tests: the retention of every Session that keeps the default, as a suite run with eviction at once. */
+export function setDefaultDocumentRetention(ms) {
+    defaultRetention = ms;
+}
+/**
+ * A retention as given, when it is a number of milliseconds, `0` or more (`Infinity` keeps documents); otherwise the
+ * default.
+ */
+export function documentRetention(ms) {
+    return typeof ms === "number" && ms >= 0 ? ms : defaultRetention;
+}
+/** Longest delay `setTimeout` supports; a longer retention waits in several steps. */
+const MAX_TIMER_DELAY = 2_147_483_647;
+/**
+ * Session kernel: one mutation line, the loaded document tracker cache, and committed publication.
+ *
+ * The cache is bounded by use: a document with no watch or document state attached leaves it once it was not read or
+ * written for the retention period, and the next access loads it from Storage. Eviction runs as a job on the mutation
+ * line, so no transaction ever holds a tracker that leaves.
+ *
+ * Only committed state is observable. Every commit callback, preparation, Storage settlement, adoption, and
+ * publication enqueue runs while the line is held; listeners run later.
+ *
+ * Storage failures are final. Every Storage call goes through one guard: the first error a Storage method throws, other
+ * than for a cancelled caller, fails the Session, as does a commit it cannot adopt. That call gets the error; every later
+ * call and every Storage call still underway gets `SessionFailed`; close listeners run at once with the error, and the
+ * Session then closes itself, Storage included, and `closed` settles. Nothing retries: transient errors are the
+ * Storage's to retry. Reopening recovers from what was committed.
+ */
+export class SessionImpl {
+    #storage;
+    #documents = new Map();
+    /** Cached documents with no observer attached, by address, oldest use first, with the time of that use. */
+    #idleDocuments = new Map();
+    /** Observers attached per document incarnation (record ID); a cached incarnation with any is never evicted. */
+    #attachedDocuments = new Map();
+    #clock;
+    #documentRetentionMs;
+    /** The pending eviction: a timer for the oldest idle document, or a line job when the retention is 0. */
+    #documentSweep;
+    #sweepJobs = 0;
+    /** Set once a timer could not be unreferenced: then none is kept, and the end of each commit evicts what expired. */
+    #documentTimersUnavailable = false;
+    #commitListeners = new Set();
+    /** The Session's own listeners, such as its scheduler's: they keep memory in step with storage, so a throw fails it. */
+    #internalListeners = new Set();
+    #closeListeners = new Set();
+    #host;
+    #tail = Promise.resolve();
+    #closing;
+    #failure;
+    /** Set when close reaches the backend: calls that fail from then on fail because it closes. */
+    #failed = Promise.withResolvers();
+    #closed = Promise.withResolvers();
+    get closed() {
+        return this.#closed.promise;
+    }
+    /** Internal: the error that failed the Session, if one did. */
+    get failure() {
+        return this.#failure;
+    }
+    /** Internal: rejects with `SessionFailed` the moment the Session fails, before work underway has ended; never resolves. */
+    get failed() {
+        return this.#failed.promise;
+    }
+    constructor(storage, now = Date.now, documentRetentionMs = () => undefined) {
+        // Waits race it; none has to.
+        this.#failed.promise.catch(() => { });
+        this.#storage = new GuardedStorage(storage, this);
+        // Cache bookkeeping must never change the outcome of the operation it follows: a clock or a retention setting
+        // that throws counts as now, and as the default.
+        this.#clock = () => {
+            try {
+                return now();
+            }
+            catch {
+                return Date.now();
+            }
+        };
+        this.#documentRetentionMs = () => {
+            try {
+                return documentRetention(documentRetentionMs());
+            }
+            catch {
+                return documentRetention(undefined);
+            }
+        };
+        this.#host = {
+            storage: this.#storage,
+            now,
+            cached: (id) => {
+                const cached = this.#documents.get(id);
+                if (cached !== undefined)
+                    this.#touchDocument(id);
+                return cached;
+            },
+            load: (definition, addressId, address, context) => this.#loadDocument(definition, addressId, address, context),
+            install: (document) => {
+                this.#documents.set(document.addressId, document);
+                this.#touchDocument(document.addressId);
+            },
+            evict: (id, recordId) => {
+                if (this.#documents.get(id)?.record.id === recordId)
+                    this.#dropDocument(id);
+            },
+            conversationCreated: (tx, record) => this.conversationCreated(tx, record),
+        };
+    }
+    /** The Storage behind the failure guard; every component reads and writes through it. */
+    get storage() {
+        return this.#storage;
+    }
+    commit(change, context) {
+        return this.commitWith(change, context);
+    }
+    /**
+     * Internal: fail the Session with `error`, the first wins, and report it once. Admission ends, and close listeners run
+     * now; they read the error from `failure`. The Storage guard calls this; the Harness also calls it for a throw in its
+     * scheduler's own commits.
+     */
+    fail(error) {
+        if (this.#failure !== undefined)
+            return;
+        this.#failure = { error };
+        this.#failed.reject(new SessionFailed(error));
+        // Seal first, so a report handler that calls back finds the Session failed. Closing runs the close listeners
+        // synchronously; a failing backend close is the caller's to see, and here nobody waits.
+        this.close(BACKGROUND_CONTEXT).catch(() => { });
+        this.report(error);
+    }
+    /**
+     * Internal commit exposing the concrete transaction and its internal operations, such as the reserved-ID root
+     * bootstrap and task replacement. `scope` sets the default `tx.createTask()` conversation and the task attributed to
+     * appended entries.
+     */
+    commitWith(change, context, scope) {
+        try {
+            this.assertUsable();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return this.#enqueue(() => this.#runCommit(change, context, scope));
+    }
+    /** Internal: run a read-only job on the mutation line so multi-read derivations observe one committed state. */
+    readOnLine(job) {
+        try {
+            this.assertUsable();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return this.#enqueue(async () => {
+            this.#assertHealthy();
+            return job();
+        });
+    }
+    /**
+     * Internal: a conversation document's current incarnation and value, for a job already running on the line (see
+     * `readOnLine()`). Absent documents are `undefined`.
+     */
+    async conversationDocumentOnLine(token, conversationId, context) {
+        const definition = token.definition;
+        const resolved = resolveAddress(definition, [conversationId, context]);
+        const loaded = await this.#loadDocument(definition, resolved.id, resolved.address, context);
+        if (loaded === undefined)
+            return undefined;
+        checkRecordScope(definition, loaded.record);
+        checkRecordVersion(definition, loaded.record, loaded.storedVersion);
+        return { record: loaded.record, version: loaded.valueVersion, value: loaded.tracker.value };
+    }
+    async snapshot(token, ...args) {
+        this.assertUsable();
+        const definition = token.definition;
+        const resolved = resolveAddress(definition, args);
+        const context = args[resolved.nextArgument];
+        const cached = this.#documents.get(resolved.id);
+        if (cached?.valueVersion === definition.version)
+            this.#touchDocument(resolved.id);
+        const loaded = cached?.valueVersion === definition.version
+            ? cached
+            : await this.#enqueue(async () => {
+                this.#assertHealthy();
+                return this.#loadDocument(definition, resolved.id, resolved.address, context);
+            });
+        if (loaded === undefined)
+            return undefined;
+        checkRecordScope(definition, loaded.record);
+        checkRecordVersion(definition, loaded.record, loaded.storedVersion);
+        return loaded.tracker.value;
+    }
+    documentState(token, ...args) {
+        try {
+            this.assertUsable();
+            const definition = token.definition;
+            const resolved = resolveAddress(definition, args);
+            const context = args[resolved.nextArgument];
+            return this.#enqueue(async () => {
+                this.#assertHealthy();
+                const loaded = await this.#loadDocument(definition, resolved.id, resolved.address, context);
+                if (loaded === undefined)
+                    return undefined;
+                const { observer: source, detach } = this.#attachDocument(definition, loaded, (value, release) => new CommittedStateSource(value, release));
+                try {
+                    return replicatedState(source, { onError: (error) => this.report(error) });
+                }
+                catch (error) {
+                    detach();
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    async watchDoc(token, ...args) {
+        this.assertUsable();
+        const definition = token.definition;
+        const resolved = resolveAddress(definition, args);
+        const context = args[resolved.nextArgument];
+        const signal = context.abortSignal;
+        let cancelled = signal?.aborted ?? false;
+        const markCancelled = () => {
+            cancelled = true;
+        };
+        signal?.addEventListener("abort", markCancelled, { once: true });
+        try {
+            const watch = await this.#enqueue(async () => {
+                this.#assertHealthy();
+                if (cancelled)
+                    throw cancellationError(signal);
+                const loaded = await this.#loadDocument(definition, resolved.id, resolved.address, context);
+                if (cancelled)
+                    throw cancellationError(signal);
+                if (loaded === undefined)
+                    return undefined;
+                return this.#attachDocument(definition, loaded, (value, release) => new CommittedWatch(value, release, (error) => this.report(error))).observer;
+            });
+            if (watch === undefined)
+                return undefined;
+            if (cancelled) {
+                watch.cancel();
+                throw cancellationError(signal);
+            }
+            if (signal !== undefined)
+                watch.observeCancellation(signal);
+            return watch;
+        }
+        finally {
+            signal?.removeEventListener("abort", markCancelled);
+        }
+    }
+    async snapshotAsOf(token, ...args) {
+        this.assertUsable();
+        const definition = token.definition;
+        const resolved = resolveAddress(definition, args);
+        if (resolved.address.scope.kind !== "conversation") {
+            throw new TypeError("Session.snapshotAsOf() requires a conversation document");
+        }
+        const conversationId = resolved.address.scope.conversationId;
+        const atValue = args[resolved.nextArgument];
+        if (typeof atValue !== "number" || !Number.isSafeInteger(atValue)) {
+            throw new TypeError("Session.snapshotAsOf() requires an entry ID");
+        }
+        const at = idFromNumber(atValue);
+        const context = args[resolved.nextArgument + 1];
+        return this.#enqueue(async () => {
+            this.#assertHealthy();
+            const storedEntry = await this.#storage.entry(conversationId, at, context);
+            if (storedEntry === undefined) {
+                throw new Error(`Entry ${at} is not visible from conversation ${conversationId}`);
+            }
+            const address = {
+                ...resolved.address,
+                scope: { kind: "conversation", conversationId: storedEntry.entry.conversationId },
+            };
+            const record = await this.#storage.findDocument(address, storedEntry.commitSeq, context);
+            if (record === undefined)
+                return undefined;
+            const stored = await this.#storage.document(record.id, storedEntry.commitSeq, context);
+            if (stored === undefined) {
+                throw new Error(`Historical document ${record.id} (${record.kind}) cannot be read`);
+            }
+            return materializeDocument(definition, stored);
+        });
+    }
+    close(context) {
+        if (this.#closing === undefined) {
+            const cleanup = withoutAbortSignal(context);
+            // Seal admission before anything else runs, then stop observers; admitted work settles before Storage closes.
+            this.#closing = Promise.resolve()
+                .then(() => this.beforeClose())
+                .then(() => this.#enqueue(async () => {
+                this.#commitListeners.clear();
+                this.#internalListeners.clear();
+                this.#documents.clear();
+                this.#idleDocuments.clear();
+                this.#attachedDocuments.clear();
+                try {
+                    await this.#storage.close(cleanup);
+                }
+                catch (error) {
+                    // A Storage that cannot close is a failed one; an earlier failure stays the cause.
+                    if (this.#failure === undefined) {
+                        this.#failure = { error };
+                        this.report(error);
+                    }
+                    throw error;
+                }
+            }))
+                .finally(() => {
+                const failure = this.#failure;
+                this.#closed.resolve(failure === undefined ? { reason: "closed" } : { reason: "failed", error: failure.error });
+            });
+            this.#notifyClose();
+        }
+        return awaitWithContext(this.#closing, context);
+    }
+    /** Run the close listeners once, each on its own: one that fails is reported, and the rest still run. */
+    #notifyClose() {
+        if (this.#documentSweep?.timer !== undefined)
+            clearTimeout(this.#documentSweep.timer);
+        this.#documentSweep = undefined;
+        const listeners = [...this.#closeListeners];
+        this.#closeListeners.clear();
+        for (const listener of listeners)
+            contained(listener, (error) => this.report(error));
+    }
+    /** Internal: the Session's failure, and errors of listeners, which never fail what ran them. A plain Session drops them. */
+    report(_error) { }
+    /**
+     * Runs inside every transaction that creates or forks a conversation, after the conversation record is staged. A
+     * plain Session stages nothing; a Harness stages its built-in documents.
+     */
+    conversationCreated(_tx, _record) {
+        return Promise.resolve();
+    }
+    /** Runs after close seals admission and before the line closes Storage; must not reject. */
+    beforeClose() {
+        return Promise.resolve();
+    }
+    /** Register a synchronous post-adoption listener. It must not block or call Session operations; a throw is reported. */
+    subscribeCommits(listener) {
+        this.assertUsable();
+        this.#commitListeners.add(listener);
+        return () => this.#commitListeners.delete(listener);
+    }
+    /**
+     * Internal: `subscribeCommits()` for the Session's own components, whose state follows each commit. A throw leaves
+     * that state behind storage, so it fails the Session instead of being reported. They run before host listeners.
+     */
+    observeCommits(listener) {
+        this.assertUsable();
+        this.#internalListeners.add(listener);
+        return () => this.#internalListeners.delete(listener);
+    }
+    /**
+     * Register a listener called synchronously when close begins, also when a failure closes the Session (`failure` is
+     * then set). It must not block or call Session operations; a throw is reported.
+     */
+    subscribeClose(listener) {
+        this.assertUsable();
+        this.#closeListeners.add(listener);
+        return () => this.#closeListeners.delete(listener);
+    }
+    /** Drop every loaded tracker on the mutation line; later access cold-loads from Storage. */
+    unloadDocuments() {
+        return this.#enqueue(async () => {
+            this.#documents.clear();
+            this.#idleDocuments.clear();
+        });
+    }
+    /**
+     * Internal, for tests: how many documents the cache holds, how many are idle, how many incarnations are pinned, and how
+     * many sweep jobs were queued on the line so far.
+     */
+    get documentCacheSizes() {
+        return {
+            cached: this.#documents.size,
+            idle: this.#idleDocuments.size,
+            attached: this.#attachedDocuments.size,
+            sweeps: this.#sweepJobs,
+        };
+    }
+    /** Note a use of a cached document: an unattached one becomes the newest idle one, and an eviction is scheduled. */
+    #touchDocument(addressId) {
+        const cached = this.#documents.get(addressId);
+        if (cached === undefined || this.#attachedDocuments.has(cached.record.id))
+            return;
+        const now = this.#clock();
+        const since = this.#idleDocuments.get(addressId);
+        // A hot document moves to the back at most once per granule, a tenth of the retention up to 1 s: it may then leave
+        // up to a granule early, which costs a reload, while a commit-heavy workload skips the reordering.
+        if (since !== undefined && now - since < Math.min(1_000, this.#documentRetentionMs() / 10))
+            return;
+        this.#idleDocuments.delete(addressId);
+        this.#idleDocuments.set(addressId, now);
+        // A pending sweep for the oldest document comes first unless the retention was shortened since; then it moves up.
+        if (this.#documentSweep === undefined || this.#documentSweep.at > now + this.#documentRetentionMs()) {
+            this.#scheduleDocumentSweep();
+        }
+    }
+    #dropDocument(addressId) {
+        this.#documents.delete(addressId);
+        this.#idleDocuments.delete(addressId);
+    }
+    /**
+     * Schedule the eviction of the oldest idle document: on the line at once when the retention is 0, otherwise when it
+     * expires, by a timer that never keeps the process alive. Where timers cannot be unreferenced, as in Cloudflare
+     * Workers, none is kept: the end of each commit evicts what expired.
+     */
+    #scheduleDocumentSweep() {
+        if (this.#closing !== undefined)
+            return;
+        const oldest = this.#idleDocuments.values().next();
+        if (oldest.done === true)
+            return;
+        const at = oldest.value + this.#documentRetentionMs();
+        if (this.#documentSweep !== undefined && this.#documentSweep.at <= at)
+            return;
+        if (this.#documentSweep?.timer !== undefined)
+            clearTimeout(this.#documentSweep.timer);
+        // The pending sweep stays set until its job runs, so touches while the line is busy queue no more.
+        const sweep = { at, timer: undefined };
+        const run = () => {
+            this.#sweepJobs++;
+            this.#enqueue(async () => {
+                if (this.#documentSweep === sweep)
+                    this.#documentSweep = undefined;
+                if (this.#closing === undefined)
+                    this.#sweepDocuments();
+            }).catch(() => { });
+        };
+        const delay = at - this.#clock();
+        this.#documentSweep = sweep;
+        if (delay <= 0) {
+            queueMicrotask(run);
+            return;
+        }
+        if (this.#documentTimersUnavailable) {
+            this.#documentSweep = undefined;
+            return;
+        }
+        const timer = setTimeout(run, Math.min(delay, MAX_TIMER_DELAY));
+        const unref = timer.unref;
+        if (typeof unref !== "function") {
+            clearTimeout(timer);
+            this.#documentTimersUnavailable = true;
+            this.#documentSweep = undefined;
+            return;
+        }
+        unref.call(timer);
+        sweep.timer = timer;
+    }
+    /** On the line: evict the idle documents whose retention passed, oldest first, then schedule the next eviction. */
+    #sweepDocuments() {
+        const expired = this.#clock() - this.#documentRetentionMs();
+        for (const [addressId, since] of this.#idleDocuments) {
+            if (since > expired)
+                break;
+            this.#dropDocument(addressId);
+        }
+        this.#scheduleDocumentSweep();
+    }
+    /** Pin a cached incarnation for one observer; the returned release unpins it once, idle again after the last. */
+    #pinDocument(addressId, recordId) {
+        this.#attachedDocuments.set(recordId, (this.#attachedDocuments.get(recordId) ?? 0) + 1);
+        this.#idleDocuments.delete(addressId);
+        let pinned = true;
+        return () => {
+            if (!pinned)
+                return;
+            pinned = false;
+            const count = (this.#attachedDocuments.get(recordId) ?? 1) - 1;
+            if (count > 0) {
+                this.#attachedDocuments.set(recordId, count);
+                return;
+            }
+            this.#attachedDocuments.delete(recordId);
+            if (this.#documents.get(addressId)?.record.id === recordId)
+                this.#touchDocument(addressId);
+        };
+    }
+    async #runCommit(change, context, scope) {
+        this.#assertHealthy();
+        context.abortSignal?.throwIfAborted();
+        const tx = new Transaction(this.#host, context, scope);
+        let result;
+        try {
+            result = await change(tx);
+            // A callback that caught a failed read must not commit, nor succeed as if it had.
+            this.#assertHealthy();
+        }
+        catch (error) {
+            await tx.settleFailure();
+            this.#sweepDocuments();
+            throw error;
+        }
+        let writes;
+        try {
+            writes = await tx.settleSuccess();
+        }
+        catch (error) {
+            // Settlement aborted every change already.
+            this.#sweepDocuments();
+            throw error;
+        }
+        if (writes.length === 0) {
+            tx.discard();
+            this.#sweepDocuments();
+            return result;
+        }
+        let seq;
+        try {
+            // Once admitted, caller cancellation does not interrupt Storage settlement.
+            seq = await this.#storage.commit(writes, withoutAbortSignal(context));
+        }
+        catch (error) {
+            // The guard has failed the Session.
+            tx.discard();
+            throw error;
+        }
+        let documents;
+        try {
+            documents = tx.adopt(seq);
+        }
+        catch (error) {
+            // Storage already committed; a failed adoption leaves memory behind durable state.
+            this.fail(error);
+            throw error;
+        }
+        for (const document of documents)
+            this.#touchDocument(addressId(document.record));
+        this.#publish(seq, writes, documents, context);
+        this.#sweepDocuments();
+        return result;
+    }
+    #publish(seq, writes, documents, context) {
+        if (this.#commitListeners.size === 0 && this.#internalListeners.size === 0)
+            return;
+        const changes = [];
+        for (const write of writes) {
+            switch (write.type) {
+                case "conversation":
+                case "entry":
+                case "task":
+                case "submission":
+                    changes.push(write);
+            }
+        }
+        for (const document of documents)
+            changes.push(document);
+        const publication = { seq, changes };
+        // The commit is durable: a failing listener neither fails the commit nor skips the others.
+        for (const listener of [...this.#internalListeners]) {
+            contained(() => listener(publication, context), (error) => this.fail(error));
+        }
+        for (const listener of [...this.#commitListeners]) {
+            contained(() => listener(publication, context), (error) => this.report(error));
+        }
+    }
+    /**
+     * Attach an observer to one committed incarnation: check the definition, then forward this incarnation's committed
+     * changes and close. `detach` removes both subscriptions.
+     */
+    #attachDocument(definition, loaded, create) {
+        checkRecordScope(definition, loaded.record);
+        checkRecordVersion(definition, loaded.record, loaded.storedVersion);
+        let unsubscribeCommit = () => { };
+        let unsubscribeClose = () => { };
+        // Attached, the incarnation stays cached; once its last observer detaches, or it retires, it is idle again.
+        const unpin = this.#pinDocument(loaded.addressId, loaded.record.id);
+        const detach = () => {
+            unsubscribeCommit();
+            unsubscribeClose();
+            unpin();
+        };
+        let observer;
+        try {
+            observer = create(loaded.tracker.value, detach);
+        }
+        catch (error) {
+            unpin();
+            throw error;
+        }
+        const observed = { version: loaded.valueVersion };
+        unsubscribeCommit = this.observeCommits((publication, context) => {
+            for (const change of publication.changes) {
+                if (change.type !== "document" || change.record.id !== loaded.record.id)
+                    continue;
+                // A document state's frames carry no caller cancellation; a watch observes its own cancellation.
+                const frameContext = observer instanceof CommittedStateSource ? withoutAbortSignal(context) : context;
+                const ops = observedOperations(observed, change);
+                // A migration-only base changes nothing for an observer of the new version.
+                if (ops.length === 0)
+                    continue;
+                // A retired incarnation never changes again: its observers keep their last value but pin nothing.
+                if (change.value === null)
+                    unpin();
+                observer.advance(change.value, ops, frameContext);
+            }
+        });
+        unsubscribeClose = this.subscribeClose(() => observer.closeSession(this.#failure));
+        return { observer, detach };
+    }
+    async #loadDocument(definition, addressId, address, context) {
+        const cached = this.#documents.get(addressId);
+        // A tracker serves only tokens of the version its value was materialized for; others reload from Storage.
+        if (cached?.valueVersion === definition.version) {
+            this.#touchDocument(addressId);
+            return cached;
+        }
+        if (cached !== undefined)
+            this.#dropDocument(addressId);
+        const record = await this.#storage.findDocument(address, "current", context);
+        if (record === undefined)
+            return undefined;
+        const stored = await this.#storage.document(record.id, "current", context);
+        if (stored === undefined)
+            throw new Error(`Current document ${record.id} (${record.kind}) cannot be read`);
+        const value = materializeDocument(definition, stored);
+        const loaded = {
+            addressId,
+            record: stored.record,
+            storedVersion: stored.version,
+            valueVersion: definition.version,
+            deltasSinceBase: stored.deltasSinceBase,
+            tracker: track(value),
+        };
+        this.#documents.set(addressId, loaded);
+        this.#touchDocument(addressId);
+        return loaded;
+    }
+    #enqueue(job) {
+        const run = this.#tail.then(job);
+        this.#tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Internal: throw `SessionFailed` when failed, else an error when closing. */
+    assertUsable() {
+        this.#assertHealthy();
+        if (this.#closing !== undefined)
+            throw new Error("Session is closed");
+    }
+    #assertHealthy() {
+        if (this.#failure !== undefined)
+            throw new SessionFailed(this.#failure.error);
+    }
+}
+/**
+ * Run a host callback that must not fail its caller: a throw, or a promise it returns that rejects, goes to `onError`,
+ * which is not awaited.
+ */
+export function contained(callback, onError) {
+    try {
+        const result = callback();
+        // Any thenable, also a promise from another realm; `Promise.resolve` adopts it with handlers of its own.
+        if (typeof result?.then === "function")
+            Promise.resolve(result).catch(onError);
+    }
+    catch (error) {
+        onError(error);
+    }
+}
+/**
+ * Operations an observer applies for one committed change. An observer hydrated under another definition version holds
+ * a differently shaped value, so it receives the new value as a root replacement instead of operations for that shape.
+ */
+function observedOperations(observed, change) {
+    if (change.value === null)
+        return RETIREMENT_OPERATIONS;
+    if (change.version === observed.version)
+        return change.ops;
+    observed.version = change.version;
+    return [["r", change.value]];
+}
+function cancellationError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
+/**
+ * The Session's Storage behind its failure guard; every component of the Session reads and writes through it. Before a
+ * call, a failed Session gets `SessionFailed` without reaching the backend. A call that throws fails the Session and
+ * rethrows the backend's error, unless it is a `StorageRequestError` or a read whose caller's context was aborted:
+ * neither says the Storage is broken.
+ * `close()` always reaches the backend, so a failed Session still closes it.
+ */
+class GuardedStorage {
+    #storage;
+    #latch;
+    /** Backend calls underway, also those off the Session line, which close waits for before it closes the backend. */
+    #underway = new Set();
+    #closing = false;
+    constructor(storage, latch) {
+        this.#storage = storage;
+        this.#latch = latch;
+    }
+    /** Never exempt, whatever it throws: once admitted, whether a failed batch committed is unknown. */
+    commit(writes, context) {
+        return this.#call(undefined, () => this.#storage.commit(writes, context));
+    }
+    mintId() {
+        return this.#call(undefined, () => this.#storage.mintId());
+    }
+    conversation(id, context) {
+        return this.#call(context, () => this.#storage.conversation(id, context));
+    }
+    scanConversations(query, limit, cursor, context) {
+        return this.#call(context, () => this.#storage.scanConversations(query, limit, cursor, context));
+    }
+    entry(first, second, third) {
+        if (third === undefined) {
+            const context = second;
+            return this.#call(context, () => this.#storage.entry(first, context));
+        }
+        return this.#call(third, () => this.#storage.entry(first, second, third));
+    }
+    findLatestHeadMarker(conversationId, atOrBeforeEntryId, context) {
+        return this.#call(context, () => this.#storage.findLatestHeadMarker(conversationId, atOrBeforeEntryId, context));
+    }
+    scanEntries(query, limit, cursor, context) {
+        return this.#call(context, () => this.#storage.scanEntries(query, limit, cursor, context));
+    }
+    task(id, context) {
+        return this.#call(context, () => this.#storage.task(id, context));
+    }
+    scanTasks(query, limit, cursor, context) {
+        return this.#call(context, () => this.#storage.scanTasks(query, limit, cursor, context));
+    }
+    submission(id, context) {
+        return this.#call(context, () => this.#storage.submission(id, context));
+    }
+    scanSubmissions(query, limit, cursor, context) {
+        return this.#call(context, () => this.#storage.scanSubmissions(query, limit, cursor, context));
+    }
+    submissionByRequest(conversationId, requestId, context) {
+        return this.#call(context, () => this.#storage.submissionByRequest(conversationId, requestId, context));
+    }
+    findDocument(address, at, context) {
+        return this.#call(context, () => this.#storage.findDocument(address, at, context));
+    }
+    document(id, at, context) {
+        return this.#call(context, () => this.#storage.document(id, at, context));
+    }
+    scanDocuments(query, limit, cursor, context) {
+        return this.#call(context, () => this.#storage.scanDocuments(query, limit, cursor, context));
+    }
+    /**
+     * Close the backend once every call underway has settled, so none outlives it or fails after `closed` settles. New
+     * calls are refused from here on: a paged read must not start its next page while the backend closes.
+     */
+    async close(context) {
+        this.#closing = true;
+        await Promise.allSettled([...this.#underway]);
+        return this.#storage.close(context);
+    }
+    /**
+     * Run one backend call under the guard. `read` is a read's context; `commit()` and `mintId()` pass none, so nothing
+     * exempts their errors: once a batch is admitted, whether it committed is unknown. A call still underway when another
+     * fails the Session ends with `SessionFailed` too, whatever it returns: nothing it read or wrote is used.
+     */
+    async #call(read, run) {
+        this.#assertHealthy();
+        if (this.#closing)
+            throw new Error("Session is closed");
+        let result;
+        // An async wrapper, so a backend that throws synchronously is guarded too.
+        const call = (async () => run())();
+        this.#underway.add(call);
+        try {
+            result = await call;
+        }
+        catch (error) {
+            this.#assertHealthy();
+            // An invalid read, or one its caller cancelled, says nothing about the Storage; it fails that call only.
+            const exempt = read !== undefined && (error instanceof StorageRequestError || read.abortSignal?.aborted === true);
+            if (!exempt)
+                this.#latch.fail(error);
+            throw error;
+        }
+        finally {
+            this.#underway.delete(call);
+        }
+        this.#assertHealthy();
+        return result;
+    }
+    #assertHealthy() {
+        const failure = this.#latch.failure;
+        if (failure !== undefined)
+            throw new SessionFailed(failure.error);
+    }
+}
+//# sourceMappingURL=session.js.map