@syncular/server 0.0.6-95 → 0.1.0

package/src/crdt-yjs/index.ts

@@ -0,0 +1,931 @@
+import {
+  type ApplyOperationResult,
+  ServerPushPluginPriority,
+  type SyncChange,
+  type SyncCrdtStateVectorHint,
+  type SyncServerPlugin,
+} from '@syncular/server';
+import { sql } from 'kysely';
+import * as Y from 'yjs';
+
+export const YJS_PAYLOAD_KEY = '__yjs';
+
+const BASE64_PATTERN =
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+export type YjsFieldKind = 'text' | 'xml-fragment' | 'prosemirror';
+
+export interface YjsServerFieldRule {
+  table: string;
+  field: string;
+  /**
+   * Column that stores canonical serialized Yjs state.
+   * Example: "content_yjs_state"
+   */
+  stateColumn: string;
+  /**
+   * Container key inside the Yjs document. Defaults to `field`.
+   */
+  containerKey?: string;
+  /**
+   * Snapshot row id column. Defaults to `id`.
+   */
+  rowIdField?: string;
+  /**
+   * CRDT container type.
+   */
+  kind?: YjsFieldKind;
+}
+
+interface ResolvedYjsServerFieldRule extends YjsServerFieldRule {
+  containerKey: string;
+  rowIdField: string;
+  kind: YjsFieldKind;
+}
+
+export interface YjsServerUpdateEnvelope {
+  updateId: string;
+  updateBase64: string;
+  requiresStateVectorBase64?: string;
+}
+
+export type YjsServerUpdateInput =
+  | YjsServerUpdateEnvelope
+  | readonly YjsServerUpdateEnvelope[];
+
+export interface YjsServerPayloadEnvelope {
+  [field: string]: YjsServerUpdateInput;
+}
+
+export interface BuildYjsTextUpdateArgs {
+  previousStateBase64?: string | Uint8Array | null;
+  nextText: string;
+  containerKey?: string;
+  updateId?: string;
+}
+
+export interface BuildYjsTextUpdateResult {
+  update: YjsServerUpdateEnvelope;
+  nextStateBase64: string;
+  nextText: string;
+}
+
+export interface ApplyYjsTextUpdatesArgs {
+  previousStateBase64?: string | Uint8Array | null;
+  updates: readonly YjsServerUpdateEnvelope[];
+  containerKey?: string;
+}
+
+export interface ApplyYjsTextUpdatesResult {
+  nextStateBase64: string;
+  text: string;
+}
+
+export interface CreateYjsServerModuleOptions {
+  name?: string;
+  rules: readonly YjsServerFieldRule[];
+  envelopeKey?: string;
+  /**
+   * Throw when envelope payload references fields without matching rules.
+   * @default true
+   */
+  strict?: boolean;
+  /**
+   * Remove the Yjs envelope key from processed payload/rows.
+   * @default true
+   */
+  stripEnvelope?: boolean;
+}
+
+export interface CreateYjsServerPushPluginOptions
+  extends CreateYjsServerModuleOptions {
+  priority?: number;
+}
+
+type RuleIndex = Map<string, Map<string, ResolvedYjsServerFieldRule>>;
+
+export interface YjsServerApplyPayloadArgs {
+  table: string;
+  rowId: string;
+  payload: Record<string, unknown>;
+  existingRow?: Record<string, unknown> | null;
+}
+
+export interface YjsServerMaterializeRowArgs {
+  table: string;
+  row: Record<string, unknown>;
+}
+
+export type YjsServerStateVectorHint = SyncCrdtStateVectorHint;
+
+export interface YjsServerTransformPullChangesArgs {
+  table: string;
+  changes: readonly SyncChange[];
+  crdtStateVectors: readonly YjsServerStateVectorHint[];
+}
+
+export interface YjsServerModule {
+  name: string;
+  rules: readonly YjsServerFieldRule[];
+  envelopeKey: string;
+  applyPayload(
+    args: YjsServerApplyPayloadArgs
+  ): Promise<Record<string, unknown>>;
+  materializeRow(
+    args: YjsServerMaterializeRowArgs
+  ): Promise<Record<string, unknown>>;
+  transformPullChanges(
+    args: YjsServerTransformPullChangesArgs
+  ): Promise<readonly SyncChange[]>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function tryReadBase64TextFromBytes(bytes: Uint8Array): string | null {
+  if (bytes.length === 0) return null;
+  try {
+    const decoded = new TextDecoder().decode(bytes).trim();
+    if (!decoded || !BASE64_PATTERN.test(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function base64ToBytes(base64: string): Uint8Array {
+  if (!BASE64_PATTERN.test(base64)) {
+    throw new Error('Invalid base64 string');
+  }
+
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+
+  const binary = atob(base64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+
+function stateValueToBytes(value: unknown): Uint8Array | null {
+  if (value instanceof Uint8Array) {
+    const encoded = tryReadBase64TextFromBytes(value);
+    if (encoded) return base64ToBytes(encoded);
+    return value;
+  }
+  const str = readString(value);
+  if (!str) return null;
+  return base64ToBytes(str);
+}
+
+function stateValueToBase64(value: unknown): string | null {
+  const str = readString(value);
+  if (str) return str;
+  if (value instanceof Uint8Array) {
+    const encoded = tryReadBase64TextFromBytes(value);
+    if (encoded) return encoded;
+    return bytesToBase64(value);
+  }
+  return null;
+}
+
+function createDocFromState(stateValue: unknown): Y.Doc {
+  const doc = new Y.Doc();
+  const bytes = stateValueToBytes(stateValue);
+  if (bytes && bytes.length > 0) {
+    Y.applyUpdate(doc, bytes);
+  }
+  return doc;
+}
+
+function exportSnapshotBase64(doc: Y.Doc): string {
+  return bytesToBase64(Y.encodeStateAsUpdate(doc));
+}
+
+function exportUpdateFromStateVectorBase64(
+  stateValue: unknown,
+  stateVectorBase64: string
+): string | null {
+  const stateBytes = stateValueToBytes(stateValue);
+  if (!stateBytes || stateBytes.length === 0) return null;
+  const stateVector = base64ToBytes(stateVectorBase64);
+  const doc = new Y.Doc();
+  try {
+    Y.applyUpdate(doc, stateBytes);
+    return bytesToBase64(Y.encodeStateAsUpdate(doc, stateVector));
+  } finally {
+    doc.destroy();
+  }
+}
+
+function ensureTextContainer(doc: Y.Doc, containerKey: string): string {
+  return doc.getText(containerKey).toString();
+}
+
+function ensureXmlFragmentContainer(doc: Y.Doc, containerKey: string): string {
+  return doc.getXmlFragment(containerKey).toString();
+}
+
+function replaceText(doc: Y.Doc, containerKey: string, nextText: string): void {
+  const text = doc.getText(containerKey);
+  const currentLength = text.length;
+  doc.transact(() => {
+    if (currentLength > 0) {
+      text.delete(0, currentLength);
+    }
+    if (nextText.length > 0) {
+      text.insert(0, nextText);
+    }
+  });
+}
+
+function patchText(doc: Y.Doc, containerKey: string, nextText: string): void {
+  const text = doc.getText(containerKey);
+  const currentText = text.toString();
+  if (currentText === nextText) return;
+
+  const minLength = Math.min(currentText.length, nextText.length);
+  let prefixLength = 0;
+  while (
+    prefixLength < minLength &&
+    currentText.charCodeAt(prefixLength) === nextText.charCodeAt(prefixLength)
+  ) {
+    prefixLength += 1;
+  }
+
+  let currentSuffixStart = currentText.length;
+  let nextSuffixStart = nextText.length;
+  while (
+    currentSuffixStart > prefixLength &&
+    nextSuffixStart > prefixLength &&
+    currentText.charCodeAt(currentSuffixStart - 1) ===
+      nextText.charCodeAt(nextSuffixStart - 1)
+  ) {
+    currentSuffixStart -= 1;
+    nextSuffixStart -= 1;
+  }
+
+  const deleteLength = currentSuffixStart - prefixLength;
+  const insertSegment = nextText.slice(prefixLength, nextSuffixStart);
+
+  doc.transact(() => {
+    if (deleteLength > 0) {
+      text.delete(prefixLength, deleteLength);
+    }
+    if (insertSegment.length > 0) {
+      text.insert(prefixLength, insertSegment);
+    }
+  });
+}
+
+function materializeRuleValue(
+  doc: Y.Doc,
+  rule: ResolvedYjsServerFieldRule
+): unknown {
+  if (rule.kind === 'text') {
+    return ensureTextContainer(doc, rule.containerKey);
+  }
+  return ensureXmlFragmentContainer(doc, rule.containerKey);
+}
+
+function seedRuleValueFromPayload(
+  doc: Y.Doc,
+  rule: ResolvedYjsServerFieldRule,
+  source: Record<string, unknown>
+): void {
+  if (rule.kind !== 'text') return;
+  const initialText = readString(source[rule.field]);
+  if (initialText) {
+    replaceText(doc, rule.containerKey, initialText);
+  }
+}
+
+function createUpdateId(): string {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  if (typeof randomUUID === 'function') {
+    return randomUUID.call(globalThis.crypto);
+  }
+  const ts = Date.now().toString(36);
+  const rnd = Math.random().toString(36).slice(2, 12);
+  return `yjs-${ts}-${rnd}`;
+}
+
+function buildRuleIndex(rules: readonly YjsServerFieldRule[]): {
+  index: RuleIndex;
+  normalizedRules: readonly ResolvedYjsServerFieldRule[];
+} {
+  const index: RuleIndex = new Map();
+  const normalizedRules: ResolvedYjsServerFieldRule[] = [];
+  const seen = new Set<string>();
+
+  for (const rule of rules) {
+    if (!rule.table.trim()) {
+      throw new Error('YjsServerFieldRule.table cannot be empty');
+    }
+    if (!rule.field.trim()) {
+      throw new Error('YjsServerFieldRule.field cannot be empty');
+    }
+    if (!rule.stateColumn.trim()) {
+      throw new Error('YjsServerFieldRule.stateColumn cannot be empty');
+    }
+
+    const key = `${rule.table}\u001f${rule.field}`;
+    if (seen.has(key)) {
+      throw new Error(
+        `Duplicate Yjs server rule for table "${rule.table}", field "${rule.field}"`
+      );
+    }
+    seen.add(key);
+
+    const resolved: ResolvedYjsServerFieldRule = {
+      ...rule,
+      containerKey: rule.containerKey ?? rule.field,
+      rowIdField: rule.rowIdField ?? 'id',
+      kind: rule.kind ?? 'text',
+    };
+    normalizedRules.push(resolved);
+
+    const tableRules = index.get(resolved.table) ?? new Map();
+    tableRules.set(resolved.field, resolved);
+    index.set(resolved.table, tableRules);
+  }
+
+  return { index, normalizedRules };
+}
+
+function normalizeUpdateEnvelope(
+  value: unknown,
+  context: string
+): YjsServerUpdateEnvelope {
+  if (!isRecord(value)) {
+    throw new Error(`${context} must be an object`);
+  }
+  const updateId = readString(value.updateId);
+  const updateBase64 = readString(value.updateBase64);
+  if (!updateId) {
+    throw new Error(`${context}.updateId must be a non-empty string`);
+  }
+  if (!updateBase64) {
+    throw new Error(
+      `${context}.updateBase64 must be a non-empty base64 string`
+    );
+  }
+  const requiresStateVectorBase64 = readString(value.requiresStateVectorBase64);
+  return {
+    updateId,
+    updateBase64,
+    ...(requiresStateVectorBase64 ? { requiresStateVectorBase64 } : {}),
+  };
+}
+
+function normalizeUpdateEnvelopes(
+  value: unknown,
+  context: string
+): YjsServerUpdateEnvelope[] {
+  if (Array.isArray(value)) {
+    return value.map((entry, i) =>
+      normalizeUpdateEnvelope(entry, `${context}[${i}]`)
+    );
+  }
+  return [normalizeUpdateEnvelope(value, context)];
+}
+
+/*async function applyYjsTextUpdates(
+  args: ApplyYjsTextUpdatesArgs
+): Promise<ApplyYjsTextUpdatesResult> {
+  const containerKey = args.containerKey ?? 'text';
+  const doc = createDocFromState(args.previousStateBase64);
+  try {
+    for (const update of args.updates) {
+      Y.applyUpdate(doc, base64ToBytes(update.updateBase64));
+    }
+    const text = ensureTextContainer(doc, containerKey);
+    const nextStateBase64 = exportSnapshotBase64(doc);
+    return { nextStateBase64, text };
+  } finally {
+    doc.destroy();
+  }
+}*/
+
+export async function buildYjsTextUpdate(
+  args: BuildYjsTextUpdateArgs
+): Promise<BuildYjsTextUpdateResult> {
+  const containerKey = args.containerKey ?? 'text';
+  const doc = createDocFromState(args.previousStateBase64);
+  try {
+    const from = Y.encodeStateVector(doc);
+    patchText(doc, containerKey, args.nextText);
+    const update = bytesToBase64(Y.encodeStateAsUpdate(doc, from));
+    const nextText = ensureTextContainer(doc, containerKey);
+    const nextStateBase64 = exportSnapshotBase64(doc);
+
+    return {
+      update: {
+        updateId: args.updateId ?? createUpdateId(),
+        updateBase64: update,
+      },
+      nextStateBase64,
+      nextText,
+    };
+  } finally {
+    doc.destroy();
+  }
+}
+
+async function materializeRowFromState(args: {
+  table: string;
+  row: Record<string, unknown>;
+  index: RuleIndex;
+  envelopeKey: string;
+  stripEnvelope: boolean;
+}): Promise<Record<string, unknown>> {
+  const tableRules = args.index.get(args.table);
+  if (!tableRules) {
+    if (args.stripEnvelope && args.envelopeKey in args.row) {
+      const next = { ...args.row };
+      delete next[args.envelopeKey];
+      return next;
+    }
+    return args.row;
+  }
+
+  let nextRow: Record<string, unknown> | null = null;
+  const ensureRow = (): Record<string, unknown> => {
+    if (nextRow) return nextRow;
+    nextRow = { ...args.row };
+    return nextRow;
+  };
+
+  for (const rule of tableRules.values()) {
+    const source = nextRow ?? args.row;
+    const stateBase64 = stateValueToBase64(source[rule.stateColumn]);
+    if (!stateBase64) continue;
+
+    const doc = createDocFromState(stateBase64);
+    try {
+      const nextValue = materializeRuleValue(doc, rule);
+      if (source[rule.field] !== nextValue) {
+        ensureRow()[rule.field] = nextValue;
+      }
+    } finally {
+      doc.destroy();
+    }
+  }
+
+  if (args.stripEnvelope) {
+    const source = nextRow ?? args.row;
+    if (args.envelopeKey in source) {
+      const target = ensureRow();
+      delete target[args.envelopeKey];
+    }
+  }
+
+  return nextRow ?? args.row;
+}
+
+async function applyYjsEnvelopeToPayload(args: {
+  table: string;
+  payload: Record<string, unknown>;
+  existingRow?: Record<string, unknown> | null;
+  index: RuleIndex;
+  envelopeKey: string;
+  stripEnvelope: boolean;
+  strict: boolean;
+}): Promise<Record<string, unknown>> {
+  const tableRules = args.index.get(args.table);
+  const rawEnvelope = args.payload[args.envelopeKey];
+
+  if (!tableRules) {
+    if (rawEnvelope !== undefined && args.strict) {
+      throw new Error(
+        `Yjs envelope provided for table "${args.table}" without matching rules`
+      );
+    }
+    if (args.stripEnvelope && rawEnvelope !== undefined) {
+      const next = { ...args.payload };
+      delete next[args.envelopeKey];
+      return next;
+    }
+    return args.payload;
+  }
+
+  const sourceEnvelope = rawEnvelope;
+  if (sourceEnvelope !== undefined && !isRecord(sourceEnvelope)) {
+    throw new Error(
+      `Yjs payload key "${args.envelopeKey}" must be an object for table "${args.table}"`
+    );
+  }
+
+  const basePayload =
+    sourceEnvelope && args.existingRow
+      ? { ...args.existingRow, ...args.payload }
+      : args.payload;
+  let nextPayload: Record<string, unknown> | null =
+    basePayload === args.payload ? null : basePayload;
+  const ensurePayload = (): Record<string, unknown> => {
+    if (nextPayload) return nextPayload;
+    nextPayload = { ...basePayload };
+    return nextPayload;
+  };
+
+  if (sourceEnvelope) {
+    for (const [field, rawUpdateInput] of Object.entries(sourceEnvelope)) {
+      const rule = tableRules.get(field);
+      if (!rule) {
+        if (args.strict) {
+          throw new Error(
+            `No Yjs rule found for envelope field "${field}" on table "${args.table}"`
+          );
+        }
+        continue;
+      }
+
+      const updates = normalizeUpdateEnvelopes(
+        rawUpdateInput,
+        `yjs.${args.table}.${field}`
+      );
+
+      const source = nextPayload ?? basePayload;
+      const existingSource = args.existingRow ?? null;
+      const baseState =
+        (existingSource
+          ? stateValueToBase64(existingSource[rule.stateColumn])
+          : null) ??
+        stateValueToBase64(source[rule.stateColumn]) ??
+        null;
+
+      const requiredBase = updates.find(
+        (update) => update.requiresStateVectorBase64
+      )?.requiresStateVectorBase64;
+      if (!baseState && requiredBase) {
+        throw new Error(
+          `Yjs diff envelope for table "${args.table}" field "${field}" requires local base state vector ${requiredBase}, but no local state is available; full snapshot resync required`
+        );
+      }
+
+      const doc = createDocFromState(baseState);
+      try {
+        if (!baseState) {
+          seedRuleValueFromPayload(doc, rule, source);
+        }
+
+        for (const update of updates) {
+          if (update.requiresStateVectorBase64) {
+            const actualStateVectorBase64 = bytesToBase64(
+              Y.encodeStateVector(doc)
+            );
+            if (actualStateVectorBase64 !== update.requiresStateVectorBase64) {
+              throw new Error(
+                `Yjs update ${update.updateId} requires base state vector ${update.requiresStateVectorBase64}, but current state vector is ${actualStateVectorBase64}; full snapshot resync required`
+              );
+            }
+          }
+          Y.applyUpdate(doc, base64ToBytes(update.updateBase64));
+        }
+
+        const nextValue = materializeRuleValue(doc, rule);
+        const nextStateBase64 = exportSnapshotBase64(doc);
+        const target = ensurePayload();
+        target[rule.field] = nextValue;
+        target[rule.stateColumn] = nextStateBase64;
+      } finally {
+        doc.destroy();
+      }
+    }
+  }
+
+  if (args.stripEnvelope) {
+    const source = nextPayload ?? basePayload;
+    if (args.envelopeKey in source) {
+      const target = ensurePayload();
+      delete target[args.envelopeKey];
+    }
+  }
+
+  return nextPayload ?? args.payload;
+}
+
+function createHintKey(rowId: string, field: string, stateColumn: string) {
+  return `${rowId}\u001f${field}\u001f${stateColumn}`;
+}
+
+function indexStateVectorHints(
+  hints: readonly YjsServerStateVectorHint[]
+): Map<string, YjsServerStateVectorHint> {
+  const indexed = new Map<string, YjsServerStateVectorHint>();
+  for (const hint of hints) {
+    if (hint.syncMode !== 'server-merge') continue;
+    indexed.set(createHintKey(hint.rowId, hint.field, hint.stateColumn), hint);
+  }
+  return indexed;
+}
+
+function transformPullChangeWithStateVectorHints(args: {
+  table: string;
+  change: SyncChange;
+  index: RuleIndex;
+  hintsByKey: ReadonlyMap<string, YjsServerStateVectorHint>;
+  envelopeKey: string;
+}): SyncChange {
+  if (args.change.op !== 'upsert' || !isRecord(args.change.row_json)) {
+    return args.change;
+  }
+
+  const tableRules = args.index.get(args.table);
+  if (!tableRules) return args.change;
+
+  const row = args.change.row_json;
+  let nextRow: Record<string, unknown> | null = null;
+  let envelope: YjsServerPayloadEnvelope | undefined;
+
+  const ensureRow = (): Record<string, unknown> => {
+    if (nextRow) return nextRow;
+    nextRow = { ...row };
+    return nextRow;
+  };
+
+  const ensureEnvelope = (): YjsServerPayloadEnvelope => {
+    if (envelope) return envelope;
+    const target = ensureRow();
+    const existingEnvelope = target[args.envelopeKey];
+    envelope = {};
+    if (isRecord(existingEnvelope)) {
+      for (const [field, updateInput] of Object.entries(existingEnvelope)) {
+        envelope[field] = updateInput as YjsServerUpdateInput;
+      }
+    }
+    target[args.envelopeKey] = envelope;
+    return envelope;
+  };
+
+  for (const rule of tableRules.values()) {
+    const hint = args.hintsByKey.get(
+      createHintKey(args.change.row_id, rule.field, rule.stateColumn)
+    );
+    if (!hint) continue;
+
+    const serverState = row[rule.stateColumn];
+    const updateBase64 = exportUpdateFromStateVectorBase64(
+      serverState,
+      hint.stateVectorBase64
+    );
+    if (!updateBase64) continue;
+
+    const target = ensureRow();
+    delete target[rule.field];
+    delete target[rule.stateColumn];
+    ensureEnvelope()[rule.field] = {
+      updateId: `server:${args.table}:${args.change.row_id}:${rule.field}:${hint.updatedAt}`,
+      updateBase64,
+      requiresStateVectorBase64: hint.stateVectorBase64,
+    };
+  }
+
+  if (!nextRow) return args.change;
+  return {
+    ...args.change,
+    row_json: nextRow,
+  };
+}
+
+async function transformPullChangesWithStateVectorHints(args: {
+  table: string;
+  changes: readonly SyncChange[];
+  index: RuleIndex;
+  envelopeKey: string;
+  crdtStateVectors: readonly YjsServerStateVectorHint[];
+}): Promise<readonly SyncChange[]> {
+  const tableRules = args.index.get(args.table);
+  if (!tableRules || args.crdtStateVectors.length === 0) {
+    return args.changes;
+  }
+  const hintsByKey = indexStateVectorHints(args.crdtStateVectors);
+  if (hintsByKey.size === 0) return args.changes;
+
+  let changed = false;
+  const nextChanges = args.changes.map((change) => {
+    const nextChange = transformPullChangeWithStateVectorHints({
+      table: args.table,
+      change,
+      index: args.index,
+      hintsByKey,
+      envelopeKey: args.envelopeKey,
+    });
+    if (nextChange !== change) changed = true;
+    return nextChange;
+  });
+
+  return changed ? nextChanges : args.changes;
+}
+
+export function createYjsServerModule(
+  options: CreateYjsServerModuleOptions
+): YjsServerModule {
+  if (options.rules.length === 0) {
+    throw new Error(
+      'createYjsServerModule requires at least one table/field rule'
+    );
+  }
+
+  const envelopeKey = options.envelopeKey ?? YJS_PAYLOAD_KEY;
+  const strict = options.strict ?? true;
+  const stripEnvelope = options.stripEnvelope ?? true;
+  const { index } = buildRuleIndex(options.rules);
+
+  return {
+    name: options.name ?? 'crdt-yjs-server',
+    rules: options.rules,
+    envelopeKey,
+
+    async applyPayload(args): Promise<Record<string, unknown>> {
+      return await applyYjsEnvelopeToPayload({
+        table: args.table,
+        payload: args.payload,
+        existingRow: args.existingRow,
+        index,
+        envelopeKey,
+        stripEnvelope,
+        strict,
+      });
+    },
+
+    async materializeRow(args): Promise<Record<string, unknown>> {
+      return await materializeRowFromState({
+        table: args.table,
+        row: args.row,
+        index,
+        envelopeKey,
+        stripEnvelope,
+      });
+    },
+
+    async transformPullChanges(args): Promise<readonly SyncChange[]> {
+      return await transformPullChangesWithStateVectorHints({
+        table: args.table,
+        changes: args.changes,
+        crdtStateVectors: args.crdtStateVectors,
+        index,
+        envelopeKey,
+      });
+    },
+  };
+}
+
+function buildTableRowIdFieldIndex(
+  rules: readonly YjsServerFieldRule[]
+): Map<string, string> {
+  const tableRowIdFields = new Map<string, string>();
+
+  for (const rule of rules) {
+    const rowIdField = rule.rowIdField ?? 'id';
+    const existing = tableRowIdFields.get(rule.table);
+    if (existing && existing !== rowIdField) {
+      throw new Error(
+        `Yjs rules for table "${rule.table}" must use a single rowIdField`
+      );
+    }
+    tableRowIdFields.set(rule.table, rowIdField);
+  }
+
+  return tableRowIdFields;
+}
+
+async function materializeAppliedResult(
+  yjsModule: YjsServerModule,
+  opTable: string,
+  applied: ApplyOperationResult
+): Promise<ApplyOperationResult> {
+  let nextResult: ApplyOperationResult['result'] = applied.result;
+  let resultChanged = false;
+
+  if (nextResult.status === 'conflict' && isRecord(nextResult.server_row)) {
+    const materializedServerRow = await yjsModule.materializeRow({
+      table: opTable,
+      row: nextResult.server_row,
+    });
+    if (materializedServerRow !== nextResult.server_row) {
+      nextResult = {
+        ...nextResult,
+        server_row: materializedServerRow,
+      };
+      resultChanged = true;
+    }
+  }
+
+  let emittedChanged = false;
+  const nextEmitted: ApplyOperationResult['emittedChanges'] = [];
+  for (const emitted of applied.emittedChanges) {
+    if (emitted.op !== 'upsert' || !isRecord(emitted.row_json)) {
+      nextEmitted.push(emitted);
+      continue;
+    }
+
+    const materializedRow = await yjsModule.materializeRow({
+      table: emitted.table,
+      row: emitted.row_json,
+    });
+    if (materializedRow !== emitted.row_json) {
+      emittedChanged = true;
+      nextEmitted.push({
+        ...emitted,
+        row_json: materializedRow,
+      });
+      continue;
+    }
+
+    nextEmitted.push(emitted);
+  }
+
+  if (!resultChanged && !emittedChanged) {
+    return applied;
+  }
+
+  return {
+    result: nextResult,
+    emittedChanges: emittedChanged ? nextEmitted : applied.emittedChanges,
+  };
+}
+
+export function createYjsServerPushPlugin(
+  options: CreateYjsServerPushPluginOptions
+): SyncServerPlugin {
+  const yjsModule = createYjsServerModule(options);
+  const tableRowIdFields = buildTableRowIdFieldIndex(options.rules);
+
+  return {
+    name: options.name ?? yjsModule.name,
+    priority: options.priority ?? ServerPushPluginPriority.CRDT,
+
+    async beforeApplyOperation(args) {
+      const op = args.op;
+      if (op.op !== 'upsert' || !isRecord(op.payload)) {
+        return op;
+      }
+
+      const rowIdField = tableRowIdFields.get(op.table);
+      let existingRow: Record<string, unknown> | null = null;
+
+      if (rowIdField) {
+        const loadedRows = await sql<Record<string, unknown>>`
+          select *
+          from ${sql.table(op.table)}
+          where ${sql.ref(rowIdField)} = ${sql.val(op.row_id)}
+          limit ${sql.val(1)}
+        `.execute(args.ctx.trx);
+        const loadedRow = loadedRows.rows[0];
+        if (loadedRow && isRecord(loadedRow)) {
+          existingRow = loadedRow;
+        }
+      }
+
+      const nextPayload = await yjsModule.applyPayload({
+        table: op.table,
+        rowId: op.row_id,
+        payload: op.payload,
+        existingRow,
+      });
+
+      if (nextPayload === op.payload) return op;
+      return {
+        ...op,
+        payload: nextPayload,
+      };
+    },
+
+    async afterApplyOperation(args) {
+      return await materializeAppliedResult(
+        yjsModule,
+        args.op.table,
+        args.applied
+      );
+    },
+
+    async transformPullChanges(args) {
+      return await yjsModule.transformPullChanges({
+        table: args.subscription.table,
+        changes: args.changes,
+        crdtStateVectors: args.subscription.crdtStateVectors,
+      });
+    },
+  };
+}