@earendil-works/chord 1.5.0 → 1.5.1

package/dist/documents/transaction.d.ts

@@ -0,0 +1,143 @@
+import { type Context } from "../context/index.ts";
+import { type Change, type Draft, type Tracker } from "../delta/index.ts";
+import type { JobHandle, Outcome, Run, StartOptions } from "../jobs/index.ts";
+import type { Columns, PutRowOf, RowOf } from "../store/columns.ts";
+import type { Condition, SetOf } from "../store/expression.ts";
+import type { ColumnRefs, Query } from "../store/query.ts";
+import type { StagedWrite } from "../store/step.ts";
+import type { ChordStore } from "../store/store.ts";
+import type { KeyOf } from "../store/table.ts";
+import { type Page, type PageOptions, type Table } from "../store/table-handle.ts";
+import type { CommitPersistence, JsonObject } from "./definition.ts";
+import type { Documents } from "./documents.ts";
+import type { SealToken } from "./fence.ts";
+import type { KeyedHandle, SingletonHandle } from "./handles.ts";
+import { type Stored } from "./persistence.ts";
+import type { DocumentSlot } from "./slot.ts";
+/** What `self.tx` gives its callback. Inside it: only `await tx.*`, no other `self.tx`, no calls to other objects. */
+export interface Tx {
+    /** The document's draft: the same one for the same document within one transaction. */
+    draft<T extends JsonObject>(handle: SingletonHandle<T>): Promise<Draft<T>>;
+    draft<T extends JsonObject>(handle: KeyedHandle<T>, key: string): Promise<Draft<T>>;
+    /** Retires the document when the transaction commits (its address reads `initial()` again); a no-op when it is absent. */
+    retire(handle: SingletonHandle<JsonObject>): Promise<void>;
+    retire(handle: KeyedHandle<JsonObject>, key: string): Promise<void>;
+    /**
+     * Starts a run of `job`, one of this object's jobs, with this transaction's other writes (§15): both commit or
+     * neither. Returns its `Run` at once; a discarded transaction's `Run` rejects `released` from `outcome`. A key of an
+     * unsettled run (one started earlier in this transaction too) returns that run.
+     */
+    start<A, R, S>(job: JobHandle<A, R, S>, args: A, options?: StartOptions): Run<Outcome<A, R, S>>;
+    /** The row with `key` as this transaction leaves it (its own `put`, `update`, `delete` overlaid; W10). */
+    get<C extends Columns, K extends readonly string[]>(table: Table<C, K>, key: KeyOf<C, K>): Promise<RowOf<C> | undefined>;
+    /** A page of committed rows, stable for the transaction (without its own writes). */
+    page<C extends Columns, K extends readonly string[]>(table: Table<C, K>, q: Query<C, K>, limit: number, options?: PageOptions): Promise<Page<RowOf<C>>>;
+    /** Every committed row of `q`, as `page`. */
+    rows<C extends Columns, K extends readonly string[]>(table: Table<C, K>, q: Query<C, K>): AsyncIterable<RowOf<C>>;
+    /** Writes `row` when the transaction commits (an upsert: the whole row replaced). */
+    put<C extends Columns, K extends readonly string[]>(table: Table<C, K>, row: PutRowOf<C>): void;
+    /** Changes the row with `key` when the transaction commits; an absent key changes nothing. */
+    update<C extends Columns, K extends readonly string[]>(table: Table<C, K>, key: KeyOf<C, K>, set: SetOf<C, K> | ((row: ColumnRefs<C>) => SetOf<C, K>)): void;
+    /** Deletes the row with `key` when the transaction commits. */
+    delete<C extends Columns, K extends readonly string[]>(table: Table<C, K>, key: KeyOf<C, K>): void;
+    /** Changes every row matching `where` when the transaction commits (one statement, its count recorded). */
+    updateWhere<C extends Columns, K extends readonly string[]>(table: Table<C, K>, where: (row: ColumnRefs<C>) => Condition, set: SetOf<C, K> | ((row: ColumnRefs<C>) => SetOf<C, K>)): void;
+    /** Deletes every row matching `where` when the transaction commits. */
+    deleteWhere<C extends Columns, K extends readonly string[]>(table: Table<C, K>, where: (row: ColumnRefs<C>) => Condition): void;
+}
+/**
+ * Chord's own changes staged in a transaction (a job's run records): adopted in its commit step with the documents,
+ * then told how the transaction ended, once the owner's line is free.
+ */
+export interface Staged {
+    /** Adopts the changes, inside the commit's batch. */
+    adopt(): void;
+    /** The transaction committed: the actions after the commit (a run starts, waiters settle). */
+    committed(): void;
+    /** The transaction was discarded: nothing was adopted. */
+    discarded(): void;
+}
+/**
+ * What one transaction does with one document: a draft, a retirement, or both (retired, then drafted anew); `found`
+ * is what is stored of a cold persisted document it retires without loading (R13).
+ */
+type Entry = {
+    readonly slot: DocumentSlot;
+    readonly key: string;
+    draft: {
+        readonly tracker: Tracker<JsonObject>;
+        readonly change: Change<JsonObject>;
+    } | undefined;
+    retire: boolean;
+    found: Stored | undefined;
+};
+/**
+ * One transaction of an object, under the seal token of whoever runs it (an attempt, a job run's invocation, the
+ * object). Commit prepares every draft (Delta records ops and checks only placed values) and adopts the changed
+ * documents and the staged changes in one batch; drafts are revoked once it settles. Cut at its token's seal, it
+ * discards everything, releases the line and refuses every later use.
+ */
+export declare class Transaction implements Tx {
+    #private;
+    readonly token: SealToken;
+    constructor(documents: Documents, token: SealToken, release: () => void, context: Context, persistence?: CommitPersistence);
+    /**
+     * The store writes of this transaction, which `write`s join (Chord's own documents: a job's run records): made by the
+     * first, which sends the commit through `store`'s step.
+     */
+    stageStore(store: ChordStore): StagedWrite[];
+    /**
+     * What its commit adopted: its documents, their ops, its store writes and the table rows they changed (all 0 before
+     * it committed).
+     */
+    committed(): {
+        readonly documents: number;
+        readonly ops: number;
+        readonly writes: number;
+        readonly rows: number;
+    };
+    /** The object whose transaction this is. */
+    get documents(): Documents;
+    draft<T extends JsonObject>(handle: SingletonHandle<T>): Promise<Draft<T>>;
+    draft<T extends JsonObject>(handle: KeyedHandle<T>, key: string): Promise<Draft<T>>;
+    /**
+     * The draft of the document at `key` of `slot` (Chord's own slots, a job's run states). A cold persisted document
+     * is loaded first, inside the transaction (it holds the line); the draft counts as pending until it settles (rule
+     * 3). A warm draft settles at once.
+     */
+    draftSlot(slot: DocumentSlot, key: string): Promise<Draft<JsonObject>>;
+    retire(handle: SingletonHandle<JsonObject>): Promise<void>;
+    retire(handle: KeyedHandle<JsonObject>, key: string): Promise<void>;
+    /** Retires the document at `key` of `slot` when the transaction commits. */
+    retireSlot(slot: DocumentSlot, key: string): Entry;
+    start<A, R, S>(job: JobHandle<A, R, S>, args: A, options?: StartOptions): Run<Outcome<A, R, S>>;
+    get<C extends Columns, K extends readonly string[]>(table: Table<C, K>, key: KeyOf<C, K>): Promise<RowOf<C> | undefined>;
+    page<C extends Columns, K extends readonly string[]>(table: Table<C, K>, q: Query<C, K>, limit: number, options?: PageOptions): Promise<Page<RowOf<C>>>;
+    rows<C extends Columns, K extends readonly string[]>(table: Table<C, K>, q: Query<C, K>): AsyncIterable<RowOf<C>>;
+    put<C extends Columns, K extends readonly string[]>(table: Table<C, K>, row: PutRowOf<C>): void;
+    update<C extends Columns, K extends readonly string[]>(table: Table<C, K>, key: KeyOf<C, K>, set: SetOf<C, K> | ((row: ColumnRefs<C>) => SetOf<C, K>)): void;
+    delete<C extends Columns, K extends readonly string[]>(table: Table<C, K>, key: KeyOf<C, K>): void;
+    updateWhere<C extends Columns, K extends readonly string[]>(table: Table<C, K>, where: (row: ColumnRefs<C>) => Condition, set: SetOf<C, K> | ((row: ColumnRefs<C>) => SetOf<C, K>)): void;
+    deleteWhere<C extends Columns, K extends readonly string[]>(table: Table<C, K>, where: (row: ColumnRefs<C>) => Condition): void;
+    /** The changes `owner` staged in this transaction, made by `make` on its first use. */
+    stage<S extends Staged>(owner: object, make: () => S): S;
+    /** The changes `owner` staged in this transaction so far, if any. */
+    staged<S extends Staged>(owner: object): S | undefined;
+    /**
+     * Prepares every draft and adopts what changed, and the staged changes, in one batch; nothing when nothing changed.
+     * A document retired and drafted anew is removed, then adopted: its frame carries the retirement. Persisted
+     * documents stage their writes here (rule 8), which sends the commit through the store's step.
+     */
+    commit(): void | Promise<void>;
+    /** Aborts every draft and prepared change. */
+    discard(): void;
+    /**
+     * Its token was sealed while it held the line: every draft is aborted, the line released, and every later use,
+     * its commit included, throws `released`.
+     */
+    cut(): void;
+    /** Tells the staged changes how the transaction ended; runs once the object's line is free. */
+    settle(): void;
+}
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/documents/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/documents/transaction.ts"],"names":[],"mappings":"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"}

