velocious 1.0.591 → 1.0.593

package/src/database/drivers/base.js

@@ -65,6 +65,7 @@
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
  * @property {boolean} [retry] - Whether retryable errors may retry the query; defaults to true.
  * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
+ * @property {boolean} [sqliteScript] - Internal SQLite flag selecting native multi-statement script execution.
  * @property {AbortSignal} [signal] - Aborts the in-flight query (destroying its connection) when it fires.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  * @property {symbol} [operationOwner] - Opaque owner for an operation-leased connection.
@@ -141,7 +142,8 @@ import TableData from "../table-data/index.js"
 import TableColumn from "../table-data/table-column.js"
 import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
-import {optionalPositiveInteger} from "typanic"
+import { optionalPositiveInteger } from "typanic"
+import { coordinateSharedTransactionConnection } from "../../testing/shared-transaction-connection-coordinator.js"
 
 /** Maximum characters inspected when building the debug SQL preview. */
 const SQL_PREVIEW_SCAN_LIMIT = 4096
@@ -1594,13 +1596,16 @@ export default class VelociousDatabaseDriversBase {
   async affectedRows(sql, options = {}) {
     await this._waitForOperationLease(options.operationOwner)
     this._assertWritableQuery(sql)
-    await this.beforeQuery(sql, options)
 
-    try {
-      return await this._affectedRowsActual(sql)
-    } finally {
-      await this.afterQuery(sql, options)
-    }
+    return await coordinateSharedTransactionConnection(this, async () => {
+      await this.beforeQuery(sql, options)
+
+      try {
+        return await this._affectedRowsActual(sql)
+      } finally {
+        await this.afterQuery(sql, options)
+      }
+    }, options.operationOwner)
   }
 
   /**
@@ -1663,13 +1668,15 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<QueryResultType>} - Resolves with the query.
    */
   async _queryActualWithHooks(sql, options) {
-    await this.beforeQuery(sql, options)
+    return await coordinateSharedTransactionConnection(this, async () => {
+      await this.beforeQuery(sql, options)
 
-    try {
-      return await this._queryActual(sql, options)
-    } finally {
-      await this.afterQuery(sql, options)
-    }
+      try {
+        return await this._queryActual(sql, options)
+      } finally {
+        await this.afterQuery(sql, options)
+      }
+    }, options.operationOwner)
   }
 
   /**
@@ -2214,42 +2221,54 @@ export default class VelociousDatabaseDriversBase {
     await this.query(`ROLLBACK TO SAVEPOINT ${savePointName}`, options)
   }
 
+  /**
+   * Truncates the given table snapshot. Drivers can override this to issue one batch.
+   * @protected
+   * @param {Array<import("./base-table.js").default>} tables - Eligible tables for this cleanup attempt.
+   * @returns {Promise<void>} - Resolves when every table has been cleaned.
+   */
+  async truncateTables(tables) {
+    const truncateErrors = []
+
+    for (const table of tables) {
+      try {
+        await table.truncate({cascade: true})
+      } catch (error) {
+        truncateErrors.push(error)
+      }
+    }
+
+    if (truncateErrors.length > 0) throw truncateErrors[0]
+  }
+
   /**
    * Runs truncate all tables.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async truncateAllTables() {
     this._assertNotReadOnly()
-    await this.withDisabledForeignKeys(async () => {
-      let tries = 0
+    let tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
 
-      while(tries <= 5) {
-        tries++
+    if (tables.length == 0) return
 
-        const tables = await this.getTables()
-        const truncateErrors = []
+    await this.withDisabledForeignKeys(async () => {
+      for (let tries = 1; tries <= 6; tries++) {
+        try {
+          await this.truncateTables(tables)
+          return
+        } catch (error) {
+          console.error(error)
 
-        for (const table of tables) {
-          if (table.getName() != "schema_migrations") {
-            try {
-              await table.truncate({cascade: true})
-            } catch (error) {
-              console.error(error)
-              truncateErrors.push(error)
-            }
-          }
-        }
+          if (tries == 6) throw error
 
-        if (truncateErrors.length == 0) {
-          break
-        } else if (tries <= 5) {
           // 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()
-        } else {
-          throw truncateErrors[0]
+          tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
+
+          if (tables.length == 0) return
         }
       }
     })

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

@@ -506,6 +506,38 @@ export default class VelociousDatabaseDriversMssql extends Base{
     })
   }
 
+  /**
+   * Truncates all eligible tables in one SQL Server request, retaining the
+   * recognized foreign-key fallback used by the per-table implementation.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when the batch completes.
+   */
+  async truncateTables(tables) {
+    const statements = []
+
+    for (const table of tables) {
+      const quotedTable = this.quoteTable(table.getName())
+
+      statements.push(
+        "BEGIN TRY",
+        `  TRUNCATE TABLE ${quotedTable};`,
+        "END TRY",
+        "BEGIN CATCH",
+        "  IF ERROR_NUMBER() = 4712",
+        "  BEGIN",
+        `    DELETE FROM ${quotedTable};`,
+        "  END",
+        "  ELSE",
+        "  BEGIN",
+        "    THROW;",
+        "  END",
+        "END CATCH;"
+      )
+    }
+
+    await this.query(statements.join("\n"))
+  }
+
   async lastInsertID(options = {}) {
     const result = await this.query("SELECT SCOPE_IDENTITY() AS last_insert_id", options)
     const lastInsertID = digg(result, 0, "last_insert_id")

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

@@ -486,6 +486,23 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return true
   }
 
+  /**
+   * Uses one multi-statement request only when the existing connection option
+   * explicitly allows it; otherwise retains the base sequential behavior.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when every table has been truncated.
+   */
+  async truncateTables(tables) {
+    if (!this.getArgs().multipleStatements) {
+      await super.truncateTables(tables)
+      return
+    }
+
+    const statements = tables.map((table) => `TRUNCATE TABLE ${this.quoteTable(table.getName())}`)
+
+    await this.query(statements.join(";\n"))
+  }
+
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

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

@@ -326,6 +326,17 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     })
   }
 
