@earendil-works/chord 1.5.0 → 1.5.1

package/dist/documents/documents.js

@@ -0,0 +1,248 @@
+// An object's documents (§9, P2, slice 6a §1.2, §10): its slots across attempts, its line (its transactions and line
+// jobs run one at a time), the seal fence over the transaction holding the line, the factory's pins between attempts,
+// the activation's loads and the residency of keyed documents; a commit's telemetry (its event, its duration, slice 9).
+import { ChordError } from "../data/index.js";
+import { chordMetrics, untraced } from "../telemetry.js";
+import { SealToken } from "./fence.js";
+import { Keyed, Singleton } from "./handles.js";
+import { KeyedSlot } from "./keyed-slot.js";
+import { Line } from "./line.js";
+import { Persistence } from "./persistence.js";
+import { Residency } from "./residency.js";
+import { SingletonSlot } from "./slot.js";
+import { Transaction } from "./transaction.js";
+/**
+ * The documents of one object, from its first activation to its end: one slot per declared name, kept across
+ * attempts, and the line. Each attempt declares its handles under its own seal token; the object's own transactions
+ * (job outcomes) run under `own`, sealed only by the object's end.
+ */
+export class Documents {
+    /** The owner's name in errors. */
+    label;
+    batch;
+    /** The object's context. */
+    context;
+    line = new Line();
+    /**
+     * The idle persisted keyed documents and their eviction. A sweep's only rejection is `onLine`'s `released` once
+     * the object ended (a sweep itself drops trackers in memory and does not throw): nothing to report.
+     */
+    residency = new Residency((sweep) => void this.onLine(async () => sweep()).catch(() => { }));
+    #owner;
+    /** The token of the object's own transactions: sealed with the object (`seal`). */
+    own = new SealToken();
+    #slots = new Map();
+    /** The transaction holding the line, until it settles or its token is sealed. */
+    #holder;
+    /** `sealed`: the object is ending; its documents stay readable, its transactions throw `released`. */
+    #state = "open";
+    /** The pins the last factory that returned declared (`at(key)`): held until the next one returns (rule 6). */
+    #pins = [];
+    constructor(owner) {
+        this.label = owner.label;
+        this.batch = owner.batch;
+        this.context = owner.context;
+        this.#owner = owner;
+    }
+    /**
+     * A handle to `definition`'s slot for an attempt sealed by `token`, whose `at(key)` pins `declarer` takes: the slot
+     * made by the first declaration of its name, checked against the values for later ones (`SlotDefinition.check`).
+     * "Declared twice" is the attempt's check.
+     */
+    declare(definition, token, declarer) {
+        const slot = this.#slots.get(definition.name);
+        if (slot !== undefined)
+            slot.definition.check(definition);
+        const persistence = slot === undefined && definition.persist ? this.#persistence(definition.name) : undefined;
+        // The definition's `keyed` decides the slot's class and the handle's; its documents are the definition's `T`.
+        if (definition.keyed) {
+            const keyed = slot ?? this.#add(new KeyedSlot(this, definition, persistence));
+            return new Keyed(keyed, token, definition.version, declarer);
+        }
+        const singleton = slot ?? this.#add(new SingletonSlot(this, definition, persistence));
+        return new Singleton(singleton, token, definition.version);
+    }
+    /**
+     * Checks a declaration of `definition` as `declare` would, changing nothing (a reload's staging: a recording factory
+     * declares against the documents the object has).
+     */
+    check(definition) {
+        this.#slots.get(definition.name)?.definition.check(definition);
+    }
+    /**
+     * Takes an attempt's declarations once its factory returned: its `at(key)` pins replace the previous factory's, the
+     * slots it no longer declares are dropped (their watches end; persisted ones load again when declared again), every
+     * declared one hydrated (`initial()`, migrations; a throw fails the activation).
+     */
+    hydrate(declared, pins, context) {
+        const previous = this.#pins;
+        this.#pins = pins;
+        for (const release of previous)
+            release();
+        // A dropped persisted slot goes whole, its loaded documents too: observably the same as keeping them, since
+        // every committed write is in the store and a later declaration reloads from there.
+        for (const [name, slot] of this.#slots) {
+            if (declared.has(name))
+                continue;
+            this.#slots.delete(name);
+            slot.drop();
+        }
+        for (const [name, definition] of declared)
+            this.#slots.get(name).hydrate(definition, context);
+    }
+    /**
+     * Loads, in one line job, every persisted singleton not loaded yet and every pinned key not loaded since it was
+     * pinned (an attempt's activation, before it goes live, rule 6); `undefined` when nothing is persisted. A failure
+     * fails the activation.
+     */
+    load(context) {
+        const persisted = [...this.#slots.values()].filter((slot) => slot.persisted !== undefined);
+        // In memory only: nothing to wait for (an activation without persisted documents takes no extra turn).
+        if (persisted.length === 0)
+            return undefined;
+        return this.onLine(async () => {
+            for (const slot of persisted)
+                await slot.loadDeclared(context);
+        });
+    }
+    /**
+     * Runs `job` on the line (a cold load, a page of keys, an eviction sweep); refused `released` once the object is
+     * ending or `token` (the handle's that asks, when the job is one handle's) is sealed, a job queued before either
+     * included (anything taking the line after the seal is refused, rule 4).
+     */
+    async onLine(job, token) {
+        if (this.#state !== "open" || token?.sealed)
+            throw this.released();
+        const release = await this.line.acquire();
+        try {
+            if (this.#state !== "open" || token?.sealed)
+                throw this.released();
+            return await job();
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Runs `fn` as one transaction on the line under `token` and commits what it drafted (§9): a throw, an abort of
+     * `context`, the token's seal or the object's end discards everything; one that did not commit while `context` was
+     * aborted is also reported (`transaction_cancelled`): an empty `catch` cannot hide a change that never happened.
+     * `persistence` defers storing a run state's change (D8).
+     */
+    async tx(fn, token, context, persistence) {
+        this.batch.assertOutside("tx");
+        this.assertAdmitted(token);
+        const release = await this.line.acquire();
+        const tx = new Transaction(this, token, release, context, persistence);
+        try {
+            this.assertAdmitted(token);
+            this.#holder = tx;
+            const result = await fn(tx);
+            // Timed only when something records: the commit's duration metric, its event on the enclosing span.
+            const timed = !untraced(this.#owner.telemetry) || !untraced(context.telemetry);
+            const started = timed ? performance.now() : 0;
+            // In-memory-only commits are synchronous (W12): no await unless the store's step is taken.
+            const step = tx.commit();
+            if (step !== undefined)
+                await step;
+            if (timed)
+                this.#recordCommit(tx, performance.now() - started, context);
+            return result;
+        }
+        catch (error) {
+            tx.discard();
+            // Only a transaction that did not commit reads this; Chord's own run under contexts that never abort.
+            const signal = context.abortSignal;
+            if (signal?.aborted)
+                this.#owner.report({ kind: "transaction_cancelled", object: this.label, error: signal.reason });
+            throw error;
+        }
+        finally {
+            if (this.#holder === tx)
+                this.#holder = undefined;
+            release();
+            tx.settle();
+        }
+    }
+    /**
+     * A commit of `tx` that took `duration` ms (from its start to its adoption): its event on `context`'s span (the
+     * method, routine or job it ran in) and the host's commit duration metric; a commit that changed nothing records
+     * nothing.
+     */
+    #recordCommit(tx, duration, context) {
+        const { documents, ops, writes, rows } = tx.committed();
+        if (documents === 0 && writes === 0)
+            return;
+        if (!untraced(context.telemetry))
+            context.telemetry.addEvent("chord.commit", { documents, ops, rows, duration });
+        chordMetrics(this.#owner.telemetry.metrics).histogram("chord.commit.duration").record(duration);
+    }
+    /**
+     * Seals `token` (the seal fence): its transactions are refused from now on, and the one holding the line is
+     * discarded and the line released.
+     */
+    fence(token) {
+        token.seal();
+        if (this.#holder?.token === token)
+            this.#cut();
+    }
+    /** Throws `released` once the object ended. */
+    assertLive() {
+        if (this.#state === "ended")
+            throw this.released();
+    }
+    /** Throws `released` once `token` is sealed or the object is ending: no new work takes the line. */
+    assertAdmitted(token) {
+        if (token.sealed || this.#state !== "open")
+            throw this.released();
+    }
+    /** The live object fails `broken` with `error` (a document the code cannot read); ignored when it is not live. */
+    fail(error) {
+        this.#owner.fail(error);
+    }
+    /** The object is ending: every transaction is refused, the one holding the line discarded; documents stay readable. */
+    seal() {
+        if (this.#state !== "open")
+            return;
+        this.#state = "sealed";
+        this.own.seal();
+        this.#cut();
+    }
+    /**
+     * Resolves once the line is free. After `seal` only an admitted step can hold it (every other holder was cut):
+     * the object's teardown waits here, so the step adopts into documents that still exist (slice 6a §1.3).
+     */
+    async settled() {
+        const release = await this.line.acquire();
+        release();
+    }
+    /** Drops every document and pin; watches end `ended`, and every later use throws `released`. */
+    end() {
+        this.#state = "ended";
+        this.residency.end();
+        for (const slot of this.#slots.values())
+            slot.drop();
+        this.#slots.clear();
+        this.#pins = [];
+    }
+    /** The `released` error of this object's documents. */
+    released() {
+        return new ChordError({ code: "released", reason: "ended", message: `${this.label}: ended` });
+    }
+    /** Discards the transaction holding the line and releases the line. */
+    #cut() {
+        const holder = this.#holder;
+        this.#holder = undefined;
+        holder?.cut();
+    }
+    #add(slot) {
+        this.#slots.set(slot.definition.current.name, slot);
+        return slot;
+    }
+    /** The store side of persisted documents named `name`; the attempt checked the store first (P3). */
+    #persistence(name) {
+        const { store, owner } = this.#owner.store;
+        return new Persistence(store, owner, "chord", name);
+    }
+}
+//# sourceMappingURL=documents.js.map

package/dist/documents/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../src/documents/documents.ts"],"names":[],"mappings":"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","sourcesContent":["// An object's documents (§9, P2, slice 6a §1.2, §10): its slots across attempts, its line (its transactions and line\n// jobs run one at a time), the seal fence over the transaction holding the line, the factory's pins between attempts,\n// the activation's loads and the residency of keyed documents; a commit's telemetry (its event, its duration, slice 9).\n\nimport type { TelemetryContext } from \"@earendil-works/pi-telemetry\";\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport type { Batch } from \"../state/internal.ts\";\nimport type { ChordStore } from \"../store/store.ts\";\nimport { chordMetrics, untraced } from \"../telemetry.ts\";\nimport type { CommitPersistence, JsonObject, StateDefinition } from \"./definition.ts\";\nimport { SealToken } from \"./fence.ts\";\nimport { type HandleOf, type KeyDeclarer, Keyed, Singleton } from \"./handles.ts\";\nimport { KeyedSlot } from \"./keyed-slot.ts\";\nimport { Line } from \"./line.ts\";\nimport { Persistence } from \"./persistence.ts\";\nimport { Residency } from \"./residency.ts\";\nimport { type AnyDefinition, SingletonSlot } from \"./slot.ts\";\nimport { Transaction } from \"./transaction.ts\";\n\n/**\n * A transaction (a document change or retirement, `self.tx`, a job start) that did not commit because the context it\n * was started with ended first: a root whose `fn` settled, a handler or routine whose object ended, a caller that\n * cancelled. `error` is that context's abort reason, naming the scope that ended (decision \"Mistakes that wait are\n * reported at once\" (e)).\n */\nexport type TransactionCancelled = {\n\treadonly kind: \"transaction_cancelled\";\n\treadonly object: string;\n\treadonly error: unknown;\n};\n\n/**\n * Who owns an object's documents: the object's name, batch and context, its store address, its live failure, and where\n * a cancelled transaction is reported.\n */\nexport type DocumentsOwner = {\n\t/** The owner's name in errors. */\n\treadonly label: string;\n\treadonly batch: Batch;\n\t/** The object's context: shared cold loads run under it (rule 11). */\n\treadonly context: Context;\n\t/** The host's store and the object's owner name in it (its type, R2), when it has one. */\n\treadonly store: { readonly store: ChordStore; readonly owner: string } | undefined;\n\t/** A document the code cannot read fails the live object `broken` (slice 6a §1.4); ignored when it is not live. */\n\tfail(error: ChordError): void;\n\t/** Reports a transaction its context's end cancelled (the host's `onError`). */\n\treport(error: TransactionCancelled): void;\n\t/** The host's telemetry adapter: commit durations go to its metrics. */\n\treadonly telemetry: TelemetryContext;\n};\n\n/**\n * The documents of one object, from its first activation to its end: one slot per declared name, kept across\n * attempts, and the line. Each attempt declares its handles under its own seal token; the object's own transactions\n * (job outcomes) run under `own`, sealed only by the object's end.\n */\nexport class Documents {\n\t/** The owner's name in errors. */\n\treadonly label: string;\n\treadonly batch: Batch;\n\t/** The object's context. */\n\treadonly context: Context;\n\treadonly line = new Line();\n\t/**\n\t * The idle persisted keyed documents and their eviction. A sweep's only rejection is `onLine`'s `released` once\n\t * the object ended (a sweep itself drops trackers in memory and does not throw): nothing to report.\n\t */\n\treadonly residency = new Residency((sweep) => void this.onLine(async () => sweep()).catch(() => {}));\n\treadonly #owner: DocumentsOwner;\n\t/** The token of the object's own transactions: sealed with the object (`seal`). */\n\treadonly own = new SealToken();\n\treadonly #slots = new Map<string, SingletonSlot | KeyedSlot>();\n\t/** The transaction holding the line, until it settles or its token is sealed. */\n\t#holder: Transaction | undefined;\n\t/** `sealed`: the object is ending; its documents stay readable, its transactions throw `released`. */\n\t#state: \"open\" | \"sealed\" | \"ended\" = \"open\";\n\t/** The pins the last factory that returned declared (`at(key)`): held until the next one returns (rule 6). */\n\t#pins: readonly (() => void)[] = [];\n\n\tconstructor(owner: DocumentsOwner) {\n\t\tthis.label = owner.label;\n\t\tthis.batch = owner.batch;\n\t\tthis.context = owner.context;\n\t\tthis.#owner = owner;\n\t}\n\n\t/**\n\t * A handle to `definition`'s slot for an attempt sealed by `token`, whose `at(key)` pins `declarer` takes: the slot\n\t * made by the first declaration of its name, checked against the values for later ones (`SlotDefinition.check`).\n\t * \"Declared twice\" is the attempt's check.\n\t */\n\tdeclare<D extends StateDefinition<JsonObject, boolean, boolean>>(\n\t\tdefinition: D,\n\t\ttoken: SealToken,\n\t\tdeclarer: KeyDeclarer,\n\t): HandleOf<D> {\n\t\tconst slot = this.#slots.get(definition.name);\n\t\tif (slot !== undefined) slot.definition.check(definition);\n\t\tconst persistence = slot === undefined && definition.persist ? this.#persistence(definition.name) : undefined;\n\t\t// The definition's `keyed` decides the slot's class and the handle's; its documents are the definition's `T`.\n\t\tif (definition.keyed) {\n\t\t\tconst keyed = slot ?? this.#add(new KeyedSlot(this, definition, persistence));\n\t\t\treturn new Keyed(keyed as KeyedSlot, token, definition.version, declarer) as unknown as HandleOf<D>;\n\t\t}\n\t\tconst singleton = slot ?? this.#add(new SingletonSlot(this, definition, persistence));\n\t\treturn new Singleton(singleton as SingletonSlot, token, definition.version) as unknown as HandleOf<D>;\n\t}\n\n\t/**\n\t * Checks a declaration of `definition` as `declare` would, changing nothing (a reload's staging: a recording factory\n\t * declares against the documents the object has).\n\t */\n\tcheck(definition: AnyDefinition): void {\n\t\tthis.#slots.get(definition.name)?.definition.check(definition);\n\t}\n\n\t/**\n\t * Takes an attempt's declarations once its factory returned: its `at(key)` pins replace the previous factory's, the\n\t * slots it no longer declares are dropped (their watches end; persisted ones load again when declared again), every\n\t * declared one hydrated (`initial()`, migrations; a throw fails the activation).\n\t */\n\thydrate(declared: ReadonlyMap<string, AnyDefinition>, pins: readonly (() => void)[], context: Context): void {\n\t\tconst previous = this.#pins;\n\t\tthis.#pins = pins;\n\t\tfor (const release of previous) release();\n\t\t// A dropped persisted slot goes whole, its loaded documents too: observably the same as keeping them, since\n\t\t// every committed write is in the store and a later declaration reloads from there.\n\t\tfor (const [name, slot] of this.#slots) {\n\t\t\tif (declared.has(name)) continue;\n\t\t\tthis.#slots.delete(name);\n\t\t\tslot.drop();\n\t\t}\n\t\tfor (const [name, definition] of declared) this.#slots.get(name)!.hydrate(definition, context);\n\t}\n\n\t/**\n\t * Loads, in one line job, every persisted singleton not loaded yet and every pinned key not loaded since it was\n\t * pinned (an attempt's activation, before it goes live, rule 6); `undefined` when nothing is persisted. A failure\n\t * fails the activation.\n\t */\n\tload(context: Context): Promise<void> | undefined {\n\t\tconst persisted = [...this.#slots.values()].filter((slot) => slot.persisted !== undefined);\n\t\t// In memory only: nothing to wait for (an activation without persisted documents takes no extra turn).\n\t\tif (persisted.length === 0) return undefined;\n\t\treturn this.onLine(async () => {\n\t\t\tfor (const slot of persisted) await slot.loadDeclared(context);\n\t\t});\n\t}\n\n\t/**\n\t * Runs `job` on the line (a cold load, a page of keys, an eviction sweep); refused `released` once the object is\n\t * ending or `token` (the handle's that asks, when the job is one handle's) is sealed, a job queued before either\n\t * included (anything taking the line after the seal is refused, rule 4).\n\t */\n\tasync onLine<T>(job: () => Promise<T>, token?: SealToken): Promise<T> {\n\t\tif (this.#state !== \"open\" || token?.sealed) throw this.released();\n\t\tconst release = await this.line.acquire();\n\t\ttry {\n\t\t\tif (this.#state !== \"open\" || token?.sealed) throw this.released();\n\t\t\treturn await job();\n\t\t} finally {\n\t\t\trelease();\n\t\t}\n\t}\n\n\t/**\n\t * Runs `fn` as one transaction on the line under `token` and commits what it drafted (§9): a throw, an abort of\n\t * `context`, the token's seal or the object's end discards everything; one that did not commit while `context` was\n\t * aborted is also reported (`transaction_cancelled`): an empty `catch` cannot hide a change that never happened.\n\t * `persistence` defers storing a run state's change (D8).\n\t */\n\tasync tx<R>(\n\t\tfn: (tx: Transaction) => R | Promise<R>,\n\t\ttoken: SealToken,\n\t\tcontext: Context,\n\t\tpersistence?: CommitPersistence,\n\t): Promise<R> {\n\t\tthis.batch.assertOutside(\"tx\");\n\t\tthis.assertAdmitted(token);\n\t\tconst release = await this.line.acquire();\n\t\tconst tx = new Transaction(this, token, release, context, persistence);\n\t\ttry {\n\t\t\tthis.assertAdmitted(token);\n\t\t\tthis.#holder = tx;\n\t\t\tconst result = await fn(tx);\n\t\t\t// Timed only when something records: the commit's duration metric, its event on the enclosing span.\n\t\t\tconst timed = !untraced(this.#owner.telemetry) || !untraced(context.telemetry);\n\t\t\tconst started = timed ? performance.now() : 0;\n\t\t\t// In-memory-only commits are synchronous (W12): no await unless the store's step is taken.\n\t\t\tconst step = tx.commit();\n\t\t\tif (step !== undefined) await step;\n\t\t\tif (timed) this.#recordCommit(tx, performance.now() - started, context);\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\ttx.discard();\n\t\t\t// Only a transaction that did not commit reads this; Chord's own run under contexts that never abort.\n\t\t\tconst signal = context.abortSignal;\n\t\t\tif (signal?.aborted)\n\t\t\t\tthis.#owner.report({ kind: \"transaction_cancelled\", object: this.label, error: signal.reason });\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tif (this.#holder === tx) this.#holder = undefined;\n\t\t\trelease();\n\t\t\ttx.settle();\n\t\t}\n\t}\n\n\t/**\n\t * A commit of `tx` that took `duration` ms (from its start to its adoption): its event on `context`'s span (the\n\t * method, routine or job it ran in) and the host's commit duration metric; a commit that changed nothing records\n\t * nothing.\n\t */\n\t#recordCommit(tx: Transaction, duration: number, context: Context): void {\n\t\tconst { documents, ops, writes, rows } = tx.committed();\n\t\tif (documents === 0 && writes === 0) return;\n\t\tif (!untraced(context.telemetry)) context.telemetry.addEvent(\"chord.commit\", { documents, ops, rows, duration });\n\t\tchordMetrics(this.#owner.telemetry.metrics).histogram(\"chord.commit.duration\").record(duration);\n\t}\n\n\t/**\n\t * Seals `token` (the seal fence): its transactions are refused from now on, and the one holding the line is\n\t * discarded and the line released.\n\t */\n\tfence(token: SealToken): void {\n\t\ttoken.seal();\n\t\tif (this.#holder?.token === token) this.#cut();\n\t}\n\n\t/** Throws `released` once the object ended. */\n\tassertLive(): void {\n\t\tif (this.#state === \"ended\") throw this.released();\n\t}\n\n\t/** Throws `released` once `token` is sealed or the object is ending: no new work takes the line. */\n\tassertAdmitted(token: SealToken): void {\n\t\tif (token.sealed || this.#state !== \"open\") throw this.released();\n\t}\n\n\t/** The live object fails `broken` with `error` (a document the code cannot read); ignored when it is not live. */\n\tfail(error: ChordError): void {\n\t\tthis.#owner.fail(error);\n\t}\n\n\t/** The object is ending: every transaction is refused, the one holding the line discarded; documents stay readable. */\n\tseal(): void {\n\t\tif (this.#state !== \"open\") return;\n\t\tthis.#state = \"sealed\";\n\t\tthis.own.seal();\n\t\tthis.#cut();\n\t}\n\n\t/**\n\t * Resolves once the line is free. After `seal` only an admitted step can hold it (every other holder was cut):\n\t * the object's teardown waits here, so the step adopts into documents that still exist (slice 6a §1.3).\n\t */\n\tasync settled(): Promise<void> {\n\t\tconst release = await this.line.acquire();\n\t\trelease();\n\t}\n\n\t/** Drops every document and pin; watches end `ended`, and every later use throws `released`. */\n\tend(): void {\n\t\tthis.#state = \"ended\";\n\t\tthis.residency.end();\n\t\tfor (const slot of this.#slots.values()) slot.drop();\n\t\tthis.#slots.clear();\n\t\tthis.#pins = [];\n\t}\n\n\t/** The `released` error of this object's documents. */\n\treleased(): ChordError {\n\t\treturn new ChordError({ code: \"released\", reason: \"ended\", message: `${this.label}: ended` });\n\t}\n\n\t/** Discards the transaction holding the line and releases the line. */\n\t#cut(): void {\n\t\tconst holder = this.#holder;\n\t\tthis.#holder = undefined;\n\t\tholder?.cut();\n\t}\n\n\t#add<S extends SingletonSlot | KeyedSlot>(slot: S): S {\n\t\tthis.#slots.set(slot.definition.current.name, slot);\n\t\treturn slot;\n\t}\n\n\t/** The store side of persisted documents named `name`; the attempt checked the store first (P3). */\n\t#persistence(name: string): Persistence {\n\t\tconst { store, owner } = this.#owner.store!;\n\t\treturn new Persistence(store, owner, \"chord\", name);\n\t}\n}\n"]}

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

@@ -0,0 +1 @@
+{"version":3,"file":"fence.d.ts","sourceRoot":"","sources":["../../src/documents/fence.ts"],"names":[],"mappings":"AAGA,mDAAmD;AACnD,qBAAa,SAAS;;IAGrB,gDAAgD;IAChD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,sFAAsF;IACtF,IAAI,IAAI,IAAI,CAEX;CACD"}

package/dist/documents/fence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fence.js","sourceRoot":"","sources":["../../src/documents/fence.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,6GAA6G;AAE7G,mDAAmD;AACnD,MAAM,OAAO,SAAS;IACrB,OAAO,GAAG,KAAK,CAAC;IAEhB,gDAAgD;IAChD,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED,sFAAsF;IACtF,IAAI;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACrB,CAAC;CACD","sourcesContent":["// The seal fence (slice 6a §1.3): the token an attempt, a job run's invocation or the object itself hands its\n// transactions. Once sealed, new transactions under it are refused `released` and the open one is discarded.\n\n/** One seal token; sealed once, never unsealed. */\nexport class SealToken {\n\t#sealed = false;\n\n\t/** Whether work under this token is refused. */\n\tget sealed(): boolean {\n\t\treturn this.#sealed;\n\t}\n\n\t/** Seals the token; `Documents.fence` also discards the transaction it holds open. */\n\tseal(): void {\n\t\tthis.#sealed = true;\n\t}\n}\n"]}

package/dist/documents/handles.d.ts

@@ -0,0 +1,76 @@
+import type { Context } from "../context/index.ts";
+import type { Draft } from "../delta/index.ts";
+import type { Watch, Watchable, WatchHandle } from "../watch.ts";
+import type { JsonObject, StateDefinition } from "./definition.ts";
+import type { SealToken } from "./fence.ts";
+import type { KeyedSlot, KeySource } from "./keyed-slot.ts";
+import type { SingletonSlot } from "./slot.ts";
+/** A singleton document: a watchable that always has a value (`initial()` until written, and after a retire). */
+export interface SingletonHandle<T extends JsonObject> extends Watchable<T> {
+    /** One transaction that drafts this document and passes the draft to `fn`. */
+    change<R>(fn: (draft: Draft<T>) => R, context: Context): Promise<R>;
+    /** One transaction that retires this document: back to `initial()`. */
+    retire(context: Context): Promise<void>;
+}
+/**
+ * Keyed documents: many per object, by string key. Not a watchable itself: each key is, through `watch(key)` and
+ * `at(key)`; a live collection is a singleton holding it.
+ */
+export interface KeyedHandle<T extends JsonObject> {
+    /** The document's value, `undefined` when absent (persisted and not in memory: loaded on the object's line). */
+    get(key: string, context: Context): Promise<T | undefined>;
+    /** The keys of the present documents, in code point order. */
+    keys(context: Context): AsyncIterable<string>;
+    /**
+     * A watch of the document at `key`, `undefined` when absent. It follows the address: a retirement is one frame with
+     * `retired: true` and `initial()`, a later creation a root replacement; it ends with the object.
+     */
+    watch(key: string, context: Context): Promise<WatchHandle<T> | undefined>;
+    /**
+     * In the factory only: the document at `key` as a watchable (a state member, a derive source, an `on` source),
+     * `initial()` while absent, loaded before the object goes live and pinned while this attempt lives.
+     */
+    at(key: string): Watchable<T>;
+    /** One transaction that drafts the document at `key` and passes the draft to `fn`. */
+    change<R>(key: string, fn: (draft: Draft<T>) => R, context: Context): Promise<R>;
+    /** One transaction that retires the document at `key` (a no-op when absent). */
+    retire(key: string, context: Context): Promise<void>;
+}
+/** The handle `self.state(definition)` returns. */
+export type HandleOf<D> = D extends StateDefinition<infer T, infer K, boolean> ? K extends true ? KeyedHandle<T> : SingletonHandle<T> : never;
+/**
+ * A singleton's handle. Reads go to the slot (allowed after the seal); `change` and `retire` take the line under the
+ * attempt's token. Exposed as a member or read by a derive, it resolves to the slot itself.
+ */
+export declare class Singleton implements SingletonHandle<JsonObject> {
+    readonly slot: SingletonSlot;
+    readonly token: SealToken;
+    /** The version of the definition it was declared with: the slot refuses it once its values are newer (R15). */
+    readonly version: number;
+    constructor(slot: SingletonSlot, token: SealToken, version: number);
+    get value(): JsonObject;
+    watch(context: Context): Promise<Watch<JsonObject>>;
+    change<R>(fn: (draft: Draft<JsonObject>) => R, context: Context): Promise<R>;
+    retire(context: Context): Promise<void>;
+}
+/** Who declares an attempt's `at(key)` pins: its factory, which alone may (the attempt). */
+export interface KeyDeclarer {
+    /** Pins `key` of `slot` for the attempt and returns its source; throws outside the factory. */
+    at(slot: KeyedSlot, key: string): KeySource;
+}
+/** A keyed handle: reads go to the slot; `change`, `retire` and cold reads take the line under the attempt's token. */
+export declare class Keyed implements KeyedHandle<JsonObject> {
+    #private;
+    readonly slot: KeyedSlot;
+    readonly token: SealToken;
+    /** As `Singleton.version`. */
+    readonly version: number;
+    constructor(slot: KeyedSlot, token: SealToken, version: number, declarer: KeyDeclarer);
+    get(key: string, context: Context): Promise<JsonObject | undefined>;
+    keys(context: Context): AsyncIterable<string>;
+    watch(key: string, context: Context): Promise<Watch<JsonObject> | undefined>;
+    at(key: string): Watchable<JsonObject>;
+    change<R>(key: string, fn: (draft: Draft<JsonObject>) => R, context: Context): Promise<R>;
+    retire(key: string, context: Context): Promise<void>;
+}
+//# sourceMappingURL=handles.d.ts.map

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

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

package/dist/documents/handles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handles.js","sourceRoot":"","sources":["../../src/documents/handles.ts"],"names":[],"mappings":"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","sourcesContent":["// Document handles (slice 6a §1.2): what `self.state` returns, one per attempt and definition, a thin view of its\n// object's slot bound to the attempt's seal token and the definition's version.\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Draft } from \"../delta/index.ts\";\nimport type { Watch, Watchable, WatchHandle } from \"../watch.ts\";\nimport type { JsonObject, StateDefinition } from \"./definition.ts\";\nimport type { SealToken } from \"./fence.ts\";\nimport type { KeyedSlot, KeySource } from \"./keyed-slot.ts\";\nimport type { SingletonSlot } from \"./slot.ts\";\n\n/** A singleton document: a watchable that always has a value (`initial()` until written, and after a retire). */\nexport interface SingletonHandle<T extends JsonObject> extends Watchable<T> {\n\t/** One transaction that drafts this document and passes the draft to `fn`. */\n\tchange<R>(fn: (draft: Draft<T>) => R, context: Context): Promise<R>;\n\t/** One transaction that retires this document: back to `initial()`. */\n\tretire(context: Context): Promise<void>;\n}\n\n/**\n * Keyed documents: many per object, by string key. Not a watchable itself: each key is, through `watch(key)` and\n * `at(key)`; a live collection is a singleton holding it.\n */\nexport interface KeyedHandle<T extends JsonObject> {\n\t/** The document's value, `undefined` when absent (persisted and not in memory: loaded on the object's line). */\n\tget(key: string, context: Context): Promise<T | undefined>;\n\t/** The keys of the present documents, in code point order. */\n\tkeys(context: Context): AsyncIterable<string>;\n\t/**\n\t * A watch of the document at `key`, `undefined` when absent. It follows the address: a retirement is one frame with\n\t * `retired: true` and `initial()`, a later creation a root replacement; it ends with the object.\n\t */\n\twatch(key: string, context: Context): Promise<WatchHandle<T> | undefined>;\n\t/**\n\t * In the factory only: the document at `key` as a watchable (a state member, a derive source, an `on` source),\n\t * `initial()` while absent, loaded before the object goes live and pinned while this attempt lives.\n\t */\n\tat(key: string): Watchable<T>;\n\t/** One transaction that drafts the document at `key` and passes the draft to `fn`. */\n\tchange<R>(key: string, fn: (draft: Draft<T>) => R, context: Context): Promise<R>;\n\t/** One transaction that retires the document at `key` (a no-op when absent). */\n\tretire(key: string, context: Context): Promise<void>;\n}\n\n/** The handle `self.state(definition)` returns. */\nexport type HandleOf<D> = D extends StateDefinition<infer T, infer K, boolean>\n\t? K extends true\n\t\t? KeyedHandle<T>\n\t\t: SingletonHandle<T>\n\t: never;\n\n/**\n * A singleton's handle. Reads go to the slot (allowed after the seal); `change` and `retire` take the line under the\n * attempt's token. Exposed as a member or read by a derive, it resolves to the slot itself.\n */\nexport class Singleton implements SingletonHandle<JsonObject> {\n\treadonly slot: SingletonSlot;\n\treadonly token: SealToken;\n\t/** The version of the definition it was declared with: the slot refuses it once its values are newer (R15). */\n\treadonly version: number;\n\n\tconstructor(slot: SingletonSlot, token: SealToken, version: number) {\n\t\tthis.slot = slot;\n\t\tthis.token = token;\n\t\tthis.version = version;\n\t}\n\n\tget value(): JsonObject {\n\t\tthis.slot.definition.assertVersion(this.version);\n\t\treturn this.slot.value;\n\t}\n\n\tasync watch(context: Context): Promise<Watch<JsonObject>> {\n\t\tthis.slot.definition.assertVersion(this.version);\n\t\t// The slot's values are this handle's documents.\n\t\treturn this.slot.openWatch(context) as Watch<JsonObject>;\n\t}\n\n\tchange<R>(fn: (draft: Draft<JsonObject>) => R, context: Context): Promise<R> {\n\t\treturn this.slot.owner.tx(async (tx) => fn(await tx.draft(this)), this.token, context);\n\t}\n\n\tretire(context: Context): Promise<void> {\n\t\treturn this.slot.owner.tx((tx) => tx.retire(this), this.token, context);\n\t}\n}\n\n/** Who declares an attempt's `at(key)` pins: its factory, which alone may (the attempt). */\nexport interface KeyDeclarer {\n\t/** Pins `key` of `slot` for the attempt and returns its source; throws outside the factory. */\n\tat(slot: KeyedSlot, key: string): KeySource;\n}\n\n/** A keyed handle: reads go to the slot; `change`, `retire` and cold reads take the line under the attempt's token. */\nexport class Keyed implements KeyedHandle<JsonObject> {\n\treadonly slot: KeyedSlot;\n\treadonly token: SealToken;\n\t/** As `Singleton.version`. */\n\treadonly version: number;\n\treadonly #declarer: KeyDeclarer;\n\n\tconstructor(slot: KeyedSlot, token: SealToken, version: number, declarer: KeyDeclarer) {\n\t\tthis.slot = slot;\n\t\tthis.token = token;\n\t\tthis.version = version;\n\t\tthis.#declarer = declarer;\n\t}\n\n\tget(key: string, context: Context): Promise<JsonObject | undefined> {\n\t\treturn this.slot.get(key, this, context);\n\t}\n\n\tkeys(context: Context): AsyncIterable<string> {\n\t\treturn this.slot.keys(this, context);\n\t}\n\n\twatch(key: string, context: Context): Promise<Watch<JsonObject> | undefined> {\n\t\treturn this.slot.watch(key, this, context);\n\t}\n\n\tat(key: string): Watchable<JsonObject> {\n\t\t// The source's values are this slot's documents.\n\t\treturn this.#declarer.at(this.slot, key) as unknown as Watchable<JsonObject>;\n\t}\n\n\tchange<R>(key: string, fn: (draft: Draft<JsonObject>) => R, context: Context): Promise<R> {\n\t\treturn this.slot.owner.tx(async (tx) => fn(await tx.draft(this, key)), this.token, context);\n\t}\n\n\tretire(key: string, context: Context): Promise<void> {\n\t\treturn this.slot.owner.tx((tx) => tx.retire(this, key), this.token, context);\n\t}\n}\n"]}

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/documents/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,iBAAiB,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7G,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/documents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/documents/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EAA0B,WAAW,EAAyC,MAAM,iBAAiB,CAAC","sourcesContent":["// Documents for apps: definitions, handles and transactions.\n\nexport { type CommitPersistence, defineState, type JsonObject, type StateDefinition } from \"./definition.ts\";\nexport type { HandleOf, KeyedHandle, SingletonHandle } from \"./handles.ts\";\nexport type { Tx } from \"./transaction.ts\";\n"]}

package/dist/documents/internal.d.ts

@@ -0,0 +1,9 @@
+export { AddressSource } from "./address-source.ts";
+export { Documents, type DocumentsOwner, type TransactionCancelled } from "./documents.ts";
+export { SealToken } from "./fence.ts";
+export { type KeyDeclarer, Keyed, Singleton } from "./handles.ts";
+export { type KeyedSlot, KeySource } from "./keyed-slot.ts";
+export { type DocumentChange, type Held, Persistence, type Stored, type StoredChange, storedAfter, } from "./persistence.ts";
+export { type AnyDefinition, type DocumentSlot, type PersistedSlot, SlotDefinition } from "./slot.ts";
+export type { Staged, Transaction } from "./transaction.ts";
+//# sourceMappingURL=internal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/documents/internal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,WAAW,EACX,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,WAAW,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACtG,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/documents/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/documents/internal.ts"],"names":[],"mappings":"AAAA,qHAAqH;AAErH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAkD,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAoB,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAkB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAGN,WAAW,EAGX,WAAW,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAA6D,cAAc,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// Documents for Chord's layers: an object's documents and slots, the handles' classes, the seal token, transactions.\n\nexport { AddressSource } from \"./address-source.ts\";\nexport { Documents, type DocumentsOwner, type TransactionCancelled } from \"./documents.ts\";\nexport { SealToken } from \"./fence.ts\";\nexport { type KeyDeclarer, Keyed, Singleton } from \"./handles.ts\";\nexport { type KeyedSlot, KeySource } from \"./keyed-slot.ts\";\nexport {\n\ttype DocumentChange,\n\ttype Held,\n\tPersistence,\n\ttype Stored,\n\ttype StoredChange,\n\tstoredAfter,\n} from \"./persistence.ts\";\nexport { type AnyDefinition, type DocumentSlot, type PersistedSlot, SlotDefinition } from \"./slot.ts\";\nexport type { Staged, Transaction } from \"./transaction.ts\";\n"]}

package/dist/documents/keyed-slot.d.ts

@@ -0,0 +1,103 @@
+import { type Context } from "../context/index.ts";
+import { type Prepared, type Tracker } from "../delta/index.ts";
+import type { StagedWrite } from "../store/step.ts";
+import type { Watch } from "../watch.ts";
+import { AddressSource } from "./address-source.ts";
+import type { JsonObject } 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";
+import { Resident } from "./residency.ts";
+import { type AnyDefinition, type DocumentSlot, type PersistedSlot, SlotDefinition } from "./slot.ts";
+/** Whom a read is for: a handle's seal token and the version it was declared with (R15). */
+export type Access = {
+    readonly token: SealToken;
+    readonly version: number;
+};
+/** A keyed slot: one resident per document in memory, one source per pinned key. */
+export declare class KeyedSlot 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;
+    /**
+     * The value at `key`, `undefined` when absent. A document in memory is read at once (also through a sealed
+     * handle); a cold persisted one is loaded on the line (refused `released` once the access's token is sealed), and
+     * `context` ends only this caller's wait. An absent key is not cached (rule 20).
+     */
+    get(raw: string, access: Access, context: Context): Promise<JsonObject | undefined>;
+    /** The present keys in code point order: in memory, the residents; persisted, the store's, a page per line job. */
+    keys(access: Access, context: Context): AsyncIterable<string>;
+    /**
+     * A watch of the document at `key`, `undefined` when absent (after a cold load); it follows the address (a
+     * retirement is a frame with the `retired` flag) and pins the key until it ends.
+     */
+    watch(raw: string, access: Access, context: Context): Promise<Watch<JsonObject> | undefined>;
+    /**
+     * Pins `key`: its source (made by the first pin) and its document stay in memory until the returned release
+     * (idempotent) runs; a persisted key not in memory is loaded by the next activation load (`loadDeclared`).
+     */
+    pin(raw: string, context: Context): () => void;
+    /** Loads pinned `key` on the line unless it was loaded since it was pinned (a consumer's `at(key)`, slice 6a §12). */
+    ensure(raw: string, context: Context): Promise<void>;
+    /** The source of pinned `key`. */
+    source(key: string): KeySource;
+    /**
+     * `key` as the slot and the store keep it: the `str()` text rules (slice 6a §8), a lone surrogate replaced by
+     * U+FFFD, NUL refused `invalid/args`. Plugin keys are a trust boundary; every entry point takes them through here,
+     * so memory and the store agree on one key.
+     */
+    key(key: string): string;
+    /** Loads every pinned key not loaded since it was pinned (activation, holding the line). */
+    loadDeclared(context: Context): Promise<void>;
+    /**
+     * Loads the document at `key` (the caller holds the line) and installs it while it is still absent from memory (a
+     * commit's `adopt` always wins). A stored version newer than the code's, another fingerprint or a failing `migrate`
+     * fails the owner (slice 6a §1.4) and rejects with the cause.
+     */
+    load(key: string, context: Context, token?: SealToken): Promise<void>;
+    cold(key: string): boolean;
+    stored(key: string): Stored | undefined;
+    stage(key: string, change: DocumentChange, was: Stored | undefined, writes: StagedWrite[]): StoredChange;
+    /**
+     * Takes the attempt's declaration: a newer version migrates each document in memory on its next access (persisted
+     * ones store a base with their next change); the pinned keys are watched, so they migrate now, all or none, and
+     * take `initial()` again.
+     */
+    hydrate(definition: AnyDefinition, context: Context): void;
+    current(key: string): Tracker<JsonObject> | undefined;
+    /** The value a draft of an absent document starts from: a fresh `initial()`. */
+    initial(context: Context): JsonObject;
+    adopt(key: string, tracker: Tracker<JsonObject>, prepared: Prepared<JsonObject>, change: StoredChange | undefined): void;
+    /** Retires the document at `key` (inside the batch): out of memory, its source reads `initial()` with the flag. */
+    retire(key: string): void;
+    /** The sweep found `resident` idle past the retention: it leaves memory. */
+    evict(resident: Resident): void;
+    /** Its object ended or no attempt declares it any more: the documents go and the keys' watches end. */
+    drop(): void;
+}
+/**
+ * One pinned key of a keyed slot as a source (`handle.at(key)`, a keyed member's `at(key)`, `watch(key)`): the
+ * document's value, `initial()` while it is absent; retirements arrive with the `retired` flag.
+ */
+export declare class KeySource extends AddressSource {
+    #private;
+    readonly key: string;
+    /** Its pins: at 0 the slot forgets it. */
+    pins: number;
+    /** Whether the key was loaded since it was pinned (always, in memory): its value is known. */
+    ready: boolean;
+    constructor(slot: KeyedSlot, key: string, initial: JsonObject, ready: boolean);
+    get value(): JsonObject;
+    /** The value without the checks (inside its slot's commits). */
+    peek(): JsonObject;
+    /** The document was retired: `initial()` from now, with the flag. */
+    retire(): void;
+    /** A new definition took over (inside a batch): `initial()` again, the value as a root replacement. */
+    retake(initial: JsonObject): void;
+    /** Its slot was dropped: the watches end. */
+    end(): void;
+}
+//# sourceMappingURL=keyed-slot.d.ts.map

package/dist/documents/keyed-slot.d.ts.map

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