@k2b/cloud 0.44.0 → 0.45.0

package/src/shared-text/awareness.ts

@@ -0,0 +1,87 @@
+import * as decoding from "lib0/decoding";
+import * as encoding from "lib0/encoding";
+import { z } from "zod";
+
+const unsigned = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const positionId = z.strictObject({ client: unsigned, clock: unsigned });
+const relativePosition = z
+  .strictObject({
+    type: positionId.nullable().optional(),
+    tname: z.string().nullable().optional(),
+    item: positionId.nullable().optional(),
+    assoc: z.number().int().min(Number.MIN_SAFE_INTEGER).max(Number.MAX_SAFE_INTEGER).optional(),
+  })
+  .refine((position) => position.type != null || position.tname != null);
+const stateSchema = z
+  .strictObject({
+    // Identity is supplied by the authenticated transport, never copied from here.
+    user: z.unknown().optional(),
+    cursor: z.strictObject({ anchor: relativePosition, head: relativePosition }).nullable().optional(),
+  })
+  .nullable();
+
+export class InvalidSharedTextAwarenessError extends Error {
+  constructor() {
+    super("Invalid shared text awareness update");
+    this.name = "InvalidSharedTextAwarenessError";
+  }
+}
+
+const encode = (clientId: number, clock: number, state: unknown): Uint8Array => {
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, 1);
+  encoding.writeVarUint(encoder, clientId);
+  encoding.writeVarUint(encoder, clock);
+  encoding.writeVarString(encoder, JSON.stringify(state));
+  return encoding.toUint8Array(encoder);
+};
+
+/** One authorized connection, with an ID allocated uniquely by its transport. */
+export const createTrustedTextAwareness = (config: {
+  clientId: number;
+  textName: string;
+  user: { userId: string; name: string; color: string };
+}) => {
+  if (!Number.isSafeInteger(config.clientId) || config.clientId < 2 ** 32) throw new RangeError("Invalid server awareness ID");
+  const user = { userId: config.user.userId, name: config.user.name, color: config.user.color };
+  let localClientId: number | undefined;
+  let clock = 0;
+  let active = false;
+  const next = (state: unknown): Uint8Array => {
+    if (clock === Number.MAX_SAFE_INTEGER) throw new RangeError("Awareness clock exhausted");
+    return encode(config.clientId, ++clock, state);
+  };
+  return {
+    /** Validate one local state and replace its envelope and identity. Throws on invalid input. */
+    publish(bytes: Uint8Array): Uint8Array {
+      try {
+        const decoder = decoding.createDecoder(bytes);
+        if (decoding.readVarUint(decoder) !== 1) throw new InvalidSharedTextAwarenessError();
+        const clientId = decoding.readVarUint(decoder);
+        const clientClock = decoding.readVarUint(decoder);
+        if (!Number.isSafeInteger(clientId) || !Number.isSafeInteger(clientClock)) throw new InvalidSharedTextAwarenessError();
+        const state = stateSchema.parse(JSON.parse(decoding.readVarString(decoder)));
+        if (decoder.pos !== bytes.length || (localClientId !== undefined && localClientId !== clientId))
+          throw new InvalidSharedTextAwarenessError();
+        if (
+          state?.cursor &&
+          [state.cursor.anchor, state.cursor.head].some((position) => position.tname !== config.textName || position.type != null)
+        )
+          throw new InvalidSharedTextAwarenessError();
+        const result = next(state === null ? null : { user, writerId: clientId, cursor: state.cursor ?? null });
+        localClientId = clientId;
+        active = state !== null;
+        return result;
+      } catch {
+        throw new InvalidSharedTextAwarenessError();
+      }
+    },
+    /** Publish on leave/close, including when the browser cannot send its own null state. */
+    remove(): Uint8Array | null {
+      if (!active) return null;
+      const result = next(null);
+      active = false;
+      return result;
+    },
+  };
+};

package/src/shared-text/changes.ts

