@agent-native/core 0.211.0 → 0.212.0-nightly-20261021010049

package/dist/collab/ydoc-manager.js

@@ -1,7 +1,9 @@
 import * as Y from "yjs";
+import { getDbExec } from "../db/client.js";
 import { emitCollabUpdate } from "./emitter.js";
 import { applyJsonDiff, applyJsonPatch, yDocToJson, initYDocWithJson, } from "./json-to-yjs.js";
-import { loadYDocRecord, loadYDocRecordWithClient, loadYDocVersion, trySaveYDocState, trySaveYDocStateWithClient, } from "./storage.js";
+import { applyLiveCopyUpdate, assertLiveCopy, assertOwnTransaction, commitLiveCopy, editLiveCopyState, liveCopiesDefined, liveCopyBindingFor, LiveCopyError, persistLiveCopyCall, readLiveCopyState, readStoredLiveCopy, liveCopyWriteRefused, refuseLiveCopyWrite, sameStamp, seedLiveCopyState, } from "./live-copy.js";
+import { collabStateDigest, ensureTable, loadYDocRecord, loadYDocRecordWithClient, loadYDocStamp, loadYDocVersion, saveYDocState as saveStoredYDocState, trySaveYDocState, trySaveYDocStateWithClient, } from "./storage.js";
 import { uint8ArrayToBase64 } from "./storage.js";
 import { applyTextToYDoc, initYDocWithText } from "./text-to-yjs.js";
 import { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";
@@ -46,6 +48,8 @@ export function computeTextEditDescriptor(oldText, newText) {
 const COMPACTION_RATIO = 4;
 const _cache = new Map();
 const _writeLocks = new Map();
+/** Writes holding or waiting for each document's lock. */
+const _writesPending = new Map();
 const _refreshLocks = new Map();
 const _loadLocks = new Map();
 function evictIfNeeded() {
@@ -65,7 +69,16 @@ function evictIfNeeded() {
         _cache.delete(oldest);
     }
 }
-async function withDocWriteLock(docId, fn) {
+/**
+ * Runs `fn` alone among this instance's writes to `docId`. A live copy's
+ * writes queue here, ahead of its runner, so the runner's own queue never
+ * sees them; the binding bounds them instead.
+ */
+async function withDocWriteLock(docId, fn, refusePath) {
+    // A write takes its place in line before its first await, so writes keep
+    // their call order and a slow `appliesTo` cannot let a burst past the bound.
+    const ahead = _writesPending.get(docId) ?? 0;
+    _writesPending.set(docId, ahead + 1);
     const previous = _writeLocks.get(docId) ?? Promise.resolve();
     let release;
     const current = new Promise((resolve) => {
@@ -73,15 +86,43 @@ async function withDocWriteLock(docId, fn) {
     });
     const chained = previous.catch(() => { }).then(() => current);
     _writeLocks.set(docId, chained);
-    await previous.catch(() => { });
+    // Not in `finally`: a refused write releases while earlier writes still run.
+    void chained.then(() => {
+        if (_writeLocks.get(docId) === chained)
+            _writeLocks.delete(docId);
+    });
     try {
+        if (liveCopiesDefined()) {
+            const binding = await liveCopyBindingFor(docId);
+            // Refused outright, not as a full queue a retry could get past.
+            if (binding && refusePath !== undefined) {
+                throw liveCopyWriteRefused(docId, refusePath);
+            }
+            // Before waiting: from a binding's persist, which runs in its commit's
+            // transaction, this write would wait on the lock that commit holds.
+            if (binding)
+                assertOwnTransaction(docId, "This write");
+            if (binding && ahead > binding.maxWaitingWrites) {
+                throw new LiveCopyError("build_failed", docId, `Live copy ${docId} already has ${binding.maxWaitingWrites} writes waiting; try again shortly.`, { reason: "queue_full" });
+            }
+        }
+        await previous.catch(() => { });
+        // Checked under the lock so a binding defined while this write waited
+        // still refuses it.
+        if (refusePath !== undefined) {
+            const refusal = refuseLiveCopyWrite(docId, refusePath);
+            if (refusal)
+                await refusal;
+        }
         return await fn();
     }
     finally {
         release();
-        if (_writeLocks.get(docId) === chained) {
-            _writeLocks.delete(docId);
-        }
+        const pending = (_writesPending.get(docId) ?? 1) - 1;
+        if (pending > 0)
+            _writesPending.set(docId, pending);
+        else
+            _writesPending.delete(docId);
     }
 }
 export async function withPreparedYDocMutation(docId, requestSource, run) {
@@ -133,7 +174,7 @@ export async function withPreparedYDocMutation(docId, requestSource, run) {
             candidate.destroy();
             throw error;
         }
-    });
+    }, "withPreparedYDocMutation");
 }
 function buildStateToStore(doc, storedByteCount) {
     const encoded = Y.encodeStateAsUpdate(doc);
@@ -244,7 +285,7 @@ async function loadDoc(docId) {
         _loadLocks.delete(docId);
     }
 }
