@syncular/server 0.9.0 → 0.10.0

package/README.md

@@ -105,9 +105,73 @@ UI. Unknown members, free-form tokens, malformed paths, and over-limit data
 fail at construction. Diagnostic prose stays in `message`; apps should map
 the stable code/details to localized copy instead of displaying that message.
 
-Validators are per-operation. They do not make multi-row or multi-table
-invariants atomic; those require a server-authoritative command or a future
-whole-commit validation seam. A validator must not mutate the row it receives.
+Validators are per-operation. A validator must not mutate the row it receives.
+
+For a multi-row or multi-table invariant, install `commitValidator`. It runs
+once after every operation is staged in the same transaction, and can inspect
+both the decoded sibling operations and final candidate state:
+
+```ts
+import {
+  CommitValidationRejection,
+  type SyncServerConfig,
+} from '@syncular/server';
+
+const config: SyncServerConfig = {
+  schema,
+  storage,
+  segments,
+  resolveScopes,
+  commitValidator: ({ operations }) => {
+    const transition = operations.find(
+      (operation) =>
+        operation.table === 'surgeries' &&
+        operation.row !== undefined &&
+        operation.stored !== undefined &&
+        operation.row.status !== operation.stored.status,
+    );
+    if (transition === undefined) return;
+
+    const hasEvent = operations.some(
+      (operation) =>
+        operation.table === 'surgery_status_events' &&
+        operation.row?.surgery_id === transition.rowId &&
+        operation.row?.status === transition.row?.status,
+    );
+    if (!hasEvent) {
+      throw new CommitValidationRejection(
+        transition.opIndex,
+        'surgery.status_event_required',
+        'diagnostic only',
+        {
+          fieldPaths: ['status'],
+          reason: 'missing_sibling_operation',
+          requiredAction: 'repair_aggregate',
+        },
+      );
+    }
+  },
+};
+```
+
+The callback also receives `read.getRow()` and bounded `read.scanRows()` APIs.
+Those reads see the final candidate state, including staged sibling upserts and
+deletes. Syncular serializes the partition before any operation read so two
+aggregate validators cannot both accept mutually invalid candidates. It also
+re-checks idempotency after taking that lock and persists a rejected outcome
+while the lock is retained, so overlapping duplicate deliveries cannot rerun
+the callback.
+
+SQLite and PostgreSQL provide that serialization directly. D1 does not expose
+an interactive lock: `D1ServerStorage` fails closed unless it is constructed
+inside an external per-partition coordinator with
+`{ commitValidationSerialized: true }` (normally one Durable Object per
+partition). Do not set that assertion on a stateless Worker. Custom storages
+must implement both the transaction lock and candidate scan seam.
+
+Whole-commit validation checks a client-proposed commit; it does not grant
+authority. Privileged operations such as connecting facilities still belong in
+explicit server-authoritative commands.
 
 ## Structured events (the ops seam)
 

package/dist/context.d.ts

@@ -14,7 +14,7 @@ import type { SegmentStore } from './segment-store.js';
 import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
 import type { SqliteImageBuilder } from './sqlite-image.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
