@k2b/cloud 0.44.0 → 0.46.0

package/src/shared-text/log.ts

@@ -14,6 +14,7 @@ const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "de
     after: string | null;
     until: string;
     doc: Y.Doc;
+    restoreRevision?: string;
     signal?: AbortSignal;
   }): Promise<SharedTextContributor[]> => {
     const contributors = new Map<string, SharedTextContributor>();
@@ -22,8 +23,8 @@ const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "de
     if (compareStreamCursor(after, config.until) >= 0) return [];
     let reachedTarget = false;
     for await (const event of handle.replay({ tenantId: config.docId, after, until: config.until, signal: config.signal })) {
-      applySharedTextEvent(config.doc, event, config.docId);
-      if (event.data.actor)
+      const applied = applySharedTextEvent(config.doc, event, config.docId, config.restoreRevision);
+      if (applied && event.data.actor)
         contributors.set(`${event.data.actor.kind}:${event.data.actor.id}`, {
           ...event.data.actor,
           lastContributedAt: event.publishedAt,
@@ -39,6 +40,7 @@ const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "de
     after: string | null;
     until: string;
     doc: Y.Doc;
+    restoreRevision?: string;
     signal?: AbortSignal;
   }): Promise<{ recoveredUpdates: number; malformedUpdates: number; historyGaps: number }> => {
     const handle = topic();
@@ -51,8 +53,7 @@ const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "de
       try {
         for await (const event of handle.replay({ tenantId: config.docId, after, until: config.until, signal: config.signal })) {
           try {
-            applySharedTextEvent(config.doc, event, config.docId);
-            recoveredUpdates++;
+            if (applySharedTextEvent(config.doc, event, config.docId, config.restoreRevision)) recoveredUpdates++;
           } catch (error) {
             if (!(error instanceof MalformedSharedTextEventError)) throw error;
             malformedUpdates++;
@@ -87,7 +88,25 @@ const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "de
       return 0;
     },
     withStore<Saved, Context>(store: SharedTextStore<Saved, Context>) {
-      return bindDocuments({ topic, replay, maxPayloadBytes: topicConfig.maxPayloadBytes }, store);
+      return bindDocuments(
+        {
+          topic,
+          replay,
+          maxPayloadBytes: topicConfig.maxPayloadBytes,
+          async *events(docId, after, until, signal) {
+            const handle = topic();
+            const exact = after === until;
+            const start = exact ? handle.cursorAt(handle.cursorSequence(until) - 1) : (after ?? handle.cursorAt(0));
+            let reached = false;
+            for await (const event of handle.replay({ tenantId: docId, after: start, until, signal })) {
+              reached = event.cursor === until;
+              if (!exact || event.cursor === until) yield event;
+            }
+            if (!reached) throw new Error("The structural receipt history is unavailable");
+          },
+        },
+        store,
+      );
     },
   };
 };

package/src/shared-text/snapshots.ts

@@ -1,10 +1,11 @@
 import { type Job, type JobConfig, RetentionGapError, type Topic, type Worker } from "@k2b/sync";
 import * as Y from "yjs";
 import { logger } from "../services/logging";
+import { validateChanges } from "./changes";
 import { compareStreamCursor } from "./cursor";
 import { createDoc } from "./documents";
-import { applySharedTextEvent, MalformedSharedTextEventError, SHARED_TEXT_NAME, sharedTextNodeId } from "./events";
-import type { SharedTextContributor, SharedTextSaveInput, SharedTextStoredState, SharedTextSyncEvent } from "./types";
+import { applySharedTextEvent, MalformedSharedTextEventError, SHARED_TEXT_NAME, sharedTextNodeId, toBase64 } from "./events";
+import type { SharedTextChange, SharedTextContributor, SharedTextSaveInput, SharedTextStoredState, SharedTextSyncEvent } from "./types";
 
 const ACK_WAIT_MS = 120_000;
 const RECONCILE_LIMIT = 5_000;
@@ -69,10 +70,20 @@ export type SharedTextSnapshotBacklog = {
 };
 type SnapshotLog = {
   id: string;
-  topic(): Pick<Topic<SharedTextSyncEvent>, "head" | "latestCursor" | "cursorSequence" | "cursorAt" | "replay">;
+  topic(): Pick<Topic<SharedTextSyncEvent>, "head" | "latestCursor" | "cursorSequence" | "cursorAt" | "replay" | "publish">;
   firstSequence(): Promise<number>;
 };
-type SnapshotOptions = { log: SnapshotLog; store: SharedTextSnapshotStore; logger?: ReturnType<typeof logger> };
+export type SharedTextSnapshotRepair = {
+  /** Application-owned, insertion-only repair in original UTF-16 coordinates. */
+  plan(text: string): readonly SharedTextChange[];
+  maxLength: number;
+};
+type SnapshotOptions = {
+  log: SnapshotLog;
+  store: SharedTextSnapshotStore;
+  logger?: ReturnType<typeof logger>;
+  repair?: SharedTextSnapshotRepair;
+};
 type InputCodec<Input> = { encode(request: SharedTextSnapshotRequest): Input; decode(input: Input): SharedTextSnapshotRequest };
 type SnapshotJob<Input> = () => Pick<Job<Input>, "submit" | "process">;
 
@@ -91,10 +102,12 @@ export function snapshots<Input>(
 }
 
 const createSnapshots = <Input>(
-  { log, store, logger: suppliedLogger }: SnapshotOptions,
+  { log, store, repair, logger: suppliedLogger }: SnapshotOptions,
   job: SnapshotJob<Input>,
   input: InputCodec<Input>,
 ) => {
+  if (repair && (!Number.isSafeInteger(repair.maxLength) || repair.maxLength < 0))
+    throw new RangeError("Repair maxLength must be a nonnegative safe integer");
   const output = suppliedLogger ?? logger("shared-text-snapshots");
   let worker: Promise<Worker> | null = null;
   let lastBacklog: SharedTextSnapshotBacklog | null = null;
@@ -147,31 +160,34 @@ const createSnapshots = <Input>(
           const head = await topic.head();
           // Cover queued older cursors in one replay; later jobs skip already saved state.
           const target = await topic.latestCursor({ tenantId: docId });
-          if (!target) {
+          if (!target && !repair) {
             output.warn("Snapshot skipped: no retained events for the note", { docId, requestedCursor: request.targetCursor });
             return;
           }
           const requestedAt = Date.now();
-          if (!initial || (initial.cursor && compareStreamCursor(initial.cursor, target) >= 0)) return;
+          if (!initial) return;
+          const covered = !target || !!(initial.cursor && compareStreamCursor(initial.cursor, target) >= 0);
+          if (covered && !repair) return;
           const doc = createDoc(initial);
           const contributors = new Map<string, SharedTextContributor>();
           try {
-            let reachedTarget = false;
+            let reachedTarget = covered;
             try {
-              for await (const event of topic.replay({
-                tenantId: docId,
-                after: initial.cursor ?? topic.cursorAt(0),
-                until: target,
-                signal: context.signal,
-              })) {
-                applySharedTextEvent(doc, event, docId);
-                if (event.data.actor)
-                  contributors.set(`${event.data.actor.kind}:${event.data.actor.id}`, {
-                    ...event.data.actor,
-                    lastContributedAt: event.publishedAt,
-                  });
-                reachedTarget = event.cursor === target;
-              }
+              if (!covered && target)
+                for await (const event of topic.replay({
+                  tenantId: docId,
+                  after: initial.cursor ?? topic.cursorAt(0),
+                  until: target,
+                  signal: context.signal,
+                })) {
+                  const applied = applySharedTextEvent(doc, event, docId, initial.restoreRevision);
+                  if (applied && event.data.actor)
+                    contributors.set(`${event.data.actor.kind}:${event.data.actor.id}`, {
+                      ...event.data.actor,
+                      lastContributedAt: event.publishedAt,
+                    });
+                  reachedTarget = event.cursor === target;
+                }
             } catch (error) {
               // Preserve all valid retained updates and unresolved dependencies;
               // record the missing/invalid history once in the DLQ after recovery.
@@ -184,10 +200,40 @@ const createSnapshots = <Input>(
             if (!reachedTarget) throw new Error("Snapshot replay did not reach its target");
             await context.heartbeat();
             context.signal.throwIfAborted();
+            let cursor = target && compareStreamCursor(target, head) > 0 ? target : head;
+            if (repair && !doc.store.pendingStructs && !doc.store.pendingDs) {
+              const text = doc.getText(SHARED_TEXT_NAME);
+              const planned = repair.plan(text.toString());
+              if (planned.some((change) => change.from !== change.to)) throw new RangeError("Snapshot repair may only insert text");
+              const changes = planned.length ? validateChanges(text.toString(), planned, repair.maxLength) : [];
+              if (changes.length) {
+                const before = Y.encodeStateVector(doc);
+                doc.transact(() => {
+                  for (const change of [...changes].reverse()) text.insert(change.from, change.insert);
+                }, "snapshot-repair");
+                context.signal.throwIfAborted();
+                if (heartbeatError) throw heartbeatError;
+                // A conflict retries the whole ordered job from the current store
+                // and tenant head; never publish a plan over a newer document.
+                const published = await topic.publish({
+                  tenantId: docId,
+                  expectedAfter: target,
+                  data: {
+                    kind: "sync",
+                    payload: toBase64(Y.encodeStateAsUpdate(doc, before)),
+                    originNodeId: sharedTextNodeId,
+                    originPeerId: null,
+                    restoreRevision: initial.restoreRevision,
+                  },
+                });
+                cursor = published.cursor;
+              } else if (covered) return;
+            } else if (covered) return;
+            context.signal.throwIfAborted();
             await store.save(docId, {
               state: Y.encodeStateAsUpdate(doc),
               text: doc.getText(SHARED_TEXT_NAME).toString(),
-              cursor: compareStreamCursor(head, target) > 0 ? head : target,
+              cursor,
               restoreRevision: initial.restoreRevision,
               requestedAt,
               actor: null,

package/src/shared-text/structural-history.ts

@@ -0,0 +1,377 @@
+/** Server-authored provenance. Read only from the authenticated document log. */
+import * as T from "@k2b/ui/text-editor/model";
+import * as Y from "yjs";
+import { captureTextAnchor, resolveTextAnchor } from "./anchors";
+import { fromBase64, toBase64 } from "./events";
+import { TableActionRejectedError } from "./table-actions";
+import type { SharedTextChange } from "./types";
+
+/** Proven later schema/row dependency; caller preserves the rejected history step. */
+export class SharedTextInverseDependencyError extends TableActionRejectedError {
+  constructor(readonly reason: "schema" | "row_scaffold" | "patch" | "alignment") {
+    super();
+  }
+}
+
+type Run = { client: number; clock: number; length: number };
+type Patch = {
+  left: string | null;
+  right: string | null;
+  removed: string;
+  inserted: string;
+  added: Run | null;
+  deleted: Run[];
+  recreate?: true;
+};
+export type SharedTextStructuralHistory = {
+  patches: Patch[];
+  column?: { header: string; hyphen: string };
+  /** Separator-only format actions depend on the complete original column alignment. */
+  alignmentColumns?: string[];
+  tables: string[];
+  retained?: boolean;
+  inverseOf?: string;
+  ingressBarrier?: boolean;
+  /** Post-action schema/row identities fence generic restoration. */
+  schemas?: { header: string; hyphens: string[]; rows: string[] }[];
+};
+const anchor = (text: Y.Text, at: number) => toBase64(captureTextAnchor(text, at));
+const resolve = (text: Y.Text, encoded: string) => resolveTextAnchor(text, fromBase64(encoded));
+const reject = (): never => {
+  throw new TableActionRejectedError();
+};
+
+// Exported Yjs traversal visits identity runs, not one linked-list search per
+// character. The transient snapshot is bounded by this document's state.
+const runs = (text: Y.Text, from: number, to: number): Run[] => {
+  const result: Run[] = [];
+  const first = Y.createRelativePositionFromTypeIndex(text, from).item;
+  if (from === to || !first || !text.doc) return result;
+  let left = to - from;
+  let item = Y.getItem(text.doc.store, first);
+  let clock = first.clock;
+  while (left > 0) {
+    if (!item.deleted && item.countable) {
+      const length = Math.min(left, item.id.clock + item.length - clock);
+      result.push({ client: item.id.client, clock, length });
+      left -= length;
+    }
+    if (!left) break;
+    if (!item.right) return reject();
+    item = item.right;
+    clock = item.id.clock;
+  }
+  return result;
+};
+
+export const prepareStructuralHistory = (text: Y.Text, changes: readonly SharedTextChange[]) => {
+  const source = text.toString();
+  const tables = T.findTables(source);
+  const previous = tables.map((table) => ({
+    header: anchor(text, table.lines[0]!.to),
+    hyphens: table.lines[1]!.cells.map((cell) => anchor(text, cell.from + cell.text.indexOf("-"))),
+  }));
+  const patches: Patch[] = changes.map((change) => ({
+    left: change.from > 0 ? anchor(text, change.from - 1) : null,
+    right: change.to < text.length ? anchor(text, change.to) : null,
+    removed: source.slice(change.from, change.to),
+    inserted: change.insert,
+    added: null,
+    deleted: runs(text, change.from, change.to),
+    ...(change.recreate ? { recreate: true as const } : {}),
+  }));
+  const alignmentColumns =
+    patches.length && patches.every((patch) => patch.removed + patch.inserted === ":")
+      ? tables.flatMap((table) =>
+          table.lines[1]!.cells.filter((cell) => changes.some((change) => change.from >= cell.from && change.to <= cell.to)).map((cell) =>
+            anchor(text, cell.from + cell.text.indexOf("-")),
+          ),
+        )
+      : [];
+  const affected = tables
+    .filter((table) => changes.some((change) => change.from <= table.to && change.to >= table.from))
+    .map((table) => anchor(text, table.lines[0]!.to));
+  return () => {
+    let shift = 0;
+    changes.forEach((change, index) => {
+      if (change.insert.length) {
+        const id = Y.createRelativePositionFromTypeIndex(text, change.from + shift).item!;
+        patches[index]!.added = { client: id.client, clock: id.clock, length: change.insert.length };
+      }
+      shift += change.insert.length - (change.to - change.from);
+    });
+    const result: SharedTextStructuralHistory = { patches, tables: affected };
+    if (alignmentColumns.length) result.alignmentColumns = alignmentColumns;
+    result.schemas = T.findTables(text.toString())
+      .filter((table) => affected.some((header) => resolve(text, header) === table.lines[0]!.to))
+      .map((table) => ({
+        header: anchor(text, table.lines[0]!.to),
+        hyphens: table.lines[1]!.cells.map((cell) => anchor(text, cell.from + cell.text.indexOf("-"))),
+        rows: table.lines.slice(2).map((line) => anchor(text, line.pipes[0] ?? line.from)),
+      }));
+    if (changes.every((change) => change.from === change.to)) {
+      for (const table of T.findTables(text.toString())) {
+        const before = previous.find((old) => resolve(text, old.header) === table.lines[0]!.to);
+        if (!before || table.columns !== before.hyphens.length + 1) continue;
+        const old = before.hyphens.map((value) => resolve(text, value));
+        const current = table.lines[1]!.cells.map((cell) => cell.from + cell.text.indexOf("-"));
+        if (!old.every((at) => at !== null && current.includes(at))) continue;
+        const at = current.find((at) => !old.includes(at))!;
+        result.column = { header: before.header, hyphen: anchor(text, at) };
+        break;
+      }
+    }
+    return result;
+  };
+};
+
+/** No mutation; a changed/deleted fixed target rejects rather than guessing. */
+export const planStructuralInverse = (
+  text: Y.Text,
+  record: SharedTextStructuralHistory,
+): { changes: SharedTextChange[]; retained: boolean } => {
+  if (record.retained) return { changes: [], retained: true };
+  if (record.column) {
+    const header = resolve(text, record.column.header),
+      hyphen = resolve(text, record.column.hyphen);
+    const table = T.findTables(text.toString()).find((table) => table.lines[0]!.to === header);
+    const column = table?.lines[1]!.cells.findIndex((cell) => hyphen !== null && hyphen >= cell.from && hyphen < cell.to) ?? -1;
+    if (!table || column < 0) return reject();
+    const dependent = table.lines.some((line, row) => (row === 1 ? line.cells[column]?.text.includes(":") : !!line.cells[column]?.text));
+    if (dependent) return { changes: [], retained: true };
+    const changes = T.deleteColumn(table, column);
+    if (!changes.length) return reject();
+    const owned = record.patches.flatMap((patch) => (patch.added ? [patch.added] : []));
+    const source = text.toString();
+    for (const change of changes) {
+      const row = table.lines.findIndex((line) => change.from >= line.from && change.to <= line.to);
+      const line = table.lines[row];
+      // Native append has one canonical scaffold, generated by insertRow. Prove
+      // its ORIGINAL delimiter IDs, not trimmed cell emptiness. A later space
+      // has another clock even if it looks exactly like scaffold padding.
+      let appended: Run | undefined;
+      if (row >= 2 && line) {
+        const newline = table.lines[0]!.lineBreak || "\n";
+        const start = Y.createRelativePositionFromTypeIndex(text, line.from - newline.length).item;
+        const expected = T.insertRow(table, 0)[0]!.insert;
+        const pipeOffsets = [...expected.matchAll(/\|/g)].map((match) => match.index);
+        if (
+          start &&
+          line.pipes.length === pipeOffsets.length &&
+          line.pipes.every((at, index) => {
+            const id = Y.createRelativePositionFromTypeIndex(text, at).item;
+            return id?.client === start.client && id.clock === start.clock + pipeOffsets[index]!;
+          }) &&
+          source.slice(change.from, change.to) === "   |"
+        )
+          appended = { client: start.client, clock: start.clock + newline.length + 1 + column * 4, length: 4 };
+      }
+      const scaffold = appended ? [...owned, appended] : owned;
+      if (
+        runs(text, change.from, change.to).some(
+          (run) =>
+            !scaffold.some(
+              (allowed) =>
+                run.client === allowed.client && run.clock >= allowed.clock && run.clock + run.length <= allowed.clock + allowed.length,
+            ),
+        )
+      )
+        return { changes: [], retained: true };
+    }
+    return { changes, retained: false };
+  }
+  const source = text.toString();
+  if (record.patches.some((patch) => patch.removed)) {
+    if (record.tables.length && !record.schemas) return reject();
+    // Restoring historical slices into newly accepted rows would assign their
+    // cells to different headers. Until identity-aware column restoration is
+    // available, that changed target visibly rejects without consuming history.
+    const tables = T.findTables(source);
+    // Alignment changes affect only separator colons. New/deleted body rows do
+    // not change those fixed targets; retain all column/schema and patch-ID
+    // checks below. Other restorations still require the original row set.
+    const alignmentOnly = record.patches.every((patch) => {
+      if (patch.recreate || patch.removed + patch.inserted !== ":") return false;
+      const left = patch.left === null ? null : resolve(text, patch.left);
+      const right = patch.right === null ? null : resolve(text, patch.right);
+      return (
+        left !== null &&
+        right !== null &&
+        tables.some((table) =>
+          table.lines[1]!.cells.some(
+            (cell) =>
+              left >= cell.from - 1 &&
+              right <= cell.to &&
+              (record.schemas ?? []).some(
+                (schema) =>
+                  resolve(text, schema.header) === table.lines[0]!.to &&
+                  schema.hyphens.some((hyphen) => resolve(text, hyphen) === cell.from + cell.text.indexOf("-")),
+              ),
+          ),
+        )
+      );
+    });
+    for (const schema of alignmentOnly ? [] : (record.schemas ?? [])) {
+      const table = tables.find((table) => table.lines[0]!.to === resolve(text, schema.header));
+      if (
+        !table ||
+        table.columns !== schema.hyphens.length ||
+        (!alignmentOnly && table.lines.length - 2 !== schema.rows.length) ||
+        schema.hyphens.some(
+          (value, index) => resolve(text, value) !== table.lines[1]!.cells[index]!.from + table.lines[1]!.cells[index]!.text.indexOf("-"),
+        ) ||
+        (!alignmentOnly &&
+          schema.rows.some((value, index) => resolve(text, value) !== (table.lines[index + 2]!.pipes[0] ?? table.lines[index + 2]!.from)))
+      )
+        throw new SharedTextInverseDependencyError("schema");
+    }
+  }
+  const deleted = Y.createDeleteSetFromStructStore(text.doc!.store);
+  const changes = record.patches.map((patch) => {
+    if (patch.added && !patch.removed) {
+      const run = patch.added;
+      if (deleted.clients.get(run.client)?.some((range) => range.clock < run.clock + run.length && range.clock + range.len > run.clock))
+        throw new SharedTextInverseDependencyError("patch");
+      const at = (clock: number) =>
+        Y.createAbsolutePositionFromRelativePosition(
+          new Y.RelativePosition(null, null, Y.createID(run.client, clock), 0),
+          text.doc!,
+          false,
+        );
+      const from = at(run.clock),
+        last = at(run.clock + run.length - 1);
+      if (from?.type !== text || last?.type !== text || source.slice(from.index, last.index + 1) !== patch.inserted)
+        throw new SharedTextInverseDependencyError("patch");
+      // A peer can extend an inserted row with a new column AFTER this run's
+      // last pipe. Removing only our run would attach that tail to the previous
+      // row (or separator). It is a dependency, not an empty independent row.
+      const end = last.index + 1;
+      if (
+        (patch.inserted.startsWith("\n") || patch.inserted.startsWith("\r")) &&
+        end < source.length &&
+        source[end] !== "\n" &&
+        source[end] !== "\r"
+      )
+        throw new SharedTextInverseDependencyError("row_scaffold");
+      return { from: from.index, to: end, insert: "" };
+    }
+    const left = patch.left === null ? -1 : resolve(text, patch.left);
+    const right = patch.right === null ? text.length : resolve(text, patch.right);
+    if (left === null || right === null || right <= left || source.slice(left + 1, right) !== patch.inserted)
+      throw new SharedTextInverseDependencyError("patch");
+    if (patch.added) {
+      const run = patch.added;
+      if (deleted.clients.get(run.client)?.some((range) => range.clock < run.clock + run.length && range.clock + range.len > run.clock))
+        throw new SharedTextInverseDependencyError("patch");
+      const first = Y.createRelativePositionFromTypeIndex(text, left + 1).item;
+      const last = Y.createRelativePositionFromTypeIndex(text, right - 1).item;
+      if (
+        first?.client !== run.client ||
+        first.clock !== run.clock ||
+        last?.client !== run.client ||
+        last.clock !== run.clock + run.length - 1
+      )
+        throw new SharedTextInverseDependencyError("patch");
+    }
+    return { from: left + 1, to: right, insert: patch.removed, ...(patch.recreate ? { recreate: true as const } : {}) };
+  });
+  return { changes, retained: false };
+};
+
+/** Ordinary input may also remove row/column syntax (raw Markdown/paste).
+ * Only the server classifies that ingress. A changed scaffold fences older
+ * unconfirmed input; unchanged cell input remains concurrently mergeable.
+ * The identity signature is transient; only the bounded classification enters
+ * the existing retained event, never a second snapshot or recovery store.
+ */
+export const prepareIngressHistory = (text: Y.Text) => {
+  const signature = () =>
+    JSON.stringify(
+      T.findTables(text.toString()).map((table) => ({
+        header: anchor(text, table.lines[0]!.to),
+        hyphens: table.lines[1]!.cells.map((cell) => anchor(text, cell.from + cell.text.indexOf("-"))),
+        rows: table.lines.map((line) => ({
+          before: line.from > 0 ? anchor(text, line.from - 1) : null,
+          pipes: line.pipes.map((at) => anchor(text, at)),
+        })),
+      })),
+    );
+  const before = signature();
+  return (): SharedTextStructuralHistory => ({ patches: [], tables: [], ...(signature() !== before ? { ingressBarrier: true } : {}) });
+};
+
+/** Stream retained provenance: memory is one document, one update and one receipt. */
+export const createStructuralIngressValidation = (doc: Y.Doc, update: Uint8Array) => {
+  const currentText = doc.getText("codemirror");
+  const decoded = Y.decodeUpdate(update);
+  const known = Y.decodeStateVector(Y.encodeStateVector(doc));
+  const introduced = decoded.structs.filter(
+    (item): item is Y.Item => item instanceof Y.Item && item.id.clock + item.length > (known.get(item.id.client) ?? 0),
+  );
+  let candidate: Y.Doc | undefined;
+  let tables: T.Table[] | undefined;
+  return {
+    check(record: SharedTextStructuralHistory, inverseSource?: SharedTextStructuralHistory): boolean {
+      if (record.ingressBarrier) return false;
+      const removed = record.patches.flatMap((patch) => patch.deleted);
+      const replaces = record.patches.some((patch) => patch.inserted.length > 0);
+      // Restoration provenance lives on the referenced retained receipt. Read
+      // it one event at a time: no growing map of all crossed action receipts.
+      if (replaces && record.inverseOf && !inverseSource) return false;
+      const replaced = inverseSource ? [...removed, ...inverseSource.patches.flatMap((patch) => patch.deleted)] : removed;
+      const touchesRemoved = (id: Y.ID | null) =>
+        id && removed.some((run) => id.client === run.client && id.clock >= run.clock && id.clock < run.clock + run.length);
+      if (introduced.some((item) => touchesRemoved(item.origin) || touchesRemoved(item.rightOrigin))) return false;
+      // Deletion-only input has no introduced origins. The receipt removed
+      // these IDs while they were LIVE, so an older unconfirmed removal cannot
+      // silently count as applied to their recreated replacement. An already
+      // accepted deletion is absent from these live removed runs and may retry.
+      // Pure removals create no replacement target: a stale row deletion may
+      // safely also remove already-deleted empty column scaffold.
+      if (
+        replaces &&
+        replaced.some((run) =>
+          decoded.ds.clients.get(run.client)?.some((range) => range.clock < run.clock + run.length && range.clock + range.len > run.clock),
+        )
+      )
+        return false;
+      if (!candidate) {
+        candidate = new Y.Doc();
+        Y.applyUpdate(candidate, Y.encodeStateAsUpdate(doc));
+        Y.applyUpdate(candidate, update);
+        tables = T.findTables(candidate.getText("codemirror").toString());
+      }
+      if (candidate.store.pendingStructs || candidate.store.pendingDs) return false;
+      const text = candidate.getText("codemirror");
+      for (const header of record.tables) {
+        const table = tables!.find((table) => table.lines[0]!.to === resolve(text, header));
+        if (table?.lines.some((line) => line.cells.length !== table.columns)) return false;
+        const before = T.findTables(currentText.toString()).find((table) => table.lines[0]!.to === resolve(currentText, header));
+        // An appended row encodes the entire old column schema. Its width
+        // cannot prove original column identity after that schema was removed.
+        if (before && removed.length)
+          for (const item of introduced) {
+            if (!(item.content instanceof Y.ContentString) || !item.content.str.includes("\n")) continue;
+            for (const id of [item.origin, item.rightOrigin]) {
+              if (!id) continue;
+              const position = Y.createAbsolutePositionFromRelativePosition(new Y.RelativePosition(null, null, id, 0), doc, false);
+              if (position?.type === currentText && position.index >= before.from && position.index <= before.to) return false;
+            }
+          }
+      }
+      return true;
+    },
+    dispose() {
+      candidate?.destroy();
+    },
+  };
+};
+
+export const validateStructuralIngress = (doc: Y.Doc, update: Uint8Array, crossed: readonly SharedTextStructuralHistory[]): boolean => {
+  const validation = createStructuralIngressValidation(doc, update);
+  try {
+    return crossed.every((record) => validation.check(record));
+  } finally {
+    validation.dispose();
+  }
+};