-export async function getDocForWrite(docId) {
+async function getDocForWrite(docId) {
     const cached = _cache.get(docId);
     if (cached) {
         cached.lastAccess = Date.now();
@@ -257,42 +298,360 @@ async function awaitPendingWrite(docId) {
     if (pending)
         await pending.catch(() => { });
 }
-export async function getDoc(docId) {
+async function readTarget(docId) {
+    // A live copy is read from SQL, never from a write in flight here, so it
+    // skips the write lock: a binding's persist runs under that lock and may
+    // read its own document.
+    if (liveCopiesDefined()) {
+        const binding = await liveCopyBindingFor(docId);
+        if (binding)
+            return { kind: "live", binding };
+    }
     await awaitPendingWrite(docId);
+    // Looked up again: the write waited for may have made it a live copy.
+    const binding = await liveCopyBindingFor(docId);
+    if (binding)
+        return { kind: "live", binding };
     const cached = _cache.get(docId);
     if (cached) {
         cached.lastAccess = Date.now();
         await mergeNewerStoredState(docId, cached);
-        return cached.doc;
+        return { kind: "doc", doc: cached.doc };
     }
-    return loadDoc(docId);
+    return { kind: "doc", doc: await loadDoc(docId) };
+}
+/** The cached document, for callers that only read it. */
+async function readDoc(docId, path) {
+    const target = await readTarget(docId);
+    if (target.kind === "doc")
+        return target.doc;
+    throw new LiveCopyError("read_refused", docId, `Document ${docId} is a live copy, which is never decoded on the request thread, so ${path} cannot read it; use readLiveCopy or getState.`, { reason: path });
 }
+/** Refuses live copies with `read_refused`; read those with `readLiveCopy`. */
+export async function getDoc(docId) {
+    return readDoc(docId, "getDoc");
+}
+/**
+ * Commits a client update. Once any live copy is defined, the result says
+ * whether the app's rows were derived from it; with none defined it is
+ * undefined, as before live copies existed.
+ */
 export async function applyUpdate(docId, update, requestSource) {
     return withDocWriteLock(docId, async () => {
+        const liveCopy = await liveCopyBindingFor(docId);
+        if (liveCopy) {
+            return commitLiveCopyUpdate(liveCopy, docId, update, requestSource);
+        }
         const doc = await getDocForWrite(docId);
         Y.applyUpdate(doc, update);
         await persistMergedState(docId, doc, () => doc.getText(DEFAULT_FIELD).toString());
         emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+        return liveCopiesDefined()
+            ? { liveCopy: "not_derived", liveCopyReason: "not_live_copy" }
+            : undefined;
     });
 }
-function isEmptyXmlSeedTarget(fragment) {
-    if (fragment.length === 0)
-        return true;
-    if (fragment.length !== 1)
-        return false;
-    const first = fragment.get(0);
-    if (!(first instanceof Y.XmlElement) || first.nodeName !== "paragraph") {
-        return false;
+const LIVE_COPY_COMMIT_ATTEMPTS = 5;
+// An empty Yjs update: no structs, no deletions.
+const EMPTY_STATE = new Uint8Array([0, 0]);
+const EMPTY_CATCH_UP = {
+    stateVector: new Uint8Array([0]),
+    deletions: EMPTY_STATE,
+};
+// Live copies are cached as validated bytes, never as a Y.Doc.
+const _liveCopyCache = new Map();
+/** Caches the bytes `stored` holds; null caches an absent copy. */
+async function cacheLiveCopyState(binding, docId, stored, catchUp, text) {
+    const entry = {
+        binding,
+        state: stored && stored.state.length > 0 ? stored.state : EMPTY_STATE,
+        catchUp,
+        stamp: stored && {
+            version: stored.version,
+            digest: await collabStateDigest(stored.state),
+        },
+        text,
+        lastAccess: Date.now(),
+    };
+    const stale = _cache.get(docId);
+    if (stale) {
+        stale.doc.destroy();
+        _cache.delete(docId);
     }
-    for (let index = 0; index < first.length; index += 1) {
-        const child = first.get(index);
-        if (!(child instanceof Y.XmlText) || child.toString().length > 0) {
-            return false;
+    _liveCopyCache.set(docId, entry);
+    evictLiveCopyCache();
+    return entry;
+}
+function evictLiveCopyCache() {
+    if (_liveCopyCache.size <= MAX_CACHE)
+        return;
+    let oldest = null;
+    let oldestTime = Infinity;
+    for (const [id, entry] of _liveCopyCache) {
+        if (entry.lastAccess < oldestTime) {
+            oldestTime = entry.lastAccess;
+            oldest = id;
         }
     }
-    return true;
+    if (oldest)
+        _liveCopyCache.delete(oldest);
 }
-export async function seedXmlFragmentIfEmpty(docId, seedUpdate, requestSource) {
+function servedState(state) {
+    return state.length > 0 ? state.slice() : EMPTY_STATE.slice();
+}
+/**
+ * The cached entry while the row still holds the bytes it was cached from.
+ * The digest matters as much as the version: a row deleted and inserted
+ * again, by any instance, starts back at version 0.
+ */
+function cachedLiveCopy(binding, docId, stamp) {
+    const cached = _liveCopyCache.get(docId);
+    if (cached?.binding !== binding || !sameStamp(cached.stamp, stamp)) {
+        return undefined;
+    }
+    cached.lastAccess = Date.now();
+    return cached;
+}
+/** Cache misses being filled, shared by readers that saw the same row. */
+const _liveCopyLoads = new Map();
+/**
+ * The stored copy to change. When this instance cached the stored row, its
+ * bytes are used instead of re-reading it; the tasks get a copy, so a
+ * refused or conflicting attempt never touches the cache.
+ */
+async function loadLiveCopyState(binding, docId) {
+    const cached = cachedLiveCopy(binding, docId, await loadYDocStamp(docId));
+    if (cached) {
+        return cached.stamp === null
+            ? { kind: "absent" }
+            : { kind: "stored", state: cached.state, ...cached.stamp };
+    }
+    return readStoredLiveCopy(binding, getDbExec(), docId);
+}
+function stampOf(stored) {
+    return stored.kind === "absent"
+        ? null
+        : { version: stored.version, digest: stored.digest };
+}
+/**
+ * The bytes a live copy serves to editors. A version this instance has not
+ * seen is checked in the runner first, so malformed state fails here instead
+ * of reaching an editor as an empty or broken document.
+ */
+async function liveCopyStateForRead(binding, docId) {
+    await ensureTable();
+    const stamp = await loadYDocStamp(docId);
+    const cached = cachedLiveCopy(binding, docId, stamp);
+    if (cached)
+        return cached;
+    // One runner task per row, however many editors open it at once; the
+    // load reads the row again, so a joiner never gets older bytes than it saw.
+    const pending = _liveCopyLoads.get(docId);
+    if (pending?.binding === binding && sameStamp(pending.stamp, stamp)) {
+        return pending.load;
+    }
+    const load = loadLiveCopyForRead(binding, docId).finally(() => {
+        if (_liveCopyLoads.get(docId)?.load === load)
+            _liveCopyLoads.delete(docId);
+    });
+    _liveCopyLoads.set(docId, { binding, stamp, load });
+    return load;
+}
+async function loadLiveCopyForRead(binding, docId) {
+    const stored = await readStoredLiveCopy(binding, getDbExec(), docId);
+    if (stored.kind === "absent") {
+        return cacheLiveCopyState(binding, docId, null, EMPTY_CATCH_UP, null);
+    }
+    const read = await readLiveCopyState(binding, docId, stored.state, true);
+    return cacheLiveCopyState(binding, docId, stored, read.catchUp, read.kind === "live" ? read.text : null);
+}
+async function commitLiveCopyUpdate(binding, docId, update, requestSource) {
+    assertOwnTransaction(docId, "applyUpdate");
+    await ensureTable();
+    for (let attempt = 0; attempt < LIVE_COPY_COMMIT_ATTEMPTS; attempt += 1) {
+        const stored = await loadLiveCopyState(binding, docId);
+        const result = await applyLiveCopyUpdate(binding, docId, stored.kind === "absent" ? null : stored.state, update);
+        if (result.kind === "unchanged")
+            return { liveCopy: "unchanged" };
+        const previousVersion = stored.kind === "absent" ? null : stored.version;
+        const version = previousVersion === null ? 0 : previousVersion + 1;
+        const outcome = await commitLiveCopy(binding, {
+            docId,
+            origin: "update",
+            previousVersion,
+            version,
+            text: result.text,
+            state: result.state,
+            ...(requestSource ? { requestSource } : {}),
+        }, stampOf(stored));
+        if (!outcome)
+            continue;
+        await cacheLiveCopyState(binding, docId, { state: result.state, version }, result.catchUp, result.text);
+        emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+        return outcome;
+    }
+    throw new LiveCopyError("version_conflict", docId, `Live copy ${docId} kept changing while the update was being committed; it was not saved.`, { reason: String(LIVE_COPY_COMMIT_ATTEMPTS) });
+}
+/**
+ * The stored live copy and derive(state). Absent (no row), unseeded (a row
+ * with nothing in the field, including a zero-byte state) and malformed
+ * (throws `malformed_state`) are never conflated.
+ */
+export async function readLiveCopy(binding, docId) {
+    await assertLiveCopy(binding, docId);
+    const { stamp, state, text } = await liveCopyStateForRead(binding, docId);
+    if (stamp === null)
+        return { kind: "absent" };
+    if (text === null) {
+        return {
+            kind: "unseeded",
+            version: stamp.version,
+            state: servedState(state),
+        };
+    }
+    return {
+        kind: "live",
+        version: stamp.version,
+        state: servedState(state),
+        text,
+    };
+}
+/**
+ * Applies a named edit to a seeded live copy and commits it with its derived
+ * text, retrying on `_collab_docs.version` conflicts. Throws `not_seeded`
+ * for an absent or unseeded copy; seed it with `seedLiveCopy` first.
+ */
+export async function mutateLiveCopy(binding, docId, options) {
+    const maxAttempts = options.maxAttempts ?? LIVE_COPY_COMMIT_ATTEMPTS;
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {
+        throw new RangeError("mutateLiveCopy maxAttempts must be a positive integer");
+    }
+    if (typeof options.edit !== "string") {
+        throw new TypeError("mutateLiveCopy edit must name an edit in the runner's module");
+    }
+    const callPersist = options.persist;
+    if (callPersist !== undefined && typeof callPersist !== "function") {
+        throw new TypeError("mutateLiveCopy persist must be a function");
+    }
+    // Refused before joining the line: a caller's transaction waiting in it
+    // could hold rows the write ahead needs to commit.
+    assertOwnTransaction(docId, "mutateLiveCopy");
+    return withDocWriteLock(docId, async () => {
+        // In line, so a slow appliesTo cannot reorder writes or unbound them.
+        await assertLiveCopy(binding, docId);
+        await ensureTable();
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            const stored = await loadLiveCopyState(binding, docId);
+            if (stored.kind === "absent") {
+                throw new LiveCopyError("not_seeded", docId, `Live copy ${docId} is absent; seed it before editing.`, { reason: "absent" });
+            }
+            const result = await editLiveCopyState(binding, docId, stored.state, options.edit, options.input);
+            if (result.kind === "unchanged") {
+                if (callPersist &&
+                    !(await persistLiveCopyCall(binding, docId, { version: stored.version, digest: stored.digest }, (tx) => callPersist(tx, {
+                        changed: false,
+                        version: stored.version,
+                        text: result.text,
+                    })))) {
+                    continue;
+                }
+                return {
+                    changed: false,
+                    liveCopy: "unchanged",
+                    version: stored.version,
+                    state: servedState(stored.state),
+                    text: result.text,
+                    update: new Uint8Array(0),
+                    attempts: attempt,
+                };
+            }
+            const version = stored.version + 1;
+            const outcome = await commitLiveCopy(binding, {
+                docId,
+                origin: "mutation",
+                previousVersion: stored.version,
+                version,
+                text: result.text,
+                state: result.state,
+                ...(options.requestSource
+                    ? { requestSource: options.requestSource }
+                    : {}),
+            }, stampOf(stored), callPersist &&
+                ((tx) => callPersist(tx, { changed: true, version, text: result.text })));
+            if (!outcome)
+                continue;
+            await cacheLiveCopyState(binding, docId, { state: result.state, version }, result.catchUp, result.text);
+            emitCollabUpdate(docId, uint8ArrayToBase64(result.update), options.requestSource);
+            touchAgentPresence(docId, options.requestSource, {
+                descriptor: { kind: "doc" },
+            });
+            return {
+                ...outcome,
+                changed: true,
+                version,
+                state: result.state.slice(),
+                text: result.text,
+                update: result.update,
+                attempts: attempt,
+            };
+        }
+        throw new LiveCopyError("version_conflict", docId, `Live copy ${docId} kept changing during ${maxAttempts} edit attempts; the edit was not saved.`, { reason: String(maxAttempts) });
+    });
+}
+/**
+ * Seeds an absent or unseeded live copy from `source`. A live copy that
+ * already has content comes back unchanged with `seeded: false`; malformed
+ * stored state throws `malformed_state` and is never overwritten.
+ */
+export async function seedLiveCopy(binding, docId, options) {
+    assertOwnTransaction(docId, "seedLiveCopy");
+    return withDocWriteLock(docId, async () => {
+        await assertLiveCopy(binding, docId);
+        await ensureTable();
+        for (let attempt = 0; attempt < LIVE_COPY_COMMIT_ATTEMPTS; attempt += 1) {
+            const stored = await loadLiveCopyState(binding, docId);
+            const result = await seedLiveCopyState(binding, docId, stored.kind === "absent" ? null : stored.state, options.source);
+            if (result.kind === "live") {
+                if (stored.kind === "absent") {
+                    throw new LiveCopyError("build_failed", docId, `The seed task for ${docId} called an absent copy live.`, { reason: "invalid_output" });
+                }
+                return {
+                    seeded: false,
+                    liveCopy: "unchanged",
+                    version: stored.version,
+                    state: servedState(stored.state),
+                    text: result.text,
+                };
+            }
+            const previousVersion = stored.kind === "absent" ? null : stored.version;
+            const version = previousVersion === null ? 0 : previousVersion + 1;
+            const outcome = await commitLiveCopy(binding, {
+                docId,
+                origin: "seed",
+                previousVersion,
+                version,
+                text: result.text,
+                state: result.state,
+                ...(options.requestSource
+                    ? { requestSource: options.requestSource }
+                    : {}),
+            }, stampOf(stored));
+            if (!outcome)
+                continue;
+            await cacheLiveCopyState(binding, docId, { state: result.state, version }, result.catchUp, result.text);
+            emitCollabUpdate(docId, uint8ArrayToBase64(result.update), options.requestSource);
+            return {
+                ...outcome,
+                seeded: true,
+                version,
+                state: result.state.slice(),
+                text: result.text,
+            };
+        }
+        throw new LiveCopyError("version_conflict", docId, `Live copy ${docId} kept changing while its seed was being committed.`, { reason: String(LIVE_COPY_COMMIT_ATTEMPTS) });
+    });
+}
+function assertXmlFragmentSeed(seedUpdate) {
     const candidate = new Y.Doc();
     try {
         const decoded = Y.decodeUpdate(seedUpdate);
@@ -310,7 +669,33 @@ export async function seedXmlFragmentIfEmpty(docId, seedUpdate, requestSource) {
     finally {
         candidate.destroy();
     }
+}
+function isEmptyXmlSeedTarget(fragment) {
+    if (fragment.length === 0)
+        return true;
+    if (fragment.length !== 1)
+        return false;
+    const first = fragment.get(0);
+    if (!(first instanceof Y.XmlElement) || first.nodeName !== "paragraph") {
+        return false;
+    }
+    for (let index = 0; index < first.length; index += 1) {
+        const child = first.get(index);
+        if (!(child instanceof Y.XmlText) || child.toString().length > 0) {
+            return false;
+        }
+    }
+    return true;
+}
+export async function seedXmlFragmentIfEmpty(docId, seedUpdate, requestSource) {
+    // Once a live copy exists, decode only after the lock's refusal check, so
+    // a covered document never integrates a seed on this thread.
+    const validateInLock = liveCopiesDefined();
+    if (!validateInLock)
+        assertXmlFragmentSeed(seedUpdate);
     return withDocWriteLock(docId, async () => {
+        if (validateInLock)
+            assertXmlFragmentSeed(seedUpdate);
         for (let attempt = 0; attempt < 5; attempt += 1) {
             const stored = await loadYDocRecord(docId);
             const committed = new Y.Doc();
@@ -344,7 +729,7 @@ export async function seedXmlFragmentIfEmpty(docId, seedUpdate, requestSource) {
             }
         }
         throw new CollabBaseVersionConflictError(`Document ${docId} kept changing while its initial XmlFragment seed was being committed.`);
-    });
+    }, "seedXmlFragmentIfEmpty");
 }
 export async function applyText(docId, newText, fieldName = DEFAULT_FIELD, requestSource, options = {}) {
     return withDocWriteLock(docId, async () => {
@@ -381,7 +766,7 @@ export async function applyText(docId, newText, fieldName = DEFAULT_FIELD, reque
             descriptor: computeTextEditDescriptor(oldText, newText),
         });
         return doc.getText(fieldName).toString();
-    });
+    }, "applyText");
 }
 export async function searchAndReplace(docId, find, replace, requestSource) {
     return withDocWriteLock(docId, async () => {
@@ -409,19 +794,33 @@ export async function searchAndReplace(docId, find, replace, requestSource) {
             },
         });
         return { found: true, update };
-    });
+    }, "searchAndReplace");
 }
 export async function getText(docId, fieldName = DEFAULT_FIELD) {
-    const doc = await getDoc(docId);
+    const doc = await readDoc(docId, "getText");
     return doc.getText(fieldName).toString();
 }
 export async function getState(docId) {
-    const doc = await getDoc(docId);
-    return Y.encodeStateAsUpdate(doc);
+    const target = await readTarget(docId);
+    if (target.kind === "doc")
+        return Y.encodeStateAsUpdate(target.doc);
+    return (await liveCopyStateForRead(target.binding, docId)).state.slice();
 }
 export async function getIncUpdate(docId, clientStateVector) {
-    const doc = await getDoc(docId);
-    return Y.encodeStateAsUpdate(doc, clientStateVector);
+    const target = await readTarget(docId);
+    if (target.kind === "doc") {
+        return Y.encodeStateAsUpdate(target.doc, clientStateVector);
+    }
+    const { state, catchUp } = await liveCopyStateForRead(target.binding, docId);
+    // Diffing against the client's vector would decode the copy on this
+    // thread. A client at the same vector lacks at most deletions; any other
+    // gets the whole state, which Yjs applies idempotently.
+    return sameBytes(clientStateVector, catchUp.stateVector)
+        ? catchUp.deletions.slice()
+        : state.slice();
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.every((byte, index) => byte === b[index]);
 }
 export async function seedFromText(docId, text, fieldName = DEFAULT_FIELD, client) {
     return withDocWriteLock(docId, async () => {
@@ -458,7 +857,7 @@ export async function seedFromText(docId, text, fieldName = DEFAULT_FIELD, clien
             lastAccess: Date.now(),
             syncedVersion: existing ? existing.version + 1 : 0,
         });
-    });
+    }, "seedFromText");
 }
 export async function applyJson(docId, newJson, fieldName = "data", _type = "map", requestSource) {
     return withDocWriteLock(docId, async () => {
@@ -469,7 +868,7 @@ export async function applyJson(docId, newJson, fieldName = "data", _type = "map
         await persistMergedState(docId, doc, () => JSON.stringify(yDocToJson(doc, fieldName)));
         emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
         touchAgentPresence(docId, requestSource, { descriptor: { kind: "doc" } });
-    });
+    }, "applyJson");
 }
 export async function applyPatchOps(docId, ops, fieldName = "data", requestSource) {
     return withDocWriteLock(docId, async () => {
@@ -485,10 +884,10 @@ export async function applyPatchOps(docId, ops, fieldName = "data", requestSourc
                 paths: ops.slice(0, 5).map((op) => op.path),
             },
         });
-    });
+    }, "applyPatchOps");
 }
 export async function getJson(docId, fieldName = "data") {
-    const doc = await getDoc(docId);
+    const doc = await readDoc(docId, "getJson");
     return yDocToJson(doc, fieldName);
 }
 export async function seedFromJson(docId, json, fieldName = "data", type = "map", client) {
@@ -526,9 +925,19 @@ export async function seedFromJson(docId, json, fieldName = "data", type = "map"
             lastAccess: Date.now(),
             syncedVersion: existing ? existing.version + 1 : 0,
         });
