@syncular/server 0.15.22 → 0.15.24

package/dist/realtime.d.ts

@@ -14,38 +14,16 @@
  * the `sync` wake-up (§8.3).
  */
 import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
-import type { LeaseConfig, ResolveScopes, ServerLimits, SyncRequestContext } from './context.js';
+import type { SyncRequestContext, SyncServerConfig } from './context.js';
 import { type SyncularServerEvents } from './events.js';
-import type { ServerSchema } from './schema.js';
-import type { SegmentStore } from './segment-store.js';
-import type { SegmentUrlConfig } from './signed-url.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
-import type { CommitValidator, ValidatorRegistry } from './validate.js';
-export interface RealtimeHubConfig {
-    readonly schema: ServerSchema;
-    readonly storage: ServerStorage;
-    readonly resolveScopes: ResolveScopes;
-    /** §6.7 validators used by sync rounds carried over this socket. */
-    readonly validators?: ValidatorRegistry;
-    /** §6.8 whole-commit validator shared with HTTP sync rounds. */
-    readonly commitValidator?: CommitValidator;
-    readonly clock?: () => number;
+/**
+ * Realtime adds fanout/presence tuning to the canonical sync-server config;
+ * socket rounds must never have a narrower push/pull capability set than HTTP.
+ */
+export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
     /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
     readonly maxDeltaBytes?: number;
-    /** Optional structured-events sink (`realtime.*` events). */
-    readonly events?: SyncularServerEvents;
-    /**
-     * Segment store for sync rounds over the socket (§8.7). Without it a
-     * socket round fails loudly with an in-band ERROR — provide the same
-     * store the HTTP binding uses (one handler, two framings).
-     */
-    readonly segments?: SegmentStore;
-    /** Request limits for socket rounds; defaults match the HTTP binding. */
-    readonly limits?: Partial<ServerLimits>;
-    readonly signedUrls?: SegmentUrlConfig;
-    /** §7.3 auth leases for socket sync rounds (§8.7) — same config the
-     * HTTP binding uses, so rounds over the socket are lease-aware too. */
-    readonly leases?: LeaseConfig;
     /**
      * §8.6 presence: cap on the serialized size (bytes) of a published
      * presence document. An over-cap publish is rejected loudly to the
@@ -149,9 +127,11 @@ export declare class RealtimeSession {
      * round's request byte stream (§8.7). Synchronous entry — assembly and
      * violation detection happen inline so a pipelined chunk arriving
      * while a response streams is caught deterministically; the round
-     * itself runs async once the request is complete.
+     * itself runs async once the request is complete. The returned promise, when
+     * present, resolves only after response streaming and registration refresh;
+     * coordinated hosts await it to retain their partition FIFO through commit.
      */
-    handleBinary(bytes: Uint8Array): void;
+    handleBinary(bytes: Uint8Array): Promise<void> | undefined;
     sendHeartbeat(): void;
     sendWake(reason: WakeReason): void;
     /** Called by the hub for every applied commit, in commitSeq order. */
@@ -186,6 +166,10 @@ export declare class RealtimeHub {
      * the same shape the HTTP adapter builds, so the round drives the
      * SAME handler with zero semantic divergence.
      */
+    requestContextFor(identity: {
+        readonly partition: string;
+        readonly actorId: string;
+    }): SyncRequestContext;
     requestContext(session: RealtimeSession): SyncRequestContext;
     /**
      * Register a connected socket (§8.1): load the client's last pull's

package/dist/realtime.js

@@ -327,7 +327,9 @@ export class RealtimeSession {
      * round's request byte stream (§8.7). Synchronous entry — assembly and
      * violation detection happen inline so a pipelined chunk arriving
      * while a response streams is caught deterministically; the round
-     * itself runs async once the request is complete.
+     * itself runs async once the request is complete. The returned promise, when
+     * present, resolves only after response streaming and registration refresh;
+     * coordinated hosts await it to retain their partition FIFO through commit.
      */
     handleBinary(bytes) {
         if (bytes.length === 0)
@@ -365,7 +367,7 @@ export class RealtimeSession {
         }
         const token = Symbol('round');
         this.#activeRound = token;
-        void this.#runRound(done.message.slice(), token);
+        return this.#runRound(done.message.slice(), token);
     }
     /** Drive the shared handler and stream the response back (§8.7). */
     async #runRound(requestBytes, token) {
@@ -702,7 +704,7 @@ export class RealtimeHub {
      * the same shape the HTTP adapter builds, so the round drives the
      * SAME handler with zero semantic divergence.
      */
-    requestContext(session) {
+    requestContextFor(identity) {
         const segments = this.#config.segments;
         if (segments === undefined) {
             // Fail loud (§8.7): a hub serving socket rounds needs the same
@@ -710,12 +712,21 @@ export class RealtimeHub {
             throw syncError('sync.invalid_request', 'socket sync rounds require a segment store on the realtime hub (§8.7)');
         }
         return {
-            partition: session.partition,
-            actorId: session.actorId,
+            partition: identity.partition,
+            actorId: identity.actorId,
             schema: this.#config.schema,
             storage: this.#config.storage,
             segments,
             resolveScopes: this.#config.resolveScopes,
+            ...(this.#config.blobs !== undefined
+                ? { blobs: this.#config.blobs }
+                : {}),
+            ...(this.#config.maxBlobBytes !== undefined
+                ? { maxBlobBytes: this.#config.maxBlobBytes }
+                : {}),
+            ...(this.#config.crdtMergers !== undefined
+                ? { crdtMergers: this.#config.crdtMergers }
+                : {}),
             ...(this.#config.validators !== undefined
                 ? { validators: this.#config.validators }
                 : {}),
@@ -731,6 +742,15 @@ export class RealtimeHub {
             ...(this.#config.signedUrls !== undefined
                 ? { signedUrls: this.#config.signedUrls }
                 : {}),
+            ...(this.#config.blobSignedUrls !== undefined
+                ? { blobSignedUrls: this.#config.blobSignedUrls }
+                : {}),
+            ...(this.#config.blobUploadUrls !== undefined
+                ? { blobUploadUrls: this.#config.blobUploadUrls }
+                : {}),
+            ...(this.#config.sqliteImageBuilder !== undefined
+                ? { sqliteImageBuilder: this.#config.sqliteImageBuilder }
+                : {}),
             ...(this.#config.leases !== undefined
                 ? { leases: this.#config.leases }
                 : {}),
@@ -740,6 +760,9 @@ export class RealtimeHub {
             realtime: this,
         };
     }
+    requestContext(session) {
+        return this.requestContextFor(session);
+    }
     /**
      * Register a connected socket (§8.1): load the client's last pull's
      * subscription list, resolve + intersect scopes, send `hello`.

package/dist/seed.d.ts

@@ -26,9 +26,34 @@ export interface SeedTarget {
     /** The client commit id (default `'seed-commit-1'`). */
     readonly commitId?: string;
 }
+export interface SeedMutationErrorOptions {
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly opIndex: number;
+    readonly code: string;
+    readonly replayed: boolean;
+    readonly retryable: boolean;
+    readonly message: string;
+    readonly recordedAtMs?: number;
+    readonly cacheIdentity?: string;
+}
+/** Structured terminal failure from the real push path used by a seed. */
+export declare class SeedMutationError extends Error {
+    readonly name = "SeedMutationError";
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly opIndex: number;
+    /** Exact protocol or host-validator rejection code. */
+    readonly code: string;
+    readonly replayed: boolean;
+    readonly retryable: boolean;
+    readonly recordedAtMs?: number;
+    readonly cacheIdentity?: string;
+    constructor(options: SeedMutationErrorOptions);
+}
 /**
  * Seed `mutations` into a partition through the real push path. Throws a
- * `SyncError` when the push is rejected or any operation fails, so a broken
- * seed fails loud at boot instead of silently serving an empty database.
+ * `SeedMutationError` when the push is rejected and `SyncError` for malformed
+ * helper input, so a broken seed fails loud instead of serving an empty store.
  */
 export declare function seedMutations(config: SyncServerConfig, target: SeedTarget, mutations: readonly SeedMutation[]): Promise<void>;

package/dist/seed.js

@@ -11,7 +11,36 @@
  */
 import { decodeMessage, encodeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
 import { SyncError } from './errors.js';
+import { composeEvents } from './events-ring.js';
 import { handleSyncRequest } from './handler.js';
+/** Structured terminal failure from the real push path used by a seed. */
+export class SeedMutationError extends Error {
+    name = 'SeedMutationError';
+    clientId;
+    clientCommitId;
+    opIndex;
+    /** Exact protocol or host-validator rejection code. */
+    code;
+    replayed;
+    retryable;
+    recordedAtMs;
+    cacheIdentity;
+    constructor(options) {
+        super(options.message);
+        this.clientId = options.clientId;
+        this.clientCommitId = options.clientCommitId;
+        this.opIndex = options.opIndex;
+        this.code = options.code;
+        this.replayed = options.replayed;
+        this.retryable = options.retryable;
+        if (options.recordedAtMs !== undefined) {
+            this.recordedAtMs = options.recordedAtMs;
+        }
+        if (options.cacheIdentity !== undefined) {
+            this.cacheIdentity = options.cacheIdentity;
+        }
+    }
+}
 const MAPPABLE_RE = /^_*[A-Za-z][A-Za-z0-9_]*$/;
 /** Pinned §12 schema alias used by generated row types and every client host. */
 function snakeToCamel(name) {
@@ -35,8 +64,8 @@ function snakeToCamel(name) {
 }
 /**
  * Seed `mutations` into a partition through the real push path. Throws a
- * `SyncError` when the push is rejected or any operation fails, so a broken
- * seed fails loud at boot instead of silently serving an empty database.
+ * `SeedMutationError` when the push is rejected and `SyncError` for malformed
+ * helper input, so a broken seed fails loud instead of serving an empty store.
  */
 export async function seedMutations(config, target, mutations) {
     const clientId = target.clientId ?? 'seed';
@@ -88,11 +117,28 @@ export async function seedMutations(config, target, mutations) {
             accept: 0b0011,
         },
     ];
+    let terminalEvent;
+    const capture = {
+        emit(event) {
+            if ((event.type === 'push.rejected' || event.type === 'push.conflicted') &&
+                event.clientId === clientId &&
+                event.clientCommitId === clientCommitId) {
+                terminalEvent = event;
+            }
+        },
+    };
     const response = await handleSyncRequest(encodeMessage({
         wireVersion: PROTOCOL_WIRE_VERSION,
         msgKind: 'request',
         frames,
-    }), { ...config, partition: target.partition, actorId: target.actorId });
+    }), {
+        ...config,
+        partition: target.partition,
+        actorId: target.actorId,
+        events: config.events === undefined
+            ? capture
+            : composeEvents(config.events, capture),
+    });
     // Fail loud: surface the first rejected/failed operation.
     const message = decodeMessage(response);
     const result = message.frames.find((frame) => frame.type === 'PUSH_RESULT' && frame.clientCommitId === clientCommitId);
@@ -101,9 +147,27 @@ export async function seedMutations(config, target, mutations) {
     }
     if (result.status === 'rejected') {
         const failed = result.results.find((r) => r.status !== 'applied');
-        const detail = failed !== undefined && 'code' in failed
-            ? ` (op ${failed.opIndex}: ${failed.code} — ${failed.message})`
-            : '';
-        throw new SyncError('sync.invalid_request', `seedMutations: the seed commit was rejected${detail}`);
+        const code = failed?.code ?? 'sync.invalid_request';
+        const opIndex = failed?.opIndex ?? 0;
+        const retryable = failed?.status === 'error' ? failed.retryable : false;
+        const detail = failed === undefined
+            ? ''
+            : ` (op ${opIndex}: ${code} — ${failed.message})`;
+        const replayed = terminalEvent?.replay ?? false;
+        throw new SeedMutationError({
+            clientId,
+            clientCommitId,
+            opIndex,
+            code,
+            replayed,
+            retryable,
+            message: `seedMutations: the seed commit was rejected${replayed ? ' (cached replay)' : ''}${detail}`,
+            ...(terminalEvent?.recordedAtMs !== undefined
+                ? { recordedAtMs: terminalEvent.recordedAtMs }
+                : {}),
+            ...(terminalEvent?.cacheIdentity !== undefined
+                ? { cacheIdentity: terminalEvent.cacheIdentity }
+                : {}),
+        });
     }
 }

package/dist/sqlite-dialect.js

@@ -93,6 +93,12 @@ export function serializePushResult(result) {
     return JSON.stringify({
         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 {
@@ -146,6 +152,12 @@ export function deserializePushResult(text) {
     return {
         status: parsed.status,
         ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+        ...(parsed.recordedAtMs !== undefined
+            ? { recordedAtMs: parsed.recordedAtMs }
+            : {}),
+        ...(parsed.cacheIdentity !== undefined
+            ? { cacheIdentity: parsed.cacheIdentity }
+            : {}),
         results,
     };
 }

package/dist/sqlite-storage.js

@@ -17,10 +17,12 @@ class SqliteTransaction {
     #storage;
     #partition;
     #open = true;
-    #commitValidationSavepoint = false;
-    constructor(storage, partition) {
+    #pushApplySavepoint = false;
+    #release;
+    constructor(storage, partition, release) {
         this.#storage = storage;
         this.#partition = partition;
+        this.#release = release;
         storage.db.exec('BEGIN IMMEDIATE');
     }
     #assertOpen() {
@@ -39,20 +41,20 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.scanRowsByIndex(this.#partition, query);
     }
-    async lockPartitionForCommitValidation() {
+    async lockPartitionForPush() {
         this.#assertOpen();
         // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
-        this.#storage.db.exec('SAVEPOINT syncular_commit_validation_candidate');
-        this.#commitValidationSavepoint = true;
+        this.#storage.db.exec('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');
         }
-        this.#storage.db.exec('ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate');
-        this.#storage.db.exec('RELEASE SAVEPOINT syncular_commit_validation_candidate');
-        this.#commitValidationSavepoint = false;
+        this.#storage.db.exec('ROLLBACK TO SAVEPOINT syncular_push_candidate');
+        this.#storage.db.exec('RELEASE SAVEPOINT syncular_push_candidate');
+        this.#pushApplySavepoint = false;
         await this.putPushResult(clientId, clientCommitId, result);
         await this.commit();
     }
@@ -113,17 +115,29 @@ class SqliteTransaction {
     async commit() {
         this.#assertOpen();
         this.#open = false;
-        this.#storage.db.exec('COMMIT');
+        try {
+            this.#storage.db.exec('COMMIT');
+        }
+        finally {
+            this.#release();
+        }
     }
     async rollback() {
         if (!this.#open)
             return;
         this.#open = false;
-        this.#storage.db.exec('ROLLBACK');
+        try {
+            this.#storage.db.exec('ROLLBACK');
+        }
+        finally {
+            this.#release();
+        }
     }
 }
 export class SqliteServerStorage {
     db;
+    /** One bun:sqlite connection can own only one transaction at a time. */
+    #transactionTail = Promise.resolve();
     /** Set by `ensureSchema`: app-table lookup for the relational row store. */
     #tables;
     #schemaVersion;
@@ -237,7 +251,19 @@ export class SqliteServerStorage {
         }
     }
     async begin(partition) {
-        return new SqliteTransaction(this, partition);
+        const previous = this.#transactionTail;
+        let release;
+        this.#transactionTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return new SqliteTransaction(this, partition, release);
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
     }
     /** Internal: write a row + refresh its scope-index entries. */
     writeRow(partition, table, row) {

package/dist/storage.d.ts

@@ -64,6 +64,10 @@ export interface StoredPushResult {
     readonly status: 'applied' | 'rejected';
     /** Present iff `status` is `applied`. */
     readonly commitSeq?: number;
+    /** Host clock when this terminal idempotency outcome was first recorded. */
+    readonly recordedAtMs?: number;
+    /** Privacy-safe identity used to distinguish this stored outcome from a race. */
+    readonly cacheIdentity?: string;
     readonly results: readonly PushOperationResult[];
 }
 export interface ClientSubscription {
@@ -182,15 +186,23 @@ export interface StorageTransaction {
      */
     scanRowsByIndex?(query: IndexRowScanQuery): Promise<StoredRow[]>;
     /**
-     * Serialize candidate-state validation for this partition before any row
-     * read/write. Required at runtime when `commitValidator` is configured.
+     * Serialize every push apply for this partition before any operation read,
+     * validation, merge, or write. The push layer re-checks idempotency only
+     * after this resolves and retains the lock through terminal-result commit.
+     * Missing support fails closed before an app-row mutation.
+     */
+    lockPartitionForPush?(): Promise<void>;
+    /**
+     * @deprecated Implement `lockPartitionForPush`. Kept as a compatibility
+     * bridge for custom adapters whose existing implementation already locks
+     * the complete partition from before candidate reads through commit.
      */
     lockPartitionForCommitValidation?(): Promise<void>;
     /**
-     * §6.8 rejection finalization while the validation serialization lock is
-     * still held: discard every candidate write, persist the rejected
-     * idempotency result, and finish the transaction atomically. Required when
-     * `commitValidator` is configured so a concurrent duplicate cannot rerun it.
+     * Rejection finalization while the push-apply serialization lock is still
+     * held: discard every candidate write, persist the rejected idempotency
+     * result, and finish the transaction atomically. Required for every push so
+     * a concurrent duplicate cannot rerun operations, validators, or merges.
      */
     commitRejectedPushResult?(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
     upsertRow(table: string, row: StoredRow, context?: {

package/package.json

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

package/src/d1-storage.ts

@@ -31,11 +31,11 @@
  * 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.
  */
@@ -143,12 +143,12 @@ class D1Transaction implements StorageTransaction {
   readonly #db: D1Database;
   readonly #partition: string;
   readonly #resolveTable: (name: string) => CompiledTable;
-  readonly #commitValidationSerialized: boolean;
+  readonly #pushApplySerialized: boolean;
   readonly #buffer: BufferedStatement[] = [];
   #open = true;
   /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
   #maxCommitSeq: number | undefined;
-  #commitValidationCheckpoint: number | undefined;
+  #pushApplyCheckpoint: number | undefined;
   #lastApplicationOpIndex: number | undefined;
   /**
    * Read-your-own-writes overlay (§6.2 needs `getRow` to see buffered writes
@@ -161,12 +161,12 @@ class D1Transaction implements StorageTransaction {
     db: D1Database,
     partition: string,
     resolveTable: (name: string) => CompiledTable,
-    commitValidationSerialized: boolean,
+    pushApplySerialized: boolean,
   ) {
     this.#db = db;
     this.#partition = partition;
     this.#resolveTable = resolveTable;
-    this.#commitValidationSerialized = commitValidationSerialized;
+    this.#pushApplySerialized = pushApplySerialized;
   }
 
   #assertOpen(): void {
@@ -312,16 +312,16 @@ class D1Transaction implements StorageTransaction {
       .slice(0, query.limit);
   }
 
-  async lockPartitionForCommitValidation(): Promise<void> {
+  async lockPartitionForPush(): Promise<void> {
     this.#assertOpen();
-    if (!this.#commitValidationSerialized) {
+    if (!this.#pushApplySerialized) {
       throw new Error(
-        'D1 whole-commit validation requires externally serialized partition writes',
+        '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(
@@ -330,11 +330,9 @@ class D1Transaction implements StorageTransaction {
     result: StoredPushResult,
   ): Promise<void> {
     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();
@@ -558,16 +556,22 @@ class D1Transaction implements StorageTransaction {
 
   async commit(): Promise<void> {
     this.#assertOpen();
-    this.#open = false;
-    if (this.#buffer.length === 0) return;
+    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;
@@ -590,23 +594,30 @@ const D1_MAX_BIND_PARAMS = 100;
 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;
 }
 
 export class D1ServerStorage implements ServerStorage {
   readonly #db: D1Database;
-  readonly #commitValidationSerialized: boolean;
+  readonly #pushApplySerialized: boolean;
   /** Set by `ensureSchema`: app-table lookup for the relational row store. */
   #tables: ReadonlyMap<string, CompiledTable> | undefined;
   #schemaVersion: number | undefined;
 
   constructor(db: D1Database, options: D1ServerStorageOptions = {}) {
     this.#db = db;
-    this.#commitValidationSerialized =
+    this.#pushApplySerialized =
+      options.pushApplySerialized === true ||
       options.commitValidationSerialized === true;
   }
 
@@ -769,7 +780,7 @@ export class D1ServerStorage implements ServerStorage {
       this.#db,
       partition,
       (name) => this.table(name),
-      this.#commitValidationSerialized,
+      this.#pushApplySerialized,
     );
   }
 

package/src/events.ts

@@ -63,12 +63,22 @@ 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. */