@syncular/server 0.15.40 → 0.15.43

package/README.md

@@ -217,6 +217,16 @@ unknown command outcome, reuse the original idempotency key because changing it
 can execute the operation twice. The full inspection and recovery recipe is in
 the public [server guide](https://syncular.dev/guide-server/#seeding-data).
 
+One extra rule applies when the seed actor changes. A Syncular `clientId` is
+bound to its first actor inside a partition. Keep the client ID stable for seed
+revisions under that actor, but allocate both a new purpose-specific `clientId`
+and a new `commitId` when moving a seed to another actor. Changing only the
+commit ID correctly fails with `sync.invalid_client_id`; do not erase the
+database to bypass that identity evidence. For example, move
+`catalog-import/seed-user/catalog-v1` to
+`catalog-import/server-authority/catalog-v2`, not merely to
+`catalog-import/seed-user/catalog-v2`.
+
 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.

package/dist/d1-storage.js

@@ -64,7 +64,17 @@ class D1Transaction {
     /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
     #maxCommitSeq;
     #pushApplyCheckpoint;
-    #lastApplicationOpIndex;
+    /**
+     * Distinct opIndexes of buffered application upserts. A constraint that
+     * only fires at `db.batch(...)` commit time (e.g. NOT NULL/CHECK the
+     * `#assertNoUniqueCollision` pre-check cannot see) is reported by D1 for
+     * the batch as a whole, and the batch API offers no way to re-run
+     * statements individually without applying them. So attribution at commit
+     * time is exact when the commit buffered exactly one application opIndex
+     * and conservatively omitted otherwise (the push layer then records its
+     * first-op default).
+     */
+    #applicationOpIndexes = new Set();
     /**
      * 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
@@ -99,13 +109,26 @@ class D1Transaction {
             .first();
         return record === null ? undefined : toStoredRow(record);
     }
+    async getPushResult(clientId, clientCommitId) {
+        this.#assertOpen();
+        // D1 reads run in autocommit; the push layer's duplicate re-check happens
+        // before this transaction buffers any write, so a direct read is exact.
+        const record = await this.#db
+            .prepare('SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?')
+            .bind(this.#partition, clientId, clientCommitId)
+            .first();
+        if (record === null)
+            return undefined;
+        try {
+            return deserializePushResult(record.result);
+        }
+        catch {
+            throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
+        }
+    }
     async scanRows(query) {
         this.#assertOpen();
-        assertScopeIndexedScan(query);
-        const variables = Object.keys(query.scopeFilter).sort();
-        const firstVariable = variables[0];
-        if (firstVariable === undefined)
-            return [];
+        const firstVariable = assertScopeIndexedScan(query);
         const firstValues = query.scopeFilter[firstVariable] ?? [];
         if (firstValues.length === 0)
             return [];
@@ -206,6 +229,7 @@ class D1Transaction {
         this.#buffer.length = checkpoint;
         this.#pending.clear();
         this.#maxCommitSeq = undefined;
+        this.#applicationOpIndexes.clear();
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
     }
@@ -272,7 +296,9 @@ class D1Transaction {
         this.#assertOpen();
         const compiled = this.#resolveTable(table);
         await this.#assertNoUniqueCollision(compiled, row, context?.opIndex);
-        this.#lastApplicationOpIndex = context?.opIndex;
+        if (context?.opIndex !== undefined) {
+            this.#applicationOpIndexes.add(context.opIndex);
+        }
         this.#pending.set(_a.#key(table, row.rowId), {
             kind: 'row',
             row,
@@ -367,7 +393,9 @@ class D1Transaction {
                 // D1 batches are atomic. Keep this logical transaction open so the
                 // push layer can discard its buffered candidates and persist the
                 // terminal rejection while the external partition queue is retained.
-                throw new StorageConstraintError(error, this.#lastApplicationOpIndex);
+                // See `#applicationOpIndexes` for the attribution contract.
+                const opIndexes = [...this.#applicationOpIndexes];
+                throw new StorageConstraintError(error, opIndexes.length === 1 ? opIndexes[0] : undefined);
             }
             throw error;
         }
@@ -620,11 +648,7 @@ export class D1ServerStorage {
         return commits;
     }
     async scanRows(partition, query) {
-        assertScopeIndexedScan(query);
-        const variables = Object.keys(query.scopeFilter).sort();
-        const firstVariable = variables[0];
-        if (firstVariable === undefined)
-            return [];
+        const firstVariable = assertScopeIndexedScan(query);
         const firstValues = query.scopeFilter[firstVariable] ?? [];
         if (firstValues.length === 0)
             return [];

package/dist/pg-executor-pglite.d.ts

@@ -8,9 +8,11 @@
  * `PgExecutor` interface (see the server README).
  *
  * pglite is single-connection, so `transaction` runs `BEGIN`/`COMMIT`/
- * `ROLLBACK` on the one connection and relies on the caller not interleaving
- * unrelated queries during a transaction scope (the storage layer holds one
- * transaction at a time per push).
+ * `ROLLBACK` on the one connection. Overlapping `transaction` calls are
+ * serialized through a promise chain (mirroring `SqliteServerStorage`'s
+ * begin() FIFO): a nested BEGIN on Postgres is a warning-level no-op, so
+ * interleaved scopes would silently collapse into one SQL transaction and
+ * break the push layer's serialization guarantee on this dev driver.
  */
 import type { PGlite } from '@electric-sql/pglite';
 import type { PgExecutor } from './pg-executor.js';

package/dist/pg-executor-pglite.js

@@ -12,18 +12,32 @@ function queryable(db) {
 export function pgliteExecutor(db) {
     const like = db;
     const q = queryable(like);
+    // One BEGIN…COMMIT/ROLLBACK scope at a time on the single connection (see
+    // the file header).
+    let transactionTail = Promise.resolve();
     return {
         query: q.query,
         async transaction(fn) {
-            await like.exec('BEGIN');
+            const previous = transactionTail;
+            let release;
+            transactionTail = new Promise((resolve) => {
+                release = resolve;
+            });
+            await previous;
             try {
-                const result = await fn(q);
-                await like.exec('COMMIT');
-                return result;
+                await like.exec('BEGIN');
+                try {
+                    const result = await fn(q);
+                    await like.exec('COMMIT');
+                    return result;
+                }
+                catch (error) {
+                    await like.exec('ROLLBACK');
+                    throw error;
+                }
             }
-            catch (error) {
-                await like.exec('ROLLBACK');
-                throw error;
+            finally {
+                release();
             }
         },
         async close() {

package/dist/postgres-storage.js

@@ -240,6 +240,17 @@ async function writeRowOn(q, compiled, partition, row) {
        VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`, [partition, compiled.name, variable, value, row.rowId]);
     }
 }
+async function getPushResultOn(q, partition, clientId, clientCommitId) {
+    const { rows } = await q.query('SELECT result FROM sync_push_results WHERE partition=$1 AND client_id=$2 AND client_commit_id=$3', [partition, clientId, clientCommitId]);
+    if (rows[0] === undefined)
+        return undefined;
+    try {
+        return deserializePushResult(asJson(rows[0].result));
+    }
+    catch {
+        throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
+    }
+}
 class PostgresTransaction {
     #client;
     #partition;
@@ -264,13 +275,16 @@ class PostgresTransaction {
         this.#assertOpen();
         return getRowOn(this.#client, this.#resolveTable(table), this.#partition, rowId);
     }
+    getPushResult(clientId, clientCommitId) {
+        this.#assertOpen();
+        // Runs on this transaction's pinned client: the push layer's duplicate
+        // re-check happens while the partition lock is held, and a pool-level
+        // read there would wait for a second connection.
+        return getPushResultOn(this.#client, this.#partition, clientId, clientCommitId);
+    }
     async scanRows(query) {
         this.#assertOpen();
-        assertScopeIndexedScan(query);
-        const variables = Object.keys(query.scopeFilter).sort();
-        const firstVariable = variables[0];
-        if (firstVariable === undefined)
-            return [];
+        const firstVariable = assertScopeIndexedScan(query);
         const firstValues = query.scopeFilter[firstVariable] ?? [];
         if (firstValues.length === 0)
             return [];
@@ -498,6 +512,11 @@ export class PostgresServerStorage {
              WHERE table_schema = current_schema() AND table_name = $1`, [table.name]);
                     if (rows.length > 0) {
                         existing.set(table.name, new Set(rows.map((r) => r.column_name)));
+                        // Parity with the SQLite/D1 `origin === 'c'` filter: only
+                        // free-standing indexes enter the rebuild set. Constraint-owned
+                        // indexes (PRIMARY KEY, UNIQUE constraints) can only be removed
+                        // through their constraint, so DROP INDEX on them would abort
+                        // the migration transaction.
                         const indexes = await client.query(`SELECT index_class.relname AS index_name
                  FROM pg_catalog.pg_class AS table_class
                  JOIN pg_catalog.pg_namespace AS namespace
@@ -508,7 +527,12 @@ export class PostgresServerStorage {
                    ON index_class.oid = index_meta.indexrelid
                 WHERE namespace.nspname = current_schema()
                   AND table_class.relname = $1
-                  AND NOT index_meta.indisprimary`, [table.name]);
+                  AND NOT index_meta.indisprimary
+                  AND NOT EXISTS (
+                    SELECT 1
+                      FROM pg_catalog.pg_constraint AS owning_constraint
+                     WHERE owning_constraint.conindid = index_meta.indexrelid
+                  )`, [table.name]);
                         existingIndexes.set(table.name, new Set(indexes.rows.map((index) => index.index_name)));
                     }
                 }
@@ -597,16 +621,8 @@ export class PostgresServerStorage {
     getRow(partition, table, rowId) {
         return getRowOn(this.#exec, this.table(table), partition, rowId);
     }
-    async getPushResult(partition, clientId, clientCommitId) {
-        const { rows } = await this.#exec.query('SELECT result FROM sync_push_results WHERE partition=$1 AND client_id=$2 AND client_commit_id=$3', [partition, clientId, clientCommitId]);
-        if (rows[0] === undefined)
-            return undefined;
-        try {
-            return deserializePushResult(asJson(rows[0].result));
-        }
-        catch {
-            throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
-        }
+    getPushResult(partition, clientId, clientCommitId) {
+        return getPushResultOn(this.#exec, partition, clientId, clientCommitId);
     }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
@@ -697,11 +713,7 @@ export class PostgresServerStorage {
         return commits;
     }
     async scanRows(partition, query) {
-        assertScopeIndexedScan(query);
-        const variables = Object.keys(query.scopeFilter).sort();
-        const firstVariable = variables[0];
-        if (firstVariable === undefined)
-            return [];
+        const firstVariable = assertScopeIndexedScan(query);
         const firstValues = query.scopeFilter[firstVariable] ?? [];
         if (firstValues.length === 0)
             return [];

package/dist/push.js

@@ -551,9 +551,16 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
         await lockPartitionForPush();
         // The optimistic lookup above may have raced another delivery. Re-check
         // only after acquiring partition serialization and before any operation
-        // read, validation, merge, or staged write.
+        // read, validation, merge, or staged write. The re-check runs on the
+        // transaction's own connection when the backend provides one: a pooled
+        // Postgres client holding the partition lock would otherwise wait for a
+        // second pool slot and deadlock against pushes waiting on the lock. A
+        // racing duplicate's result commits before the lock releases, so the
+        // transaction-scoped read observes it.
         try {
-            const serializedPersisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+            const serializedPersisted = tx.getPushResult !== undefined
+                ? await tx.getPushResult(clientId, frame.clientCommitId)
+                : await storage.getPushResult(partition, clientId, frame.clientCommitId);
             if (serializedPersisted !== undefined) {
                 await tx.rollback();
                 return processedPushCommit(frame.clientCommitId, serializedPersisted, true);
@@ -652,12 +659,28 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 await tx.rollback();
                 throw new Error('storage transaction lost atomic push rejection finalization support');
             }
-            await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-            const canonical = await storage.getPushResult(partition, clientId, frame.clientCommitId);
-            if (canonical === undefined) {
-                throw new Error('push rejection finalization did not persist an outcome');
+            try {
+                await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
+                const canonical = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+                if (canonical === undefined) {
+                    throw new Error('push rejection finalization did not persist an outcome');
+                }
+                return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
+            }
+            catch (finalizationError) {
+                // A failed finalization must still release the transaction: on
+                // SQLite an unreleased BEGIN wedges the storage's global begin()
+                // queue, on Postgres it leaks the pinned pool client. rollback() is
+                // a no-op when the finalization already committed.
+                try {
+                    await tx.rollback();
+                }
+                catch {
+                    // Surface the finalization failure; a rollback failure would
+                    // otherwise mask it.
+                }
+                throw finalizationError;
             }
-            return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
         }
         await tx.rollback();
         throw error;

package/dist/relational-rows.d.ts

@@ -69,11 +69,28 @@ export declare function createTableDdl(table: CompiledTable, dialect: Relational
  * `existingColumns` (introspected). Added columns are nullable (header note).
  */
 export declare function addColumnDdl(table: CompiledTable, existingColumns: ReadonlySet<string>, dialect: RelationalDialect): string[];
+/**
+ * Ownership marker for server-created projection indexes. A version bump
+ * rebuilds declared indexes by dropping every index Syncular owns and
+ * re-creating the declared set; this prefix is what marks an index as
+ * Syncular-owned, so operator-added tuning indexes survive bumps. Portable
+ * identifier validation reserves the `sync_` prefix for the server storage
+ * namespace, which keeps user and operator index names out of it.
+ */
+export declare const SYNC_INDEX_PREFIX = "sync_ix_";
+/**
+ * Physical name of one declared index: the ownership prefix plus the
+ * declared name. When that would exceed the 63-byte Postgres identifier
+ * limit, the declared name is replaced by its FNV-1a hash so the physical
+ * name stays deterministic, unique, and within the limit.
+ */
+export declare function physicalIndexName(declaredName: string): string;
 /**
  * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes
- * (DESIGN "user indexes" — the same names/columns the client materializes;
- * cross-table index-name uniqueness is the user's schema concern, exactly
- * as it is client-side).
+ * (DESIGN "user indexes" — the same declared names/columns the client
+ * materializes; cross-table index-name uniqueness is the user's schema
+ * concern, exactly as it is client-side). Server-side the physical name
+ * carries the {@link SYNC_INDEX_PREFIX} ownership marker.
  */
 export declare function createIndexDdl(table: CompiledTable): string[];
 /** Idempotent removal of one Syncular-owned relational projection index. */
@@ -246,5 +263,11 @@ export declare function rewritePlan(table: CompiledTable, oldLayout: readonly St
  * missing columns, and rebuild declared secondary indexes. Rebuilding during
  * a version bump supports DROP INDEX and same-name index replacement without
  * requiring historical index definitions in the stored column-layout marker.
+ *
+ * The drop set is limited to Syncular-owned indexes: physical names carrying
+ * {@link SYNC_INDEX_PREFIX}, plus bare declared names (databases whose
+ * projection indexes predate the ownership prefix migrate onto the prefixed
+ * scheme through this rule). Operator-added tuning indexes keep their own
+ * names and survive every bump.
  */
 export declare function schemaDdl(schema: CompiledSchema, existingColumnsByTable: ReadonlyMap<string, ReadonlySet<string>>, dialect: RelationalDialect, existingIndexesByTable?: ReadonlyMap<string, ReadonlySet<string>>): string[];

package/dist/relational-rows.js

@@ -144,11 +144,43 @@ export function addColumnDdl(table, existingColumns, dialect) {
     }
     return out;
 }
+/**
+ * Ownership marker for server-created projection indexes. A version bump
+ * rebuilds declared indexes by dropping every index Syncular owns and
+ * re-creating the declared set; this prefix is what marks an index as
+ * Syncular-owned, so operator-added tuning indexes survive bumps. Portable
+ * identifier validation reserves the `sync_` prefix for the server storage
+ * namespace, which keeps user and operator index names out of it.
+ */
+export const SYNC_INDEX_PREFIX = 'sync_ix_';
+/** Deterministic FNV-1a 64-bit hash, hex-encoded. Dependency-free so it runs
+ * identically on every server runtime. */
+function fnv1a64Hex(value) {
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of new TextEncoder().encode(value)) {
+        hash ^= BigInt(byte);
+        hash = (hash * 0x100000001b3n) & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/**
+ * Physical name of one declared index: the ownership prefix plus the
+ * declared name. When that would exceed the 63-byte Postgres identifier
+ * limit, the declared name is replaced by its FNV-1a hash so the physical
+ * name stays deterministic, unique, and within the limit.
+ */
+export function physicalIndexName(declaredName) {
+    const prefixed = `${SYNC_INDEX_PREFIX}${declaredName}`;
+    if (new TextEncoder().encode(prefixed).length <= 63)
+        return prefixed;
+    return `${SYNC_INDEX_PREFIX}${fnv1a64Hex(declaredName)}`;
+}
 /**
  * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes
- * (DESIGN "user indexes" — the same names/columns the client materializes;
- * cross-table index-name uniqueness is the user's schema concern, exactly
- * as it is client-side).
+ * (DESIGN "user indexes" — the same declared names/columns the client
+ * materializes; cross-table index-name uniqueness is the user's schema
+ * concern, exactly as it is client-side). Server-side the physical name
+ * carries the {@link SYNC_INDEX_PREFIX} ownership marker.
  */
 export function createIndexDdl(table) {
     // User indexes name app columns — nothing to index without the projection.
@@ -159,7 +191,7 @@ export function createIndexDdl(table) {
         const columns = index.columns
             .map((column) => quoteIdent(column))
             .join(', ');
-        return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(index.name)} ON ${quoteIdent(table.name)} (${columns})`;
+        return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(physicalIndexName(index.name))} ON ${quoteIdent(table.name)} (${columns})`;
     });
 }
 /** Idempotent removal of one Syncular-owned relational projection index. */
@@ -541,21 +573,35 @@ export function rewritePlan(table, oldLayout, physicalColumnsBefore) {
  * missing columns, and rebuild declared secondary indexes. Rebuilding during
  * a version bump supports DROP INDEX and same-name index replacement without
  * requiring historical index definitions in the stored column-layout marker.
+ *
+ * The drop set is limited to Syncular-owned indexes: physical names carrying
+ * {@link SYNC_INDEX_PREFIX}, plus bare declared names (databases whose
+ * projection indexes predate the ownership prefix migrate onto the prefixed
+ * scheme through this rule). Operator-added tuning indexes keep their own
+ * names and survive every bump.
  */
 export function schemaDdl(schema, existingColumnsByTable, dialect, existingIndexesByTable = new Map()) {
-    const out = [];
+    const drops = [];
+    const creates = [];
     for (const table of schema.tables.values()) {
         const existing = existingColumnsByTable.get(table.name);
         if (existing === undefined) {
-            out.push(createTableDdl(table, dialect));
+            creates.push(createTableDdl(table, dialect));
         }
         else {
+            const declared = new Set(table.indexes.map((index) => index.name));
             for (const indexName of existingIndexesByTable.get(table.name) ?? []) {
-                out.push(dropIndexDdl(indexName));
+                if (indexName.startsWith(SYNC_INDEX_PREFIX) ||
+                    declared.has(indexName)) {
+                    drops.push(dropIndexDdl(indexName));
+                }
             }
-            out.push(...addColumnDdl(table, existing, dialect));
+            creates.push(...addColumnDdl(table, existing, dialect));
         }
-        out.push(...createIndexDdl(table));
+        creates.push(...createIndexDdl(table));
     }
-    return out;
+    // Every drop precedes every create: an index name moving between tables in
+    // one bump must release the global (SQLite) index namespace before the
+    // receiving table re-creates it.
+    return [...drops, ...creates];
 }

package/dist/schema.js

@@ -8,11 +8,8 @@
 import { validatePortableRelationalIdentifier, } from '@syncular/core';
 const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
 /**
- * Identifier rules for relational server storage (DESIGN "current-row
- * tables"): app tables live in the same namespace as the sync
- * infrastructure tables (`sync_*`) and carry `_sync_*` meta columns, so
- * both prefixes are reserved; identifiers over 63 bytes would be silently
- * truncated by Postgres.
+ * Compile one `prefix:{variable}` scope pattern against the table's column
+ * list, resolving the scope column's positional index for row extraction.
  */
 function compilePattern(table, spec, columnIndex) {
     const pattern = typeof spec === 'string' ? spec : spec.pattern;
@@ -40,6 +37,11 @@ export function compileSchema(schema) {
         if (tables.has(table.name)) {
             throw new Error(`duplicate table ${JSON.stringify(table.name)}`);
         }
+        // Identifier rules (DESIGN "current-row tables") live in core's
+        // validatePortableRelationalIdentifier, shared with typegen: app tables
+        // share a namespace with the sync infrastructure tables (`sync_*`) and
+        // carry `_sync_*` meta columns, so both prefixes are reserved, and
+        // Postgres silently truncates identifiers over 63 bytes.
         validatePortableRelationalIdentifier('table', table.name);
         const columnIndex = new Map();
         table.columns.forEach((column, index) => {

package/dist/sqlite-storage.js

@@ -33,6 +33,12 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.getRow(this.#partition, table, rowId);
     }
+    getPushResult(clientId, clientCommitId) {
+        this.#assertOpen();
+        // One shared bun:sqlite connection — this read runs inside this
+        // transaction's BEGIN IMMEDIATE.
+        return this.#storage.getPushResult(this.#partition, clientId, clientCommitId);
+    }
     scanRows(query) {
         this.#assertOpen();
         return this.#storage.scanRows(this.#partition, query);
@@ -114,11 +120,25 @@ class SqliteTransaction {
     }
     async commit() {
         this.#assertOpen();
-        this.#open = false;
         try {
             this.#storage.db.exec('COMMIT');
         }
+        catch (error) {
+            // A failed COMMIT (SQLITE_BUSY from an external writer, I/O error)
+            // leaves the connection inside BEGIN IMMEDIATE. Roll back before the
+            // FIFO releases, so the next queued transaction starts on a clean
+            // connection.
+            try {
+                this.#storage.db.exec('ROLLBACK');
+            }
+            catch {
+                // Surface the COMMIT failure; a rollback failure would otherwise
+                // mask it.
+            }
+            throw error;
+        }
         finally {
+            this.#open = false;
             this.#release();
         }
     }
@@ -251,6 +271,10 @@ export class SqliteServerStorage {
         }
     }
     async begin(partition) {
+        // Deliberately global across partitions: SQLite is single-writer per
+        // database file, so one FIFO over the shared connection is the correct
+        // serialization unit — a per-partition queue would still contend on the
+        // same BEGIN IMMEDIATE writer lock.
         const previous = this.#transactionTail;
         let release;
         this.#transactionTail = new Promise((resolve) => {
@@ -370,11 +394,7 @@ export class SqliteServerStorage {
         return commits;
     }
     async scanRows(partition, query) {
-        assertScopeIndexedScan(query);
-        const variables = Object.keys(query.scopeFilter).sort();
-        const firstVariable = variables[0];
-        if (firstVariable === undefined)
-            return [];
+        const firstVariable = assertScopeIndexedScan(query);
         const firstValues = query.scopeFilter[firstVariable] ?? [];
         if (firstValues.length === 0)
             return [];

package/dist/storage-query.d.ts

@@ -1,6 +1,10 @@
 import type { CompiledTable, IndexSchema } from './schema.js';
 import type { IndexRowScanQuery, RowScanQuery } from './storage.js';
-/** Fail loudly instead of making an unsupported unscoped scan look empty. */
-export declare function assertScopeIndexedScan(query: RowScanQuery): void;
+/**
+ * Fail loudly instead of making an unsupported unscoped scan look empty.
+ * Returns the first scope variable in sorted order — the one every adapter
+ * drives its inverted-index candidate selection with.
+ */
+export declare function assertScopeIndexedScan(query: RowScanQuery): string;
 /** Validate and resolve one exact trusted-host relational index lookup. */
 export declare function resolveIndexRowScan(table: CompiledTable, query: IndexRowScanQuery): IndexSchema;

package/dist/storage-query.js

@@ -1,12 +1,18 @@
 import { StorageQueryError } from './storage-errors.js';
-/** Fail loudly instead of making an unsupported unscoped scan look empty. */
+/**
+ * Fail loudly instead of making an unsupported unscoped scan look empty.
+ * Returns the first scope variable in sorted order — the one every adapter
+ * drives its inverted-index candidate selection with.
+ */
 export function assertScopeIndexedScan(query) {
     const scopeFilter = query.scopeFilter;
-    if (scopeFilter === undefined ||
-        scopeFilter === null ||
-        Object.keys(scopeFilter).length === 0) {
+    const firstVariable = scopeFilter === undefined || scopeFilter === null
+        ? undefined
+        : Object.keys(scopeFilter).sort()[0];
+    if (firstVariable === undefined) {
         throw new StorageQueryError('sync.storage.scan_requires_scope');
     }
+    return firstVariable;
 }
 /** Validate and resolve one exact trusted-host relational index lookup. */
 export function resolveIndexRowScan(table, query) {

package/dist/storage.d.ts

@@ -173,6 +173,17 @@ export interface ScopeActivityQuery {
  */
 export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+    /**
+     * Optional transaction-scoped idempotency lookup (§2.3) with the same
+     * semantics as `ServerStorage.getPushResult`, including the
+     * `sync.idempotency_cache_miss` throw. The push layer prefers it for the
+     * post-serialization duplicate re-check so the read runs on the
+     * transaction's own connection — a pooled Postgres client that holds the
+     * partition lock must never wait for a second pool slot mid-push. In-tree
+     * SQLite/Postgres/D1 adapters implement it; a custom adapter that omits it
+     * keeps the pool-level read.
+     */
+    getPushResult?(clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
     /**
      * Optional candidate-state scan used only by whole-commit validation.
      * In-tree SQLite/Postgres/D1 backends implement it with read-your-own-writes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.15.40",
+  "version": "0.15.43",
   "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.40"
+    "@syncular/core": "0.15.43"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/d1-storage.ts

@@ -149,7 +149,17 @@ class D1Transaction implements StorageTransaction {
   /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
   #maxCommitSeq: number | undefined;
   #pushApplyCheckpoint: number | undefined;
-  #lastApplicationOpIndex: number | undefined;
+  /**
+   * Distinct opIndexes of buffered application upserts. A constraint that
+   * only fires at `db.batch(...)` commit time (e.g. NOT NULL/CHECK the
+   * `#assertNoUniqueCollision` pre-check cannot see) is reported by D1 for
+   * the batch as a whole, and the batch API offers no way to re-run
+   * statements individually without applying them. So attribution at commit
+   * time is exact when the commit buffered exactly one application opIndex
+   * and conservatively omitted otherwise (the push layer then records its
+   * first-op default).
+   */
+  readonly #applicationOpIndexes = new Set<number>();
   /**
    * 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
@@ -194,12 +204,33 @@ class D1Transaction implements StorageTransaction {
     return record === null ? undefined : toStoredRow(record);
   }
 
+  async getPushResult(
+    clientId: string,
+    clientCommitId: string,
+  ): Promise<StoredPushResult | undefined> {
+    this.#assertOpen();
+    // D1 reads run in autocommit; the push layer's duplicate re-check happens
+    // before this transaction buffers any write, so a direct read is exact.
+    const record = await this.#db
+      .prepare(
+        'SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?',
+      )
+      .bind(this.#partition, clientId, clientCommitId)
+      .first<{ result: string }>();
+    if (record === null) return undefined;
+    try {
+      return deserializePushResult(record.result);
+    } catch {
+      throw syncError(
+        'sync.idempotency_cache_miss',
+        'persisted push result unreadable (§6.3)',
+      );
+    }
+  }
+
   async scanRows(query: RowScanQuery): Promise<StoredRow[]> {
     this.#assertOpen();
-    assertScopeIndexedScan(query);
-    const variables = Object.keys(query.scopeFilter).sort();
-    const firstVariable = variables[0];
-    if (firstVariable === undefined) return [];
+    const firstVariable = assertScopeIndexedScan(query);
     const firstValues = query.scopeFilter[firstVariable] ?? [];
     if (firstValues.length === 0) return [];
 
@@ -337,6 +368,7 @@ class D1Transaction implements StorageTransaction {
     this.#buffer.length = checkpoint;
     this.#pending.clear();
     this.#maxCommitSeq = undefined;
+    this.#applicationOpIndexes.clear();
     await this.putPushResult(clientId, clientCommitId, result);
     await this.commit();
   }
@@ -427,7 +459,9 @@ class D1Transaction implements StorageTransaction {
     this.#assertOpen();
     const compiled = this.#resolveTable(table);
     await this.#assertNoUniqueCollision(compiled, row, context?.opIndex);
-    this.#lastApplicationOpIndex = context?.opIndex;
+    if (context?.opIndex !== undefined) {
+      this.#applicationOpIndexes.add(context.opIndex);
+    }
     this.#pending.set(D1Transaction.#key(table, row.rowId), {
       kind: 'row',
       row,
@@ -572,7 +606,12 @@ class D1Transaction implements StorageTransaction {
         // D1 batches are atomic. Keep this logical transaction open so the
         // push layer can discard its buffered candidates and persist the
         // terminal rejection while the external partition queue is retained.
-        throw new StorageConstraintError(error, this.#lastApplicationOpIndex);
+        // See `#applicationOpIndexes` for the attribution contract.
+        const opIndexes = [...this.#applicationOpIndexes];
+        throw new StorageConstraintError(
+          error,
+          opIndexes.length === 1 ? opIndexes[0] : undefined,
+        );
       }
       throw error;
     }
@@ -928,10 +967,7 @@ export class D1ServerStorage implements ServerStorage {
   }
 
   async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
-    assertScopeIndexedScan(query);
-    const variables = Object.keys(query.scopeFilter).sort();
-    const firstVariable = variables[0];
-    if (firstVariable === undefined) return [];
+    const firstVariable = assertScopeIndexedScan(query);
     const firstValues = query.scopeFilter[firstVariable] ?? [];
     if (firstValues.length === 0) return [];
     // Candidates via the inverted index LEFT JOINed to the row table — one

package/src/pg-executor-pglite.ts

@@ -8,9 +8,11 @@
  * `PgExecutor` interface (see the server README).
  *
  * pglite is single-connection, so `transaction` runs `BEGIN`/`COMMIT`/
- * `ROLLBACK` on the one connection and relies on the caller not interleaving
- * unrelated queries during a transaction scope (the storage layer holds one
- * transaction at a time per push).
+ * `ROLLBACK` on the one connection. Overlapping `transaction` calls are
+ * serialized through a promise chain (mirroring `SqliteServerStorage`'s
+ * begin() FIFO): a nested BEGIN on Postgres is a warning-level no-op, so
+ * interleaved scopes would silently collapse into one SQL transaction and
+ * break the push layer's serialization guarantee on this dev driver.
  */
 import type { PGlite } from '@electric-sql/pglite';
 import type { PgExecutor, PgQueryable, PgRow } from './pg-executor';
@@ -43,17 +45,30 @@ function queryable(db: PgliteLike): PgQueryable {
 export function pgliteExecutor(db: PGlite | PgliteLike): PgExecutor {
   const like = db as PgliteLike;
   const q = queryable(like);
+  // One BEGIN…COMMIT/ROLLBACK scope at a time on the single connection (see
+  // the file header).
+  let transactionTail: Promise<void> = Promise.resolve();
   return {
     query: q.query,
     async transaction<T>(fn: (client: PgQueryable) => Promise<T>): Promise<T> {
-      await like.exec('BEGIN');
+      const previous = transactionTail;
+      let release!: () => void;
+      transactionTail = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      await previous;
       try {
-        const result = await fn(q);
-        await like.exec('COMMIT');
-        return result;
-      } catch (error) {
-        await like.exec('ROLLBACK');
-        throw error;
+        await like.exec('BEGIN');
+        try {
+          const result = await fn(q);
+          await like.exec('COMMIT');
+          return result;
+        } catch (error) {
+          await like.exec('ROLLBACK');
+          throw error;
+        }
+      } finally {
+        release();
       }
     },
     async close() {

package/src/postgres-storage.ts

@@ -434,6 +434,27 @@ async function writeRowOn(
   }
 }
 
+async function getPushResultOn(
+  q: PgQueryable,
+  partition: string,
+  clientId: string,
+  clientCommitId: string,
+): Promise<StoredPushResult | undefined> {
+  const { rows } = await q.query<{ result: unknown }>(
+    'SELECT result FROM sync_push_results WHERE partition=$1 AND client_id=$2 AND client_commit_id=$3',
+    [partition, clientId, clientCommitId],
+  );
+  if (rows[0] === undefined) return undefined;
+  try {
+    return deserializePushResult(asJson(rows[0].result));
+  } catch {
+    throw syncError(
+      'sync.idempotency_cache_miss',
+      'persisted push result unreadable (§6.3)',
+    );
+  }
+}
+
 class PostgresTransaction implements StorageTransaction {
   #client: PgQueryable;
   #partition: string;
@@ -472,12 +493,25 @@ class PostgresTransaction implements StorageTransaction {
     );
   }
 
+  getPushResult(
+    clientId: string,
+    clientCommitId: string,
+  ): Promise<StoredPushResult | undefined> {
+    this.#assertOpen();
+    // Runs on this transaction's pinned client: the push layer's duplicate
+    // re-check happens while the partition lock is held, and a pool-level
+    // read there would wait for a second connection.
+    return getPushResultOn(
+      this.#client,
+      this.#partition,
+      clientId,
+      clientCommitId,
+    );
+  }
+
   async scanRows(query: RowScanQuery): Promise<StoredRow[]> {
     this.#assertOpen();
-    assertScopeIndexedScan(query);
-    const variables = Object.keys(query.scopeFilter).sort();
-    const firstVariable = variables[0];
-    if (firstVariable === undefined) return [];
+    const firstVariable = assertScopeIndexedScan(query);
     const firstValues = query.scopeFilter[firstVariable] ?? [];
     if (firstValues.length === 0) return [];
     const sql = scanRowPageSql(
@@ -791,6 +825,11 @@ export class PostgresServerStorage implements ServerStorage {
           );
           if (rows.length > 0) {
             existing.set(table.name, new Set(rows.map((r) => r.column_name)));
+            // Parity with the SQLite/D1 `origin === 'c'` filter: only
+            // free-standing indexes enter the rebuild set. Constraint-owned
+            // indexes (PRIMARY KEY, UNIQUE constraints) can only be removed
+            // through their constraint, so DROP INDEX on them would abort
+            // the migration transaction.
             const indexes = await client.query<{ index_name: string }>(
               `SELECT index_class.relname AS index_name
                  FROM pg_catalog.pg_class AS table_class
@@ -802,7 +841,12 @@ export class PostgresServerStorage implements ServerStorage {
                    ON index_class.oid = index_meta.indexrelid
                 WHERE namespace.nspname = current_schema()
                   AND table_class.relname = $1
-                  AND NOT index_meta.indisprimary`,
+                  AND NOT index_meta.indisprimary
+                  AND NOT EXISTS (
+                    SELECT 1
+                      FROM pg_catalog.pg_constraint AS owning_constraint
+                     WHERE owning_constraint.conindid = index_meta.indexrelid
+                  )`,
               [table.name],
             );
             existingIndexes.set(
@@ -948,24 +992,12 @@ export class PostgresServerStorage implements ServerStorage {
     return getRowOn(this.#exec, this.table(table), partition, rowId);
   }
 
-  async getPushResult(
+  getPushResult(
     partition: string,
     clientId: string,
     clientCommitId: string,
   ): Promise<StoredPushResult | undefined> {
-    const { rows } = await this.#exec.query<{ result: unknown }>(
-      'SELECT result FROM sync_push_results WHERE partition=$1 AND client_id=$2 AND client_commit_id=$3',
-      [partition, clientId, clientCommitId],
-    );
-    if (rows[0] === undefined) return undefined;
-    try {
-      return deserializePushResult(asJson(rows[0].result));
-    } catch {
-      throw syncError(
-        'sync.idempotency_cache_miss',
-        'persisted push result unreadable (§6.3)',
-      );
-    }
+    return getPushResultOn(this.#exec, partition, clientId, clientCommitId);
   }
 
   async readCommitWindow(
@@ -1054,10 +1086,7 @@ export class PostgresServerStorage implements ServerStorage {
   }
 
   async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
-    assertScopeIndexedScan(query);
-    const variables = Object.keys(query.scopeFilter).sort();
-    const firstVariable = variables[0];
-    if (firstVariable === undefined) return [];
+    const firstVariable = assertScopeIndexedScan(query);
     const firstValues = query.scopeFilter[firstVariable] ?? [];
     if (firstValues.length === 0) return [];
     // Candidates via the inverted index (ordered + LIMITed at the covering

package/src/push.ts

@@ -886,13 +886,21 @@ export async function processPushCommitWithTrace(
     await lockPartitionForPush();
     // The optimistic lookup above may have raced another delivery. Re-check
     // only after acquiring partition serialization and before any operation
-    // read, validation, merge, or staged write.
+    // read, validation, merge, or staged write. The re-check runs on the
+    // transaction's own connection when the backend provides one: a pooled
+    // Postgres client holding the partition lock would otherwise wait for a
+    // second pool slot and deadlock against pushes waiting on the lock. A
+    // racing duplicate's result commits before the lock releases, so the
+    // transaction-scoped read observes it.
     try {
-      const serializedPersisted = await storage.getPushResult(
-        partition,
-        clientId,
-        frame.clientCommitId,
-      );
+      const serializedPersisted =
+        tx.getPushResult !== undefined
+          ? await tx.getPushResult(clientId, frame.clientCommitId)
+          : await storage.getPushResult(
+              partition,
+              clientId,
+              frame.clientCommitId,
+            );
       if (serializedPersisted !== undefined) {
         await tx.rollback();
         return processedPushCommit(
@@ -1028,22 +1036,36 @@ export async function processPushCommitWithTrace(
           'storage transaction lost atomic push rejection finalization support',
         );
       }
-      await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-      const canonical = await storage.getPushResult(
-        partition,
-        clientId,
-        frame.clientCommitId,
-      );
-      if (canonical === undefined) {
-        throw new Error(
-          'push rejection finalization did not persist an outcome',
+      try {
+        await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
+        const canonical = await storage.getPushResult(
+          partition,
+          clientId,
+          frame.clientCommitId,
+        );
+        if (canonical === undefined) {
+          throw new Error(
+            'push rejection finalization did not persist an outcome',
+          );
+        }
+        return processedPushCommit(
+          frame.clientCommitId,
+          canonical,
+          canonical.cacheIdentity !== stored.cacheIdentity,
         );
+      } catch (finalizationError) {
+        // A failed finalization must still release the transaction: on
+        // SQLite an unreleased BEGIN wedges the storage's global begin()
+        // queue, on Postgres it leaks the pinned pool client. rollback() is
+        // a no-op when the finalization already committed.
+        try {
+          await tx.rollback();
+        } catch {
+          // Surface the finalization failure; a rollback failure would
+          // otherwise mask it.
+        }
+        throw finalizationError;
       }
-      return processedPushCommit(
-        frame.clientCommitId,
-        canonical,
-        canonical.cacheIdentity !== stored.cacheIdentity,
-      );
     }
     await tx.rollback();
     throw error;

package/src/relational-rows.ts

@@ -170,11 +170,45 @@ export function addColumnDdl(
   return out;
 }
 
+/**
+ * Ownership marker for server-created projection indexes. A version bump
+ * rebuilds declared indexes by dropping every index Syncular owns and
+ * re-creating the declared set; this prefix is what marks an index as
+ * Syncular-owned, so operator-added tuning indexes survive bumps. Portable
+ * identifier validation reserves the `sync_` prefix for the server storage
+ * namespace, which keeps user and operator index names out of it.
+ */
+export const SYNC_INDEX_PREFIX = 'sync_ix_';
+
+/** Deterministic FNV-1a 64-bit hash, hex-encoded. Dependency-free so it runs
+ * identically on every server runtime. */
+function fnv1a64Hex(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte);
+    hash = (hash * 0x100000001b3n) & 0xffffffffffffffffn;
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+/**
+ * Physical name of one declared index: the ownership prefix plus the
+ * declared name. When that would exceed the 63-byte Postgres identifier
+ * limit, the declared name is replaced by its FNV-1a hash so the physical
+ * name stays deterministic, unique, and within the limit.
+ */
+export function physicalIndexName(declaredName: string): string {
+  const prefixed = `${SYNC_INDEX_PREFIX}${declaredName}`;
+  if (new TextEncoder().encode(prefixed).length <= 63) return prefixed;
+  return `${SYNC_INDEX_PREFIX}${fnv1a64Hex(declaredName)}`;
+}
+
 /**
  * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes
- * (DESIGN "user indexes" — the same names/columns the client materializes;
- * cross-table index-name uniqueness is the user's schema concern, exactly
- * as it is client-side).
+ * (DESIGN "user indexes" — the same declared names/columns the client
+ * materializes; cross-table index-name uniqueness is the user's schema
+ * concern, exactly as it is client-side). Server-side the physical name
+ * carries the {@link SYNC_INDEX_PREFIX} ownership marker.
  */
 export function createIndexDdl(table: CompiledTable): string[] {
   // User indexes name app columns — nothing to index without the projection.
@@ -184,7 +218,7 @@ export function createIndexDdl(table: CompiledTable): string[] {
     const columns = index.columns
       .map((column) => quoteIdent(column))
       .join(', ');
-    return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(index.name)} ON ${quoteIdent(table.name)} (${columns})`;
+    return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(physicalIndexName(index.name))} ON ${quoteIdent(table.name)} (${columns})`;
   });
 }
 
@@ -678,6 +712,12 @@ export function rewritePlan(
  * missing columns, and rebuild declared secondary indexes. Rebuilding during
  * a version bump supports DROP INDEX and same-name index replacement without
  * requiring historical index definitions in the stored column-layout marker.
+ *
+ * The drop set is limited to Syncular-owned indexes: physical names carrying
+ * {@link SYNC_INDEX_PREFIX}, plus bare declared names (databases whose
+ * projection indexes predate the ownership prefix migrate onto the prefixed
+ * scheme through this rule). Operator-added tuning indexes keep their own
+ * names and survive every bump.
  */
 export function schemaDdl(
   schema: CompiledSchema,
@@ -685,18 +725,28 @@ export function schemaDdl(
   dialect: RelationalDialect,
   existingIndexesByTable: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string[] {
-  const out: string[] = [];
+  const drops: string[] = [];
+  const creates: string[] = [];
   for (const table of schema.tables.values()) {
     const existing = existingColumnsByTable.get(table.name);
     if (existing === undefined) {
-      out.push(createTableDdl(table, dialect));
+      creates.push(createTableDdl(table, dialect));
     } else {
+      const declared = new Set(table.indexes.map((index) => index.name));
       for (const indexName of existingIndexesByTable.get(table.name) ?? []) {
-        out.push(dropIndexDdl(indexName));
+        if (
+          indexName.startsWith(SYNC_INDEX_PREFIX) ||
+          declared.has(indexName)
+        ) {
+          drops.push(dropIndexDdl(indexName));
+        }
       }
-      out.push(...addColumnDdl(table, existing, dialect));
+      creates.push(...addColumnDdl(table, existing, dialect));
     }
-    out.push(...createIndexDdl(table));
+    creates.push(...createIndexDdl(table));
   }
-  return out;
+  // Every drop precedes every create: an index name moving between tables in
+  // one bump must release the global (SQLite) index namespace before the
+  // receiving table re-creates it.
+  return [...drops, ...creates];
 }

package/src/schema.ts

@@ -104,11 +104,8 @@ export interface CompiledSchema {
 const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
 
 /**
- * Identifier rules for relational server storage (DESIGN "current-row
- * tables"): app tables live in the same namespace as the sync
- * infrastructure tables (`sync_*`) and carry `_sync_*` meta columns, so
- * both prefixes are reserved; identifiers over 63 bytes would be silently
- * truncated by Postgres.
+ * Compile one `prefix:{variable}` scope pattern against the table's column
+ * list, resolving the scope column's positional index for row extraction.
  */
 function compilePattern(
   table: TableSchema,
@@ -145,6 +142,11 @@ export function compileSchema(schema: ServerSchema): CompiledSchema {
     if (tables.has(table.name)) {
       throw new Error(`duplicate table ${JSON.stringify(table.name)}`);
     }
+    // Identifier rules (DESIGN "current-row tables") live in core's
+    // validatePortableRelationalIdentifier, shared with typegen: app tables
+    // share a namespace with the sync infrastructure tables (`sync_*`) and
+    // carry `_sync_*` meta columns, so both prefixes are reserved, and
+    // Postgres silently truncates identifiers over 63 bytes.
     validatePortableRelationalIdentifier('table', table.name);
     const columnIndex = new Map<string, number>();
     table.columns.forEach((column, index) => {

package/src/sqlite-storage.ts

@@ -92,6 +92,20 @@ class SqliteTransaction implements StorageTransaction {
     return this.#storage.getRow(this.#partition, table, rowId);
   }
 
+  getPushResult(
+    clientId: string,
+    clientCommitId: string,
+  ): Promise<StoredPushResult | undefined> {
+    this.#assertOpen();
+    // One shared bun:sqlite connection — this read runs inside this
+    // transaction's BEGIN IMMEDIATE.
+    return this.#storage.getPushResult(
+      this.#partition,
+      clientId,
+      clientCommitId,
+    );
+  }
+
   scanRows(query: RowScanQuery): Promise<StoredRow[]> {
     this.#assertOpen();
     return this.#storage.scanRows(this.#partition, query);
@@ -244,10 +258,22 @@ class SqliteTransaction implements StorageTransaction {
 
   async commit(): Promise<void> {
     this.#assertOpen();
-    this.#open = false;
     try {
       this.#storage.db.exec('COMMIT');
+    } catch (error) {
+      // A failed COMMIT (SQLITE_BUSY from an external writer, I/O error)
+      // leaves the connection inside BEGIN IMMEDIATE. Roll back before the
+      // FIFO releases, so the next queued transaction starts on a clean
+      // connection.
+      try {
+        this.#storage.db.exec('ROLLBACK');
+      } catch {
+        // Surface the COMMIT failure; a rollback failure would otherwise
+        // mask it.
+      }
+      throw error;
     } finally {
+      this.#open = false;
       this.#release();
     }
   }
@@ -415,6 +441,10 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async begin(partition: string): Promise<StorageTransaction> {
+    // Deliberately global across partitions: SQLite is single-writer per
+    // database file, so one FIFO over the shared connection is the correct
+    // serialization unit — a per-partition queue would still contend on the
+    // same BEGIN IMMEDIATE writer lock.
     const previous = this.#transactionTail;
     let release!: () => void;
     this.#transactionTail = new Promise<void>((resolve) => {
@@ -593,10 +623,7 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
-    assertScopeIndexedScan(query);
-    const variables = Object.keys(query.scopeFilter).sort();
-    const firstVariable = variables[0];
-    if (firstVariable === undefined) return [];
+    const firstVariable = assertScopeIndexedScan(query);
     const firstValues = query.scopeFilter[firstVariable] ?? [];
     if (firstValues.length === 0) return [];
     // Candidates via the inverted index LEFT JOINed to the row table — one

package/src/storage-query.ts

@@ -3,18 +3,23 @@ import type { CompiledTable, IndexSchema } from './schema';
 import type { IndexRowScanQuery, RowScanQuery } from './storage';
 import { StorageQueryError } from './storage-errors';
 
-/** Fail loudly instead of making an unsupported unscoped scan look empty. */
-export function assertScopeIndexedScan(query: RowScanQuery): void {
+/**
+ * Fail loudly instead of making an unsupported unscoped scan look empty.
+ * Returns the first scope variable in sorted order — the one every adapter
+ * drives its inverted-index candidate selection with.
+ */
+export function assertScopeIndexedScan(query: RowScanQuery): string {
   const scopeFilter = (
     query as RowScanQuery & { readonly scopeFilter?: ScopeMap | null }
   ).scopeFilter;
-  if (
-    scopeFilter === undefined ||
-    scopeFilter === null ||
-    Object.keys(scopeFilter).length === 0
-  ) {
+  const firstVariable =
+    scopeFilter === undefined || scopeFilter === null
+      ? undefined
+      : Object.keys(scopeFilter).sort()[0];
+  if (firstVariable === undefined) {
     throw new StorageQueryError('sync.storage.scan_requires_scope');
   }
+  return firstVariable;
 }
 
 /** Validate and resolve one exact trusted-host relational index lookup. */

package/src/storage.ts

@@ -190,6 +190,20 @@ export interface ScopeActivityQuery {
  */
 export interface StorageTransaction {
   getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+  /**
+   * Optional transaction-scoped idempotency lookup (§2.3) with the same
+   * semantics as `ServerStorage.getPushResult`, including the
+   * `sync.idempotency_cache_miss` throw. The push layer prefers it for the
+   * post-serialization duplicate re-check so the read runs on the
+   * transaction's own connection — a pooled Postgres client that holds the
+   * partition lock must never wait for a second pool slot mid-push. In-tree
+   * SQLite/Postgres/D1 adapters implement it; a custom adapter that omits it
+   * keeps the pool-level read.
+   */
+  getPushResult?(
+    clientId: string,
+    clientCommitId: string,
+  ): Promise<StoredPushResult | undefined>;
   /**
    * Optional candidate-state scan used only by whole-commit validation.
    * In-tree SQLite/Postgres/D1 backends implement it with read-your-own-writes