+  /**
+   * Truncates all eligible tables in one PostgreSQL request.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when the batch completes.
+   */
+  async truncateTables(tables) {
+    const quotedTables = tables.map((table) => this.quoteTable(table.getName()))
+
+    await this.query(`TRUNCATE TABLE ${quotedTables.join(", ")} CASCADE`)
+  }
+
   async lastInsertID(options = {}) {
     const result = await this.query("SELECT LASTVAL() AS last_insert_id", options)
 

package/src/database/drivers/sqlite/base.js

@@ -161,6 +161,18 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     })
   }
 
+  /**
+   * Deletes every eligible table through the platform driver's native SQLite
+   * script path so the whole cleanup is submitted as one request.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when the script completes.
+   */
+  async truncateTables(tables) {
+    const statements = tables.map((table) => `DELETE FROM ${this.quoteTable(table.getName())}`)
+
+    await this.query(statements.join(";\n"), {sqliteScript: true})
+  }
+
   /**
    * Runs insert multiple.
    * @param {string} tableName - Table name.

package/src/database/drivers/sqlite/connection-sql-js.js

@@ -89,14 +89,15 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
   /**
    * Runs query.
    * @param {string} sql - SQL string.
+   * @param {{mutation?: boolean}} [options] - Internal query classification options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with the query.
    */
