velocious 1.0.475 → 1.0.477

package/build/frontend-model-controller.js

@@ -6,7 +6,9 @@ import FrontendModelBaseResource from "./frontend-model-resource/base-resource.j
 import Response from "./http-server/client/response.js"
 import {frontendModelResourcesWithBuiltInsForBackendProject} from "./frontend-models/built-in-resources.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject, frontendModelSyncManifestForBackendProjects} from "./frontend-models/resource-definition.js"
-import {createOfflineGrantFromBootstrap} from "./sync/offline-grant.js"
+import {createOfflineGrantFromBootstrap, verifyOfflineGrant} from "./sync/offline-grant.js"
+import {serverChangeFeedStoreForConfiguration} from "./sync/server-change-feed.js"
+import {mutationIdempotencyKey, verifySignedMutation} from "./sync/device-identity.js"
 import {FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
 import {assignSafeProperty, deserializeFrontendModelTransportValue, isBackendModelInstance, serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
 import {requestDetails} from "./error-reporting/request-details.js"
@@ -172,6 +174,19 @@ const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")
 const frontendModelClientSafeErrorMessage = "Request failed."
 const frontendModelDebugErrorEnvironments = new Set(["development", "test"])
 
+/**
+ * Builds a client-safe sync replay validation error.
+ * @param {string} message - Client-safe validation message.
+ * @param {unknown} [cause] - Original cause.
+ * @returns {VelociousError} - Client-safe replay error.
+ */
+function frontendSyncReplaySafeError(message, cause) {
+  return VelociousError.safe(message, {
+    cause,
+    code: "frontend_sync_replay_error"
+  })
+}
+
 /**
  * Runs frontend model query metadata.
  * @param {import("./database/query/model-class-query.js").default} query - Query instance.
@@ -3561,6 +3576,622 @@ export default class FrontendModelController extends Controller {
     throw new Error("Expected sync bootstrap current user")
   }
 
+  /**
+   * Runs frontend sync replay.
+   * @returns {Promise<void>} - Sync replay response with per-mutation results.
+   */
+  async frontendSyncReplay() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const signedMutations = this.frontendSyncReplaySignedMutations(params)
+    const results = []
+
+    for (const signedMutation of signedMutations) {
+      let idempotencyKey = null
+
+      try {
+        idempotencyKey = mutationIdempotencyKey(/** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation))
+        const {response, serverChangeFeedError, serverChangeFeedStatus, serverSequence} = await this.frontendSyncReplaySignedMutation(signedMutation)
+
+        results.push({
+          idempotencyKey,
+          response,
+          serverChangeFeedError,
+          serverChangeFeedStatus,
+          serverSequence,
+          status: "success"
+        })
+      } catch (error) {
+        const errorContext = this.frontendModelEndpointErrorContext({
+          action: "frontendSyncReplay",
+          commandType: signedMutation && typeof signedMutation === "object" && "mutation" in signedMutation
+            ? /** @type {{mutation?: {operation?: ?}}} */ (signedMutation).mutation?.operation
+            : undefined,
+          error,
+          model: signedMutation && typeof signedMutation === "object" && "mutation" in signedMutation
+            ? /** @type {{mutation?: {model?: ?}}} */ (signedMutation).mutation?.model
+            : undefined
+        })
+
+        await this.frontendModelLogEndpointError({
+          action: errorContext.action,
+          commandType: errorContext.commandType,
+          error,
+          model: errorContext.model
+        })
+
+        results.push({
+          idempotencyKey,
+          response: await this.frontendModelClientErrorPayloadForError(error, errorContext),
+          status: "error"
+        })
+      }
+    }
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+        results,
+        status: "success"
+      }, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Resolves signed replay mutations from request params.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {Array<?>} - Signed mutation envelopes.
+   */
+  frontendSyncReplaySignedMutations(params) {
+    if (Array.isArray(params.mutations)) return params.mutations
+    if (params.mutation) return [params.mutation]
+
+    throw new Error("Expected sync replay mutation or mutations")
+  }
+
+  /**
+   * Verifies and replays one signed sync mutation.
+   * @param {?} signedMutation - Signed mutation envelope.
+   * @returns {Promise<{response: Record<string, ?>, serverChangeFeedError?: Record<string, ?>, serverChangeFeedStatus?: "error", serverSequence: number | null}>} - Frontend-model command response and appended server sequence.
+   */
+  async frontendSyncReplaySignedMutation(signedMutation) {
+    const configuration = this.getConfiguration()
+    const syncConfiguration = configuration.getSyncConfiguration()
+    const backendPublicKey = syncConfiguration.deviceCertificateBackendPublicKey
+
+    if (!backendPublicKey) throw frontendSyncReplaySafeError("sync.deviceCertificateBackendPublicKey is required for sync replay")
+
+    let mutation
+
+    try {
+      mutation = await verifySignedMutation({
+        backendPublicKey,
+        signedMutation: /** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation)
+      })
+    } catch (error) {
+      throw frontendSyncReplaySafeError(error instanceof Error ? error.message : String(error), error)
+    }
+
+    const syncManifest = frontendModelSyncManifestForBackendProjects(configuration.getBackendProjects())
+    const syncResource = syncManifest[mutation.model]
+
+    if (!syncResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
+    if (!syncResource.operations.includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay operation is not enabled for ${mutation.model}: ${mutation.operation}`)
+    }
+    if (syncResource.policyHash !== mutation.policyHash) {
+      throw frontendSyncReplaySafeError(`Sync replay policy hash mismatch for ${mutation.model}`)
+    }
+
+    const signedOfflineGrant = this.frontendSyncReplaySignedOfflineGrant(signedMutation)
+    const offlineGrant = await this.frontendSyncReplayVerifiedOfflineGrant({
+      signedOfflineGrant,
+      signingKeys: syncConfiguration.offlineGrantSigningKeys
+    })
+
+    this.frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource})
+
+    const commandParams = await this.frontendSyncReplayCommandParams(mutation)
+    const replayCommand = this.frontendSyncReplayCommandForMutation(mutation)
+
+    let response
+
+    try {
+      response = await this.withFrontendModelParams(commandParams, async () => {
+        return await this.withFrontendModelRequestContext(commandParams, this.response(), async () => {
+          if (["create", "update", "destroy"].includes(mutation.operation)) {
+            return await this.frontendModelCommandPayload(/** @type {"create" | "update" | "destroy"} */ (mutation.operation)) || this.frontendModelErrorPayload("Action halted by beforeAction.")
+          }
+
+          return await this.frontendSyncReplayCustomCommandPayload({mutation, replayCommand}) || this.frontendModelErrorPayload("Action halted by beforeAction.")
+        })
+      })
+    } catch (error) {
+      const errorContext = this.frontendModelEndpointErrorContext({
+        action: "frontendSyncReplay",
+        commandType: /** @type {?} */ (replayCommand.commandType),
+        error,
+        model: mutation.model
+      })
+
+      await this.frontendModelLogEndpointError({
+        action: errorContext.action,
+        commandType: errorContext.commandType,
+        error,
+        model: errorContext.model
+      })
+
+      return {
+        response: await this.frontendModelClientErrorPayloadForError(error, errorContext),
+        serverSequence: null
+      }
+    }
+
+    try {
+      const serverSequence = await this.frontendSyncAppendServerChange({
+        idempotencyKey: mutationIdempotencyKey(/** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation)),
+        mutation,
+        offlineGrant,
+        response
+      })
+
+      return {response, serverSequence}
+    } catch (error) {
+      const errorContext = this.frontendModelEndpointErrorContext({
+        action: "frontendSyncReplay",
+        commandType: /** @type {?} */ (replayCommand.commandType),
+        error,
+        model: mutation.model
+      })
+
+      await this.frontendModelLogEndpointError({
+        action: errorContext.action,
+        commandType: errorContext.commandType,
+        error,
+        model: errorContext.model
+      })
+
+      return {
+        response,
+        serverChangeFeedError: await this.frontendModelClientErrorPayloadForError(error, errorContext),
+        serverChangeFeedStatus: "error",
+        serverSequence: null
+      }
+    }
+  }
+
+  /**
+   * Resolves the signed offline grant carried by a replay request.
+   * @param {?} signedMutation - Signed mutation envelope.
+   * @returns {?} - Signed offline grant envelope.
+   */
+  frontendSyncReplaySignedOfflineGrant(signedMutation) {
+    if (!signedMutation || typeof signedMutation !== "object" || Array.isArray(signedMutation)) {
+      throw frontendSyncReplaySafeError("Expected sync replay signed offline grant")
+    }
+
+    const signedMutationRecord = /** @type {Record<string, ?>} */ (signedMutation)
+    const signedOfflineGrant = signedMutationRecord.signedOfflineGrant || signedMutationRecord.offlineGrant || signedMutationRecord.signedGrant
+
+    if (!signedOfflineGrant) throw frontendSyncReplaySafeError("Expected sync replay signed offline grant")
+
+    return signedOfflineGrant
+  }
+
+  /**
+   * Verifies a sync replay signed offline grant.
+   * @param {object} args - Arguments.
+   * @param {?} args.signedOfflineGrant - Signed offline grant envelope.
+   * @param {import("./sync/offline-grant.js").OfflineGrantSigningKey[]} args.signingKeys - Available signing keys.
+   * @returns {Promise<import("./sync/offline-grant.js").OfflineGrant>} - Verified offline grant.
+   */
+  async frontendSyncReplayVerifiedOfflineGrant({signedOfflineGrant, signingKeys}) {
+    try {
+      return await verifyOfflineGrant({
+        now: new Date(),
+        signedGrant: /** @type {import("./sync/offline-grant.js").SignedOfflineGrant} */ (signedOfflineGrant),
+        signingKeys
+      })
+    } catch (error) {
+      throw frontendSyncReplaySafeError(error instanceof Error ? error.message : String(error), error)
+    }
+  }
+
+  /**
+   * Validates that a verified offline grant authorizes a replayed mutation.
+   * @param {object} args - Arguments.
+   * @param {import("./sync/device-identity.js").SyncMutation} args.mutation - Verified mutation.
+   * @param {import("./sync/offline-grant.js").OfflineGrant} args.offlineGrant - Verified grant.
+   * @param {Record<string, ?>} args.syncResource - Current sync resource entry.
+   * @returns {void} - Throws when unauthorized.
+   */
+  frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource}) {
+    if (offlineGrant.grantId !== mutation.offlineGrantId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant does not match mutation")
+    }
+    if (offlineGrant.deviceId !== mutation.actorDeviceId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant device does not match mutation")
+    }
+    if (offlineGrant.userId !== mutation.actorUserId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant user does not match mutation")
+    }
+
+    const grantResource = /** @type {Record<string, ?> | undefined} */ (offlineGrant.resources[mutation.model])
+    const grantOperations = Array.isArray(grantResource?.operations) ? grantResource.operations : []
+    const grantPolicyHash = grantResource?.policyHash
+
+    if (!grantResource || grantResource.enabled !== true) throw frontendSyncReplaySafeError(`Sync replay offline grant does not authorize ${mutation.model}`)
+    if (!grantOperations.includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay offline grant does not authorize ${mutation.model}: ${mutation.operation}`)
+    }
+    if (grantPolicyHash !== mutation.policyHash || grantPolicyHash !== syncResource.policyHash) {
+      throw frontendSyncReplaySafeError(`Sync replay offline grant policy hash mismatch for ${mutation.model}`)
+    }
+    if (!offlineGrant.scopes || typeof offlineGrant.scopes !== "object" || Array.isArray(offlineGrant.scopes)) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant scopes are invalid")
+    }
+  }
+
+  /**
+   * Replays a verified custom sync mutation through the resource command API.
+   * @param {object} args - Arguments.
+   * @param {import("./sync/device-identity.js").SyncMutation} args.mutation - Verified mutation.
+   * @param {{commandType: string, methodName?: string, scope?: "collection" | "member"}} args.replayCommand - Resolved replay command metadata.
+   * @returns {Promise<Record<string, ?>>} - Command response payload.
+   */
+  async frontendSyncReplayCustomCommandPayload({mutation, replayCommand}) {
+    if (typeof replayCommand.methodName !== "string" || replayCommand.methodName.length < 1) {
+      throw frontendSyncReplaySafeError(`Sync replay command is not registered for ${mutation.model}: ${mutation.operation}`)
+    }
+
+    const frontendModelResource = this.getConfiguration().getBackendProjects()
+      .map((backendProject) => this.frontendModelResourceConfigurationForBackendProjectModelName({backendProject, modelName: mutation.model}))
+      .find((resourceConfiguration) => resourceConfiguration)
+
+    if (!frontendModelResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
+
+    const resource = new frontendModelResource.resourceClass({
+      ability: this.currentAbility(),
+      controller: this,
+      context: {
+        ...(this.currentAbility()?.getContext() || {}),
+        params: this.frontendModelParams(),
+        request: this.request()
+      },
+      locals: this.currentAbility()?.getLocals() || {},
+      modelClass: this.frontendModelResourceModelClass(frontendModelResource),
+      modelName: frontendModelResource.modelName,
+      params: this.frontendModelParams(),
+      resourceConfiguration: frontendModelResource.resourceConfiguration
+    })
+    const command = resource.resourceMethod(replayCommand.methodName)
+
+    if (!command) {
+      return this.frontendModelErrorPayload(`Missing frontend-model custom command '${replayCommand.methodName}'.`)
+    }
+
+    const commandArguments = /** @type {Record<string, ?>} */ (mutation.payload && typeof mutation.payload === "object" && !Array.isArray(mutation.payload) ? mutation.payload : {})
+    const responsePayload = await command.method.call(command.resource, commandArguments)
+
+    if (!responsePayload || typeof responsePayload !== "object") {
+      return {status: "success"}
+    }
+
+    return /** @type {Record<string, ?>} */ (
+      await this.autoSerializeFrontendModelsInPayload(
+        responsePayload,
+        /** @type {{serialize: (model: ?, action: string) => Promise<Record<string, ?>>}} */ (command.resource),
+        replayCommand.methodName
+      )
+    )
+  }
+
+  /**
+   * Builds frontend-model command params for a verified replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {Promise<Record<string, ?>>} - Frontend-model command params.
+   */
+  async frontendSyncReplayCommandParams(mutation) {
+    const payload = mutation.payload && typeof mutation.payload === "object" && !Array.isArray(mutation.payload) ? mutation.payload : {}
+    const {attributes, primaryKeyValue} = await this.frontendSyncReplayCommandAttributes(mutation)
+    const commandParams = /** @type {Record<string, ?>} */ ({
+      ...payload,
+      attributes,
+      model: mutation.model
+    })
+
+    if (["create", "update", "destroy"].includes(mutation.operation)) {
+      if (mutation.operation !== "create") {
+        const id = commandParams.id || commandParams.recordId || primaryKeyValue
+
+        if (typeof id !== "string" && typeof id !== "number") throw frontendSyncReplaySafeError(`Sync replay ${mutation.operation} requires an id`)
+
+        commandParams.id = id
+      }
+
+      return commandParams
+    }
+
+    const replayCommand = this.frontendSyncReplayCommandForMutation(mutation)
+
+    commandParams.frontendModelCustomCommandMethodName = replayCommand.methodName
+    commandParams.frontendModelCustomCommandScope = replayCommand.scope
+
+    if (replayCommand.scope === "member") {
+      const id = commandParams.id || commandParams.recordId || primaryKeyValue
+
+      if (typeof id !== "string" && typeof id !== "number") throw frontendSyncReplaySafeError(`Sync replay ${mutation.operation} requires an id`)
+
+      commandParams.id = id
+    }
+
+    return commandParams
+  }
+
+  /**
+   * Resolves the frontend-model command used for a verified replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {{commandType: string, methodName?: string, scope?: "collection" | "member"}} - Command metadata.
+   */
+  frontendSyncReplayCommandForMutation(mutation) {
+    if (["create", "update", "destroy"].includes(mutation.operation)) {
+      return {commandType: mutation.operation}
+    }
+
+    const frontendModelResource = this.getConfiguration().getBackendProjects()
+      .map((backendProject) => this.frontendModelResourceConfigurationForBackendProjectModelName({backendProject, modelName: mutation.model}))
+      .find((resourceConfiguration) => resourceConfiguration)
+
+    if (!frontendModelResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
+
+    const commandName = typeof mutation.command === "string" && mutation.command.length > 0 ? mutation.command : mutation.operation
+    const resourceConfiguration = frontendModelResource.resourceConfiguration
+
+    if (Object.prototype.hasOwnProperty.call(resourceConfiguration.collectionCommands, commandName)) {
+      return {commandType: commandName, methodName: commandName, scope: "collection"}
+    }
+
+    if (Object.prototype.hasOwnProperty.call(resourceConfiguration.memberCommands, commandName)) {
+      return {commandType: commandName, methodName: commandName, scope: "member"}
+    }
+
+    throw frontendSyncReplaySafeError(`Sync replay command is not registered for ${mutation.model}: ${commandName}`)
+  }
+
+  /**
+   * Resolves command attributes and primary key from a replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {Promise<{attributes: Record<string, ?>, primaryKeyValue: string | number | undefined}>} - Command attributes and primary key value.
+   */
+  async frontendSyncReplayCommandAttributes(mutation) {
+    const attributes = /** @type {Record<string, ?>} */ ({...(mutation.attributes || {})})
+    const frontendModelResource = this.getConfiguration().getBackendProjects()
+      .map((backendProject) => this.frontendModelResourceConfigurationForBackendProjectModelName({backendProject, modelName: mutation.model}))
+      .find((resourceConfiguration) => resourceConfiguration)
+
+    if (!frontendModelResource) return {attributes, primaryKeyValue: undefined}
+
+    const primaryKey = typeof frontendModelResource.resourceConfiguration.primaryKey === "string" ? frontendModelResource.resourceConfiguration.primaryKey : "id"
+    const primaryKeyAttribute = attributes[primaryKey]
+    const primaryKeyValue = typeof primaryKeyAttribute === "string" || typeof primaryKeyAttribute === "number" ? primaryKeyAttribute : undefined
+
+    if (primaryKeyValue !== undefined && mutation.operation !== "create") delete attributes[primaryKey]
+
+    return {attributes, primaryKeyValue}
+  }
+
+  /**
+   * Appends a successfully replayed mutation to the server change feed.
+   * @param {object} args - Arguments.
+   * @param {string | null} args.idempotencyKey - Mutation idempotency key.
+   * @param {import("./sync/device-identity.js").SyncMutation} args.mutation - Verified mutation.
+   * @param {import("./sync/offline-grant.js").OfflineGrant} args.offlineGrant - Verified offline grant.
+   * @param {Record<string, ?>} args.response - Replay command response.
+   * @returns {Promise<number | null>} - Assigned server sequence, or null when no change was appended.
+   */
+  async frontendSyncAppendServerChange({idempotencyKey, mutation, offlineGrant, response}) {
+    if (response.status !== "success") return null
+
+    const store = serverChangeFeedStoreForConfiguration(this.getConfiguration())
+    const responseSyncChanges = Array.isArray(response.syncChanges) ? response.syncChanges : []
+    const syncChanges = responseSyncChanges.length > 0 ? responseSyncChanges : [{
+      attributes: mutation.attributes,
+      model: mutation.model,
+      operation: mutation.operation,
+      payload: mutation.payload
+    }]
+    let serverSequence = /** @type {number | null} */ (null)
+
+    for (const syncChange of syncChanges) {
+      if (!syncChange || typeof syncChange !== "object" || Array.isArray(syncChange)) continue
+
+      const change = /** @type {Record<string, ?>} */ (syncChange)
+      const payload = /** @type {Record<string, ?>} */ (change.payload && typeof change.payload === "object" && !Array.isArray(change.payload) ? change.payload : {})
+      const attributes = /** @type {Record<string, ?>} */ (change.attributes && typeof change.attributes === "object" && !Array.isArray(change.attributes) ? change.attributes : {})
+      const model = typeof change.model === "string" && change.model.length > 0 ? change.model : mutation.model
+      const operation = typeof change.operation === "string" && change.operation.length > 0 ? change.operation : mutation.operation
+      const rawRecordId = change.recordId ?? payload.id ?? payload.recordId ?? attributes.id ?? null
+      const recordId = rawRecordId === null || rawRecordId === undefined ? null : String(rawRecordId)
+      const appendedChange = await store.append({
+        actorDeviceId: mutation.actorDeviceId,
+        actorUserId: mutation.actorUserId,
+        attributes,
+        idempotencyKey,
+        model,
+        operation,
+        payload,
+        recordId,
+        response,
+        scope: offlineGrant.scopes
+      })
+
+      serverSequence = appendedChange.serverSequence
+    }
+
+    return serverSequence
+  }
+
+  /**
+   * Verifies the signed offline grant used to scope sync read endpoints.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {Promise<import("./sync/offline-grant.js").OfflineGrant>} - Verified offline grant.
+   */
+  async frontendSyncRequestVerifiedOfflineGrant(params) {
+    const signedOfflineGrant = this.frontendSyncReplaySignedOfflineGrant(params)
+
+    return await this.frontendSyncReplayVerifiedOfflineGrant({
+      signedOfflineGrant,
+      signingKeys: this.getConfiguration().getSyncConfiguration().offlineGrantSigningKeys
+    })
+  }
+
+  /**
+   * Runs frontend sync change feed.
+   * @returns {Promise<void>} - Sync change-feed response.
+   */
+  async frontendSyncChangeFeed() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const offlineGrant = await this.frontendSyncRequestVerifiedOfflineGrant(params)
+    const afterSequence = this.frontendSyncChangeFeedAfterSequence(params)
+    const store = serverChangeFeedStoreForConfiguration(this.getConfiguration())
+    const limit = this.frontendSyncChangeFeedLimit(params)
+    const currentServerSequence = await store.latestSequence()
+    const serverSequence = this.frontendSyncChangeFeedUpToSequence(params, currentServerSequence)
+    const page = await store.changesAfter({afterSequence, limit, scope: offlineGrant.scopes, upToSequence: serverSequence})
+
+    if (page.snapshotRequired) {
+      await this.render({
+        json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+          changes: [],
+          oldestSequence: page.oldestSequence,
+          requestedAfterSequence: afterSequence,
+          serverSequence,
+          snapshot: await this.frontendSyncSnapshotPayload({scope: offlineGrant.scopes, serverSequence}),
+          status: "snapshot_required"
+        }, this.transportSerializationOptions()))
+      })
+      return
+    }
+
+    const changes = page.changes
+    const includeSnapshot = params.snapshot === true || params.includeSnapshot === true || afterSequence === 0
+    const snapshot = includeSnapshot ? await this.frontendSyncSnapshotPayload({scope: offlineGrant.scopes, serverSequence}) : undefined
+
+    const payload = /** @type {Record<string, ?>} */ ({
+      changes,
+      hasMore: page.hasMore,
+      nextSequence: page.nextSequence,
+      serverSequence,
+      status: "success",
+      upToSequence: page.upToSequence
+    })
+
+    if (snapshot) payload.snapshot = snapshot
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Resolves sync change-feed cursor.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {number} - Exclusive lower-bound sequence.
+   */
+  frontendSyncChangeFeedAfterSequence(params) {
+    const afterSequence = params.afterSequence ?? params.cursor ?? 0
+
+    if (typeof afterSequence === "number" && Number.isInteger(afterSequence) && afterSequence >= 0) return afterSequence
+    if (typeof afterSequence === "string" && /^\d+$/.test(afterSequence)) return Number(afterSequence)
+
+    throw new Error("Expected sync change-feed afterSequence")
+  }
+
+  /**
+   * Resolves sync change-feed page limit.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {number} - Page limit.
+   */
+  frontendSyncChangeFeedLimit(params) {
+    const limit = params.limit ?? params.pageSize ?? 100
+
+    if (typeof limit === "number" && Number.isInteger(limit) && limit > 0) return limit
+    if (typeof limit === "string" && /^\d+$/.test(limit)) return Number(limit)
+
+    throw new Error("Expected sync change-feed positive limit")
+  }
+
+  /**
+   * Resolves sync change-feed stable high-water mark.
+   * @param {Record<string, ?>} params - Request params.
+   * @param {number} currentServerSequence - Current latest server sequence.
+   * @returns {number} - Inclusive upper-bound sequence.
+   */
+  frontendSyncChangeFeedUpToSequence(params, currentServerSequence) {
+    const upToSequence = params.upToSequence ?? params.serverSequence ?? currentServerSequence
+
+    if (typeof upToSequence === "number" && Number.isInteger(upToSequence) && upToSequence >= 0) return Math.min(upToSequence, currentServerSequence)
+    if (typeof upToSequence === "string" && /^\d+$/.test(upToSequence)) return Math.min(Number(upToSequence), currentServerSequence)
+
+    throw new Error("Expected sync change-feed upToSequence")
+  }
+
+  /**
+   * Runs frontend sync snapshot endpoint.
+   * @returns {Promise<void>} - Sync snapshot response.
+   */
+  async frontendSyncSnapshot() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const offlineGrant = await this.frontendSyncRequestVerifiedOfflineGrant(params)
+    const store = serverChangeFeedStoreForConfiguration(this.getConfiguration())
+    const serverSequence = await store.latestSequence()
+    const snapshot = await this.frontendSyncSnapshotPayload({scope: offlineGrant.scopes, serverSequence})
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+        snapshot,
+        status: "success"
+      }, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Builds a snapshot of sync-enabled frontend model resources at a stable server sequence.
+   * @param {object} args - Arguments.
+   * @param {number} args.serverSequence - Snapshot sequence.
+   * @param {Record<string, ?>} [args.scope] - Caller sync scope.
+   * @returns {Promise<{resources: Record<string, ?>, serverSequence: number}>} - Snapshot payload.
+   */
+  async frontendSyncSnapshotPayload({scope, serverSequence}) {
+    const syncManifest = frontendModelSyncManifestForBackendProjects(this.getConfiguration().getBackendProjects())
+    const resources = /** @type {Record<string, ?>} */ ({})
+
+    for (const modelName of Object.keys(syncManifest).sort()) {
+      const commandParams = {...(scope || {}), model: modelName}
+
+      resources[modelName] = await this.withFrontendModelParams(commandParams, async () => {
+        return await this.withFrontendModelRequestContext(commandParams, this.response(), async () => {
+          return await this.frontendModelCommandPayload("index") || this.frontendModelErrorPayload("Action halted by beforeAction.")
+        })
+      })
+    }
+
+    return {resources, serverSequence}
+  }
+
   /**
    * Runs frontend api.
    * @returns {Promise<void>} - Shared frontend model API action with batch support.

package/build/frontend-models/base.js

@@ -62,7 +62,11 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  */
 /**
  * Defines this typedef.
- * @typedef {{enabled: boolean, operations: string[], policyHash: string, policyVersion: string | null, metadata?: FrontendModelSyncMetadata}} FrontendModelSyncConfig
+ * @typedef {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} FrontendModelSyncConflictStrategy
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{enabled: boolean, operations: string[], policyHash: string, policyVersion: string | null, conflictStrategy?: FrontendModelSyncConflictStrategy, metadata?: FrontendModelSyncMetadata}} FrontendModelSyncConfig
  */
 /**
  * Defines this typedef.