velocious 1.0.489 → 1.0.493

package/src/sync/sync-client.js

@@ -0,0 +1,433 @@
+// @ts-check
+
+import {forcedFunction} from "typanic"
+
+import Configuration from "../configuration.js"
+
+import {serializedScopeFromQuery} from "./query-scope.js"
+import SyncApiClient from "./sync-api-client.js"
+import SyncScopeStore from "./sync-scope-store.js"
+import {currentSyncClient, setCurrentSyncClient} from "./sync-client-registry.js"
+
+let clientCounter = 0
+
+/** @type {{create: "afterCreate", update: "afterUpdate", destroy: "afterDestroy"}} */
+const TRACKED_CALLBACK_NAMES = {create: "afterCreate", destroy: "afterDestroy", update: "afterUpdate"}
+
+/**
+ * Declarative client-side sync driver.
+ *
+ * Apps configure resources, transport, auth, and connectivity once; Velocious
+ * owns scope persistence, per-scope cursors, pull paging/apply, local queueing,
+ * and online-gated replay. Declare sync interest from queries:
+ *
+ *     const syncClient = new SyncClient({...})
+ *     syncClient.setCurrent()
+ *     await syncClient.sync(Event.where({partnerId}))
+ */
+export default class SyncClient {
+  /**
+   * Creates a declarative sync client.
+   * @param {import("./sync-client-types.js").SyncClientConfig} config - Sync client configuration.
+   */
+  constructor(config) {
+    if (!config || typeof config !== "object") throw new Error("SyncClient requires a configuration object")
+
+    forcedFunction(config.postChanges, "SyncClient config.postChanges")
+    forcedFunction(config.postReplay, "SyncClient config.postReplay")
+    forcedFunction(config.authenticationToken, "SyncClient config.authenticationToken")
+
+    if (!config.syncModel) throw new Error("SyncClient requires config.syncModel")
+    if (!config.resources || typeof config.resources !== "object" || Object.keys(config.resources).length === 0) {
+      throw new Error("SyncClient requires at least one entry in config.resources")
+    }
+
+    for (const [resourceType, resource] of Object.entries(config.resources)) {
+      if (!resource || typeof resource !== "object" || !resource.modelClass) {
+        throw new Error(`SyncClient resource ${resourceType} must declare a modelClass`)
+      }
+    }
+
+    this.config = config
+    this._clientNumber = ++clientCounter
+    /** @type {import("./sync-scope-store.js").default | null} */
+    this._scopeStore = config.scopeStore || null
+    /** @type {Promise<void> | null} */
+    this._scheduledReplay = null
+    /** @type {Record<string, import("./sync-api-client-types.js").SyncResourceConfig> | null} */
+    this._pullResourceConfigs = null
+    /** @type {Array<{callback: (record: ?) => Promise<void>, callbackName: "afterCreate" | "afterUpdate" | "afterDestroy", modelClass: ?}>} */
+    this._trackedCallbacks = []
+    /** @type {WeakSet<object>} */
+    this._remoteApplyRecords = new WeakSet()
+    this._started = false
+  }
+
+  /**
+   * Registers automatic mutation tracking for every resource with `track` enabled:
+   * local model creates/updates/destroys queue pending sync rows and schedule an
+   * immediate replay attempt, without app-side queue calls.
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this._started) return
+
+    this._started = true
+
+    for (const [resourceType, resourceConfig] of Object.entries(this.config.resources)) {
+      const operations = this.trackedOperations({resourceConfig, resourceType})
+
+      for (const operation of operations) {
+        const callbackName = TRACKED_CALLBACK_NAMES[operation]
+        const callback = this.trackedMutationCallback({operation, resourceConfig})
+
+        resourceConfig.modelClass[callbackName](callback)
+        this._trackedCallbacks.push({callback, callbackName, modelClass: resourceConfig.modelClass})
+      }
+    }
+  }
+
+  /**
+   * Unregisters all tracking callbacks (tests, sign-out, hot reload).
+   * @returns {void}
+   */
+  stop() {
+    for (const {callback, callbackName, modelClass} of this._trackedCallbacks) {
+      modelClass.unregisterLifecycleCallback(callbackName, callback)
+    }
+
+    this._trackedCallbacks = []
+    this._started = false
+  }
+
+  /**
+   * Resolves and validates the tracked operations for a resource config.
+   * @param {{resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig, resourceType: string}} args - Resource config and name.
+   * @returns {Array<"create" | "update" | "destroy">} Tracked operations.
+   */
+  trackedOperations({resourceConfig, resourceType}) {
+    const track = resourceConfig.track
+
+    if (track === undefined || track === false) return []
+    if (track === true) return ["create", "update", "destroy"]
+
+    if (!track || typeof track !== "object" || !Array.isArray(track.operations) || track.operations.length === 0) {
+      throw new Error(`SyncClient resource ${resourceType} track must be true or {operations: [...]}`)
+    }
+
+    for (const operation of track.operations) {
+      if (!(operation in TRACKED_CALLBACK_NAMES)) {
+        throw new Error(`SyncClient resource ${resourceType} track.operations must be create/update/destroy, got: ${String(operation)}`)
+      }
+    }
+
+    return track.operations
+  }
+
+  /**
+   * Builds the lifecycle callback queueing one tracked mutation.
+   * @param {{operation: "create" | "update" | "destroy", resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Operation and resource config.
+   * @returns {(record: ?) => Promise<void>} Lifecycle callback.
+   */
+  trackedMutationCallback({operation, resourceConfig}) {
+    return async (record) => {
+      if (this.isRemoteApply(record)) return
+
+      await SyncApiClient.queueLocalSync({
+        booleanAttributes: resourceConfig.booleanAttributes || [],
+        data: resourceConfig.trackedData ? resourceConfig.trackedData({operation, record}) : undefined,
+        localOnlyAttributes: resourceConfig.localOnlyAttributes || [],
+        resource: record,
+        syncModel: this.config.syncModel,
+        syncType: this.defaultSyncType({operation, record, resourceConfig})
+      })
+
+      this.scheduleReplay()
+    }
+  }
+
+  /**
+   * Whether a record is currently being written by pull-apply (echo suppression).
+   * @param {?} record - Local model record.
+   * @returns {boolean} Whether the record write originates from a remote change.
+   */
+  isRemoteApply(record) {
+    return this._remoteApplyRecords.has(record)
+  }
+
+  /**
+   * Registers this client as the app's current sync client.
+   * @returns {void}
+   */
+  setCurrent() {
+    setCurrentSyncClient(this)
+  }
+
+  /**
+   * Returns the app's current sync client.
+   * @returns {SyncClient} Current sync client.
+   */
+  static current() {
+    return /** @type {SyncClient} */ (currentSyncClient())
+  }
+
+  /**
+   * Declares (or re-activates) a sync scope from a model query and pulls it when online.
+   * @param {import("../database/query/model-class-query.js").default<?>} query - Query declaring the sync scope.
+   * @returns {Promise<{scope: import("./sync-client-types.js").SerializedSyncScope, pulled: import("./sync-api-client-types.js").SyncChangesResult | null}>} Declared scope and pull result (null while offline).
+   */
+  async sync(query) {
+    const scope = serializedScopeFromQuery(query)
+    const scopeStore = this.scopeStore()
+    const scopeRow = await scopeStore.findOrCreateScope(scope)
+
+    if (!scopeRow.cursorPayload && this.config.legacyCursor) {
+      const legacyCursorPayload = await this.config.legacyCursor({scope})
+      const legacyCursor = SyncApiClient.syncCursorFromPayload(legacyCursorPayload)
+
+      if (legacyCursor) await scopeStore.saveCursor(scopeRow, legacyCursor)
+    }
+
+    return {pulled: await this.pull(), scope}
+  }
+
+  /**
+   * Deactivates the sync scope declared by a model query.
+   * @param {import("../database/query/model-class-query.js").default<?>} query - Query whose scope should stop syncing.
+   * @returns {Promise<void>}
+   */
+  async unsync(query) {
+    await this.scopeStore().deactivate(serializedScopeFromQuery(query))
+  }
+
+  /**
+   * Pulls changes for every active scope with per-scope cursors (single-flighted, online-gated).
+   * @returns {Promise<import("./sync-api-client-types.js").SyncChangesResult | null>} Combined pull result, or null while offline.
+   */
+  async pull() {
+    if (!(await this.isOnline())) return null
+
+    /** @type {import("./sync-api-client-types.js").SyncChangesResult | null} */
+    let combinedResult = null
+
+    await SyncApiClient.singleFlight(`velocious-sync-client-pull-${this._clientNumber}`, async () => {
+      const authenticationToken = await this.config.authenticationToken()
+      const scopeStore = this.scopeStore()
+      const pullResourceConfigs = this.pullResourceConfigs()
+      const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => {
+        this._remoteApplyRecords.add(record)
+
+        return () => this._remoteApplyRecords.delete(record)
+      })
+      /**
+       * Applies one pulled change, failing loudly instead of silently skipping unconfigured resources.
+       * @param {import("./sync-api-client-types.js").SyncChangeEnvelope} sync - Pulled change.
+       * @returns {Promise<import("./sync-api-client-types.js").SyncChangeApplyResult>} Apply result.
+       */
+      const applySync = async (sync) => {
+        const resourceType = sync.resourceType()
+
+        if (!resourceType || !pullResourceConfigs[resourceType]) {
+          throw new Error(`No sync resource with pull attributes configured for pulled change: ${String(resourceType)}`)
+        }
+
+        return await applier(sync)
+      }
+      const result = {
+        changed: false,
+        pages: 0,
+        resourceChanged: /** @type {Record<string, boolean>} */ ({}),
+        resourceCounts: /** @type {Record<string, number>} */ ({}),
+        syncedCount: 0
+      }
+
+      for (const scopeRow of await scopeStore.activeScopes()) {
+        const scopeResult = await SyncApiClient.pullChanges({
+          applySync,
+          authenticationToken,
+          batchSize: this.config.batchSize,
+          loadCursor: async () => await scopeStore.loadCursor(scopeRow),
+          postChanges: async (payload) => await this.config.postChanges({
+            ...payload,
+            scope: {conditions: scopeRow.conditions, resourceType: scopeRow.resourceType}
+          }),
+          saveCursor: async (cursor) => await scopeStore.saveCursor(scopeRow, cursor)
+        })
+
+        result.changed ||= scopeResult.changed
+        result.pages += scopeResult.pages
+        result.syncedCount += scopeResult.syncedCount
+
+        for (const [resourceType, count] of Object.entries(scopeResult.resourceCounts)) {
+          result.resourceCounts[resourceType] = (result.resourceCounts[resourceType] || 0) + count
+        }
+        for (const [resourceType, changed] of Object.entries(scopeResult.resourceChanged)) {
+          result.resourceChanged[resourceType] ||= changed
+        }
+      }
+
+      combinedResult = result
+    })
+
+    return combinedResult
+  }
+
+  /**
+   * 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: ?, data?: Record<string, ?>, syncType?: string}} args - Queue args.
+   * @returns {Promise<?>} Pending local sync row.
+   */
+  async queue({data, resource, syncType}) {
+    const resourceConfig = this.resourceConfigFor(resource)
+    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})
+    })
+
+    this.scheduleReplay()
+
+    return syncRow
+  }
+
+  /**
+   * Drains pending local sync rows to the backend (single-flighted, online-gated).
+   * Rows are only marked successful after the backend acknowledges them.
+   * @returns {Promise<void>}
+   */
+  async replayPending() {
+    if (!(await this.isOnline())) return
+
+    await SyncApiClient.singleFlight(`velocious-sync-client-replay-${this._clientNumber}`, async () => {
+      await SyncApiClient.replayLocalSyncs({
+        authenticationToken: await this.config.authenticationToken(),
+        batchSize: this.config.batchSize,
+        postReplay: this.config.postReplay,
+        syncModel: this.config.syncModel
+      })
+    })
+  }
+
+  /**
+   * Schedules a background replay attempt without blocking the caller.
+   * Failures go to config.onError (or rethrow when none is configured).
+   * @returns {void}
+   */
+  scheduleReplay() {
+    this._scheduledReplay = (async () => {
+      try {
+        await this.replayPending()
+      } catch (error) {
+        this.reportError(/** @type {Error} */ (error))
+      }
+    })()
+  }
+
+  /**
+   * Awaits the last scheduled background replay (useful in tests and shutdown flows).
+   * @returns {Promise<void>}
+   */
+  async waitForScheduledReplay() {
+    if (this._scheduledReplay) await this._scheduledReplay
+  }
+
+  /**
+   * Reports a background sync failure.
+   * @param {Error} error - Background failure.
+   * @returns {void}
+   */
+  reportError(error) {
+    if (this.config.onError) {
+      this.config.onError(error)
+      return
+    }
+
+    throw error
+  }
+
+  /**
+   * Resolves connectivity through the configured gate.
+   * @returns {Promise<boolean>} Whether the backend is considered reachable.
+   */
+  async isOnline() {
+    if (!this.config.isOnline) return true
+
+    return (await this.config.isOnline()) !== false
+  }
+
+  /**
+   * Returns the scope store backing declared scopes and cursors.
+   * @returns {import("./sync-scope-store.js").default} Scope store.
+   */
+  scopeStore() {
+    this._scopeStore ||= new SyncScopeStore({configuration: this.config.configuration || Configuration.current()})
+
+    return this._scopeStore
+  }
+
+  /**
+   * Resolves the declared resource config for a local record.
+   * @param {?} resource - Local model record.
+   * @returns {import("./sync-client-types.js").SyncClientResourceConfig} Declared resource config.
+   */
+  resourceConfigFor(resource) {
+    const modelClass = resource?.constructor
+
+    if (typeof modelClass?.getModelName !== "function") {
+      throw new Error(`Sync resources must be model records with a static getModelName(), got: ${String(resource)}`)
+    }
+
+    const resourceType = modelClass.getModelName()
+    const resourceConfig = this.config.resources[resourceType]
+
+    if (!resourceConfig) throw new Error(`No sync resource configured for: ${resourceType}`)
+
+    return resourceConfig
+  }
+
+  /**
+   * Resolves the sync type for a mutation through the resource config.
+   * @param {{operation: "create" | "update" | "destroy", record: ?, resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Mutation args.
+   * @returns {string} Sync type.
+   */
+  defaultSyncType({operation, record, resourceConfig}) {
+    if (resourceConfig.syncType) return resourceConfig.syncType({operation, record})
+    if (operation === "destroy") return "delete"
+
+    return operation
+  }
+
+  /**
+   * Derives the pull-apply resource configs from the declared resources.
+   * @returns {Record<string, import("./sync-api-client-types.js").SyncResourceConfig>} Pull-apply resource configs.
+   */
+  pullResourceConfigs() {
+    this._pullResourceConfigs ||= /** @type {Record<string, import("./sync-api-client-types.js").SyncResourceConfig>} */ (Object.fromEntries(
+      Object.entries(this.config.resources)
+        .filter(([, resource]) => Boolean(resource.attributes))
+        .map(([resourceType, resource]) => [resourceType, {
+          afterApply: resource.afterApply,
+          attributes: /** @type {import("./sync-api-client-types.js").SyncResourceConfig["attributes"]} */ (resource.attributes),
+          enabled: true,
+          findRecord: resource.findRecord,
+          findRecordForDelete: resource.findRecordForDelete,
+          modelClass: resource.modelClass
+        }])
+    ))
+
+    return this._pullResourceConfigs
+  }
+}
+
+/**
+ * Declares a sync scope on the current sync client.
+ * @param {import("../database/query/model-class-query.js").default<?>} query - Query declaring the sync scope.
+ * @returns {Promise<{scope: import("./sync-client-types.js").SerializedSyncScope, pulled: import("./sync-api-client-types.js").SyncChangesResult | null}>} Declared scope and pull result.
+ */
+export async function sync(query) {
+  return await SyncClient.current().sync(query)
+}

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

