@earendil-works/pi-durable 1.3.0 → 1.5.0

package/dist/session/transaction.d.ts

@@ -1,7 +1,7 @@
 import { type Context, type Draft, type JsonValue } from "@earendil-works/chord";
-import { type Tracker } from "@earendil-works/chord/delta";
+import { type Op, type PendingOps, type Tracker } from "@earendil-works/chord/delta";
 import { type AnyDocDefinition } from "../documents.ts";
-import type { ConversationDocFamilyToken, ConversationDocToken, ConversationId, ConversationOwnership, ConversationQuery, ConversationRecord, Cursor, DocumentAddress, DocumentCommitChange, DocumentId, DocumentRecord, Entry, EntryDraft, EntryId, EntryQuery, EntryRecord, JsonObject, Seq, SessionDocFamilyToken, SessionDocToken, Storage, StorageWrite, SubmissionCreate, SubmissionId, SubmissionRecord, SubmissionSettlement, Task, TaskDocFamilyToken, TaskDocToken, TaskId, TaskOptions, TaskQuery, TaskRecord, Tx, TypedEntry, TypedEntryDraft } from "../types.ts";
+import type { ConversationDocFamilyToken, ConversationDocToken, ConversationId, ConversationOwnership, ConversationQuery, ConversationRecord, Cursor, DocumentAddress, DocumentCommitChange, DocumentContent, DocumentId, DocumentRecord, Entry, EntryDraft, EntryId, EntryQuery, EntryRecord, JsonObject, Seq, SessionDocFamilyToken, SessionDocToken, Storage, StorageWrite, SubmissionCreate, SubmissionId, SubmissionRecord, SubmissionSettlement, Task, TaskDocFamilyToken, TaskDocToken, TaskId, TaskOptions, TaskQuery, TaskRecord, Tx, TypedEntry, TypedEntryDraft } from "../types.ts";
 type AnyTaskRecord = TaskRecord<JsonValue, JsonValue, JsonValue>;
 /** One committed document incarnation owned by the Session tracker cache. */
 export type LoadedDocument = {
@@ -15,9 +15,29 @@ export type LoadedDocument = {
     deltasSinceBase: number;
     readonly tracker: Tracker<JsonObject>;
 };
+/**
+ * The changes of a cached incarnation that deferred commits adopted in memory and the Session has not stored yet
+ * (`CommitPersistence`), folded. The Session owns it; a commit that stores them takes them.
+ */
+export type HeldDocument = {
+    readonly loaded: LoadedDocument;
+    readonly pending: PendingOps;
+    /** Set when a held commit selected a base (`checkpointWhen`): their store writes the whole value. */
+    base: boolean;
+};
+/** What adoption publishes: to the Session's own observers, and the stored changes to `observeCommits()`. */
+export type AdoptedDocuments = {
+    /** This commit's own changes, as memory adopted them. */
+    readonly observed: readonly DocumentCommitChange[];
+    /** What Storage got: `observed`, unless the commit also stored held changes, which precede its own. */
+    readonly stored: readonly DocumentCommitChange[];
+};
 /** Session services used by a transaction while it holds the mutation line. */
 export interface TransactionHost {
+    /** Reads wait while their key has an unpublished writer (`GatedStorage`). */
     readonly storage: Storage;
+    /** Wait while `key` has an unpublished writer; `undefined` when it has none. */
+    touch(key: string): Promise<void> | undefined;
     /** Wall clock for task lifecycle times. */
     now(): number;
     /** Return the cached current incarnation without loading. */
@@ -30,7 +50,21 @@ export interface TransactionHost {
     evict(addressId: string, recordId: DocumentId): void;
     /** Stage writes that belong to every newly created or forked conversation, in its creating transaction. */
     conversationCreated(tx: Transaction, record: ConversationRecord): Promise<void>;
+    /** The newest entry ID visible from a conversation, known from the Session's commits. */
+    latestEntryId(conversationId: ConversationId, context: Context): Promise<EntryId | undefined>;
+    /**
+     * The current documents of a live task when the Session knows all of them (it created the task), else `undefined`.
+     */
+    taskDocuments(taskId: TaskId): Iterable<DocumentRecord> | undefined;
+    /** The newest visible head marker of a conversation, known from the Session's commits. */
+    latestHeadMarker(conversationId: ConversationId, context: Context): Promise<(EntryRecord & {
+        readonly head: EntryId;
+    }) | undefined>;
 }
+/** Internal run creation resolves submission carriers against staged records before reading storage. */
+export type TaskCreationOptions = TaskOptions & {
+    readonly submissionIds?: readonly SubmissionId[];
+};
 /** Defaults a commit binds to: `tx.createTask()` conversation and the task attributed to appended entries. */
 export type TransactionScope = {
     readonly conversationId?: ConversationId;
@@ -46,6 +80,15 @@ export type TransactionScope = {
 export declare class Transaction implements Tx {
     #private;
     constructor(host: TransactionHost, context: Context, scope?: TransactionScope);
+    /** Internal: the context of the commit this transaction belongs to. */
+    get context(): Context;
+    /** Internal: whether a table write was staged, after which table reads throw `ReadAfterWrite`. */
+    get hasTableWrite(): boolean;
+    /**
+     * Internal: whether `tx` is a transaction of a commit of the Session behind `host`. A brand check, so a proxy or
+     * another wrapper of a transaction is not one.
+     */
+    static ownedBy(tx: Tx, host: TransactionHost): tx is Transaction;
     conversation(id: ConversationId): Promise<ConversationRecord | undefined>;
     entry(id: EntryId): Promise<EntryRecord | undefined>;
     entry<D extends JsonValue>(token: Entry<D>, id: EntryId): Promise<TypedEntry<D> | undefined>;
@@ -55,6 +98,7 @@ export declare class Transaction implements Tx {
     latestHeadMarker(conversationId: ConversationId): Promise<(EntryRecord & {
         readonly head: EntryId;
     }) | undefined>;
+    latestEntryId(conversationId: ConversationId): Promise<EntryId | undefined>;
     scanTasks(query: TaskQuery, limit: number, cursor?: Cursor): Promise<import("../types.ts").Page<TaskRecord<JsonValue, JsonValue, JsonValue>, Readonly<Record<string, JsonValue>>>>;
     /** Internal: committed submission record. */
     submission(id: SubmissionId): Promise<SubmissionRecord | undefined>;
@@ -72,7 +116,7 @@ export declare class Transaction implements Tx {
     appendEntry<D extends JsonValue>(token: Entry<D>, conversationId: ConversationId, value: TypedEntryDraft<NoInfer<D>>): Promise<TypedEntry<D>>;
     createTask<I, S extends {
         phase: string;
-    }, R, H extends object>(task: Task<I, S, R, H>, input: I, options: TaskOptions): Promise<TaskId<R>>;
+    }, R, H extends object>(task: Task<I, S, R, H>, input: I, options: TaskCreationOptions): Promise<TaskId<R>>;
     /** Create a raw submission record with a fresh ID; no admission rules apply. */
     createSubmission(create: SubmissionCreate): Promise<SubmissionRecord>;
     /**
@@ -86,6 +130,8 @@ export declare class Transaction implements Tx {
     setTask(value: AnyTaskRecord): void;
     /** Internal: candidate records of the tasks this transaction created or replaced so far. */
     stagedTasks(): AnyTaskRecord[];
+    /** Internal: IDs of the tasks this transaction creates. */
+    createdTaskIds(): TaskId[];
     /** Internal: conversations this transaction created or forked so far. */
     stagedConversations(): ConversationRecord[];
     doc<T extends JsonObject>(token: SessionDocToken<T>): Promise<Draft<T>>;
@@ -109,8 +155,44 @@ export declare class Transaction implements Tx {
     settleSuccess(): Promise<readonly StorageWrite[]>;
     /** Abort every prepared change after Storage failure or when no write is required. */
     discard(): void;
+    /**
+     * Internal: what a deferred commit holds in memory instead of storing (`CommitPersistence`), each changed incarnation
+     * with its operations and whether they selected a base; `undefined` when the commit must be stored. It may be held
+     * only when every write changes an existing `latest`, `initial`-fork conversation document at its stored version.
+     */
+    holdable(): {
+        readonly loaded: LoadedDocument;
+        readonly ops: readonly Op[];
+        readonly base: boolean;
+    }[] | undefined;
+    /**
+     * Internal: adopt a held commit (`holdable()`) in memory only. Trackers advance by pointer swap; stored versions and
+     * delta counts stay, as nothing was stored. Returns its publication for the Session's own observers.
+     */
+    adoptHeld(): DocumentCommitChange[];
+    /**
+     * Internal: store the held changes of every incarnation this commit reads or writes in front of its own, so a stored
+     * document never misses an operation its later ones build on. Called right before Storage admission, after every
+     * fallible step, because it empties the holds: a failure earlier keeps them. Returns the holds it took.
+     */
+    takeHeld<H extends HeldDocument>(held: (id: DocumentId) => H | undefined): H[];
+    /**
+     * Internal: the keys this commit writes, once settled (and after `takeHeld()`), for the Session's unpublished write
+     * set: its table records, and the address and incarnation of every document it creates, changes, or retires, with
+     * the scope of every incarnation it creates or retires.
+     */
+    writeKeys(): string[];
     /** Adopt every prepared change by pointer swap after Storage success and describe the publication. */
-    adopt(seq: Seq): DocumentCommitChange[];
+    adopt(seq: Seq): AdoptedDocuments;
 }
+/**
+ * Take a hold's changes after `ops`, a commit's own on top of them, as one stored content for an incarnation now at
+ * `value`, and the operations a reader of the stored state applies to reach it: the folded ones, or a root replacement
+ * after the queue overflowed, which stores a base, as does a hold whose commits selected one.
+ */
+export declare function storeHeld(hold: HeldDocument, ops: readonly Op[], value: JsonObject, version: number): {
+    readonly content: DocumentContent;
+    readonly ops: readonly Op[];
+};
 export {};
 //# sourceMappingURL=transaction.d.ts.map

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

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

package/dist/session/transaction.js

@@ -1,12 +1,14 @@
 import { copyJson } from "@earendil-works/chord";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { track } from "@earendil-works/chord/delta";
 import { addressId, checkRecordScope, checkRecordVersion, documentCreate, materializeDocumentValue, resolveAddress, } from "../documents.js";
 import { ReadAfterWrite } from "../errors.js";
 import { ROOT_CONVERSATION_ID } from "../types.js";
 import { prepareForkDocumentCopies } from "./forks.js";
+import { documentKey, incarnationKey, scopeKey, tableKeys } from "./keys.js";
 /**
- * Complete record after applying one change. Placement turns a queued input `placed` and a queued write `done`; only a
- * placed input can be answered. A settled record stays.
+ * Complete record after applying one change. Placement turns a queued input `placed` and a queued write `done`; a
+ * continue is never queued, so never placed. Only a placed input or continue can be answered. A settled record stays.
  */
 function applySubmissionChange(current, change) {
     if (current.status === "done" || current.status === "unanswered")
@@ -18,7 +20,7 @@ function applySubmissionChange(current, change) {
         return { ...current, status, entry: change.entry };
     }
     if (change.status === "done" && current.status !== "placed") {
-        throw new Error(`Submission ${current.id} is not a placed input`);
+        throw new Error(`Submission ${current.id} is not a placed input or continue`);
     }
     // Queued and placed records carry no answer, reason, or detail; an unanswered input keeps its entry.
     return { ...current, ...change };
@@ -61,6 +63,21 @@ export class Transaction {
         this.#context = context;
         this.#scope = scope;
     }
+    /** Internal: the context of the commit this transaction belongs to. */
+    get context() {
+        return this.#context;
+    }
+    /** Internal: whether a table write was staged, after which table reads throw `ReadAfterWrite`. */
+    get hasTableWrite() {
+        return this.#hasTableWrite;
+    }
+    /**
+     * Internal: whether `tx` is a transaction of a commit of the Session behind `host`. A brand check, so a proxy or
+     * another wrapper of a transaction is not one.
+     */
+    static ownedBy(tx, host) {
+        return #host in tx && tx.#host === host;
+    }
     // ─── Table reads ────────────────────────────────────────────────────────
     conversation(id) {
         return this.#read("conversation", () => this.#host.storage.conversation(id, this.#context));
@@ -83,7 +100,10 @@ export class Transaction {
         return this.#read("scanEntries", () => this.#host.storage.scanEntries(query, limit, cursor, this.#context));
     }
     latestHeadMarker(conversationId) {
-        return this.#read("latestHeadMarker", () => this.#host.storage.findLatestHeadMarker(conversationId, undefined, this.#context));
+        return this.#read("latestHeadMarker", () => this.#host.latestHeadMarker(conversationId, this.#context));
+    }
+    latestEntryId(conversationId) {
+        return this.#read("latestEntryId", () => this.#host.latestEntryId(conversationId, this.#context));
     }
     scanTasks(query, limit, cursor) {
         return this.#read("scanTasks", () => this.#host.storage.scanTasks(query, limit, cursor, this.#context));
@@ -173,6 +193,21 @@ export class Transaction {
     }
     createTask(task, input, options) {
         return this.#write(async () => {
+            if (options.submissionIds !== undefined) {
+                let trace;
+                let links;
+                for (let index = 0; index < options.submissionIds.length; index++) {
+                    const id = options.submissionIds[index];
+                    const submission = this.#submissions.get(id) ?? (await this.#host.storage.submission(id, this.#context));
+                    if (index === 0)
+                        trace = submission?.trace ?? "root";
+                    else if (submission?.trace !== undefined) {
+                        links ??= [];
+                        links.push(submission.trace);
+                    }
+                }
+                options = { ...options, trace, links };
+            }
             const ownership = options.ownership;
             let owner;
             if (ownership.kind === "task") {
@@ -202,6 +237,10 @@ export class Transaction {
                 kind: definition.name,
                 version: definition.version,
                 input,
+                trace: options.trace === "root"
+                    ? undefined
+                    : (options.trace ?? this.#context.telemetry.propagation?.inject(this.#context.telemetry)),
+                links: options.links,
                 ...(owner === undefined ? {} : { owner: owner.id }),
                 background: options.background ?? false,
                 abortRequested: false,
@@ -264,6 +303,14 @@ export class Transaction {
                 records.push(task.write.record);
         return records;
     }
+    /** Internal: IDs of the tasks this transaction creates. */
+    createdTaskIds() {
+        const ids = [];
+        for (const [id, task] of this.#tasksById)
+            if (task.write?.kind === "create")
+                ids.push(id);
+        return ids;
+    }
     /** Internal: conversations this transaction created or forked so far. */
     stagedConversations() {
         const records = [];
@@ -394,6 +441,9 @@ export class Transaction {
         return entry.change.state;
     }
     async #findRetirement(entry) {
+        const gate = this.#host.touch(documentKey(entry.addressId));
+        if (gate !== undefined)
+            await gate;
         const record = this.#host.cached(entry.addressId)?.record ??
             (await this.#host.storage.findDocument(entry.address, "current", this.#context));
         this.#assertOpen();
@@ -408,6 +458,7 @@ export class Transaction {
         this.#sealed = true;
         this.#abortChanges();
         await Promise.allSettled(this.#pendingOperations);
+        this.#context = BACKGROUND_CONTEXT;
     }
     /**
      * Seal after callback success, prepare every open change, and assemble the atomic batch.
@@ -418,6 +469,7 @@ export class Transaction {
         if (this.#pendingOperations.size > 0) {
             this.#abortChanges();
             await Promise.allSettled(this.#pendingOperations);
+            this.#context = BACKGROUND_CONTEXT;
             throw new Error("Session commit callback settled before its pending Tx operations");
         }
         try {
@@ -432,14 +484,134 @@ export class Transaction {
             this.#abortChanges();
             throw error;
         }
+        finally {
+            this.#context = BACKGROUND_CONTEXT;
+        }
     }
     /** Abort every prepared change after Storage failure or when no write is required. */
     discard() {
         this.#abortChanges();
     }
+    /**
+     * Internal: what a deferred commit holds in memory instead of storing (`CommitPersistence`), each changed incarnation
+     * with its operations and whether they selected a base; `undefined` when the commit must be stored. It may be held
+     * only when every write changes an existing `latest`, `initial`-fork conversation document at its stored version.
+     */
+    holdable() {
+        if (this.#writes.some((write) => write.type !== "document.change"))
+            return undefined;
+        const held = [];
+        for (const plan of this.#plans) {
+            const { content, change } = plan;
+            if (content === undefined && !plan.retire)
+                continue;
+            if (plan.retire || change?.loaded === undefined || content?.type !== "document.change")
+                return undefined;
+            const { loaded, prepared, version } = change;
+            const record = loaded.record;
+            if (record.scope.kind !== "conversation" || record.history !== "latest" || record.fork !== "initial") {
+                return undefined;
+            }
+            // A migration stores a base at once.
+            if (loaded.storedVersion !== version)
+                return undefined;
+            held.push({ loaded, ops: prepared.ops, base: content.content.kind === "base" });
+        }
+        return held;
+    }
+    /**
+     * Internal: adopt a held commit (`holdable()`) in memory only. Trackers advance by pointer swap; stored versions and
+     * delta counts stay, as nothing was stored. Returns its publication for the Session's own observers.
+     */
+    adoptHeld() {
+        const publications = [];
+        for (const plan of this.#plans) {
+            // Every plan of a held commit changes or reads a loaded incarnation (`holdable()`).
+            const { tracker, prepared, version, loaded } = plan.change;
+            if (prepared.ops.length === 0) {
+                prepared.abort();
+                continue;
+            }
+            tracker.adopt(prepared);
+            const record = loaded.record;
+            const conversationId = plan.conversationId;
+            publications.push({
+                type: "document",
+                kind: "change",
+                record,
+                conversationId,
+                version,
+                value: prepared.value,
+                ops: prepared.ops,
+            });
+        }
+        return publications;
+    }
+    /**
+     * Internal: store the held changes of every incarnation this commit reads or writes in front of its own, so a stored
+     * document never misses an operation its later ones build on. Called right before Storage admission, after every
+     * fallible step, because it empties the holds: a failure earlier keeps them. Returns the holds it took.
+     */
+    takeHeld(held) {
+        const taken = [];
+        for (const plan of this.#plans) {
+            // A new incarnation holds nothing yet.
+            if (!("createdAt" in plan.record))
+                continue;
+            const hold = held(plan.record.id);
+            if (hold === undefined)
+                continue;
+            taken.push(hold);
+            const own = plan.content?.type === "document.change" ? plan.content : undefined;
+            const change = plan.change;
+            const value = change?.prepared.value ?? hold.loaded.tracker.value;
+            const stored = storeHeld(hold, change?.prepared.ops ?? EMPTY_OPERATIONS, value, hold.loaded.valueVersion);
+            // A base this commit selected or must write covers what was held.
+            const content = own?.content.kind === "base" ? own.content : stored.content;
+            const write = { type: "document.change", id: plan.record.id, content };
+            if (own !== undefined)
+                this.#writes[this.#writes.indexOf(own)] = write;
+            else
+                this.#insertBeforeRetirement(write);
+            if (!plan.retire)
+                plan.held = { ops: stored.ops, observed: own !== undefined };
+            plan.content = write;
+            // Held documents are conversation documents; one this commit only read has no owner resolved yet.
+            if (plan.record.scope.kind === "conversation")
+                plan.conversationId = plan.record.scope.conversationId;
+        }
+        return taken;
+    }
+    /**
+     * Internal: the keys this commit writes, once settled (and after `takeHeld()`), for the Session's unpublished write
+     * set: its table records, and the address and incarnation of every document it creates, changes, or retires, with
+     * the scope of every incarnation it creates or retires.
+     */
+    writeKeys() {
+        const keys = [];
+        tableKeys(this.#writes, keys);
+        for (const plan of this.#plans) {
+            if (plan.content === undefined && !plan.retire)
+                continue;
+            keys.push(documentKey(plan.addressId), incarnationKey(plan.record.id));
+            if (plan.retire || !("createdAt" in plan.record))
+                keys.push(scopeKey(plan.record.scope));
+        }
+        return keys;
+    }
+    /** Stage a content write for an incarnation, before its retirement when it retires. */
+    #insertBeforeRetirement(write) {
+        const at = this.#writes.findIndex((candidate) => candidate.type === "document.retire" && candidate.id === write.id);
+        if (at < 0)
+            this.#writes.push(write);
+        else
+            this.#writes.splice(at, 0, write);
+    }
     /** Adopt every prepared change by pointer swap after Storage success and describe the publication. */
     adopt(seq) {
         const publications = [];
+        // Only when the commit stored held changes: then what Storage got differs from what memory adopted.
+        let stored;
         for (const plan of this.#plans) {
             const committed = "createdAt" in plan.record;
             let record = committed ? plan.record : { ...plan.record, createdAt: seq };
@@ -474,34 +646,26 @@ export class Transaction {
                     });
                 }
             }
-            const conversationId = plan.conversationId;
-            if (plan.retire) {
-                if (committed)
-                    this.#host.evict(plan.addressId, record.id);
-                const retired = { version: undefined, value: null, ops: EMPTY_OPERATIONS };
-                publications.push({ type: "document", record, conversationId, ...retired });
-            }
-            else if (plan.content?.type === "document.copy") {
-                publications.push({
-                    type: "document.copy",
-                    record,
-                    conversationId: conversationId,
-                    source: plan.content.source,
-                });
-            }
-            else if (change !== undefined && publishes(plan)) {
-                const ops = change.loaded === undefined ? EMPTY_OPERATIONS : change.prepared.ops;
-                publications.push({
-                    type: "document",
-                    record,
-                    conversationId,
-                    version: change.version,
-                    value: change.prepared.value,
-                    ops,
-                });
+            if (plan.retire && committed)
+                this.#host.evict(plan.addressId, record.id);
+            const publication = describe(plan, record);
+            if (publication === undefined)
+                continue;
+            const held = plan.held;
+            if (held === undefined) {
+                publications.push(publication);
+                stored?.push(publication);
+                continue;
             }
+            stored ??= [...publications];
+            if (held.observed)
+                publications.push(publication);
+            // Only a document change of a loaded incarnation carries held operations; a retirement is published alone.
+            stored.push(publication.type === "document" && publication.kind === "change"
+                ? { ...publication, ops: held.ops }
+                : publication);
         }
-        return publications;
+        return { observed: publications, stored: stored ?? publications };
     }
     async #assemble() {
         const storage = this.#host.storage;
@@ -540,18 +704,30 @@ export class Transaction {
                 plan.retire = true;
                 retiring.add(plan.record.id);
             }
+            const retire = (record) => {
+                if (retiring.has(record.id))
+                    return;
+                plans.push({ addressId: addressId(record), record, retire: true });
+                retiring.add(record.id);
+            };
             for (const taskId of terminalTaskIds) {
                 if (this.#tasksById.get(taskId)?.write?.kind === "create")
                     continue;
+                // The Session knows the documents of the tasks it created; any other task's are scanned.
+                const gate = this.#host.touch(scopeKey({ kind: "task", taskId }));
+                if (gate !== undefined)
+                    await gate;
+                const known = this.#host.taskDocuments(taskId);
+                if (known !== undefined) {
+                    for (const record of known)
+                        retire(record);
+                    continue;
+                }
                 let cursor;
                 do {
                     const page = await storage.scanDocuments({ scope: { kind: "task", taskId }, at: "current" }, INTERNAL_SCAN_PAGE_SIZE, cursor, this.#context);
-                    for (const record of page.items) {
-                        if (retiring.has(record.id))
-                            continue;
-                        plans.push({ addressId: addressId(record), record, retire: true });
-                        retiring.add(record.id);
-                    }
+                    for (const record of page.items)
+                        retire(record);
                     cursor = page.next;
                 } while (cursor !== undefined);
             }
@@ -594,7 +770,7 @@ export class Transaction {
             if (plan.content?.type === "document.change" && plan.content.content.kind === "delta" && change?.loaded) {
                 const { prepared, version } = change;
                 const info = { deltasSinceBase: change.loaded.deltasSinceBase };
-                if (change.definition?.checkpointWhen?.(prepared.value, prepared.ops, info)) {
+                if (change.definition.checkpointWhen(prepared.value, prepared.ops, info)) {
                     plan.content = { ...plan.content, content: { version, kind: "base", value: prepared.value } };
                 }
             }
@@ -677,7 +853,7 @@ export class Transaction {
         try {
             this.#assertOpen();
             if (this.#hasTableWrite)
-                throw new ReadAfterWrite(method);
+                throw new ReadAfterWrite(`Tx.${method}()`);
             return this.#track(read());
         }
         catch (error) {
@@ -785,6 +961,42 @@ function planDocument(document) {
         }
     }
 }
+/** The publication of one adopted plan, if it publishes (`publishes()`), with `record` as committed. */
+function describe(plan, record) {
+    const conversationId = plan.conversationId;
+    if (plan.retire)
+        return { type: "document", kind: "retire", record, conversationId };
+    if (plan.content?.type === "document.copy") {
+        return { type: "document.copy", record, conversationId: conversationId, source: plan.content.source };
+    }
+    const change = plan.change;
+    if (change === undefined || !publishes(plan))
+        return undefined;
+    const ops = change.loaded === undefined ? EMPTY_OPERATIONS : change.prepared.ops;
+    return {
+        type: "document",
+        kind: "change",
+        record,
+        conversationId,
+        version: change.version,
+        value: change.prepared.value,
+        ops,
+    };
+}
+/**
+ * Take a hold's changes after `ops`, a commit's own on top of them, as one stored content for an incarnation now at
+ * `value`, and the operations a reader of the stored state applies to reach it: the folded ones, or a root replacement
+ * after the queue overflowed, which stores a base, as does a hold whose commits selected one.
+ */
+export function storeHeld(hold, ops, value, version) {
+    hold.pending.push(ops);
+    const taken = hold.pending.take();
+    if (taken.kind === "replace")
+        return { content: { version, kind: "base", value }, ops: [["r", value]] };
+    if (hold.base)
+        return { content: { version, kind: "base", value }, ops: taken.ops };
+    return { content: { version, kind: "delta", ops: taken.ops }, ops: taken.ops };
+}
 /**
  * Whether adoption publishes the plan: every creation, copy, and retirement, and a loaded incarnation that writes
  * content, which includes a migration-only base so observers of the older shape receive the new value.