@agent-native/core 0.211.0 → 0.211.1-nightly-20261020213022

package/dist/collab/live-copy.js

@@ -0,0 +1,415 @@
+import { getDbExec, getScopedDbExec, insideDbTransactionCallback, withDbExec, } from "../db/client.js";
+import { BoundedTaskError } from "./bounded-tasks.js";
+import { LIVE_COPY_TASK, } from "./live-copy-tasks.js";
+import { CollabStateMalformedError, collabStateDigest, ensureTable, loadYDocRecordStrict, loadYDocStampWithClient, trySaveYDocStateWithClient, } from "./storage.js";
+// A live copy is a collab document whose Yjs state is the only writable copy
+// of a body. Every commit derives the body's text from that state and writes
+// both in one transaction, so the stored text is always derive(live copy) at
+// the stored version. This side only moves bytes: the Yjs work runs in the
+// binding's bounded runner (see live-copy-tasks.ts).
+export const LIVE_COPY_DEFAULT_FIELD = "default";
+const DEFAULT_MAX_STATE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_WAITING_WRITES = 16;
+export class LiveCopyError extends Error {
+    code;
+    docId;
+    /**
+     * Refusal reason from the task, the malformed-state reason, the bounded
+     * task error code, or the refused path, depending on `code`.
+     */
+    reason;
+    constructor(code, docId, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "LiveCopyError";
+        this.code = code;
+        this.docId = docId;
+        if (options.reason !== undefined)
+            this.reason = options.reason;
+    }
+}
+const LIVE_COPY_BINDINGS_KEY = "__agentNativeLiveCopies__";
+const bindingsGlobal = globalThis;
+const bindings = (bindingsGlobal[LIVE_COPY_BINDINGS_KEY] ??= new Map());
+/**
+ * Declares which collab documents are live copies and how their text is
+ * derived. While a binding exists, core's other write paths (text, JSON,
+ * search-replace, prepared mutations, and the text/JSON/XML seeders) refuse
+ * documents it covers.
+ */
+export function defineLiveCopy(options) {
+    if (typeof options.name !== "string" || options.name.length === 0) {
+        throw new TypeError("defineLiveCopy needs a name");
+    }
+    if (typeof options.appliesTo !== "function") {
+        throw new TypeError("defineLiveCopy needs an appliesTo(docId) function");
+    }
+    if (!options.runner || typeof options.runner.run !== "function") {
+        throw new TypeError("defineLiveCopy needs a bounded task runner");
+    }
+    const maxStateBytes = options.maxStateBytes ?? DEFAULT_MAX_STATE_BYTES;
+    if (!Number.isFinite(maxStateBytes) || maxStateBytes <= 0) {
+        throw new RangeError("defineLiveCopy maxStateBytes must be positive");
+    }
+    const maxWaitingWrites = options.maxWaitingWrites ?? DEFAULT_MAX_WAITING_WRITES;
+    if (!Number.isSafeInteger(maxWaitingWrites) || maxWaitingWrites < 0) {
+        throw new RangeError("defineLiveCopy maxWaitingWrites must be a non-negative integer");
+    }
+    const binding = Object.freeze({
+        name: options.name,
+        appliesTo: options.appliesTo,
+        runner: options.runner,
+        field: options.field ?? LIVE_COPY_DEFAULT_FIELD,
+        maxStateBytes,
+        maxWaitingWrites,
+        ...(options.persist ? { persist: options.persist } : {}),
+    });
+    bindings.set(binding.name, binding);
+    return binding;
+}
+/** Synchronous, so a caller can keep main's behavior when none is defined. */
+export function liveCopiesDefined() {
+    return bindings.size > 0;
+}
+/**
+ * Removes a binding so its documents take ordinary collab writes again. A
+ * binding already replaced under its name leaves the replacement in place.
+ */
+export function releaseLiveCopy(binding) {
+    if (bindings.get(binding.name) === binding)
+        bindings.delete(binding.name);
+}
+export async function liveCopyBindingFor(docId) {
+    if (bindings.size === 0)
+        return null;
+    for (const binding of bindings.values()) {
+        if (await binding.appliesTo(docId))
+            return binding;
+    }
+    return null;
+}
+/**
+ * Throws `write_refused` when a live copy covers `docId`. With no binding
+ * defined it returns synchronously, so a write that has not taken its lock
+ * yet keeps its place in line.
+ */
+export function refuseLiveCopyWrite(docId, path) {
+    if (bindings.size === 0)
+        return undefined;
+    return liveCopyBindingFor(docId).then((binding) => {
+        if (binding)
+            throw liveCopyWriteRefused(docId, path);
+    });
+}
+export function liveCopyWriteRefused(docId, path) {
+    return new LiveCopyError("write_refused", docId, `Document ${docId} is a live copy; ${path} would write it without deriving its text.`, { reason: path });
+}
+export async function assertLiveCopy(binding, docId) {
+    const covers = await binding.appliesTo(docId);
+    assertActiveLiveCopy(binding, docId);
+    if (!covers) {
+        throw new LiveCopyError("not_live_copy", docId, `Document ${docId} is not a live copy for this binding.`);
+    }
+}
+/** Throws unless `binding` is still the one registered under its name. */
+export function assertActiveLiveCopy(binding, docId) {
+    if (bindings.get(binding.name) === binding)
+        return;
+    throw new LiveCopyError("not_live_copy", docId, `Live copy binding ${binding.name} was released or replaced; use the binding defineLiveCopy returned last.`, { reason: "binding_inactive" });
+}
+/**
+ * A commit updates this instance's cache and notifies connected editors as
+ * soon as it lands, so it must own its transaction: inside a caller's, a
+ * later rollback would leave editors holding state that was never saved.
+ */
+export function assertOwnTransaction(docId, path) {
+    if (getScopedDbExec() === undefined && !insideDbTransactionCallback()) {
+        return;
+    }
+    throw new LiveCopyError("write_refused", docId, `${path} was called for live copy ${docId} inside a database transaction. Call it outside the transaction, and write the app's rows in the binding's persist hook, or in mutateLiveCopy's persist option for rows that belong to one edit.`, { reason: "caller_transaction" });
+}
+/**
+ * The stored bytes, read strictly: unreadable base64 or a bad version throws
+ * `malformed_state` instead of reading as empty. The bytes are not decoded
+ * as Yjs here; the tasks do that in the runner.
+ */
+export async function readStoredLiveCopy(binding, client, docId) {
+    let record;
+    try {
+        record = await loadYDocRecordStrict(client, docId, binding.maxStateBytes);
+    }
+    catch (error) {
+        if (error instanceof CollabStateMalformedError) {
+            throw new LiveCopyError("malformed_state", docId, `Stored live copy for ${docId} is unreadable (${error.reason}).`, { reason: error.reason, cause: error });
+        }
+        throw error;
+    }
+    if (record.kind === "absent")
+        return { kind: "absent" };
+    if (record.kind === "too_large") {
+        throw new LiveCopyError("state_too_large", docId, `Stored live copy ${docId} is about ${record.bytes} bytes; the limit is ${binding.maxStateBytes}.`, { reason: String(record.bytes) });
+    }
+    assertStateSize(binding, docId, record.state, "Stored live copy");
+    return {
+        kind: "stored",
+        state: record.state,
+        version: record.version,
+        digest: await collabStateDigest(record.state),
+    };
+}
+function assertStateSize(binding, docId, state, what) {
+    if (state.length > binding.maxStateBytes) {
+        throw new LiveCopyError("state_too_large", docId, `${what} ${docId} is ${state.length} bytes; the limit is ${binding.maxStateBytes}.`, { reason: String(state.length) });
+    }
+}
+const TASK_FAILURE_CODES = new Set([
+    "malformed_state",
+    "unsupported_content",
+    "state_too_large",
+    "not_seeded",
+    "derive_refused",
+    "derive_failed",
+    "build_refused",
+    "build_failed",
+]);
+/**
+ * Runs a live-copy task and returns its result once it has a shape `kinds`
+ * allows. Runner failures become `failure` with the runner's error code as
+ * the reason; a task's typed failure becomes a `LiveCopyError` with its code.
+ */
+async function runLiveCopyTask(binding, docId, task, input, failure, kinds) {
+    let output;
+    try {
+        output = await binding.runner.run(task, {
+            ...input,
+            field: binding.field,
+            maxStateBytes: binding.maxStateBytes,
+        });
+    }
+    catch (error) {
+        if (error instanceof BoundedTaskError) {
+            throw new LiveCopyError(failure, docId, `Live copy task ${task} for ${docId} failed: ${error.message}`, { reason: error.code, cause: error });
+        }
+        throw error;
+    }
+    const result = output;
+    const kind = typeof result === "object" && result ? result.kind : undefined;
+    if (kind === "failed") {
+        const { code, reason, message } = result;
+        if (typeof code === "string" &&
+            TASK_FAILURE_CODES.has(code) &&
+            typeof reason === "string") {
+            throw new LiveCopyError(code, docId, `Live copy ${docId} ${String(message)}.`, { reason });
+        }
+    }
+    else if (typeof kind === "string" && kinds.includes(kind)) {
+        const checked = result;
+        const { state, text, update } = checked;
+        const textOk = text === undefined || typeof text === "string";
+        if (kind !== "changed" && textOk)
+            return checked;
+        if (state instanceof Uint8Array &&
+            typeof text === "string" &&
+            (update === undefined || update instanceof Uint8Array)) {
+            assertStateSize(binding, docId, state, "Live copy");
+            return checked;
+        }
+    }
+    throw new LiveCopyError(failure, docId, `Live copy task ${task} for ${docId} returned a result it may not; build the runner's module with defineLiveCopyTasks.`, { reason: "invalid_output" });
+}
+function required(docId, value, check, failure) {
+    if (check(value))
+        return value;
+    throw new LiveCopyError(failure, docId, `Live copy task for ${docId} left out part of its result.`, { reason: "invalid_output" });
+}
+const isString = (value) => typeof value === "string";
+const isBytes = (value) => value instanceof Uint8Array;
+function catchUpOf(docId, result, failure) {
+    return {
+        stateVector: required(docId, result.stateVector, isBytes, failure),
+        deletions: required(docId, result.deletions, isBytes, failure),
+    };
+}
+/** Validates stored state in the runner; derives its text when asked. */
+export async function readLiveCopyState(binding, docId, state, derive) {
+    const input = {
+        state,
+        derive,
+    };
+    const result = await runLiveCopyTask(binding, docId, LIVE_COPY_TASK.read, input, "derive_failed", ["unseeded", "live"]);
+    const catchUp = catchUpOf(docId, result, "derive_failed");
+    if (result.kind === "unseeded")
+        return { kind: "unseeded", catchUp };
+    return {
+        kind: "live",
+        text: derive
+            ? required(docId, result.text, isString, "derive_failed")
+            : null,
+        catchUp,
+    };
+}
+/** Merges a client update in the runner; null state means absent. */
+export async function applyLiveCopyUpdate(binding, docId, state, update) {
+    const input = {
+        state,
+        update,
+    };
+    const result = await runLiveCopyTask(binding, docId, LIVE_COPY_TASK.apply, input, "derive_failed", ["unchanged", "changed"]);
+    if (result.kind === "unchanged")
+        return { kind: "unchanged" };
+    return {
+        kind: "changed",
+        state: result.state,
+        text: result.text,
+        catchUp: catchUpOf(docId, result, "derive_failed"),
+    };
+}
+/** Seeds an absent or unseeded copy; a live one comes back with its text. */
+export async function seedLiveCopyState(binding, docId, state, source) {
+    const input = {
+        state,
+        source,
+    };
+    const result = await runLiveCopyTask(binding, docId, LIVE_COPY_TASK.seed, input, "build_failed", ["live", "changed"]);
+    if (result.kind === "live") {
+        return {
+            kind: "live",
+            text: required(docId, result.text, isString, "build_failed"),
+        };
+    }
+    return {
+        kind: "changed",
+        state: result.state,
+        text: result.text,
+        update: required(docId, result.update, isBytes, "build_failed"),
+        catchUp: catchUpOf(docId, result, "build_failed"),
+    };
+}
+/** Runs a named edit from the runner's module on seeded state. */
+export async function editLiveCopyState(binding, docId, state, edit, editInput) {
+    const input = {
+        state,
+        edit,
+        input: editInput,
+    };
+    const result = await runLiveCopyTask(binding, docId, LIVE_COPY_TASK.edit, input, "build_failed", ["unchanged", "changed"]);
+    if (result.kind === "unchanged") {
+        return {
+            kind: "unchanged",
+            text: required(docId, result.text, isString, "build_failed"),
+        };
+    }
+    return {
+        kind: "changed",
+        state: result.state,
+        text: result.text,
+        update: required(docId, result.update, isBytes, "build_failed"),
+        catchUp: catchUpOf(docId, result, "build_failed"),
+    };
+}
+class CommitVersionConflict extends Error {
+}
+function persistOutcome(docId, value) {
+    if (value === undefined)
+        return { liveCopy: "derived" };
+    if (typeof value === "object" && value !== null) {
+        const { derived, reason } = value;
+        if (derived === true)
+            return { liveCopy: "derived" };
+        if (derived === false && typeof reason === "string" && reason !== "") {
+            return { liveCopy: "not_derived", liveCopyReason: reason };
+        }
+    }
+    throw new TypeError(`Live copy persist for ${docId} must return nothing, { derived: true }, or { derived: false, reason }.`);
+}
+async function runLiveCopyTransaction(docId, write) {
+    const exec = getDbExec();
+    if (typeof exec.transaction !== "function") {
+        throw new LiveCopyError("write_refused", docId, `Live copy ${docId} needs a database that supports transactions.`, { reason: "no_transactions" });
+    }
+    await exec.transaction(write);
+}
+async function runCallPersist(docId, tx, persist) {
+    const value = await withDbExec(tx, () => persist(tx));
+    if (value !== undefined) {
+        throw new TypeError(`The persist passed for live copy ${docId} must return nothing.`);
+    }
+}
+export function sameStamp(a, b) {
+    return a?.version === b?.version && a?.digest === b?.digest;
+}
+/**
+ * Commits a derived state: the binding's persist hook, the caller's, then
+ * the `_collab_docs` write, in one transaction, at the row `base` names
+ * (null: no row). Returns null when another writer changed the row first;
+ * nothing is written in that case.
+ */
+export async function commitLiveCopy(binding, commit, base, callPersist) {
+    assertOwnTransaction(commit.docId, "commitLiveCopy");
+    await ensureTable();
+    let outcome = { liveCopy: "derived" };
+    try {
+        await runLiveCopyTransaction(commit.docId, async (tx) => {
+            const persist = binding.persist;
+            if (persist) {
+                // The pool's own transaction does not scope getDbExec(); without
+                // this, app helpers inside persist query a second connection,
+                // outside the row locks persist holds.
+                const value = await withDbExec(tx, () => persist(tx, commit));
+                outcome = persistOutcome(commit.docId, value);
+            }
+            if (callPersist) {
+                // The caller's persist checks the app's rows against this edit, so a
+                // peer that committed first must stop the attempt here, as a retry,
+                // not there, as a refusal. Exact once the binding's persist holds
+                // the lock every commit of the document takes.
+                const current = await loadYDocStampWithClient(tx, commit.docId);
+                if (!sameStamp(current, base))
+                    throw new CommitVersionConflict();
+                await runCallPersist(commit.docId, tx, callPersist);
+            }
+            const saved = await trySaveYDocStateWithClient(tx, commit.docId, commit.state, commit.text, base?.version ?? null, base?.digest);
+            if (!saved)
+                throw new CommitVersionConflict();
+            // After the last statement: a binding released or replaced while its
+            // work, its persist or its save ran rolls back with all of them.
+            assertActiveLiveCopy(binding, commit.docId);
+        });
+        return outcome;
+    }
+    catch (error) {
+        if (!(error instanceof CommitVersionConflict))
+            throw error;
+        // A released or replaced binding says so, not a retry that cannot help.
+        assertActiveLiveCopy(binding, commit.docId);
+        return null;
+    }
+}
+/**
+ * Runs a caller's persist by itself, for a write that committed nothing,
+ * while the copy is still the row `base` names. Returns false, with nothing
+ * written, when another writer changed it first.
+ */
+export async function persistLiveCopyCall(binding, docId, base, callPersist) {
+    assertOwnTransaction(docId, "persistLiveCopyCall");
+    try {
+        await runLiveCopyTransaction(docId, async (tx) => {
+            await runCallPersist(docId, tx, callPersist);
+            // Locked after the app's rows, as a commit locks them, and held to the
+            // end so no commit can slip in before this one lands.
+            const current = await loadYDocStampWithClient(tx, docId, {
+                forShare: true,
+            });
+            if (!sameStamp(current, base))
+                throw new CommitVersionConflict();
+            // After the last statement, as in commitLiveCopy.
+            assertActiveLiveCopy(binding, docId);
+        });
+        return true;
+    }
+    catch (error) {
+        if (!(error instanceof CommitVersionConflict))
+            throw error;
+        assertActiveLiveCopy(binding, docId);
+        return false;
+    }
+}

