@earendil-works/pi-durable 1.3.0 → 1.5.0

package/dist/session/conversation-tails.d.ts

@@ -0,0 +1,33 @@
+import type { ConversationId, EntryId, EntryRecord, StorageWrite } from "../types.ts";
+/** An entry that carries a `head`: the marker of a context range. */
+export type HeadMarker = EntryRecord & {
+    readonly head: EntryId;
+};
+/**
+ * The newest entry ID and newest head marker per conversation, for the Session that owns its Storage: every entry is
+ * written by one of its commits, so `apply` keeps both current, and a value read from Storage stays valid until the
+ * next entry of that conversation. Read only on the Session line after touching the conversation's appends, so no
+ * commit that appends to it is unpublished and a value read from Storage can be kept. The newest entry visible from a conversation is its own newest, or for a fork without entries
+ * of its own the parent's entry at the fork point: IDs grow, so a conversation's own new entry is always the newest.
+ * Each map is bounded by a count, the least recently used conversation leaving first. Kept markers are frozen: entry
+ * records are immutable (`Tx.appendEntry()`).
+ */
+export declare class ConversationTails {
+    #private;
+    /** The newest entry ID visible from `conversationId`, read with `read` when not known. */
+    latest(conversationId: ConversationId, read: () => Promise<EntryId | undefined>): Promise<EntryId | undefined>;
+    /**
+     * The newest visible head marker at or before `atOrBefore` (any when `undefined`), read with `read` when not known.
+     * The newest marker answers every cutoff at or after it, and no marker answers every cutoff.
+     */
+    marker(conversationId: ConversationId, atOrBefore: EntryId | undefined, read: () => Promise<HeadMarker | undefined>): Promise<HeadMarker | undefined>;
+    /** The newest entry ID of `conversationId` if known, without reading: `null` for none, `undefined` when unknown. */
+    peek(conversationId: ConversationId): EntryId | null | undefined;
+    /** At a commit's publication: apply a durable batch. */
+    apply(writes: readonly StorageWrite[]): void;
+    /** How many conversations have their newest entry kept, for tests that bound memory. */
+    get size(): number;
+    /** How many conversations have their newest head marker kept, for tests that bound memory. */
+    get markers(): number;
+}
+//# sourceMappingURL=conversation-tails.d.ts.map

package/dist/session/conversation-tails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-tails.d.ts","sourceRoot":"","sources":["../../src/session/conversation-tails.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtF,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAQlE;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;;IAM7B,0FAA0F;IACpF,MAAM,CACX,cAAc,EAAE,cAAc,EAC9B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,GACtC,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAM9B;IAED;;;OAGG;IACG,MAAM,CACX,cAAc,EAAE,cAAc,EAC9B,UAAU,EAAE,OAAO,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,GACzC,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAWjC;IAED,oHAAoH;IACpH,IAAI,CAAC,cAAc,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAE/D;IAED,wDAAwD;IACxD,KAAK,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAe3C;IAED,wFAAwF;IACxF,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,8FAA8F;IAC9F,IAAI,OAAO,IAAI,MAAM,CAEpB;CACD"}

package/dist/session/conversation-tails.js

