@earendil-works/chord 1.4.0 → 1.5.1

package/dist/documents/address-source.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "../context/index.ts";
+import type { Prepared } from "../delta/index.ts";
+import { Source } from "../state/internal.ts";
+import type { JsonObject } from "./definition.ts";
+/** A source following one document address; `value` is the document's, or `initial()` while it is absent. */
+export declare abstract class AddressSource extends Source {
+    #private;
+    abstract get value(): JsonObject;
+    deliver(context: Context): void;
+    /**
+     * A commit wrote the document, which read `before`: its ops, or a root replacement when the draft started from
+     * another base or the document was retired earlier in the batch.
+     */
+    written(before: JsonObject, prepared: Prepared<JsonObject>): void;
+    /** The document was retired: it reads `initial` again, and the frame says so. */
+    retired(initial: JsonObject): void;
+    /** The value changed outside a commit (a migration, a load): a root replacement. */
+    replaced(): void;
+}
+//# sourceMappingURL=address-source.d.ts.map

package/dist/documents/address-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-source.d.ts","sourceRoot":"","sources":["../../src/documents/address-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAM,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,6GAA6G;AAC7G,8BAAsB,aAAc,SAAQ,MAAM;;IAKjD,aAAsB,KAAK,IAAI,UAAU,CAAC;IAE1C,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAI9B;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAIhE;IAED,iFAAiF;IACjF,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAQjC;IAED,oFAAoF;IACpF,QAAQ,IAAI,IAAI,CAGf;CACD"}

package/dist/documents/address-source.js