package/dist/collab/routes.d.ts

@@ -13,8 +13,13 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
     };
 }>>;
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
+} | {
+    liveCopy: "derived" | "not_derived" | "unchanged";
+    liveCopyReason?: string;
+    error?: undefined;
+    ok: boolean;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/routes.js

@@ -1,4 +1,5 @@
 import { defineEventHandler, setResponseStatus, setResponseHeader, getRouterParam, getQuery, getRequestHeader, } from "h3";
+import * as Y from "yjs";
 import { readBody } from "../server/h3-helpers.js";
 import { uint8ArrayToBase64, base64ToUint8Array } from "./storage.js";
 import * as manager from "./ydoc-manager.js";
@@ -16,6 +17,22 @@ function enforcePayloadLimit(event, body) {
     }
     return true;
 }
+/**
+ * The client's state vector, or null when it is not one. A vector is a flat
+ * list of clocks, read in one pass and bounded by the URL, so reading it
+ * here is not the document decode live copies keep off this thread.
+ */
+function readStateVector(encoded) {
+    try {
+        const stateVector = base64ToUint8Array(encoded);
+        Y.decodeStateVector(stateVector);
+        return stateVector;
+        // coercion-ok: null is this reader's typed "not a state vector"; the route answers 400
+    }
+    catch {
+        return null;
+    }
+}
 export const getCollabState = defineEventHandler(async (event) => {
     setResponseHeader(event, "Cache-Control", "private, no-store");
     const docId = getRouterParam(event, "docId");
@@ -39,14 +56,13 @@ export const getCollabState = defineEventHandler(async (event) => {
         }
     }
     let state;
-    if (encodedStateVector) {
-        try {
-            state = await manager.getIncUpdate(docId, base64ToUint8Array(encodedStateVector));
-        }
-        catch {
+    if (encodedStateVector !== null) {
+        const stateVector = readStateVector(encodedStateVector);
+        if (!stateVector) {
             setResponseStatus(event, 400);
-            return { error: "stateVector must be base64-encoded" };
+            return { error: "stateVector must be a base64-encoded Yjs state vector" };
         }
+        state = await manager.getIncUpdate(docId, stateVector);
     }
     else {
         state = await manager.getState(docId);
@@ -73,8 +89,8 @@ export const postCollabUpdate = defineEventHandler(async (event) => {
         return { error: "update (base64) required" };
     }
     const binary = base64ToUint8Array(update);
-    await manager.applyUpdate(docId, binary, requestSource);
-    return { ok: true };
+    const outcome = await manager.applyUpdate(docId, binary, requestSource);
+    return outcome ? { ok: true, ...outcome } : { ok: true };
 });
 export const postCollabText = defineEventHandler(async (event) => {
     const docId = getRouterParam(event, "docId");

package/dist/collab/storage.d.ts

@@ -7,10 +7,62 @@ export interface YDocStateRecord {
 }
 export declare function loadYDocRecord(docId: string): Promise<YDocStateRecord | null>;
 export declare function loadYDocRecordWithClient(client: DbExec, docId: string): Promise<YDocStateRecord | null>;
+export type CollabStateMalformedReason = "base64" | "version" | "yjs";
+/** A stored `_collab_docs` row that cannot be read. Never treat it as empty. */
+export declare class CollabStateMalformedError extends Error {
+    readonly code = "collab_state_malformed";
+    readonly docId: string;
+    readonly reason: CollabStateMalformedReason;
+    constructor(docId: string, reason: CollabStateMalformedReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Absent means no row. A row whose `yjs_state` is `''` is present with a
+ * zero-byte state; callers that seed must update it at its version rather
+ * than insert.
+ */
+export type StrictYDocRecord = {
+    kind: "absent";
+} | {
+    kind: "present";
+    state: Uint8Array;
+    version: number;
+}
+/** Longer than `maxBytes` allows; its text was never read. */
+ | {
+    kind: "too_large";
+    bytes: number;
+};
+/**
+ * Decodes canonical base64, or returns null; `Buffer` silently skips junk.
+ * A round trip instead of a pattern: a repeated-group regex overflows the
+ * stack on a few megabytes.
+ */
+export declare function strictBase64ToUint8Array(value: string): Uint8Array | null;
+export declare function loadYDocRecordStrict(client: DbExec, docId: string, maxBytes: number, options?: {
+    forUpdate?: boolean;
+}): Promise<StrictYDocRecord>;
 export declare function loadYDocVersion(docId: string): Promise<number | null>;
+/**
+ * A row's version and a SHA-256 of its stored text. A version alone repeats:
+ * a row deleted and inserted again starts back at 0.
+ */
+export interface YDocStamp {
+    version: number;
+    digest: string;
+}
+export declare function loadYDocStamp(docId: string): Promise<YDocStamp | null>;
+export declare function loadYDocStampWithClient(client: DbExec, docId: string, options?: {
+    forShare?: boolean;
+}): Promise<YDocStamp | null>;
+/** The digest `loadYDocStamp` reports for a row this module wrote `state` to. */
+export declare function collabStateDigest(state: Uint8Array): Promise<string>;
 export declare function loadYDocState(docId: string): Promise<Uint8Array | null>;
 export declare function trySaveYDocState(docId: string, state: Uint8Array, textSnapshot: string, expectedVersion: number | null): Promise<boolean>;
-export declare function trySaveYDocStateWithClient(client: DbExec, docId: string, state: Uint8Array, textSnapshot: string, expectedVersion: number | null): Promise<boolean>;
+export declare function trySaveYDocStateWithClient(client: DbExec, docId: string, state: Uint8Array, textSnapshot: string, expectedVersion: number | null, 
+/** Also requires the stored text to have this digest; see `YDocStamp`. */
+expectedDigest?: string): Promise<boolean>;
 export declare function saveYDocState(docId: string, state: Uint8Array, textSnapshot: string): Promise<void>;
 export declare function hasCollabState(docId: string): Promise<boolean>;
 export declare function deleteCollabState(docId: string): Promise<void>;

package/dist/collab/storage.js

@@ -42,6 +42,62 @@ export async function loadYDocRecordWithClient(client, docId) {
         version: Number(rows[0].version ?? 0),
     };
 }
+/** A stored `_collab_docs` row that cannot be read. Never treat it as empty. */
+export class CollabStateMalformedError extends Error {
+    code = "collab_state_malformed";
+    docId;
+    reason;
+    constructor(docId, reason, message, options) {
+        super(message, options);
+        this.name = "CollabStateMalformedError";
+        this.docId = docId;
+        this.reason = reason;
+    }
+}
+/**
+ * Decodes canonical base64, or returns null; `Buffer` silently skips junk.
+ * A round trip instead of a pattern: a repeated-group regex overflows the
+ * stack on a few megabytes.
+ */
+export function strictBase64ToUint8Array(value) {
+    let bytes;
+    try {
+        bytes = base64ToUint8Array(value);
+        // coercion-ok: null is this reader's typed "not base64"; callers raise malformed_state
+    }
+    catch {
+        return null;
+    }
+    return uint8ArrayToBase64(bytes) === value ? bytes : null;
+}
+export async function loadYDocRecordStrict(client, docId, maxBytes, options = {}) {
+    // The longest canonical base64 of maxBytes bytes. Longer text is left in
+    // the database, so a huge row costs neither the transfer nor the decode.
+    const maxLength = 4 * Math.ceil(maxBytes / 3);
+    const { rows } = await client.execute({
+        sql: `SELECT CASE WHEN length(yjs_state) <= ? THEN yjs_state END AS yjs_state, length(yjs_state) AS encoded_length, version FROM _collab_docs WHERE doc_id = ?${options.forUpdate ? " FOR UPDATE" : ""}`,
+        args: [maxLength, docId],
+    });
+    if (rows.length === 0)
+        return { kind: "absent" };
+    const encodedLength = Number(rows[0].encoded_length);
+    if (encodedLength > maxLength) {
+        return { kind: "too_large", bytes: Math.floor((encodedLength * 3) / 4) };
+    }
+    const stored = rows[0].yjs_state;
+    if (typeof stored !== "string") {
+        throw new CollabStateMalformedError(docId, "base64", `_collab_docs.yjs_state for ${docId} is not text`);
+    }
+    const state = strictBase64ToUint8Array(stored);
+    if (!state) {
+        throw new CollabStateMalformedError(docId, "base64", `_collab_docs.yjs_state for ${docId} is not valid base64`);
+    }
+    const version = Number(rows[0].version);
+    if (!Number.isSafeInteger(version) || version < 0) {
+        throw new CollabStateMalformedError(docId, "version", `_collab_docs.version for ${docId} is unreadable: ${String(rows[0].version)}`);
+    }
+    return { kind: "present", state, version };
+}
 export async function loadYDocVersion(docId) {
     await ensureTable();
     const client = getDbExec();
@@ -57,6 +113,31 @@ export async function loadYDocVersion(docId) {
     }
     return version;
 }
+const STATE_DIGEST_SQL = `encode(sha256(convert_to(yjs_state, 'UTF8')), 'hex')`;
+export async function loadYDocStamp(docId) {
+    await ensureTable();
+    return loadYDocStampWithClient(getDbExec(), docId);
+}
+export async function loadYDocStampWithClient(client, docId, options = {}) {
+    const { rows } = await client.execute({
+        sql: `SELECT version, ${STATE_DIGEST_SQL} AS digest FROM _collab_docs WHERE doc_id = ?${options.forShare ? " FOR SHARE" : ""}`,
+        args: [docId],
+    });
+    if (rows.length === 0)
+        return null;
+    const version = Number(rows[0].version);
+    const digest = rows[0].digest;
+    if (!Number.isFinite(version) || typeof digest !== "string") {
+        throw new Error(`_collab_docs row for ${docId} is unreadable: version ${String(rows[0].version)}`);
+    }
+    return { version, digest };
+}
+/** The digest `loadYDocStamp` reports for a row this module wrote `state` to. */
+export async function collabStateDigest(state) {
+    const text = new TextEncoder().encode(uint8ArrayToBase64(state));
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", text);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 export async function loadYDocState(docId) {
     const record = await loadYDocRecord(docId);
     return record?.state ?? null;
@@ -65,7 +146,9 @@ export async function trySaveYDocState(docId, state, textSnapshot, expectedVersi
     await ensureTable();
     return trySaveYDocStateWithClient(getDbExec(), docId, state, textSnapshot, expectedVersion);
 }
-export async function trySaveYDocStateWithClient(client, docId, state, textSnapshot, expectedVersion) {
+export async function trySaveYDocStateWithClient(client, docId, state, textSnapshot, expectedVersion, 
+/** Also requires the stored text to have this digest; see `YDocStamp`. */
+expectedDigest) {
     const b64 = uint8ArrayToBase64(state);
     const nowExpr = "NOW()::text";
     if (expectedVersion === null) {
@@ -75,10 +158,15 @@ export async function trySaveYDocStateWithClient(client, docId, state, textSnaps
         });
         return result.rowsAffected > 0;
     }
-    const result = await client.execute({
-        sql: `UPDATE _collab_docs SET yjs_state = ?, text_snapshot = ?, version = version + 1, updated_at = ${nowExpr} WHERE doc_id = ? AND version = ?`,
-        args: [b64, textSnapshot, docId, expectedVersion],
-    });
+    const result = await client.execute(expectedDigest === undefined
+        ? {
+            sql: `UPDATE _collab_docs SET yjs_state = ?, text_snapshot = ?, version = version + 1, updated_at = ${nowExpr} WHERE doc_id = ? AND version = ?`,
+            args: [b64, textSnapshot, docId, expectedVersion],
+        }
+        : {
+            sql: `UPDATE _collab_docs SET yjs_state = ?, text_snapshot = ?, version = version + 1, updated_at = ${nowExpr} WHERE doc_id = ? AND version = ? AND ${STATE_DIGEST_SQL} = ?`,
+            args: [b64, textSnapshot, docId, expectedVersion, expectedDigest],
+        });
     return result.rowsAffected > 0;
 }
 export async function saveYDocState(docId, state, textSnapshot) {