-  async query(sql) {
+  async query(sql, {mutation = false} = {}) {
     const result = await queryWeb(this.connection, sql)
     const downcasedSQL = sql.toLowerCase().trim()
 
     // Auto-save database in local storage in case we can find manipulating instructions in the SQL
-    if (downcasedSQL.startsWith("delete ") || downcasedSQL.startsWith("insert into ") || downcasedSQL.startsWith("update ")) {
+    if (mutation || downcasedSQL.startsWith("delete ") || downcasedSQL.startsWith("insert into ") || downcasedSQL.startsWith("update ")) {
       this.saveDatabaseDebounce()
     }
 

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

@@ -84,11 +84,17 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with the query actual.
    */
-  async _queryActual(sql) {
+  async _queryActual(sql, options = {}) {
     if (!this.connection) throw new Error("No connection")
 
+    if (options.sqliteScript) {
+      await this.connection.exec(sql)
+      return []
+    }
+
     return await query(this.connection, sql)
   }
 

package/src/database/drivers/sqlite/index.native.js

@@ -82,13 +82,19 @@ export default class VelociousDatabaseDriversSqliteNative extends Base {
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Query result rows.
    */
-  async _queryActual(sql) {
-    return await this._queryMutex.sync(() => {
+  async _queryActual(sql, options = {}) {
+    return await this._queryMutex.sync(async () => {
       if (!this.connection) throw new Error("Not connected yet")
 
-      return query(this.connection, sql)
+      if (options.sqliteScript) {
+        await this.connection.execAsync(sql)
+        return []
+      }
+
+      return await query(this.connection, sql)
     })
   }
 

package/src/database/drivers/sqlite/index.web.js

@@ -178,13 +178,16 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with the query actual.
    */
-  async _queryActual(sql) {
-    const result = await this.getConnection().query(sql)
+  async _queryActual(sql, options = {}) {
+    const connection = this.getConnection()
+    const result = connection instanceof ConnectionSqlJs
+      ? await connection.query(sql, {mutation: options.sqliteScript === true})
+      : await connection.query(sql)
 
     if (!Array.isArray(result)) {
-      const connection = this.getConnection()
       const connectionName = connection?.constructor?.name || "UnknownConnection"
 
       throw new Error(`Sqlite web connection ${connectionName} returned a non-array result: ${typeof result}`)

package/src/environment-handlers/base.js

@@ -27,6 +27,24 @@ export default class VelociousEnvironmentHandlerBase {
    */
   async createTestSharedTransactionConnection(_args) { return undefined }
 
+  /**
+   * Gets the active shared-transaction coordinator owner for a connection.
+   * Browser runtimes never install the Node test broker.
+   * @param {object} _connection - Parent physical connection.
+   * @returns {symbol | undefined} - Active coordinator owner.
+   */
+  getSharedTransactionCoordinatorOwner(_connection) { return undefined }
+
+  /**
+   * Runs work as the current shared-transaction coordinator owner.
+   * @template T
+   * @param {object} _connection - Parent physical connection.
+   * @param {symbol} _owner - Coordinator owner.
+   * @param {() => T} callback - Owned work.
+   * @returns {T} - Callback result.
+   */
+  runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
+
   /**
    * Mutable ambient tenant used by runtimes without async-context storage.
    * @type {ReturnType<typeof JSON.parse> | undefined}

package/src/environment-handlers/node.js

@@ -80,6 +80,38 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @type {import("node:async_hooks").AsyncLocalStorage<TimezoneStore> | undefined} */
   _timezoneAsyncLocalStorage = NodeAsyncLocalStorage ? new NodeAsyncLocalStorage() : undefined
 
+  /**
+   * Shared-transaction coordinator ownership by physical connection.
+   * @type {import("node:async_hooks").AsyncLocalStorage<Map<object, symbol>> | undefined}
+   */
+  _sharedTransactionCoordinatorAsyncLocalStorage = NodeAsyncLocalStorage ? new NodeAsyncLocalStorage() : undefined
+
+  /**
+   * Gets the active shared-transaction coordinator owner for a connection.
+   * @param {object} connection - Parent physical connection.
+   * @returns {symbol | undefined} - Active coordinator owner.
+   */
+  getSharedTransactionCoordinatorOwner(connection) {
+    return this._sharedTransactionCoordinatorAsyncLocalStorage?.getStore()?.get(connection)
+  }
+
+  /**
+   * Runs work as the current shared-transaction coordinator owner.
+   * @template T
+   * @param {object} connection - Parent physical connection.
+   * @param {symbol} owner - Coordinator owner.
+   * @param {() => T} callback - Owned work.
+   * @returns {T} - Callback result.
+   */
+  runWithSharedTransactionCoordinatorOwner(connection, owner, callback) {
+    if (!this._sharedTransactionCoordinatorAsyncLocalStorage) return callback()
+
+    const owners = new Map(this._sharedTransactionCoordinatorAsyncLocalStorage.getStore())
+
+    owners.set(connection, owner)
+    return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
+  }
+
   /**
    * Find commands result.
    * @type {import("./base.js").CommandFileObjectType[] | undefined} */

package/src/sync/conflict-strategy.js

@@ -63,6 +63,9 @@ export async function applySyncReplayResultToLocalMutationLog({mutationLog, reco
  * @returns {import("./local-mutation-log.js").LocalMutationStatus} - Local mutation-log status.
  */
 export function replayResultLocalStatus(result) {
+  if (result.syncState === "conflict") return "conflict"
+  if (result.syncState === "failed" || result.syncState === "rejected") return "rejected"
+  if (result.syncState === "successful" || result.syncState === "duplicate") return "synced"
   if (result.status === "conflict") return "conflict"
   if (result.status === "error" || result.status === "rejected") return "rejected"
   if (result.status === "success" && replayResultHasFailedApplication(result)) return "rejected"

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

@@ -148,6 +148,30 @@ export default class LocalMutationLog {
     })
   }
 
+  /**
+   * Replaces the mutation payload of a still-pending record. Used when an
+   * acknowledged predecessor supplies the authoritative base for its successor.
+   * @param {{id: string, mutation: import("./device-identity.js").SyncMutation}} args - Record and replacement mutation.
+   * @returns {Promise<LocalMutationLogRecord>} Updated record.
+   */
+  async updateMutation({id, mutation}) {
+    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 (!PENDING_STATUSES.has(record.status)) throw new Error(`Cannot update mutation for ${record.status} local mutation '${id}'`)
+
+      record.mutation = normalizeMutation(mutation)
+      record.updatedAt = this.currentTimestamp()
+      await this.storage.updateRecord(this.storageKey, cloneRecord(record))
+
+      return cloneRecord(record)
+    })
+  }
+
   /**
    * Prunes terminal records that are no longer needed for replay dependencies.
    * @param {object} [args] - Compaction options.

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

@@ -73,6 +73,9 @@
 /**
  * @typedef {object} SyncReplayItem
  * @property {string | number} id - Sync id.
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} [conflict] - Structured durable conflict payload.
+ * @property {string} [reason] - Rejection reason.
+ * @property {string | number | null} [serverVersion] - Authoritative version after successful replay.
  * @property {string} syncState - Replay state.
  */
 

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

@@ -3,6 +3,7 @@
 import {optionalBoolean, optionalInteger} from "typanic"
 
 import recordChanges from "../database/record-changes.js"
+import {applySyncReplayResultToLocalMutationLog} from "./conflict-strategy.js"
 
 /** @typedef {import("./sync-api-client-types.js").SyncChangeApplyResult} SyncChangeApplyResult */
 /** @typedef {import("./sync-api-client-types.js").SyncChangeEnvelope} SyncChangeEnvelope */
@@ -21,6 +22,208 @@ const syncTaskPromises = new Map()
  * persistence/auth hooks.
  */
 export default class SyncApiClient {
+  /**
+   * Appends one conflict-tracked intent to the existing durable mutation log.
+   * @param {object} args - Queue arguments.
+   * @param {string | number | null} args.baseVersion - Authoritative version observed before the local mutation.
+   * @param {import("./sync-client-types.js").SyncClientConflictTrackingConfig} args.conflictTracking - Durable tracking configuration.
+   * @param {Record<string, unknown>} args.data - Backend-safe mutation attributes.
+   * @param {"create" | "update" | "destroy"} args.operation - Local operation.
+   * @param {ReturnType<typeof JSON.parse>} args.resource - Local resource.
+   * @param {string} args.resourceType - Resource type.
+   * @param {string} args.syncType - Wire operation.
+   * @returns {Promise<import("./local-mutation-log.js").LocalMutationLogRecord>} Appended intent.
+   */
+  static async queueConflictTrackedSync({baseVersion, conflictTracking, data, operation, resource, resourceType, syncType}) {
+    const resourceId = String(resource.id())
+    const records = await conflictTracking.mutationLog.records()
+    const predecessor = records
+      .filter((record) => record.mutation.model === resourceType && record.mutation.payload?.resourceId === resourceId)
+      .at(-1)
+    const clientMutationId = conflictTracking.clientMutationId()
+    const now = conflictTracking.now ? conflictTracking.now() : new Date()
+    const predecessorTime = predecessor ? new Date(predecessor.mutation.occurredAt).getTime() : Number.NEGATIVE_INFINITY
+    const occurredAt = new Date(Math.max(now.getTime(), predecessorTime + 1)).toISOString()
+
+    return await conflictTracking.mutationLog.append({
+      dependencies: predecessor ? [{clientMutationId: predecessor.mutation.clientMutationId, model: resourceType}] : [],
+      mutation: {
+        actorDeviceId: conflictTracking.actorDeviceId,
+        actorUserId: conflictTracking.actorUserId,
+        attributes: /** @type {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} */ (data),
+        baseVersion,
+        clientMutationId,
+        model: resourceType,
+        occurredAt,
+        offlineGrantId: conflictTracking.offlineGrantId,
+        operation,
+        payload: {resourceId, syncType},
+        policyHash: conflictTracking.policyHash
+      }
+    })
+  }
+
+  /**
+   * Drains the existing mutation log in predecessor order. Independent records
+   * continue after durable conflicts/rejections; successors stay blocked.
+   * @param {object} args - Replay arguments.
+   * @param {string} args.authenticationToken - Authentication token.
+   * @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>>>}) => Promise<SyncReplayResponse>} args.postReplay - Transport boundary.
+   * @param {(identity: string) => number} args.remoteGeneration - Current remote generation.
+   * @param {string} args.resourceType - Resource whose log records should drain.
+   * @returns {Promise<void>} Resolves when no ready intent remains.
+   */
+  static async replayConflictTrackedSyncs({authenticationToken, batchSize, conflictTracking, postReplay, remoteGeneration, resourceType}) {
+    const maxBatchSize = this.normalizedBatchSize(batchSize)
+
+    while (true) {
+      const records = await conflictTracking.mutationLog.records()
+      const statuses = new Map(records.map((record) => [record.mutation.clientMutationId, record.status]))
+      const pending = records.filter((record) => record.status === "pending" && record.mutation.model === resourceType)
+      const ready = pending.filter((record) => record.dependencies.every((dependency) => statuses.get(dependency.clientMutationId) === "synced"))
+
+      if (ready.length === 0) return
+
+      const groups = this.conflictReplayGroups({pending, ready}).slice(0, maxBatchSize)
+      const generations = new Map(groups.map((group) => [group[0].mutation.clientMutationId, remoteGeneration(this.conflictRecordIdentity(group[0]))]))
+      const response = await postReplay({
+        authenticationToken,
+        syncs: groups.map((group) => this.conflictReplayPayload(group))
+      })
+
+      this.ensureSuccessfulResponse(response)
+
+      const responsesById = new Map((response.syncs || []).map((result) => [String(result.id), result]))
+
+      for (const group of groups) {
+        const result = responsesById.get(group[0].mutation.clientMutationId)
+
+        if (!result) throw new Error(`Sync response missing result for mutation ${group[0].mutation.clientMutationId}`)
+        if (!["successful", "duplicate", "conflict", "failed", "rejected"].includes(result.syncState)) {
+          throw new Error(`Invalid sync state returned for mutation ${group[0].mutation.clientMutationId}: ${result.syncState}`)
+        }
+
+        for (const record of group) {
+          await applySyncReplayResultToLocalMutationLog({mutationLog: conflictTracking.mutationLog, record, result: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (result)})
+        }
+
+        if (["successful", "duplicate"].includes(result.syncState) && result.serverVersion !== undefined) {
+          const identity = this.conflictRecordIdentity(group[0])
+
+          if (remoteGeneration(identity) === generations.get(group[0].mutation.clientMutationId)) {
+            await this.rebaseConflictSuccessor({conflictTracking, predecessor: group[group.length - 1], serverVersion: result.serverVersion})
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Builds safe transport groups from root-ready records and their successors.
+   * @param {{pending: Array<import("./local-mutation-log.js").LocalMutationLogRecord>, ready: Array<import("./local-mutation-log.js").LocalMutationLogRecord>}} args - Pending and root-ready records.
+   * @returns {Array<Array<import("./local-mutation-log.js").LocalMutationLogRecord>>} Safe transport groups.
+   */
+  static conflictReplayGroups({pending, ready}) {
+    const groups = []
+    const selectedIdentities = new Set()
+
+    for (const record of ready) {
+      const identity = this.conflictRecordIdentity(record)
+
+      if (selectedIdentities.has(identity)) continue
+
+      const group = [record]
+      let tail = record
+
+      while (true) {
+        const successor = pending.find((candidate) => candidate.dependencies.some((dependency) => dependency.clientMutationId === tail.mutation.clientMutationId))
+
+        if (!successor || !this.canCoalesceConflictRecords(tail, successor)) break
+        group.push(successor)
+        tail = successor
+      }
+
+      groups.push(group)
+      selectedIdentities.add(identity)
+    }
+
+    return groups
+  }
+
+  /**
+   * Checks whether two durable intents can share one transport mutation.
+   * @param {import("./local-mutation-log.js").LocalMutationLogRecord} left - Earlier intent.
+   * @param {import("./local-mutation-log.js").LocalMutationLogRecord} right - Later intent.
+   * @returns {boolean} Whether scalar updates can share one transport mutation.
+   */
+  static canCoalesceConflictRecords(left, right) {
+    if (left.mutation.operation !== "update" || right.mutation.operation !== "update") return false
+    if (this.conflictRecordIdentity(left) !== this.conflictRecordIdentity(right)) return false
+    if (left.mutation.baseVersion !== right.mutation.baseVersion) return false
+    if (!this.scalarSyncAttributes(left.mutation.attributes) || !this.scalarSyncAttributes(right.mutation.attributes)) return false
+
+    return !Object.keys(left.mutation.attributes || {}).some((key) => Object.hasOwn(right.mutation.attributes || {}, key))
+  }
+
+  /**
+   * Checks whether attributes contain scalar JSON values only.
+   * @param {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue> | undefined} attributes - Attributes.
+   * @returns {boolean} Whether every value is scalar.
+   */
+  static scalarSyncAttributes(attributes) {
+    return Boolean(attributes) && Object.values(attributes || {}).every((value) => value === null || ["string", "number", "boolean"].includes(typeof value))
+  }
+
+  /**
+   * Builds one replay envelope for a safe transport group.
+   * @param {Array<import("./local-mutation-log.js").LocalMutationLogRecord>} group - Transport group.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Replay envelope.
+   */
+  static conflictReplayPayload(group) {
+    const first = group[0]
+    const payload = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ ({
+      baseVersion: first.mutation.baseVersion,
+      clientUpdatedAt: first.mutation.occurredAt,
+      data: Object.assign({}, ...group.map((record) => record.mutation.attributes || {})),
+      id: first.mutation.clientMutationId,
+      resourceId: first.mutation.payload?.resourceId,
+      resourceType: first.mutation.model,
+      syncType: first.mutation.payload?.syncType
+    })
+
+    return payload
+  }
+
+  /**
+   * Builds a stable resource identity for ordering and remote generations.
+   * @param {import("./local-mutation-log.js").LocalMutationLogRecord} record - Record.
+   * @returns {string} Resource identity.
+   */
+  static conflictRecordIdentity(record) {
+    return `${record.mutation.model}:${String(record.mutation.payload?.resourceId)}`
+  }
+
+  /**
+   * Rebases the direct pending successor from an authoritative acknowledgement.
+   * @param {object} args - Rebase args.
+   * @param {import("./sync-client-types.js").SyncClientConflictTrackingConfig} args.conflictTracking - Tracking config.
+   * @param {import("./local-mutation-log.js").LocalMutationLogRecord} args.predecessor - Acknowledged predecessor.
+   * @param {string | number | null} args.serverVersion - Authoritative server version.
+   * @returns {Promise<void>}
+   */
+  static async rebaseConflictSuccessor({conflictTracking, predecessor, serverVersion}) {
+    const successor = (await conflictTracking.mutationLog.pendingRecords())
+      .find((record) => record.dependencies.some((dependency) => dependency.clientMutationId === predecessor.mutation.clientMutationId))
+
+    if (!successor) return
+
+    await conflictTracking.mutationLog.updateMutation({
+      id: successor.id,
+      mutation: {...successor.mutation, baseVersion: serverVersion}
+    })
+  }
   /**
    * Serializes sync work with the same key so callers do not have to keep app-local locks.
    * @param {string} key - Lock key.