-    });
+    }, "seedFromJson");
+}
+/** Overwrites a document's stored state and text. Refuses live copies. */
+export function saveYDocState(docId, state, textSnapshot) {
+    if (!liveCopiesDefined()) {
+        return saveStoredYDocState(docId, state, textSnapshot);
+    }
+    // Refused under the lock: checked outside it, a seed that makes the
+    // document a live copy could land between the check and this overwrite.
+    return withDocWriteLock(docId, () => saveStoredYDocState(docId, state, textSnapshot), "saveYDocState");
 }
 export function releaseDoc(docId) {
+    _liveCopyCache.delete(docId);
     const entry = _cache.get(docId);
     if (entry) {
         entry.doc.destroy();

package/dist/db/client.d.ts

@@ -165,5 +165,11 @@ export declare function createDbExec(config?: DbExecConfig): Promise<DbExec>;
 export declare function annotateMissingTable(err: unknown, sql: unknown): unknown;
 export declare function withDbExec<T>(exec: DbExec, run: () => T): T;
 export declare function getScopedDbExec(): DbExec | undefined;
+/**
+ * True while a `getDbExec().transaction()` callback runs. That callback leaves
+ * `getScopedDbExec()` unset, so code that must not run inside a caller's
+ * transaction asks this as well.
+ */
+export declare function insideDbTransactionCallback(): boolean;
 export declare function getDbExec(): DbExec;
 export declare function closeDbExec(): Promise<void>;