@earendil-works/chord 1.3.0 → 1.5.0

package/dist/next/documents/handles.js

@@ -0,0 +1,66 @@
+// Document handles (slice 6a §1.2): what `self.state` returns, one per attempt and definition, a thin view of its
+// object's slot bound to the attempt's seal token and the definition's version.
+/**
+ * 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 class Singleton {
+    slot;
+    token;
+    /** The version of the definition it was declared with: the slot refuses it once its values are newer (R15). */
+    version;
+    constructor(slot, token, version) {
+        this.slot = slot;
+        this.token = token;
+        this.version = version;
+    }
+    get value() {
+        this.slot.definition.assertVersion(this.version);
+        return this.slot.value;
+    }
+    async watch(context) {
+        this.slot.definition.assertVersion(this.version);
+        // The slot's values are this handle's documents.
+        return this.slot.openWatch(context);
+    }
+    change(fn, context) {
+        return this.slot.owner.tx(async (tx) => fn(await tx.draft(this)), this.token, context);
+    }
+    retire(context) {
+        return this.slot.owner.tx((tx) => tx.retire(this), this.token, context);
+    }
+}
+/** A keyed handle: reads go to the slot; `change`, `retire` and cold reads take the line under the attempt's token. */
+export class Keyed {
+    slot;
+    token;
+    /** As `Singleton.version`. */
+    version;
+    #declarer;
+    constructor(slot, token, version, declarer) {
+        this.slot = slot;
+        this.token = token;
+        this.version = version;
+        this.#declarer = declarer;
+    }
+    get(key, context) {
+        return this.slot.get(key, this, context);
+    }
+    keys(context) {
+        return this.slot.keys(this, context);
+    }
+    watch(key, context) {
+        return this.slot.watch(key, this, context);
+    }
+    at(key) {
+        // The source's values are this slot's documents.
+        return this.#declarer.at(this.slot, key);
+    }
+    change(key, fn, context) {
+        return this.slot.owner.tx(async (tx) => fn(await tx.draft(this, key)), this.token, context);
+    }
+    retire(key, context) {
+        return this.slot.owner.tx((tx) => tx.retire(this, key), this.token, context);
+    }
+}
+//# sourceMappingURL=handles.js.map

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

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

@@ -0,0 +1,4 @@
+export { type CommitPersistence, defineState, type JsonObject, type StateDefinition } from "./definition.ts";
+export type { HandleOf, KeyedHandle, SingletonHandle } from "./handles.ts";
+export type { Tx } from "./transaction.ts";
+//# sourceMappingURL=index.d.ts.map

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

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

@@ -0,0 +1,3 @@
+// Documents for apps: definitions, handles and transactions.
+export { defineState } from "./definition.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/next/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/next/documents/internal.d.ts

@@ -0,0 +1,9 @@
+export { AddressSource } from "./address-source.ts";
+export { Documents, type DocumentsOwner } 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/next/documents/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../../src/next/documents/internal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,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/next/documents/internal.js

@@ -0,0 +1,9 @@
+// Documents for Chord's layers: an object's documents and slots, the handles' classes, the seal token, transactions.
+export { AddressSource } from "./address-source.js";
+export { Documents } from "./documents.js";
+export { SealToken } from "./fence.js";
+export { Keyed, Singleton } from "./handles.js";
+export { KeySource } from "./keyed-slot.js";
+export { Persistence, storedAfter, } from "./persistence.js";
+export { SlotDefinition } from "./slot.js";
+//# sourceMappingURL=internal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../../src/next/documents/internal.ts"],"names":[],"mappings":"AAAA,qHAAqH;AAErH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAuB,MAAM,gBAAgB,CAAC;AAChE,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 } 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/next/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 { Watch } from "../../watch.ts";
+import type { StagedWrite } from "../store/step.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/next/documents/keyed-slot.d.ts.map

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

package/dist/next/documents/keyed-slot.js

