velocious 1.0.476 → 1.0.477

package/build/configuration-types.js

@@ -348,6 +348,7 @@
  * frontends and peers; `policy` is hashed but intentionally omitted from
  * frontend-safe manifests.
  * @typedef {object} FrontendModelResourceSyncConfiguration
+ * @property {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} [conflictStrategy] - Strategy used when replay detects server/client divergence. Defaults to `optimisticVersion`.
  * @property {boolean} [enabled] - Whether the resource is sync-enabled. Defaults to true when `sync` is configured.
  * @property {string[]} [operations] - Sync operation names such as `index`, `find`, `create`, `update`, custom domain commands, etc.
  * @property {string | number} [policyVersion] - App-controlled policy version used as a stable change signal.
@@ -359,6 +360,7 @@
  * Velocious sync configuration.
  * @typedef {object} VelociousSyncConfiguration
  * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
+ * @property {number} [changeFeedRetentionSize] - Number of accepted server changes retained before clients must refresh from snapshot.
  * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.
  * @property {number} [offlineGrantTtlMs] - Default offline grant TTL in milliseconds. Defaults to 24 hours.
  */
@@ -366,6 +368,7 @@
 /**
  * Frontend-safe normalized sync metadata.
  * @typedef {object} NormalizedFrontendModelResourceSyncConfiguration
+ * @property {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} conflictStrategy - Normalized replay conflict strategy.
  * @property {boolean} enabled - Whether the resource is sync-enabled.
  * @property {string[]} operations - Sorted, duplicate-free sync operation names.
  * @property {string | null} policyVersion - App-controlled policy version, or null.

package/build/configuration.js

@@ -232,6 +232,9 @@ export default class VelociousConfiguration {
     /** Grace period for paused WebSocket sessions before permanent teardown. */
     this._websocketSessionGraceSeconds = 300
 