-import type { ValidatorRegistry } from './validate.js';
+import type { CommitValidator, ValidatorRegistry } from './validate.js';
 /** SSP2 body content type (§1.1). */
 export declare const SSP2_CONTENT_TYPE = "application/vnd.syncular.sync.v2";
 export interface ResolveScopesArgs {
@@ -94,6 +94,13 @@ export interface SyncServerConfig {
      * process, never on the wire.
      */
     readonly validators?: ValidatorRegistry;
+    /**
+     * §6.8 whole-commit validator. When present, the storage serializes this
+     * partition before operation reads/writes, then invokes the callback once
+     * over every staged decoded operation and candidate-state reader before
+     * commit-log/idempotency append. A throw rolls back the complete commit.
+     */
+    readonly commitValidator?: CommitValidator;
     readonly resolveScopes: ResolveScopes;
     /**
      * §7.3 auth leases. Absent ⇒ the feature is off: no `LEASE` frame is

package/dist/d1-storage.d.ts

@@ -13,9 +13,18 @@ export interface D1Database {
     batch(statements: D1PreparedStatement[]): Promise<unknown[]>;
     exec(query: string): Promise<unknown>;
 }
+export interface D1ServerStorageOptions {
+    /**
+     * Assert that all writes for a partition reach this storage serially.
+     * Required for §6.8 because D1 exposes no interactive transaction lock.
+     * Set this only inside a per-partition Durable Object or equivalent
+     * coordinator; the default fails closed when a commit validator is used.
+     */
+    readonly commitValidationSerialized?: boolean;
+}
 export declare class D1ServerStorage implements ServerStorage {
     #private;
-    constructor(db: D1Database);
+    constructor(db: D1Database, options?: D1ServerStorageOptions);
     /** Apply the schema DDL (idempotent). Call once before use. */
     migrate(): Promise<void>;
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */

package/dist/postgres-storage.js

@@ -225,6 +225,7 @@ class PostgresTransaction {
     #partition;
     #resolveTable;
     #open = true;
+    #commitValidationSavepoint = false;
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
@@ -243,6 +244,65 @@ class PostgresTransaction {
         this.#assertOpen();
         return getRowOn(this.#client, this.#resolveTable(table), this.#partition, rowId);
     }
+    async scanRows(query) {
+        this.#assertOpen();
+        const variables = Object.keys(query.scopeFilter).sort();
+        const firstVariable = variables[0];
+        if (firstVariable === undefined)
+            return [];
+        const firstValues = query.scopeFilter[firstVariable] ?? [];
+        if (firstValues.length === 0)
+            return [];
+        const sql = scanRowPageSql(this.#resolveTable(query.table), firstValues.length, 'postgres');
+        const rows = [];
+        let afterRowId = query.afterRowId ?? '';
+        const batchSize = Math.max(64, query.limit);
+        while (rows.length < query.limit) {
+            const { rows: records } = await this.#client.query(sql, [
+                this.#partition,
+                query.table,
+                firstVariable,
+                ...firstValues,
+                afterRowId,
+                batchSize,
+            ]);
+            if (records.length === 0)
+                break;
+            for (const record of records) {
+                afterRowId = record.row_id;
+                if (record.payload === null || record.payload === undefined)
+                    continue;
+                const stored = toStoredRow(record);
+                if (!matchesEffective(stored.scopes, query.scopeFilter))
+                    continue;
+                rows.push(stored);
+                if (rows.length >= query.limit)
+                    break;
+            }
+            if (records.length < batchSize)
+                break;
+        }
+        return rows;
+    }
+    async lockPartitionForCommitValidation() {
+        this.#assertOpen();
+        await this.#client.query(`INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
+       ON CONFLICT (partition) DO NOTHING`, [this.#partition]);
+        await this.#client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [this.#partition]);
+        await this.#client.query('SAVEPOINT syncular_commit_validation_candidate');
+        this.#commitValidationSavepoint = true;
+    }
+    async commitRejectedPushResult(clientId, clientCommitId, result) {
+        this.#assertOpen();
+        if (!this.#commitValidationSavepoint) {
+            throw new Error('whole-commit rejection requires its validation savepoint');
+        }
+        await this.#client.query('ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate');
+        await this.#client.query('RELEASE SAVEPOINT syncular_commit_validation_candidate');
+        this.#commitValidationSavepoint = false;
+        await this.putPushResult(clientId, clientCommitId, result);
+        await this.commit();
+    }
     async upsertRow(table, row) {
         this.#assertOpen();
         await writeRowOn(this.#client, this.#resolveTable(table), this.#partition, row);

package/dist/push.js

@@ -21,7 +21,7 @@ import { decodeRow, encodeRow, parseBlobRef, } from '@syncular/core';
 import { clockOf } from './context.js';
 import { SyncError } from './errors.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
-import { toValidateRow, ValidationRejection } from './validate.js';
+import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
 /**
  * Extract the blobIds a decoded row references through its `blob_ref`
  * columns (§5.9.4), skipping NULLs. Malformed BlobRefs already failed at
@@ -149,7 +149,18 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     if (op.op === 'delete') {
         if (stored === undefined) {
             // Deleting an absent row is applied (idempotent, §6.2); no change.
-            return { kind: 'applied', change: undefined };
+            return {
+                kind: 'applied',
+                change: undefined,
+                operation: {
+                    opIndex,
+                    op: 'delete',
+                    table: table.name,
+                    rowId: op.rowId,
+                    row: undefined,
+                    stored: undefined,
+                },
+            };
         }
         if (!authorizeWrite(table, stored.scopes, resolved)) {
             return errorRecord(opIndex, 'sync.forbidden', 'delete denied by scope authorization (§3.4)');
@@ -161,7 +172,8 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         // §6.7: validate the delete against the stored row (row = undefined,
         // stored = the row about to be removed). Only reached for an existing
         // row — an absent-row delete is an idempotent no-op above.
-        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, decodeRow(table.columns, stored.payload), opIndex, partition, actorId);
+        const storedValues = decodeRow(table.columns, stored.payload);
+        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId);
         if (deleteReject !== undefined)
             return deleteReject;
         await tx.deleteRow(op.table, op.rowId);
@@ -173,6 +185,15 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
                 op: 'delete',
                 scopes: stored.scopes,
             },
+            operation: {
+                opIndex,
+                op: 'delete',
+                table: table.name,
+                rowId: op.rowId,
+                row: undefined,
+                stored: toValidateRow(table.columns, storedValues),
+                storedServerVersion: stored.serverVersion,
+            },
         };
     }
     // upsert — payload presence is enforced by the envelope codec (§6.1).
@@ -253,6 +274,16 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
                 scopes: stored.scopes,
                 payload: newPayload,
             },
+            operation: {
+                opIndex,
+                op: 'upsert',
+                table: table.name,
+                rowId: op.rowId,
+                row: toValidateRow(table.columns, values),
+                stored: toValidateRow(table.columns, storedValues),
+                storedServerVersion: stored.serverVersion,
+                nextServerVersion: newVersion,
+            },
         };
     }
     // Insert path: no stored row.
@@ -309,6 +340,15 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
             scopes: extracted.scopes,
             payload: insertPayload,
         },
+        operation: {
+            opIndex,
+            op: 'upsert',
+            table: table.name,
+            rowId: op.rowId,
+            row: toValidateRow(table.columns, values),
+            stored: undefined,
+            nextServerVersion: 1,
+        },
     };
 }
 /**
@@ -346,6 +386,73 @@ function missingScopeVariable(table, scopes) {
     }
     return undefined;
 }
+function commitValidationReader(tx, schema) {
+    const tableFor = (name) => {
+        const table = schema.tables.get(name);
+        if (table === undefined) {
+            throw new Error(`commit validator requested unknown table ${JSON.stringify(name)}`);
+        }
+        return table;
+    };
+    return {
+        getRow: async (tableName, rowId) => {
+            const table = tableFor(tableName);
+            const stored = await tx.getRow(tableName, rowId);
+            if (stored === undefined)
+                return undefined;
+            return {
+                row: toValidateRow(table.columns, decodeRow(table.columns, stored.payload)),
+                serverVersion: stored.serverVersion,
+            };
+        },
+        scanRows: async ({ table: tableName, scopeFilter, afterRowId = null, limit = 100, }) => {
+            const table = tableFor(tableName);
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000) {
+                throw new Error('commit validator scan limit must be an integer from 1 to 1,000');
+            }
+            if (tx.scanRows === undefined) {
+                throw new Error('storage transaction does not support commit-validator scans');
+            }
+            const rows = await tx.scanRows({
+                table: tableName,
+                scopeFilter,
+                afterRowId,
+                limit,
+            });
+            return rows.map((stored) => ({
+                row: toValidateRow(table.columns, decodeRow(table.columns, stored.payload)),
+                serverVersion: stored.serverVersion,
+            }));
+        },
+    };
+}
+async function runCommitValidator(validator, tx, schema, clientId, clientCommitId, actorId, partition, operations) {
+    if (validator === undefined)
+        return undefined;
+    try {
+        await validator({
+            clientId,
+            clientCommitId,
+            actorId,
+            partition,
+            operations,
+            read: commitValidationReader(tx, schema),
+        });
+    }
+    catch (error) {
+        if (error instanceof CommitValidationRejection) {
+            if (error.opIndex >= operations.length) {
+                return errorRecord(0, 'sync.constraint_violation', `commit validator rejection names unavailable opIndex ${error.opIndex}`);
+            }
+            return errorRecord(error.opIndex, error.code, error.message, false, error.details);
+        }
+        if (error instanceof ValidationRejection) {
+            return errorRecord(operations[0]?.opIndex ?? 0, error.code, error.message, false, error.details);
+        }
+        return errorRecord(operations[0]?.opIndex ?? 0, 'sync.constraint_violation', `whole-commit validator threw: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return undefined;
+}
 function resultFrame(clientCommitId, stored, replay) {
     const status = stored.status === 'applied' ? (replay ? 'cached' : 'applied') : 'rejected';
     return {
@@ -358,6 +465,22 @@ function resultFrame(clientCommitId, stored, replay) {
         results: [...stored.results],
     };
 }
+function idempotencyCacheMissFrame(clientCommitId, error) {
+    return {
+        type: 'PUSH_RESULT',
+        clientCommitId,
+        status: 'rejected',
+        results: [
+            {
+                opIndex: 0,
+                status: 'error',
+                code: 'sync.idempotency_cache_miss',
+                message: error.message,
+                retryable: true,
+            },
+        ],
+    };
+}
 /**
  * Process one `PUSH_COMMIT` frame: idempotency replay (§2.3), sequential
  * atomic apply (§6.4), realtime notification for applied commits.
@@ -373,20 +496,7 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             error.code === 'sync.idempotency_cache_miss') {
             // §6.3: answer the retryable cache-miss for this commit rather than
             // re-applying. Not persisted — a retry may find a readable record.
-            return {
-                type: 'PUSH_RESULT',
-                clientCommitId: frame.clientCommitId,
-                status: 'rejected',
-                results: [
-                    {
-                        opIndex: 0,
-                        status: 'error',
-                        code: 'sync.idempotency_cache_miss',
-                        message: error.message,
-                        retryable: true,
-                    },
-                ],
-            };
+            return idempotencyCacheMissFrame(frame.clientCommitId, error);
         }
         throw error;
     }
@@ -397,10 +507,38 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
     const blobCtx = { store: ctx.blobs, partition };
     const crdtMergers = ctx.crdtMergers;
     const validators = ctx.validators;
+    const commitValidator = ctx.commitValidator;
     const tx = await storage.begin(partition);
+    const commitRejectedPushResult = tx.commitRejectedPushResult?.bind(tx);
     try {
+        if (commitValidator !== undefined) {
+            if (tx.lockPartitionForCommitValidation === undefined ||
+                commitRejectedPushResult === undefined) {
+                throw new Error('storage transaction does not support atomic whole-commit validation finalization');
+            }
+            await tx.lockPartitionForCommitValidation();
+            // The optimistic lookup above may have raced another request for the
+            // same idempotency key. Re-check after acquiring partition serialization
+            // so a concurrent duplicate never reruns the aggregate validator.
+            try {
+                const serializedPersisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+                if (serializedPersisted !== undefined) {
+                    await tx.rollback();
+                    return resultFrame(frame.clientCommitId, serializedPersisted, true);
+                }
+            }
+            catch (error) {
+                if (error instanceof SyncError &&
+                    error.code === 'sync.idempotency_cache_miss') {
+                    await tx.rollback();
+                    return idempotencyCacheMissFrame(frame.clientCommitId, error);
+                }
+                throw error;
+            }
+        }
         const results = [];
         const changes = [];
+        const validatedOperations = [];
         let terminated;
         for (let opIndex = 0; opIndex < frame.operations.length; opIndex++) {
             const op = frame.operations[opIndex];
@@ -412,25 +550,43 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
                 break;
             }
             results.push({ opIndex, status: 'applied' });
+            validatedOperations.push(outcome.operation);
             if (outcome.change !== undefined)
                 changes.push(outcome.change);
         }
+        if (terminated === undefined) {
+            const commitReject = await runCommitValidator(commitValidator, tx, schema, clientId, frame.clientCommitId, ctx.actorId, partition, validatedOperations);
+            if (commitReject?.kind === 'terminate') {
+                terminated = commitReject.record;
+            }
+        }
         if (terminated !== undefined) {
             // §6.3 rejected: only the terminating operation's record; §6.4:
             // every write of the commit rolls back.
-            await tx.rollback();
             const stored = {
                 status: 'rejected',
                 results: [terminated],
             };
-            const rejectionTx = await storage.begin(partition);
-            try {
-                await rejectionTx.putPushResult(clientId, frame.clientCommitId, stored);
-                await rejectionTx.commit();
+            if (commitValidator !== undefined) {
+                // Discard candidate rows and persist the rejection while retaining the
+                // same partition lock. This closes the duplicate-request race between
+                // rollback and the durable idempotency outcome.
+                if (commitRejectedPushResult === undefined) {
+                    throw new Error('storage transaction lost whole-commit rejection finalization support');
+                }
+                await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
             }
-            catch (error) {
-                await rejectionTx.rollback();
-                throw error;
+            else {
+                await tx.rollback();
+                const rejectionTx = await storage.begin(partition);
+                try {
+                    await rejectionTx.putPushResult(clientId, frame.clientCommitId, stored);
+                    await rejectionTx.commit();
+                }
+                catch (error) {
+                    await rejectionTx.rollback();
+                    throw error;
+                }
             }
             return resultFrame(frame.clientCommitId, stored, false);
         }

package/dist/realtime.d.ts

@@ -20,13 +20,15 @@ import type { ServerSchema } from './schema.js';
 import type { SegmentStore } from './segment-store.js';
 import type { SegmentUrlConfig } from './signed-url.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
-import type { ValidatorRegistry } from './validate.js';
+import type { CommitValidator, ValidatorRegistry } from './validate.js';
 export interface RealtimeHubConfig {
     readonly schema: ServerSchema;
     readonly storage: ServerStorage;
     readonly resolveScopes: ResolveScopes;
     /** §6.7 validators used by sync rounds carried over this socket. */
     readonly validators?: ValidatorRegistry;
+    /** §6.8 whole-commit validator shared with HTTP sync rounds. */
+    readonly commitValidator?: CommitValidator;
     readonly clock?: () => number;
     /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
     readonly maxDeltaBytes?: number;

package/dist/realtime.js

@@ -719,6 +719,9 @@ export class RealtimeHub {
             ...(this.#config.validators !== undefined
                 ? { validators: this.#config.validators }
                 : {}),
+            ...(this.#config.commitValidator !== undefined
+                ? { commitValidator: this.#config.commitValidator }
+                : {}),
             ...(this.#config.clock !== undefined
                 ? { clock: this.#config.clock }
                 : {}),

package/dist/sqlite-storage.js

@@ -15,6 +15,7 @@ class SqliteTransaction {
     #storage;
     #partition;
     #open = true;
+    #commitValidationSavepoint = false;
     constructor(storage, partition) {
         this.#storage = storage;
         this.#partition = partition;
@@ -28,6 +29,27 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.getRow(this.#partition, table, rowId);
     }
+    scanRows(query) {
+        this.#assertOpen();
+        return this.#storage.scanRows(this.#partition, query);
+    }
+    async lockPartitionForCommitValidation() {
+        this.#assertOpen();
+        // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
+        this.#storage.db.exec('SAVEPOINT syncular_commit_validation_candidate');
+        this.#commitValidationSavepoint = true;
+    }
+    async commitRejectedPushResult(clientId, clientCommitId, result) {
+        this.#assertOpen();
+        if (!this.#commitValidationSavepoint) {
+            throw new Error('whole-commit rejection requires its validation savepoint');
+        }
+        this.#storage.db.exec('ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate');
+        this.#storage.db.exec('RELEASE SAVEPOINT syncular_commit_validation_candidate');
+        this.#commitValidationSavepoint = false;
+        await this.putPushResult(clientId, clientCommitId, result);
+        await this.commit();
+    }
     async upsertRow(table, row) {
         this.#assertOpen();
         this.#storage.writeRow(this.#partition, table, row);

package/dist/storage.d.ts

@@ -150,6 +150,24 @@ export interface ScopeActivityQuery {
  */
 export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+    /**
+     * Optional candidate-state scan used only by whole-commit validation.
+     * In-tree SQLite/Postgres/D1 backends implement it with read-your-own-writes
+     * semantics. A custom backend may omit it until `commitValidator` is used.
+     */
+    scanRows?(query: RowScanQuery): Promise<StoredRow[]>;
+    /**
+     * Serialize candidate-state validation for this partition before any row
+     * read/write. Required at runtime when `commitValidator` is configured.
+     */
+    lockPartitionForCommitValidation?(): Promise<void>;
+    /**
+     * §6.8 rejection finalization while the validation serialization lock is
+     * still held: discard every candidate write, persist the rejected
+     * idempotency result, and finish the transaction atomically. Required when
+     * `commitValidator` is configured so a concurrent duplicate cannot rerun it.
+     */
+    commitRejectedPushResult?(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
     upsertRow(table: string, row: StoredRow): Promise<void>;
     deleteRow(table: string, rowId: string): Promise<void>;
     /** Allocates the next per-partition commitSeq and appends the commit. */

package/dist/validate.d.ts

@@ -13,7 +13,7 @@
  * path pays only an `undefined` check per operation and builds no context
  * object — zero cost, the events-seam discipline.
  */
-import { type RejectionDetails, type RowColumn, type RowValue } from '@syncular/core';
+import { type RejectionDetails, type RowColumn, type RowValue, type ScopeMap } from '@syncular/core';
 /**
  * §6.7 reserved code prefixes. A host validator code MUST NOT start with
  * any of these: they namespace the protocol's own error families (§10.2)
@@ -49,6 +49,52 @@ export interface ValidateOperation {
     /** The currently-stored row (update/delete), keyed by column name; undefined on insert. */
     readonly stored: ValidateRow | undefined;
 }
+/**
+ * One authorized, decoded operation presented to the whole-commit validator.
+ * `row` is the final candidate row after scope stripping and CRDT merge;
+ * `stored` is the state observed immediately before this operation. Multiple
+ * operations targeting one row therefore retain their sequential evidence.
+ */
+export interface ValidateCommitOperation extends ValidateOperation {
+    readonly opIndex: number;
+    readonly storedServerVersion?: number;
+    readonly nextServerVersion?: number;
+}
+/** One candidate-state row read from inside the still-open commit transaction. */
+export interface CommitValidationRow {
+    readonly row: ValidateRow;
+    readonly serverVersion: number;
+}
+export interface CommitValidationScanInput {
+    readonly table: string;
+    /** Exact scope filter, using the same AND-across-keys semantics as sync. */
+    readonly scopeFilter: ScopeMap;
+    readonly afterRowId?: string | null;
+    /** Bounded per call by the server to 1..1,000; defaults to 100. */
+    readonly limit?: number;
+}
+/**
+ * Candidate-state reads bound to the same storage transaction as the commit.
+ * Reads observe every staged sibling operation and no uncommitted competing
+ * transaction when the storage's commit-validation lock contract is honored.
+ */
+export interface CommitValidationReader {
+    getRow(table: string, rowId: string): Promise<CommitValidationRow | undefined>;
+    scanRows(input: CommitValidationScanInput): Promise<CommitValidationRow[]>;
+}
+export interface ValidateCommitInput {
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly actorId: string;
+    readonly partition: string;
+    readonly operations: readonly ValidateCommitOperation[];
+    readonly read: CommitValidationReader;
+}
+/**
+ * Runs once after every operation passed protocol/scope/row validation and was
+ * staged, but before commit-log/idempotency append and transaction commit.
+ */
+export type CommitValidator = (input: ValidateCommitInput) => void | Promise<void>;
 /** Ambient context a validator may consult (§6.7). */
 export interface ValidateContext {
     /** Host-authenticated actor (§1.1) performing the write. */
@@ -84,5 +130,14 @@ export declare class ValidationRejection extends Error {
     readonly details: RejectionDetails | undefined;
     constructor(code: string, message?: string, details?: RejectionDetails);
 }
+/**
+ * A whole-commit rejection attributed to one operation for the existing
+ * per-operation PUSH_RESULT envelope. The validator may still describe
+ * multiple affected fields in `details.fieldPaths`.
+ */
+export declare class CommitValidationRejection extends ValidationRejection {
+    readonly opIndex: number;
+    constructor(opIndex: number, code: string, message?: string, details?: RejectionDetails);
+}
 /** Build the column-keyed row object a validator inspects (§6.7). */
 export declare function toValidateRow(columns: readonly RowColumn[], values: readonly RowValue[]): ValidateRow;