@syncular/server 0.15.12 → 0.15.14

package/README.md

@@ -173,6 +173,10 @@ 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.
 
+The task-oriented [concurrency and conflict-correction guide](https://syncular.dev/guide-concurrency-correction/)
+shows version projection, aggregate rollback, corrected replacement commits,
+explicit acknowledgement, and restart-safe recovery UI together.
+
 ## Structured events (the ops seam)
 
 One optional interface, `SyncularServerEvents`, carries every

package/dist/d1-storage.js

@@ -1,3 +1,4 @@
+var _a;
 /**
  * Cloudflare D1 server storage (TODO §4.2 — the Workers deployment rung).
  *
@@ -39,10 +40,19 @@
  * This mirrors PostgreSQL's per-partition row lock, achieved by placement
  * rather than a lock D1 does not expose.
  */
+import { decodeRow } from '@syncular/core';
 import { syncError } from './errors.js';
-import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, upsertSql, upsertValues, } from './relational-rows.js';
+import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
+import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
+function relationalValuesEqual(left, right) {
+    if (left instanceof Uint8Array && right instanceof Uint8Array) {
+        return (left.length === right.length &&
+            left.every((value, index) => value === right[index]));
+    }
+    return Object.is(left, right);
+}
 class D1Transaction {
     #db;
     #partition;
@@ -53,6 +63,7 @@ class D1Transaction {
     /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
     #maxCommitSeq;
     #commitValidationCheckpoint;
+    #lastApplicationOpIndex;
     /**
      * Read-your-own-writes overlay (§6.2 needs `getRow` to see buffered writes
      * of the same commit — e.g. two ops touching the same row): keyed
@@ -77,7 +88,7 @@ class D1Transaction {
     }
     async getRow(table, rowId) {
         this.#assertOpen();
-        const pending = this.#pending.get(D1Transaction.#key(table, rowId));
+        const pending = this.#pending.get(_a.#key(table, rowId));
         if (pending !== undefined) {
             return pending.kind === 'row' ? pending.row : undefined;
         }
@@ -159,14 +170,75 @@ class D1Transaction {
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
     }
-    async upsertRow(table, row) {
+    async #assertNoUniqueCollision(table, row, opIndex) {
+        if (!table.materialize)
+            return;
+        const uniqueIndexes = table.indexes.filter((index) => index.unique === true);
+        if (uniqueIndexes.length === 0)
+            return;
+        const incoming = decodeRow(table.columns, row.payload);
+        for (const index of uniqueIndexes) {
+            const indices = index.columns.map((column) => {
+                const resolved = table.columnIndex.get(column);
+                if (resolved === undefined) {
+                    throw new Error(`compiled unique index references unknown column`);
+                }
+                return resolved;
+            });
+            const values = indices.map((position) => incoming[position] ?? null);
+            // SQLite UNIQUE permits multiple rows when any indexed value is NULL.
+            if (values.some((value) => value === null))
+                continue;
+            for (const [key, pending] of this.#pending) {
+                if (!key.startsWith(`${table.name}\u0000`) || pending.kind !== 'row') {
+                    continue;
+                }
+                if (pending.row.rowId === row.rowId)
+                    continue;
+                const candidate = decodeRow(table.columns, pending.row.payload);
+                if (indices.every((position, valueIndex) => relationalValuesEqual(candidate[position] ?? null, values[valueIndex] ?? null))) {
+                    throw new StorageConstraintError(undefined, opIndex);
+                }
+            }
+            const predicates = index.columns
+                .map((column) => `${quoteIdent(column)}=?`)
+                .join(' AND ');
+            const sql = `SELECT ${quoteIdent('_sync_row_id')} AS row_id FROM ${quoteIdent(table.name)} WHERE ${quoteIdent('_sync_partition')}=? AND ${predicates} AND ${quoteIdent('_sync_row_id')}<>? LIMIT 1`;
+            const bind = indices.map((position, valueIndex) => {
+                const schemaColumn = position === undefined ? undefined : table.columns[position];
+                if (schemaColumn === undefined) {
+                    throw new Error(`compiled unique index references unknown column`);
+                }
+                return toSqlValue(schemaColumn, values[valueIndex] ?? null, 'sqlite');
+            });
+            const persisted = await this.#db
+                .prepare(sql)
+                .bind(this.#partition, ...bind, row.rowId)
+                .first();
+            if (persisted === null)
+                continue;
+            const pending = this.#pending.get(_a.#key(table.name, persisted.row_id));
+            if (pending?.kind === 'deleted')
+                continue;
+            if (pending?.kind === 'row') {
+                const candidate = decodeRow(table.columns, pending.row.payload);
+                const stillCollides = indices.every((position, valueIndex) => relationalValuesEqual(candidate[position] ?? null, values[valueIndex] ?? null));
+                if (!stillCollides)
+                    continue;
+            }
+            throw new StorageConstraintError(undefined, opIndex);
+        }
+    }
+    async upsertRow(table, row, context) {
         this.#assertOpen();
-        this.#pending.set(D1Transaction.#key(table, row.rowId), {
+        const compiled = this.#resolveTable(table);
+        await this.#assertNoUniqueCollision(compiled, row, context?.opIndex);
+        this.#lastApplicationOpIndex = context?.opIndex;
+        this.#pending.set(_a.#key(table, row.rowId), {
             kind: 'row',
             row,
         });
         const p = this.#partition;
-        const compiled = this.#resolveTable(table);
         this.#buffer_(upsertSql(compiled, 'sqlite'), upsertValues(compiled, p, row, 'sqlite'));
         this.#buffer_('DELETE FROM sync_row_scopes WHERE partition=? AND tbl=? AND row_id=?', [p, table, row.rowId]);
         for (const [variable, value] of Object.entries(row.scopes)) {
@@ -175,7 +247,7 @@ class D1Transaction {
     }
     async deleteRow(table, rowId) {
         this.#assertOpen();
-        this.#pending.set(D1Transaction.#key(table, rowId), { kind: 'deleted' });
+        this.#pending.set(_a.#key(table, rowId), { kind: 'deleted' });
         const p = this.#partition;
         this.#buffer_(deleteRowSql(this.#resolveTable(table), 'sqlite'), [
             p,
@@ -237,7 +309,7 @@ class D1Transaction {
     }
     async putPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
-        this.#buffer_('INSERT OR REPLACE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)', [this.#partition, clientId, clientCommitId, serializePushResult(result)]);
+        this.#buffer_('INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)', [this.#partition, clientId, clientCommitId, serializePushResult(result)]);
     }
     async commit() {
         this.#assertOpen();
@@ -246,7 +318,15 @@ class D1Transaction {
             return;
         const statements = this.#buffer.map((entry) => this.#db.prepare(entry.sql).bind(...entry.params));
         // One atomic D1 batch — the §6.4 all-or-nothing commit.
-        await this.#db.batch(statements);
+        try {
+            await this.#db.batch(statements);
+        }
+        catch (error) {
+            if (isD1ConstraintError(error)) {
+                throw new StorageConstraintError(error, this.#lastApplicationOpIndex);
+            }
+            throw error;
+        }
     }
     async rollback() {
         if (!this.#open)
@@ -255,6 +335,7 @@ class D1Transaction {
         this.#buffer.length = 0;
     }
 }
+_a = D1Transaction;
 /**
  * D1 caps bound parameters at 100 per statement; the relational upsert
  * binds one per app column plus the five `_sync_*` meta columns.

package/dist/postgres-storage.js

@@ -2,6 +2,7 @@ import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
 import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
+import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -303,9 +304,17 @@ class PostgresTransaction {
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
     }
-    async upsertRow(table, row) {
+    async upsertRow(table, row, context) {
         this.#assertOpen();
-        await writeRowOn(this.#client, this.#resolveTable(table), this.#partition, row);
+        try {
+            await writeRowOn(this.#client, this.#resolveTable(table), this.#partition, row);
+        }
+        catch (error) {
+            if (isPostgresConstraintError(error)) {
+                throw new StorageConstraintError(error, context?.opIndex);
+            }
+            throw error;
+        }
     }
     async deleteRow(table, rowId) {
         this.#assertOpen();
@@ -371,8 +380,7 @@ class PostgresTransaction {
         this.#assertOpen();
         await this.#client.query(`INSERT INTO sync_push_results(partition, client_id, client_commit_id, result)
        VALUES ($1,$2,$3,$4)
-       ON CONFLICT (partition, client_id, client_commit_id) DO UPDATE
-         SET result=EXCLUDED.result`, [
+       ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING`, [
             this.#partition,
             clientId,
             clientCommitId,

package/dist/push.js

@@ -21,6 +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 { StorageConstraintError } from './storage-errors.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
 /**
  * Extract the blobIds a decoded row references through its `blob_ref`
@@ -263,7 +264,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
             scopes: stored.scopes,
             payload: newPayload,
         };
-        await tx.upsertRow(op.table, newRow);
+        await tx.upsertRow(op.table, newRow, { opIndex });
         return {
             kind: 'applied',
             change: {
@@ -329,7 +330,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         scopes: extracted.scopes,
         payload: insertPayload,
     };
-    await tx.upsertRow(op.table, newRow);
+    await tx.upsertRow(op.table, newRow, { opIndex });
     return {
         kind: 'applied',
         change: {
@@ -481,6 +482,22 @@ function idempotencyCacheMissFrame(clientCommitId, error) {
         ],
     };
 }
+async function persistRejectedPushResult(storage, partition, clientId, clientCommitId, stored) {
+    const rejectionTx = await storage.begin(partition);
+    try {
+        await rejectionTx.putPushResult(clientId, clientCommitId, stored);
+        await rejectionTx.commit();
+    }
+    catch (error) {
+        await rejectionTx.rollback();
+        throw error;
+    }
+    const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
+    if (canonical === undefined) {
+        throw new Error('push rejection finalization did not persist an outcome');
+    }
+    return canonical;
+}
 /**
  * Process one `PUSH_COMMIT` frame: idempotency replay (§2.3), sequential
  * atomic apply (§6.4), realtime notification for applied commits.
@@ -578,15 +595,8 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             }
             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;
-                }
+                const canonical = await persistRejectedPushResult(storage, partition, clientId, frame.clientCommitId, stored);
+                return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
             }
             return resultFrame(frame.clientCommitId, stored, false);
         }
@@ -612,6 +622,22 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
     }
     catch (error) {
         await tx.rollback();
+        if (error instanceof StorageConstraintError) {
+            const stored = {
+                status: 'rejected',
+                results: [
+                    {
+                        opIndex: error.opIndex ?? 0,
+                        status: 'error',
+                        code: 'sync.constraint_violation',
+                        message: 'write violates a relational constraint',
+                        retryable: false,
+                    },
+                ],
+            };
+            const canonical = await persistRejectedPushResult(storage, partition, clientId, frame.clientCommitId, stored);
+            return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+        }
         throw error;
     }
 }

package/dist/sqlite-storage.js

@@ -11,6 +11,7 @@ import { syncError } from './errors.js';
 import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { collectCommitWindowPage, deserializePushResult, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
+import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 class SqliteTransaction {
     #storage;
     #partition;
@@ -50,9 +51,17 @@ class SqliteTransaction {
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
     }
-    async upsertRow(table, row) {
+    async upsertRow(table, row, context) {
         this.#assertOpen();
-        this.#storage.writeRow(this.#partition, table, row);
+        try {
+            this.#storage.writeRow(this.#partition, table, row);
+        }
+        catch (error) {
+            if (isSqliteConstraintError(error)) {
+                throw new StorageConstraintError(error, context?.opIndex);
+            }
+            throw error;
+        }
     }
     async deleteRow(table, rowId) {
         this.#assertOpen();
@@ -93,7 +102,7 @@ class SqliteTransaction {
     async putPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
         this.#storage.db
-            .query('INSERT OR REPLACE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)')
+            .query('INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)')
             .run(this.#partition, clientId, clientCommitId, serializePushResult(result));
     }
     async commit() {

package/dist/storage-errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Privacy-safe storage failures which the push protocol is allowed to turn
+ * into durable application-write rejections. Database-specific errors remain
+ * attached only as an internal cause and never cross the protocol boundary.
+ */
+export declare class StorageConstraintError extends Error {
+    readonly name = "StorageConstraintError";
+    readonly opIndex: number | undefined;
+    constructor(cause: unknown, opIndex?: number);
+}
+/** SQLite primary/extended constraint result codes (`SQLITE_CONSTRAINT*`). */
+export declare function isSqliteConstraintError(error: unknown): boolean;
+/** PostgreSQL SQLSTATE class 23: integrity constraint violation. */
+export declare function isPostgresConstraintError(error: unknown): boolean;
+/**
+ * D1 may preserve SQLite's structured code or expose only a bounded platform
+ * prefix. The text fallback is adapter-private classification only: no part of
+ * the original message is copied to the public StorageConstraintError.
+ */
+export declare function isD1ConstraintError(error: unknown): boolean;

package/dist/storage-errors.js

@@ -0,0 +1,46 @@
+/**
+ * Privacy-safe storage failures which the push protocol is allowed to turn
+ * into durable application-write rejections. Database-specific errors remain
+ * attached only as an internal cause and never cross the protocol boundary.
+ */
+export class StorageConstraintError extends Error {
+    name = 'StorageConstraintError';
+    opIndex;
+    constructor(cause, opIndex) {
+        super('application row violates a relational constraint', { cause });
+        this.opIndex = opIndex;
+    }
+}
+function driverError(error) {
+    return typeof error === 'object' && error !== null
+        ? error
+        : undefined;
+}
+/** SQLite primary/extended constraint result codes (`SQLITE_CONSTRAINT*`). */
+export function isSqliteConstraintError(error) {
+    const candidate = driverError(error);
+    const code = candidate?.code;
+    if (typeof code === 'string' &&
+        (code === 'SQLITE_CONSTRAINT' || code.startsWith('SQLITE_CONSTRAINT_'))) {
+        return true;
+    }
+    const errno = candidate?.errno;
+    return typeof errno === 'number' && (errno & 0xff) === 19;
+}
+/** PostgreSQL SQLSTATE class 23: integrity constraint violation. */
+export function isPostgresConstraintError(error) {
+    const code = driverError(error)?.code;
+    return typeof code === 'string' && /^23[0-9A-Z]{3}$/.test(code);
+}
+/**
+ * D1 may preserve SQLite's structured code or expose only a bounded platform
+ * prefix. The text fallback is adapter-private classification only: no part of
+ * the original message is copied to the public StorageConstraintError.
+ */
+export function isD1ConstraintError(error) {
+    if (isSqliteConstraintError(error))
+        return true;
+    const message = driverError(error)?.message;
+    return (typeof message === 'string' &&
+        /^(?:D1(?:_EXEC)?_ERROR:\s*)?(?:UNIQUE|NOT NULL|CHECK|FOREIGN KEY) constraint failed\b/i.test(message));
+}

package/dist/storage.d.ts

@@ -168,10 +168,16 @@ export interface StorageTransaction {
      * `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>;
+    upsertRow(table: string, row: StoredRow, context?: {
+        readonly opIndex: number;
+    }): Promise<void>;
     deleteRow(table: string, rowId: string): Promise<void>;
     /** Allocates the next per-partition commitSeq and appends the commit. */
     appendCommit(commit: NewCommit): Promise<number>;
+    /**
+     * Persist an idempotency outcome only when the key is still absent. The
+     * first writer wins; callers read the canonical value after commit.
+     */
     putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
     /**
      * Blob reference index (§5.9.4) — ADDITIVE, optional. Set the blobIds a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.15.12",
+  "version": "0.15.14",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -53,7 +53,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.15.12"
+    "@syncular/core": "0.15.14"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/d1-storage.ts

@@ -39,6 +39,7 @@
  * This mirrors PostgreSQL's per-partition row lock, achieved by placement
  * rather than a lock D1 does not expose.
  */
+import { decodeRow, type RowValue } from '@syncular/core';
 import { syncError } from './errors';
 import {
   commitWindowPageSql,
@@ -47,6 +48,7 @@ import {
   layoutsOf,
   migratePayload,
   parseLayouts,
+  quoteIdent,
   retiredTableNames,
   rewritePlan,
   rewriteRowSql,
@@ -59,6 +61,7 @@ import {
   selectRowSql,
   selectRowsForRewriteSql,
   tableColumnNames,
+  toSqlValue,
   upsertSql,
   upsertValues,
 } from './relational-rows';
@@ -91,6 +94,7 @@ import type {
   StoredPushResult,
   StoredRow,
 } from './storage';
+import { isD1ConstraintError, StorageConstraintError } from './storage-errors';
 
 // -- The subset of the D1 API this storage uses (structural typing) ---------
 // Declared locally so the package takes no `@cloudflare/workers-types`
@@ -115,6 +119,16 @@ interface BufferedStatement {
   readonly params: readonly unknown[];
 }
 
+function relationalValuesEqual(left: RowValue, right: RowValue): boolean {
+  if (left instanceof Uint8Array && right instanceof Uint8Array) {
+    return (
+      left.length === right.length &&
+      left.every((value, index) => value === right[index])
+    );
+  }
+  return Object.is(left, right);
+}
+
 /** Read-your-own-writes overlay entry: a buffered upsert, or a deletion. */
 type PendingRow =
   | { readonly kind: 'row'; readonly row: StoredRow }
@@ -132,6 +146,7 @@ class D1Transaction implements StorageTransaction {
   /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
   #maxCommitSeq: number | undefined;
   #commitValidationCheckpoint: number | undefined;
+  #lastApplicationOpIndex: number | undefined;
   /**
    * Read-your-own-writes overlay (§6.2 needs `getRow` to see buffered writes
    * of the same commit — e.g. two ops touching the same row): keyed
@@ -270,14 +285,98 @@ class D1Transaction implements StorageTransaction {
     await this.commit();
   }
 
-  async upsertRow(table: string, row: StoredRow): Promise<void> {
+  async #assertNoUniqueCollision(
+    table: CompiledTable,
+    row: StoredRow,
+    opIndex: number | undefined,
+  ): Promise<void> {
+    if (!table.materialize) return;
+    const uniqueIndexes = table.indexes.filter(
+      (index) => index.unique === true,
+    );
+    if (uniqueIndexes.length === 0) return;
+    const incoming = decodeRow(table.columns, row.payload);
+
+    for (const index of uniqueIndexes) {
+      const indices = index.columns.map((column) => {
+        const resolved = table.columnIndex.get(column);
+        if (resolved === undefined) {
+          throw new Error(`compiled unique index references unknown column`);
+        }
+        return resolved;
+      });
+      const values = indices.map((position) => incoming[position] ?? null);
+      // SQLite UNIQUE permits multiple rows when any indexed value is NULL.
+      if (values.some((value) => value === null)) continue;
+
+      for (const [key, pending] of this.#pending) {
+        if (!key.startsWith(`${table.name}\u0000`) || pending.kind !== 'row') {
+          continue;
+        }
+        if (pending.row.rowId === row.rowId) continue;
+        const candidate = decodeRow(table.columns, pending.row.payload);
+        if (
+          indices.every((position, valueIndex) =>
+            relationalValuesEqual(
+              candidate[position] ?? null,
+              values[valueIndex] ?? null,
+            ),
+          )
+        ) {
+          throw new StorageConstraintError(undefined, opIndex);
+        }
+      }
+
+      const predicates = index.columns
+        .map((column) => `${quoteIdent(column)}=?`)
+        .join(' AND ');
+      const sql = `SELECT ${quoteIdent('_sync_row_id')} AS row_id FROM ${quoteIdent(table.name)} WHERE ${quoteIdent('_sync_partition')}=? AND ${predicates} AND ${quoteIdent('_sync_row_id')}<>? LIMIT 1`;
+      const bind = indices.map((position, valueIndex) => {
+        const schemaColumn =
+          position === undefined ? undefined : table.columns[position];
+        if (schemaColumn === undefined) {
+          throw new Error(`compiled unique index references unknown column`);
+        }
+        return toSqlValue(schemaColumn, values[valueIndex] ?? null, 'sqlite');
+      });
+      const persisted = await this.#db
+        .prepare(sql)
+        .bind(this.#partition, ...bind, row.rowId)
+        .first<{ row_id: string }>();
+      if (persisted === null) continue;
+
+      const pending = this.#pending.get(
+        D1Transaction.#key(table.name, persisted.row_id),
+      );
+      if (pending?.kind === 'deleted') continue;
+      if (pending?.kind === 'row') {
+        const candidate = decodeRow(table.columns, pending.row.payload);
+        const stillCollides = indices.every((position, valueIndex) =>
+          relationalValuesEqual(
+            candidate[position] ?? null,
+            values[valueIndex] ?? null,
+          ),
+        );
+        if (!stillCollides) continue;
+      }
+      throw new StorageConstraintError(undefined, opIndex);
+    }
+  }
+
+  async upsertRow(
+    table: string,
+    row: StoredRow,
+    context?: { readonly opIndex: number },
+  ): Promise<void> {
     this.#assertOpen();
+    const compiled = this.#resolveTable(table);
+    await this.#assertNoUniqueCollision(compiled, row, context?.opIndex);
+    this.#lastApplicationOpIndex = context?.opIndex;
     this.#pending.set(D1Transaction.#key(table, row.rowId), {
       kind: 'row',
       row,
     });
     const p = this.#partition;
-    const compiled = this.#resolveTable(table);
     this.#buffer_(
       upsertSql(compiled, 'sqlite'),
       upsertValues(compiled, p, row, 'sqlite'),
@@ -394,7 +493,7 @@ class D1Transaction implements StorageTransaction {
   ): Promise<void> {
     this.#assertOpen();
     this.#buffer_(
-      'INSERT OR REPLACE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
+      'INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
       [this.#partition, clientId, clientCommitId, serializePushResult(result)],
     );
   }
@@ -407,7 +506,14 @@ class D1Transaction implements StorageTransaction {
       this.#db.prepare(entry.sql).bind(...entry.params),
     );
     // One atomic D1 batch — the §6.4 all-or-nothing commit.
-    await this.#db.batch(statements);
+    try {
+      await this.#db.batch(statements);
+    } catch (error) {
+      if (isD1ConstraintError(error)) {
+        throw new StorageConstraintError(error, this.#lastApplicationOpIndex);
+      }
+      throw error;
+    }
   }
 
   async rollback(): Promise<void> {

package/src/postgres-storage.ts

@@ -84,6 +84,10 @@ import type {
   StoredPushResult,
   StoredRow,
 } from './storage';
+import {
+  isPostgresConstraintError,
+  StorageConstraintError,
+} from './storage-errors';
 
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
@@ -506,14 +510,25 @@ class PostgresTransaction implements StorageTransaction {
     await this.commit();
   }
 
-  async upsertRow(table: string, row: StoredRow): Promise<void> {
+  async upsertRow(
+    table: string,
+    row: StoredRow,
+    context?: { readonly opIndex: number },
+  ): Promise<void> {
     this.#assertOpen();
-    await writeRowOn(
-      this.#client,
-      this.#resolveTable(table),
-      this.#partition,
-      row,
-    );
+    try {
+      await writeRowOn(
+        this.#client,
+        this.#resolveTable(table),
+        this.#partition,
+        row,
+      );
+    } catch (error) {
+      if (isPostgresConstraintError(error)) {
+        throw new StorageConstraintError(error, context?.opIndex);
+      }
+      throw error;
+    }
   }
 
   async deleteRow(table: string, rowId: string): Promise<void> {
@@ -618,8 +633,7 @@ class PostgresTransaction implements StorageTransaction {
     await this.#client.query(
       `INSERT INTO sync_push_results(partition, client_id, client_commit_id, result)
        VALUES ($1,$2,$3,$4)
-       ON CONFLICT (partition, client_id, client_commit_id) DO UPDATE
-         SET result=EXCLUDED.result`,
+       ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING`,
       [
         this.#partition,
         clientId,

package/src/push.ts

@@ -42,6 +42,7 @@ import type {
   StoredCommit,
   StoredPushResult,
 } from './storage';
+import { StorageConstraintError } from './storage-errors';
 import type {
   CommitValidationReader,
   CommitValidator,
@@ -435,7 +436,7 @@ async function applyOperation(
       scopes: stored.scopes,
       payload: newPayload,
     };
-    await tx.upsertRow(op.table, newRow);
+    await tx.upsertRow(op.table, newRow, { opIndex });
     return {
       kind: 'applied',
       change: {
@@ -540,7 +541,7 @@ async function applyOperation(
     scopes: extracted.scopes,
     payload: insertPayload,
   };
-  await tx.upsertRow(op.table, newRow);
+  await tx.upsertRow(op.table, newRow, { opIndex });
   return {
     kind: 'applied',
     change: {
@@ -769,6 +770,32 @@ function idempotencyCacheMissFrame(
   };
 }
 
+async function persistRejectedPushResult(
+  storage: SyncRequestContext['storage'],
+  partition: string,
+  clientId: string,
+  clientCommitId: string,
+  stored: StoredPushResult,
+): Promise<StoredPushResult> {
+  const rejectionTx = await storage.begin(partition);
+  try {
+    await rejectionTx.putPushResult(clientId, clientCommitId, stored);
+    await rejectionTx.commit();
+  } catch (error) {
+    await rejectionTx.rollback();
+    throw error;
+  }
+  const canonical = await storage.getPushResult(
+    partition,
+    clientId,
+    clientCommitId,
+  );
+  if (canonical === undefined) {
+    throw new Error('push rejection finalization did not persist an outcome');
+  }
+  return canonical;
+}
+
 export interface AppliedCommitEvent {
   readonly commit: StoredCommit;
 }
@@ -912,18 +939,18 @@ export async function processPushCommit(
         await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
       } 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;
-        }
+        const canonical = await persistRejectedPushResult(
+          storage,
+          partition,
+          clientId,
+          frame.clientCommitId,
+          stored,
+        );
+        return resultFrame(
+          frame.clientCommitId,
+          canonical,
+          canonical !== stored,
+        );
       }
       return resultFrame(frame.clientCommitId, stored, false);
     }
@@ -949,6 +976,28 @@ export async function processPushCommit(
     return resultFrame(frame.clientCommitId, stored, false);
   } catch (error) {
     await tx.rollback();
+    if (error instanceof StorageConstraintError) {
+      const stored: StoredPushResult = {
+        status: 'rejected',
+        results: [
+          {
+            opIndex: error.opIndex ?? 0,
+            status: 'error',
+            code: 'sync.constraint_violation',
+            message: 'write violates a relational constraint',
+            retryable: false,
+          },
+        ],
+      };
+      const canonical = await persistRejectedPushResult(
+        storage,
+        partition,
+        clientId,
+        frame.clientCommitId,
+        stored,
+      );
+      return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+    }
     throw error;
   }
 }

package/src/sqlite-storage.ts

@@ -57,6 +57,10 @@ import type {
   StoredPushResult,
   StoredRow,
 } from './storage';
+import {
+  isSqliteConstraintError,
+  StorageConstraintError,
+} from './storage-errors';
 
 class SqliteTransaction implements StorageTransaction {
   #storage: SqliteServerStorage;
@@ -113,9 +117,20 @@ class SqliteTransaction implements StorageTransaction {
     await this.commit();
   }
 
-  async upsertRow(table: string, row: StoredRow): Promise<void> {
+  async upsertRow(
+    table: string,
+    row: StoredRow,
+    context?: { readonly opIndex: number },
+  ): Promise<void> {
     this.#assertOpen();
-    this.#storage.writeRow(this.#partition, table, row);
+    try {
+      this.#storage.writeRow(this.#partition, table, row);
+    } catch (error) {
+      if (isSqliteConstraintError(error)) {
+        throw new StorageConstraintError(error, context?.opIndex);
+      }
+      throw error;
+    }
   }
 
   async deleteRow(table: string, rowId: string): Promise<void> {
@@ -209,7 +224,7 @@ class SqliteTransaction implements StorageTransaction {
     this.#assertOpen();
     this.#storage.db
       .query(
-        'INSERT OR REPLACE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
+        'INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
       )
       .run(
         this.#partition,

package/src/storage-errors.ts

@@ -0,0 +1,62 @@
+/**
+ * Privacy-safe storage failures which the push protocol is allowed to turn
+ * into durable application-write rejections. Database-specific errors remain
+ * attached only as an internal cause and never cross the protocol boundary.
+ */
+export class StorageConstraintError extends Error {
+  override readonly name = 'StorageConstraintError';
+  readonly opIndex: number | undefined;
+
+  constructor(cause: unknown, opIndex?: number) {
+    super('application row violates a relational constraint', { cause });
+    this.opIndex = opIndex;
+  }
+}
+
+interface DriverError {
+  readonly code?: unknown;
+  readonly errno?: unknown;
+  readonly message?: unknown;
+}
+
+function driverError(error: unknown): DriverError | undefined {
+  return typeof error === 'object' && error !== null
+    ? (error as DriverError)
+    : undefined;
+}
+
+/** SQLite primary/extended constraint result codes (`SQLITE_CONSTRAINT*`). */
+export function isSqliteConstraintError(error: unknown): boolean {
+  const candidate = driverError(error);
+  const code = candidate?.code;
+  if (
+    typeof code === 'string' &&
+    (code === 'SQLITE_CONSTRAINT' || code.startsWith('SQLITE_CONSTRAINT_'))
+  ) {
+    return true;
+  }
+  const errno = candidate?.errno;
+  return typeof errno === 'number' && (errno & 0xff) === 19;
+}
+
+/** PostgreSQL SQLSTATE class 23: integrity constraint violation. */
+export function isPostgresConstraintError(error: unknown): boolean {
+  const code = driverError(error)?.code;
+  return typeof code === 'string' && /^23[0-9A-Z]{3}$/.test(code);
+}
+
+/**
+ * D1 may preserve SQLite's structured code or expose only a bounded platform
+ * prefix. The text fallback is adapter-private classification only: no part of
+ * the original message is copied to the public StorageConstraintError.
+ */
+export function isD1ConstraintError(error: unknown): boolean {
+  if (isSqliteConstraintError(error)) return true;
+  const message = driverError(error)?.message;
+  return (
+    typeof message === 'string' &&
+    /^(?:D1(?:_EXEC)?_ERROR:\s*)?(?:UNIQUE|NOT NULL|CHECK|FOREIGN KEY) constraint failed\b/i.test(
+      message,
+    )
+  );
+}

package/src/storage.ts

@@ -188,10 +188,18 @@ export interface StorageTransaction {
     clientCommitId: string,
     result: StoredPushResult,
   ): Promise<void>;
-  upsertRow(table: string, row: StoredRow): Promise<void>;
+  upsertRow(
+    table: string,
+    row: StoredRow,
+    context?: { readonly opIndex: number },
+  ): Promise<void>;
   deleteRow(table: string, rowId: string): Promise<void>;
   /** Allocates the next per-partition commitSeq and appends the commit. */
   appendCommit(commit: NewCommit): Promise<number>;
+  /**
+   * Persist an idempotency outcome only when the key is still absent. The
+   * first writer wins; callers read the canonical value after commit.
+   */
   putPushResult(
     clientId: string,
     clientCommitId: string,