@syncular/server 0.20.1 → 0.21.0

package/src/push.ts

@@ -19,6 +19,7 @@
  */
 import {
   decodeRow,
+  decodeSparseRow,
   encodeRow,
   type PushCommitFrame,
   type PushOperation,
@@ -27,10 +28,11 @@ import {
   parseBlobRef,
   type RejectionDetails,
   type RowValue,
+  type SparseRowValue,
 } from '@syncular/core';
 import type { BlobStore } from './blob-store';
 import type { SyncRequestContext } from './context';
-import { clockOf } from './context';
+import { clockOf, limitsOf } from './context';
 import type { CrdtMergerRegistry } from './crdt-merger';
 import { SyncError } from './errors';
 import { emitEvent } from './events';
@@ -42,11 +44,13 @@ import {
 import type { CompiledSchema, CompiledTable } from './schema';
 import type { ResolvedScopes } from './scopes';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes';
+import { decodeColumnVersions, encodeColumnVersions } from './relational-rows';
 import type {
   NewChange,
   StorageTransaction,
   StoredCommit,
   StoredPushResult,
+  StoredRow,
 } from './storage';
 import { StorageConstraintError } from './storage-errors';
 import type {
@@ -79,13 +83,32 @@ function blobIdsInRow(
   return ids;
 }
 
+/** Final state of one staged client operation, as the §6.11 reference pass
+ * sees it after every client operation has been applied to candidate state. */
+interface StagedWrite {
+  readonly table: CompiledTable;
+  readonly op: 'upsert' | 'delete';
+  readonly rowId: string;
+  readonly opIndex: number;
+  /** Final post-merge, post-scope-strip values (upsert only). */
+  readonly values?: readonly RowValue[];
+  /** Stored row observed immediately before the write; undefined on insert. */
+  readonly stored: StoredRow | undefined;
+}
+
+type TerminatingOutcome = {
+  readonly kind: 'terminate';
+  readonly record: PushOperationResult;
+};
+
 type OperationOutcome =
   | {
       readonly kind: 'applied';
       readonly change: NewChange | undefined;
       readonly operation: ValidateCommitOperation;
+      readonly staged: StagedWrite;
     }
-  | { readonly kind: 'terminate'; readonly record: PushOperationResult };
+  | TerminatingOutcome;
 
 function errorRecord(
   opIndex: number,
@@ -93,7 +116,7 @@ function errorRecord(
   message: string,
   retryable = false,
   details?: RejectionDetails,
-): OperationOutcome {
+): TerminatingOutcome {
   return {
     kind: 'terminate',
     record: {
@@ -111,6 +134,7 @@ function conflictRecord(
   opIndex: number,
   serverVersion: number,
   serverRow: Uint8Array,
+  conflictColumns: Uint8Array,
 ): OperationOutcome {
   return {
     kind: 'terminate',
@@ -118,13 +142,26 @@ function conflictRecord(
       opIndex,
       status: 'conflict',
       code: 'sync.version_conflict',
-      message: 'row version does not match baseVersion (§6.2)',
+      message: 'present columns moved past baseVersion (§6.2)',
       serverVersion,
       serverRow,
+      conflictColumns,
     },
   };
 }
 
+/** §6.3 `conflictColumns`: a presence-layout bitmap over the marked columns. */
+function conflictColumnsBitmap(
+  columnCount: number,
+  marked: readonly number[],
+): Uint8Array {
+  const bytes = new Uint8Array(Math.ceil(columnCount / 8));
+  for (const index of marked) {
+    bytes[index >> 3] = (bytes[index >> 3] ?? 0) | (1 << (index & 7));
+  }
+  return bytes;
+}
+
 interface BlobApplyContext {
   readonly store: BlobStore | undefined;
   readonly partition: string;
@@ -149,7 +186,7 @@ async function runValidator(
   opIndex: number,
   partition: string,
   actorId: string,
-): Promise<OperationOutcome | undefined> {
+): Promise<TerminatingOutcome | undefined> {
   const validator = validators?.[table.name];
   if (validator === undefined) return undefined;
   try {
@@ -201,18 +238,22 @@ async function runValidator(
  *
  * A NULL incoming crdt value is a semantic clear, not a merge — it passes
  * through untouched (the app is nulling the column, the same as any other
- * type). Merging only runs for a non-NULL incoming crdt value.
+ * type). Merging only runs for a non-NULL incoming crdt value. `present`
+ * marks the sparse payload's present columns (§6.2): an absent crdt column
+ * is unchanged and never merges.
  */
 async function mergeCrdtColumns(
   table: CompiledTable,
   values: RowValue[],
   storedValues: readonly RowValue[] | undefined,
+  present: readonly boolean[],
   opIndex: number,
   mergers: CrdtMergerRegistry | undefined,
 ): Promise<OperationOutcome | { readonly changed: boolean }> {
   if (table.crdtColumns.length === 0) return { changed: false };
   let changed = false;
   for (const { index, crdtType } of table.crdtColumns) {
+    if (!present[index]) continue;
     const incoming = values[index];
     if (!(incoming instanceof Uint8Array)) continue; // NULL clear or absent
     const merger = mergers?.[crdtType];
@@ -284,6 +325,13 @@ async function applyOperation(
           row: undefined,
           stored: undefined,
         },
+        staged: {
+          table,
+          op: 'delete',
+          rowId: op.rowId,
+          opIndex,
+          stored: undefined,
+        },
       };
     }
     if (!authorizeWrite(table, stored.scopes, resolved)) {
@@ -335,10 +383,13 @@ async function applyOperation(
         stored: toValidateRow(table.columns, storedValues),
         storedServerVersion: stored.serverVersion,
       },
+      staged: { table, op: 'delete', rowId: op.rowId, opIndex, stored },
     };
   }
 
-  // upsert — payload presence is enforced by the envelope codec (§6.1).
+  // upsert — payload presence is enforced by the envelope codec (§6.1). The
+  // payload is a sparse row (§2.4, wire version 3): `undefined` marks an
+  // absent column the apply leaves unchanged.
   const payload = op.payload;
   if (payload === undefined) {
     return errorRecord(
@@ -347,9 +398,9 @@ async function applyOperation(
       'upsert without payload',
     );
   }
-  let values: RowValue[];
+  let sparse: SparseRowValue[];
   try {
-    values = decodeRow(table.columns, payload);
+    sparse = decodeSparseRow(table.columns, table.primaryKeyIndex, payload);
   } catch (error) {
     return errorRecord(
       opIndex,
@@ -357,7 +408,7 @@ async function applyOperation(
       `row payload failed row-codec decode (§1.7): ${error instanceof Error ? error.message : String(error)}`,
     );
   }
-  const pkValue = renderScopeValue(values[table.primaryKeyIndex]);
+  const pkValue = renderScopeValue(sparse[table.primaryKeyIndex] ?? null);
   if (pkValue !== op.rowId) {
     return errorRecord(
       opIndex,
@@ -365,6 +416,8 @@ async function applyOperation(
       'payload primary key does not match rowId',
     );
   }
+  const present = sparse.map((value) => value !== undefined);
+  const presentCount = present.filter(Boolean).length;
 
   if (stored !== undefined) {
     // §3.4 step 2: authorize against the STORED row, never the payload.
@@ -375,42 +428,108 @@ async function applyOperation(
         'write denied by scope authorization (§3.4)',
       );
     }
-    if (op.baseVersion === 0) {
-      // Lost insert race (§6.2); the stored row was authorized above,
-      // so disclosure of the winner is permitted.
-      return conflictRecord(opIndex, stored.serverVersion, stored.payload);
-    }
-    if (
-      op.baseVersion !== undefined &&
-      op.baseVersion !== stored.serverVersion
-    ) {
-      return conflictRecord(opIndex, stored.serverVersion, stored.payload);
-    }
-    // §3.4 rule 5: scope columns are immutable on update — keep the
-    // stored row's scope column values on both the baseVersion and
-    // last-write-wins paths.
     const storedValues = decodeRow(table.columns, stored.payload);
-    let mutated = false;
+    // §3.4 rule 5 / §6.2: scope columns are immutable on update. A present
+    // scope column whose value differs from the stored row is
+    // sync.invalid_request; present and equal applies as a no-op.
     for (const pattern of table.scopePatterns) {
-      const storedValue = storedValues[pattern.columnIndex] ?? null;
-      if (values[pattern.columnIndex] !== storedValue) {
-        values[pattern.columnIndex] = storedValue;
-        mutated = true;
+      const incoming = sparse[pattern.columnIndex];
+      if (incoming === undefined) continue;
+      if ((incoming ?? null) !== (storedValues[pattern.columnIndex] ?? null)) {
+        return errorRecord(
+          opIndex,
+          'sync.invalid_request',
+          'scope column is immutable on update (§3.4)',
+        );
       }
     }
-    // §5.10.3: crdt columns merge (stored ⊕ incoming) — never LWW, never
-    // baseVersion-conflict (they were excluded from the checks above).
+    if (op.baseVersion !== undefined && op.baseVersion > stored.serverVersion) {
+      return errorRecord(
+        opIndex,
+        'sync.invalid_request',
+        'baseVersion exceeds the stored server version (§6.2)',
+      );
+    }
+    // §2.2 column versions. A row stored before column versions carries no
+    // blob: every column sits at the row's current serverVersion. With a
+    // blob, an unlisted column sits at 1.
+    const storedVersions = decodeColumnVersions(stored.columnVersions);
+    const effectiveVersion = (index: number): number =>
+      storedVersions.get(index) ??
+      (stored.columnVersions === undefined ? stored.serverVersion : 1);
+    const crdtIndexes = new Set(
+      table.crdtColumns.map((column) => column.index),
+    );
+    if (op.baseVersion === 0) {
+      // Lost insert race (§6.2); the stored row was authorized above, so
+      // disclosure of the winner is permitted. Every present non-crdt
+      // column exceeds baseVersion 0.
+      const marked: number[] = [];
+      for (let i = 0; i < table.columns.length; i++) {
+        if (present[i] && !crdtIndexes.has(i) && i !== table.primaryKeyIndex) {
+          marked.push(i);
+        }
+      }
+      return conflictRecord(
+        opIndex,
+        stored.serverVersion,
+        stored.payload,
+        conflictColumnsBitmap(table.columns.length, marked),
+      );
+    }
+    if (op.baseVersion !== undefined) {
+      // §6.2: conflict when any present non-crdt column moved past
+      // baseVersion. crdt columns merge and never conflict.
+      const marked: number[] = [];
+      for (let i = 0; i < table.columns.length; i++) {
+        if (
+          present[i] &&
+          !crdtIndexes.has(i) &&
+          effectiveVersion(i) > op.baseVersion
+        ) {
+          marked.push(i);
+        }
+      }
+      if (marked.length > 0) {
+        return conflictRecord(
+          opIndex,
+          stored.serverVersion,
+          stored.payload,
+          conflictColumnsBitmap(table.columns.length, marked),
+        );
+      }
+    }
+    // §6.2 apply: write the present non-crdt columns, merge the present
+    // crdt columns (stored ⊕ incoming, §5.10.3), leave absent columns
+    // unchanged, and increment server_version.
+    const values: RowValue[] = [...storedValues];
+    for (let i = 0; i < table.columns.length; i++) {
+      if (!present[i]) continue;
+      values[i] = sparse[i] ?? null;
+    }
     const mergeOutcome = await mergeCrdtColumns(
       table,
       values,
       storedValues,
+      present,
       opIndex,
       crdtMergers,
     );
     if ('kind' in mergeOutcome) return mergeOutcome;
-    if (mergeOutcome.changed) mutated = true;
-    const newPayload = mutated ? encodeRow(table.columns, values) : payload;
     const newVersion = stored.serverVersion + 1;
+    const nextVersions = new Map<number, number>();
+    for (let i = 0; i < table.columns.length; i++) {
+      // The primary key is immutable: its version never advances past the
+      // insert, so it never enters conflictColumns.
+      const version =
+        present[i] && i !== table.primaryKeyIndex
+          ? newVersion
+          : effectiveVersion(i);
+      if (version > 1) nextVersions.set(i, version);
+    }
+    // The stored payload is always the full-row codec (§2.4): the sparse
+    // push payload never reaches storage, segments, or COMMIT frames.
+    const newPayload = encodeRow(table.columns, values);
     // §6.6 / §5.9.6: verify referenced blobs exist before writing.
     const blobCheck = await checkAndRecordBlobs(
       tx,
@@ -421,9 +540,9 @@ async function applyOperation(
       blobCtx,
     );
     if (blobCheck !== undefined) return blobCheck;
-    // §6.7: validate the merged, scope-stripped row that will persist —
-    // for a crdt column the validator sees the MERGED value (§5.10.3), the
-    // state the store holds, not the raw pushed update.
+    // §6.7: validate the merged row that will persist — for a crdt column
+    // the validator sees the MERGED value (§5.10.3), the state the store
+    // holds, not the raw pushed update.
     const updateReject = await runValidator(
       validators,
       table,
@@ -436,11 +555,13 @@ async function applyOperation(
       actorId,
     );
     if (updateReject !== undefined) return updateReject;
+    const columnVersions = encodeColumnVersions(nextVersions);
     const newRow = {
       rowId: op.rowId,
       serverVersion: newVersion,
       scopes: stored.scopes,
       payload: newPayload,
+      ...(columnVersions !== undefined ? { columnVersions } : {}),
     };
     await tx.upsertRow(op.table, newRow, { opIndex });
     return {
@@ -463,10 +584,12 @@ async function applyOperation(
         storedServerVersion: stored.serverVersion,
         nextServerVersion: newVersion,
       },
+      staged: { table, op: 'upsert', rowId: op.rowId, opIndex, values, stored },
     };
   }
 
-  // Insert path: no stored row.
+  // Insert path: no stored row (§5.2).
+  const values: RowValue[] = sparse.map((value) => value ?? null);
   if (op.baseVersion !== undefined && op.baseVersion !== 0) {
     // Authorize the payload first so absence is not disclosed to actors
     // without the scope; then §6.2: baseVersion ≠ 0, row absent.
@@ -487,6 +610,26 @@ async function applyOperation(
       'upsert with baseVersion targets an absent row (§6.2)',
     );
   }
+  if (op.baseVersion === undefined) {
+    // §5.2: a delete within the retention horizon beats an unversioned
+    // upsert; an explicit insert (baseVersion 0) recreates instead.
+    const tombstoneSeq = await tx.getTombstoneSeq(op.table, op.rowId);
+    if (tombstoneSeq !== undefined) {
+      return errorRecord(
+        opIndex,
+        'sync.row_deleted',
+        'a deleted row rejects an unversioned upsert within the retention horizon (§5.2)',
+      );
+    }
+  }
+  if (presentCount < table.columns.length) {
+    // §6.3: an insert requires every column present.
+    return errorRecord(
+      opIndex,
+      'sync.row_missing',
+      'a partial payload targets an absent row (§6.3)',
+    );
+  }
   const extracted = storedScopesForRow(table, values);
   if ('missing' in extracted) {
     // §3.4 step 2: a missing or empty scope column value ⇒ deny.
@@ -509,13 +652,14 @@ async function applyOperation(
     table,
     values,
     undefined,
+    present,
     opIndex,
     crdtMergers,
   );
   if ('kind' in insertMerge) return insertMerge;
-  const insertPayload = insertMerge.changed
-    ? encodeRow(table.columns, values)
-    : payload;
+  // The stored payload is the full-row codec (§2.4); every column is
+  // present on an insert.
+  const insertPayload = encodeRow(table.columns, values);
   // §6.6 / §5.9.6: verify referenced blobs exist before writing.
   const blobCheck = await checkAndRecordBlobs(
     tx,
@@ -541,6 +685,8 @@ async function applyOperation(
     actorId,
   );
   if (insertReject !== undefined) return insertReject;
+  // §5.2: an explicit insert recreates — the tombstone goes with it.
+  await tx.clearTombstone(op.table, op.rowId);
   const newRow = {
     rowId: op.rowId,
     serverVersion: 1,
@@ -567,6 +713,14 @@ async function applyOperation(
       stored: undefined,
       nextServerVersion: 1,
     },
+    staged: {
+      table,
+      op: 'upsert',
+      rowId: op.rowId,
+      opIndex,
+      values,
+      stored: undefined,
+    },
   };
 }
 
@@ -738,6 +892,291 @@ async function runCommitValidator(
   return undefined;
 }
 
+/** §6.3.1 reference values are bounded to 256 encoded bytes; an over-long
+ * row id still rejects with the same code and reason, and the parent table
+ * name alone names the reference. */
+function parentReference(
+  parentTable: string,
+  parentRowId: string,
+): Readonly<Record<string, string>> {
+  return new TextEncoder().encode(parentRowId).length <= 256
+    ? { parent: parentTable, row: parentRowId }
+    : { parent: parentTable };
+}
+
+function referenceRejection(
+  opIndex: number,
+  message: string,
+  details: RejectionDetails,
+): PushOperationResult {
+  return {
+    opIndex,
+    status: 'error',
+    code: 'sync.reference_violation',
+    message,
+    retryable: false,
+    details,
+  };
+}
+
+/**
+ * §6.11 declared-reference enforcement, once per commit after every client
+ * operation is staged and before whole-commit validation: a present non-null
+ * reference column must name a live parent, and a parent delete expands
+ * through `CASCADE` / `SET NULL` or rejects `restricted_delete` under
+ * `RESTRICT`. Candidate state is read through the transaction, so a commit
+ * that deletes a parent and its children together passes. Appended
+ * operations join the §6.8 staged operation list (`opIndex` ≥ the client
+ * operation count) and emit ordinary changes carrying the child's stored
+ * scopes; a rejection attributes to the originating client delete.
+ */
+async function enforceReferences(
+  tx: StorageTransaction,
+  schema: CompiledSchema,
+  staged: readonly StagedWrite[],
+  clientOpCount: number,
+  cascadeLimit: number,
+  validators: ValidatorRegistry | undefined,
+  partition: string,
+  actorId: string,
+): Promise<
+  | {
+      readonly kind: 'ok';
+      readonly changes: NewChange[];
+      readonly operations: ValidateCommitOperation[];
+      /** Synthetic opIndex → originating client opIndex. */
+      readonly originByIndex: readonly number[];
+    }
+  | { readonly kind: 'terminate'; readonly record: PushOperationResult }
+> {
+  const changes: NewChange[] = [];
+  const operations: ValidateCommitOperation[] = [];
+  const originByIndex: number[] = [];
+
+  for (const write of staged) {
+    if (write.op !== 'upsert' || write.values === undefined) continue;
+    for (const reference of write.table.references) {
+      const value = write.values[reference.columnIndex];
+      if (value === null || value === undefined) continue;
+      const parentRowId = renderScopeValue(value);
+      if (parentRowId === undefined) continue;
+      if ((await tx.getRow(reference.parentTable, parentRowId)) !== undefined) {
+        continue;
+      }
+      return {
+        kind: 'terminate',
+        record: referenceRejection(
+          write.opIndex,
+          'declared reference names an absent parent row (§6.11)',
+          {
+            reason: 'missing_parent',
+            fieldPaths: [reference.column],
+            references: parentReference(reference.parentTable, parentRowId),
+          },
+        ),
+      };
+    }
+  }
+
+  const schedule = (
+    table: CompiledTable,
+    rowId: string,
+    originOpIndex: number,
+    scheduled: Set<string>,
+    queue: Array<{
+      readonly table: CompiledTable;
+      readonly rowId: string;
+      readonly originOpIndex: number;
+    }>,
+  ): boolean => {
+    const key = `${table.name}\u0000${rowId}`;
+    if (scheduled.has(key)) return false;
+    scheduled.add(key);
+    queue.push({ table, rowId, originOpIndex });
+    return true;
+  };
+
+  const scheduled = new Set<string>();
+  const processed = new Set<string>();
+  const queue: Array<{
+    readonly table: CompiledTable;
+    readonly rowId: string;
+    readonly originOpIndex: number;
+  }> = [];
+  for (const write of staged) {
+    if (write.op === 'delete' && write.stored !== undefined) {
+      schedule(write.table, write.rowId, write.opIndex, scheduled, queue);
+    }
+  }
+
+  for (let cursor = 0; cursor < queue.length; cursor++) {
+    const item = queue[cursor];
+    if (item === undefined) continue;
+    const key = `${item.table.name}\u0000${item.rowId}`;
+    if (processed.has(key)) continue;
+    processed.add(key);
+    for (const reference of item.table.referencedBy) {
+      if (tx.scanRowsByIndex === undefined) {
+        throw new Error(
+          'storage transaction does not support declared-reference enforcement (scanRowsByIndex)',
+        );
+      }
+      const children: StoredRow[] = [];
+      let afterRowId: string | null = null;
+      for (;;) {
+        const page = await tx.scanRowsByIndex({
+          table: reference.table,
+          index: reference.index,
+          values: [item.rowId],
+          afterRowId,
+          limit: 1_000,
+        });
+        children.push(...page);
+        if (page.length < 1_000) break;
+        afterRowId = page[page.length - 1]?.rowId ?? null;
+      }
+      if (children.length === 0) continue;
+      if (reference.onDelete === 'RESTRICT') {
+        return {
+          kind: 'terminate',
+          record: referenceRejection(
+            item.originOpIndex,
+            'delete is blocked by a declared reference with ON DELETE RESTRICT (§6.11)',
+            {
+              reason: 'restricted_delete',
+              references: { child: reference.table },
+            },
+          ),
+        };
+      }
+      const child = schema.tables.get(reference.table);
+      if (child === undefined) {
+        throw new Error(
+          `unreachable: reference child table ${reference.table} is not compiled`,
+        );
+      }
+      for (const childRow of children) {
+        if (originByIndex.length >= cascadeLimit) {
+          return {
+            kind: 'terminate',
+            record: referenceRejection(
+              item.originOpIndex,
+              'declared-reference cascade exceeded the per-commit operation cap (§6.11)',
+              { reason: 'cascade_limit' },
+            ),
+          };
+        }
+        if (
+          !schedule(child, childRow.rowId, item.originOpIndex, scheduled, queue)
+        ) {
+          continue;
+        }
+        const syntheticIndex = clientOpCount + originByIndex.length;
+        const storedValues = decodeRow(child.columns, childRow.payload);
+        if (reference.onDelete === 'CASCADE') {
+          const reject = await runValidator(
+            validators,
+            child,
+            'delete',
+            childRow.rowId,
+            undefined,
+            storedValues,
+            item.originOpIndex,
+            partition,
+            actorId,
+          );
+          if (reject !== undefined) {
+            return { kind: 'terminate', record: reject.record };
+          }
+          await tx.deleteRow(child.name, childRow.rowId);
+          changes.push({
+            table: child.name,
+            rowId: childRow.rowId,
+            op: 'delete',
+            scopes: childRow.scopes,
+          });
+          operations.push({
+            opIndex: syntheticIndex,
+            op: 'delete',
+            table: child.name,
+            rowId: childRow.rowId,
+            row: undefined,
+            stored: toValidateRow(child.columns, storedValues),
+            storedServerVersion: childRow.serverVersion,
+          });
+        } else {
+          const values = [...storedValues];
+          values[reference.columnIndex] = null;
+          const reject = await runValidator(
+            validators,
+            child,
+            'upsert',
+            childRow.rowId,
+            values,
+            storedValues,
+            item.originOpIndex,
+            partition,
+            actorId,
+          );
+          if (reject !== undefined) {
+            return { kind: 'terminate', record: reject.record };
+          }
+          const nextServerVersion = childRow.serverVersion + 1;
+          // §6.2: the SET NULL upsert writes only the reference column, so
+          // only that column's version moves.
+          const storedVersions = decodeColumnVersions(childRow.columnVersions);
+          const nextVersions = new Map<number, number>();
+          for (let i = 0; i < child.columns.length; i++) {
+            const version =
+              i === reference.columnIndex
+                ? nextServerVersion
+                : (storedVersions.get(i) ??
+                  (childRow.columnVersions === undefined
+                    ? childRow.serverVersion
+                    : 1));
+            if (version > 1) nextVersions.set(i, version);
+          }
+          const payload = encodeRow(child.columns, values);
+          const cascadeVersions = encodeColumnVersions(nextVersions);
+          await tx.upsertRow(
+            child.name,
+            {
+              rowId: childRow.rowId,
+              serverVersion: nextServerVersion,
+              scopes: childRow.scopes,
+              payload,
+              ...(cascadeVersions !== undefined
+                ? { columnVersions: cascadeVersions }
+                : {}),
+            },
+            { opIndex: syntheticIndex },
+          );
+          changes.push({
+            table: child.name,
+            rowId: childRow.rowId,
+            op: 'upsert',
+            rowVersion: nextServerVersion,
+            scopes: childRow.scopes,
+            payload,
+          });
+          operations.push({
+            opIndex: syntheticIndex,
+            op: 'upsert',
+            table: child.name,
+            rowId: childRow.rowId,
+            row: toValidateRow(child.columns, values),
+            stored: toValidateRow(child.columns, storedValues),
+            storedServerVersion: childRow.serverVersion,
+            nextServerVersion,
+          });
+        }
+        originByIndex.push(item.originOpIndex);
+      }
+    }
+  }
+  return { kind: 'ok', changes, operations, originByIndex };
+}
+
 function resultFrame(
   clientCommitId: string,
   stored: StoredPushResult,
@@ -950,6 +1389,7 @@ export async function processPushOperationsWithTrace(
     const results: PushOperationResult[] = [];
     const changes: NewChange[] = [];
     const validatedOperations: ValidateCommitOperation[] = [];
+    const stagedWrites: StagedWrite[] = [];
     let terminated: PushOperationResult | undefined;
     const operations = await buildOperations(tx);
     for (let opIndex = 0; opIndex < operations.length; opIndex++) {
@@ -973,9 +1413,34 @@ export async function processPushOperationsWithTrace(
       }
       results.push({ opIndex, status: 'applied' });
       validatedOperations.push(outcome.operation);
+      stagedWrites.push(outcome.staged);
       if (outcome.change !== undefined) changes.push(outcome.change);
     }
 
+    // §6.11: reference enforcement runs after every client operation is
+    // staged (so the candidate state is final for the client's own writes)
+    // and before whole-commit validation.
+    let appendedOrigin: readonly number[] = [];
+    if (terminated === undefined) {
+      const referencePass = await enforceReferences(
+        tx,
+        schema,
+        stagedWrites,
+        operations.length,
+        limitsOf(ctx).maxCascadeOperationsPerCommit,
+        validators,
+        partition,
+        ctx.actorId,
+      );
+      if (referencePass.kind === 'terminate') {
+        terminated = referencePass.record;
+      } else {
+        changes.push(...referencePass.changes);
+        validatedOperations.push(...referencePass.operations);
+        appendedOrigin = referencePass.originByIndex;
+      }
+    }
+
     if (terminated === undefined) {
       const commitReject = await runCommitValidator(
         commitValidator,
@@ -988,7 +1453,17 @@ export async function processPushOperationsWithTrace(
         validatedOperations,
       );
       if (commitReject?.kind === 'terminate') {
-        terminated = commitReject.record;
+        // An appended §6.11 cascade operation carries a synthetic opIndex;
+        // surface the originating client operation instead.
+        const rejected = commitReject.record;
+        terminated =
+          rejected.opIndex >= operations.length
+            ? {
+                ...rejected,
+                opIndex:
+                  appendedOrigin[rejected.opIndex - operations.length] ?? 0,
+              }
+            : rejected;
       }
     }