@@ -0,0 +1,27 @@
+import type { SharedTextChange } from "./types";
+
+export const validateChanges = (text: string, changes: readonly SharedTextChange[], maxLength: number): SharedTextChange[] => {
+  const sorted = [...changes].sort((a, b) => a.from - b.from || a.to - b.to);
+  let length = text.length;
+  const splitsCharacter = (at: number) =>
+    at > 0 && at < text.length && /[\uD800-\uDBFF]/.test(text[at - 1]!) && /[\uDC00-\uDFFF]/.test(text[at]!);
+  for (let index = 0; index < sorted.length; index++) {
+    const change = sorted[index]!;
+    const previous = sorted[index - 1];
+    if (
+      !Number.isSafeInteger(change.from) ||
+      !Number.isSafeInteger(change.to) ||
+      change.from < 0 ||
+      change.to < change.from ||
+      change.to > text.length ||
+      (change.recreate === true && change.to === change.from) ||
+      (previous && (change.from < previous.to || change.from === previous.from))
+    )
+      throw new RangeError("Shared text changes must have distinct, non-overlapping original-source ranges");
+    if (splitsCharacter(change.from) || splitsCharacter(change.to) || !change.insert.isWellFormed())
+      throw new RangeError("Shared text changes must preserve Unicode characters");
+    length += change.insert.length - (change.to - change.from);
+  }
+  if (length > maxLength) throw new RangeError("Shared text changes exceed maxLength");
+  return sorted.filter((change) => change.recreate === true || text.slice(change.from, change.to) !== change.insert);
+};

package/src/shared-text/documents.ts

@@ -1,10 +1,21 @@
 import type { Topic } from "@k2b/sync";
 import * as Y from "yjs";
-import { compareStreamCursor } from "./cursor";
+import { validateChanges } from "./changes";
+import { compareStreamCursor, maxStreamCursor } from "./cursor";
 import { SHARED_TEXT_NAME, sharedTextNodeId, toBase64 } from "./events";
