@syncular/server 0.15.22 → 0.15.24

package/README.md

@@ -19,7 +19,7 @@ The supported set, and what deliberately does **not** get an adapter:
 | Runtime | Adapter | Transport | Storage | Status |
 | --- | --- | --- | --- | --- |
 | **Bun / Node** | `@syncular/server-hono` | HTTP (`POST /sync`, segments, blobs) **+ WS realtime** (§8, host-driven upgrade) | any: `SqliteServerStorage`, `PostgresServerStorage`, memory | **Supported now** — the reference deployment; runs the full conformance catalog on both bindings. |
-| **Cloudflare Workers** | `@syncular/server-workers` | HTTP binding via Hono (Workers-native) **+ WS realtime** (§8, Durable Object host with hibernation) | `D1ServerStorage` (D1); R2-as-S3 for segments/blobs (§5.4 delegated presign) | **Supported now** — this rung. Realtime rides a **Durable Object** (`SyncularRealtimeDO`), opt-in; HTTP-only is also fully conformant (below). |
+| **Cloudflare Workers** | `@syncular/server-workers` | HTTP binding via Hono (Workers-native) **+ optional WS realtime** (§8) | `D1ServerStorage` behind one per-partition Durable Object queue; R2-as-S3 for segments/blobs | **Supported now** — D1 sync writes always traverse the DO; WebSocket upgrades remain optional. |
 | Raw Deno / edge-misc | — | — | — | **Not adapted** (policy below). |
 
 **The policy for "not adapted".** Untested ≠ unsupported forever. The core
@@ -30,23 +30,20 @@ HTTP via the fetch-handler round-trip tests), and we do not claim runtimes we
 do not test. Deno is a plausible future adapter the day someone runs the
 catalog on it; until then it is neutral-core-friendly, not supported.
 
-**Workers realtime — the Durable Object.** SPEC §1.1's two bindings are two
-framings of one handler; an **HTTP-only deployment is fully conformant**
-(clients that cannot open the socket sync over `POST /sync`, identical
-semantics — a smaller complete deployment, not a degraded one), so realtime on
-Workers is opt-in. When enabled it rides a **Durable Object**
-(`SyncularRealtimeDO`): one DO per partition hosting the `RealtimeHub` (the DO
-id derived from the partition, so a partition's sockets and its commit fan-out
-are co-located and single-threaded — also the natural per-partition write
-serialization point the D1 storage wants); WebSocket **hibernation** so idle
-sockets don't bill wall time (the existing `RealtimeSession` is the
+**Workers coordination and realtime — the Durable Object.** HTTP-only is fully
+conformant at the protocol level, but D1 still requires a per-partition Durable
+Object queue for every `/sync` round that may push. WebSocket upgrades are
+optional; the write coordinator is not. `SyncularRealtimeDO` hosts that FIFO
+and, when realtime is enabled, the `RealtimeHub`. The DO id derives from the
+partition, so unrelated partitions remain concurrent. WebSocket
+**hibernation** keeps idle sockets from billing wall time (the existing
+`RealtimeSession` is the
 per-connection state machine, driven from the hibernation callbacks and
 rehydrated from a minimal socket attachment + the D1 client record on wake);
 storage via the same **D1** binding so realtime rounds and `POST /sync` rounds
 share one commit log and one segment store; commit fan-out (§8.2) runs in-DO
-(no LISTEN/NOTIFY needed — writes and sockets are co-located), and an HTTP push
-landing in a plain isolate wakes the partition's DO (the in-platform
-LISTEN/NOTIFY analogue). Full shape, wiring, hibernation semantics, and the
+(no LISTEN/NOTIFY needed — writes and sockets are co-located). Full shape,
+wiring, hibernation semantics, and the
 manual real-workerd smoke recipe in `@syncular/server-workers/README.md`.
 
 **No relay (decision).** There is deliberately no *relay* — no bridge that
@@ -162,17 +159,33 @@ re-checks idempotency after taking that lock and persists a rejected outcome
 while the lock is retained, so overlapping duplicate deliveries cannot rerun
 the callback.
 