@@ -0,0 +1,395 @@
+// Keyed slots (slice 6a §1.2, §4, §10, §11): the documents of one keyed name on one object, by key. In memory, every
+// present document stays; persisted, a document is loaded on demand (a cold read is a job on the object's line, one
+// load in flight per key, shared) and leaves memory when unpinned and idle for the retention (`residency.ts`). A key
+// read through `at(key)` or a watch has its own source, which exists while the key is pinned.
+import { awaitWithContext } from "../../context/index.js";
+import { track } from "../../delta/index.js";
+import { ChordError } from "../data/index.js";
+import { asChordError } from "../data/internal.js";
+import { compareText, storedText } from "../store/text.js";
+import { AddressSource } from "./address-source.js";
+import { storedAfter, } from "./persistence.js";
+import { Resident } from "./residency.js";
+import { SlotDefinition } from "./slot.js";
+/** The keys `keys(ctx)` reads per page from the store. */
+const KEYS_PAGE = 100;
+/** A keyed slot: one resident per document in memory, one source per pinned key. */
+export class KeyedSlot {
+    owner;
+    definition;
+    persisted;
+    #persistence;
+    #residents = new Map();
+    /** The sources of pinned keys: a key is pinned while it has one. */
+    #sources = new Map();
+    /** Cold loads in flight, by key: shared by every reader of the key. */
+    #loads = new Map();
+    /** Names a refused key (the slot's name is the same at every version): made once, not per key check. */
+    #keyWhat;
+    constructor(owner, definition, persistence) {
+        this.owner = owner;
+        this.definition = new SlotDefinition(definition);
+        this.#keyWhat = `${definition.name}: key`;
+        this.#persistence = persistence;
+        this.persisted = persistence === undefined ? undefined : this;
+    }
+    get persistence() {
+        // Only reached through `persisted`, which a persisted slot alone has.
+        return this.#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, access, context) {
+        // Not `async`: `#get` is the one async layer; a refused key still reaches the caller as a rejection.
+        try {
+            return this.#get(this.key(raw), access, context);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    /** `get` of a key that went through `key` already. */
+    async #get(key, access, context) {
+        this.owner.assertLive();
+        this.definition.assertVersion(access.version);
+        const resident = this.#resident(key);
+        if (resident !== undefined) {
+            this.#touch(resident);
+            return resident.tracker.value;
+        }
+        if (this.#persistence === undefined)
+            return undefined;
+        await this.#loadShared(key, access.token, context);
+        return this.#residents.get(key)?.tracker.value;
+    }
+    /** The present keys in code point order: in memory, the residents; persisted, the store's, a page per line job. */
+    async *keys(access, context) {
+        this.owner.assertLive();
+        this.definition.assertVersion(access.version);
+        const persistence = this.#persistence;
+        if (persistence === undefined) {
+            yield* [...this.#residents.keys()].sort(compareText);
+            return;
+        }
+        let after;
+        for (;;) {
+            const page = await this.owner.onLine(() => persistence.keys(after, KEYS_PAGE, context), access.token);
+            yield* page;
+            if (page.length < KEYS_PAGE)
+                return;
+            after = page.at(-1);
+        }
+    }
+    /**
+     * 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.
+     */
+    async watch(raw, access, context) {
+        const key = this.key(raw);
+        if ((await this.#get(key, access, context)) === undefined)
+            return undefined;
+        const release = this.pin(key, context);
+        // Retired between the load and now: absent.
+        if (!this.#residents.has(key)) {
+            release();
+            return undefined;
+        }
+        let watch;
+        try {
+            // The source's values are this slot's documents.
+            watch = this.#sources.get(key).openWatch(context);
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+        void watch.closed.then(release);
+        return watch;
+    }
+    /**
+     * 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, context) {
+        const key = this.key(raw);
+        let source = this.#sources.get(key);
+        if (source === undefined) {
+            const ready = this.#persistence === undefined || this.#residents.has(key);
+            source = new KeySource(this, key, this.definition.current.initial(context), ready);
+            this.#sources.set(key, source);
+        }
+        source.pins++;
+        const resident = this.#residents.get(key);
+        if (resident !== undefined)
+            this.owner.residency.forget(resident);
+        const pinned = source;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (--pinned.pins > 0 || this.#sources.get(key) !== pinned)
+                return;
+            this.#sources.delete(key);
+            const idle = this.#residents.get(key);
+            if (idle !== undefined)
+                this.#touch(idle);
+        };
+    }
+    /** Loads pinned `key` on the line unless it was loaded since it was pinned (a consumer's `at(key)`, slice 6a §12). */
+    async ensure(raw, context) {
+        const key = this.key(raw);
+        if (this.#sources.get(key)?.ready !== false)
+            return;
+        await this.owner.onLine(() => this.load(key, context));
+    }
+    /** The source of pinned `key`. */
+    source(key) {
+        return this.#sources.get(this.key(key));
+    }
+    /**
+     * `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) {
+        return storedText(key, this.#keyWhat);
+    }
+    /** Loads every pinned key not loaded since it was pinned (activation, holding the line). */
+    async loadDeclared(context) {
+        for (const [key, source] of this.#sources)
+            if (!source.ready)
+                await this.load(key, context);
+    }
+    /**
+     * 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.
+     */
+    async load(key, context, token) {
+        if (this.#residents.has(key))
+            return;
+        // A store error rejects as the store's (`storage_failed`, `aborted`).
+        const document = await this.persistence.read(key, context);
+        // The transaction was cut meanwhile: what it read may be stale already.
+        if (token?.sealed === true)
+            return;
+        let loaded;
+        try {
+            loaded =
+                document === undefined ? undefined : this.persistence.decode(document, this.definition.current, context);
+        }
+        catch (error) {
+            // What the code cannot read (a failing `migrate`, whatever it throws) fails the owner.
+            const failure = asChordError(error, this.owner.label);
+            this.owner.fail(failure);
+            throw failure;
+        }
+        if (loaded !== undefined && !this.#residents.has(key)) {
+            const resident = new Resident(this, key, track(loaded.value), loaded.stored, this.definition.current.version);
+            this.#residents.set(key, resident);
+            this.#touch(resident);
+        }
+        const source = this.#sources.get(key);
+        if (source !== undefined)
+            source.ready = true;
+    }
+    cold(key) {
+        return this.#persistence !== undefined && !this.#residents.has(key);
+    }
+    stored(key) {
+        return this.#residents.get(key)?.stored;
+    }
+    stage(key, change, was, writes) {
+        return this.persistence.stage(key, this.definition.current, was, change, writes);
+    }
+    /**
+     * 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, context) {
+        const from = this.definition.hydrated;
+        this.definition.hydrate(definition);
+        if (from === undefined || from.version === definition.version)
+            return;
+        const pinned = [...this.#sources.keys()].flatMap((key) => this.#residents.get(key) ?? []);
+        const migrated = pinned.map((resident) => [resident, this.#migrated(resident, context)]);
+        for (const [resident, tracker] of migrated) {
+            resident.tracker = tracker;
+            resident.version = definition.version;
+        }
+        this.owner.batch.commit(() => {
+            for (const source of this.#sources.values())
+                source.retake(definition.initial(context));
+        }, context);
+    }
+    current(key) {
+        return this.#resident(key)?.tracker;
+    }
+    /** The value a draft of an absent document starts from: a fresh `initial()`. */
+    initial(context) {
+        return this.definition.current.initial(context);
+    }
+    adopt(key, tracker, prepared, change) {
+        const stored = change === undefined ? undefined : storedAfter(change);
+        const source = this.#sources.get(key);
+        const before = source?.peek();
+        tracker.adopt(prepared);
+        let resident = this.#residents.get(key);
+        const { version } = this.definition.current;
+        if (resident === undefined) {
+            resident = new Resident(this, key, tracker, stored, version);
+            this.#residents.set(key, resident);
+        }
+        else {
+            resident.tracker = tracker;
+            resident.stored = stored;
+            resident.version = version;
+        }
+        if (source === undefined)
+            this.#touch(resident);
+        else
+            source.written(before, prepared);
+    }
+    /** Retires the document at `key` (inside the batch): out of memory, its source reads `initial()` with the flag. */
+    retire(key) {
+        const resident = this.#residents.get(key);
+        if (resident !== undefined) {
+            this.#residents.delete(key);
+            this.owner.residency.forget(resident);
+        }
+        this.#sources.get(key)?.retire();
+    }
+    /** The sweep found `resident` idle past the retention: it leaves memory. */
+    evict(resident) {
+        if (this.#residents.get(resident.key) === resident)
+            this.#residents.delete(resident.key);
+    }
+    /** Its object ended or no attempt declares it any more: the documents go and the keys' watches end. */
+    drop() {
+        for (const resident of this.#residents.values())
+            this.owner.residency.forget(resident);
+        this.#residents.clear();
+        for (const source of this.#sources.values())
+            source.end();
+        this.#sources.clear();
+    }
+    /**
+     * A cold persisted key's load, one in flight per key, on the line under the owner's context (rule 11). The load is
+     * every waiter's: when it takes the line, a waiter whose handle was sealed meanwhile (its attempt failed live, the
+     * object still open) is refused `released`, and with no other waiter the load does not run (rule 4).
+     */
+    async #loadShared(key, token, context) {
+        // Also when a load is in flight: a sealed handle's cold read is refused (rule 4).
+        this.owner.assertAdmitted(token);
+        let load = this.#loads.get(key);
+        if (load === undefined)
+            load = this.#startLoad(key);
+        load.tokens.add(token);
+        await awaitWithContext(load.done, context);
+        if (load.refused?.has(token))
+            throw this.owner.released();
+    }
+    /** Starts the shared load of `key`; it leaves `#loads` when it settles. */
+    #startLoad(key) {
+        const tokens = new Set();
+        const load = {
+            tokens,
+            refused: undefined,
+            // The job runs once the line is taken, after `load` is assigned.
+            done: this.owner.onLine(async () => {
+                const refused = new Set([...tokens].filter(({ sealed }) => sealed));
+                load.refused = refused;
+                if (refused.size === tokens.size)
+                    throw this.owner.released();
+                await this.load(key, this.owner.context);
+            }),
+        };
+        this.#loads.set(key, load);
+        const settled = () => {
+            this.#loads.delete(key);
+        };
+        load.done.then(settled, settled);
+        return load;
+    }
+    /** The resident at `key`, migrated to the slot's version first when it is older (migration on access). */
+    #resident(key) {
+        const resident = this.#residents.get(key);
+        if (resident === undefined || resident.version === this.definition.current.version)
+            return resident;
+        const tracker = this.#migrated(resident, this.owner.context);
+        resident.tracker = tracker;
+        resident.version = this.definition.current.version;
+        return resident;
+    }
+    /**
+     * `resident`'s value migrated from its version to the slot's (checked, R8). A throwing `migrate` fails the live
+     * owner `broken` (slice 6a §1.4) and throws the failure (an activation fails with it).
+     */
+    #migrated(resident, context) {
+        try {
+            return track(this.definition.current.migrate(resident.tracker.value, resident.version, context));
+        }
+        catch (error) {
+            const failure = asChordError(error, this.owner.label);
+            this.owner.fail(failure);
+            throw failure;
+        }
+    }
+    /** A use of `resident` while unpinned: persisted, it is idle from now (Durable's granule rule). */
+    #touch(resident) {
+        if (this.#persistence !== undefined && !this.#sources.has(resident.key))
+            this.owner.residency.touch(resident);
+    }
+}
+/**
+ * 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 class KeySource extends AddressSource {
+    #slot;
+    key;
+    /** Its pins: at 0 the slot forgets it. */
+    pins = 0;
+    /** Whether the key was loaded since it was pinned (always, in memory): its value is known. */
+    ready;
+    #initial;
+    constructor(slot, key, initial, ready) {
+        super(slot.owner.batch);
+        this.#slot = slot;
+        this.key = key;
+        this.#initial = initial;
+        this.ready = ready;
+    }
+    get value() {
+        this.#slot.owner.assertLive();
+        if (!this.ready) {
+            const message = `${this.#slot.definition.current.name}(${this.key}): read before it was loaded`;
+            throw new ChordError({ code: "not_ready", message });
+        }
+        return this.peek();
+    }
+    /** The value without the checks (inside its slot's commits). */
+    peek() {
+        return this.#slot.current(this.key)?.value ?? this.#initial;
+    }
+    /** The document was retired: `initial()` from now, with the flag. */
+    retire() {
+        this.retired(this.#initial);
+    }
+    /** A new definition took over (inside a batch): `initial()` again, the value as a root replacement. */
+    retake(initial) {
+        this.#initial = initial;
+        if (this.ready)
+            this.replaced();
+    }
+    /** Its slot was dropped: the watches end. */
+    end() {
+        this.endWatches();
+    }
+}
+//# sourceMappingURL=keyed-slot.js.map