package/dist/documents/transaction.js

@@ -0,0 +1,442 @@
+// Transactions (§9, R12, R13): drafts of an object's documents, prepared and adopted in one batch, with Chord's own
+// staged changes (job runs, §15), fenced by the token they run under; they run on the object's line (`line.ts`).
+import { withoutAbortSignal } from "../context/index.js";
+import { ChordError } from "../data/index.js";
+import { asChordError } from "../data/internal.js";
+import { track } from "../delta/index.js";
+import { refreshOf } from "../store/live-query.js";
+import { refusalOf } from "../store/refusal.js";
+import { TableChanges } from "../store/table-changes.js";
+import { ROWS_PAGE, TableHandle } from "../store/table-handle.js";
+import { checkReadable } from "./persistence.js";
+const IMMEDIATE = { kind: "immediate" };
+/**
+ * One transaction of an object, under the seal token of whoever runs it (an attempt, a job run's invocation, the
+ * object). Commit prepares every draft (Delta records ops and checks only placed values) and adopts the changed
+ * documents and the staged changes in one batch; drafts are revoked once it settles. Cut at its token's seal, it
+ * discards everything, releases the line and refuses every later use.
+ */
+export class Transaction {
+    #documents;
+    token;
+    #release;
+    #context;
+    #entries = new Map();
+    /** Chord's own staged changes, by their owner (a job); made by the first. */
+    #staged;
+    /**
+     * The store writes, in staging order, and the store they commit to; made by the first (the flag that sends the
+     * commit through the store's step, W12).
+     */
+    #writes;
+    /** The tables written, each with its writes and overlay. */
+    #tables;
+    /** `tx.*` reads underway: a callback settling with one is refused (rule 3, as Durable's). */
+    #pending = 0;
+    /** When its commit reaches the store (a run state's deferred change, D8). */
+    #persistence;
+    #state = "open";
+    /** Rejected by `cut` while the commit waits in the store's queue: its caller is told at once (rule 3). */
+    #queued;
+    /** What its commit adopts, once it started (telemetry's `chord.commit` counts it when asked). */
+    #adoptions = [];
+    /** The table rows its commit's step changed, once it committed through the store. */
+    #rows = 0;
+    constructor(documents, token, release, context, persistence = IMMEDIATE) {
+        this.#documents = documents;
+        this.token = token;
+        this.#release = release;
+        this.#context = context;
+        this.#persistence = persistence;
+    }
+    /**
+     * The store writes of this transaction, which `write`s join (Chord's own documents: a job's run records): made by the
+     * first, which sends the commit through `store`'s step.
+     */
+    stageStore(store) {
+        this.#writes ??= { store, staged: [] };
+        return this.#writes.staged;
+    }
+    /**
+     * What its commit adopted: its documents, their ops, its store writes and the table rows they changed (all 0 before
+     * it committed).
+     */
+    committed() {
+        let ops = 0;
+        for (const { prepared } of this.#adoptions)
+            ops += prepared?.ops.length ?? 0;
+        return { documents: this.#adoptions.length, ops, writes: this.#writes?.staged.length ?? 0, rows: this.#rows };
+    }
+    /** The object whose transaction this is. */
+    get documents() {
+        return this.#documents;
+    }
+    draft(handle, key = "") {
+        // Not `async`: the draft's promise is returned as it is, without another promise around it (the in-memory path
+        // stays as cheap as before the store); a throw still reaches the caller as a rejection.
+        let slot;
+        let at;
+        // Keyed keys follow the text rules (`KeyedSlot.key`); a singleton's key is always "".
+        try {
+            slot = this.#slotOf(handle);
+            at = key === "" ? key : slot.key(key);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        // The entry is made for this handle's slot, whose documents are `T`.
+        return this.draftSlot(slot, at);
+    }
+    /**
+     * The draft of the document at `key` of `slot` (Chord's own slots, a job's run states). A cold persisted document
+     * is loaded first, inside the transaction (it holds the line); the draft counts as pending until it settles (rule
+     * 3). A warm draft settles at once.
+     */
+    async draftSlot(slot, key) {
+        const entry = this.#entry(slot, key);
+        const persisted = slot.persisted;
+        if (entry.draft !== undefined || entry.retire || persisted?.cold(key) !== true)
+            return this.#begin(entry);
+        this.#pending++;
+        try {
+            await persisted.load(key, this.#context, this.token);
+            this.#assertOpen();
+            return this.#begin(entry);
+        }
+        finally {
+            this.#pending--;
+        }
+    }
+    async retire(handle, key = "") {
+        const slot = this.#slotOf(handle);
+        const at = key === "" ? key : slot.key(key);
+        const entry = this.retireSlot(slot, at);
+        const persisted = slot.persisted;
+        // A cold persisted document is found, not loaded (one read; absent: a no-op, R13); a version or fingerprint
+        // the code cannot read fails the owner as a load would (R15): a retirement of it is no exception.
+        if (entry.found === undefined && persisted?.cold(at)) {
+            const found = await this.#track(persisted.persistence.find(at, this.#context));
+            // Cut meanwhile: its attempt was sealed, and failing the owner now would fail its successor.
+            this.#assertOpen();
+            if (found !== undefined)
+                checkFound(found, persisted, slot);
+            entry.found = found?.stored;
+        }
+    }
+    /** Retires the document at `key` of `slot` when the transaction commits. */
+    retireSlot(slot, key) {
+        const entry = this.#entry(slot, key);
+        entry.draft?.change.abort();
+        entry.draft = undefined;
+        entry.retire = true;
+        return entry;
+    }
+    start(job, args, options = {}) {
+        // Job handles are Chord's own: `self.job` made them.
+        return job.stage(this, args, this.#context, options);
+    }
+    get(table, key) {
+        const handle = this.#handle(table);
+        const changes = this.#tables?.get(handle);
+        const read = changes === undefined ? handle.get(key, this.#context) : changes.get(key, this.#context);
+        // The handle's rows are the table's, typed by `C`.
+        return this.#track(read);
+    }
+    page(table, q, limit, options = {}) {
+        // As in `get`; the query's table is checked against the handle's.
+        const read = this.#handle(table).page(q, limit, this.#context, options);
+        return this.#track(read);
+    }
+    async *rows(table, q) {
+        let after;
+        do {
+            const page = await this.page(table, q, ROWS_PAGE, after === undefined ? {} : { after });
+            yield* page.items;
+            after = page.next;
+        } while (after !== undefined);
+    }
+    put(table, row) {
+        this.#changes(table).put(row);
+    }
+    update(table, key, set) {
+        this.#changes(table).update(key, set);
+    }
+    delete(table, key) {
+        this.#changes(table).delete(key);
+    }
+    updateWhere(table, where, set) {
+        this.#changes(table).updateWhere(where, set);
+    }
+    deleteWhere(table, where) {
+        this.#changes(table).deleteWhere(where);
+    }
+    /** The changes `owner` staged in this transaction, made by `make` on its first use. */
+    stage(owner, make) {
+        this.#assertOpen();
+        this.#staged ??= new Map();
+        let staged = this.#staged.get(owner);
+        if (staged === undefined) {
+            staged = make();
+            this.#staged.set(owner, staged);
+        }
+        // Each owner stages one kind of change, the one its `make` returns.
+        return staged;
+    }
+    /** The changes `owner` staged in this transaction so far, if any. */
+    staged(owner) {
+        // As in `stage`: the owner's own kind.
+        return this.#staged?.get(owner);
+    }
+    /**
+     * Prepares every draft and adopts what changed, and the staged changes, in one batch; nothing when nothing changed.
+     * A document retired and drafted anew is removed, then adopted: its frame carries the retirement. Persisted
+     * documents stage their writes here (rule 8), which sends the commit through the store's step.
+     */
+    commit() {
+        this.#assertOpen();
+        if (this.#pending > 0)
+            throw new Error(`${this.#documents.label}: the callback settled before its pending tx operations`);
+        if (this.#tables !== undefined)
+            this.#refreshQueries(this.#tables);
+        this.#state = "committing";
+        this.#context.abortSignal?.throwIfAborted();
+        const adoptions = [];
+        for (const entries of this.#entries.values()) {
+            for (const entry of entries.values()) {
+                let prepared = entry.draft?.change.prepare();
+                if (prepared !== undefined && prepared.ops.length === 0) {
+                    prepared.abort();
+                    prepared = undefined;
+                }
+                const { slot, key } = entry;
+                const retires = entry.retire && (slot.current(key) !== undefined || entry.found !== undefined);
+                if (prepared === undefined && !retires)
+                    continue;
+                const persisted = slot.persisted;
+                let stored;
+                if (persisted !== undefined) {
+                    const writes = this.stageStore(persisted.persistence.store);
+                    const was = persisted.stored(key) ?? entry.found;
+                    stored = persisted.stage(key, { prepared, retires }, was, writes, this.#persistence);
+                }
+                adoptions.push({ entry, prepared, retires, stored });
+            }
+        }
+        const writes = this.#writes;
+        this.#adoptions = adoptions;
+        if (writes === undefined) {
+            this.#adopt(adoptions);
+            this.#state = "committed";
+            return;
+        }
+        return this.#step(writes.store, writes.staged, adoptions);
+    }
+    /**
+     * Commits through the store's step (§3): admitted while neither cut nor sealed (else `released`, nothing written),
+     * then the documents and staged changes adopted inside the step. Once queued, the caller's abort no longer counts;
+     * a cut while queued rejects `released` at once (the queue drops the entry at its admission, writing nothing).
+     */
+    async #step(store, staged, adoptions) {
+        const fence = {
+            admit: () => {
+                if (this.#state !== "committing" || this.token.sealed)
+                    return false;
+                this.#state = "stepping";
+                return true;
+            },
+            adopt: (_seq, _ids, rows) => {
+                this.#rows = rows;
+                this.#adopt(adoptions);
+            },
+        };
+        this.#queued = Promise.withResolvers();
+        try {
+            // The race handles the commit's own later rejection too.
+            await Promise.race([store.commit(staged, fence, withoutAbortSignal(this.#context)), this.#queued.promise]);
+        }
+        catch (error) {
+            if (this.#state === "cut")
+                throw this.#cutError();
+            throw this.#refused(error);
+        }
+        finally {
+            this.#queued = undefined;
+        }
+        this.#state = "committed";
+    }
+    /**
+     * The error a commit the store rejected rejects with (D4): the store's own (`released`, `storage_failed`) as it
+     * is; a refused step classified, an `int` `CHECK` failing only this transaction (`invalid/args`), any other refusal
+     * failing the live object `broken` too (memory and disk disagree).
+     */
+    #refused(error) {
+        const refusal = refusalOf(error, this.#documents.label);
+        if (refusal === undefined)
+            return error;
+        if (refusal.kind === "broken")
+            this.#documents.fail(refusal.error);
+        return refusal.error;
+    }
+    /**
+     * Adopts the changed documents (persisted ones with what the commit stored of them) and the staged changes in one
+     * batch; nothing when nothing changed.
+     */
+    #adopt(adoptions) {
+        const staged = this.#staged;
+        if (adoptions.length === 0 && staged === undefined)
+            return;
+        this.#documents.batch.commit(() => {
+            for (const { entry, prepared, retires, stored } of adoptions) {
+                if (retires)
+                    entry.slot.retire(entry.key);
+                if (prepared === undefined)
+                    continue;
+                entry.slot.adopt(entry.key, entry.draft.tracker, prepared, stored);
+            }
+            for (const each of staged?.values() ?? [])
+                each.adopt();
+        }, this.#context);
+    }
+    /** Aborts every draft and prepared change. */
+    discard() {
+        if (this.#state === "cut")
+            return;
+        this.#state = "discarded";
+        this.#abortDrafts();
+    }
+    /**
+     * Its token was sealed while it held the line: every draft is aborted, the line released, and every later use,
+     * its commit included, throws `released`.
+     */
+    cut() {
+        // A commit admitted to the step runs to its end; one still queued is refused at admission.
+        if (this.#state !== "open" && this.#state !== "committing")
+            return;
+        this.#state = "cut";
+        this.#abortDrafts();
+        this.#release();
+        this.#queued?.reject(this.#cutError());
+    }
+    /** Tells the staged changes how the transaction ended; runs once the object's line is free. */
+    settle() {
+        if (this.#staged === undefined)
+            return;
+        const committed = this.#state === "committed";
+        for (const staged of this.#staged.values()) {
+            if (committed)
+                staged.committed();
+            else
+                staged.discarded();
+        }
+    }
+    #abortDrafts() {
+        for (const entries of this.#entries.values())
+            for (const entry of entries.values())
+                entry.draft?.change.abort();
+    }
+    /** The slot behind a handle of this object, after the handle's version fence (R15). */
+    #slotOf(handle) {
+        // Handles are Chord's own: `self.state` made them.
+        const { slot, version } = handle;
+        slot.definition.assertVersion(version);
+        return slot;
+    }
+    #entry(slot, key) {
+        this.#assertOpen();
+        if (slot.owner !== this.#documents) {
+            throw new Error(`${this.#documents.label}: a transaction drafts only its own object's documents`);
+        }
+        let entries = this.#entries.get(slot);
+        if (entries === undefined) {
+            entries = new Map();
+            this.#entries.set(slot, entries);
+        }
+        let entry = entries.get(key);
+        if (entry === undefined) {
+            entry = { slot, key, draft: undefined, retire: false, found: undefined };
+            entries.set(key, entry);
+        }
+        return entry;
+    }
+    #assertOpen() {
+        if (this.#state === "open")
+            return;
+        if (this.#state === "cut")
+            throw this.#cutError();
+        throw new Error(`${this.#documents.label}: the transaction has settled`);
+    }
+    #cutError() {
+        return new ChordError({
+            code: "released",
+            reason: "discarded",
+            message: `${this.#documents.label}: the transaction was discarded at the seal`,
+        });
+    }
+    /** The handle behind `table`, one of this object's tables (another object's is refused). */
+    #handle(table) {
+        this.#assertOpen();
+        // Plugin code may pass any table: only this object's handles are taken.
+        const handle = table;
+        if (!(handle instanceof TableHandle) || handle.owner.scope !== this.#documents) {
+            throw new Error(`${this.#documents.label}: a transaction writes only its own object's tables`);
+        }
+        handle.assertVersion();
+        return handle;
+    }
+    /** The writes to `table` in this transaction, made by the first. */
+    #changes(table) {
+        const handle = this.#handle(table);
+        this.#tables ??= new Map();
+        let changes = this.#tables.get(handle);
+        if (changes === undefined) {
+            this.#writes ??= { store: handle.store, staged: [] };
+            changes = new TableChanges(handle, this.#writes.staged);
+            this.#tables.set(handle, changes);
+        }
+        return changes;
+    }
+    /**
+     * Stages the re-run of the live queries over the tables this transaction wrote (decision "Live queries over an
+     * object's own tables"): read in the commit step after every table write staged so far (the callback's), published
+     * in the commit's batch. None when no written table has a live query.
+     */
+    #refreshQueries(tables) {
+        const refresh = refreshOf(tables.keys(), this.#context);
+        if (refresh === undefined)
+            return;
+        this.#writes.staged.push(refresh.write);
+        this.stage(refresh, () => refresh);
+    }
+    /** Counts `read` as pending until the operation's promise settles (rule 3). */
+    async #track(read) {
+        this.#pending++;
+        try {
+            return await read;
+        }
+        finally {
+            this.#pending--;
+        }
+    }
+    /** The entry's draft, begun on the current document (or a fresh `initial()`) by the first use. */
+    #begin(entry) {
+        if (entry.draft === undefined) {
+            const { slot, key } = entry;
+            const current = entry.retire ? undefined : slot.current(key);
+            const tracker = current ?? track(slot.initial(this.#context));
+            entry.draft = { tracker, change: tracker.beginChange() };
+        }
+        return entry.draft.change.state;
+    }
+}
+/** Throws, failing `slot`'s owner `broken`, when its definition cannot read the cold document `found` (R15). */
+function checkFound(found, persisted, slot) {
+    try {
+        checkReadable({ version: found.stored.version, fingerprint: found.fingerprint }, persisted.definition.current);
+    }
+    catch (error) {
+        const failure = asChordError(error, slot.owner.label);
+        slot.owner.fail(failure);
+        throw failure;
+    }
+}
+//# sourceMappingURL=transaction.js.map