-SQLite and PostgreSQL provide that serialization directly. D1 does not expose
-an interactive lock: `D1ServerStorage` fails closed unless it is constructed
-inside an external per-partition coordinator with
-`{ commitValidationSerialized: true }` (normally one Durable Object per
-partition). Do not set that assertion on a stateless Worker. Custom storages
-must implement both the transaction lock and candidate scan seam.
+SQLite and PostgreSQL provide that serialization directly for every push. D1
+does not expose an interactive lock: `D1ServerStorage` fails closed unless it
+is constructed inside an explicit per-partition coordinator with
+`{ pushApplySerialized: true }` (normally the packaged Durable Object FIFO).
+Do not set that assertion on a stateless Worker. Custom storages must implement
+the pre-operation partition lock, locked idempotency re-check, atomic rejection
+finalization, and—when `commitValidator` is used—candidate scans.
 
 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.
 
+## Seed idempotency and safe revisioning
+
+`seedMutations` uses the real push path and a stable `clientId`/`commitId`.
+Both applied and rejected outcomes are terminal for that key. A rejected call
+throws `SeedMutationError`, whose structured `code`, `opIndex`, `replayed`,
+`recordedAtMs`, and `cacheIdentity` fields distinguish a fresh policy failure
+from replay of an older cached rejection.
+
+After correcting a development seed definition, advance an explicit seed
+revision (`catalog-v1` to `catalog-v2`) and rerun it; do not delete the database
+or unrelated rows. This does not apply to application commands. After an
+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).
+
 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.d.ts

