velocious 1.0.591 → 1.0.592

package/src/sync/sync-client.js

@@ -119,10 +119,14 @@ export default class SyncClient {
     this._scheduledReplay = null
     /** @type {Record<string, import("./sync-api-client-types.js").SyncResourceConfig> | null} */
     this._pullResourceConfigs = null
-    /** @type {Array<{callback: (record: ReturnType<typeof JSON.parse>) => Promise<void>, callbackName: "afterCreate" | "afterUpdate" | "afterDestroy", modelClass: ReturnType<typeof JSON.parse>}>} */
+    /** @type {Array<{callback: (record: ReturnType<typeof JSON.parse>) => Promise<void> | void, callbackName: "afterCreate" | "afterUpdate" | "afterDestroy" | "beforeUpdate" | "beforeDestroy", modelClass: ReturnType<typeof JSON.parse>}>} */
     this._trackedCallbacks = []
     /** @type {WeakSet<object>} */
     this._remoteApplyRecords = new WeakSet()
+    /** @type {Map<string, number>} */
+    this._remoteGenerations = new Map()
+    /** @type {WeakMap<object, Array<string | number | null>>} */
+    this._capturedBaseVersions = new WeakMap()
     this._withoutTrackingDepth = 0
     /** @type {Logger | {error: (...messages: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} | null} */
     this._logger = null
@@ -145,6 +149,23 @@ export default class SyncClient {
     for (const [resourceType, resourceConfig] of Object.entries(this.config.resources)) {
       const operations = this.trackedOperations({resourceConfig, resourceType})
 
+      if (resourceConfig.conflictTracking) {
+        for (const operation of operations.filter((candidate) => candidate !== "create")) {
+          const callbackName = operation === "destroy" ? "beforeDestroy" : "beforeUpdate"
+          const callback = (/** @type {ReturnType<typeof JSON.parse>} */ record) => {
+            if (this.isTrackingSuppressed(record)) return
+
+            const capturedVersions = this._capturedBaseVersions.get(record) || []
+
+            capturedVersions.push(this.preMutationBaseVersionFor({operation, record, resourceConfig}))
+            this._capturedBaseVersions.set(record, capturedVersions)
+          }
+
+          resourceConfig.modelClass[callbackName](callback)
+          this._trackedCallbacks.push({callback, callbackName, modelClass: resourceConfig.modelClass})
+        }
+      }
+
       for (const operation of operations) {
         const callbackName = TRACKED_CALLBACK_NAMES[operation]
         const callback = this.trackedMutationCallback({operation, resourceConfig})
@@ -220,6 +241,9 @@ export default class SyncClient {
         resource: record
       })
       const syncType = this.defaultSyncType({operation, record, resourceConfig})
+      const baseVersion = resourceConfig.conflictTracking
+        ? this.capturedBaseVersionFor({operation, record, resourceConfig})
+        : null
       const databaseOperation = record.databaseOperation()
       const operationScope = databaseOperation
         ? databaseOperation.forModel(this.config.syncModel)
@@ -227,12 +251,19 @@ export default class SyncClient {
 
       await record.connection().afterCommit(async () => {
         try {
-          await SyncApiClient.queueLocalSync({
-            data,
-            resource: record,
-            syncModel: operationScope,
-            syncType
-          })
+          if (resourceConfig.conflictTracking) {
+            await SyncApiClient.queueConflictTrackedSync({
+              baseVersion,
+              conflictTracking: resourceConfig.conflictTracking,
+              data,
+              operation,
+              resource: record,
+              resourceType: record.constructor.getModelName(),
+              syncType
+            })
+          } else {
+            await SyncApiClient.queueLocalSync({data, resource: record, syncModel: operationScope, syncType})
+          }
         } catch (error) {
           await this.reportAfterCommitError(/** @type {Error} */ (error))
 
@@ -483,6 +514,17 @@ export default class SyncClient {
         throw new Error(`No sync resource with pull attributes configured for ${source}: ${String(resourceType)}`)
       }
 
+      const data = sync.data()
+      const versionAttribute = this.config.resources[resourceType].conflictTracking?.versionAttribute
+
+      if (versionAttribute) {
+        const dataAttributes = data && typeof data === "object" && !Array.isArray(data)
+          ? /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (data)
+          : {}
+
+        this.noteRemoteVersion({resourceId: String(sync.resourceId()), resourceType, version: dataAttributes[versionAttribute]})
+      }
+
       return await applier(sync)
     }
   }
@@ -658,18 +700,42 @@ export default class SyncClient {
   /**
    * Queues a local model change as a pending sync row and schedules an immediate
    * replay attempt (kept pending while offline or when the backend rejects it).
-   * @param {{resource: ReturnType<typeof JSON.parse>, data?: Record<string, ReturnType<typeof JSON.parse>>, syncType?: string}} args - Queue args.
-   * @returns {Promise<ReturnType<typeof JSON.parse>>} Pending local sync row.
+   * @param {{baseVersion?: string | number | null, resource: ReturnType<typeof JSON.parse>, data?: Record<string, ReturnType<typeof JSON.parse>>, operation?: "create" | "update" | "destroy", syncType?: string}} args - Queue args.
+   * @returns {Promise<ReturnType<typeof JSON.parse> | import("./local-mutation-log.js").LocalMutationLogRecord>} Pending local sync row or durable conflict-tracked intent.
    */
-  async queue({data, resource, syncType}) {
+  async queue({baseVersion, data, operation = "update", resource, syncType}) {
     const resourceConfig = this.resourceConfigFor(resource)
+    const resolvedSyncType = syncType ?? this.defaultSyncType({operation, record: resource, resourceConfig})
+
+    if (resourceConfig.conflictTracking) {
+      const queuedData = SyncApiClient.queuedSyncData({
+        booleanAttributes: resourceConfig.booleanAttributes || [],
+        data,
+        localOnlyAttributes: resourceConfig.localOnlyAttributes || [],
+        resource
+      })
+      const record = await SyncApiClient.queueConflictTrackedSync({
+        baseVersion: baseVersion === undefined ? this.baseVersionFor({operation, record: resource, resourceConfig}) : baseVersion,
+        conflictTracking: resourceConfig.conflictTracking,
+        data: queuedData,
+        operation,
+        resource,
+        resourceType: resource.constructor.getModelName(),
+        syncType: resolvedSyncType
+      })
+
+      this.scheduleReplay()
+
+      return record
+    }
+
     const syncRow = await SyncApiClient.queueLocalSync({
       booleanAttributes: resourceConfig.booleanAttributes || [],
       data,
       localOnlyAttributes: resourceConfig.localOnlyAttributes || [],
       resource,
       syncModel: this.config.syncModel,
-      syncType: syncType ?? this.defaultSyncType({operation: "update", record: resource, resourceConfig})
+      syncType: resolvedSyncType
     })
 
     this.scheduleReplay()
@@ -686,6 +752,19 @@ export default class SyncClient {
     if (!(await this.isOnline())) return
 
     await SyncApiClient.singleFlight(`velocious-sync-client-replay-${this._clientNumber}`, async () => {
+      for (const [resourceType, resourceConfig] of Object.entries(this.config.resources)) {
+        if (!resourceConfig.conflictTracking) continue
+
+        await SyncApiClient.replayConflictTrackedSyncs({
+          authenticationToken: await this.config.authenticationToken(),
+          batchSize: this.config.batchSize,
+          conflictTracking: resourceConfig.conflictTracking,
+          postReplay: this.config.postReplay,
+          remoteGeneration: (identity) => this._remoteGenerations.get(identity) || 0,
+          resourceType
+        })
+      }
+
       await SyncApiClient.replayLocalSyncs({
         authenticationToken: await this.config.authenticationToken(),
         batchSize: this.config.batchSize,
@@ -695,6 +774,82 @@ export default class SyncClient {
     })
   }
 
+  /**
+   * Records an authoritative remote observation so an in-flight acknowledgement
+   * cannot rebase a successor across that observation.
+   * @param {{resourceId: string | number, resourceType: string, version?: string | number | null}} args - Remote identity.
+   * @returns {void}
+   */
+  noteRemoteVersion({resourceId, resourceType, version}) {
+    void version
+    const identity = `${resourceType}:${String(resourceId)}`
+
+    this._remoteGenerations.set(identity, (this._remoteGenerations.get(identity) || 0) + 1)
+  }
+
+  /**
+   * Reads the authoritative base version observed before a local mutation.
+   * @param {{operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>, resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Version args.
+   * @returns {string | number | null} Base version.
+   */
+  baseVersionFor({operation, record, resourceConfig}) {
+    if (operation === "create") return null
+
+    const versionAttribute = resourceConfig.conflictTracking?.versionAttribute
+
+    if (!versionAttribute) return null
+
+    const value = record.readAttribute(versionAttribute)
+
+    if (value instanceof Date) return value.toISOString()
+    if (value === null || typeof value === "string" || typeof value === "number") return value
+
+    throw new Error(`Sync conflict version ${versionAttribute} must be a Date, string, number, or null`)
+  }
+
+  /**
+   * Reads the pre-assignment value exposed by record changes during beforeUpdate.
+   * Deletes have no version change pair and use the record's current version.
+   * @param {{operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>, resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Version args.
+   * @returns {string | number | null} Pre-mutation base version.
+   */
+  preMutationBaseVersionFor({operation, record, resourceConfig}) {
+    const versionAttribute = resourceConfig.conflictTracking?.versionAttribute
+    const versionColumn = versionAttribute
+      ? record.constructor.getAttributeNameToColumnNameMap()[versionAttribute]
+      : undefined
+    const versionChange = operation === "update" && versionColumn
+      ? record.changes()[versionColumn]
+      : undefined
+
+    if (!versionChange) return this.baseVersionFor({operation, record, resourceConfig})
+
+    const value = versionChange[0]
+
+    if (value instanceof Date) return value.toISOString()
+    if (value === null || typeof value === "string" || typeof value === "number") return value
+
+    throw new Error(`Sync conflict version ${versionAttribute} must be a Date, string, number, or null`)
+  }
+
+  /**
+   * Consumes the base captured for this lifecycle event before its after-commit
+   * closure is deferred, preserving repeated same-record writes in one transaction.
+   * @param {{operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>, resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Capture args.
+   * @returns {string | number | null} Captured base version.
+   */
+  capturedBaseVersionFor({operation, record, resourceConfig}) {
+    if (operation === "create") return null
+
+    const capturedVersions = this._capturedBaseVersions.get(record)
+    const baseVersion = capturedVersions?.shift()
+
+    if (capturedVersions?.length === 0) this._capturedBaseVersions.delete(record)
+    if (baseVersion !== undefined) return baseVersion
+
+    return this.baseVersionFor({operation, record, resourceConfig})
+  }
+
   /**
    * Schedules a background replay attempt without blocking the caller.
    * Failures go to config.onError (or rethrow when none is configured).
@@ -822,7 +977,7 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     throw new Error(`${resourceType} static sync must be true or a sync declaration object, got: ${String(declaration)}`)
   }
 
-  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, publish, realtime, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
+  const {afterApply, attributes, booleanAttributes, conflictTracking, findRecord, findRecordForDelete, localOnlyAttributes, publish, realtime, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
   const unknownKeys = Object.keys(restDeclaration)
 
   // `publish` is the server-side half of the shared `static sync` declaration
@@ -831,7 +986,7 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
   void publish
 
   if (unknownKeys.length > 0) {
-    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, publish, realtime, syncType, track, trackedData)`)
+    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, conflictTracking, findRecord, findRecordForDelete, localOnlyAttributes, publish, realtime, syncType, track, trackedData)`)
   }
   if (syncType !== undefined && typeof syncType !== "function" && syncType !== "upsert") {
     throw new Error(`${resourceType} static sync syncType must be a function or the string "upsert", got: ${String(syncType)}`)
@@ -839,13 +994,19 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
 
   const derived = derivedSyncAttributes({modelClass, resourceType})
 
+  if (conflictTracking) validateConflictTracking({conflictTracking, derived, resourceType})
+
   return {
     afterApply,
     attributes,
     booleanAttributes: mergedAttributeNames(derived.booleanAttributes, booleanAttributes),
+    conflictTracking: conflictTracking ? {...conflictTracking, versionAttribute: conflictTracking.versionAttribute || "updatedAt"} : undefined,
     findRecord,
     findRecordForDelete,
-    localOnlyAttributes: mergedAttributeNames(derived.localOnlyAttributes, localOnlyAttributes),
+    localOnlyAttributes: mergedAttributeNames(
+      derived.localOnlyAttributes,
+      [...(localOnlyAttributes || []), ...(conflictTracking ? [conflictTracking.versionAttribute || "updatedAt"] : [])]
+    ),
     modelClass,
     realtime,
     syncType,
@@ -854,6 +1015,29 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
   }
 }
 
+/**
+ * Validates one resource's durable conflict-tracking declaration.
+ * @param {{conflictTracking: import("./sync-client-types.js").SyncClientConflictTrackingConfig, derived: {booleanAttributes: string[], localOnlyAttributes: string[]}, resourceType: string}} args - Validation args.
+ * @returns {void}
+ */
+function validateConflictTracking({conflictTracking, derived, resourceType}) {
+  const requiredStrings = {
+    actorDeviceId: conflictTracking.actorDeviceId,
+    actorUserId: conflictTracking.actorUserId,
+    offlineGrantId: conflictTracking.offlineGrantId,
+    policyHash: conflictTracking.policyHash
+  }
+
+  for (const [key, value] of Object.entries(requiredStrings)) {
+    if (typeof value !== "string" || value.length === 0) throw new Error(`${resourceType} conflictTracking.${key} must be a non-empty string`)
+  }
+  if (!conflictTracking.mutationLog || typeof conflictTracking.mutationLog.append !== "function") throw new Error(`${resourceType} conflictTracking.mutationLog must be a LocalMutationLog`)
+  if (typeof conflictTracking.clientMutationId !== "function") throw new Error(`${resourceType} conflictTracking.clientMutationId must be a function`)
+  if (!conflictTracking.versionAttribute && !derived.localOnlyAttributes.includes("updatedAt")) {
+    throw new Error(`${resourceType} conflictTracking requires versionAttribute because the model has no updatedAt column`)
+  }
+}
+
 /**
  * Derives boolean and local-only attribute names from a model's column metadata:
  * booleans from boolean column types; local-only from the primary key,

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

@@ -7,6 +7,7 @@ import {resolveSyncConflict} from "./conflict-strategy.js"
 import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
 import stableJsonStringify from "./stable-json.js"
 import sha256Hex from "../utils/sha256-hex.js"
+import {decodeReplayPersistedData, serializeReplayPersistedData} from "./sync-replay-persisted-data.js"
 import {ValidationError} from "../database/record/index.js"
 import VelociousError from "../velocious-error.js"
 
@@ -173,6 +174,7 @@ 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})
 
       /** @type {ReturnType<typeof JSON.parse>} */
       let applyResult
@@ -210,7 +212,18 @@ export default class SyncEnvelopeReplayService {
       await this.persistReplayMutation({actor: actorResult.actor, context, existingSync, applyResult, mutation, shouldApply})
       await this.afterReplayMutation({actor: actorResult.actor, context, existingSync, applyResult, mutation, shouldApply})
 
-      syncResponses.push({id: mutation.id, syncState: "successful"})
+      /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
+      const successfulResponse = {id: mutation.id, syncState: duplicate ? "duplicate" : "successful"}
+
+      const persistedReplayMetadata = duplicate ? this.replayPersistedMetadata(existingSync) : null
+
+      if (persistedReplayMetadata) {
+        successfulResponse.serverVersion = persistedReplayMetadata.acknowledgementVersion
+      } else if (this.conflictStrategy && mutation.baseVersion !== undefined && applyResult?.record) {
+        successfulResponse.serverVersion = normalizeConflictValue(applyResult.record.readAttribute(this.conflictStrategy.versionAttribute))
+      }
+
+      syncResponses.push(successfulResponse)
     }
 
     return {syncs: syncResponses}
@@ -405,6 +418,56 @@ export default class SyncEnvelopeReplayService {
     return Number.isNaN(parsedValue.getTime()) ? null : parsedValue
   }
 
+  /**
+   * Checks whether a skipped mutation exactly matches the persisted replay row.
+   * Older distinct mutations retain the established successful stale-skip response.
+   * @param {{existingSync: ReturnType<typeof JSON.parse>, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Existing row and incoming mutation.
+   * @returns {boolean} Whether this is a duplicate replay.
+   */
+  isDuplicateReplayMutation({existingSync, mutation}) {
+    if (!existingSync) return false
+
+    const metadata = this.replayPersistedMetadata(existingSync)
+
+    if (metadata) {
+      return metadata.clientMutationId === String(mutation.clientMutationId || mutation.id)
+        && metadata.payloadFingerprint === sha256Hex(mutation.serializedData)
+    }
+
+    const existingClientUpdatedAt = this.existingReplaySyncClientUpdatedAt(existingSync)
+    const existingData = this.replaySyncRecordValue(existingSync, "data")
+    const existingSyncType = this.replaySyncRecordValue(existingSync, "syncType")
+    const serializedExistingData = typeof existingData === "string" ? existingData : JSON.stringify(existingData)
+
+    return existingClientUpdatedAt?.getTime() === mutation.clientUpdatedAt.getTime()
+      && serializedExistingData === mutation.serializedData
+      && existingSyncType === mutation.syncType
+  }
+
+  /**
+   * Reads a model-backed sync-row value through its accessor or plain property.
+   * @param {ReturnType<typeof JSON.parse>} syncRecord - Existing sync row.
+   * @param {string} attributeName - Attribute name.
+   * @returns {ReturnType<typeof JSON.parse>} Stored value.
+   */
+  replaySyncRecordValue(syncRecord, attributeName) {
+    const record = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (syncRecord)
+    const value = record[attributeName]
+
+    return typeof value === "function" ? value.call(syncRecord) : value
+  }
+
+  /**
+   * Reads durable replay acknowledgement metadata from a model-backed sync row.
+   * @param {ReturnType<typeof JSON.parse>} syncRecord - Existing sync row.
+   * @returns {{acknowledgementVersion: string | number | null, clientMutationId: string, payloadFingerprint: string} | null} Persisted metadata.
+   */
+  replayPersistedMetadata(syncRecord) {
+    if (!syncRecord) return null
+
+    return decodeReplayPersistedData(this.replaySyncRecordValue(syncRecord, "data")).metadata
+  }
+
   /**
    * Applies one normalized mutation to domain models.
    *
@@ -638,19 +701,30 @@ export default class SyncEnvelopeReplayService {
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Apply result with the deleted flag.
    */
   async applyRoutedReplayDelete({mutation, resource}) {
-    const record = await resource.findSyncRecord({forDelete: true, mutation})
+    const ModelClass = resource.modelClass()
+    const runDelete = async () => {
+      const record = await resource.findSyncRecord({forDelete: true, mutation})
 
-    if (!record) return {created: false, deleted: false, record: null}
+      if (!record) return {created: false, deleted: false, record: null}
 
-    const releaseServerApply = markServerApply(record)
+      const conflictResult = await this.routedReplayConflictResult({attributes: {}, existingRecord: record, mutation, resource})
 
-    try {
-      await record.destroy()
-    } finally {
-      releaseServerApply()
+      if (conflictResult) return conflictResult
+
+      const releaseServerApply = markServerApply(record)
+
+      try {
+        await record.destroy()
+      } finally {
+        releaseServerApply()
+      }
+
+      return {created: false, deleted: true, record}
     }
 
-    return {created: false, deleted: true, record}
+    if (!this.conflictStrategy) return await runDelete()
+
+    return await ModelClass.withAdvisoryLock(syncReplayConflictLockName({resourceId: mutation.resourceId, resourceType: mutation.resourceType}), runDelete, {dedicatedConnection: true})
   }
 
   /**
@@ -973,11 +1047,22 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Resolves an apply result for stale mutations that should not touch domain models.
-   * @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.
+   * 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.
    * @returns {Promise<ReturnType<typeof JSON.parse>>} Project-specific apply result.
    */
-  async skippedReplayMutation(_args) {
-    return null
+  async skippedReplayMutation({actor, context, existingSync, mutation}) {
+    if (!this.isDuplicateReplayMutation({existingSync, mutation}) || !this.routingConfigured()) return null
+
+    const registration = this.replayResourceRegistration(mutation.resourceType)
+
+    if (!registration) return null
+
+    const resource = await this.buildReplayResource({actor, context, mutation, registration})
+    const record = await resource.findSyncRecord({forDelete: mutation.syncType === "delete", mutation})
+
+    return {created: false, deleted: false, duplicate: true, record}
   }
 
   /**
@@ -1007,6 +1092,18 @@ export default class SyncEnvelopeReplayService {
       }
     }
 
+    if (this.conflictStrategy && shouldApply && mutation.baseVersion !== undefined && applyResult?.record) {
+      const publicPayload = decodeReplayPersistedData(attributes.data).payload
+      const acknowledgementVersion = normalizeConflictValue(applyResult.record.readAttribute(this.conflictStrategy.versionAttribute))
+
+      attributes.data = serializeReplayPersistedData({
+        acknowledgementVersion,
+        clientMutationId: String(mutation.clientMutationId || mutation.id),
+        payload: publicPayload,
+        payloadFingerprint: sha256Hex(mutation.serializedData)
+      })
+    }
+
     if (existingSync) {
       const existingClientUpdatedAt = this.existingReplaySyncClientUpdatedAt(existingSync)
 

package/src/sync/sync-model-change-feed-service.js

@@ -3,6 +3,7 @@
 import VelociousError from "../velocious-error.js"
 
 import {declaredSyncScopeAttributes} from "./sync-scope-attributes.js"
+import {decodeReplayPersistedData} from "./sync-replay-persisted-data.js"
 
 /**
  * Generic cursor-paginated change feed over an app-owned sync/change model.
@@ -243,9 +244,7 @@ export default class SyncModelChangeFeedService {
     const data = this.recordValue(record, "data")
 
     if (data === "" || data === null || data === undefined) return null
-    if (typeof data !== "string") return data
-
-    return JSON.parse(data)
+    return decodeReplayPersistedData(data).payload
   }
 
   /**
@@ -285,4 +284,3 @@ export default class SyncModelChangeFeedService {
     return date.toISOString()
   }
 }
-

package/src/sync/sync-replay-persisted-data.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+const METADATA_KEY = "$velociousReplay"
+const PAYLOAD_KEY = "payload"
+
+/**
+ * Wraps change-feed data with replay acknowledgement metadata in the existing
+ * durable sync-row data column.
+ * @param {{acknowledgementVersion: string | number | null, clientMutationId: string, payload: ReturnType<typeof JSON.parse>, payloadFingerprint: string}} args - Durable replay metadata and public payload.
+ * @returns {string} Serialized durable value.
+ */
+export function serializeReplayPersistedData({acknowledgementVersion, clientMutationId, payload, payloadFingerprint}) {
+  return JSON.stringify({
+    [METADATA_KEY]: {acknowledgementVersion, clientMutationId, payloadFingerprint},
+    [PAYLOAD_KEY]: payload
+  })
+}
+
+/**
+ * Decodes framework-owned replay metadata while leaving ordinary sync data unchanged.
+ * @param {ReturnType<typeof JSON.parse>} value - Parsed or serialized sync-row data.
+ * @returns {{metadata: {acknowledgementVersion: string | number | null, clientMutationId: string, payloadFingerprint: string} | null, payload: ReturnType<typeof JSON.parse>}} Decoded metadata and public payload.
+ */
+export function decodeReplayPersistedData(value) {
+  const parsed = typeof value === "string" ? JSON.parse(value) : value
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {metadata: null, payload: parsed}
+
+  const record = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (parsed)
+  const metadata = record[METADATA_KEY]
+
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata) || !Object.hasOwn(record, PAYLOAD_KEY)) {
+    return {metadata: null, payload: parsed}
+  }
+
+  const metadataRecord = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (metadata)
+
+  if (typeof metadataRecord.clientMutationId !== "string" || typeof metadataRecord.payloadFingerprint !== "string") {
+    return {metadata: null, payload: parsed}
+  }
+
+  return {
+    metadata: {
+      acknowledgementVersion: metadataRecord.acknowledgementVersion,
+      clientMutationId: metadataRecord.clientMutationId,
+      payloadFingerprint: metadataRecord.payloadFingerprint
+    },
+    payload: record[PAYLOAD_KEY]
+  }
+}