velocious 1.0.489 → 1.0.492

package/build/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/build/sync/sync-envelope-replay-service.js

@@ -12,11 +12,26 @@
 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.
    */
   constructor(args = {}) {
     this.logger = args.logger || console
+    this.syncModel = args.syncModel || null
+    this.actorForeignKeyColumn = args.actorForeignKeyColumn || "authentication_token_id"
+
+    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)}`)
+    }
   }
 
   /**
@@ -178,11 +193,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()
   }
 
   /**
@@ -238,10 +275,45 @@ 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, existingSync, mutation}) {
+    if (!this.syncModel) return
+
+    const attributes = this.replayPersistAttributes({actor, mutation})
+
+    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.

package/build/sync/sync-resource-base.js

@@ -0,0 +1,143 @@
+// @ts-check
+
+import {forcedNonBlankStringParam} from "typanic"
+
+import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
+
+/**
+ * Optional client-declared sync scope carried on a changes request.
+ * @typedef {object} SerializedChangesScope
+ * @property {Record<string, ?>} conditions - Plain attribute conditions from the client query.
+ * @property {string} resourceType - Client resource/model name the scope was declared for.
+ */
+
+/**
+ * Base resource for Velocious sync endpoints.
+ *
+ * Velocious owns the changes/replay orchestration (scope parsing, feed paging,
+ * replay delegation, response shape) while apps subclass and only declare
+ * authorization, feed scoping, and their replay service.
+ * @template {typeof import("../database/record/index.js").default} [TModelClass=typeof import("../database/record/index.js").default]
+ * @augments {FrontendModelBaseResource<TModelClass>}
+ */
+export default class SyncResourceBase extends FrontendModelBaseResource {
+  /**
+   * Returns a stable change-feed page after app authorization.
+   * @returns {Promise<Record<string, ?>>} Change-feed page result.
+   */
+  async changes() {
+    const params = this.params()
+    const scope = this.changesScope(params)
+
+    await this.authorizeChanges({params, scope})
+
+    return await this.changeFeedService({params, scope}).changes()
+  }
+
+  /**
+   * Replays client sync envelopes through the app replay service.
+   * @returns {Promise<Record<string, ?>>} Replay result with per-sync states.
+   */
+  async replay() {
+    const result = await this.buildReplayService().replay(this.params())
+
+    if (result.status === "error") return result
+
+    return {status: "success", syncs: result.syncs}
+  }
+
+  /**
+   * Parses the optional client-declared scope from request params.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {SerializedChangesScope | null} Parsed scope, or null when the client sent none.
+   */
+  changesScope(params) {
+    const scope = params.scope
+
+    if (scope === undefined || scope === null) return null
+
+    if (typeof scope !== "object" || Array.isArray(scope)) {
+      throw new Error(`Sync changes scope must be an object, got: ${String(scope)}`)
+    }
+
+    const scopeParams = /** @type {Record<string, ?>} */ (scope)
+    const resourceType = forcedNonBlankStringParam(scopeParams, "resourceType")
+    const conditions = scopeParams.conditions
+
+    if (!conditions || typeof conditions !== "object" || Array.isArray(conditions)) {
+      throw new Error(`Sync changes scope.conditions must be an object, got: ${String(conditions)}`)
+    }
+
+    return {conditions: /** @type {Record<string, ?>} */ (conditions), resourceType}
+  }
+
+  /**
+   * Builds the change-feed service serving this changes request.
+   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null}} args - Request params and parsed scope.
+   * @returns {{changes: () => Promise<Record<string, ?>>}} Change-feed service.
+   */
+  changeFeedService({params, scope}) {
+    return new SyncModelChangeFeedService({
+      modelClass: this.syncModelClass(),
+      params,
+      scopeQuery: ({query}) => this.scopeChangesQuery({params, query, scope})
+    })
+  }
+
+  /**
+   * Builds the app replay service handling this replay request.
+   * @returns {import("./sync-envelope-replay-service.js").default} Replay service instance.
+   */
+  buildReplayService() {
+    const ReplayServiceClass = this.replayServiceClass()
+
+    return new ReplayServiceClass(this.replayServiceArgs())
+  }
+
+  /**
+   * Returns constructor args for the app replay service.
+   * @returns {Record<string, ?>} Replay service constructor args.
+   */
+  replayServiceArgs() {
+    return {}
+  }
+
+  /**
+   * Returns the sync model class backing the change feed.
+   * @returns {typeof import("../database/record/index.js").default} Sync model class.
+   */
+  syncModelClass() {
+    const modelClass = /** @type {typeof SyncResourceBase} */ (this.constructor).ModelClass
+
+    if (!modelClass) throw new Error(`${this.constructor.name} must define static ModelClass`)
+
+    return modelClass
+  }
+
+  /**
+   * Authorizes the current context for reading the requested changes.
+   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null}} _args - Request params and parsed scope.
+   * @returns {Promise<void>} Resolves when access is allowed; throws otherwise.
+   */
+  async authorizeChanges(_args) {
+    throw new Error("SyncResourceBase#authorizeChanges must be implemented")
+  }
+
+  /**
+   * Applies app visibility scoping onto the change-feed query.
+   * @param {{params: Record<string, ?>, query: import("../database/query/model-class-query.js").default, scope: SerializedChangesScope | null}} _args - Request params, feed query, and parsed scope.
+   * @returns {void}
+   */
+  scopeChangesQuery(_args) {
+    throw new Error("SyncResourceBase#scopeChangesQuery must be implemented")
+  }
+
+  /**
+   * Returns the app replay service class handling replay mutations.
+   * @returns {typeof import("./sync-envelope-replay-service.js").default} Replay service class.
+   */
+  replayServiceClass() {
+    throw new Error("SyncResourceBase#replayServiceClass must be implemented")
+  }
+}