+import {
+  createStructuralIngressValidation,
+  planStructuralInverse,
+  prepareIngressHistory,
+  prepareStructuralHistory,
+  SharedTextInverseDependencyError,
+  type SharedTextStructuralHistory,
+} from "./structural-history";
+import { TableActionRejectedError } from "./table-actions";
 import { textDiffHunks } from "./text-diff";
 import type {
   SharedTextActor,
+  SharedTextChange,
   SharedTextContributor,
   SharedTextEditResult,
   SharedTextSnapshot,
@@ -13,15 +24,25 @@ import type {
   SharedTextSyncEvent,
 } from "./types";
 
+/** Text for a diffed edit, original-source changes, or an application-prepared Yjs update. */
+type PlannedEdit = string | readonly SharedTextChange[] | { update: Uint8Array };
+
 type DocumentLog = {
-  /** Omitted logs use Sync’s default message payload limit (128 KiB). */
+  /** Omitted logs use Sync’s default message payload limit (128 KiB) for diffs and skip the event size check. */
   maxPayloadBytes?: number;
+  events?(
+    docId: string,
+    after: string | null,
+    until: string,
+    signal?: AbortSignal,
+  ): AsyncIterable<{ cursor: string; data: SharedTextSyncEvent }>;
   topic(): Pick<Topic<SharedTextSyncEvent>, "latestCursor" | "publish">;
   replay(config: {
     docId: string;
     after: string | null;
     until: string;
     doc: Y.Doc;
+    restoreRevision?: string;
     signal?: AbortSignal;
   }): Promise<SharedTextContributor[]>;
 };
@@ -51,109 +72,439 @@ export const createDoc = (stored: SharedTextStoredState): Y.Doc => {
 };
 
 export const bindDocuments = <Saved, Context>(
-  { topic, replay, maxPayloadBytes = 128 * 1024 }: DocumentLog,
+  { topic, replay, events, maxPayloadBytes }: DocumentLog,
   store: SharedTextStore<Saved, Context>,
 ) => {
-  return {
-    async read(docId: string, options: { signal?: AbortSignal } = {}): Promise<SharedTextSnapshot | null> {
-      const stored = await store.load(docId, options);
-      if (!stored) return null;
-      const latest = await topic().latestCursor({ tenantId: docId });
-      if (!latest || (stored.cursor && compareStreamCursor(latest, stored.cursor) <= 0))
-        return { state: stored.state, text: stored.text, cursor: stored.cursor };
-      const doc = createDoc(stored);
+  const write = async (
+    docId: string,
+    options: {
+      actor: SharedTextActor | null;
+      context?: Context;
+      signal?: AbortSignal;
+      actionId?: string;
+      inverseOf?: string;
+      retained?: () => boolean;
+      validate?: () => Promise<void>;
+    },
+    update: (current: {
+      text: string;
+      cursor: string | null;
+      restoreRevision: string;
+      contributors: SharedTextContributor[];
+      state(): Uint8Array;
+    }) => PlannedEdit | Promise<PlannedEdit>,
+    maxLength?: number,
+  ): Promise<SharedTextEditResult<Saved>> => {
+    if (maxLength !== undefined && (!Number.isSafeInteger(maxLength) || maxLength < 0))
+      throw new RangeError("maxLength must be a nonnegative safe integer");
+    const requestedAt = Date.now();
+    const stored = await store.load(docId, { signal: options.signal });
+    if (!stored) return { status: "notFound" };
+    const handle = topic();
+    const target = await handle.latestCursor({ tenantId: docId });
+    const doc = createDoc(stored);
+    try {
+      let contributors: SharedTextContributor[] = [];
       try {
-        await replay({ docId, after: stored.cursor, until: latest, doc, signal: options.signal });
-        return { state: Y.encodeStateAsUpdate(doc), text: doc.getText(SHARED_TEXT_NAME).toString(), cursor: latest };
+        if (target)
+          contributors = await replay({
+            docId,
+            after: stored.cursor,
+            until: target,
+            doc,
+            restoreRevision: stored.restoreRevision,
+            signal: options.signal,
+          });
+      } catch (error) {
+        // A cancelled request is not a sync failure: it throws like every other abort before publication.
+        options.signal?.throwIfAborted();
+        return { status: "syncFailed", error };
+      }
+      options.signal?.throwIfAborted();
+      if (maxLength !== undefined && (doc.store.pendingStructs || doc.store.pendingDs))
+        return { status: "syncFailed", error: new Error("Shared text has unresolved update dependencies") };
+      const ytext = doc.getText(SHARED_TEXT_NAME);
+      const text = ytext.toString();
+      const next = await update({
+        text,
+        cursor: target,
+        restoreRevision: stored.restoreRevision,
+        contributors,
+        state: () => Y.encodeStateAsUpdate(doc),
+      });
+      let changes: readonly SharedTextChange[] = [];
+      let prepared: Uint8Array | undefined;
+      if (maxLength === undefined) {
+        if (typeof next === "string") {
+          if (next === text) return { status: "unchanged", text };
+          changes = textDiffHunks(text, next, maxPayloadBytes ?? 128 * 1024).map((diff) => ({
+            from: diff.index,
+            to: diff.index + diff.deleteCount,
+            insert: diff.insert,
+          }));
+        } else if ("update" in next) prepared = next.update;
+        else throw new TypeError("edit must return text or a prepared update");
+      } else {
+        if (typeof next === "string" || "update" in next) throw new TypeError("change must return disjoint edits");
+        changes = validateChanges(text, next, maxLength);
+      }
+      if (!prepared && !changes.length && !options.inverseOf) return { status: "unchanged", text };
+      // A request cancelled while the callback ran must not publish a write.
+      options.signal?.throwIfAborted();
+      const beforeEditState = Y.encodeStateVector(doc);
+      const finishHistory = options.actionId ? prepareStructuralHistory(ytext, changes) : undefined;
+      if (prepared) {
+        // Application-prepared transactions preserve exact item identities and
+        // may be replayed after a partial publication/persistence failure.
+        Y.applyUpdate(doc, prepared, "server-edit");
+      } else
+        doc.transact(() => {
+          for (let index = changes.length - 1; index >= 0; index--) {
+            const change = changes[index]!;
+            if (change.to > change.from) ytext.delete(change.from, change.to - change.from);
+            if (change.insert.length) ytext.insert(change.from, change.insert);
+          }
+        }, "cli-edit");
+      const actor = options.actor;
+      const updateBytes = Y.encodeStateAsUpdate(doc, beforeEditState);
+      const receipt = options.actionId ? { actionId: options.actionId, update: updateBytes } : undefined;
+      const history: SharedTextStructuralHistory = finishHistory?.() ?? { patches: [], tables: [], ingressBarrier: true };
+      if (history && options.inverseOf) {
+        history.inverseOf = options.inverseOf;
+        history.retained = options.retained?.() ?? false;
+      }
+      const event: SharedTextSyncEvent = {
+        kind: "sync",
+        payload: toBase64(updateBytes),
+        ...(options.actionId ? { actionId: options.actionId } : {}),
+        ...(history ? { history } : {}),
+        restoreRevision: stored.restoreRevision,
+        originNodeId: sharedTextNodeId,
+        originPeerId: null,
+        ...(actor ? { actor } : {}),
+      };
+      if (maxPayloadBytes !== undefined && new TextEncoder().encode(JSON.stringify(event)).length > maxPayloadBytes)
+        throw new RangeError("The structural receipt exceeds the document log payload budget");
+      await options.validate?.();
+      options.signal?.throwIfAborted();
+      const published = await handle.publish({
+        tenantId: docId,
+        ...(maxLength !== undefined ? { expectedAfter: target } : {}),
+        data: event,
+      });
+      let persistedDoc: Y.Doc | undefined;
+      try {
+        persistedDoc = createDoc(stored);
+        await replay({
+          docId,
+          after: stored.cursor,
+          until: published.cursor,
+          doc: persistedDoc,
+          restoreRevision: stored.restoreRevision,
+          signal: options.signal,
+        });
+        const persistedText = persistedDoc.getText(SHARED_TEXT_NAME).toString();
+        const credited = new Map(contributors.map((contributor) => [`${contributor.kind}:${contributor.id}`, contributor]));
+        if (actor) credited.set(`${actor.kind}:${actor.id}`, { ...actor, lastContributedAt: new Date(requestedAt) });
+        const saved = await store.save(
+          docId,
+          {
+            state: Y.encodeStateAsUpdate(persistedDoc),
+            text: persistedText,
+            cursor: published.cursor,
+            restoreRevision: stored.restoreRevision,
+            requestedAt,
+            actor,
+            contributors: [...credited.values()],
+          },
+          options.context,
+        );
+        return { status: "edited", text: persistedText, cursor: published.cursor, saved, ...(receipt ? { receipt } : {}) };
+      } catch (error) {
+        return { status: "persistFailed", cursor: published.cursor, error, ...(receipt ? { receipt } : {}) };
       } finally {
-        doc.destroy();
+        persistedDoc?.destroy();
       }
-    },
-    async edit(
+    } finally {
+      doc.destroy();
+    }
+  };
+  return {
+    /** A retained cursor is authority only after document, actor and lineage checks. */
+    async inverse(
       docId: string,
-      options: { actor: SharedTextActor | null; context?: Context; signal?: AbortSignal },
-      update: (current: {
-        text: string;
-        contributors: SharedTextContributor[];
-        state(): Uint8Array;
-      }) => string | { update: Uint8Array } | Promise<string | { update: Uint8Array }>,
+      options: {
+        actor: SharedTextActor;
+        context?: Context;
+        signal?: AbortSignal;
+        actionId: string;
+        receiptCursor: string;
+        restoreRevision: string;
+        maxLength: number;
+        validate?: () => Promise<void>;
+      },
     ): Promise<SharedTextEditResult<Saved>> {
-      const requestedAt = Date.now();
+      if (!events) throw new Error("This document log cannot read structural receipts");
+      let retained = false;
+      return write(
+        docId,
+        { ...options, inverseOf: options.receiptCursor, retained: () => retained },
+        async (current) => {
+          let receipt: SharedTextSyncEvent | undefined;
+          // Exact cursor lookup, independent of snapshot progress. A missing or
+          // expired event fails visibly; snapshots do not pin receipt history.
+          try {
+            for await (const event of events(docId, options.receiptCursor, options.receiptCursor, options.signal)) receipt = event.data;
+          } catch {
+            throw new TableActionRejectedError();
+          }
+          if (
+            !receipt?.history ||
+            !receipt.actionId ||
+            receipt.actor?.kind !== options.actor.kind ||
+            receipt.actor.id !== options.actor.id ||
+            receipt.restoreRevision !== options.restoreRevision ||
+            current.restoreRevision !== options.restoreRevision
+          )
+            throw new TableActionRejectedError();
+          const alignmentColumns = receipt.history.alignmentColumns;
+          if (alignmentColumns?.length && current.cursor && current.cursor !== options.receiptCursor) {
+            try {
+              for await (const later of events(docId, options.receiptCursor, current.cursor, options.signal)) {
+                const actor = later.data.actor;
+                const other = !actor || actor.kind !== options.actor.kind || actor.id !== options.actor.id;
+                if (other && later.data.history?.alignmentColumns?.some((column) => alignmentColumns.includes(column)))
+                  throw new SharedTextInverseDependencyError("alignment");
+              }
+            } catch (error) {
+              if (error instanceof SharedTextInverseDependencyError) throw error;
+              options.signal?.throwIfAborted();
+              throw new TableActionRejectedError();
+            }
+          }
+          const copy = new Y.Doc();
+          try {
+            Y.applyUpdate(copy, current.state());
+            const planned = planStructuralInverse(copy.getText(SHARED_TEXT_NAME), receipt.history);
+            retained = planned.retained;
+            return planned.changes;
+          } finally {
+            copy.destroy();
+          }
+        },
+        options.maxLength,
+      );
+    },
+    /** Validate before retained publication; rejected bytes remain client-owned. */
+    async accept(
+      docId: string,
+      options: {
+        actor: SharedTextActor;
+        update: Uint8Array;
+        baseCursor: string | null;
+        restoreRevision: string;
+        originNodeId: string;
+        originPeerId: string | null;
+        signal?: AbortSignal;
+        validate?: () => Promise<boolean>;
+        /** Application-owned limit on the merged canonical UTF-16 text. */
+        maxLength?: number;
+        /** Validate application-owned fields in the fully merged encoded state. */
+        validateState?: (state: Uint8Array) => boolean | Promise<boolean>;
+      },
+    ): Promise<{ status: "accepted"; cursor: string } | { status: "recoveryRequired" | "notFound" }> {
+      if (options.maxLength !== undefined && (!Number.isSafeInteger(options.maxLength) || options.maxLength < 0))
+        throw new RangeError("maxLength must be a nonnegative safe integer");
+      Y.decodeUpdate(options.update);
+      if (!events) throw new Error("This document log cannot validate ingress");
       const stored = await store.load(docId, { signal: options.signal });
       if (!stored) return { status: "notFound" };
+      if (stored.restoreRevision !== options.restoreRevision) return { status: "recoveryRequired" };
       const handle = topic();
       const target = await handle.latestCursor({ tenantId: docId });
+      // Idle notes use a shared-topic watermark, which may be ahead of their
+      // own last retained event (or have no retained event at all). CAS still
+      // targets the tenant head; browser coverage belongs to the snapshot too.
+      const covered = maxStreamCursor(stored.cursor, target);
+      if (options.baseCursor) {
+        try {
+          if (!covered || compareStreamCursor(options.baseCursor, covered) > 0) return { status: "recoveryRequired" };
+        } catch {
+          return { status: "recoveryRequired" };
+        }
+      }
+      if (!target && stored.cursor !== options.baseCursor) return { status: "recoveryRequired" };
       const doc = createDoc(stored);
       try {
-        let contributors: SharedTextContributor[] = [];
+        if (target)
+          await replay({
+            docId,
+            after: stored.cursor,
+            until: target,
+            doc,
+            restoreRevision: stored.restoreRevision,
+            signal: options.signal,
+          });
+        const validation = createStructuralIngressValidation(doc, options.update);
         try {
-          if (target) contributors = await replay({ docId, after: stored.cursor, until: target, doc, signal: options.signal });
-        } catch (error) {
-          // A cancelled request is not a sync failure: it throws like every other abort before publication.
-          options.signal?.throwIfAborted();
-          return { status: "syncFailed", error };
+          if (target && (!options.baseCursor || compareStreamCursor(options.baseCursor, target) < 0)) {
+            try {
+              for await (const event of events(docId, options.baseCursor, target, options.signal)) {
+                options.signal?.throwIfAborted();
+                if (event.data.restoreRevision !== undefined && event.data.restoreRevision !== options.restoreRevision) continue;
+                // An unreferenced send marker has no domain or text effect.
+                // It must not make an otherwise valid pending edit unrecoverable.
+                if (event.data.kind === "freeze") continue;
+                // Old/unclassified retained events cannot prove that an edit's
+                // original table/row targets survived. Do not guess at ingress.
+                const history = event.data.history;
+                if (!history) return { status: "recoveryRequired" };
+                let inverseSource: SharedTextStructuralHistory | undefined;
+                if (history.inverseOf && history.patches.some((patch) => patch.inserted.length > 0)) {
+                  // A pure removal can be recreated by a LATER inverse receipt.
+                  // Its old IDs must not be acknowledged as a removal of the
+                  // new target. Exact retained lookup keeps this proof bounded.
+                  for await (const original of events(docId, history.inverseOf, history.inverseOf, options.signal)) {
+                    if (original.data.restoreRevision === options.restoreRevision) inverseSource = original.data.history;
+                  }
+                }
+                if (!validation.check(history, inverseSource)) return { status: "recoveryRequired" };
+              }
+            } catch {
+              options.signal?.throwIfAborted();
+              return { status: "recoveryRequired" };
+            }
+          }
+        } finally {
+          validation.dispose();
         }
+        // A retained echo confirms input, not a promise that missing causal
+        // predecessors might arrive later. Never strand confirmed bytes behind
+        // a predecessor which was rejected for requiring recovery.
+        const finishHistory = prepareIngressHistory(doc.getText(SHARED_TEXT_NAME));
+        Y.applyUpdate(doc, options.update, "ingress-probe");
+        if (doc.store.pendingStructs || doc.store.pendingDs) return { status: "recoveryRequired" };
+        if (options.maxLength !== undefined && doc.getText(SHARED_TEXT_NAME).length > options.maxLength)
+          return { status: "recoveryRequired" };
+        if (options.validateState && !(await options.validateState(Y.encodeStateAsUpdate(doc)))) return { status: "recoveryRequired" };
         options.signal?.throwIfAborted();
-        const ytext = doc.getText(SHARED_TEXT_NAME);
-        const text = ytext.toString();
-        const next = await update({ text, contributors, state: () => Y.encodeStateAsUpdate(doc) });
-        if (next === text) return { status: "unchanged", text };
-        // A request cancelled while the callback ran must not publish a write.
+        if (options.validate && !(await options.validate())) return { status: "recoveryRequired" };
         options.signal?.throwIfAborted();
-        const beforeEditState = Y.encodeStateVector(doc);
-        if (typeof next === "string") {
-          const hunks = textDiffHunks(text, next, maxPayloadBytes);
-          doc.transact(() => {
-            for (const diff of hunks.reverse()) {
-              if (diff.deleteCount > 0) ytext.delete(diff.index, diff.deleteCount);
-              if (diff.insert.length > 0) ytext.insert(diff.index, diff.insert);
-            }
-          }, "cli-edit");
-        } else {
-          // Application-prepared transactions preserve exact item identities and
-          // may be replayed after a partial publication/persistence failure.
-          Y.applyUpdate(doc, next.update, "server-edit");
-        }
-        const actor = options.actor;
         const published = await handle.publish({
           tenantId: docId,
+          expectedAfter: target,
           data: {
             kind: "sync",
-            payload: toBase64(Y.encodeStateAsUpdate(doc, beforeEditState)),
+            payload: toBase64(options.update),
+            history: finishHistory(),
+            actor: options.actor,
+            restoreRevision: options.restoreRevision,
+            originNodeId: options.originNodeId,
+            originPeerId: options.originPeerId,
+          },
+        });
+        return { status: "accepted", cursor: published.cursor };
+      } finally {
+        doc.destroy();
+      }
+    },
+    /**
+     * Capture an exact ordered boundary. The application commits this cursor,
+     * full state and generation with its send transaction; an unreferenced
+     * marker has no domain effect. Later updates are outside the captured state.
+     */
+    async freeze(
+      docId: string,
+      options: {
+        actor: SharedTextActor;
+        restoreRevision: string;
+        signal?: AbortSignal;
+        validate: (state: Uint8Array) => Promise<void>;
+      },
+    ): Promise<{ state: Uint8Array; text: string; cursor: string; restoreRevision: string } | null> {
+      options.signal?.throwIfAborted();
+      const stored = await store.load(docId, { signal: options.signal });
+      if (!stored) return null;
+      if (stored.restoreRevision !== options.restoreRevision) throw new Error("Document generation changed before freeze");
+      const handle = topic();
+      const target = await handle.latestCursor({ tenantId: docId });
+      const doc = createDoc(stored);
+      try {
+        if (target)
+          await replay({
+            docId,
+            after: stored.cursor,
+            until: target,
+            doc,
+            restoreRevision: stored.restoreRevision,
+            signal: options.signal,
+          });
+        if (doc.store.pendingStructs || doc.store.pendingDs) throw new Error("Document has unresolved dependencies before freeze");
+        const state = Y.encodeStateAsUpdate(doc);
+        // Give validation a copy: it cannot alter the state returned for sending.
+        await options.validate(state.slice());
+        options.signal?.throwIfAborted();
+        const published = await handle.publish({
+          tenantId: docId,
+          expectedAfter: target,
+          data: {
+            kind: "freeze",
+            payload: "",
+            restoreRevision: stored.restoreRevision,
+            actor: options.actor,
             originNodeId: sharedTextNodeId,
             originPeerId: null,
-            ...(actor ? { actor } : {}),
           },
         });
-        let persistedDoc: Y.Doc | undefined;
-        try {
-          persistedDoc = createDoc(stored);
-          await replay({ docId, after: stored.cursor, until: published.cursor, doc: persistedDoc, signal: options.signal });
-          const persistedText = persistedDoc.getText(SHARED_TEXT_NAME).toString();
-          const credited = new Map(contributors.map((contributor) => [`${contributor.kind}:${contributor.id}`, contributor]));
-          if (actor) credited.set(`${actor.kind}:${actor.id}`, { ...actor, lastContributedAt: new Date(requestedAt) });
-          const saved = await store.save(
-            docId,
-            {
-              state: Y.encodeStateAsUpdate(persistedDoc),
-              text: persistedText,
-              cursor: published.cursor,
-              restoreRevision: stored.restoreRevision,
-              requestedAt,
-              actor,
-              contributors: [...credited.values()],
-            },
-            options.context,
-          );
-          return { status: "edited", text: persistedText, cursor: published.cursor, saved };
-        } catch (error) {
-          return { status: "persistFailed", cursor: published.cursor, error };
-        } finally {
-          persistedDoc?.destroy();
-        }
+        return { state, text: doc.getText(SHARED_TEXT_NAME).toString(), cursor: published.cursor, restoreRevision: stored.restoreRevision };
       } finally {
         doc.destroy();
       }
     },
+    async read(docId: string, options: { signal?: AbortSignal } = {}): Promise<SharedTextSnapshot | null> {
+      const stored = await store.load(docId, options);
+      if (!stored) return null;
+      const latest = await topic().latestCursor({ tenantId: docId });
+      if (!latest || (stored.cursor && compareStreamCursor(latest, stored.cursor) <= 0))
+        return { state: stored.state, text: stored.text, cursor: stored.cursor, restoreRevision: stored.restoreRevision };
+      const doc = createDoc(stored);
+      try {
+        await replay({ docId, after: stored.cursor, until: latest, doc, restoreRevision: stored.restoreRevision, signal: options.signal });
+        return {
+          state: Y.encodeStateAsUpdate(doc),
+          text: doc.getText(SHARED_TEXT_NAME).toString(),
+          cursor: latest,
+          restoreRevision: stored.restoreRevision,
+        };
+      } finally {
+        doc.destroy();
+      }
+    },
+    edit(
+      docId: string,
+      options: { actor: SharedTextActor | null; context?: Context; signal?: AbortSignal },
+      update: (current: {
+        text: string;
+        contributors: SharedTextContributor[];
+        state(): Uint8Array;
+      }) => string | { update: Uint8Array } | Promise<string | { update: Uint8Array }>,
+    ): Promise<SharedTextEditResult<Saved>> {
+      return write(docId, options, update);
+    },
+    /** Disjoint original-source changes, accepted only while the captured tenant head is unchanged. */
+    async change(
+      docId: string,
+      options: { actor: SharedTextActor | null; context?: Context; signal?: AbortSignal; maxLength: number; actionId?: string },
+      update: (current: {
+        text: string;
+        restoreRevision: string;
+        contributors: SharedTextContributor[];
+        state(): Uint8Array;
+      }) => readonly SharedTextChange[] | Promise<readonly SharedTextChange[]>,
+    ): Promise<SharedTextEditResult<Saved>> {
+      if (!Number.isSafeInteger(options.maxLength) || options.maxLength < 0)
+        throw new RangeError("maxLength must be a nonnegative safe integer");
+      return write(docId, options, update, options.maxLength);
+    },
   };
 };