@@ -1,5 +1,16 @@
 // @ts-check
 
+import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
+
+/**
+ * One declarative broadcast fanned out after a mutation applies.
+ * @typedef {object} SyncReplayBroadcast
+ * @property {string | ((args: Record<string, ?>) => string)} channel - Channel name or resolver.
+ * @property {(args: Record<string, ?>) => Record<string, ?>} broadcastParams - Channel routing params.
+ * @property {(args: Record<string, ?>) => ?} body - Broadcast body.
+ * @property {(args: Record<string, ?>) => boolean} [when] - Optional gate; skipped when it returns false.
+ */
+
 /**
  * Replays client sync envelopes through project supplied authentication,
  * authorization, application, and persistence hooks.
@@ -12,11 +23,60 @@
 export default class SyncEnvelopeReplayService {
   /**
    * Creates a sync envelope replay service.
+   *
+   * When a sync model is given, `findExistingReplaySync` and
+   * `persistReplayMutation` get model-backed default implementations. The sync
+   * model must expose `findBy`/`create` statics plus instance
+   * `assign`/`save`/`clientUpdatedAt` and `advanceServerSequence` (the
+   * change-feed sequence contract), and the actor returned from
+   * `authenticateReplay` must expose an `id()` method.
    * @param {object} [args] - Constructor arguments.
    * @param {{debug?: (...args: Array<unknown>) => void, warn?: (...args: Array<unknown>) => void}} [args.logger] - Logger used for normalization warnings.
+   * @param {?} [args.syncModel] - Sync/change model enabling model-backed default hooks.
+   * @param {string} [args.actorForeignKeyColumn] - Sync model column linking rows to the replay actor.
+   * @param {?} [args.authenticationTokenModel] - Token model enabling the default token-lookup authenticateReplay.
+   * @param {string} [args.authenticationTokenColumn] - Token model column holding the token. Defaults to "token".
+   * @param {string} [args.authenticationTokenParam] - Request param carrying the token. Defaults to "authenticationToken".
+   * @param {Record<string, ((args: Record<string, ?>) => Promise<?>) | ConstructorParameters<typeof SyncReplayUpsertApplier>[0]>} [args.applyHandlers] - Per-resourceType apply handlers (functions or declarative upsert-applier specs) enabling the default applyReplayMutation dispatch.
+   * @param {(args: Record<string, ?>) => Record<string, ?>} [args.persistExtraAttributes] - Extra attributes merged into the model-backed persisted row (e.g. an event scope column).
+   * @param {(args: {mutation: ?, applyResult: ?}) => ?} [args.persistSerializedData] - Overrides the persisted data payload (object results are JSON stringified).
+   * @param {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [args.broadcaster] - Delivers declarative broadcasts. Required when broadcasts are configured.
+   * @param {SyncReplayBroadcast[]} [args.broadcasts] - Broadcasts fanned out by the default afterReplayMutation.
    */
   constructor(args = {}) {
     this.logger = args.logger || console
+    this.syncModel = args.syncModel || null
+    this.actorForeignKeyColumn = args.actorForeignKeyColumn || "authentication_token_id"
+    this.authenticationTokenModel = args.authenticationTokenModel || null
+    this.authenticationTokenColumn = args.authenticationTokenColumn || "token"
+    this.authenticationTokenParam = args.authenticationTokenParam || "authenticationToken"
+    this.persistExtraAttributes = args.persistExtraAttributes || null
+    this.persistSerializedData = args.persistSerializedData || null
+    this.broadcaster = args.broadcaster || null
+    this.broadcasts = args.broadcasts || null
+    this.applyHandlers = args.applyHandlers ? this.builtApplyHandlers(args.applyHandlers) : null
+
+    if (args.actorForeignKeyColumn !== undefined && (typeof args.actorForeignKeyColumn !== "string" || args.actorForeignKeyColumn.length < 1)) {
+      throw new Error(`actorForeignKeyColumn must be a non-blank string, got: ${String(args.actorForeignKeyColumn)}`)
+    }
+    if (this.broadcasts && !this.broadcaster) {
+      throw new Error("SyncEnvelopeReplayService broadcasts require a broadcaster option delivering them")
+    }
+  }
+
+  /**
+   * Wraps declarative apply-handler specs in upsert appliers.
+   * @param {Record<string, ?>} applyHandlers - Raw apply handlers.
+   * @returns {Record<string, (args: Record<string, ?>) => Promise<?>>} Callable handlers by resource type.
+   */
+  builtApplyHandlers(applyHandlers) {
+    return Object.fromEntries(Object.entries(applyHandlers).map(([resourceType, handler]) => {
+      if (typeof handler === "function") return [resourceType, handler]
+
+      const applier = new SyncReplayUpsertApplier(handler)
+
+      return [resourceType, (/** @type {Record<string, ?>} */ applyArgs) => applier.apply(/** @type {?} */ (applyArgs))]
+    }))
   }
 
   /**
@@ -76,11 +136,30 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Authenticates the sync batch actor.
-   * @param {Record<string, ?>} _params - Request params.
+   *
+   * Defaults to a token-model lookup when `authenticationTokenModel` is
+   * configured; otherwise apps override this hook.
+   * @param {Record<string, ?>} params - Request params.
    * @returns {Promise<{authenticated: true, actor: ?} | {authenticated: false, errorCode: string, errorMessage: string}>} Auth result.
    */