@@ -0,0 +1,44 @@
+// Watchable document addresses (slice 6a §11; decision "One retirement mechanism"): the frames of a source that
+// follows one address, a singleton's slot or one key of a keyed slot. A change arrives with its ops, a write over
+// another base as a root replacement, a retirement as `[["r", initial()]]` with the `retired` flag, and a document
+// created after a retirement in the same batch as one root replacement with the flag.
+import { Source } from "../state/internal.js";
+const NO_OPS = [];
+/** A source following one document address; `value` is the document's, or `initial()` while it is absent. */
+export class AddressSource extends Source {
+    /** The ops of the current batch's frame, and whether the document was retired in it. */
+    #ops = NO_OPS;
+    #retired = false;
+    deliver(context) {
+        this.publish(this.value, this.#ops, this.#retired, context);
+        this.#ops = NO_OPS;
+        this.#retired = false;
+    }
+    /**
+     * A commit wrote the document, which read `before`: its ops, or a root replacement when the draft started from
+     * another base or the document was retired earlier in the batch.
+     */
+    written(before, prepared) {
+        // The ops are kept for a frame, which only a watched source gets: an unwatched one keeps none.
+        if (this.watched)
+            this.#ops = prepared.base === before && !this.#retired ? prepared.ops : [["r", prepared.value]];
+        this.changed();
+    }
+    /** The document was retired: it reads `initial` again, and the frame says so. */
+    retired(initial) {
+        // Reset by the frame, which only a watched source gets.
+        if (this.watched) {
+            this.#ops = [["r", initial]];
+            this.#retired = true;
+        }
+        this.changed();
+        this.retiredInBatch();
+    }
+    /** The value changed outside a commit (a migration, a load): a root replacement. */
+    replaced() {
+        if (this.watched)
+            this.#ops = [["r", this.value]];
+        this.changed();
+    }
+}
+//# sourceMappingURL=address-source.js.map

package/dist/documents/address-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-source.js","sourceRoot":"","sources":["../../src/documents/address-source.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAChH,kHAAkH;AAClH,mHAAmH;AACnH,sFAAsF;AAItF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,MAAM,MAAM,GAAkB,EAAE,CAAC;AAEjC,6GAA6G;AAC7G,MAAM,OAAgB,aAAc,SAAQ,MAAM;IACjD,wFAAwF;IACxF,IAAI,GAAG,MAAM,CAAC;IACd,QAAQ,GAAG,KAAK,CAAC;IAIjB,OAAO,CAAC,OAAgB;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,MAAkB,EAAE,QAA8B;QACzD,+FAA+F;QAC/F,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAClH,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,iFAAiF;IACjF,OAAO,CAAC,OAAmB;QAC1B,wDAAwD;QACxD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC,cAAc,EAAE,CAAC;IACvB,CAAC;IAED,oFAAoF;IACpF,QAAQ;QACP,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;CACD","sourcesContent":["// Watchable document addresses (slice 6a §11; decision \"One retirement mechanism\"): the frames of a source that\n// follows one address, a singleton's slot or one key of a keyed slot. A change arrives with its ops, a write over\n// another base as a root replacement, a retirement as `[[\"r\", initial()]]` with the `retired` flag, and a document\n// created after a retirement in the same batch as one root replacement with the flag.\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Op, Prepared } from \"../delta/index.ts\";\nimport { Source } from \"../state/internal.ts\";\nimport type { JsonObject } from \"./definition.ts\";\n\nconst NO_OPS: readonly Op[] = [];\n\n/** A source following one document address; `value` is the document's, or `initial()` while it is absent. */\nexport abstract class AddressSource extends Source {\n\t/** The ops of the current batch's frame, and whether the document was retired in it. */\n\t#ops = NO_OPS;\n\t#retired = false;\n\n\tabstract override get value(): JsonObject;\n\n\tdeliver(context: Context): void {\n\t\tthis.publish(this.value, this.#ops, this.#retired, context);\n\t\tthis.#ops = NO_OPS;\n\t\tthis.#retired = false;\n\t}\n\n\t/**\n\t * A commit wrote the document, which read `before`: its ops, or a root replacement when the draft started from\n\t * another base or the document was retired earlier in the batch.\n\t */\n\twritten(before: JsonObject, prepared: Prepared<JsonObject>): void {\n\t\t// The ops are kept for a frame, which only a watched source gets: an unwatched one keeps none.\n\t\tif (this.watched) this.#ops = prepared.base === before && !this.#retired ? prepared.ops : [[\"r\", prepared.value]];\n\t\tthis.changed();\n\t}\n\n\t/** The document was retired: it reads `initial` again, and the frame says so. */\n\tretired(initial: JsonObject): void {\n\t\t// Reset by the frame, which only a watched source gets.\n\t\tif (this.watched) {\n\t\t\tthis.#ops = [[\"r\", initial]];\n\t\t\tthis.#retired = true;\n\t\t}\n\t\tthis.changed();\n\t\tthis.retiredInBatch();\n\t}\n\n\t/** The value changed outside a commit (a migration, a load): a root replacement. */\n\treplaced(): void {\n\t\tif (this.watched) this.#ops = [[\"r\", this.value]];\n\t\tthis.changed();\n\t}\n}\n"]}

package/dist/documents/definition.d.ts

@@ -0,0 +1,84 @@
+import type { Context } from "../context/index.ts";
+import type { Schema, Static } from "../contracts/index.ts";
+import type { Op } from "../delta/index.ts";
+import type { JsonValue } from "../json.ts";
+/** A document root: a JSON object. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * When a commit reaches the store (Durable's `CommitPersistence`): `immediate`, the default, before the commit
+ * resolves; `deferred` (a persisted run's state change, D8): adopted and published at once, stored with the next
+ * immediate change, the run's outcome, the object's close, or about `withinMs` (default 1,000 ms) later.
+ */
+export type CommitPersistence = {
+    readonly kind: "immediate";
+} | {
+    readonly kind: "deferred";
+    readonly withinMs?: number;
+};
+/** What a persisted document's `checkpointWhen` learns of its stored revisions. */
+export type CheckpointInfo = {
+    /** The deltas stored after its newest base, without the change being decided. */
+    readonly deltasSinceBase: number;
+};
+/** Whether a commit's change of a persisted document is stored as a whole new base (`true`) or as a delta. */
+export type CheckpointWhen<T> = (value: T, ops: readonly Op[], info: CheckpointInfo) => boolean;
+/** What `defineState` takes for any document. */
+type StateOptions<S extends Schema, K extends boolean> = {
+    readonly schema: S;
+    readonly version: number;
+    readonly initial: () => DocumentOf<S>;
+    /** Maps a value of an older version `from` to this version's shape; pure. Required to read older values. */
+    readonly migrate?: (old: JsonObject, from: number) => DocumentOf<S>;
+    readonly keyed?: K;
+};
+/** What a persisted document adds (slice 6a §10): `checkpointWhen` is required. */
+type PersistOptions<S extends Schema> = {
+    /** Stored in the host's store; only in `local` types with empty params (P3). */
+    readonly persist: true;
+    /** Called once per commit per changed document; creations and version changes always store a base. */
+    readonly checkpointWhen: CheckpointWhen<DocumentOf<S>>;
+};
+/**
+ * Declares a document: a singleton per object, or with `keyed: true` many per object, each by a string key; with
+ * `persist: true` stored in the host's store. Its name is a restricted name (lowercase `[a-z0-9@/._~-]`).
+ */
+export declare function defineState<S extends Schema, K extends boolean = false>(name: string, options: StateOptions<S, K> & {
+    readonly persist?: false;
+    readonly checkpointWhen?: never;
+}): StateDefinition<DocumentOf<S>, K, false>;
+export declare function defineState<S extends Schema, K extends boolean = false>(name: string, options: StateOptions<S, K> & PersistOptions<S>): StateDefinition<DocumentOf<S>, K, true>;
+/** The value of a document whose schema is `S`: its static type, which must be a JSON object. */
+type DocumentOf<S extends Schema> = Static<S> extends JsonObject ? Static<S> : never;
+/** A declared document; `T` is its value, `K` whether it is keyed, `P` whether it is persisted. */
+export declare class StateDefinition<T extends JsonObject, K extends boolean, P extends boolean = false> {
+    #private;
+    readonly name: string;
+    readonly schema: Schema;
+    readonly version: number;
+    readonly keyed: boolean;
+    readonly persist: boolean;
+    /**
+     * `hash64` of the schema's normal form (descriptions and titles ignored), computed once: the same version with
+     * another fingerprint is a schema changed without a version bump.
+     */
+    readonly fingerprint: string;
+    /** Type only: whether the definition is keyed. */
+    readonly "~keyed"?: K;
+    /** Type only: whether the definition is persisted. */
+    readonly "~persist"?: P;
+    constructor(name: string, schema: Schema, version: number, initial: () => T, migrate: ((old: JsonObject, from: number) => T) | undefined, keyed: boolean, persist: boolean, checkpointWhen: CheckpointWhen<T> | undefined);
+    /** Whether a persisted document's change is stored as a new base (its `checkpointWhen`); never asked in memory. */
+    checkpointWhen(value: T, ops: readonly Op[], info: CheckpointInfo): boolean;
+    /** A fresh `initial()` value; the first is checked against the schema (counted), later ones are not (R8). */
+    initial(context: Context): T;
+    /**
+     * `old`, a value of version `from`, migrated to this version and checked against the schema once, as it is
+     * produced (R8, counted). Throws without a `migrate` (the access is refused, the data kept) and when the result does
+     * not match.
+     */
+    migrate(old: JsonObject, from: number, context: Context): T;
+}
+export {};
+//# sourceMappingURL=definition.d.ts.map

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

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

package/dist/documents/definition.js

@@ -0,0 +1,74 @@
+// Document definitions: `defineState(name, ...)`, its fingerprint, the one check of a definition's `initial()` (R8),
+// the checked `migrate` of an older value and, for a persisted document, its checkpoint rule (slice 6a §10).
+import { checkName, fingerprintOf } from "../contracts/internal.js";
+import { snapshotSchema } from "../contracts/snapshot.js";
+import { validatorFor } from "../data/internal.js";
+import { chordMetrics } from "../telemetry.js";
+export function defineState(name, options) {
+    checkName(name, "A state name");
+    const { schema, version, initial, migrate, keyed, persist, checkpointWhen } = options;
+    return new StateDefinition(name, schema, version, initial, migrate, keyed ?? false, persist ?? false, checkpointWhen);
+}
+const NEVER = () => false;
+/** A declared document; `T` is its value, `K` whether it is keyed, `P` whether it is persisted. */
+export class StateDefinition {
+    name;
+    schema;
+    version;
+    keyed;
+    persist;
+    /**
+     * `hash64` of the schema's normal form (descriptions and titles ignored), computed once: the same version with
+     * another fingerprint is a schema changed without a version bump.
+     */
+    fingerprint;
+    #initial;
+    #migrate;
+    /** Method-typed so that a definition of a narrower `T` still is a `StateDefinition<JsonObject, ...>`. */
+    #checkpointWhen;
+    #checked = false;
+    constructor(name, schema, version, initial, migrate, keyed, persist, checkpointWhen) {
+        this.name = name;
+        this.schema = schema;
+        this.version = version;
+        this.#initial = initial;
+        this.#migrate = migrate;
+        this.keyed = keyed;
+        this.persist = persist;
+        this.#checkpointWhen = checkpointWhen ?? NEVER;
+        this.fingerprint = fingerprintOf(snapshotSchema(schema, name).normal);
+    }
+    /** Whether a persisted document's change is stored as a new base (its `checkpointWhen`); never asked in memory. */
+    checkpointWhen(value, ops, info) {
+        return this.#checkpointWhen(value, ops, info);
+    }
+    /** A fresh `initial()` value; the first is checked against the schema (counted), later ones are not (R8). */
+    initial(context) {
+        const value = this.#initial();
+        if (this.#checked)
+            return value;
+        this.#check(value, "initial()", context);
+        this.#checked = true;
+        return value;
+    }
+    /**
+     * `old`, a value of version `from`, migrated to this version and checked against the schema once, as it is
+     * produced (R8, counted). Throws without a `migrate` (the access is refused, the data kept) and when the result does
+     * not match.
+     */
+    migrate(old, from, context) {
+        if (this.#migrate === undefined) {
+            throw new Error(`${this.name}: no migrate from version ${from} to ${this.version}`);
+        }
+        const value = this.#migrate(old, from);
+        this.#check(value, `migrate() from version ${from}`, context);
+        return value;
+    }
+    #check(value, what, context) {
+        chordMetrics(context.telemetry.metrics).counter("chord.data.validations").add(1);
+        if (!validatorFor(this, context).check(value)) {
+            throw new Error(`${this.name}: ${what} does not match the schema`);
+        }
+    }
+}
+//# sourceMappingURL=definition.js.map

package/dist/documents/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/documents/definition.ts"],"names":[],"mappings":"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","sourcesContent":["// Document definitions: `defineState(name, ...)`, its fingerprint, the one check of a definition's `initial()` (R8),\n// the checked `migrate` of an older value and, for a persisted document, its checkpoint rule (slice 6a §10).\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Schema, Static } from \"../contracts/index.ts\";\nimport { checkName, fingerprintOf } from \"../contracts/internal.ts\";\nimport { snapshotSchema } from \"../contracts/snapshot.ts\";\nimport { validatorFor } from \"../data/internal.ts\";\nimport type { Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\n\n/** A document root: a JSON object. */\nexport type JsonObject = { [key: string]: JsonValue };\n\n/**\n * When a commit reaches the store (Durable's `CommitPersistence`): `immediate`, the default, before the commit\n * resolves; `deferred` (a persisted run's state change, D8): adopted and published at once, stored with the next\n * immediate change, the run's outcome, the object's close, or about `withinMs` (default 1,000 ms) later.\n */\nexport type CommitPersistence =\n\t| { readonly kind: \"immediate\" }\n\t| { readonly kind: \"deferred\"; readonly withinMs?: number };\n\n/** What a persisted document's `checkpointWhen` learns of its stored revisions. */\nexport type CheckpointInfo = {\n\t/** The deltas stored after its newest base, without the change being decided. */\n\treadonly deltasSinceBase: number;\n};\n\n/** Whether a commit's change of a persisted document is stored as a whole new base (`true`) or as a delta. */\nexport type CheckpointWhen<T> = (value: T, ops: readonly Op[], info: CheckpointInfo) => boolean;\n\n/** What `defineState` takes for any document. */\ntype StateOptions<S extends Schema, K extends boolean> = {\n\treadonly schema: S;\n\treadonly version: number;\n\treadonly initial: () => DocumentOf<S>;\n\t/** Maps a value of an older version `from` to this version's shape; pure. Required to read older values. */\n\treadonly migrate?: (old: JsonObject, from: number) => DocumentOf<S>;\n\treadonly keyed?: K;\n};\n\n/** What a persisted document adds (slice 6a §10): `checkpointWhen` is required. */\ntype PersistOptions<S extends Schema> = {\n\t/** Stored in the host's store; only in `local` types with empty params (P3). */\n\treadonly persist: true;\n\t/** Called once per commit per changed document; creations and version changes always store a base. */\n\treadonly checkpointWhen: CheckpointWhen<DocumentOf<S>>;\n};\n\n/**\n * Declares a document: a singleton per object, or with `keyed: true` many per object, each by a string key; with\n * `persist: true` stored in the host's store. Its name is a restricted name (lowercase `[a-z0-9@/._~-]`).\n */\nexport function defineState<S extends Schema, K extends boolean = false>(\n\tname: string,\n\toptions: StateOptions<S, K> & { readonly persist?: false; readonly checkpointWhen?: never },\n): StateDefinition<DocumentOf<S>, K, false>;\nexport function defineState<S extends Schema, K extends boolean = false>(\n\tname: string,\n\toptions: StateOptions<S, K> & PersistOptions<S>,\n): StateDefinition<DocumentOf<S>, K, true>;\nexport function defineState<S extends Schema, K extends boolean>(\n\tname: string,\n\toptions: StateOptions<S, K> & {\n\t\treadonly persist?: boolean;\n\t\treadonly checkpointWhen?: CheckpointWhen<DocumentOf<S>>;\n\t},\n): StateDefinition<DocumentOf<S>, K, boolean> {\n\tcheckName(name, \"A state name\");\n\tconst { schema, version, initial, migrate, keyed, persist, checkpointWhen } = options;\n\treturn new StateDefinition(\n\t\tname,\n\t\tschema,\n\t\tversion,\n\t\tinitial,\n\t\tmigrate,\n\t\tkeyed ?? false,\n\t\tpersist ?? false,\n\t\tcheckpointWhen,\n\t);\n}\n\n/** The value of a document whose schema is `S`: its static type, which must be a JSON object. */\ntype DocumentOf<S extends Schema> = Static<S> extends JsonObject ? Static<S> : never;\n\nconst NEVER: CheckpointWhen<JsonObject> = () => false;\n\n/** A declared document; `T` is its value, `K` whether it is keyed, `P` whether it is persisted. */\nexport class StateDefinition<T extends JsonObject, K extends boolean, P extends boolean = false> {\n\treadonly name: string;\n\treadonly schema: Schema;\n\treadonly version: number;\n\treadonly keyed: boolean;\n\treadonly persist: boolean;\n\t/**\n\t * `hash64` of the schema's normal form (descriptions and titles ignored), computed once: the same version with\n\t * another fingerprint is a schema changed without a version bump.\n\t */\n\treadonly fingerprint: string;\n\t/** Type only: whether the definition is keyed. */\n\tdeclare readonly \"~keyed\"?: K;\n\t/** Type only: whether the definition is persisted. */\n\tdeclare readonly \"~persist\"?: P;\n\treadonly #initial: () => T;\n\treadonly #migrate: ((old: JsonObject, from: number) => T) | undefined;\n\t/** Method-typed so that a definition of a narrower `T` still is a `StateDefinition<JsonObject, ...>`. */\n\treadonly #checkpointWhen: { rule(value: T, ops: readonly Op[], info: CheckpointInfo): boolean }[\"rule\"];\n\t#checked = false;\n\n\tconstructor(\n\t\tname: string,\n\t\tschema: Schema,\n\t\tversion: number,\n\t\tinitial: () => T,\n\t\tmigrate: ((old: JsonObject, from: number) => T) | undefined,\n\t\tkeyed: boolean,\n\t\tpersist: boolean,\n\t\tcheckpointWhen: CheckpointWhen<T> | undefined,\n\t) {\n\t\tthis.name = name;\n\t\tthis.schema = schema;\n\t\tthis.version = version;\n\t\tthis.#initial = initial;\n\t\tthis.#migrate = migrate;\n\t\tthis.keyed = keyed;\n\t\tthis.persist = persist;\n\t\tthis.#checkpointWhen = checkpointWhen ?? NEVER;\n\t\tthis.fingerprint = fingerprintOf(snapshotSchema(schema, name).normal);\n\t}\n\n\t/** Whether a persisted document's change is stored as a new base (its `checkpointWhen`); never asked in memory. */\n\tcheckpointWhen(value: T, ops: readonly Op[], info: CheckpointInfo): boolean {\n\t\treturn this.#checkpointWhen(value, ops, info);\n\t}\n\n\t/** A fresh `initial()` value; the first is checked against the schema (counted), later ones are not (R8). */\n\tinitial(context: Context): T {\n\t\tconst value = this.#initial();\n\t\tif (this.#checked) return value;\n\t\tthis.#check(value, \"initial()\", context);\n\t\tthis.#checked = true;\n\t\treturn value;\n\t}\n\n\t/**\n\t * `old`, a value of version `from`, migrated to this version and checked against the schema once, as it is\n\t * produced (R8, counted). Throws without a `migrate` (the access is refused, the data kept) and when the result does\n\t * not match.\n\t */\n\tmigrate(old: JsonObject, from: number, context: Context): T {\n\t\tif (this.#migrate === undefined) {\n\t\t\tthrow new Error(`${this.name}: no migrate from version ${from} to ${this.version}`);\n\t\t}\n\t\tconst value = this.#migrate(old, from);\n\t\tthis.#check(value, `migrate() from version ${from}`, context);\n\t\treturn value;\n\t}\n\n\t#check(value: T, what: string, context: Context): void {\n\t\tchordMetrics(context.telemetry.metrics).counter(\"chord.data.validations\").add(1);\n\t\tif (!validatorFor(this, context).check(value)) {\n\t\t\tthrow new Error(`${this.name}: ${what} does not match the schema`);\n\t\t}\n\t}\n}\n"]}

package/dist/documents/documents.d.ts

@@ -0,0 +1,126 @@
+import type { TelemetryContext } from "@earendil-works/pi-telemetry";
+import type { Context } from "../context/index.ts";
+import { ChordError } from "../data/index.ts";
+import type { Batch } from "../state/internal.ts";
+import type { ChordStore } from "../store/store.ts";
+import type { CommitPersistence, JsonObject, StateDefinition } from "./definition.ts";
+import { SealToken } from "./fence.ts";
+import { type HandleOf, type KeyDeclarer } from "./handles.ts";
+import { Line } from "./line.ts";
+import { Residency } from "./residency.ts";
+import { type AnyDefinition } from "./slot.ts";
+import { Transaction } from "./transaction.ts";
+/**
+ * A transaction (a document change or retirement, `self.tx`, a job start) that did not commit because the context it
+ * was started with ended first: a root whose `fn` settled, a handler or routine whose object ended, a caller that
+ * cancelled. `error` is that context's abort reason, naming the scope that ended (decision "Mistakes that wait are
+ * reported at once" (e)).
+ */
+export type TransactionCancelled = {
+    readonly kind: "transaction_cancelled";
+    readonly object: string;
+    readonly error: unknown;
+};
+/**
+ * Who owns an object's documents: the object's name, batch and context, its store address, its live failure, and where
+ * a cancelled transaction is reported.
+ */
+export type DocumentsOwner = {
+    /** The owner's name in errors. */
+    readonly label: string;
+    readonly batch: Batch;
+    /** The object's context: shared cold loads run under it (rule 11). */
+    readonly context: Context;
+    /** The host's store and the object's owner name in it (its type, R2), when it has one. */
+    readonly store: {
+        readonly store: ChordStore;
+        readonly owner: string;
+    } | undefined;
+    /** A document the code cannot read fails the live object `broken` (slice 6a §1.4); ignored when it is not live. */
+    fail(error: ChordError): void;
+    /** Reports a transaction its context's end cancelled (the host's `onError`). */
+    report(error: TransactionCancelled): void;
+    /** The host's telemetry adapter: commit durations go to its metrics. */
+    readonly telemetry: TelemetryContext;
+};
+/**
+ * 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 declare class Documents {
+    #private;
+    /** The owner's name in errors. */
+    readonly label: string;
+    readonly batch: Batch;
+    /** The object's context. */
+    readonly context: Context;
+    readonly line: 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.
+     */
+    readonly residency: Residency;
+    /** The token of the object's own transactions: sealed with the object (`seal`). */
+    readonly own: SealToken;
+    constructor(owner: DocumentsOwner);
+    /**
+     * 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<D extends StateDefinition<JsonObject, boolean, boolean>>(definition: D, token: SealToken, declarer: KeyDeclarer): HandleOf<D>;
+    /**
+     * 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: AnyDefinition): void;
+    /**
+     * 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: ReadonlyMap<string, AnyDefinition>, pins: readonly (() => void)[], context: Context): void;
+    /**
+     * 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: Context): Promise<void> | undefined;
+    /**
+     * 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).
+     */
+    onLine<T>(job: () => Promise<T>, token?: SealToken): Promise<T>;
+    /**
+     * 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).
+     */
+    tx<R>(fn: (tx: Transaction) => R | Promise<R>, token: SealToken, context: Context, persistence?: CommitPersistence): Promise<R>;
+    /**
+     * 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: SealToken): void;
+    /** Throws `released` once the object ended. */
+    assertLive(): void;
+    /** Throws `released` once `token` is sealed or the object is ending: no new work takes the line. */
+    assertAdmitted(token: SealToken): void;
+    /** The live object fails `broken` with `error` (a document the code cannot read); ignored when it is not live. */
+    fail(error: ChordError): void;
+    /** The object is ending: every transaction is refused, the one holding the line discarded; documents stay readable. */
+    seal(): void;
+    /**
+     * 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).
+     */
+    settled(): Promise<void>;
+    /** Drops every document and pin; watches end `ended`, and every later use throws `released`. */
+    end(): void;
+    /** The `released` error of this object's documents. */
+    released(): ChordError;
+}
+//# sourceMappingURL=documents.d.ts.map

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

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

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