+    /** Interval (seconds) between server→client heartbeat pings; 0 disables reaping of silent sockets. */
+    this._websocketSessionHeartbeatSeconds = 30
+
     /**
      * Optional wrapper called around every WebSocket-borne request /
      * connection message / channel dispatch. Apps register it here
@@ -407,18 +410,23 @@ export default class VelociousConfiguration {
    */
   _normalizeSyncConfiguration(sync) {
     const deviceCertificateBackendPublicKey = sync?.deviceCertificateBackendPublicKey || null
+    const changeFeedRetentionSize = sync?.changeFeedRetentionSize
     const offlineGrantSigningKeys = sync?.offlineGrantSigningKeys || []
     const offlineGrantTtlMs = sync?.offlineGrantTtlMs
 
     if (deviceCertificateBackendPublicKey !== null && (typeof deviceCertificateBackendPublicKey !== "object" || Array.isArray(deviceCertificateBackendPublicKey))) {
       throw new Error("sync.deviceCertificateBackendPublicKey must be a public JSON Web Key object")
     }
+    if (changeFeedRetentionSize !== undefined && (!Number.isInteger(changeFeedRetentionSize) || changeFeedRetentionSize <= 0)) {
+      throw new Error("sync.changeFeedRetentionSize must be a positive integer")
+    }
     if (!Array.isArray(offlineGrantSigningKeys)) throw new Error("sync.offlineGrantSigningKeys must be an array")
     if (offlineGrantTtlMs !== undefined && (!Number.isInteger(offlineGrantTtlMs) || offlineGrantTtlMs <= 0)) {
       throw new Error("sync.offlineGrantTtlMs must be a positive integer number of milliseconds")
     }
 
     return {
+      changeFeedRetentionSize: changeFeedRetentionSize || 10000,
       deviceCertificateBackendPublicKey,
       offlineGrantSigningKeys: offlineGrantSigningKeys.map((key) => normalizeOfflineGrantSigningKey(key)),
       offlineGrantTtlMs: offlineGrantTtlMs || 24 * 60 * 60 * 1000
@@ -2047,6 +2055,12 @@ export default class VelociousConfiguration {
    */
   getWebsocketSessionGraceSeconds() { return this._websocketSessionGraceSeconds }
 
+  /**
+   * Runs get websocket session heartbeat seconds.
+   * @returns {number} - Interval (seconds) between server→client heartbeat pings; 0 disables reaping.
+   */
+  getWebsocketSessionHeartbeatSeconds() { return this._websocketSessionHeartbeatSeconds }
+
   /**
    * Registers a wrapper invoked around every WS-borne request /
    * connection message / channel dispatch. The wrapper receives the
@@ -2124,6 +2138,16 @@ export default class VelociousConfiguration {
     this._websocketSessionGraceSeconds = seconds
   }
 
+  /**
+   * Runs set websocket session heartbeat seconds.
+   * @param {number} seconds
+   * @returns {void}
+   */
+  setWebsocketSessionHeartbeatSeconds(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) throw new Error(`Invalid heartbeat seconds: ${seconds}`)
+    this._websocketSessionHeartbeatSeconds = seconds
+  }
+
   /**
    * Moves a session into the paused registry and starts the grace
    * timer. When the timer fires, the session's permanent teardown

package/build/frontend-model-controller.js

@@ -7,6 +7,7 @@ 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, 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"
@@ -3594,9 +3595,16 @@ export default class FrontendModelController extends Controller {
 
       try {
         idempotencyKey = mutationIdempotencyKey(/** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation))
-        const response = await this.frontendSyncReplaySignedMutation(signedMutation)
+        const {response, serverChangeFeedError, serverChangeFeedStatus, serverSequence} = await this.frontendSyncReplaySignedMutation(signedMutation)
 
-        results.push({idempotencyKey, response, status: "success"})
+        results.push({
+          idempotencyKey,
+          response,
+          serverChangeFeedError,
+          serverChangeFeedStatus,
+          serverSequence,
+          status: "success"
+        })
       } catch (error) {
         const errorContext = this.frontendModelEndpointErrorContext({
           action: "frontendSyncReplay",
@@ -3647,7 +3655,7 @@ export default class FrontendModelController extends Controller {
   /**
    * Verifies and replays one signed sync mutation.
    * @param {?} signedMutation - Signed mutation envelope.
-   * @returns {Promise<Record<string, ?>>} - Frontend-model command response.
+   * @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()
@@ -3677,9 +3685,6 @@ export default class FrontendModelController extends Controller {
     if (syncResource.policyHash !== mutation.policyHash) {
       throw frontendSyncReplaySafeError(`Sync replay policy hash mismatch for ${mutation.model}`)
     }
-    if (!["create", "update", "destroy"].includes(mutation.operation)) {
-      throw frontendSyncReplaySafeError(`Sync replay operation is not supported yet: ${mutation.operation}`)
-    }
 
     const signedOfflineGrant = this.frontendSyncReplaySignedOfflineGrant(signedMutation)
     const offlineGrant = await this.frontendSyncReplayVerifiedOfflineGrant({
@@ -3690,17 +3695,24 @@ export default class FrontendModelController extends Controller {
     this.frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource})
 
     const commandParams = await this.frontendSyncReplayCommandParams(mutation)
+    const replayCommand = this.frontendSyncReplayCommandForMutation(mutation)
+
+    let response
 
     try {
-      return await this.withFrontendModelParams(commandParams, async () => {
+      response = await this.withFrontendModelParams(commandParams, async () => {
         return await this.withFrontendModelRequestContext(commandParams, this.response(), async () => {
-          return await this.frontendModelCommandPayload(/** @type {"create" | "update" | "destroy"} */ (mutation.operation)) || this.frontendModelErrorPayload("Action halted by beforeAction.")
+          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 {"create" | "update" | "destroy"} */ (mutation.operation),
+        commandType: /** @type {?} */ (replayCommand.commandType),
         error,
         model: mutation.model
       })
@@ -3712,7 +3724,42 @@ export default class FrontendModelController extends Controller {
         model: errorContext.model
       })
 
-      return await this.frontendModelClientErrorPayloadForError(error, errorContext)
+      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
+      }
     }
   }
 
