@earendil-works/pi-durable 1.3.0 → 1.5.0

package/dist/search.js

@@ -2,6 +2,84 @@
  * BM25 tool search for code mode's `searchTools()` and the `tool_search` tool, a copy of the coding agent's tool search
  * ranking: durable keeps its own copy of what it needs from the coding agent.
  */
+/**
+ * Okapi BM25 (k1 1.2, b 0.75) over `text`, with the name and the namespace as separate fields: the names of the best
+ * matches, best first; ties keep document order.
+ * - A tool that matches more of the query's terms, in any field, ranks above one that matches fewer, whatever their
+ *   scores: for `screenshot window`, a tool whose description has both words beats `window` whose name has one.
+ * - A query term in the name scores more than any number of mentions in the text.
+ * - A tool whose whole local name (after the last `__`) is in the query gets a bonus worth one more match of every
+ *   query term, so among tools matching as many terms, `peekaboo app` finds `mcp__peekaboo__app` over tools that
+ *   only mention the words.
+ * - A query that is exactly a tool's name, or its name after a `__`, ranks that tool first, before coverage.
+ *
+ * Only `text` is length-normalized, so a long name or long namespace instructions do not lower a tool's score.
+ */
+export function rankDocuments(query, documents, limit) {
+    const queryTerms = new Set(tokenize(query));
+    if (queryTerms.size === 0 || documents.length === 0 || limit <= 0)
+        return [];
+    const indexed = documents.map(indexDocument);
+    const averageLength = indexed.reduce((sum, document) => sum + document.textLength, 0) / indexed.length || 1;
+    const idf = new Map([...queryTerms].map((term) => {
+        const frequency = indexed.filter((document) => document.nameTerms.has(term) || document.textCounts.has(term) || document.namespaceTerms.has(term)).length;
+        return [term, Math.log(1 + (indexed.length - frequency + 0.5) / (frequency + 0.5))];
+    }));
+    const fullNameBonus = [...idf.values()].reduce((sum, value) => sum + value, 0);
+    const exactQuery = normalizeName(query);
+    const matches = [];
+    for (const document of indexed) {
+        const norm = K1 * (1 - B + (B * document.textLength) / averageLength);
+        let score = 0;
+        let covered = 0;
+        for (const term of queryTerms) {
+            const count = document.textCounts.get(term) ?? 0;
+            const weight = (document.nameTerms.has(term) ? NAME_WEIGHT : 0) +
+                (document.namespaceTerms.has(term) ? NAMESPACE_WEIGHT : 0) +
+                (count * (K1 + 1)) / (count + norm);
+            if (weight > 0)
+                covered++;
+            score += idf.get(term) * weight;
+        }
+        if (score === 0)
+            continue;
+        const local = document.localNameTerms;
+        if (local.length > 0 && local.every((term) => queryTerms.has(term)))
+            score += fullNameBonus;
+        matches.push({ name: document.name, score, covered, exact: isExactNameQuery(exactQuery, document.name) });
+    }
+    return matches
+        .sort((left, right) => Number(right.exact) - Number(left.exact) || right.covered - left.covered || right.score - left.score)
+        .slice(0, limit)
+        .map((match) => match.name);
+}
+const K1 = 1.2;
+const B = 0.75;
+/**
+ * A query term in the name counts this many times its IDF. The text part of a term is at most `K1 + 1` (2.2) times
+ * its IDF and about 1 for a single mention, so a name match beats any number of mentions in the text.
+ */
+const NAME_WEIGHT = 3;
+/**
+ * A query term in the namespace text counts this many times its IDF. Every tool of the namespace shares it, so it helps
+ * find the namespace but not the tool in it.
+ */
+const NAMESPACE_WEIGHT = 0.5;
+function indexDocument(document) {
+    const textCounts = new Map();
+    for (const term of tokenize(document.text))
+        textCounts.set(term, (textCounts.get(term) ?? 0) + 1);
+    const segments = document.name.split("__");
+    return {
+        name: document.name,
+        nameTerms: new Set(tokenize(document.name)),
+        localNameTerms: [...new Set(tokenize(segments[segments.length - 1]))],
+        textCounts,
+        textLength: [...textCounts.values()].reduce((sum, count) => sum + count, 0),
+        namespaceTerms: new Set(tokenize(document.namespaceText ?? "")),
+    };
+}
+const wordSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
 const STOP_WORDS = new Set([
     "a",
     "an",
@@ -25,6 +103,23 @@ const STOP_WORDS = new Set([
     "to",
     "with",
 ]);
+/** Unicode word segmentation with identifier boundaries and English stop words/singular forms. */
+export function tokenize(text) {
+    const normalized = text
+        .normalize("NFC")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{M}\p{N}]+/gu, " ");
+    // The segmenter costs about 15 times a split. Plain ASCII splits into the same words at spaces, so only other
+    // text, such as Chinese written without spaces, goes through it.
+    const words = /^[a-z0-9 ]*$/.test(normalized)
+        ? normalized.split(" ")
+        : Array.from(wordSegmenter.segment(normalized), (segment) => (segment.isWordLike ? segment.segment : ""));
+    return words
+        .filter((word) => word.length > 0 && !STOP_WORDS.has(word))
+        .map((word) => (/^[a-z0-9]+$/.test(word) ? stem(word) : word));
+}
 /** Naive singular form, so `issues` matches `issue` and `searches` matches `search`. */
 function stem(term) {
     if (term.length > 4 && term.endsWith("ies"))
@@ -35,51 +130,19 @@ function stem(term) {
         return term.slice(0, -1);
     return term;
 }
-/** Lowercase terms, split at camelCase boundaries and non-alphanumerics, without stop words. */
-export function tokenize(text) {
-    return text
-        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+/** Lowercase with characters invalid in script identifiers as `_`, so `dev-radius` matches `dev_radius`. */
+function normalizeName(name) {
+    return name
+        .trim()
         .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((term) => term.length > 0 && !STOP_WORDS.has(term))
-        .map(stem);
+        .replace(/[^a-z0-9_$]/g, "_");
 }
-/** Okapi BM25 (k1 1.2, b 0.75): the names of the best matches, best first; ties keep document order. */
-export function rankDocuments(query, documents, limit) {
-    const k1 = 1.2;
-    const b = 0.75;
-    const queryTerms = [...new Set(tokenize(query))];
-    if (queryTerms.length === 0 || documents.length === 0 || limit <= 0)
-        return [];
-    const termCounts = documents.map((document) => {
-        const counts = new Map();
-        for (const term of tokenize(document.text))
-            counts.set(term, (counts.get(term) ?? 0) + 1);
-        return counts;
-    });
-    const lengths = termCounts.map((counts) => [...counts.values()].reduce((sum, count) => sum + count, 0));
-    const averageLength = lengths.reduce((sum, length) => sum + length, 0) / documents.length || 1;
-    const idf = new Map(queryTerms.map((term) => {
-        const frequency = termCounts.filter((counts) => counts.has(term)).length;
-        return [term, Math.log(1 + (documents.length - frequency + 0.5) / (frequency + 0.5))];
-    }));
-    const matches = [];
-    documents.forEach((document, index) => {
-        let score = 0;
-        for (const term of queryTerms) {
-            const count = termCounts[index].get(term);
-            if (!count)
-                continue;
-            const norm = k1 * (1 - b + (b * lengths[index]) / averageLength);
-            score += (idf.get(term) ?? 0) * ((count * (k1 + 1)) / (count + norm));
-        }
-        if (score > 0)
-            matches.push({ name: document.name, score });
-    });
-    return matches
-        .sort((left, right) => right.score - left.score)
-        .slice(0, limit)
-        .map((match) => match.name);
+/**
+ * Whether the whole query is the tool's name: its full name or a suffix after a `__` separator, so `thread_read` and
+ * `app__thread_read` both name `mcp__app__thread_read`.
+ */
+function isExactNameQuery(query, name) {
+    const normalized = normalizeName(name);
+    return normalized === query || normalized.endsWith(`__${query}`);
 }
 //# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * BM25 tool search for code mode's `searchTools()` and the `tool_search` tool, a copy of the coding agent's tool search\n * ranking: durable keeps its own copy of what it needs from the coding agent.\n */\n\nexport type SearchDocument = { readonly name: string; readonly text: string };\n\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n\t\"a\",\n\t\"an\",\n\t\"and\",\n\t\"are\",\n\t\"as\",\n\t\"at\",\n\t\"be\",\n\t\"by\",\n\t\"for\",\n\t\"from\",\n\t\"in\",\n\t\"is\",\n\t\"it\",\n\t\"of\",\n\t\"on\",\n\t\"or\",\n\t\"that\",\n\t\"the\",\n\t\"this\",\n\t\"to\",\n\t\"with\",\n]);\n\n/** Naive singular form, so `issues` matches `issue` and `searches` matches `search`. */\nfunction stem(term: string): string {\n\tif (term.length > 4 && term.endsWith(\"ies\")) return `${term.slice(0, -3)}y`;\n\tif (term.length > 4 && /(ches|shes|sses|xes|zes)$/.test(term)) return term.slice(0, -2);\n\tif (term.length > 3 && term.endsWith(\"s\") && !term.endsWith(\"ss\")) return term.slice(0, -1);\n\treturn term;\n}\n\n/** Lowercase terms, split at camelCase boundaries and non-alphanumerics, without stop words. */\nexport function tokenize(text: string): string[] {\n\treturn text\n\t\t.replace(/([a-z0-9])([A-Z])/g, \"$1 $2\")\n\t\t.replace(/([A-Z]+)([A-Z][a-z])/g, \"$1 $2\")\n\t\t.toLowerCase()\n\t\t.split(/[^a-z0-9]+/)\n\t\t.filter((term) => term.length > 0 && !STOP_WORDS.has(term))\n\t\t.map(stem);\n}\n\n/** Okapi BM25 (k1 1.2, b 0.75): the names of the best matches, best first; ties keep document order. */\nexport function rankDocuments(query: string, documents: readonly SearchDocument[], limit: number): string[] {\n\tconst k1 = 1.2;\n\tconst b = 0.75;\n\tconst queryTerms = [...new Set(tokenize(query))];\n\tif (queryTerms.length === 0 || documents.length === 0 || limit <= 0) return [];\n\tconst termCounts = documents.map((document) => {\n\t\tconst counts = new Map<string, number>();\n\t\tfor (const term of tokenize(document.text)) counts.set(term, (counts.get(term) ?? 0) + 1);\n\t\treturn counts;\n\t});\n\tconst lengths = termCounts.map((counts) => [...counts.values()].reduce((sum, count) => sum + count, 0));\n\tconst averageLength = lengths.reduce((sum, length) => sum + length, 0) / documents.length || 1;\n\tconst idf = new Map(\n\t\tqueryTerms.map((term) => {\n\t\t\tconst frequency = termCounts.filter((counts) => counts.has(term)).length;\n\t\t\treturn [term, Math.log(1 + (documents.length - frequency + 0.5) / (frequency + 0.5))] as const;\n\t\t}),\n\t);\n\tconst matches: { name: string; score: number }[] = [];\n\tdocuments.forEach((document, index) => {\n\t\tlet score = 0;\n\t\tfor (const term of queryTerms) {\n\t\t\tconst count = termCounts[index]!.get(term);\n\t\t\tif (!count) continue;\n\t\t\tconst norm = k1 * (1 - b + (b * lengths[index]!) / averageLength);\n\t\t\tscore += (idf.get(term) ?? 0) * ((count * (k1 + 1)) / (count + norm));\n\t\t}\n\t\tif (score > 0) matches.push({ name: document.name, score });\n\t});\n\treturn matches\n\t\t.sort((left, right) => right.score - left.score)\n\t\t.slice(0, limit)\n\t\t.map((match) => match.name);\n}\n"]}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * BM25 tool search for code mode's `searchTools()` and the `tool_search` tool, a copy of the coding agent's tool search\n * ranking: durable keeps its own copy of what it needs from the coding agent.\n */\n\n/** A tool as the ranker sees it: its name, its text, and the text of its namespace. */\nexport type SearchDocument = {\n\treadonly name: string;\n\t/** Description and parameter names and descriptions; not the name, which the ranker reads from `name`. */\n\treadonly text: string;\n\t/** Name, description, and instructions of the tool's namespace. */\n\treadonly namespaceText?: string;\n};\n\n/**\n * Okapi BM25 (k1 1.2, b 0.75) over `text`, with the name and the namespace as separate fields: the names of the best\n * matches, best first; ties keep document order.\n * - A tool that matches more of the query's terms, in any field, ranks above one that matches fewer, whatever their\n *   scores: for `screenshot window`, a tool whose description has both words beats `window` whose name has one.\n * - A query term in the name scores more than any number of mentions in the text.\n * - A tool whose whole local name (after the last `__`) is in the query gets a bonus worth one more match of every\n *   query term, so among tools matching as many terms, `peekaboo app` finds `mcp__peekaboo__app` over tools that\n *   only mention the words.\n * - A query that is exactly a tool's name, or its name after a `__`, ranks that tool first, before coverage.\n *\n * Only `text` is length-normalized, so a long name or long namespace instructions do not lower a tool's score.\n */\nexport function rankDocuments(query: string, documents: readonly SearchDocument[], limit: number): string[] {\n\tconst queryTerms = new Set(tokenize(query));\n\tif (queryTerms.size === 0 || documents.length === 0 || limit <= 0) return [];\n\tconst indexed = documents.map(indexDocument);\n\tconst averageLength = indexed.reduce((sum, document) => sum + document.textLength, 0) / indexed.length || 1;\n\tconst idf = new Map(\n\t\t[...queryTerms].map((term) => {\n\t\t\tconst frequency = indexed.filter(\n\t\t\t\t(document) =>\n\t\t\t\t\tdocument.nameTerms.has(term) || document.textCounts.has(term) || document.namespaceTerms.has(term),\n\t\t\t).length;\n\t\t\treturn [term, Math.log(1 + (indexed.length - frequency + 0.5) / (frequency + 0.5))] as const;\n\t\t}),\n\t);\n\tconst fullNameBonus = [...idf.values()].reduce((sum, value) => sum + value, 0);\n\tconst exactQuery = normalizeName(query);\n\tconst matches: { name: string; score: number; covered: number; exact: boolean }[] = [];\n\tfor (const document of indexed) {\n\t\tconst norm = K1 * (1 - B + (B * document.textLength) / averageLength);\n\t\tlet score = 0;\n\t\tlet covered = 0;\n\t\tfor (const term of queryTerms) {\n\t\t\tconst count = document.textCounts.get(term) ?? 0;\n\t\t\tconst weight =\n\t\t\t\t(document.nameTerms.has(term) ? NAME_WEIGHT : 0) +\n\t\t\t\t(document.namespaceTerms.has(term) ? NAMESPACE_WEIGHT : 0) +\n\t\t\t\t(count * (K1 + 1)) / (count + norm);\n\t\t\tif (weight > 0) covered++;\n\t\t\tscore += idf.get(term)! * weight;\n\t\t}\n\t\tif (score === 0) continue;\n\t\tconst local = document.localNameTerms;\n\t\tif (local.length > 0 && local.every((term) => queryTerms.has(term))) score += fullNameBonus;\n\t\tmatches.push({ name: document.name, score, covered, exact: isExactNameQuery(exactQuery, document.name) });\n\t}\n\treturn matches\n\t\t.sort(\n\t\t\t(left, right) =>\n\t\t\t\tNumber(right.exact) - Number(left.exact) || right.covered - left.covered || right.score - left.score,\n\t\t)\n\t\t.slice(0, limit)\n\t\t.map((match) => match.name);\n}\n\nconst K1 = 1.2;\n\nconst B = 0.75;\n\n/**\n * A query term in the name counts this many times its IDF. The text part of a term is at most `K1 + 1` (2.2) times\n * its IDF and about 1 for a single mention, so a name match beats any number of mentions in the text.\n */\nconst NAME_WEIGHT = 3;\n\n/**\n * A query term in the namespace text counts this many times its IDF. Every tool of the namespace shares it, so it helps\n * find the namespace but not the tool in it.\n */\nconst NAMESPACE_WEIGHT = 0.5;\n\n/** A document split into the fields the ranker weighs differently. */\ntype IndexedDocument = {\n\tname: string;\n\t/** Terms of the name: `mcp`, `app`, `thread`, `read` for `mcp__app__thread_read`. */\n\tnameTerms: ReadonlySet<string>;\n\t/** Terms of the name after its last `__`, the part models say: `thread`, `read`. */\n\tlocalNameTerms: readonly string[];\n\ttextCounts: ReadonlyMap<string, number>;\n\ttextLength: number;\n\tnamespaceTerms: ReadonlySet<string>;\n};\n\nfunction indexDocument(document: SearchDocument): IndexedDocument {\n\tconst textCounts = new Map<string, number>();\n\tfor (const term of tokenize(document.text)) textCounts.set(term, (textCounts.get(term) ?? 0) + 1);\n\tconst segments = document.name.split(\"__\");\n\treturn {\n\t\tname: document.name,\n\t\tnameTerms: new Set(tokenize(document.name)),\n\t\tlocalNameTerms: [...new Set(tokenize(segments[segments.length - 1]!))],\n\t\ttextCounts,\n\t\ttextLength: [...textCounts.values()].reduce((sum, count) => sum + count, 0),\n\t\tnamespaceTerms: new Set(tokenize(document.namespaceText ?? \"\")),\n\t};\n}\n\nconst wordSegmenter = new Intl.Segmenter(undefined, { granularity: \"word\" });\n\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n\t\"a\",\n\t\"an\",\n\t\"and\",\n\t\"are\",\n\t\"as\",\n\t\"at\",\n\t\"be\",\n\t\"by\",\n\t\"for\",\n\t\"from\",\n\t\"in\",\n\t\"is\",\n\t\"it\",\n\t\"of\",\n\t\"on\",\n\t\"or\",\n\t\"that\",\n\t\"the\",\n\t\"this\",\n\t\"to\",\n\t\"with\",\n]);\n\n/** Unicode word segmentation with identifier boundaries and English stop words/singular forms. */\nexport function tokenize(text: string): string[] {\n\tconst normalized = text\n\t\t.normalize(\"NFC\")\n\t\t.replace(/([a-z0-9])([A-Z])/g, \"$1 $2\")\n\t\t.replace(/([A-Z]+)([A-Z][a-z])/g, \"$1 $2\")\n\t\t.toLowerCase()\n\t\t.replace(/[^\\p{L}\\p{M}\\p{N}]+/gu, \" \");\n\t// The segmenter costs about 15 times a split. Plain ASCII splits into the same words at spaces, so only other\n\t// text, such as Chinese written without spaces, goes through it.\n\tconst words = /^[a-z0-9 ]*$/.test(normalized)\n\t\t? normalized.split(\" \")\n\t\t: Array.from(wordSegmenter.segment(normalized), (segment) => (segment.isWordLike ? segment.segment : \"\"));\n\treturn words\n\t\t.filter((word) => word.length > 0 && !STOP_WORDS.has(word))\n\t\t.map((word) => (/^[a-z0-9]+$/.test(word) ? stem(word) : word));\n}\n\n/** Naive singular form, so `issues` matches `issue` and `searches` matches `search`. */\nfunction stem(term: string): string {\n\tif (term.length > 4 && term.endsWith(\"ies\")) return `${term.slice(0, -3)}y`;\n\tif (term.length > 4 && /(ches|shes|sses|xes|zes)$/.test(term)) return term.slice(0, -2);\n\tif (term.length > 3 && term.endsWith(\"s\") && !term.endsWith(\"ss\")) return term.slice(0, -1);\n\treturn term;\n}\n\n/** Lowercase with characters invalid in script identifiers as `_`, so `dev-radius` matches `dev_radius`. */\nfunction normalizeName(name: string): string {\n\treturn name\n\t\t.trim()\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9_$]/g, \"_\");\n}\n\n/**\n * Whether the whole query is the tool's name: its full name or a suffix after a `__` separator, so `thread_read` and\n * `app__thread_read` both name `mcp__app__thread_read`.\n */\nfunction isExactNameQuery(query: string, name: string): boolean {\n\tconst normalized = normalizeName(name);\n\treturn normalized === query || normalized.endsWith(`__${query}`);\n}\n"]}

package/dist/session/cached-storage.d.ts

@@ -0,0 +1,71 @@
+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 AnyTaskRecord = TaskRecord<JsonValue, JsonValue, JsonValue>;
+type StoredEntry = {
+    readonly entry: EntryRecord;
+    readonly commitSeq: Seq;
+};
+/**
+ * Storage that serves hot record reads from memory: conversations, tasks, and written submissions, each table bounded
+ * by a count, the least recently used record leaving first, except live tasks, which are kept until they end, and the
+ * ended tasks a task waits on, kept until it moved on from its wait: a task's record is read again at each of its state
+ * changes, a waiter reads the outcomes of what it waited on once it resumes (`runtime.outcomes()`), and both are
+ * bounded by live work, which the scheduler keeps in memory too. Without that, a burst of more tasks than the count
+ * would make each of those reads a Storage read on the line. Every commit goes through it, and one process owns a
+ * Storage, so it applies each batch as it is published and never goes stale: `commit()`'s batches when the Session publishes
+ * them (`published()`), not at their durability receipts. A read
+ * result is kept only when no commit published since the read started wrote its record, as the read may not observe
+ * that commit; versions are kept only for records with a read in flight. Cached values are frozen and shared. Entries,
+ * scans, and documents pass through: the Session keeps documents and the newest entry per conversation itself, and
+ * context ranges hold the entries a run reads.
+ *
+ * Not for a read-only Session: another process writes its Storage.
+ */
+export declare class CachedStorage implements Storage {
+    #private;
+    constructor(storage: Storage);
+    /** The backend's own scope for a publication (`Storage.publishing`), when it has one. */
+    get publishing(): Storage["publishing"];
+    /** Pass the batches through; the Session applies each one with `published()` when it publishes it. */
+    commit(batches: readonly (readonly StorageWrite[])[], receive: (index: number, seq: Seq) => void, context: Context): Promise<CommitResult>;
+    /**
+     * Apply a batch `commit()` stored, when the Session publishes it. Its records are frozen in place and kept as
+     * they are, no copies: the Session's components that follow the publication, such as the scheduler's live tasks,
+     * hold the same objects, so a live task's record is in memory once.
+     */
+    published(writes: readonly StorageWrite[]): void;
+    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<AnyTaskRecord | undefined>;
+    scanTasks(query: TaskQuery, limit: number, cursor: Cursor | undefined, context: Context): Promise<Page<AnyTaskRecord, Cursor>>;
+    /** Cached as written only: this process writes every submission it settles, and a read one is usually settled. */
+    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>;
+    /** Records kept per table, for tests that bound memory. */
+    get sizes(): {
+        readonly conversations: number;
+        readonly tasks: number;
+        readonly liveTasks: number;
+        readonly awaited: number;
+        readonly waits: number;
+        readonly submissions: number;
+    };
+    /** Records with a read in flight, for tests that bound memory. */
+    get readsInFlight(): number;
+}
+/** `storage`'s publication scope (`Storage.publishing`), for a wrapper to expose as its own; none when it has none. */
+export declare function scopeOf(storage: Storage): Storage["publishing"];
+export {};
+//# sourceMappingURL=cached-storage.d.ts.map

package/dist/session/cached-storage.d.ts.map

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

package/dist/session/cached-storage.js

@@ -0,0 +1,269 @@
+/**
+ * Storage that serves hot record reads from memory: conversations, tasks, and written submissions, each table bounded
+ * by a count, the least recently used record leaving first, except live tasks, which are kept until they end, and the
+ * ended tasks a task waits on, kept until it moved on from its wait: a task's record is read again at each of its state
+ * changes, a waiter reads the outcomes of what it waited on once it resumes (`runtime.outcomes()`), and both are
+ * bounded by live work, which the scheduler keeps in memory too. Without that, a burst of more tasks than the count
+ * would make each of those reads a Storage read on the line. Every commit goes through it, and one process owns a
+ * Storage, so it applies each batch as it is published and never goes stale: `commit()`'s batches when the Session publishes
+ * them (`published()`), not at their durability receipts. A read
+ * result is kept only when no commit published since the read started wrote its record, as the read may not observe
+ * that commit; versions are kept only for records with a read in flight. Cached values are frozen and shared. Entries,
+ * scans, and documents pass through: the Session keeps documents and the newest entry per conversation itself, and
+ * context ranges hold the entries a run reads.
+ *
+ * Not for a read-only Session: another process writes its Storage.
+ */
+export class CachedStorage {
+    #storage;
+    #conversations = new Lru(4096);
+    /** Live (non-terminal) task records, until their task ends. */
+    #liveTasks = new Map();
+    /**
+     * Tasks some task waits on, or waited on until its wait ended and it has not moved on since: how many such waits name
+     * each, and its ended record once it ended.
+     */
+    #awaited = new Map();
+    /** Per task that waits, or left its wait and has not changed since: what it waited on, and whether it left. */
+    #waits = new Map();
+    // Ended task records carry inputs and outcomes, such as a tool call's arguments, so fewer are kept.
+    #tasks = new Lru(256);
+    #submissions = new Lru(256);
+    /** Per record with a read in flight: the reads, and how many published commits wrote it since the first began. */
+    #reads = new Map();
+    constructor(storage) {
+        this.#storage = storage;
+    }
+    /** The backend's own scope for a publication (`Storage.publishing`), when it has one. */
+    get publishing() {
+        return scopeOf(this.#storage);
+    }
+    /** Pass the batches through; the Session applies each one with `published()` when it publishes it. */
+    commit(batches, receive, context) {
+        return this.#storage.commit(batches, receive, context);
+    }
+    /**
+     * Apply a batch `commit()` stored, when the Session publishes it. Its records are frozen in place and kept as
+     * they are, no copies: the Session's components that follow the publication, such as the scheduler's live tasks,
+     * hold the same objects, so a live task's record is in memory once.
+     */
+    published(writes) {
+        for (const write of writes) {
+            switch (write.type) {
+                case "conversation":
+                    this.#wrote(write.value.id);
+                    this.#conversations.set(write.value.id, freeze(write.value));
+                    break;
+                case "task":
+                    this.#wrote(write.value.id);
+                    this.#followWait(write.value);
+                    this.#keepTask(freeze(write.value));
+                    break;
+                case "submission":
+                    this.#wrote(write.value.id);
+                    this.#submissions.set(write.value.id, freeze(write.value));
+                    break;
+            }
+        }
+    }
+    mintId() {
+        return this.#storage.mintId();
+    }
+    conversation(id, context) {
+        const cached = this.#conversations.get(id);
+        if (cached !== undefined)
+            return Promise.resolve(cached);
+        return this.#keep(id, () => this.#storage.conversation(id, context), (record) => this.#conversations.set(id, record));
+    }
+    scanConversations(query, limit, cursor, context) {
+        return this.#storage.scanConversations(query, limit, cursor, context);
+    }
+    entry(first, second, third) {
+        if (third === undefined)
+            return this.#storage.entry(first, second);
+        return this.#storage.entry(first, second, third);
+    }
+    findLatestHeadMarker(conversationId, atOrBeforeEntryId, context) {
+        return this.#storage.findLatestHeadMarker(conversationId, atOrBeforeEntryId, context);
+    }
+    scanEntries(query, limit, cursor, context) {
+        return this.#storage.scanEntries(query, limit, cursor, context);
+    }
+    task(id, context) {
+        const cached = this.#liveTasks.get(id) ?? this.#awaited.get(id)?.record ?? this.#tasks.get(id);
+        if (cached !== undefined)
+            return Promise.resolve(cached);
+        return this.#keep(id, () => this.#storage.task(id, context), (record) => this.#keepTask(record));
+    }
+    scanTasks(query, limit, cursor, context) {
+        return this.#storage.scanTasks(query, limit, cursor, context);
+    }
+    /** Cached as written only: this process writes every submission it settles, and a read one is usually settled. */
+    submission(id, context) {
+        const cached = this.#submissions.get(id);
+        return cached === undefined ? this.#storage.submission(id, context) : Promise.resolve(cached);
+    }
+    scanSubmissions(query, limit, cursor, context) {
+        return this.#storage.scanSubmissions(query, limit, cursor, context);
+    }
+    submissionByRequest(conversationId, requestId, context) {
+        return this.#storage.submissionByRequest(conversationId, requestId, context);
+    }
+    findDocument(address, at, context) {
+        return this.#storage.findDocument(address, at, context);
+    }
+    document(id, at, context) {
+        return this.#storage.document(id, at, context);
+    }
+    scanDocuments(query, limit, cursor, context) {
+        return this.#storage.scanDocuments(query, limit, cursor, context);
+    }
+    close(context) {
+        return this.#storage.close(context);
+    }
+    /** Records kept per table, for tests that bound memory. */
+    get sizes() {
+        return {
+            conversations: this.#conversations.size,
+            tasks: this.#tasks.size,
+            liveTasks: this.#liveTasks.size,
+            awaited: this.#awaited.size,
+            waits: this.#waits.size,
+            submissions: this.#submissions.size,
+        };
+    }
+    /** Keep a frozen task record: a live one until its task ends, an ended one in the bounded table. */
+    #keepTask(record) {
+        if (record.state.status === "terminal") {
+            this.#liveTasks.delete(record.id);
+            const awaited = this.#awaited.get(record.id);
+            if (awaited !== undefined)
+                awaited.record = record;
+            else
+                this.#tasks.set(record.id, record);
+            return;
+        }
+        this.#tasks.delete(record.id);
+        this.#liveTasks.set(record.id, record);
+    }
+    /**
+     * Follow a task's waits from its written record: a wait holds the ended records of its `on` until the task, after
+     * leaving the wait, changes again (or ends), as the phase that resumes reads their outcomes before its next commit.
+     */
+    #followWait(record) {
+        const wait = this.#waits.get(record.id);
+        if (record.state.status === "waiting") {
+            if (wait !== undefined)
+                this.#release(wait.on);
+            const on = record.state.on;
+            this.#waits.set(record.id, { on, left: false });
+            for (const id of on) {
+                let awaited = this.#awaited.get(id);
+                if (awaited === undefined) {
+                    // One that ended already moves over from the bounded table.
+                    const ended = this.#tasks.get(id);
+                    this.#tasks.delete(id);
+                    awaited = ended === undefined ? { count: 0 } : { count: 0, record: ended };
+                    this.#awaited.set(id, awaited);
+                }
+                awaited.count++;
+            }
+            return;
+        }
+        if (wait === undefined)
+            return;
+        if (!wait.left && record.state.status !== "terminal") {
+            wait.left = true;
+            return;
+        }
+        this.#waits.delete(record.id);
+        this.#release(wait.on);
+    }
+    /** A wait on `on` is over: what no other wait names goes back to the bounded table. */
+    #release(on) {
+        for (const id of on) {
+            const awaited = this.#awaited.get(id);
+            if (--awaited.count > 0)
+                continue;
+            this.#awaited.delete(id);
+            if (awaited.record !== undefined)
+                this.#tasks.set(id, awaited.record);
+        }
+    }
+    /** A published commit wrote record `id`: a read of it in flight may have missed that. */
+    #wrote(id) {
+        const reads = this.#reads.get(id);
+        if (reads !== undefined)
+            reads.version++;
+    }
+    /** Resolve with a read's result, frozen; keep a found record unless a commit published since wrote it. */
+    async #keep(id, read, keep) {
+        let reads = this.#reads.get(id);
+        if (reads === undefined) {
+            reads = { count: 0, version: 0 };
+            this.#reads.set(id, reads);
+        }
+        reads.count++;
+        const version = reads.version;
+        let value;
+        try {
+            value = await read();
+        }
+        finally {
+            if (--reads.count === 0)
+                this.#reads.delete(id);
+        }
+        if (value === undefined)
+            return undefined;
+        freeze(value);
+        if (reads.version === version)
+            keep(value);
+        return value;
+    }
+    /** Records with a read in flight, for tests that bound memory. */
+    get readsInFlight() {
+        return this.#reads.size;
+    }
+}
+/** `storage`'s publication scope (`Storage.publishing`), for a wrapper to expose as its own; none when it has none. */
+export function scopeOf(storage) {
+    if (storage.publishing === undefined)
+        return undefined;
+    return (publish, context) => storage.publishing(publish, context);
+}
+/** A Map bounded to `capacity` entries that drops the least recently used one. */
+class Lru {
+    #map = new Map();
+    #capacity;
+    constructor(capacity) {
+        this.#capacity = capacity;
+    }
+    get(key) {
+        const value = this.#map.get(key);
+        if (value === undefined)
+            return undefined;
+        this.#map.delete(key);
+        this.#map.set(key, value);
+        return value;
+    }
+    get size() {
+        return this.#map.size;
+    }
+    delete(key) {
+        this.#map.delete(key);
+    }
+    set(key, value) {
+        this.#map.delete(key);
+        this.#map.set(key, value);
+        if (this.#map.size > this.#capacity)
+            this.#map.delete(this.#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=cached-storage.js.map

package/dist/session/cached-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-storage.js","sourceRoot":"","sources":["../../src/session/cached-storage.ts"],"names":[],"mappings":"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","sourcesContent":["// Write-through cache of hot Storage record reads for the Session that owns the Storage.\nimport type { Context, JsonValue } from \"@earendil-works/chord\";\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 AnyTaskRecord = TaskRecord<JsonValue, JsonValue, JsonValue>;\ntype StoredEntry = { readonly entry: EntryRecord; readonly commitSeq: Seq };\n\n/**\n * Storage that serves hot record reads from memory: conversations, tasks, and written submissions, each table bounded\n * by a count, the least recently used record leaving first, except live tasks, which are kept until they end, and the\n * ended tasks a task waits on, kept until it moved on from its wait: a task's record is read again at each of its state\n * changes, a waiter reads the outcomes of what it waited on once it resumes (`runtime.outcomes()`), and both are\n * bounded by live work, which the scheduler keeps in memory too. Without that, a burst of more tasks than the count\n * would make each of those reads a Storage read on the line. Every commit goes through it, and one process owns a\n * Storage, so it applies each batch as it is published and never goes stale: `commit()`'s batches when the Session publishes\n * them (`published()`), not at their durability receipts. A read\n * result is kept only when no commit published since the read started wrote its record, as the read may not observe\n * that commit; versions are kept only for records with a read in flight. Cached values are frozen and shared. Entries,\n * scans, and documents pass through: the Session keeps documents and the newest entry per conversation itself, and\n * context ranges hold the entries a run reads.\n *\n * Not for a read-only Session: another process writes its Storage.\n */\nexport class CachedStorage implements Storage {\n\treadonly #storage: Storage;\n\treadonly #conversations = new Lru<ConversationId, ConversationRecord>(4096);\n\t/** Live (non-terminal) task records, until their task ends. */\n\treadonly #liveTasks = new Map<TaskId, AnyTaskRecord>();\n\t/**\n\t * Tasks some task waits on, or waited on until its wait ended and it has not moved on since: how many such waits name\n\t * each, and its ended record once it ended.\n\t */\n\treadonly #awaited = new Map<TaskId, { count: number; record?: AnyTaskRecord }>();\n\t/** Per task that waits, or left its wait and has not changed since: what it waited on, and whether it left. */\n\treadonly #waits = new Map<TaskId, { readonly on: readonly TaskId[]; left: boolean }>();\n\t// Ended task records carry inputs and outcomes, such as a tool call's arguments, so fewer are kept.\n\treadonly #tasks = new Lru<TaskId, AnyTaskRecord>(256);\n\treadonly #submissions = new Lru<SubmissionId, SubmissionRecord>(256);\n\t/** Per record with a read in flight: the reads, and how many published commits wrote it since the first began. */\n\treadonly #reads = new Map<Id<string>, { count: number; version: number }>();\n\n\tconstructor(storage: Storage) {\n\t\tthis.#storage = storage;\n\t}\n\n\t/** The backend's own scope for a publication (`Storage.publishing`), when it has one. */\n\tget publishing(): Storage[\"publishing\"] {\n\t\treturn scopeOf(this.#storage);\n\t}\n\n\t/** Pass the batches through; the Session applies each one with `published()` when it publishes it. */\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\t/**\n\t * Apply a batch `commit()` stored, when the Session publishes it. Its records are frozen in place and kept as\n\t * they are, no copies: the Session's components that follow the publication, such as the scheduler's live tasks,\n\t * hold the same objects, so a live task's record is in memory once.\n\t */\n\tpublished(writes: readonly StorageWrite[]): void {\n\t\tfor (const write of writes) {\n\t\t\tswitch (write.type) {\n\t\t\t\tcase \"conversation\":\n\t\t\t\t\tthis.#wrote(write.value.id);\n\t\t\t\t\tthis.#conversations.set(write.value.id, freeze(write.value));\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"task\":\n\t\t\t\t\tthis.#wrote(write.value.id);\n\t\t\t\t\tthis.#followWait(write.value);\n\t\t\t\t\tthis.#keepTask(freeze(write.value));\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"submission\":\n\t\t\t\t\tthis.#wrote(write.value.id);\n\t\t\t\t\tthis.#submissions.set(write.value.id, freeze(write.value));\n\t\t\t\t\tbreak;\n\t\t\t}\n\t\t}\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\tconst cached = this.#conversations.get(id);\n\t\tif (cached !== undefined) return Promise.resolve(cached);\n\t\treturn this.#keep(\n\t\t\tid,\n\t\t\t() => this.#storage.conversation(id, context),\n\t\t\t(record) => this.#conversations.set(id, record),\n\t\t);\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.#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) return this.#storage.entry(first as EntryId, second as Context);\n\t\treturn this.#storage.entry(first as ConversationId, second as EntryId, third);\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.#storage.findLatestHeadMarker(conversationId, atOrBeforeEntryId, context);\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.#storage.scanEntries(query, limit, cursor, context);\n\t}\n\n\ttask(id: TaskId, context: Context): Promise<AnyTaskRecord | undefined> {\n\t\tconst cached = this.#liveTasks.get(id) ?? this.#awaited.get(id)?.record ?? this.#tasks.get(id);\n\t\tif (cached !== undefined) return Promise.resolve(cached);\n\t\treturn this.#keep(\n\t\t\tid,\n\t\t\t() => this.#storage.task(id, context),\n\t\t\t(record) => this.#keepTask(record),\n\t\t);\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<AnyTaskRecord, Cursor>> {\n\t\treturn this.#storage.scanTasks(query, limit, cursor, context);\n\t}\n\n\t/** Cached as written only: this process writes every submission it settles, and a read one is usually settled. */\n\tsubmission(id: SubmissionId, context: Context): Promise<SubmissionRecord | undefined> {\n\t\tconst cached = this.#submissions.get(id);\n\t\treturn cached === undefined ? this.#storage.submission(id, context) : Promise.resolve(cached);\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.#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.#storage.submissionByRequest(conversationId, requestId, context);\n\t}\n\n\tfindDocument(address: DocumentAddress, at: DocumentPoint, context: Context): Promise<DocumentRecord | undefined> {\n\t\treturn this.#storage.findDocument(address, at, context);\n\t}\n\n\tdocument(id: DocumentId, at: DocumentPoint, context: Context): Promise<StoredDocument | undefined> {\n\t\treturn 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.#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/** Records kept per table, for tests that bound memory. */\n\tget sizes(): {\n\t\treadonly conversations: number;\n\t\treadonly tasks: number;\n\t\treadonly liveTasks: number;\n\t\treadonly awaited: number;\n\t\treadonly waits: number;\n\t\treadonly submissions: number;\n\t} {\n\t\treturn {\n\t\t\tconversations: this.#conversations.size,\n\t\t\ttasks: this.#tasks.size,\n\t\t\tliveTasks: this.#liveTasks.size,\n\t\t\tawaited: this.#awaited.size,\n\t\t\twaits: this.#waits.size,\n\t\t\tsubmissions: this.#submissions.size,\n\t\t};\n\t}\n\n\t/** Keep a frozen task record: a live one until its task ends, an ended one in the bounded table. */\n\t#keepTask(record: AnyTaskRecord): void {\n\t\tif (record.state.status === \"terminal\") {\n\t\t\tthis.#liveTasks.delete(record.id);\n\t\t\tconst awaited = this.#awaited.get(record.id);\n\t\t\tif (awaited !== undefined) awaited.record = record;\n\t\t\telse this.#tasks.set(record.id, record);\n\t\t\treturn;\n\t\t}\n\t\tthis.#tasks.delete(record.id);\n\t\tthis.#liveTasks.set(record.id, record);\n\t}\n\n\t/**\n\t * Follow a task's waits from its written record: a wait holds the ended records of its `on` until the task, after\n\t * leaving the wait, changes again (or ends), as the phase that resumes reads their outcomes before its next commit.\n\t */\n\t#followWait(record: AnyTaskRecord): void {\n\t\tconst wait = this.#waits.get(record.id);\n\t\tif (record.state.status === \"waiting\") {\n\t\t\tif (wait !== undefined) this.#release(wait.on);\n\t\t\tconst on = record.state.on;\n\t\t\tthis.#waits.set(record.id, { on, left: false });\n\t\t\tfor (const id of on) {\n\t\t\t\tlet awaited = this.#awaited.get(id);\n\t\t\t\tif (awaited === undefined) {\n\t\t\t\t\t// One that ended already moves over from the bounded table.\n\t\t\t\t\tconst ended = this.#tasks.get(id);\n\t\t\t\t\tthis.#tasks.delete(id);\n\t\t\t\t\tawaited = ended === undefined ? { count: 0 } : { count: 0, record: ended };\n\t\t\t\t\tthis.#awaited.set(id, awaited);\n\t\t\t\t}\n\t\t\t\tawaited.count++;\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t\tif (wait === undefined) return;\n\t\tif (!wait.left && record.state.status !== \"terminal\") {\n\t\t\twait.left = true;\n\t\t\treturn;\n\t\t}\n\t\tthis.#waits.delete(record.id);\n\t\tthis.#release(wait.on);\n\t}\n\n\t/** A wait on `on` is over: what no other wait names goes back to the bounded table. */\n\t#release(on: readonly TaskId[]): void {\n\t\tfor (const id of on) {\n\t\t\tconst awaited = this.#awaited.get(id)!;\n\t\t\tif (--awaited.count > 0) continue;\n\t\t\tthis.#awaited.delete(id);\n\t\t\tif (awaited.record !== undefined) this.#tasks.set(id, awaited.record);\n\t\t}\n\t}\n\n\t/** A published commit wrote record `id`: a read of it in flight may have missed that. */\n\t#wrote(id: Id<string>): void {\n\t\tconst reads = this.#reads.get(id);\n\t\tif (reads !== undefined) reads.version++;\n\t}\n\n\t/** Resolve with a read's result, frozen; keep a found record unless a commit published since wrote it. */\n\tasync #keep<T extends object>(\n\t\tid: Id<string>,\n\t\tread: () => Promise<T | undefined>,\n\t\tkeep: (value: T) => void,\n\t): Promise<T | undefined> {\n\t\tlet reads = this.#reads.get(id);\n\t\tif (reads === undefined) {\n\t\t\treads = { count: 0, version: 0 };\n\t\t\tthis.#reads.set(id, reads);\n\t\t}\n\t\treads.count++;\n\t\tconst version = reads.version;\n\t\tlet value: T | undefined;\n\t\ttry {\n\t\t\tvalue = await read();\n\t\t} finally {\n\t\t\tif (--reads.count === 0) this.#reads.delete(id);\n\t\t}\n\t\tif (value === undefined) return undefined;\n\t\tfreeze(value);\n\t\tif (reads.version === version) keep(value);\n\t\treturn value;\n\t}\n\n\t/** Records with a read in flight, for tests that bound memory. */\n\tget readsInFlight(): number {\n\t\treturn this.#reads.size;\n\t}\n}\n\n/** `storage`'s publication scope (`Storage.publishing`), for a wrapper to expose as its own; none when it has none. */\nexport function scopeOf(storage: Storage): Storage[\"publishing\"] {\n\tif (storage.publishing === undefined) return undefined;\n\treturn (publish, context) => storage.publishing!(publish, context);\n}\n\n/** A Map bounded to `capacity` entries that drops the least recently used one. */\nclass Lru<K, V> {\n\treadonly #map = new Map<K, V>();\n\treadonly #capacity: number;\n\n\tconstructor(capacity: number) {\n\t\tthis.#capacity = capacity;\n\t}\n\n\tget(key: K): V | undefined {\n\t\tconst value = this.#map.get(key);\n\t\tif (value === undefined) return undefined;\n\t\tthis.#map.delete(key);\n\t\tthis.#map.set(key, value);\n\t\treturn value;\n\t}\n\n\tget size(): number {\n\t\treturn this.#map.size;\n\t}\n\n\tdelete(key: K): void {\n\t\tthis.#map.delete(key);\n\t}\n\n\tset(key: K, value: V): void {\n\t\tthis.#map.delete(key);\n\t\tthis.#map.set(key, value);\n\t\tif (this.#map.size > this.#capacity) this.#map.delete(this.#map.keys().next().value!);\n\t}\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"]}