@@ -0,0 +1,101 @@
+/** Conversations whose newest entry ID is kept: IDs only, so many. */
+const LATEST_CAPACITY = 4096;
+/** Conversations whose newest head marker is kept: whole entries (a compaction summary is one), so fewer. */
+const MARKER_CAPACITY = 256;
+/**
+ * The newest entry ID and newest head marker per conversation, for the Session that owns its Storage: every entry is
+ * written by one of its commits, so `apply` keeps both current, and a value read from Storage stays valid until the
+ * next entry of that conversation. Read only on the Session line after touching the conversation's appends, so no
+ * commit that appends to it is unpublished and a value read from Storage can be kept. The newest entry visible from a conversation is its own newest, or for a fork without entries
+ * of its own the parent's entry at the fork point: IDs grow, so a conversation's own new entry is always the newest.
+ * Each map is bounded by a count, the least recently used conversation leaving first. Kept markers are frozen: entry
+ * records are immutable (`Tx.appendEntry()`).
+ */
+export class ConversationTails {
+    /** Newest entry ID per conversation, `null` for none. */
+    #latest = new Map();
+    /** Newest head marker per conversation, `null` for none. */
+    #markers = new Map();
+    /** The newest entry ID visible from `conversationId`, read with `read` when not known. */
+    async latest(conversationId, read) {
+        const known = use(this.#latest, conversationId);
+        if (known !== undefined)
+            return known ?? undefined;
+        const latest = await read();
+        put(this.#latest, conversationId, latest ?? null, LATEST_CAPACITY);
+        return latest;
+    }
+    /**
+     * The newest visible head marker at or before `atOrBefore` (any when `undefined`), read with `read` when not known.
+     * The newest marker answers every cutoff at or after it, and no marker answers every cutoff.
+     */
+    async marker(conversationId, atOrBefore, read) {
+        const marker = use(this.#markers, conversationId);
+        if (marker === null)
+            return undefined;
+        if (marker !== undefined && (atOrBefore === undefined || atOrBefore >= marker.id))
+            return marker;
+        const latest = this.#latest.get(conversationId);
+        const found = await read();
+        // Only a read that no newer entry can change: no cutoff, or one at or after the newest entry.
+        if (atOrBefore === undefined || (latest !== undefined && (latest ?? 0) <= atOrBefore)) {
+            put(this.#markers, conversationId, found === undefined ? null : freeze(found), MARKER_CAPACITY);
+        }
+        return found;
+    }
+    /** The newest entry ID of `conversationId` if known, without reading: `null` for none, `undefined` when unknown. */
+    peek(conversationId) {
+        return this.#latest.get(conversationId);
+    }
+    /** At a commit's publication: apply a durable batch. */
+    apply(writes) {
+        for (const write of writes) {
+            if (write.type === "conversation") {
+                // A new root conversation sees no entries; a fork sees its parent's up to the fork point.
+                if (write.value.parent !== undefined)
+                    continue;
+                put(this.#latest, write.value.id, null, LATEST_CAPACITY);
+                put(this.#markers, write.value.id, null, MARKER_CAPACITY);
+            }
+            else if (write.type === "entry") {
+                const entry = write.value;
+                put(this.#latest, entry.conversationId, entry.id, LATEST_CAPACITY);
+                if (entry.head !== undefined) {
+                    put(this.#markers, entry.conversationId, freeze(entry), MARKER_CAPACITY);
+                }
+            }
+        }
+    }
+    /** How many conversations have their newest entry kept, for tests that bound memory. */
+    get size() {
+        return this.#latest.size;
+    }
+    /** How many conversations have their newest head marker kept, for tests that bound memory. */
+    get markers() {
+        return this.#markers.size;
+    }
+}
+/** `map`'s value for `key`, made the most recently used. */
+function use(map, key) {
+    const value = map.get(key);
+    if (value === undefined)
+        return undefined;
+    map.delete(key);
+    map.set(key, value);
+    return value;
+}
+/** Set `key` as the most recently used, dropping the least recently used beyond `capacity`. */
+function put(map, key, value, capacity) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > capacity)
+        map.delete(map.keys().next().value);
+}
+function freeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        freeze(child);
+    return Object.freeze(value);
+}
+//# sourceMappingURL=conversation-tails.js.map

package/dist/session/conversation-tails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-tails.js","sourceRoot":"","sources":["../../src/session/conversation-tails.ts"],"names":[],"mappings":"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","sourcesContent":["// The newest entry and newest head marker of each recently used conversation, kept current from the Session's commits.\nimport type { ConversationId, EntryId, EntryRecord, StorageWrite } from \"../types.ts\";\n\n/** An entry that carries a `head`: the marker of a context range. */\nexport type HeadMarker = EntryRecord & { readonly head: EntryId };\n\n/** Conversations whose newest entry ID is kept: IDs only, so many. */\nconst LATEST_CAPACITY = 4096;\n\n/** Conversations whose newest head marker is kept: whole entries (a compaction summary is one), so fewer. */\nconst MARKER_CAPACITY = 256;\n\n/**\n * The newest entry ID and newest head marker per conversation, for the Session that owns its Storage: every entry is\n * written by one of its commits, so `apply` keeps both current, and a value read from Storage stays valid until the\n * next entry of that conversation. Read only on the Session line after touching the conversation's appends, so no\n * commit that appends to it is unpublished and a value read from Storage can be kept. The newest entry visible from a conversation is its own newest, or for a fork without entries\n * of its own the parent's entry at the fork point: IDs grow, so a conversation's own new entry is always the newest.\n * Each map is bounded by a count, the least recently used conversation leaving first. Kept markers are frozen: entry\n * records are immutable (`Tx.appendEntry()`).\n */\nexport class ConversationTails {\n\t/** Newest entry ID per conversation, `null` for none. */\n\treadonly #latest = new Map<ConversationId, EntryId | null>();\n\t/** Newest head marker per conversation, `null` for none. */\n\treadonly #markers = new Map<ConversationId, HeadMarker | null>();\n\n\t/** The newest entry ID visible from `conversationId`, read with `read` when not known. */\n\tasync latest(\n\t\tconversationId: ConversationId,\n\t\tread: () => Promise<EntryId | undefined>,\n\t): Promise<EntryId | undefined> {\n\t\tconst known = use(this.#latest, conversationId);\n\t\tif (known !== undefined) return known ?? undefined;\n\t\tconst latest = await read();\n\t\tput(this.#latest, conversationId, latest ?? null, LATEST_CAPACITY);\n\t\treturn latest;\n\t}\n\n\t/**\n\t * The newest visible head marker at or before `atOrBefore` (any when `undefined`), read with `read` when not known.\n\t * The newest marker answers every cutoff at or after it, and no marker answers every cutoff.\n\t */\n\tasync marker(\n\t\tconversationId: ConversationId,\n\t\tatOrBefore: EntryId | undefined,\n\t\tread: () => Promise<HeadMarker | undefined>,\n\t): Promise<HeadMarker | undefined> {\n\t\tconst marker = use(this.#markers, conversationId);\n\t\tif (marker === null) return undefined;\n\t\tif (marker !== undefined && (atOrBefore === undefined || atOrBefore >= marker.id)) return marker;\n\t\tconst latest = this.#latest.get(conversationId);\n\t\tconst found = await read();\n\t\t// Only a read that no newer entry can change: no cutoff, or one at or after the newest entry.\n\t\tif (atOrBefore === undefined || (latest !== undefined && (latest ?? 0) <= atOrBefore)) {\n\t\t\tput(this.#markers, conversationId, found === undefined ? null : freeze(found), MARKER_CAPACITY);\n\t\t}\n\t\treturn found;\n\t}\n\n\t/** The newest entry ID of `conversationId` if known, without reading: `null` for none, `undefined` when unknown. */\n\tpeek(conversationId: ConversationId): EntryId | null | undefined {\n\t\treturn this.#latest.get(conversationId);\n\t}\n\n\t/** At a commit's publication: apply a durable batch. */\n\tapply(writes: readonly StorageWrite[]): void {\n\t\tfor (const write of writes) {\n\t\t\tif (write.type === \"conversation\") {\n\t\t\t\t// A new root conversation sees no entries; a fork sees its parent's up to the fork point.\n\t\t\t\tif (write.value.parent !== undefined) continue;\n\t\t\t\tput(this.#latest, write.value.id, null, LATEST_CAPACITY);\n\t\t\t\tput(this.#markers, write.value.id, null, MARKER_CAPACITY);\n\t\t\t} else if (write.type === \"entry\") {\n\t\t\t\tconst entry = write.value;\n\t\t\t\tput(this.#latest, entry.conversationId, entry.id, LATEST_CAPACITY);\n\t\t\t\tif (entry.head !== undefined) {\n\t\t\t\t\tput(this.#markers, entry.conversationId, freeze(entry as HeadMarker), MARKER_CAPACITY);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t/** How many conversations have their newest entry kept, for tests that bound memory. */\n\tget size(): number {\n\t\treturn this.#latest.size;\n\t}\n\n\t/** How many conversations have their newest head marker kept, for tests that bound memory. */\n\tget markers(): number {\n\t\treturn this.#markers.size;\n\t}\n}\n\n/** `map`'s value for `key`, made the most recently used. */\nfunction use<K, V>(map: Map<K, V>, key: K): V | undefined {\n\tconst value = map.get(key);\n\tif (value === undefined) return undefined;\n\tmap.delete(key);\n\tmap.set(key, value);\n\treturn value;\n}\n\n/** Set `key` as the most recently used, dropping the least recently used beyond `capacity`. */\nfunction put<K, V>(map: Map<K, V>, key: K, value: V, capacity: number): void {\n\tmap.delete(key);\n\tmap.set(key, value);\n\tif (map.size > capacity) map.delete(map.keys().next().value!);\n}\n\nfunction freeze<T>(value: T): T {\n\tif (value === null || typeof value !== \"object\" || Object.isFrozen(value)) return value;\n\tfor (const child of Object.values(value)) freeze(child);\n\treturn Object.freeze(value);\n}\n"]}

package/dist/session/keys.d.ts

@@ -0,0 +1,68 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import type { CommitResult, ConversationId, ConversationQuery, ConversationRecord, Cursor, DocumentAddress, DocumentId, DocumentPoint, DocumentQuery, DocumentRecord, EntryId, EntryQuery, EntryRecord, Id, Page, Seq, Storage, StorageWrite, StoredDocument, SubmissionId, SubmissionQuery, SubmissionRecord, TaskId, TaskQuery, TaskRecord } from "../types.ts";
+type StoredEntry = {
+    readonly entry: EntryRecord;
+    readonly commitSeq: Seq;
+};
+/** A task record. */
+export declare function taskKey(id: TaskId): string;
+/** A conversation record. */
+export declare function conversationKey(id: ConversationId): string;
+/** An entry record. */
+export declare function entryKey(id: EntryId): string;
+/** The newest entries of a conversation: appended blind, read by scans, the newest entry, and head markers. */
+export declare function appendKey(id: ConversationId): string;
+/** A submission record. */
+export declare function submissionKey(id: SubmissionId): string;
+/** The submission a conversation's request ID names. */
+export declare function requestKey(conversationId: ConversationId, requestId: string): string;
+/** A document address (`addressId()`): its current incarnation, value, and held changes. */
+export declare function documentKey(addressId: string): string;
+/** A document incarnation, for reads by its ID. */
+export declare function incarnationKey(id: DocumentId): string;
+/** The incarnations alive in a scope: created and retired blind, read by scans and the task-document index. */
+export declare function scopeKey(scope: DocumentRecord["scope"]): string;
+/**
+ * A node of the scheduler's ownership tree (a task ID, or `c<conversation ID>`): the live work listed below it. Written
+ * by task creation and a task becoming terminal for every node from the task's parent up to and including the nearest
+ * live task or the root conversation; read by every walk that expands the node.
+ */
+export declare function ownedKey(node: TaskId | string): string;
+/** The ownerless conversations with live work below them, which global idle walks from. */
+export declare const ROOTS_KEY = "roots";
+/** The live tasks with cancellation intent: abort marks, and held outcomes other than `completed`. */
+export declare const INTENT_KEY = "intent";
+/** Every unpublished write: what a read that cannot be keyed, such as a scan, touches. */
+export declare const ALL_KEYS = "*";
+/** The keys of the table records in `writes`; document writes are keyed by the transaction, which knows addresses. */
+export declare function tableKeys(writes: readonly StorageWrite[], keys: string[]): void;
+/**
+ * The Storage a job on the line reads through: every read first touches its key (`touch`), which waits while the key
+ * has an unpublished writer, so the read sees what the line admitted before it. Scans that cannot be keyed touch
+ * `ALL_KEYS`. Commits and `close()` pass through; the line never commits through it.
+ */
+export declare class GatedStorage implements Storage {
+    #private;
+    constructor(storage: Storage, touch: (key: string) => Promise<void> | undefined);
+    commit(batches: readonly (readonly StorageWrite[])[], receive: (index: number, seq: Seq) => void, context: Context): Promise<CommitResult>;
+    mintId<I extends Id<string>>(): Promise<I>;
+    conversation(id: ConversationId, context: Context): Promise<ConversationRecord | undefined>;
+    scanConversations(query: ConversationQuery, limit: number, cursor: Cursor | undefined, context: Context): Promise<Page<ConversationRecord, Cursor>>;
+    entry(id: EntryId, context: Context): Promise<StoredEntry | undefined>;
+    entry(conversationId: ConversationId, id: EntryId, context: Context): Promise<StoredEntry | undefined>;
+    findLatestHeadMarker(conversationId: ConversationId, atOrBeforeEntryId: EntryId | undefined, context: Context): Promise<(EntryRecord & {
+        readonly head: EntryId;
+    }) | undefined>;
+    scanEntries(query: EntryQuery, limit: number, cursor: Cursor | undefined, context: Context): Promise<Page<EntryRecord, Cursor>>;
+    task(id: TaskId, context: Context): Promise<TaskRecord<JsonValue, JsonValue, JsonValue> | undefined>;
+    scanTasks(query: TaskQuery, limit: number, cursor: Cursor | undefined, context: Context): Promise<Page<TaskRecord<JsonValue, JsonValue, JsonValue>, Cursor>>;
+    submission(id: SubmissionId, context: Context): Promise<SubmissionRecord | undefined>;
+    scanSubmissions(query: SubmissionQuery, limit: number, cursor: Cursor | undefined, context: Context): Promise<Page<SubmissionRecord, Cursor>>;
+    submissionByRequest(conversationId: ConversationId, requestId: string, context: Context): Promise<SubmissionRecord | undefined>;
+    findDocument(address: DocumentAddress, at: DocumentPoint, context: Context): Promise<DocumentRecord | undefined>;
+    document(id: DocumentId, at: DocumentPoint, context: Context): Promise<StoredDocument | undefined>;
+    scanDocuments(query: DocumentQuery, limit: number, cursor: Cursor | undefined, context: Context): Promise<Page<DocumentRecord, Cursor>>;
+    close(context: Context): Promise<void>;
+}
+export {};
+//# sourceMappingURL=keys.d.ts.map

package/dist/session/keys.d.ts.map

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

package/dist/session/keys.js

@@ -0,0 +1,161 @@
+import { addressId } from "../documents.js";
+/** A task record. */
+export function taskKey(id) {
+    return `task:${id}`;
+}
+/** A conversation record. */
+export function conversationKey(id) {
+    return `conv:${id}`;
+}
+/** An entry record. */
+export function entryKey(id) {
+    return `entry:${id}`;
+}
+/** The newest entries of a conversation: appended blind, read by scans, the newest entry, and head markers. */
+export function appendKey(id) {
+    return `entry-append:${id}`;
+}
+/** A submission record. */
+export function submissionKey(id) {
+    return `sub:${id}`;
+}
+/** The submission a conversation's request ID names. */
+export function requestKey(conversationId, requestId) {
+    return `req:${conversationId}:${requestId}`;
+}
+/** A document address (`addressId()`): its current incarnation, value, and held changes. */
+export function documentKey(addressId) {
+    return `doc:${addressId}`;
+}
+/** A document incarnation, for reads by its ID. */
+export function incarnationKey(id) {
+    return `docid:${id}`;
+}
+/** The incarnations alive in a scope: created and retired blind, read by scans and the task-document index. */
+export function scopeKey(scope) {
+    switch (scope.kind) {
+        case "session":
+            return "docscope:session";
+        case "conversation":
+            return `docscope:c${scope.conversationId}`;
+        case "task":
+            return `docscope:t${scope.taskId}`;
+    }
+}
+/**
+ * A node of the scheduler's ownership tree (a task ID, or `c<conversation ID>`): the live work listed below it. Written
+ * by task creation and a task becoming terminal for every node from the task's parent up to and including the nearest
+ * live task or the root conversation; read by every walk that expands the node.
+ */
+export function ownedKey(node) {
+    return `owned:${node}`;
+}
+/** The ownerless conversations with live work below them, which global idle walks from. */
+export const ROOTS_KEY = "roots";
+/** The live tasks with cancellation intent: abort marks, and held outcomes other than `completed`. */
+export const INTENT_KEY = "intent";
+/** Every unpublished write: what a read that cannot be keyed, such as a scan, touches. */
+export const ALL_KEYS = "*";
+/** The keys of the table records in `writes`; document writes are keyed by the transaction, which knows addresses. */
+export function tableKeys(writes, keys) {
+    for (const write of writes) {
+        switch (write.type) {
+            case "conversation":
+                keys.push(conversationKey(write.value.id));
+                break;
+            case "entry":
+                keys.push(entryKey(write.value.id), appendKey(write.value.conversationId));
+                break;
+            case "task":
+                keys.push(taskKey(write.value.id));
+                break;
+            case "submission":
+                keys.push(submissionKey(write.value.id));
+                if (write.value.requestId !== undefined) {
+                    keys.push(requestKey(write.value.conversationId, write.value.requestId));
+                }
+                break;
+        }
+    }
+}
+/**
+ * The Storage a job on the line reads through: every read first touches its key (`touch`), which waits while the key
+ * has an unpublished writer, so the read sees what the line admitted before it. Scans that cannot be keyed touch
+ * `ALL_KEYS`. Commits and `close()` pass through; the line never commits through it.
+ */
+export class GatedStorage {
+    #storage;
+    #touch;
+    constructor(storage, touch) {
+        this.#storage = storage;
+        this.#touch = touch;
+    }
+    commit(batches, receive, context) {
+        return this.#storage.commit(batches, receive, context);
+    }
+    mintId() {
+        return this.#storage.mintId();
+    }
+    conversation(id, context) {
+        return this.#after(conversationKey(id), () => this.#storage.conversation(id, context));
+    }
+    scanConversations(query, limit, cursor, context) {
+        return this.#after(ALL_KEYS, () => this.#storage.scanConversations(query, limit, cursor, context));
+    }
+    entry(first, second, third) {
+        if (third === undefined) {
+            const id = first;
+            return this.#after(entryKey(id), () => this.#storage.entry(id, second));
+        }
+        const conversationId = first;
+        const id = second;
+        // Visibility follows the conversation's immutable ancestry; the conversation may be unpublished itself.
+        return this.#after(conversationKey(conversationId), () => this.#after(entryKey(id), () => this.#storage.entry(conversationId, id, third)));
+    }
+    findLatestHeadMarker(conversationId, atOrBeforeEntryId, context) {
+        return this.#afterEntries(conversationId, () => this.#storage.findLatestHeadMarker(conversationId, atOrBeforeEntryId, context));
+    }
+    scanEntries(query, limit, cursor, context) {
+        return this.#afterEntries(query.conversationId, () => this.#storage.scanEntries(query, limit, cursor, context));
+    }
+    task(id, context) {
+        return this.#after(taskKey(id), () => this.#storage.task(id, context));
+    }
+    scanTasks(query, limit, cursor, context) {
+        return this.#after(ALL_KEYS, () => this.#storage.scanTasks(query, limit, cursor, context));
+    }
+    submission(id, context) {
+        return this.#after(submissionKey(id), () => this.#storage.submission(id, context));
+    }
+    scanSubmissions(query, limit, cursor, context) {
+        return this.#after(ALL_KEYS, () => this.#storage.scanSubmissions(query, limit, cursor, context));
+    }
+    submissionByRequest(conversationId, requestId, context) {
+        return this.#after(requestKey(conversationId, requestId), () => this.#storage.submissionByRequest(conversationId, requestId, context));
+    }
+    findDocument(address, at, context) {
+        return this.#after(documentKey(addressId(address)), () => this.#storage.findDocument(address, at, context));
+    }
+    document(id, at, context) {
+        return this.#after(incarnationKey(id), () => this.#storage.document(id, at, context));
+    }
+    scanDocuments(query, limit, cursor, context) {
+        return this.#after(scopeKey(query.scope), () => this.#storage.scanDocuments(query, limit, cursor, context));
+    }
+    close(context) {
+        return this.#storage.close(context);
+    }
+    /**
+     * Run a read of a conversation's entries once neither its appends nor its creation has an unpublished writer: Storage
+     * refuses the read of a conversation it does not have yet.
+     */
+    #afterEntries(conversationId, read) {
+        return this.#after(conversationKey(conversationId), () => this.#after(appendKey(conversationId), read));
+    }
+    /** Run `read` once `key` has no unpublished writer. */
+    #after(key, read) {
+        const gate = this.#touch(key);
+        return gate === undefined ? read() : gate.then(read);
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/session/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/session/keys.ts"],"names":[],"mappings":"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","sourcesContent":["// The keys of the Session line: what a commit writes and a job reads, so a read of an unpublished write waits for it.\nimport type { Context, JsonValue } from \"@earendil-works/chord\";\nimport { addressId } from \"../documents.ts\";\nimport type {\n\tCommitResult,\n\tConversationId,\n\tConversationQuery,\n\tConversationRecord,\n\tCursor,\n\tDocumentAddress,\n\tDocumentId,\n\tDocumentPoint,\n\tDocumentQuery,\n\tDocumentRecord,\n\tEntryId,\n\tEntryQuery,\n\tEntryRecord,\n\tId,\n\tPage,\n\tSeq,\n\tStorage,\n\tStorageWrite,\n\tStoredDocument,\n\tSubmissionId,\n\tSubmissionQuery,\n\tSubmissionRecord,\n\tTaskId,\n\tTaskQuery,\n\tTaskRecord,\n} from \"../types.ts\";\n\ntype StoredEntry = { readonly entry: EntryRecord; readonly commitSeq: Seq };\n\n/** A task record. */\nexport function taskKey(id: TaskId): string {\n\treturn `task:${id}`;\n}\n\n/** A conversation record. */\nexport function conversationKey(id: ConversationId): string {\n\treturn `conv:${id}`;\n}\n\n/** An entry record. */\nexport function entryKey(id: EntryId): string {\n\treturn `entry:${id}`;\n}\n\n/** The newest entries of a conversation: appended blind, read by scans, the newest entry, and head markers. */\nexport function appendKey(id: ConversationId): string {\n\treturn `entry-append:${id}`;\n}\n\n/** A submission record. */\nexport function submissionKey(id: SubmissionId): string {\n\treturn `sub:${id}`;\n}\n\n/** The submission a conversation's request ID names. */\nexport function requestKey(conversationId: ConversationId, requestId: string): string {\n\treturn `req:${conversationId}:${requestId}`;\n}\n\n/** A document address (`addressId()`): its current incarnation, value, and held changes. */\nexport function documentKey(addressId: string): string {\n\treturn `doc:${addressId}`;\n}\n\n/** A document incarnation, for reads by its ID. */\nexport function incarnationKey(id: DocumentId): string {\n\treturn `docid:${id}`;\n}\n\n/** The incarnations alive in a scope: created and retired blind, read by scans and the task-document index. */\nexport function scopeKey(scope: DocumentRecord[\"scope\"]): string {\n\tswitch (scope.kind) {\n\t\tcase \"session\":\n\t\t\treturn \"docscope:session\";\n\t\tcase \"conversation\":\n\t\t\treturn `docscope:c${scope.conversationId}`;\n\t\tcase \"task\":\n\t\t\treturn `docscope:t${scope.taskId}`;\n\t}\n}\n\n/**\n * A node of the scheduler's ownership tree (a task ID, or `c<conversation ID>`): the live work listed below it. Written\n * by task creation and a task becoming terminal for every node from the task's parent up to and including the nearest\n * live task or the root conversation; read by every walk that expands the node.\n */\nexport function ownedKey(node: TaskId | string): string {\n\treturn `owned:${node}`;\n}\n\n/** The ownerless conversations with live work below them, which global idle walks from. */\nexport const ROOTS_KEY = \"roots\";\n\n/** The live tasks with cancellation intent: abort marks, and held outcomes other than `completed`. */\nexport const INTENT_KEY = \"intent\";\n\n/** Every unpublished write: what a read that cannot be keyed, such as a scan, touches. */\nexport const ALL_KEYS = \"*\";\n\n/** The keys of the table records in `writes`; document writes are keyed by the transaction, which knows addresses. */\nexport function tableKeys(writes: readonly StorageWrite[], keys: string[]): void {\n\tfor (const write of writes) {\n\t\tswitch (write.type) {\n\t\t\tcase \"conversation\":\n\t\t\t\tkeys.push(conversationKey(write.value.id));\n\t\t\t\tbreak;\n\t\t\tcase \"entry\":\n\t\t\t\tkeys.push(entryKey(write.value.id), appendKey(write.value.conversationId));\n\t\t\t\tbreak;\n\t\t\tcase \"task\":\n\t\t\t\tkeys.push(taskKey(write.value.id));\n\t\t\t\tbreak;\n\t\t\tcase \"submission\":\n\t\t\t\tkeys.push(submissionKey(write.value.id));\n\t\t\t\tif (write.value.requestId !== undefined) {\n\t\t\t\t\tkeys.push(requestKey(write.value.conversationId, write.value.requestId));\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t}\n\t}\n}\n\n/**\n * The Storage a job on the line reads through: every read first touches its key (`touch`), which waits while the key\n * has an unpublished writer, so the read sees what the line admitted before it. Scans that cannot be keyed touch\n * `ALL_KEYS`. Commits and `close()` pass through; the line never commits through it.\n */\nexport class GatedStorage implements Storage {\n\treadonly #storage: Storage;\n\treadonly #touch: (key: string) => Promise<void> | undefined;\n\n\tconstructor(storage: Storage, touch: (key: string) => Promise<void> | undefined) {\n\t\tthis.#storage = storage;\n\t\tthis.#touch = touch;\n\t}\n\n\tcommit(\n\t\tbatches: readonly (readonly StorageWrite[])[],\n\t\treceive: (index: number, seq: Seq) => void,\n\t\tcontext: Context,\n\t): Promise<CommitResult> {\n\t\treturn this.#storage.commit(batches, receive, context);\n\t}\n\n\tmintId<I extends Id<string>>(): Promise<I> {\n\t\treturn this.#storage.mintId<I>();\n\t}\n\n\tconversation(id: ConversationId, context: Context): Promise<ConversationRecord | undefined> {\n\t\treturn this.#after(conversationKey(id), () => this.#storage.conversation(id, context));\n\t}\n\n\tscanConversations(\n\t\tquery: ConversationQuery,\n\t\tlimit: number,\n\t\tcursor: Cursor | undefined,\n\t\tcontext: Context,\n\t): Promise<Page<ConversationRecord, Cursor>> {\n\t\treturn this.#after(ALL_KEYS, () => this.#storage.scanConversations(query, limit, cursor, context));\n\t}\n\n\tentry(id: EntryId, context: Context): Promise<StoredEntry | undefined>;\n\tentry(conversationId: ConversationId, id: EntryId, context: Context): Promise<StoredEntry | undefined>;\n\tentry(\n\t\tfirst: EntryId | ConversationId,\n\t\tsecond: EntryId | Context,\n\t\tthird?: Context,\n\t): Promise<StoredEntry | undefined> {\n\t\tif (third === undefined) {\n\t\t\tconst id = first as EntryId;\n\t\t\treturn this.#after(entryKey(id), () => this.#storage.entry(id, second as Context));\n\t\t}\n\t\tconst conversationId = first as ConversationId;\n\t\tconst id = second as EntryId;\n\t\t// Visibility follows the conversation's immutable ancestry; the conversation may be unpublished itself.\n\t\treturn this.#after(conversationKey(conversationId), () =>\n\t\t\tthis.#after(entryKey(id), () => this.#storage.entry(conversationId, id, third)),\n\t\t);\n\t}\n\n\tfindLatestHeadMarker(\n\t\tconversationId: ConversationId,\n\t\tatOrBeforeEntryId: EntryId | undefined,\n\t\tcontext: Context,\n\t): Promise<(EntryRecord & { readonly head: EntryId }) | undefined> {\n\t\treturn this.#afterEntries(conversationId, () =>\n\t\t\tthis.#storage.findLatestHeadMarker(conversationId, atOrBeforeEntryId, context),\n\t\t);\n\t}\n\n\tscanEntries(\n\t\tquery: EntryQuery,\n\t\tlimit: number,\n\t\tcursor: Cursor | undefined,\n\t\tcontext: Context,\n\t): Promise<Page<EntryRecord, Cursor>> {\n\t\treturn this.#afterEntries(query.conversationId, () => this.#storage.scanEntries(query, limit, cursor, context));\n\t}\n\n\ttask(id: TaskId, context: Context): Promise<TaskRecord<JsonValue, JsonValue, JsonValue> | undefined> {\n\t\treturn this.#after(taskKey(id), () => this.#storage.task(id, context));\n\t}\n\n\tscanTasks(\n\t\tquery: TaskQuery,\n\t\tlimit: number,\n\t\tcursor: Cursor | undefined,\n\t\tcontext: Context,\n\t): Promise<Page<TaskRecord<JsonValue, JsonValue, JsonValue>, Cursor>> {\n\t\treturn this.#after(ALL_KEYS, () => this.#storage.scanTasks(query, limit, cursor, context));\n\t}\n\n\tsubmission(id: SubmissionId, context: Context): Promise<SubmissionRecord | undefined> {\n\t\treturn this.#after(submissionKey(id), () => this.#storage.submission(id, context));\n\t}\n\n\tscanSubmissions(\n\t\tquery: SubmissionQuery,\n\t\tlimit: number,\n\t\tcursor: Cursor | undefined,\n\t\tcontext: Context,\n\t): Promise<Page<SubmissionRecord, Cursor>> {\n\t\treturn this.#after(ALL_KEYS, () => this.#storage.scanSubmissions(query, limit, cursor, context));\n\t}\n\n\tsubmissionByRequest(\n\t\tconversationId: ConversationId,\n\t\trequestId: string,\n\t\tcontext: Context,\n\t): Promise<SubmissionRecord | undefined> {\n\t\treturn this.#after(requestKey(conversationId, requestId), () =>\n\t\t\tthis.#storage.submissionByRequest(conversationId, requestId, context),\n\t\t);\n\t}\n\n\tfindDocument(address: DocumentAddress, at: DocumentPoint, context: Context): Promise<DocumentRecord | undefined> {\n\t\treturn this.#after(documentKey(addressId(address)), () => this.#storage.findDocument(address, at, context));\n\t}\n\n\tdocument(id: DocumentId, at: DocumentPoint, context: Context): Promise<StoredDocument | undefined> {\n\t\treturn this.#after(incarnationKey(id), () => this.#storage.document(id, at, context));\n\t}\n\n\tscanDocuments(\n\t\tquery: DocumentQuery,\n\t\tlimit: number,\n\t\tcursor: Cursor | undefined,\n\t\tcontext: Context,\n\t): Promise<Page<DocumentRecord, Cursor>> {\n\t\treturn this.#after(scopeKey(query.scope), () => this.#storage.scanDocuments(query, limit, cursor, context));\n\t}\n\n\tclose(context: Context): Promise<void> {\n\t\treturn this.#storage.close(context);\n\t}\n\n\t/**\n\t * Run a read of a conversation's entries once neither its appends nor its creation has an unpublished writer: Storage\n\t * refuses the read of a conversation it does not have yet.\n\t */\n\t#afterEntries<T>(conversationId: ConversationId, read: () => Promise<T>): Promise<T> {\n\t\treturn this.#after(conversationKey(conversationId), () => this.#after(appendKey(conversationId), read));\n\t}\n\n\t/** Run `read` once `key` has no unpublished writer. */\n\t#after<T>(key: string, read: () => Promise<T>): Promise<T> {\n\t\tconst gate = this.#touch(key);\n\t\treturn gate === undefined ? read() : gate.then(read);\n\t}\n}\n"]}