@@ -3788,6 +3835,60 @@ export default class FrontendModelController extends Controller {
     }
   }
 
+  /**
+   * 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.
@@ -3802,7 +3903,24 @@ export default class FrontendModelController extends Controller {
       model: mutation.model
     })
 
-    if (mutation.operation !== "create") {
+    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`)
@@ -3813,6 +3931,36 @@ export default class FrontendModelController extends Controller {
     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.
@@ -3835,6 +3983,215 @@ export default class FrontendModelController extends Controller {
     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.

package/build/frontend-models/resource-definition.js

@@ -288,7 +288,7 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
   const sync = resourceConfiguration.sync
 
   if (sync === undefined || sync === null) return undefined
-  if (sync === false) return {enabled: false, operations: [], policyHash: syncPolicyHash({enabled: false}), policyVersion: null}
+  if (sync === false) return {conflictStrategy: "optimisticVersion", enabled: false, operations: [], policyHash: syncPolicyHash({conflictStrategy: "optimisticVersion", enabled: false}), policyVersion: null}
   if (sync === true) {
     return normalizeFrontendModelResourceSync({
       ...resourceConfiguration,
@@ -299,18 +299,20 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
     throw new Error("Resource sync configuration must be true, false, or an object.")
   }
 
-  const {enabled = true, metadata, operations, policy, policyVersion, ...rest} = /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration} */ (sync)
+  const {conflictStrategy, enabled = true, metadata, operations, policy, policyVersion, ...rest} = /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration} */ (sync)
 
   if (Object.keys(rest).length > 0) {
-    throw new Error(`Unexpected sync keys: ${Object.keys(rest).join(", ")}. Allowed: enabled, metadata, operations, policy, policyVersion`)
+    throw new Error(`Unexpected sync keys: ${Object.keys(rest).join(", ")}. Allowed: conflictStrategy, enabled, metadata, operations, policy, policyVersion`)
   }
   if (enabled !== true && enabled !== false) throw new Error("Resource sync enabled must be true or false when provided.")
 
+  const normalizedConflictStrategy = normalizeSyncConflictStrategy(conflictStrategy)
   const normalizedOperations = normalizeSyncOperations(operations)
   const normalizedMetadata = metadata === undefined ? undefined : deterministicSyncJson({label: "metadata", value: metadata})
   const normalizedPolicy = policy === undefined ? undefined : deterministicSyncJson({label: "policy", value: policy})
   const normalizedPolicyVersion = policyVersion === undefined || policyVersion === null ? null : String(policyVersion)
   const hashInput = {
+    conflictStrategy: normalizedConflictStrategy,
     enabled,
     metadata: normalizedMetadata,
     modelName: resourceConfiguration.modelName || null,
@@ -320,6 +322,7 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
   }
   /** @type {import("../configuration-types.js").NormalizedFrontendModelResourceSyncConfiguration} */
   const normalized = {
+    conflictStrategy: normalizedConflictStrategy,
     enabled,
     operations: normalizedOperations,
     policyHash: syncPolicyHash(hashInput),
@@ -331,6 +334,20 @@ function normalizeFrontendModelResourceSync(resourceConfiguration) {
   return normalized
 }
 
+/**
+ * Normalizes the sync conflict strategy for replay clients/servers.
+ * @param {unknown} conflictStrategy - Raw strategy.
+ * @returns {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} - Normalized strategy.
+ */
+function normalizeSyncConflictStrategy(conflictStrategy) {
+  if (conflictStrategy === undefined || conflictStrategy === null) return "optimisticVersion"
+  if (["optimisticVersion", "serverWins", "lastWriterWins", "fieldThreeWay", "appendOnly"].includes(String(conflictStrategy))) {
+    return /** @type {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} */ (conflictStrategy)
+  }
+
+  throw new Error(`Unknown resource sync conflictStrategy: ${String(conflictStrategy)}`)
+}
+
 /**
  * Normalizes sync operations into a stable, duplicate-free list.
  * @param {unknown} operations - Raw operations value.