@earendil-works/chord 1.4.0 → 1.5.1

package/dist/documents/persistence.js

@@ -0,0 +1,129 @@
+// Persisted documents' store side (slice 6a §8, §10): a slot's address in the documents engine, what is stored of each
+// loaded document (Durable's `LoadedDocument` fields), its loads with the version and fingerprint checks and the
+// checked `migrate`, and the writes one commit stages for a changed or retired document.
+import { changeDocument, createDocument, findDocument, listDocumentKeys, loadDocument, retireDocument, } from "../store/engine.js";
+import { chordMetrics } from "../telemetry.js";
+/**
+ * The documents of one persisted name on one object: `(<object type>, namespace, name, key)`, the namespace `chord` for
+ * `self.state`, `chord.jobs` and `chord.job-states` for persisted job runs (slice 6b D5).
+ */
+export class Persistence {
+    store;
+    #address;
+    /** `owner` is the object's type (R2); `kind` the definition's or the job's name. */
+    constructor(store, owner, namespace, kind) {
+        this.store = store;
+        this.#address = { owner, namespace, kind };
+    }
+    /**
+     * The stored document at `key`, `undefined` when absent: found and loaded with plain reads (a store error rejects
+     * as the store's). Counted (`chord.store.loads`).
+     */
+    async read(key, context) {
+        const address = this.at(key);
+        const document = await this.store.read(async (executor) => {
+            const record = await findDocument(executor, address);
+            return record === undefined ? undefined : loadDocument(executor, record);
+        }, context);
+        if (document !== undefined)
+            chordMetrics(context.telemetry.metrics).counter("chord.store.loads").add(1);
+        return document;
+    }
+    /**
+     * `document` as `definition` reads it: a stored version newer than the code's, or the same version with another
+     * fingerprint (D9), throws; an older one is migrated and the result checked once (R8). What throws here is the
+     * code's (a failing `migrate` too, whatever it throws), never the store's.
+     */
+    decode(document, definition, context) {
+        const { record, deltasSinceBase } = document;
+        checkReadable(record, definition);
+        // The engine stores what commits gave it: JSON objects of the record's version.
+        const stored = document.value;
+        const value = record.version === definition.version ? stored : definition.migrate(stored, record.version, context);
+        return {
+            value,
+            stored: { id: record.id, revision: record.revision, version: record.version, deltasSinceBase },
+        };
+    }
+    /**
+     * What is stored of the live document at `key` without loading it (a retirement's find) and the schema fingerprint
+     * it was stored with (`checkReadable` takes both), `undefined` when absent.
+     */
+    async find(key, context) {
+        const record = await this.store.read((executor) => findDocument(executor, this.at(key)), context);
+        if (record === undefined)
+            return undefined;
+        // The change counter is all a retirement needs; `deltasSinceBase` is not read for one.
+        const stored = { id: record.id, revision: record.revision, version: record.version, deltasSinceBase: 0 };
+        return { stored, fingerprint: record.fingerprint };
+    }
+    /** Up to `limit` keys of live documents after `after`, in code point order. */
+    keys(after, limit, context) {
+        return this.store.read((executor) => listDocumentKeys(executor, this.#address, after, limit), context);
+    }
+    /**
+     * Stages one commit's writes of the document at `key` into `writes` (rule 8: serialized here, before the queue):
+     * its retirement when `retired` is stored, then its creation, or the change of `stored` (a base when created, when
+     * the stored version is older, or when `checkpointWhen` asks; a delta otherwise), `held` ops stored before the
+     * change's own (D8: a held base makes it a base). Returns what the commit stores.
+     */
+    stage(key, definition, stored, change, writes, held) {
+        const { prepared, retires } = change;
+        if (retires && stored !== undefined)
+            writes.push(retireDocument(stored.id, stored.revision));
+        if (prepared === undefined)
+            return { kind: "retire" };
+        const { version, fingerprint } = definition;
+        if (retires || stored === undefined) {
+            const base = { version, fingerprint, value: prepared.value };
+            const created = { id: 0 };
+            const write = createDocument(this.at(key), base, JSON.stringify(prepared.value), (id) => {
+                created.id = id;
+            });
+            writes.push(write);
+            return { kind: "create", version, created };
+        }
+        const info = { deltasSinceBase: stored.deltasSinceBase };
+        const base = held?.base === true ||
+            stored.version !== version ||
+            definition.checkpointWhen(prepared.value, prepared.ops, info);
+        const ops = held === undefined ? prepared.ops : [...held.ops, ...prepared.ops];
+        const content = base
+            ? { kind: "base", version, fingerprint, value: prepared.value }
+            : { kind: "delta", version, ops };
+        const text = JSON.stringify(base ? prepared.value : ops);
+        writes.push(changeDocument(stored.id, stored.revision, content, text));
+        const deltasSinceBase = base ? 0 : stored.deltasSinceBase + 1;
+        return { kind: "change", stored: { id: stored.id, revision: stored.revision + 1, version, deltasSinceBase } };
+    }
+    /** The address of `key`: a singleton's (`""`) has no key. */
+    at(key) {
+        return key === "" ? this.#address : { ...this.#address, key };
+    }
+}
+/**
+ * Throws when `definition` cannot read a document stored at `stored`'s version and fingerprint: a newer version than
+ * the code's, or the same version with another fingerprint (D9). A load and a retirement check alike (R15).
+ */
+export function checkReadable(stored, definition) {
+    const { name, version, fingerprint } = definition;
+    if (stored.version > version) {
+        throw new Error(`${name}: stored at version ${stored.version}, newer than the code's ${version}`);
+    }
+    if (stored.version === version && stored.fingerprint !== fingerprint) {
+        throw new Error(`${name}: stored with another schema at version ${version} (a schema changed without a bump)`);
+    }
+}
+/** What is stored after a commit's `change` was adopted. */
+export function storedAfter(change) {
+    switch (change.kind) {
+        case "retire":
+            return undefined;
+        case "create":
+            return { id: change.created.id, revision: 1, version: change.version, deltasSinceBase: 0 };
+        case "change":
+        case "held":
+            return change.stored;
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/dist/documents/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/documents/persistence.ts"],"names":[],"mappings":"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","sourcesContent":["// Persisted documents' store side (slice 6a §8, §10): a slot's address in the documents engine, what is stored of each\n// loaded document (Durable's `LoadedDocument` fields), its loads with the version and fingerprint checks and the\n// checked `migrate`, and the writes one commit stages for a changed or retired document.\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Op, Prepared } from \"../delta/index.ts\";\nimport {\n\tchangeDocument,\n\tcreateDocument,\n\ttype DocumentAddress,\n\ttype DocumentContent,\n\tfindDocument,\n\tlistDocumentKeys,\n\tloadDocument,\n\tretireDocument,\n\ttype StoredDocument,\n} from \"../store/engine.ts\";\nimport type { StagedWrite } from \"../store/step.ts\";\nimport type { ChordStore } from \"../store/store.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\nimport type { JsonObject } from \"./definition.ts\";\nimport type { AnyDefinition } from \"./slot.ts\";\n\n/** What is stored of a loaded document: its record's id and revision, its base's version, the deltas after it. */\nexport type Stored = {\n\treadonly id: number;\n\treadonly revision: number;\n\t/** The version of the stored base: below the definition's, the next change stores a base (rule 1). */\n\treadonly version: number;\n\treadonly deltasSinceBase: number;\n};\n\n/** A live document found without loading it: what is stored of it and the fingerprint it was stored with. */\nexport type FoundDocument = { readonly stored: Stored; readonly fingerprint: string };\n\n/** A loaded document: its value at the definition's version, and what is stored of it. */\nexport type Loaded = { readonly value: JsonObject; readonly stored: Stored };\n\n/** One transaction's change of one document: its prepared draft (if changed), and whether it retires it. */\nexport type DocumentChange = { readonly prepared: Prepared<JsonObject> | undefined; readonly retires: boolean };\n\n/** A run state's held ops (D8), stored before the next change's own; `base` when a held change asked for a base. */\nexport type Held = { readonly ops: readonly Op[]; readonly base: boolean };\n\n/**\n * What one commit stores of a document, in the store writes' words: a retirement (nothing stored after it), a\n * creation whose id the step assigns (`create`: `created.id` once it applied), a change of the record `stored` was\n * prepared on, or nothing yet (`held`: a deferred change of a run's state, D8, kept in memory over `stored`).\n */\nexport type StoredChange =\n\t| { readonly kind: \"retire\" }\n\t| { readonly kind: \"create\"; readonly version: number; readonly created: { id: number } }\n\t| { readonly kind: \"change\"; readonly stored: Stored }\n\t| { readonly kind: \"held\"; readonly stored: Stored; readonly withinMs: number };\n\n/**\n * The documents of one persisted name on one object: `(<object type>, namespace, name, key)`, the namespace `chord` for\n * `self.state`, `chord.jobs` and `chord.job-states` for persisted job runs (slice 6b D5).\n */\nexport class Persistence {\n\treadonly store: ChordStore;\n\treadonly #address: Omit<DocumentAddress, \"key\">;\n\n\t/** `owner` is the object's type (R2); `kind` the definition's or the job's name. */\n\tconstructor(store: ChordStore, owner: string, namespace: string, kind: string) {\n\t\tthis.store = store;\n\t\tthis.#address = { owner, namespace, kind };\n\t}\n\n\t/**\n\t * The stored document at `key`, `undefined` when absent: found and loaded with plain reads (a store error rejects\n\t * as the store's). Counted (`chord.store.loads`).\n\t */\n\tasync read(key: string, context: Context): Promise<StoredDocument | undefined> {\n\t\tconst address = this.at(key);\n\t\tconst document = await this.store.read(async (executor) => {\n\t\t\tconst record = await findDocument(executor, address);\n\t\t\treturn record === undefined ? undefined : loadDocument(executor, record);\n\t\t}, context);\n\t\tif (document !== undefined) chordMetrics(context.telemetry.metrics).counter(\"chord.store.loads\").add(1);\n\t\treturn document;\n\t}\n\n\t/**\n\t * `document` as `definition` reads it: a stored version newer than the code's, or the same version with another\n\t * fingerprint (D9), throws; an older one is migrated and the result checked once (R8). What throws here is the\n\t * code's (a failing `migrate` too, whatever it throws), never the store's.\n\t */\n\tdecode(document: StoredDocument, definition: AnyDefinition, context: Context): Loaded {\n\t\tconst { record, deltasSinceBase } = document;\n\t\tcheckReadable(record, definition);\n\t\t// The engine stores what commits gave it: JSON objects of the record's version.\n\t\tconst stored = document.value as JsonObject;\n\t\tconst value =\n\t\t\trecord.version === definition.version ? stored : definition.migrate(stored, record.version, context);\n\t\treturn {\n\t\t\tvalue,\n\t\t\tstored: { id: record.id, revision: record.revision, version: record.version, deltasSinceBase },\n\t\t};\n\t}\n\n\t/**\n\t * What is stored of the live document at `key` without loading it (a retirement's find) and the schema fingerprint\n\t * it was stored with (`checkReadable` takes both), `undefined` when absent.\n\t */\n\tasync find(key: string, context: Context): Promise<FoundDocument | undefined> {\n\t\tconst record = await this.store.read((executor) => findDocument(executor, this.at(key)), context);\n\t\tif (record === undefined) return undefined;\n\t\t// The change counter is all a retirement needs; `deltasSinceBase` is not read for one.\n\t\tconst stored = { id: record.id, revision: record.revision, version: record.version, deltasSinceBase: 0 };\n\t\treturn { stored, fingerprint: record.fingerprint };\n\t}\n\n\t/** Up to `limit` keys of live documents after `after`, in code point order. */\n\tkeys(after: string | undefined, limit: number, context: Context): Promise<string[]> {\n\t\treturn this.store.read((executor) => listDocumentKeys(executor, this.#address, after, limit), context);\n\t}\n\n\t/**\n\t * Stages one commit's writes of the document at `key` into `writes` (rule 8: serialized here, before the queue):\n\t * its retirement when `retired` is stored, then its creation, or the change of `stored` (a base when created, when\n\t * the stored version is older, or when `checkpointWhen` asks; a delta otherwise), `held` ops stored before the\n\t * change's own (D8: a held base makes it a base). Returns what the commit stores.\n\t */\n\tstage(\n\t\tkey: string,\n\t\tdefinition: AnyDefinition,\n\t\tstored: Stored | undefined,\n\t\tchange: DocumentChange,\n\t\twrites: StagedWrite[],\n\t\theld?: Held,\n\t): StoredChange {\n\t\tconst { prepared, retires } = change;\n\t\tif (retires && stored !== undefined) writes.push(retireDocument(stored.id, stored.revision));\n\t\tif (prepared === undefined) return { kind: \"retire\" };\n\t\tconst { version, fingerprint } = definition;\n\t\tif (retires || stored === undefined) {\n\t\t\tconst base = { version, fingerprint, value: prepared.value };\n\t\t\tconst created = { id: 0 };\n\t\t\tconst write = createDocument(this.at(key), base, JSON.stringify(prepared.value), (id) => {\n\t\t\t\tcreated.id = id;\n\t\t\t});\n\t\t\twrites.push(write);\n\t\t\treturn { kind: \"create\", version, created };\n\t\t}\n\t\tconst info = { deltasSinceBase: stored.deltasSinceBase };\n\t\tconst base =\n\t\t\theld?.base === true ||\n\t\t\tstored.version !== version ||\n\t\t\tdefinition.checkpointWhen(prepared.value, prepared.ops, info);\n\t\tconst ops = held === undefined ? prepared.ops : [...held.ops, ...prepared.ops];\n\t\tconst content: DocumentContent = base\n\t\t\t? { kind: \"base\", version, fingerprint, value: prepared.value }\n\t\t\t: { kind: \"delta\", version, ops };\n\t\tconst text = JSON.stringify(base ? prepared.value : ops);\n\t\twrites.push(changeDocument(stored.id, stored.revision, content, text));\n\t\tconst deltasSinceBase = base ? 0 : stored.deltasSinceBase + 1;\n\t\treturn { kind: \"change\", stored: { id: stored.id, revision: stored.revision + 1, version, deltasSinceBase } };\n\t}\n\n\t/** The address of `key`: a singleton's (`\"\"`) has no key. */\n\tat(key: string): DocumentAddress {\n\t\treturn key === \"\" ? this.#address : { ...this.#address, key };\n\t}\n}\n\n/**\n * Throws when `definition` cannot read a document stored at `stored`'s version and fingerprint: a newer version than\n * the code's, or the same version with another fingerprint (D9). A load and a retirement check alike (R15).\n */\nexport function checkReadable(\n\tstored: { readonly version: number; readonly fingerprint: string },\n\tdefinition: AnyDefinition,\n): void {\n\tconst { name, version, fingerprint } = definition;\n\tif (stored.version > version) {\n\t\tthrow new Error(`${name}: stored at version ${stored.version}, newer than the code's ${version}`);\n\t}\n\tif (stored.version === version && stored.fingerprint !== fingerprint) {\n\t\tthrow new Error(`${name}: stored with another schema at version ${version} (a schema changed without a bump)`);\n\t}\n}\n\n/** What is stored after a commit's `change` was adopted. */\nexport function storedAfter(change: StoredChange): Stored | undefined {\n\tswitch (change.kind) {\n\t\tcase \"retire\":\n\t\t\treturn undefined;\n\t\tcase \"create\":\n\t\t\treturn { id: change.created.id, revision: 1, version: change.version, deltasSinceBase: 0 };\n\t\tcase \"change\":\n\t\tcase \"held\":\n\t\t\treturn change.stored;\n\t}\n}\n"]}

package/dist/documents/residency.d.ts

@@ -0,0 +1,31 @@
+import type { Tracker } from "../delta/index.ts";
+import type { JsonObject } from "./definition.ts";
+import type { Stored } from "./persistence.ts";
+/** One keyed document in memory: its slot, its tracker and, persisted, what is stored of it. */
+export declare class Resident {
+    readonly slot: {
+        evict(resident: Resident): void;
+    };
+    readonly key: string;
+    tracker: Tracker<JsonObject>;
+    stored: Stored | undefined;
+    /** The definition version the tracker's value is at: below the slot's, it migrates on its next access. */
+    version: number;
+    constructor(slot: {
+        evict(resident: Resident): void;
+    }, key: string, tracker: Tracker<JsonObject>, stored: Stored | undefined, version: number);
+}
+/** How long an unpinned persisted keyed document stays in memory after its last read or write (slice 6a §10). */
+export declare const RETENTION_MS: number;
+/** The idle persisted keyed documents of one object, oldest first, and the one timer evicting them. */
+export declare class Residency {
+    #private;
+    constructor(onLine: (sweep: () => void) => void);
+    /** A use of an unpinned `resident`: it becomes the newest idle one (once per granule), and a sweep is scheduled. */
+    touch(resident: Resident): void;
+    /** `resident` is pinned or left memory: it is no longer idle. */
+    forget(resident: Resident): void;
+    /** The object ended: nothing is evicted any more, the timer is cleared. */
+    end(): void;
+}
+//# sourceMappingURL=residency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"residency.d.ts","sourceRoot":"","sources":["../../src/documents/residency.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,gGAAgG;AAChG,qBAAa,QAAQ;IACpB,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;KAAE,CAAC;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;IAEhB,YACC,IAAI,EAAE;QAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;KAAE,EACzC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,EAOf;CACD;AAED,iHAAiH;AACjH,eAAO,MAAM,YAAY,QAAc,CAAC;AAKxC,uGAAuG;AACvG,qBAAa,SAAS;;IAQrB,YAAY,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,EAE9C;IAED,oHAAoH;IACpH,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAQ9B;IAED,iEAAiE;IACjE,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE/B;IAED,2EAA2E;IAC3E,GAAG,IAAI,IAAI,CAKV;CAmCD"}

package/dist/documents/residency.js

@@ -0,0 +1,93 @@
+// Residency of keyed documents (slice 6a §10, rule 23): which keyed documents are in memory, and the eviction of
+// persisted ones nobody pinned and nobody read or wrote for the retention. One idle structure and one timer per
+// object, Durable's (`Session.#touchDocument`): an insertion-ordered map whose oldest entry the timer waits for, a
+// touch moving an entry to the back at most once per granule (O(1) per touch, no timer per key).
+/** One keyed document in memory: its slot, its tracker and, persisted, what is stored of it. */
+export class Resident {
+    slot;
+    key;
+    tracker;
+    stored;
+    /** The definition version the tracker's value is at: below the slot's, it migrates on its next access. */
+    version;
+    constructor(slot, key, tracker, stored, version) {
+        this.slot = slot;
+        this.key = key;
+        this.tracker = tracker;
+        this.stored = stored;
+        this.version = version;
+    }
+}
+/** How long an unpinned persisted keyed document stays in memory after its last read or write (slice 6a §10). */
+export const RETENTION_MS = 10 * 60_000;
+/** A touch moves an entry at most once per granule: a tenth of the retention, up to 1 s (Durable's rule). */
+const GRANULE_MS = Math.min(1_000, RETENTION_MS / 10);
+/** The idle persisted keyed documents of one object, oldest first, and the one timer evicting them. */
+export class Residency {
+    /** Runs a sweep on the object's line. */
+    #onLine;
+    #idle = new Map();
+    /** The pending sweep: when it is due and its timer; stays set until its job runs on the line. */
+    #sweep;
+    #ended = false;
+    constructor(onLine) {
+        this.#onLine = onLine;
+    }
+    /** A use of an unpinned `resident`: it becomes the newest idle one (once per granule), and a sweep is scheduled. */
+    touch(resident) {
+        const now = Date.now();
+        const since = this.#idle.get(resident);
+        // A hot document moves at most once per granule: it may then leave up to a granule early (a reload).
+        if (since !== undefined && now - since < GRANULE_MS)
+            return;
+        this.#idle.delete(resident);
+        this.#idle.set(resident, now);
+        if (this.#sweep === undefined)
+            this.#schedule();
+    }
+    /** `resident` is pinned or left memory: it is no longer idle. */
+    forget(resident) {
+        this.#idle.delete(resident);
+    }
+    /** The object ended: nothing is evicted any more, the timer is cleared. */
+    end() {
+        this.#ended = true;
+        this.#idle.clear();
+        clearTimeout(this.#sweep?.timer);
+        this.#sweep = undefined;
+    }
+    /** Schedules the eviction of the oldest idle document when its retention expires. */
+    #schedule() {
+        const oldest = this.#idle.values().next();
+        if (this.#ended || oldest.done === true)
+            return;
+        const at = oldest.value + RETENTION_MS;
+        const sweep = { at, timer: undefined };
+        this.#sweep = sweep;
+        // A timer firing early sweeps nothing and schedules the next one.
+        sweep.timer = setTimeout(() => this.#onLine(() => {
+            if (this.#sweep === sweep)
+                this.#sweep = undefined;
+            this.#evictExpired();
+        }), Math.max(0, at - Date.now()));
+    }
+    /**
+     * On the line: evicts the idle documents whose retention passed, oldest first, then schedules the next sweep. No
+     * load in flight needs a pin against it: cold loads run on the line too, so a sweep never runs during one, and a
+     * load installing an unpinned key touches it (it is then the newest idle one).
+     */
+    #evictExpired() {
+        if (this.#ended)
+            return;
+        const expired = Date.now() - RETENTION_MS;
+        for (const [resident, since] of this.#idle) {
+            if (since > expired)
+                break;
+            this.#idle.delete(resident);
+            resident.slot.evict(resident);
+        }
+        if (this.#sweep === undefined)
+            this.#schedule();
+    }
+}
+//# sourceMappingURL=residency.js.map

package/dist/documents/residency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"residency.js","sourceRoot":"","sources":["../../src/documents/residency.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,gHAAgH;AAChH,mHAAmH;AACnH,iGAAiG;AAMjG,gGAAgG;AAChG,MAAM,OAAO,QAAQ;IACX,IAAI,CAAsC;IAC1C,GAAG,CAAS;IACrB,OAAO,CAAsB;IAC7B,MAAM,CAAqB;IAC3B,0GAA0G;IAC1G,OAAO,CAAS;IAEhB,YACC,IAAyC,EACzC,GAAW,EACX,OAA4B,EAC5B,MAA0B,EAC1B,OAAe;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED,iHAAiH;AACjH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,MAAM,CAAC;AAExC,6GAA6G;AAC7G,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,EAAE,CAAC,CAAC;AAEtD,uGAAuG;AACvG,MAAM,OAAO,SAAS;IACrB,yCAAyC;IAChC,OAAO,CAA8B;IACrC,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,iGAAiG;IACjG,MAAM,CAAwF;IAC9F,MAAM,GAAG,KAAK,CAAC;IAEf,YAAY,MAAmC;QAC9C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,oHAAoH;IACpH,KAAK,CAAC,QAAkB;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvC,qGAAqG;QACrG,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,GAAG,KAAK,GAAG,UAAU;YAAE,OAAO;QAC5D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;IACjD,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,QAAkB;QACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAED,2EAA2E;IAC3E,GAAG;QACF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,qFAAqF;IACrF,SAAS;QACR,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QAChD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,GAAG,YAAY,CAAC;QACvC,MAAM,KAAK,GAA8E,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAClH,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,kEAAkE;QAClE,KAAK,CAAC,KAAK,GAAG,UAAU,CACvB,GAAG,EAAE,CACJ,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YACjB,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;gBAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACnD,IAAI,CAAC,aAAa,EAAE,CAAC;QACtB,CAAC,CAAC,EACH,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAC5B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,aAAa;QACZ,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC;QAC1C,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5C,IAAI,KAAK,GAAG,OAAO;gBAAE,MAAM;YAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;IACjD,CAAC;CACD","sourcesContent":["// Residency of keyed documents (slice 6a §10, rule 23): which keyed documents are in memory, and the eviction of\n// persisted ones nobody pinned and nobody read or wrote for the retention. One idle structure and one timer per\n// object, Durable's (`Session.#touchDocument`): an insertion-ordered map whose oldest entry the timer waits for, a\n// touch moving an entry to the back at most once per granule (O(1) per touch, no timer per key).\n\nimport type { Tracker } from \"../delta/index.ts\";\nimport type { JsonObject } from \"./definition.ts\";\nimport type { Stored } from \"./persistence.ts\";\n\n/** One keyed document in memory: its slot, its tracker and, persisted, what is stored of it. */\nexport class Resident {\n\treadonly slot: { evict(resident: Resident): void };\n\treadonly key: string;\n\ttracker: Tracker<JsonObject>;\n\tstored: Stored | undefined;\n\t/** The definition version the tracker's value is at: below the slot's, it migrates on its next access. */\n\tversion: number;\n\n\tconstructor(\n\t\tslot: { evict(resident: Resident): void },\n\t\tkey: string,\n\t\ttracker: Tracker<JsonObject>,\n\t\tstored: Stored | undefined,\n\t\tversion: number,\n\t) {\n\t\tthis.slot = slot;\n\t\tthis.key = key;\n\t\tthis.tracker = tracker;\n\t\tthis.stored = stored;\n\t\tthis.version = version;\n\t}\n}\n\n/** How long an unpinned persisted keyed document stays in memory after its last read or write (slice 6a §10). */\nexport const RETENTION_MS = 10 * 60_000;\n\n/** A touch moves an entry at most once per granule: a tenth of the retention, up to 1 s (Durable's rule). */\nconst GRANULE_MS = Math.min(1_000, RETENTION_MS / 10);\n\n/** The idle persisted keyed documents of one object, oldest first, and the one timer evicting them. */\nexport class Residency {\n\t/** Runs a sweep on the object's line. */\n\treadonly #onLine: (sweep: () => void) => void;\n\treadonly #idle = new Map<Resident, number>();\n\t/** The pending sweep: when it is due and its timer; stays set until its job runs on the line. */\n\t#sweep: { readonly at: number; timer: ReturnType<typeof setTimeout> | undefined } | undefined;\n\t#ended = false;\n\n\tconstructor(onLine: (sweep: () => void) => void) {\n\t\tthis.#onLine = onLine;\n\t}\n\n\t/** A use of an unpinned `resident`: it becomes the newest idle one (once per granule), and a sweep is scheduled. */\n\ttouch(resident: Resident): void {\n\t\tconst now = Date.now();\n\t\tconst since = this.#idle.get(resident);\n\t\t// A hot document moves at most once per granule: it may then leave up to a granule early (a reload).\n\t\tif (since !== undefined && now - since < GRANULE_MS) return;\n\t\tthis.#idle.delete(resident);\n\t\tthis.#idle.set(resident, now);\n\t\tif (this.#sweep === undefined) this.#schedule();\n\t}\n\n\t/** `resident` is pinned or left memory: it is no longer idle. */\n\tforget(resident: Resident): void {\n\t\tthis.#idle.delete(resident);\n\t}\n\n\t/** The object ended: nothing is evicted any more, the timer is cleared. */\n\tend(): void {\n\t\tthis.#ended = true;\n\t\tthis.#idle.clear();\n\t\tclearTimeout(this.#sweep?.timer);\n\t\tthis.#sweep = undefined;\n\t}\n\n\t/** Schedules the eviction of the oldest idle document when its retention expires. */\n\t#schedule(): void {\n\t\tconst oldest = this.#idle.values().next();\n\t\tif (this.#ended || oldest.done === true) return;\n\t\tconst at = oldest.value + RETENTION_MS;\n\t\tconst sweep: { readonly at: number; timer: ReturnType<typeof setTimeout> | undefined } = { at, timer: undefined };\n\t\tthis.#sweep = sweep;\n\t\t// A timer firing early sweeps nothing and schedules the next one.\n\t\tsweep.timer = setTimeout(\n\t\t\t() =>\n\t\t\t\tthis.#onLine(() => {\n\t\t\t\t\tif (this.#sweep === sweep) this.#sweep = undefined;\n\t\t\t\t\tthis.#evictExpired();\n\t\t\t\t}),\n\t\t\tMath.max(0, at - Date.now()),\n\t\t);\n\t}\n\n\t/**\n\t * On the line: evicts the idle documents whose retention passed, oldest first, then schedules the next sweep. No\n\t * load in flight needs a pin against it: cold loads run on the line too, so a sweep never runs during one, and a\n\t * load installing an unpinned key touches it (it is then the newest idle one).\n\t */\n\t#evictExpired(): void {\n\t\tif (this.#ended) return;\n\t\tconst expired = Date.now() - RETENTION_MS;\n\t\tfor (const [resident, since] of this.#idle) {\n\t\t\tif (since > expired) break;\n\t\t\tthis.#idle.delete(resident);\n\t\t\tresident.slot.evict(resident);\n\t\t}\n\t\tif (this.#sweep === undefined) this.#schedule();\n\t}\n}\n"]}

package/dist/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/documents/slot.d.ts.map

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

package/dist/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 { ChordError } from "../data/index.js";
+import { track } from "../delta/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