velocious 1.0.672 → 1.0.673

package/build/sync/sync-envelope-replay-service.js

@@ -40,6 +40,19 @@ import {scalarModelPrimaryKey, scalarModelPrimaryKeyValue} from "../utils/model-
  * @property {(args: Record<string, ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>} body - Broadcast body.
  * @property {(args: Record<string, ReturnType<typeof JSON.parse>>) => boolean} [when] - Optional gate; skipped when it returns false.
  */
+/**
+ * Private durable idempotency metadata stored outside an application's public change feed.
+ * @typedef {object} SyncReplayReceipt
+ * @property {string | number | null} acknowledgementVersion - Authoritative version returned for an exact retry.
+ * @property {string} clientMutationId - Stable client-owned mutation identity.
+ * @property {string} mutationFingerprint - Hash of the complete normalized mutation identity and intent.
+ */
+/**
+ * Application-owned durable receipt storage.
+ * @typedef {object} SyncReplayReceiptStore
+ * @property {(args: {actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, mutation: SyncReplayMutation}) => Promise<SyncReplayReceipt | null>} find - Finds a receipt in the already-authorized replay partition.
+ * @property {(args: {actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, mutation: SyncReplayMutation, receipt: SyncReplayReceipt}) => Promise<void>} save - Durably records a successful apply before its response is returned.
+ */
 
 /**
  * Replays client sync envelopes through project supplied authentication,
@@ -75,6 +88,7 @@ export default class SyncEnvelopeReplayService {
    * @param {import("../configuration.js").default} [args.configuration] - Configuration whose frontend-model registry routes mutations to resource classes.
    * @param {{strategy?: "optimisticVersion" | "serverWins", versionAttribute: string} | null} [args.conflictStrategy] - Optional base-version conflict detection for routed upserts. Only `optimisticVersion` and `serverWins` are supported for backend replay because the server does not have the client's base snapshot. When `strategy` is omitted it defaults to `optimisticVersion`, matching `resolveSyncConflict` and normalized resource config. When configured, a mutation whose baseVersion does not match the current server versionAttribute is rejected with a structured conflict result instead of being applied.
    * @param {Record<string, import("../configuration-types.js").FrontendModelResourceClassType | string>} [args.resourceTypeOverrides] - Per-resourceType routing overrides: a resource class, or a string alias resolved through the registry.
+   * @param {SyncReplayReceiptStore} [args.replayReceiptStore] - Private durable idempotency storage, separate from public sync/change rows.
    * @param {import("../authorization/ability.js").default} [args.ability] - Ability scoping routed record lookups and create membership checks.
    * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.abilityContext] - Ability context passed to routed resources.
    * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.locals] - Locals passed to routed resources.
@@ -94,6 +108,7 @@ export default class SyncEnvelopeReplayService {
     this.configuration = args.configuration || null
     this.conflictStrategy = args.conflictStrategy || null
     this.resourceTypeOverrides = args.resourceTypeOverrides || null
+    this.replayReceiptStore = args.replayReceiptStore || null
     this.ability = args.ability || null
     this.abilityContext = args.abilityContext || null
     this.locals = args.locals || null
@@ -106,6 +121,9 @@ export default class SyncEnvelopeReplayService {
     if (this.broadcasts && !this.broadcaster) {
       throw new Error("SyncEnvelopeReplayService broadcasts require a broadcaster option delivering them")
     }
+    if (this.replayReceiptStore && (typeof this.replayReceiptStore.find !== "function" || typeof this.replayReceiptStore.save !== "function")) {
+      throw new Error("SyncEnvelopeReplayService replayReceiptStore requires find and save functions")
+    }
     if (this.conflictStrategy) {
       const supportedConflictStrategies = new Set(["optimisticVersion", "serverWins"])
 
@@ -163,6 +181,7 @@ export default class SyncEnvelopeReplayService {
       }
 
       const mutation = normalizedResult.mutation
+      const mutationFingerprint = this.replayMutationFingerprint(mutation)
       const accessResult = await this.authorizeReplayMutation({actor: actorResult.actor, context, mutation})
 
       if (!accessResult.allowed) {
@@ -175,8 +194,18 @@ export default class SyncEnvelopeReplayService {
       }
 
       const existingSync = await this.findExistingReplaySync({actor: actorResult.actor, context, mutation})
-      const shouldApply = await this.shouldApplyReplayMutation({actor: actorResult.actor, context, existingSync, mutation})
-      const duplicate = !shouldApply && this.isDuplicateReplayMutation({existingSync, mutation})
+      const replayReceipt = await this.findReplayReceipt({actor: actorResult.actor, context, mutation})
+      const receiptDuplicate = replayReceipt ? this.isDuplicateReplayReceipt({mutationFingerprint, mutation, receipt: replayReceipt}) : false
+
+      if (replayReceipt && !receiptDuplicate) {
+        syncResponses.push({id: mutation.id, reason: "sync-client-mutation-id-reused", syncState: "failed"})
+        continue
+      }
+
+      const shouldApply = receiptDuplicate
+        ? false
+        : await this.shouldApplyReplayMutation({actor: actorResult.actor, context, existingSync, mutation})
+      const duplicate = receiptDuplicate || (!shouldApply && this.isDuplicateReplayMutation({existingSync, mutation}))
 
       /** @type {ReturnType<typeof JSON.parse>} */
       let applyResult
@@ -184,7 +213,7 @@ export default class SyncEnvelopeReplayService {
       try {
         applyResult = shouldApply
           ? await this.applyReplayMutation({actor: actorResult.actor, context, existingSync, mutation})
-          : await this.skippedReplayMutation({actor: actorResult.actor, context, existingSync, mutation})
+          : await this.skippedReplayMutation({actor: actorResult.actor, context, duplicate, existingSync, mutation})
       } catch (error) {
         // Client-safe apply failures (schema validation, model validation,
         // authorization denials, unknown resource types) fail this sync and
@@ -212,12 +241,13 @@ export default class SyncEnvelopeReplayService {
       }
 
       await this.persistReplayMutation({actor: actorResult.actor, context, existingSync, applyResult, mutation, shouldApply})
+      if (shouldApply) await this.persistReplayReceipt({actor: actorResult.actor, context, mutation, mutationFingerprint, applyResult})
       await this.afterReplayMutation({actor: actorResult.actor, context, existingSync, applyResult, mutation, shouldApply})
 
       /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
       const successfulResponse = {id: mutation.id, syncState: duplicate ? "duplicate" : "successful"}
 
-      const persistedReplayMetadata = duplicate ? this.replayPersistedMetadata(existingSync) : null
+      const persistedReplayMetadata = duplicate ? replayReceipt ?? this.replayPersistedMetadata(existingSync) : null
 
       if (persistedReplayMetadata) {
         successfulResponse.serverVersion = persistedReplayMetadata.acknowledgementVersion
@@ -470,6 +500,75 @@ export default class SyncEnvelopeReplayService {
     return decodeReplayPersistedData(this.replaySyncRecordValue(syncRecord, "data")).metadata
   }
 
+  /**
+   * Loads private idempotency metadata from the application-owned durable store.
+   * @param {{actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, mutation: SyncReplayMutation}} args - Authorized replay context.
+   * @returns {Promise<SyncReplayReceipt | null>} Durable receipt or null.
+   */
+  async findReplayReceipt(args) {
+    if (!this.replayReceiptStore) return null
+
+    const receipt = await this.replayReceiptStore.find(args)
+
+    if (receipt === null) return null
+    if (!receipt || typeof receipt !== "object" || typeof receipt.clientMutationId !== "string" || typeof receipt.mutationFingerprint !== "string") {
+      throw new Error("Sync replay receipt store returned invalid receipt metadata")
+    }
+
+    return receipt
+  }
+
+  /**
+   * Checks an incoming normalized mutation against private receipt metadata.
+   * @param {{mutation: SyncReplayMutation, mutationFingerprint?: string, receipt: SyncReplayReceipt}} args - Mutation and durable receipt.
+   * @returns {boolean} Whether this is the exact mutation whose apply was acknowledged.
+   */
+  isDuplicateReplayReceipt({mutation, mutationFingerprint = this.replayMutationFingerprint(mutation), receipt}) {
+    return receipt.clientMutationId === String(mutation.clientMutationId || mutation.id)
+      && receipt.mutationFingerprint === mutationFingerprint
+  }
+
+  /**
+   * Hashes the complete normalized mutation intent without retaining its payload.
+   * @param {SyncReplayMutation} mutation - Normalized replay mutation.
+   * @returns {string} Stable SHA-256 fingerprint.
+   */
+  replayMutationFingerprint(mutation) {
+    return sha256Hex(stableJsonStringify({
+      baseVersion: mutation.baseVersion,
+      clientUpdatedAt: mutation.clientUpdatedAt.toISOString(),
+      data: mutation.data,
+      resourceId: mutation.resourceId,
+      resourceType: mutation.resourceType,
+      syncType: mutation.syncType
+    }))
+  }
+
+  /**
+   * Persists private receipt metadata after a successful apply and feed write.
+   * @param {{actor: ReturnType<typeof JSON.parse>, applyResult: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, mutation: SyncReplayMutation, mutationFingerprint: string}} args - Applied replay context.
+   * @returns {Promise<void>} Completion after the receipt is durable.
+   */
+  async persistReplayReceipt({actor, applyResult, context, mutation, mutationFingerprint}) {
+    if (!this.replayReceiptStore) return
+
+    let acknowledgementVersion = null
+    if (this.conflictStrategy && applyResult?.record) {
+      acknowledgementVersion = normalizeConflictValue(applyResult.record.readAttribute(this.conflictStrategy.versionAttribute))
+    }
+
+    await this.replayReceiptStore.save({
+      actor,
+      context,
+      mutation,
+      receipt: {
+        acknowledgementVersion,
+        clientMutationId: String(mutation.clientMutationId || mutation.id),
+        mutationFingerprint
+      }
+    })
+  }
+
   /**
    * Applies one normalized mutation to domain models.
    *
@@ -1059,11 +1158,11 @@ export default class SyncEnvelopeReplayService {
    * Resolves an apply result for stale mutations that should not touch domain models.
    * Exact duplicates resolve the current routed record so the acknowledgement
    * can include its authoritative version without applying the mutation again.
-   * @param {{actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, existingSync: ReturnType<typeof JSON.parse>, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor, batch context, existing sync row, and mutation.
+   * @param {{actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, duplicate?: boolean, existingSync: ReturnType<typeof JSON.parse>, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor, batch context, existing sync row, and duplicate decision.
    * @returns {Promise<ReturnType<typeof JSON.parse>>} Project-specific apply result.
    */
-  async skippedReplayMutation({actor, context, existingSync, mutation}) {
-    if (!this.isDuplicateReplayMutation({existingSync, mutation}) || !this.routingConfigured()) return null
+  async skippedReplayMutation({actor, context, duplicate = false, existingSync, mutation}) {
+    if ((!duplicate && !this.isDuplicateReplayMutation({existingSync, mutation})) || !this.routingConfigured()) return null
 
     const registration = this.replayResourceRegistration(mutation.resourceType)
 
@@ -1102,7 +1201,7 @@ export default class SyncEnvelopeReplayService {
       }
     }
 
-    if (this.conflictStrategy && shouldApply && mutation.baseVersion !== undefined && applyResult?.record) {
+    if (!this.replayReceiptStore && this.conflictStrategy && shouldApply && mutation.baseVersion !== undefined && applyResult?.record) {
       const publicPayload = decodeReplayPersistedData(attributes.data).payload
       const acknowledgementVersion = normalizeConflictValue(applyResult.record.readAttribute(this.conflictStrategy.versionAttribute))
 

package/build/sync/sync-realtime-bridge.js

@@ -400,6 +400,15 @@ export default class SyncRealtimeBridge {
     if (generation !== this._generation) return
     if (this.realtimeConfiguration()?.pullOnReconnect === false) return
 
+    const coordinatorRun = this.syncClient.requestCoordinatorSync("realtime")
+
+    if (coordinatorRun) {
+      this._scheduledPull ||= coordinatorRun.finally(() => {
+        this._scheduledPull = null
+      })
+      return
+    }
+
     this._scheduledPull ||= (async () => {
       try {
         await this.syncClient.pull()

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.672",
+  "version": "1.0.673",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/database/drivers/base.js

@@ -2742,32 +2742,66 @@ export default class VelociousDatabaseDriversBase {
    */
   async truncateAllTables() {
     this._assertNotReadOnly()
-    let tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
+    const tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
 
     if (tables.length == 0) return
 
+    await this._truncateAllTables(tables)
+    await this.flushPendingWrites()
+  }
+
+  /**
+   * Owns the foreign-key boundary around every cleanup retry. Drivers that
+   * require one physical request for the full operation may override it.
+   * @protected
+   * @param {Array<import("./base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves after cleanup succeeds.
+   */
+  async _truncateAllTables(tables) {
     await this.withDisabledForeignKeys(async () => {
-      for (let tries = 1; tries <= 6; tries++) {
-        try {
-          await this.truncateTables(tables)
-          return
-        } catch (error) {
-          console.error(error)
+      await this._truncateAllTablesWithRetries(tables)
+    })
+  }
 
-          if (tries == 6) throw error
+  /**
+   * Retries cleanup against refreshed schema snapshots. Drivers may override
+   * `_truncateAllTablesAttempt` to own a complete driver-specific attempt.
+   * @protected
+   * @param {Array<import("./base-table.js").default>} initialTables - Initial eligible tables.
+   * @returns {Promise<void>} - Resolves after one cleanup attempt succeeds.
+   */
+  async _truncateAllTablesWithRetries(initialTables) {
+    let tables = initialTables
 
-          // A truncate failed — the schema cache may still list a table that was
-          // dropped out from under us (e.g. a db:rollback test that left the
-          // shared DB rolled back). Clear it so the next pass re-reads the live
-          // table list and no longer tries to truncate a table that is gone.
-          this.clearSchemaCache()
-          tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
+    for (let tries = 1; tries <= 6; tries++) {
+      try {
+        await this._truncateAllTablesAttempt(tables)
+        return
+      } catch (error) {
+        console.error(error)
 
-          if (tables.length == 0) return
-        }
+        if (tries == 6) throw error
+
+        // A truncate failed — the schema cache may still list a table that was
+        // dropped out from under us (e.g. a db:rollback test that left the
+        // shared DB rolled back). Clear it so the next pass re-reads the live
+        // table list and no longer tries to truncate a table that is gone.
+        this.clearSchemaCache()
+        tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
+
+        if (tables.length == 0) return
       }
-    })
-    await this.flushPendingWrites()
+    }
+  }
+
+  /**
+   * Runs one cleanup attempt while the default owner has constraints disabled.
+   * @protected
+   * @param {Array<import("./base-table.js").default>} tables - Current eligible tables.
+   * @returns {Promise<void>} - Resolves when the attempt completes.
+   */
+  async _truncateAllTablesAttempt(tables) {
+    await this.truncateTables(tables)
   }
 
   /**

package/src/database/drivers/mssql/index.js

@@ -33,6 +33,8 @@ import UUID from "pure-uuid"
  * @type {number}
  */
 const APPLOCK_NOT_HELD_ERROR_NUMBER = 1223
+const DISABLE_FOREIGN_KEYS_SQL = "EXEC sp_MSforeachtable \"ALTER TABLE ? NOCHECK CONSTRAINT all\""
+const ENABLE_FOREIGN_KEYS_SQL = "EXEC sp_MSforeachtable @command1=\"print '?'\", @command2=\"ALTER TABLE ? WITH CHECK CHECK CONSTRAINT all\""
 
 export default class VelociousDatabaseDriversMssql extends Base{
   /** @type {import("mssql").Transaction | null} */
@@ -177,7 +179,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @returns {Promise<void>} - Resolves when foreign keys are disabled.
    */
   async disableForeignKeys() {
-    await this._execConstraintToggle("EXEC sp_MSforeachtable \"ALTER TABLE ? NOCHECK CONSTRAINT all\"", "disableForeignKeys")
+    await this._execConstraintToggle(DISABLE_FOREIGN_KEYS_SQL, "disableForeignKeys")
   }
 
   /**
@@ -185,7 +187,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @returns {Promise<void>} - Resolves when foreign keys are enabled.
    */
   async enableForeignKeys() {
-    await this._execConstraintToggle("EXEC sp_MSforeachtable @command1=\"print '?'\", @command2=\"ALTER TABLE ? WITH CHECK CHECK CONSTRAINT all\"", "enableForeignKeys")
+    await this._execConstraintToggle(ENABLE_FOREIGN_KEYS_SQL, "enableForeignKeys")
   }
 
   /**
@@ -514,6 +516,40 @@ export default class VelociousDatabaseDriversMssql extends Base{
     })
   }
 
+  /**
+   * Keeps constraint toggles and cleanup inside each physical SQL Server
+   * request so a pool cannot split lifecycle ownership across sessions.
+   * @protected
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves after one cleanup attempt succeeds.
+   */
+  async _truncateAllTables(tables) {
+    await this._truncateAllTablesWithRetries(tables)
+  }
+
+  /**
+   * Runs one fail-loud cleanup batch with restoration on both success and
+   * failure. The outer retry owner refreshes stale table snapshots.
+   * @protected
+   * @param {Array<import("../base-table.js").default>} tables - Current eligible tables.
+   * @returns {Promise<void>} - Resolves after the batch completes.
+   */
+  async _truncateAllTablesAttempt(tables) {
+    const statements = [
+      "BEGIN TRY",
+      `  ${DISABLE_FOREIGN_KEYS_SQL};`,
+      ...this._truncateTableStatements(tables),
+      `  ${ENABLE_FOREIGN_KEYS_SQL};`,
+      "END TRY",
+      "BEGIN CATCH",
+      `  ${ENABLE_FOREIGN_KEYS_SQL};`,
+      "  THROW;",
+      "END CATCH;"
+    ]
+
+    await this.query(statements.join("\n"))
+  }
+
   /**
    * Truncates all eligible tables in one SQL Server request, retaining the
    * recognized foreign-key fallback used by the per-table implementation.
@@ -521,6 +557,15 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @returns {Promise<void>} - Resolves when the batch completes.
    */
   async truncateTables(tables) {
+    await this.query(this._truncateTableStatements(tables).join("\n"))
+  }
+
+  /**
+   * Builds the per-table truncate/delete-fallback statements.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {string[]} - SQL statements.
+   */
+  _truncateTableStatements(tables) {
     const statements = []
 
     for (const table of tables) {
@@ -543,7 +588,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
       )
     }
 
-    await this.query(statements.join("\n"))
+    return statements
   }
 
   async lastInsertID(options = {}) {

package/src/sync/local-mutation-log.js

@@ -195,6 +195,42 @@ export default class LocalMutationLog {
     })
   }
 
+  /**
+   * Resolves a durable conflict explicitly. Keeping the server acknowledges the
+   * preserved local intent without replaying it; retrying local intent rebases
+   * it onto the conflict's authoritative serverVersion and returns it to the
+   * pending queue. The prior conflict result stays attached as audit metadata.
+   * @param {{id: string, resolution: "keep-server" | "retry-local"}} args - Resolution.
+   * @returns {Promise<LocalMutationLogRecord>} Resolved record.
+   */
+  async resolveConflict({id, resolution}) {
+    if (!["keep-server", "retry-local"].includes(resolution)) throw new Error(`Unknown local mutation conflict resolution '${resolution}'`)
+
+    return await withStorageKeyLock(this.storageKey, async () => {
+      const rawRecord = await this.storage.record(this.storageKey, id)
+
+      if (!rawRecord) throw new Error(`No local mutation log record '${id}'`)
+
+      const record = normalizeRecord(rawRecord)
+
+      if (record.status !== "conflict") throw new Error(`Cannot resolve ${record.status} local mutation '${id}' as a conflict`)
+
+      if (resolution === "keep-server") {
+        record.status = "synced"
+      } else {
+        const serverVersion = conflictServerVersion(record)
+
+        record.mutation = {...record.mutation, baseVersion: serverVersion}
+        record.status = "pending"
+      }
+
+      record.updatedAt = this.currentTimestamp()
+      await this.storage.updateRecord(this.storageKey, cloneRecord(record))
+
+      return restoreSyncResultTypes(cloneRecord(record))
+    })
+  }
+
   /**
    * Prunes terminal records that are no longer needed for replay dependencies.
    * @param {object} [args] - Compaction options.
@@ -267,6 +303,23 @@ function validStorage(storage) {
     && typeof storageObject.updateRecord === "function"
 }
 
+/**
+ * Reads the authoritative version from a conflicted mutation.
+ * @param {LocalMutationLogRecord} record - Conflicted record.
+ * @returns {string | number | null} - Authoritative version.
+ */
+function conflictServerVersion(record) {
+  const conflict = record.syncResult?.conflict
+
+  if (!conflict || conflict instanceof Date || typeof conflict !== "object" || Array.isArray(conflict) || !Object.hasOwn(conflict, "serverVersion")) {
+    throw new Error(`Cannot retry local mutation '${record.id}' without a conflict serverVersion`)
+  }
+
+  const conflictMetadata = /** @type {Record<string, unknown>} */ (conflict)
+
+  return cloneBaseVersion(conflictMetadata.serverVersion)
+}
+
 /**
  * Sorts records by newest update/sequence first.
  * @param {LocalMutationLogRecord} left - Left record.

package/src/sync/sync-api-client.js

@@ -72,12 +72,13 @@ export default class SyncApiClient {
    * @param {number} [args.batchSize] - Batch size.
    * @param {import("./sync-client-types.js").SyncClientConflictTrackingConfig} args.conflictTracking - Tracking configuration.
    * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}, options?: {signal?: AbortSignal}) => Promise<SyncReplayResponse>} args.postReplay - Transport boundary.
+   * @param {(args: {record: import("./local-mutation-log.js").LocalMutationLogRecord, result: SyncReplayItem}) => Promise<void>} [args.applyConflict] - Applies authoritative conflict state to the local replica before preserving the rejected intent.
    * @param {(identity: string) => number} args.remoteGeneration - Current remote generation.
    * @param {string} args.resourceType - Resource whose log records should drain.
    * @param {AbortSignal} [args.signal] - Lifecycle cancellation signal.
    * @returns {Promise<void>} Resolves when no ready intent remains.
    */
-  static async replayConflictTrackedSyncs({authenticationToken, batchSize, conflictTracking, postReplay, remoteGeneration, resourceType, signal}) {
+  static async replayConflictTrackedSyncs({applyConflict, authenticationToken, batchSize, conflictTracking, postReplay, remoteGeneration, resourceType, signal}) {
     const maxBatchSize = this.normalizedBatchSize(batchSize)
 
     while (true) {
@@ -111,6 +112,11 @@ export default class SyncApiClient {
           throw new Error(`Invalid sync state returned for mutation ${group[0].mutation.clientMutationId}: ${result.syncState}`)
         }
 
+        if (result.syncState === "conflict" && applyConflict) {
+          await applyConflict({record: group[0], result})
+          throwIfSyncAborted(signal)
+        }
+
         for (const record of group) {
           await applySyncReplayResultToLocalMutationLog({mutationLog: conflictTracking.mutationLog, record, result: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (result)})
           throwIfSyncAborted(signal)