-  async authenticateReplay(_params) {
-    throw new Error("SyncEnvelopeReplayService.authenticateReplay must be implemented")
+  async authenticateReplay(params) {
+    if (!this.authenticationTokenModel) {
+      throw new Error("SyncEnvelopeReplayService.authenticateReplay must be implemented (or configure authenticationTokenModel)")
+    }
+
+    const token = params[this.authenticationTokenParam]
+
+    if (!token) {
+      return {authenticated: false, errorCode: "missing-authentication-token", errorMessage: "Missing authentication token"}
+    }
+
+    const actor = await this.authenticationTokenModel.findBy({[this.authenticationTokenColumn]: token})
+
+    if (!actor) {
+      return {authenticated: false, errorCode: "invalid-authentication-token", errorMessage: "Invalid authentication token"}
+    }
+
+    return {actor, authenticated: true}
   }
 
   /**
@@ -178,11 +257,33 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Loads the previously stored sync/change row for stale-client comparison.
-   * @param {{actor: ?, context: Record<string, ?>, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} _args - Actor, batch context, and mutation.
+   *
+   * Defaults to a sync-model lookup by actor and resource identity when a sync
+   * model is configured; otherwise apps override this hook.
+   * @param {{actor: ?, context: Record<string, ?>, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor, batch context, and mutation.
    * @returns {Promise<?>} Existing sync row.
    */
-  async findExistingReplaySync(_args) {
-    return null
+  async findExistingReplaySync({actor, mutation}) {
+    if (!this.syncModel) return null
+
+    return await this.syncModel.findBy({
+      [this.actorForeignKeyColumn]: this.replayActorId(actor),
+      resource_id: mutation.resourceId,
+      resource_type: mutation.resourceType
+    })
+  }
+
+  /**
+   * Resolves the persisted actor id used by model-backed default hooks.
+   * @param {?} actor - Actor returned from authenticateReplay.
+   * @returns {?} Actor id.
+   */
+  replayActorId(actor) {
+    if (!actor || typeof actor !== "object" || typeof actor.id !== "function") {
+      throw new Error("SyncEnvelopeReplayService model-backed defaults require an actor with an id() method from authenticateReplay")
+    }
+
+    return actor.id()
   }
 
   /**
@@ -220,11 +321,20 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Applies one normalized mutation to domain models.
-   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} _args - Actor, batch context, existing sync row, and mutation.
+   *
+   * Defaults to dispatching through the configured apply-handler registry;
+   * mutations without a registered handler fail loudly.
+   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor, batch context, existing sync row, and mutation.
    * @returns {Promise<?>} Project-specific apply result.
    */
-  async applyReplayMutation(_args) {
-    return null
+  async applyReplayMutation(args) {
+    if (!this.applyHandlers) return null
+
+    const applyHandler = this.applyHandlers[args.mutation.resourceType]
+
+    if (!applyHandler) throw new Error(`No sync apply handler registered for: ${args.mutation.resourceType}`)
+
+    return await applyHandler(args)
   }
 
   /**
@@ -238,17 +348,84 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Persists one normalized mutation into the app sync/change store.
-   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} _args - Replay persistence arguments.
+   *
+   * Defaults to a stale-guarded sync-model upsert (with server re-sequencing on
+   * updates) when a sync model is configured; otherwise apps override this hook.
+   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} args - Replay persistence arguments.
    * @returns {Promise<void>}
    */
-  async persistReplayMutation(_args) {}
+  async persistReplayMutation({actor, applyResult, context, existingSync, mutation, shouldApply}) {
+    if (!this.syncModel) return
+
+    const attributes = this.replayPersistAttributes({actor, mutation})
+
+    // Stale replays never applied anything, so the applyResult-driven extension
+    // hooks must not run against the default null skipped result.
+    if (this.persistExtraAttributes && shouldApply) {
+      Object.assign(attributes, this.persistExtraAttributes({actor, applyResult, context, existingSync, mutation, shouldApply}))
+    }
+
+    if (this.persistSerializedData && shouldApply) {
+      const serializedData = this.persistSerializedData({applyResult, mutation})
+
+      if (serializedData !== undefined && serializedData !== null) {
+        attributes.data = typeof serializedData === "string" ? serializedData : JSON.stringify(serializedData)
+      }
+    }
+
+    if (existingSync) {
+      const existingClientUpdatedAt = this.existingReplaySyncClientUpdatedAt(existingSync)
+
+      if (existingClientUpdatedAt && mutation.clientUpdatedAt <= existingClientUpdatedAt) return
+
+      existingSync.assign(attributes)
+      await existingSync.advanceServerSequence()
+      await existingSync.save()
+    } else {
+      await this.syncModel.create(attributes)
+    }
+  }
+
+  /**
+   * Builds the sync-model attributes persisted by the model-backed default.
+   * @param {{actor: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor and mutation.
+   * @returns {Record<string, ?>} Sync row attributes.
+   */
+  replayPersistAttributes({actor, mutation}) {
+    return {
+      [this.actorForeignKeyColumn]: this.replayActorId(actor),
+      client_updated_at: mutation.clientUpdatedAt,
+      data: mutation.serializedData,
+      resource_id: mutation.resourceId,
+      resource_type: mutation.resourceType,
+      sync_type: mutation.syncType
+    }
+  }
 
   /**
    * Runs side effects after a successful mutation replay and persistence.
-   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} _args - Replay side-effect arguments.
+   *
+   * Defaults to fanning the applied result out through the configured
+   * declarative broadcasts.
+   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, applyResult: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, shouldApply: boolean}} args - Replay side-effect arguments.
    * @returns {Promise<void>}
    */
-  async afterReplayMutation(_args) {}
+  async afterReplayMutation(args) {
+    if (!this.broadcasts || !this.broadcaster) return
+    // Stale replays never applied anything - broadcasting their skipped results
+    // would fan out stale side effects (or crash on the default null applyResult).
+    if (!args.shouldApply) return
+
+    for (const broadcast of this.broadcasts) {
+      if (broadcast.when && !broadcast.when(args)) continue
+
+      await this.broadcaster({
+        body: broadcast.body(args),
+        channel: typeof broadcast.channel === "function" ? broadcast.channel(args) : broadcast.channel,
+        params: broadcast.broadcastParams(args)
+      })
+    }
+  }
 }
 
 /**