@earendil-works/chord 1.3.0 → 1.5.0

package/dist/next/documents/slot.d.ts

@@ -0,0 +1,109 @@
+import type { Context } from "../../context/index.ts";
+import { type Prepared, type Tracker } from "../../delta/index.ts";
+import type { StagedWrite } from "../store/step.ts";
+import { AddressSource } from "./address-source.ts";
+import type { CommitPersistence, JsonObject, StateDefinition } from "./definition.ts";
+import type { Documents } from "./documents.ts";
+import type { SealToken } from "./fence.ts";
+import { type DocumentChange, type Persistence, type Stored, type StoredChange } from "./persistence.ts";
+/** A document definition, whatever its value and keyedness. */
+export type AnyDefinition = StateDefinition<JsonObject, boolean, boolean>;
+/**
+ * What a transaction drafts and adopts: documents of one object by key (a singleton ignores the key). The slots of
+ * `self.state`, and Chord's own (a job's run state documents).
+ */
+export interface DocumentSlot {
+    readonly owner: Documents;
+    /** The tracker of the document at `key`, `undefined` while absent. */
+    current(key: string): Tracker<JsonObject> | undefined;
+    /** The value a draft of an absent document starts from. */
+    initial(context: Context): JsonObject;
+    /** The persisted slot's store side; `undefined` for documents in memory only. */
+    readonly persisted: PersistedSlot | undefined;
+    /** Adopts a commit of the document at `key` (inside the batch), with what the commit stored of it. */
+    adopt(key: string, tracker: Tracker<JsonObject>, prepared: Prepared<JsonObject>, stored: StoredChange | undefined): void;
+    /** Retires the document at `key` (inside the batch). */
+    retire(key: string): void;
+}
+/** What a transaction needs of a persisted slot (slice 6a §4, §10). */
+export interface PersistedSlot {
+    readonly persistence: Persistence;
+    readonly definition: SlotDefinition;
+    /** Whether the document at `key` may be stored without being in memory (a persisted keyed document not loaded). */
+    cold(key: string): boolean;
+    /** What is stored of the document at `key` as memory knows it; `undefined` when absent or cold. */
+    stored(key: string): Stored | undefined;
+    /**
+     * Stages one commit's writes of the document at `key` into `writes` (`was`: what is stored of it, a cold one's as
+     * the transaction found it); `persistence` is the transaction's (a deferred change of a run's state is held, D8).
+     */
+    stage(key: string, change: DocumentChange, was: Stored | undefined, writes: StagedWrite[], persistence: CommitPersistence): StoredChange;
+    /**
+     * Loads the document at `key` (its caller holds the line): installed when present and still absent from memory,
+     * and, for a transaction's load (`token`), while the token is not sealed (a cut transaction released the line, so
+     * a successor may have changed or retired the key meanwhile).
+     */
+    load(key: string, context: Context, token?: SealToken): Promise<void>;
+}
+/**
+ * The definition a slot's values are of (the one that hydrated it last; the first declaration until then): the checks
+ * of a new attempt's declaration and the old handles' version fence (R15).
+ */
+export declare class SlotDefinition {
+    #private;
+    constructor(definition: AnyDefinition);
+    /** The definition the values are of. */
+    get current(): AnyDefinition;
+    /** The definition the values were hydrated with, `undefined` before the first hydration. */
+    get hydrated(): AnyDefinition | undefined;
+    /**
+     * Checks a declaration of this name by a new attempt: a flipped `keyed` or `persist`, a version older than the values (old code)
+     * or the same version with another fingerprint (a schema changed without a bump) throw (the attempt fails broken).
+     */
+    check(definition: AnyDefinition): void;
+    /** Records the hydration with `definition`. */
+    hydrate(definition: AnyDefinition): void;
+    /**
+     * Throws `released` for a handle of `version` once the values migrated past it (old code reads no new shape), and
+     * `not_ready` for a handle of a newer version until its activation migrated them (new code reads no old shape: a
+     * retry's factory).
+     */
+    assertVersion(version: number): void;
+}
+/**
+ * A singleton's slot: one tracker while written, `initial()` while absent; the source its handles and members watch.
+ * Persisted, it loads once per object (again after a failed load) and stays in memory while the object lives.
+ */
+export declare class SingletonSlot extends AddressSource implements DocumentSlot, PersistedSlot {
+    #private;
+    readonly owner: Documents;
+    readonly definition: SlotDefinition;
+    readonly persisted: PersistedSlot | undefined;
+    constructor(owner: Documents, definition: AnyDefinition, persistence: Persistence | undefined);
+    get persistence(): Persistence;
+    get value(): JsonObject;
+    /**
+     * Takes the attempt's declaration `definition` (`check` accepted it): the first takes `initial()`; a newer version
+     * migrates the value in memory (a persisted one stores a base with its next change) and takes `initial()` again,
+     * and a value that changed reaches watches as a root replacement; the same version keeps everything.
+     */
+    hydrate(definition: AnyDefinition, context: Context): void;
+    /** Loads the persisted document unless it is loaded already (the caller holds the line). */
+    load(_key: string, context: Context): Promise<void>;
+    /** Loads the persisted document unless it is loaded already (activation, holding the line). */
+    loadDeclared(context: Context): Promise<void>;
+    /** A singleton has one document: its key is always `""`. */
+    key(_key: string): string;
+    cold(_key: string): boolean;
+    stored(_key: string): Stored | undefined;
+    stage(key: string, change: DocumentChange, was: Stored | undefined, writes: StagedWrite[]): StoredChange;
+    current(_key: string): Tracker<JsonObject> | undefined;
+    /** The value a draft of the absent document starts from: the `initial()` taken at hydration. */
+    initial(_context: Context): JsonObject;
+    adopt(_key: string, tracker: Tracker<JsonObject>, prepared: Prepared<JsonObject>, stored: StoredChange | undefined): void;
+    /** Retires the document: it reads `initial()` again, and the frame says it was retired. */
+    retire(_key: string): void;
+    /** Its object ended or no attempt declares it any more: the document goes and its watches end. */
+    drop(): void;
+}
+//# sourceMappingURL=slot.d.ts.map

