@syncular/server 0.15.22 → 0.15.24

package/src/seed.ts

@@ -21,6 +21,8 @@ import {
 } from '@syncular/core';
 import type { SyncServerConfig } from './context';
 import { SyncError } from './errors';
+import type { SyncularServerEvent, SyncularServerEvents } from './events';
+import { composeEvents } from './events-ring';
 import { handleSyncRequest } from './handler';
 
 /** One app-shaped seed mutation — the same vocabulary as client mutations. */
@@ -54,6 +56,48 @@ export interface SeedTarget {
   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 class SeedMutationError extends Error {
+  override 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) {
+    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. */
@@ -79,8 +123,8 @@ function snakeToCamel(name: string): string {
 
 /**
  * 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: SyncServerConfig,
@@ -154,13 +198,37 @@ export async function seedMutations(
       accept: 0b0011,
     },
   ];
+  type SeedTerminalEvent = Extract<
+    SyncularServerEvent,
+    { type: 'push.rejected' | 'push.conflicted' }
+  >;
+  let terminalEvent: SeedTerminalEvent | undefined;
+  const capture: SyncularServerEvents = {
+    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.
@@ -177,13 +245,30 @@ export async function seedMutations(
   }
   if (result.status === 'rejected') {
     const failed = result.results.find((r) => r.status !== 'applied');
+    const code = failed?.code ?? 'sync.invalid_request';
+    const opIndex = failed?.opIndex ?? 0;
+    const retryable = failed?.status === 'error' ? failed.retryable : false;
     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}`,
-    );
+      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/src/sqlite-dialect.ts

@@ -134,6 +134,12 @@ export function serializePushResult(result: StoredPushResult): string {
   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 {
@@ -164,6 +170,8 @@ export function deserializePushResult(text: string): StoredPushResult {
   const parsed = JSON.parse(text) as {
     status: 'applied' | 'rejected';
     commitSeq?: number;
+    recordedAtMs?: number;
+    cacheIdentity?: string;
     results: SerializedResult[];
   };
   const results: PushOperationResult[] = parsed.results.map((record) => {
@@ -192,6 +200,12 @@ export function deserializePushResult(text: string): StoredPushResult {
   return {
     status: parsed.status,
     ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+    ...(parsed.recordedAtMs !== undefined
+      ? { recordedAtMs: parsed.recordedAtMs }
+      : {}),
+    ...(parsed.cacheIdentity !== undefined
+      ? { cacheIdentity: parsed.cacheIdentity }
+      : {}),
     results,
   };
 }

package/src/sqlite-storage.ts

@@ -69,11 +69,17 @@ class SqliteTransaction implements StorageTransaction {
   #storage: SqliteServerStorage;
   #partition: string;
   #open = true;
-  #commitValidationSavepoint = false;
+  #pushApplySavepoint = false;
+  readonly #release: () => void;
 
-  constructor(storage: SqliteServerStorage, partition: string) {
+  constructor(
+    storage: SqliteServerStorage,
+    partition: string,
+    release: () => void,
+  ) {
     this.#storage = storage;
     this.#partition = partition;
+    this.#release = release;
     storage.db.exec('BEGIN IMMEDIATE');
   }
 
@@ -96,11 +102,11 @@ class SqliteTransaction implements StorageTransaction {
     return this.#storage.scanRowsByIndex(this.#partition, query);
   }
 
-  async lockPartitionForCommitValidation(): Promise<void> {
+  async lockPartitionForPush(): Promise<void> {
     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(
@@ -109,18 +115,12 @@ class SqliteTransaction implements StorageTransaction {
     result: StoredPushResult,
   ): Promise<void> {
     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();
   }
@@ -245,18 +245,28 @@ class SqliteTransaction implements StorageTransaction {
   async commit(): Promise<void> {
     this.#assertOpen();
     this.#open = false;
-    this.#storage.db.exec('COMMIT');
+    try {
+      this.#storage.db.exec('COMMIT');
+    } finally {
+      this.#release();
+    }
   }
 
   async rollback(): Promise<void> {
     if (!this.#open) return;
     this.#open = false;
-    this.#storage.db.exec('ROLLBACK');
+    try {
+      this.#storage.db.exec('ROLLBACK');
+    } finally {
+      this.#release();
+    }
   }
 }
 
 export class SqliteServerStorage implements ServerStorage {
   readonly db: Database;
+  /** One bun:sqlite connection can own only one transaction at a time. */
+  #transactionTail: Promise<void> = Promise.resolve();
   /** Set by `ensureSchema`: app-table lookup for the relational row store. */
   #tables: ReadonlyMap<string, CompiledTable> | undefined;
   #schemaVersion: number | undefined;
@@ -405,7 +415,18 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async begin(partition: string): Promise<StorageTransaction> {
-    return new SqliteTransaction(this, partition);
+    const previous = this.#transactionTail;
+    let release!: () => void;
+    this.#transactionTail = new Promise<void>((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. */

package/src/storage.ts

@@ -70,6 +70,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[];
 }
 
@@ -199,15 +203,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,