@@ -16,9 +16,15 @@ export interface D1Database {
 export interface D1ServerStorageOptions {
     /**
      * Assert that all writes for a partition reach this storage serially.
-     * Required for §6.8 because D1 exposes no interactive transaction lock.
-     * Set this only inside a per-partition Durable Object or equivalent
-     * coordinator; the default fails closed when a commit validator is used.
+     * Required for every push because D1 exposes no interactive transaction
+     * lock. Set this only inside an explicit per-partition request queue,
+     * Durable Object, or equivalent coordinator; the default fails closed.
+     */
+    readonly pushApplySerialized?: boolean;
+    /**
+     * @deprecated Use `pushApplySerialized`. This alias remains valid only
+     * because the old assertion already promised that every partition write,
+     * not merely validator callbacks, was externally serialized.
      */
     readonly commitValidationSerialized?: boolean;
 }

package/dist/d1-storage.js

@@ -32,11 +32,11 @@ var _a;
  * reading `max_commit_seq` live and buffering the `+1` write. Under a single
  * Worker request this is exact. Two concurrent pushes to one partition need an
  * external serialization point (normally a per-partition Durable Object); a
- * realtime notifier alone does not serialize HTTP writes. A stateless
- * HTTP-only deployment SHOULD front same-partition writes with a coordinating
- * primitive (a DO or a Queue). For §6.8 whole-commit validation this becomes
- * mandatory and fail-closed: the coordinator must explicitly set
- * `commitValidationSerialized`, because D1 cannot provide the required lock.
+ * realtime notifier alone does not serialize HTTP writes. Every deployment
+ * that accepts D1 pushes MUST front same-partition sync rounds with a
+ * coordinating primitive (a DO or a Queue). The adapter fails closed unless
+ * that coordinator explicitly sets `pushApplySerialized`, because D1 cannot
+ * provide the required pre-operation lock.
  * This mirrors PostgreSQL's per-partition row lock, achieved by placement
  * rather than a lock D1 does not expose.
  */
@@ -58,12 +58,12 @@ class D1Transaction {
     #db;
     #partition;
     #resolveTable;
-    #commitValidationSerialized;
+    #pushApplySerialized;
     #buffer = [];
     #open = true;
     /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
     #maxCommitSeq;
-    #commitValidationCheckpoint;
+    #pushApplyCheckpoint;
     #lastApplicationOpIndex;
     /**
      * Read-your-own-writes overlay (§6.2 needs `getRow` to see buffered writes
@@ -71,11 +71,11 @@ class D1Transaction {
      * `tbl\u0000rowId` → the pending state, consulted by `getRow` before D1.
      */
     #pending = new Map();
-    constructor(db, partition, resolveTable, commitValidationSerialized) {
+    constructor(db, partition, resolveTable, pushApplySerialized) {
         this.#db = db;
         this.#partition = partition;
         this.#resolveTable = resolveTable;
-        this.#commitValidationSerialized = commitValidationSerialized;
+        this.#pushApplySerialized = pushApplySerialized;
     }
     #assertOpen() {
         if (!this.#open)
@@ -188,20 +188,20 @@ class D1Transaction {
             .sort((left, right) => left.rowId.localeCompare(right.rowId))
             .slice(0, query.limit);
     }
-    async lockPartitionForCommitValidation() {
+    async lockPartitionForPush() {
         this.#assertOpen();
-        if (!this.#commitValidationSerialized) {
-            throw new Error('D1 whole-commit validation requires externally serialized partition writes');
+        if (!this.#pushApplySerialized) {
+            throw new Error('D1 push apply requires externally serialized partition writes');
         }
         // D1 has no interactive lock. The caller explicitly asserted that every
         // write for this partition is already serialized (normally by its DO).
-        this.#commitValidationCheckpoint = this.#buffer.length;
+        this.#pushApplyCheckpoint = this.#buffer.length;
     }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
-        const checkpoint = this.#commitValidationCheckpoint;
+        const checkpoint = this.#pushApplyCheckpoint;
         if (checkpoint === undefined) {
-            throw new Error('whole-commit rejection requires its validation checkpoint');
+            throw new Error('push rejection requires its apply checkpoint');
         }
         this.#buffer.length = checkpoint;
         this.#pending.clear();
@@ -352,16 +352,21 @@ class D1Transaction {
     }
     async commit() {
         this.#assertOpen();
-        this.#open = false;
-        if (this.#buffer.length === 0)
+        if (this.#buffer.length === 0) {
+            this.#open = false;
             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.
         try {
             await this.#db.batch(statements);
+            this.#open = false;
         }
         catch (error) {
             if (isD1ConstraintError(error)) {
+                // 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);
             }
             throw error;
@@ -382,14 +387,15 @@ _a = D1Transaction;
 const D1_MAX_BIND_PARAMS = 100;
 export class D1ServerStorage {
     #db;
-    #commitValidationSerialized;
+    #pushApplySerialized;
     /** Set by `ensureSchema`: app-table lookup for the relational row store. */
     #tables;
     #schemaVersion;
     constructor(db, options = {}) {
         this.#db = db;
-        this.#commitValidationSerialized =
-            options.commitValidationSerialized === true;
+        this.#pushApplySerialized =
+            options.pushApplySerialized === true ||
+                options.commitValidationSerialized === true;
     }
     /** Apply the schema DDL (idempotent). Call once before use. */
     async migrate() {
@@ -512,7 +518,7 @@ export class D1ServerStorage {
         }
     }
     async begin(partition) {
-        return new D1Transaction(this.#db, partition, (name) => this.table(name), this.#commitValidationSerialized);
+        return new D1Transaction(this.#db, partition, (name) => this.table(name), this.#pushApplySerialized);
     }
     async getMaxCommitSeq(partition) {
         const row = await this.#db

package/dist/events.d.ts

@@ -59,11 +59,21 @@ export interface PushRejectedEvent extends PushEventBase {
     readonly type: 'push.rejected';
     readonly code: string;
     readonly opIndex: number;
+    /** True when the rejection was replayed from the idempotency cache. */
+    readonly replay: boolean;
+    /** Original host time for outcomes recorded by a metadata-aware server. */
+    readonly recordedAtMs?: number;
+    /** Privacy-safe identity of the stored outcome, when available. */
+    readonly cacheIdentity?: string;
 }
 /** A push commit terminated by a version conflict (§6.2). */
 export interface PushConflictedEvent extends PushEventBase {
     readonly type: 'push.conflicted';
     readonly opIndex: number;
+    /** True when the conflict was replayed from the idempotency cache. */
+    readonly replay: boolean;
+    readonly recordedAtMs?: number;
+    readonly cacheIdentity?: string;
 }
 /** One emitted segment within a pull subscription section. */
 export interface PullSegmentSummary {

package/dist/handler.js

@@ -15,7 +15,7 @@ import { SyncError, syncError } from './errors.js';
 import { emitEvent, } from './events.js';
 import { END_FRAME_BYTES, encodeResponseFrame, RESPONSE_ENVELOPE_HEADER, } from './frame-bytes.js';
 import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, clampPullLimits, subscriptionSection, } from './pull.js';
-import { processPushCommit } from './push.js';
+import { processPushCommitWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { computeEffective } from './scopes.js';
 function validateResolvedKeys(allowed, schema) {
@@ -199,7 +199,8 @@ function pushResultDetailsFrame(frame) {
             entries,
         };
 }
-function emitPushEvent(events, ctx, clientId, push, frame) {
+function emitPushEvent(events, ctx, clientId, push, processed) {
+    const { frame } = processed;
     const base = {
         atMs: clockOf(ctx)(),
         partition: ctx.partition,
@@ -213,7 +214,7 @@ function emitPushEvent(events, ctx, clientId, push, frame) {
             type: 'push.applied',
             ...base,
             ...(frame.commitSeq !== undefined ? { commitSeq: frame.commitSeq } : {}),
-            replay: frame.status === 'cached',
+            replay: processed.replayed,
         });
         return;
     }
@@ -224,6 +225,13 @@ function emitPushEvent(events, ctx, clientId, push, frame) {
             type: 'push.conflicted',
             ...base,
             opIndex: record.opIndex,
+            replay: processed.replayed,
+            ...(processed.recordedAtMs !== undefined
+                ? { recordedAtMs: processed.recordedAtMs }
+                : {}),
+            ...(processed.cacheIdentity !== undefined
+                ? { cacheIdentity: processed.cacheIdentity }
+                : {}),
         });
         return;
     }
@@ -234,6 +242,13 @@ function emitPushEvent(events, ctx, clientId, push, frame) {
             ? record.code
             : 'sync.invalid_request',
         opIndex: record?.opIndex ?? 0,
+        replay: processed.replayed,
+        ...(processed.recordedAtMs !== undefined
+            ? { recordedAtMs: processed.recordedAtMs }
+            : {}),
+        ...(processed.cacheIdentity !== undefined
+            ? { cacheIdentity: processed.cacheIdentity }
+            : {}),
     });
 }
 async function* streamResponse(plan, ctx, schema, report) {
@@ -276,9 +291,10 @@ async function* streamResponse(plan, ctx, schema, report) {
     try {
         // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
         for (const push of plan.pushes) {
-            const frame = await processPushCommit(ctx, schema, plan.resolved, plan.header.clientId, push);
+            const processed = await processPushCommitWithTrace(ctx, schema, plan.resolved, plan.header.clientId, push);
+            const { frame } = processed;
             if (events !== undefined) {
-                emitPushEvent(events, ctx, plan.header.clientId, push, frame);
+                emitPushEvent(events, ctx, plan.header.clientId, push, processed);
             }
             yield encodeResponseFrame(frame);
             const details = pushResultDetailsFrame(frame);

package/dist/postgres-storage.js

@@ -91,6 +91,12 @@ function serializePushResult(result) {
     return {
         status: result.status,
         ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
+        ...(result.recordedAtMs !== undefined
+            ? { recordedAtMs: result.recordedAtMs }
+            : {}),
+        ...(result.cacheIdentity !== undefined
+            ? { cacheIdentity: result.cacheIdentity }
+            : {}),
         results: result.results.map((record) => {
             if (record.status === 'conflict') {
                 return {
@@ -144,6 +150,12 @@ function deserializePushResult(value) {
     return {
         status: parsed.status,
         ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+        ...(parsed.recordedAtMs !== undefined
+            ? { recordedAtMs: parsed.recordedAtMs }
+            : {}),
+        ...(parsed.cacheIdentity !== undefined
+            ? { cacheIdentity: parsed.cacheIdentity }
+            : {}),
         results,
     };
 }
@@ -233,7 +245,7 @@ class PostgresTransaction {
     #partition;
     #resolveTable;
     #open = true;
-    #commitValidationSavepoint = false;
+    #pushApplySavepoint = false;
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
@@ -297,22 +309,22 @@ class PostgresTransaction {
         this.#assertOpen();
         return scanRowsByIndexOn(this.#client, this.#resolveTable(query.table), this.#partition, query);
     }
-    async lockPartitionForCommitValidation() {
+    async lockPartitionForPush() {
         this.#assertOpen();
         await this.#client.query(`INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
        ON CONFLICT (partition) DO NOTHING`, [this.#partition]);
         await this.#client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [this.#partition]);
-        await this.#client.query('SAVEPOINT syncular_commit_validation_candidate');
-        this.#commitValidationSavepoint = true;
+        await this.#client.query('SAVEPOINT syncular_push_candidate');
+        this.#pushApplySavepoint = true;
     }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
-        if (!this.#commitValidationSavepoint) {
-            throw new Error('whole-commit rejection requires its validation savepoint');
+        if (!this.#pushApplySavepoint) {
+            throw new Error('push rejection requires its apply savepoint');
         }
-        await this.#client.query('ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate');
-        await this.#client.query('RELEASE SAVEPOINT syncular_commit_validation_candidate');
-        this.#commitValidationSavepoint = false;
+        await this.#client.query('ROLLBACK TO SAVEPOINT syncular_push_candidate');
+        await this.#client.query('RELEASE SAVEPOINT syncular_push_candidate');
+        this.#pushApplySavepoint = false;
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
     }

package/dist/push.d.ts

@@ -22,6 +22,13 @@ import type { SyncRequestContext } from './context.js';
 import type { CompiledSchema } from './schema.js';
 import type { ResolvedScopes } from './scopes.js';
 import type { StoredCommit } from './storage.js';
+export interface ProcessedPushCommit {
+    readonly frame: PushResultFrame;
+    /** True when this request observed an already-recorded idempotency outcome. */
+    readonly replayed: boolean;
+    readonly recordedAtMs?: number;
+    readonly cacheIdentity?: string;
+}
 export interface AppliedCommitEvent {
     readonly commit: StoredCommit;
 }
@@ -30,3 +37,9 @@ export interface AppliedCommitEvent {
  * atomic apply (§6.4), realtime notification for applied commits.
  */
 export declare function processPushCommit(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<PushResultFrame>;
+/**
+ * Host-observable variant of `processPushCommit`. The SSP2 wire frame keeps
+ * rejected replays as `status: rejected`; this companion result preserves the
+ * cache provenance needed by structured events and server helpers.
+ */
+export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<ProcessedPushCommit>;

package/dist/push.js

@@ -466,6 +466,25 @@ function resultFrame(clientCommitId, stored, replay) {
         results: [...stored.results],
     };
 }
+function processedPushCommit(clientCommitId, stored, replayed) {
+    return {
+        frame: resultFrame(clientCommitId, stored, replayed),
+        replayed,
+        ...(stored.recordedAtMs !== undefined
+            ? { recordedAtMs: stored.recordedAtMs }
+            : {}),
+        ...(stored.cacheIdentity !== undefined
+            ? { cacheIdentity: stored.cacheIdentity }
+            : {}),
+    };
+}
+function newStoredPushResult(recordedAtMs, result) {
+    return {
+        ...result,
+        recordedAtMs,
+        cacheIdentity: crypto.randomUUID(),
+    };
+}
 function idempotencyCacheMissFrame(clientCommitId, error) {
     return {
         type: 'PUSH_RESULT',
@@ -482,27 +501,19 @@ 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.
  */
 export async function processPushCommit(ctx, schema, resolved, clientId, frame) {
+    return (await processPushCommitWithTrace(ctx, schema, resolved, clientId, frame)).frame;
+}
+/**
+ * Host-observable variant of `processPushCommit`. The SSP2 wire frame keeps
+ * rejected replays as `status: rejected`; this companion result preserves the
+ * cache provenance needed by structured events and server helpers.
+ */
+export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame) {
     const { storage, partition } = ctx;
     let persisted;
     try {
@@ -513,12 +524,15 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             error.code === 'sync.idempotency_cache_miss') {
             // §6.3: answer the retryable cache-miss for this commit rather than
             // re-applying. Not persisted — a retry may find a readable record.
-            return idempotencyCacheMissFrame(frame.clientCommitId, error);
+            return {
+                frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                replayed: false,
+            };
         }
         throw error;
     }
     if (persisted !== undefined) {
-        return resultFrame(frame.clientCommitId, persisted, true);
+        return processedPushCommit(frame.clientCommitId, persisted, true);
     }
     const createdAtMs = clockOf(ctx)();
     const blobCtx = { store: ctx.blobs, partition };
@@ -526,32 +540,35 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
     const validators = ctx.validators;
     const commitValidator = ctx.commitValidator;
     const tx = await storage.begin(partition);
+    const lockPartitionForPush = tx.lockPartitionForPush?.bind(tx) ??
+        tx.lockPartitionForCommitValidation?.bind(tx);
     const commitRejectedPushResult = tx.commitRejectedPushResult?.bind(tx);
     try {
-        if (commitValidator !== undefined) {
-            if (tx.lockPartitionForCommitValidation === undefined ||
-                commitRejectedPushResult === undefined) {
-                throw new Error('storage transaction does not support atomic whole-commit validation finalization');
-            }
-            await tx.lockPartitionForCommitValidation();
-            // The optimistic lookup above may have raced another request for the
-            // same idempotency key. Re-check after acquiring partition serialization
-            // so a concurrent duplicate never reruns the aggregate validator.
-            try {
-                const serializedPersisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
-                if (serializedPersisted !== undefined) {
-                    await tx.rollback();
-                    return resultFrame(frame.clientCommitId, serializedPersisted, true);
-                }
+        if (lockPartitionForPush === undefined ||
+            commitRejectedPushResult === undefined) {
+            throw new Error('storage transaction does not support serialized push apply and atomic rejection finalization');
+        }
+        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.
+        try {
+            const serializedPersisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+            if (serializedPersisted !== undefined) {
+                await tx.rollback();
+                return processedPushCommit(frame.clientCommitId, serializedPersisted, true);
             }
-            catch (error) {
-                if (error instanceof SyncError &&
-                    error.code === 'sync.idempotency_cache_miss') {
-                    await tx.rollback();
-                    return idempotencyCacheMissFrame(frame.clientCommitId, error);
-                }
-                throw error;
+        }
+        catch (error) {
+            if (error instanceof SyncError &&
+                error.code === 'sync.idempotency_cache_miss') {
+                await tx.rollback();
+                return {
+                    frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                    replayed: false,
+                };
             }
+            throw error;
         }
         const results = [];
         const changes = [];
@@ -580,25 +597,18 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
         if (terminated !== undefined) {
             // §6.3 rejected: only the terminating operation's record; §6.4:
             // every write of the commit rolls back.
-            const stored = {
+            const stored = newStoredPushResult(createdAtMs, {
                 status: 'rejected',
                 results: [terminated],
-            };
-            if (commitValidator !== undefined) {
-                // Discard candidate rows and persist the rejection while retaining the
-                // same partition lock. This closes the duplicate-request race between
-                // rollback and the durable idempotency outcome.
-                if (commitRejectedPushResult === undefined) {
-                    throw new Error('storage transaction lost whole-commit rejection finalization support');
-                }
-                await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-            }
-            else {
-                await tx.rollback();
-                const canonical = await persistRejectedPushResult(storage, partition, clientId, frame.clientCommitId, stored);
-                return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+            });
+            // Discard candidates and persist the rejection while retaining the same
+            // partition lock. There is no unlock gap in which a duplicate can rerun.
+            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 resultFrame(frame.clientCommitId, stored, false);
+            return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
         }
         const commitSeq = await tx.appendCommit({
             clientId,
@@ -607,7 +617,11 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             createdAtMs,
             changes,
         });
-        const stored = { status: 'applied', commitSeq, results };
+        const stored = newStoredPushResult(createdAtMs, {
+            status: 'applied',
+            commitSeq,
+            results,
+        });
         await tx.putPushResult(clientId, frame.clientCommitId, stored);
         await tx.commit();
         if (ctx.realtime !== undefined && changes.length > 0) {
@@ -618,12 +632,11 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
                 changes,
             });
         }
-        return resultFrame(frame.clientCommitId, stored, false);
+        return processedPushCommit(frame.clientCommitId, stored, false);
     }
     catch (error) {
-        await tx.rollback();
         if (error instanceof StorageConstraintError) {
-            const stored = {
+            const stored = newStoredPushResult(createdAtMs, {
                 status: 'rejected',
                 results: [
                     {
@@ -634,10 +647,19 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
                         retryable: false,
                     },
                 ],
-            };
-            const canonical = await persistRejectedPushResult(storage, partition, clientId, frame.clientCommitId, stored);
-            return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+            });
+            if (commitRejectedPushResult === undefined) {
+                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');
+            }
+            return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
         }
+        await tx.rollback();
         throw error;
     }
 }