@earendil-works/chord 1.4.0 → 1.5.1

package/dist/documents/slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.js","sourceRoot":"","sources":["../../src/documents/slot.ts"],"names":[],"mappings":"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","sourcesContent":["// Document slots (slice 6a §1.2): one per declared document name on its object, across the object's attempts. A slot\n// holds the documents' trackers, the version and definition its values are of, what is stored of persisted ones, and\n// the watches; each attempt's handles are thin views of it. This file: what every slot is, and the singleton's slot\n// (the keyed one is `keyed-slot.ts`).\n\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { type Prepared, type Tracker, track } from \"../delta/index.ts\";\nimport type { StagedWrite } from \"../store/step.ts\";\nimport { AddressSource } from \"./address-source.ts\";\nimport type { CommitPersistence, JsonObject, StateDefinition } from \"./definition.ts\";\nimport type { Documents } from \"./documents.ts\";\nimport type { SealToken } from \"./fence.ts\";\nimport { type DocumentChange, type Persistence, type Stored, type StoredChange, storedAfter } from \"./persistence.ts\";\n\n/** A document definition, whatever its value and keyedness. */\nexport type AnyDefinition = StateDefinition<JsonObject, boolean, boolean>;\n\n/**\n * What a transaction drafts and adopts: documents of one object by key (a singleton ignores the key). The slots of\n * `self.state`, and Chord's own (a job's run state documents).\n */\nexport interface DocumentSlot {\n\treadonly owner: Documents;\n\t/** The tracker of the document at `key`, `undefined` while absent. */\n\tcurrent(key: string): Tracker<JsonObject> | undefined;\n\t/** The value a draft of an absent document starts from. */\n\tinitial(context: Context): JsonObject;\n\t/** The persisted slot's store side; `undefined` for documents in memory only. */\n\treadonly persisted: PersistedSlot | undefined;\n\t/** Adopts a commit of the document at `key` (inside the batch), with what the commit stored of it. */\n\tadopt(\n\t\tkey: string,\n\t\ttracker: Tracker<JsonObject>,\n\t\tprepared: Prepared<JsonObject>,\n\t\tstored: StoredChange | undefined,\n\t): void;\n\t/** Retires the document at `key` (inside the batch). */\n\tretire(key: string): void;\n}\n\n/** What a transaction needs of a persisted slot (slice 6a §4, §10). */\nexport interface PersistedSlot {\n\treadonly persistence: Persistence;\n\treadonly definition: SlotDefinition;\n\t/** Whether the document at `key` may be stored without being in memory (a persisted keyed document not loaded). */\n\tcold(key: string): boolean;\n\t/** What is stored of the document at `key` as memory knows it; `undefined` when absent or cold. */\n\tstored(key: string): Stored | undefined;\n\t/**\n\t * Stages one commit's writes of the document at `key` into `writes` (`was`: what is stored of it, a cold one's as\n\t * the transaction found it); `persistence` is the transaction's (a deferred change of a run's state is held, D8).\n\t */\n\tstage(\n\t\tkey: string,\n\t\tchange: DocumentChange,\n\t\twas: Stored | undefined,\n\t\twrites: StagedWrite[],\n\t\tpersistence: CommitPersistence,\n\t): StoredChange;\n\t/**\n\t * Loads the document at `key` (its caller holds the line): installed when present and still absent from memory,\n\t * and, for a transaction's load (`token`), while the token is not sealed (a cut transaction released the line, so\n\t * a successor may have changed or retired the key meanwhile).\n\t */\n\tload(key: string, context: Context, token?: SealToken): Promise<void>;\n}\n\n/**\n * The definition a slot's values are of (the one that hydrated it last; the first declaration until then): the checks\n * of a new attempt's declaration and the old handles' version fence (R15).\n */\nexport class SlotDefinition {\n\t#current: AnyDefinition;\n\t#hydrated = false;\n\n\tconstructor(definition: AnyDefinition) {\n\t\tthis.#current = definition;\n\t}\n\n\t/** The definition the values are of. */\n\tget current(): AnyDefinition {\n\t\treturn this.#current;\n\t}\n\n\t/** The definition the values were hydrated with, `undefined` before the first hydration. */\n\tget hydrated(): AnyDefinition | undefined {\n\t\treturn this.#hydrated ? this.#current : undefined;\n\t}\n\n\t/**\n\t * Checks a declaration of this name by a new attempt: a flipped `keyed` or `persist`, a version older than the values (old code)\n\t * or the same version with another fingerprint (a schema changed without a bump) throw (the attempt fails broken).\n\t */\n\tcheck(definition: AnyDefinition): void {\n\t\tconst { name, version, keyed, persist, fingerprint } = this.#current;\n\t\tif (definition.keyed !== keyed) {\n\t\t\tthrow new Error(`${name}: declared ${definition.keyed ? \"keyed\" : \"singleton\"}, its documents are not`);\n\t\t}\n\t\tif (definition.persist !== persist) {\n\t\t\tthrow new Error(`${name}: declared ${definition.persist ? \"persisted\" : \"in memory\"}, its documents are not`);\n\t\t}\n\t\tif (definition.version < version) {\n\t\t\tthrow new Error(`${name}: version ${definition.version} is older than its documents' (${version})`);\n\t\t}\n\t\tif (definition.version === version && definition.fingerprint !== fingerprint) {\n\t\t\tthrow new Error(`${name}: the schema changed without a version bump (version ${version})`);\n\t\t}\n\t}\n\n\t/** Records the hydration with `definition`. */\n\thydrate(definition: AnyDefinition): void {\n\t\tthis.#current = definition;\n\t\tthis.#hydrated = true;\n\t}\n\n\t/**\n\t * Throws `released` for a handle of `version` once the values migrated past it (old code reads no new shape), and\n\t * `not_ready` for a handle of a newer version until its activation migrated them (new code reads no old shape: a\n\t * retry's factory).\n\t */\n\tassertVersion(version: number): void {\n\t\tconst current = this.#current;\n\t\tif (version === current.version) return;\n\t\tconst message = `${current.name}: a handle of version ${version}; the documents are at version ${current.version}`;\n\t\tif (version < current.version) throw new ChordError({ code: \"released\", reason: \"version\", message });\n\t\tthrow new ChordError({ code: \"not_ready\", message: `${message} until the activation migrates them` });\n\t}\n}\n\n/**\n * A singleton's slot: one tracker while written, `initial()` while absent; the source its handles and members watch.\n * Persisted, it loads once per object (again after a failed load) and stays in memory while the object lives.\n */\nexport class SingletonSlot extends AddressSource implements DocumentSlot, PersistedSlot {\n\treadonly owner: Documents;\n\treadonly definition: SlotDefinition;\n\treadonly persisted: PersistedSlot | undefined;\n\treadonly #persistence: Persistence | undefined;\n\t/** `initial()`, taken at hydration; `undefined` before the first. */\n\t#initial: JsonObject | undefined;\n\t#tracker: Tracker<JsonObject> | undefined;\n\t/** What is stored of it (persisted); `undefined` while absent. */\n\t#stored: Stored | undefined;\n\t/** In memory: always; persisted: once loaded. */\n\t#loaded: boolean;\n\n\tconstructor(owner: Documents, definition: AnyDefinition, persistence: Persistence | undefined) {\n\t\tsuper(owner.batch);\n\t\tthis.owner = owner;\n\t\tthis.definition = new SlotDefinition(definition);\n\t\tthis.#persistence = persistence;\n\t\tthis.persisted = persistence === undefined ? undefined : this;\n\t\tthis.#loaded = persistence === undefined;\n\t}\n\n\tget persistence(): Persistence {\n\t\t// Only reached through `persisted`, which a persisted slot alone has.\n\t\treturn this.#persistence!;\n\t}\n\n\tget value(): JsonObject {\n\t\tthis.owner.assertLive();\n\t\tif (this.#initial === undefined || !this.#loaded) {\n\t\t\tconst message = `${this.definition.current.name}: read before activation`;\n\t\t\tthrow new ChordError({ code: \"not_ready\", message });\n\t\t}\n\t\treturn this.#tracker?.value ?? this.#initial;\n\t}\n\n\t/**\n\t * Takes the attempt's declaration `definition` (`check` accepted it): the first takes `initial()`; a newer version\n\t * migrates the value in memory (a persisted one stores a base with its next change) and takes `initial()` again,\n\t * and a value that changed reaches watches as a root replacement; the same version keeps everything.\n\t */\n\thydrate(definition: AnyDefinition, context: Context): void {\n\t\tconst from = this.definition.hydrated;\n\t\tif (from !== undefined && from.version === definition.version) {\n\t\t\tthis.definition.hydrate(definition);\n\t\t\treturn;\n\t\t}\n\t\tconst before = from === undefined || !this.#loaded ? undefined : this.value;\n\t\tconst tracker =\n\t\t\tthis.#tracker === undefined || from === undefined\n\t\t\t\t? this.#tracker\n\t\t\t\t: track(definition.migrate(this.#tracker.value, from.version, context));\n\t\tthis.#initial = definition.initial(context);\n\t\tthis.#tracker = tracker;\n\t\tthis.definition.hydrate(definition);\n\t\tif (before !== undefined) this.batch.commit(() => this.replaced(), context);\n\t}\n\n\t/** Loads the persisted document unless it is loaded already (the caller holds the line). */\n\tasync load(_key: string, context: Context): Promise<void> {\n\t\tif (this.#loaded) return;\n\t\tconst document = await this.persistence.read(\"\", context);\n\t\t// Singletons load at activation, on the line: what the code cannot read fails the activation.\n\t\tconst loaded =\n\t\t\tdocument === undefined ? undefined : this.persistence.decode(document, this.definition.current, context);\n\t\tif (loaded !== undefined) {\n\t\t\tthis.#tracker = track(loaded.value);\n\t\t\tthis.#stored = loaded.stored;\n\t\t}\n\t\tthis.#loaded = true;\n\t}\n\n\t/** Loads the persisted document unless it is loaded already (activation, holding the line). */\n\tloadDeclared(context: Context): Promise<void> {\n\t\treturn this.load(\"\", context);\n\t}\n\n\t/** A singleton has one document: its key is always `\"\"`. */\n\tkey(_key: string): string {\n\t\treturn \"\";\n\t}\n\n\tcold(_key: string): boolean {\n\t\treturn false;\n\t}\n\n\tstored(_key: string): Stored | undefined {\n\t\treturn this.#stored;\n\t}\n\n\tstage(key: string, change: DocumentChange, was: Stored | undefined, writes: StagedWrite[]): StoredChange {\n\t\treturn this.persistence.stage(key, this.definition.current, was, change, writes);\n\t}\n\n\tcurrent(_key: string): Tracker<JsonObject> | undefined {\n\t\treturn this.#tracker;\n\t}\n\n\t/** The value a draft of the absent document starts from: the `initial()` taken at hydration. */\n\tinitial(_context: Context): JsonObject {\n\t\treturn this.#initial!;\n\t}\n\n\tadopt(\n\t\t_key: string,\n\t\ttracker: Tracker<JsonObject>,\n\t\tprepared: Prepared<JsonObject>,\n\t\tstored: StoredChange | undefined,\n\t): void {\n\t\t// Unchecked: a step admitted before the object ended adopts after its seal (slice 6a §1.3).\n\t\tconst before = this.#tracker?.value ?? this.#initial!;\n\t\ttracker.adopt(prepared);\n\t\tthis.#tracker = tracker;\n\t\tthis.#stored = stored === undefined ? undefined : storedAfter(stored);\n\t\tthis.written(before, prepared);\n\t}\n\n\t/** Retires the document: it reads `initial()` again, and the frame says it was retired. */\n\tretire(_key: string): void {\n\t\tthis.#tracker = undefined;\n\t\tthis.#stored = undefined;\n\t\tthis.retired(this.#initial!);\n\t}\n\n\t/** Its object ended or no attempt declares it any more: the document goes and its watches end. */\n\tdrop(): void {\n\t\tthis.#tracker = undefined;\n\t\tthis.#stored = undefined;\n\t\tthis.endWatches();\n\t}\n}\n"]}

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