package/dist/next/documents/slot.d.ts.map

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

package/dist/next/documents/slot.js

@@ -0,0 +1,181 @@
+// Document slots (slice 6a §1.2): one per declared document name on its object, across the object's attempts. A slot
+// holds the documents' trackers, the version and definition its values are of, what is stored of persisted ones, and
+// the watches; each attempt's handles are thin views of it. This file: what every slot is, and the singleton's slot
+// (the keyed one is `keyed-slot.ts`).
+import { track } from "../../delta/index.js";
+import { ChordError } from "../data/index.js";
+import { AddressSource } from "./address-source.js";
+import { storedAfter } from "./persistence.js";
+/**
+ * The definition a slot's values are of (the one that hydrated it last; the first declaration until then): the checks
+ * of a new attempt's declaration and the old handles' version fence (R15).
+ */
+export class SlotDefinition {
+    #current;
+    #hydrated = false;
+    constructor(definition) {
+        this.#current = definition;
+    }
+    /** The definition the values are of. */
+    get current() {
+        return this.#current;
+    }
+    /** The definition the values were hydrated with, `undefined` before the first hydration. */
+    get hydrated() {
+        return this.#hydrated ? this.#current : undefined;
+    }
+    /**
+     * Checks a declaration of this name by a new attempt: a flipped `keyed` or `persist`, a version older than the values (old code)
+     * or the same version with another fingerprint (a schema changed without a bump) throw (the attempt fails broken).
+     */
+    check(definition) {
+        const { name, version, keyed, persist, fingerprint } = this.#current;
+        if (definition.keyed !== keyed) {
+            throw new Error(`${name}: declared ${definition.keyed ? "keyed" : "singleton"}, its documents are not`);
+        }
+        if (definition.persist !== persist) {
+            throw new Error(`${name}: declared ${definition.persist ? "persisted" : "in memory"}, its documents are not`);
+        }
+        if (definition.version < version) {
+            throw new Error(`${name}: version ${definition.version} is older than its documents' (${version})`);
+        }
+        if (definition.version === version && definition.fingerprint !== fingerprint) {
+            throw new Error(`${name}: the schema changed without a version bump (version ${version})`);
+        }
+    }
+    /** Records the hydration with `definition`. */
+    hydrate(definition) {
+        this.#current = definition;
+        this.#hydrated = true;
+    }
+    /**
+     * Throws `released` for a handle of `version` once the values migrated past it (old code reads no new shape), and
+     * `not_ready` for a handle of a newer version until its activation migrated them (new code reads no old shape: a
+     * retry's factory).
+     */
+    assertVersion(version) {
+        const current = this.#current;
+        if (version === current.version)
+            return;
+        const message = `${current.name}: a handle of version ${version}; the documents are at version ${current.version}`;
+        if (version < current.version)
+            throw new ChordError({ code: "released", reason: "version", message });
+        throw new ChordError({ code: "not_ready", message: `${message} until the activation migrates them` });
+    }
+}
+/**
+ * A singleton's slot: one tracker while written, `initial()` while absent; the source its handles and members watch.
+ * Persisted, it loads once per object (again after a failed load) and stays in memory while the object lives.
+ */
+export class SingletonSlot extends AddressSource {
+    owner;
+    definition;
+    persisted;
+    #persistence;
+    /** `initial()`, taken at hydration; `undefined` before the first. */
+    #initial;
+    #tracker;
+    /** What is stored of it (persisted); `undefined` while absent. */
+    #stored;
+    /** In memory: always; persisted: once loaded. */
+    #loaded;
+    constructor(owner, definition, persistence) {
+        super(owner.batch);
+        this.owner = owner;
+        this.definition = new SlotDefinition(definition);
+        this.#persistence = persistence;
+        this.persisted = persistence === undefined ? undefined : this;
+        this.#loaded = persistence === undefined;
+    }
+    get persistence() {
+        // Only reached through `persisted`, which a persisted slot alone has.
+        return this.#persistence;
+    }
+    get value() {
+        this.owner.assertLive();
+        if (this.#initial === undefined || !this.#loaded) {
+            const message = `${this.definition.current.name}: read before activation`;
+            throw new ChordError({ code: "not_ready", message });
+        }
+        return this.#tracker?.value ?? this.#initial;
+    }
+    /**
+     * Takes the attempt's declaration `definition` (`check` accepted it): the first takes `initial()`; a newer version
+     * migrates the value in memory (a persisted one stores a base with its next change) and takes `initial()` again,
+     * and a value that changed reaches watches as a root replacement; the same version keeps everything.
+     */
+    hydrate(definition, context) {
+        const from = this.definition.hydrated;
+        if (from !== undefined && from.version === definition.version) {
+            this.definition.hydrate(definition);
+            return;
+        }
+        const before = from === undefined || !this.#loaded ? undefined : this.value;
+        const tracker = this.#tracker === undefined || from === undefined
+            ? this.#tracker
+            : track(definition.migrate(this.#tracker.value, from.version, context));
+        this.#initial = definition.initial(context);
+        this.#tracker = tracker;
+        this.definition.hydrate(definition);
+        if (before !== undefined)
+            this.batch.commit(() => this.replaced(), context);
+    }
+    /** Loads the persisted document unless it is loaded already (the caller holds the line). */
+    async load(_key, context) {
+        if (this.#loaded)
+            return;
+        const document = await this.persistence.read("", context);
+        // Singletons load at activation, on the line: what the code cannot read fails the activation.
+        const loaded = document === undefined ? undefined : this.persistence.decode(document, this.definition.current, context);
+        if (loaded !== undefined) {
+            this.#tracker = track(loaded.value);
+            this.#stored = loaded.stored;
+        }
+        this.#loaded = true;
+    }
+    /** Loads the persisted document unless it is loaded already (activation, holding the line). */
+    loadDeclared(context) {
+        return this.load("", context);
+    }
+    /** A singleton has one document: its key is always `""`. */
+    key(_key) {
+        return "";
+    }
+    cold(_key) {
+        return false;
+    }
+    stored(_key) {
+        return this.#stored;
+    }
+    stage(key, change, was, writes) {
+        return this.persistence.stage(key, this.definition.current, was, change, writes);
+    }
+    current(_key) {
+        return this.#tracker;
+    }
+    /** The value a draft of the absent document starts from: the `initial()` taken at hydration. */
+    initial(_context) {
+        return this.#initial;
+    }
+    adopt(_key, tracker, prepared, stored) {
+        // Unchecked: a step admitted before the object ended adopts after its seal (slice 6a §1.3).
+        const before = this.#tracker?.value ?? this.#initial;
+        tracker.adopt(prepared);
+        this.#tracker = tracker;
+        this.#stored = stored === undefined ? undefined : storedAfter(stored);
+        this.written(before, prepared);
+    }
+    /** Retires the document: it reads `initial()` again, and the frame says it was retired. */
+    retire(_key) {
+        this.#tracker = undefined;
+        this.#stored = undefined;
+        this.retired(this.#initial);
+    }
+    /** Its object ended or no attempt declares it any more: the document goes and its watches end. */
+    drop() {
+        this.#tracker = undefined;
+        this.#stored = undefined;
+        this.endWatches();
+    }
+}
+//# sourceMappingURL=slot.js.map

package/dist/next/documents/slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.js","sourceRoot":"","sources":["../../../src/next/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 { type Prepared, type Tracker, track } from \"../../delta/index.ts\";\nimport { ChordError } from \"../data/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/next/documents/transaction.d.ts

@@ -0,0 +1,133 @@
+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[];
+    /** 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/next/documents/transaction.d.ts.map

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