velocious 1.0.700 → 1.0.702

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

@@ -27,6 +27,7 @@ const RESOURCE_STATIC_CONFIG_KEYS = new Set([
   "ModelClass",
   "primaryKey",
   "quickSearchColumns",
+  "quickSearchNumericColumns",
   "relationships",
   "ReplayServiceClass",
   "server",
@@ -168,6 +169,8 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
     "memberCommands",
     "modelName",
     "primaryKey",
+    "quickSearchColumns",
+    "quickSearchNumericColumns",
     "relationships",
     "server",
     "sync"
@@ -180,6 +183,8 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
 
   const normalizedCommands = normalizeFrontendModelResourceCommands(resourceConfiguration)
   const sync = normalizeFrontendModelResourceSync(resourceConfiguration)
+  const quickSearchColumns = normalizeFrontendModelQuickSearchColumns(resourceConfiguration.quickSearchColumns, "quickSearchColumns")
+  const quickSearchNumericColumns = normalizeFrontendModelQuickSearchColumns(resourceConfiguration.quickSearchNumericColumns, "quickSearchNumericColumns")
 
   return {
     ...resourceConfiguration,
@@ -192,6 +197,8 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
     // generator uses it to type each custom command method.
     commandMetadata: normalizedCommands.commandMetadata,
     memberCommands: normalizedCommands.memberCommands,
+    quickSearchColumns,
+    quickSearchNumericColumns,
     sync
   }
 }
@@ -518,6 +525,46 @@ function normalizeSyncOperations(operations) {
   return [...new Set(normalized)].sort()
 }
 
+/**
+ * Normalizes declarative quick-search column entries into a stable list.
+ * Each entry is a plain column-name string or a `{path, column}` object whose
+ * path is a relationship path from the root model.
+ * @param {unknown} columns - Raw quick-search column declarations.
+ * @param {string} label - Config key label for error messages.
+ * @returns {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn> | null} - Normalized columns, or null when undeclared.
+ */
+function normalizeFrontendModelQuickSearchColumns(columns, label) {
+  if (columns === undefined || columns === null) return null
+
+  if (!Array.isArray(columns)) throw new Error(`Resource ${label} must be an array of column names or {path, column} objects.`)
+
+  return columns.map((entry) => {
+    if (typeof entry === "string") {
+      if (entry.length < 1) throw new Error(`Resource ${label} entries must be non-empty column names.`)
+
+      return {column: entry}
+    }
+
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`Resource ${label} entries must be column names or {path, column} objects, got: ${JSON.stringify(entry)}`)
+    }
+
+    const entryRecord = /** @type {Record<string, unknown>} */ (entry)
+    const column = entryRecord.column
+    const path = entryRecord.path
+
+    if (typeof column !== "string" || column.length < 1) throw new Error(`Resource ${label} entries require a non-empty column name.`)
+
+    if (path === undefined || path === null) return {column}
+
+    if (!Array.isArray(path) || path.some((pathSegment) => typeof pathSegment !== "string" || pathSegment.length < 1)) {
+      throw new Error(`Resource ${label} entry paths must be arrays of non-empty relationship names.`)
+    }
+
+    return {column, path: [...path]}
+  })
+}
+
 /**
  * Builds a deterministic policy hash.
  * @param {unknown} value - Hash input.

package/src/sync/local-mutation-log.js

@@ -173,11 +173,17 @@ export default class LocalMutationLog {
 
   /**
    * Replaces the mutation payload of a still-pending record. Used when an
-   * acknowledged predecessor supplies the authoritative base for its successor.
-   * @param {{id: string, mutation: import("./device-identity.js").SyncMutation}} args - Record and replacement mutation.
+   * acknowledged predecessor supplies the authoritative base for its successor
+   * and when an offline session re-signs a pending record under a refreshed
+   * grant (pass the new `signedMutation` envelope together with the mutation).
+   * @param {{id: string, mutation: import("./device-identity.js").SyncMutation, signedMutation?: import("./device-identity.js").SignedSyncMutation}} args - Record and replacement mutation.
    * @returns {Promise<LocalMutationLogRecord>} Updated record.
    */
-  async updateMutation({id, mutation}) {
+  async updateMutation({id, mutation, signedMutation}) {
+    if (signedMutation !== undefined && stableJsonStringify(signedMutation.mutation) !== stableJsonStringify(mutation)) {
+      throw new Error("signedMutation must match the mutation payload it signs")
+    }
+
     return await withStorageKeyLock(this.storageKey, async () => {
       const rawRecord = await this.storage.record(this.storageKey, id)
 
@@ -188,6 +194,7 @@ export default class LocalMutationLog {
       if (!PENDING_STATUSES.has(record.status)) throw new Error(`Cannot update mutation for ${record.status} local mutation '${id}'`)
 
       record.mutation = normalizeMutation(mutation)
+      if (signedMutation !== undefined) record.signedMutation = /** @type {import("./device-identity.js").SignedSyncMutation} */ (JSON.parse(JSON.stringify(signedMutation)))
       record.updatedAt = this.currentTimestamp()
       await this.storage.updateRecord(this.storageKey, cloneRecord(record))
 

package/src/sync/peer-mutation-bundle.js

@@ -11,6 +11,12 @@ import {createSignedMutation, mutationIdempotencyKey, verifySignedMutation} from
  */
 /**
  * One peer mutation bundle entry.
+ * @typedef {object} PeerMutationBundleImportResult
+ * @property {Array<{clientMutationId: string, idempotencyKey: string, localRecordId: string}>} imported - Entries appended to the local log.
+ * @property {Array<{errorMessage: string, index: number}>} rejected - Entries that failed verification.
+ * @property {Array<{clientMutationId: string, idempotencyKey: string, localRecordId: string, reason: "duplicate"}>} skipped - Entries already present by idempotency key.
+ */
+/**
  * @typedef {object} PeerMutationBundleEntry
  * @property {string} [localRecordId] - Exporting device's local mutation record id.
  * @property {number} [localSequence] - Exporting device's local mutation sequence.

package/src/sync/sync-api-client.js

@@ -29,13 +29,14 @@ export default class SyncApiClient {
    * @param {string | number | null} args.baseVersion - Authoritative version observed before the local mutation.
    * @param {import("./sync-client-types.js").SyncClientConflictTrackingConfig} args.conflictTracking - Durable tracking configuration.
    * @param {Record<string, unknown>} args.data - Backend-safe mutation attributes.
+   * @param {import("./sync-offline-session.js").default} [args.offlineSession] - Active long-offline session: the mutation identity (actor ids, grant id, policy hash) is supplied by the session and the appended record carries the device-signed envelope.
    * @param {"create" | "update" | "destroy"} args.operation - Local operation.
    * @param {ReturnType<typeof JSON.parse>} args.resource - Local resource.
    * @param {string} args.resourceType - Resource type.
    * @param {string} args.syncType - Wire operation.
    * @returns {Promise<import("./local-mutation-log.js").LocalMutationLogRecord>} Appended intent.
    */
-  static async queueConflictTrackedSync({baseVersion, conflictTracking, data, operation, resource, resourceType, syncType}) {
+  static async queueConflictTrackedSync({baseVersion, conflictTracking, data, offlineSession, operation, resource, resourceType, syncType}) {
     const resourceId = String(scalarModelPrimaryKeyValue(resource.id(), `Conflict-tracked sync for ${resourceType}`))
     const records = await conflictTracking.mutationLog.records()
     const predecessor = records
@@ -46,20 +47,40 @@ export default class SyncApiClient {
     const predecessorTime = predecessor ? new Date(predecessor.mutation.occurredAt).getTime() : Number.NEGATIVE_INFINITY
     const occurredAt = new Date(Math.max(now.getTime(), predecessorTime + 1)).toISOString()
 
+    const dependencies = predecessor ? [{clientMutationId: predecessor.mutation.clientMutationId, model: resourceType}] : []
+    const attributes = /** @type {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} */ (data)
+
+    if (offlineSession) {
+      // Long-offline queueing: the session supplies the rotating identity
+      // (actor ids, live grant id, current policy hash) and signs the intent
+      // with the device key so it can replay without a live session.
+      const signedMutation = await offlineSession.signMutation({
+        attributes,
+        baseVersion,
+        clientMutationId,
+        model: resourceType,
+        occurredAt,
+        operation,
+        payload: {resourceId, syncType}
+      })
+
+      return await conflictTracking.mutationLog.append({dependencies, mutation: signedMutation.mutation, signedMutation})
+    }
+
     return await conflictTracking.mutationLog.append({
-      dependencies: predecessor ? [{clientMutationId: predecessor.mutation.clientMutationId, model: resourceType}] : [],
+      dependencies,
       mutation: {
-        actorDeviceId: conflictTracking.actorDeviceId,
-        actorUserId: conflictTracking.actorUserId,
-        attributes: /** @type {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} */ (data),
+        actorDeviceId: await resolveConflictTrackingIdentityValue({conflictTracking, key: "actorDeviceId", resourceType}),
+        actorUserId: await resolveConflictTrackingIdentityValue({conflictTracking, key: "actorUserId", resourceType}),
+        attributes,
         baseVersion,
         clientMutationId,
         model: resourceType,
         occurredAt,
-        offlineGrantId: conflictTracking.offlineGrantId,
+        offlineGrantId: await resolveConflictTrackingIdentityValue({conflictTracking, key: "offlineGrantId", resourceType}),
         operation,
         payload: {resourceId, syncType},
-        policyHash: conflictTracking.policyHash
+        policyHash: await resolveConflictTrackingIdentityValue({conflictTracking, key: "policyHash", resourceType})
       }
     })
   }
@@ -938,3 +959,28 @@ function throwIfSyncAborted(signal) {
 
   throw signal.reason instanceof Error ? signal.reason : new Error("Sync operation aborted")
 }
+
+/**
+ * Resolves one conflict-tracking identity field at queue time: a static string
+ * or a function (sync or async) resolving the current value. Grants and policy
+ * hashes rotate at runtime, so declarations may resolve them per mutation.
+ * @param {{conflictTracking: import("./sync-client-types.js").SyncClientConflictTrackingConfig, key: "actorDeviceId" | "actorUserId" | "offlineGrantId" | "policyHash", resourceType: string}} args - Resolution args.
+ * @returns {Promise<string>} - Resolved non-empty identity value.
+ */
+async function resolveConflictTrackingIdentityValue({conflictTracking, key, resourceType}) {
+  const value = conflictTracking[key]
+
+  if (typeof value === "function") {
+    const resolved = await value()
+
+    if (typeof resolved !== "string" || resolved.length === 0) {
+      throw new Error(`${resourceType} conflictTracking.${key} resolved to an empty value`)
+    }
+
+    return resolved
+  }
+
+  if (typeof value === "string" && value.length > 0) return value
+
+  throw new Error(`${resourceType} conflictTracking.${key} must be a non-empty string or a function resolving one (or start an offline session)`)
+}

package/src/sync/sync-client-types.js

@@ -21,13 +21,13 @@
  * Durable optimistic-version tracking configuration. Identity/grant fields are
  * retained in the shared LocalMutationLog mutation shape used by offline sync.
  * @typedef {object} SyncClientConflictTrackingConfig
- * @property {string} actorDeviceId - Stable device identity.
- * @property {string} actorUserId - Stable user identity.
+ * @property {string | (() => string | Promise<string>)} [actorDeviceId] - Stable device identity, or a function resolving it at queue time. When a `sync.client.offline` session is configured, the session supplies it and the declaration may omit it.
+ * @property {string | (() => string | Promise<string>)} [actorUserId] - Stable user identity, or a function resolving it at queue time. When a `sync.client.offline` session is configured, the session supplies it and the declaration may omit it.
  * @property {() => string} clientMutationId - Durable idempotency-id generator.
  * @property {import("./local-mutation-log.js").default} mutationLog - Existing durable mutation log.
  * @property {() => Date} [now] - Mutation clock.
- * @property {string} offlineGrantId - Grant identifier retained with intent.
- * @property {string} policyHash - Policy hash retained with intent.
+ * @property {string | (() => string | Promise<string>)} [offlineGrantId] - Grant identifier retained with intent, or a function resolving it at queue time (grants rotate at runtime). When a `sync.client.offline` session is configured, the session supplies it and the declaration may omit it.
+ * @property {string | (() => string | Promise<string>)} [policyHash] - Policy hash retained with intent, or a function resolving it at queue time (policy hashes rotate with the server policy). When a `sync.client.offline` session is configured, the session supplies it and the declaration may omit it.
  * @property {string} [versionAttribute] - Authoritative version attribute; defaults to updatedAt when present.
  */
 
@@ -128,6 +128,8 @@
  * @property {(args: {scope: SerializedSyncScope}) => string | null | Promise<string | null>} [legacyCursor] - Seeds a newly declared scope's cursor (e.g. from a pre-scope cursor store) so devices don't re-pull everything.
  * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
  * @property {(payload: import("./sync-api-client-types.js").SyncChangesRequest & {scope: SerializedSyncScope}, options?: {signal?: AbortSignal}) => Promise<import("./sync-api-client-types.js").SyncChangesResponse>} postChanges - Posts one changes request.
+ * @property {import("../configuration-types.js").NormalizedVelociousSyncClientOfflineConfiguration} [offline] - Normalized long-offline session configuration from `sync.client.offline`.
+ * @property {(path: string, payload: Record<string, ReturnType<typeof JSON.parse>>, options?: {signal?: AbortSignal}) => Promise<ReturnType<typeof JSON.parse>>} offlinePost - Path-selecting POSTer over the configured transport for the offline session's bootstrap/replay endpoints.
  * @property {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}, options?: {signal?: AbortSignal}) => Promise<import("./sync-api-client-types.js").SyncReplayResponse>} postReplay - Posts one replay request.
  * @property {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
  * @property {import("../remote-request-context.js").RemoteRequestContext} requestContext - Immutable scalar context captured for this client.

package/src/sync/sync-client.js

@@ -10,6 +10,7 @@ import VelociousWebsocketClient from "../http-client/websocket-client.js"
 
 import {serializedScopeFromQuery} from "./query-scope.js"
 import SyncApiClient from "./sync-api-client.js"
+import SyncOfflineSession from "./sync-offline-session.js"
 import SyncRealtimeBridge from "./sync-realtime-bridge.js"
 import SyncScopeStore from "./sync-scope-store.js"
 import {currentSyncClient, setCurrentSyncClient} from "./sync-client-registry.js"
@@ -121,7 +122,7 @@ export default class SyncClient {
       const metadataModelClass = tenantHandle
         ? tenantHandle.metadataModelClass({databaseIdentifier: /** @type {string} */ (databaseIdentifier), modelClass})
         : modelClass
-      const resourceConfig = resourceConfigFromSyncDeclaration({declaration: modelClass.sync, metadataModelClass, modelClass, resourceType})
+      const resourceConfig = resourceConfigFromSyncDeclaration({declaration: modelClass.sync, metadataModelClass, modelClass, offlineConfigured: Boolean(clientConfiguration.offline), resourceType})
 
       if (databaseIdentity && resourceConfig.conflictTracking) {
         resourceConfig.conflictTracking = {
@@ -153,6 +154,8 @@ export default class SyncClient {
       isOnline: clientConfiguration.isOnline,
       legacyCursor,
       onError: clientConfiguration.onError,
+      offline: clientConfiguration.offline,
+      offlinePost: transportPathPoster({requestContext: capturedRequestContext, transport: clientConfiguration.transport}),
       postChanges: transportPoster({path: `${clientConfiguration.mountPath}/changes`, requestContext: capturedRequestContext, transport: clientConfiguration.transport}),
       postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, requestContext: capturedRequestContext, transport: clientConfiguration.transport}),
       realtime: clientConfiguration.realtime,
@@ -170,6 +173,8 @@ export default class SyncClient {
       : null
     /** @type {SyncRealtimeBridge | null} */
     this._realtimeBridge = null
+    /** @type {SyncOfflineSession | null} */
+    this._offlineSession = null
     /** @type {import("./sync-client-types.js").SyncClientSharedConnection | null | undefined} Shared app-lifetime websocket connection (undefined until first resolved, null when none is configured). */
     this._syncConnection = undefined
     /** @type {Promise<void> | null} */
@@ -1089,6 +1094,7 @@ export default class SyncClient {
           baseVersion: baseVersion === undefined ? this.baseVersionFor({operation, record: resource, resourceConfig}) : baseVersion,
           conflictTracking: resourceConfig.conflictTracking,
           data: queuedData,
+          offlineSession: this.config.offline ? this.offlineSession() : undefined,
           operation,
           resource,
           resourceType: resource.constructor.getModelName(),
@@ -1137,19 +1143,28 @@ export default class SyncClient {
 
     await SyncApiClient.singleFlight(`velocious-sync-client-replay-${this._clientNumber}`, async () => await this.withTenantOperation(async (operation) => {
       this._throwIfLifecycleAborted(signal)
-      for (const [resourceType, resourceConfig] of Object.entries(this.config.resources)) {
-        if (!resourceConfig.conflictTracking) continue
 
-        await SyncApiClient.replayConflictTrackedSyncs({
-          applyConflict: async ({record, result}) => await this.applyConflictReplayResult({record, result, resourceType}),
-          authenticationToken: await this.config.authenticationToken(),
-          batchSize: this.config.batchSize,
-          conflictTracking: resourceConfig.conflictTracking,
-          postReplay: this.config.postReplay,
-          remoteGeneration: (identity) => this._remoteGenerations.get(identity) || 0,
-          resourceType,
-          signal
-        })
+      if (this.config.offline) {
+        // Long-offline session configured: the signed offline session owns the
+        // conflict-tracked mutation logs, so the background drain replays them
+        // through the signed replay endpoint instead of the legacy unsigned
+        // one. One owner per log — never both.
+        await this._replayOfflinePending({signal})
+      } else {
+        for (const [resourceType, resourceConfig] of Object.entries(this.config.resources)) {
+          if (!resourceConfig.conflictTracking) continue
+
+          await SyncApiClient.replayConflictTrackedSyncs({
+            applyConflict: async ({record, result}) => await this.applyConflictReplayResult({record, result, resourceType}),
+            authenticationToken: await this.config.authenticationToken(),
+            batchSize: this.config.batchSize,
+            conflictTracking: resourceConfig.conflictTracking,
+            postReplay: this.config.postReplay,
+            remoteGeneration: (identity) => this._remoteGenerations.get(identity) || 0,
+            resourceType,
+            signal
+          })
+        }
       }
 
       this._throwIfLifecycleAborted(signal)
@@ -1256,6 +1271,203 @@ export default class SyncClient {
     })
   }
 
+  /**
+   * Returns the framework-owned long-offline session built from
+   * `sync.client.offline`, creating it on first use. Fails when the offline
+   * configuration block is missing.
+   * @returns {SyncOfflineSession} - The client's offline session.
+   */
+  offlineSession() {
+    if (!this.config.offline) {
+      throw new Error("SyncClient has no sync.client.offline configuration - configure deviceIdentityStorage, enrollDevice, and grantScopes to use the long-offline session")
+    }
+
+    if (!this._offlineSession) {
+      this._offlineSession = new SyncOfflineSession({
+        authenticationToken: this.config.authenticationToken,
+        config: this.config.offline,
+        mutationLogs: this.offlineMutationLogs(),
+        post: this.config.offlinePost
+      })
+    }
+
+    return this._offlineSession
+  }
+
+  /**
+   * Collects the durable mutation logs the offline session signs, replays,
+   * re-signs, and exports: the configured `sync.client.offline.mutationLog`
+   * when given, plus every conflict-tracking log declared by the synced models.
+   * @returns {Array<import("./local-mutation-log.js").default>} - Session mutation logs.
+   */
+  offlineMutationLogs() {
+    /** @type {Array<import("./local-mutation-log.js").default>} */
+    const logs = []
+
+    if (this.config.offline?.mutationLog) logs.push(this.config.offline.mutationLog)
+
+    for (const resourceConfig of Object.values(this.config.resources)) {
+      const mutationLog = resourceConfig.conflictTracking?.mutationLog
+
+      if (!mutationLog) continue
+      if (logs.some((log) => log === mutationLog || log.storageKey === mutationLog.storageKey)) continue
+
+      logs.push(mutationLog)
+    }
+
+    if (logs.length === 0) throw new Error("SyncClient offline session found no durable mutation log - declare conflictTracking on a synced model or configure sync.client.offline.mutationLog")
+
+    return logs
+  }
+
+  /**
+   * Starts the long-offline session: resolves the device signing identity
+   * (generating and enrolling a key pair when the app-owned storage has none)
+   * and bootstraps a live offline grant through the built-in
+   * `/frontend-models/sync/bootstrap` endpoint. Idempotent.
+   * @returns {Promise<import("./sync-offline-session.js").SyncOfflineSessionSummary>} - Session summary (actor ids, live grant id, expiry).
+   */
+  async startOfflineSession() {
+    return await this._runLifecycleWork(async (signal) => {
+      this._throwIfLifecycleAborted(signal)
+
+      const summary = await this.offlineSession().start()
+
+      this._throwIfLifecycleAborted(signal)
+
+      return summary
+    })
+  }
+
+  /**
+   * Stops the long-offline session. The device identity and retained grants
+   * stay in the app-owned durable storage; pending mutations stay in the
+   * durable mutation logs and replay with the grant they were signed under.
+   * @returns {Promise<void>} - Resolves after the session is stopped.
+   */
+  async stopOfflineSession() {
+    if (!this._offlineSession) return
+
+    await this._offlineSession.stop()
+  }
+
+  /**
+   * Bootstraps a fresh offline grant and re-signs this device's pending
+   * mutations under it (the replay idempotency key is grant-id-free, so
+   * re-signing never duplicates an intent).
+   * @returns {Promise<import("./sync-offline-session.js").SyncOfflineSessionSummary>} - Refreshed session summary.
+   */
+  async refreshOfflineGrant() {
+    return await this._runLifecycleWork(async (signal) => {
+      this._throwIfLifecycleAborted(signal)
+
+      const summary = await this.offlineSession().refreshGrant()
+
+      this._throwIfLifecycleAborted(signal)
+
+      return summary
+    })
+  }
+
+  /**
+   * Drains the durable mutation logs through the built-in signed replay
+   * endpoint (`/frontend-models/sync/replay`): ensures a live grant (refreshing
+   * an expired one), batches pending signed mutations with the signed grant
+   * each was signed under, and maps per-mutation results back onto the log
+   * records as synced/conflict/rejected. Structured conflicts stay reachable
+   * through the existing conflict contract (`syncResult.conflict` on the record
+   * and `resolveConflict(...)`).
+   * @param {object} [options] - Replay options.
+   * @param {number} [options.batchSize] - Max signed mutations per request.
+   * @returns {Promise<import("./sync-offline-session.js").SyncOfflineReplayResult>} - Mapped replay result.
+   */
+  async replayOfflinePending(options = {}) {
+    return await this._runLifecycleWork(async (signal) => await this._replayOfflinePending({...options, signal}))
+  }
+
+  /**
+   * Signed replay implementation bound to one lifecycle generation.
+   * @param {object} [options] - Replay options.
+   * @param {number} [options.batchSize] - Max signed mutations per request.
+   * @param {AbortSignal} [options.signal] - Lifecycle cancellation signal.
+   * @returns {Promise<import("./sync-offline-session.js").SyncOfflineReplayResult>} - Mapped replay result.
+   */
+  async _replayOfflinePending(options = {}) {
+    const {signal, ...replayOptions} = options
+    const lifecycleSignal = signal ?? this._lifecycleAbortController.signal
+
+    this._throwIfLifecycleAborted(lifecycleSignal)
+
+    const result = await this.offlineSession().replayPending({...replayOptions, signal: lifecycleSignal})
+
+    this._throwIfLifecycleAborted(lifecycleSignal)
+
+    for (const entry of result.results) {
+      if (entry.status !== "conflict" || !entry.serverResult) continue
+
+      await this.applyOfflineConflictReplayResult(entry)
+    }
+
+    return result
+  }
+
+  /**
+   * Applies the authoritative server version carried by a signed replay
+   * conflict result through the same conflict contract the online replay uses.
+   * @param {{mutation: import("./device-identity.js").SyncMutation, serverResult: Record<string, ReturnType<typeof JSON.parse>> | null, status: string}} entry - Mapped replay result.
+   * @returns {Promise<void>} - Resolves after the conflict server version is applied.
+   */
+  async applyOfflineConflictReplayResult(entry) {
+    if (!entry.serverResult) return
+
+    const response = entry.serverResult.response
+
+    if (!response || typeof response !== "object" || Array.isArray(response)) return
+
+    const conflict = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (response).conflict
+
+    if (!conflict || !Object.hasOwn(conflict, "serverModel")) return
+
+    await this.applyConflictReplayResult({
+      record: /** @type {import("./local-mutation-log.js").LocalMutationLogRecord} */ ({mutation: {payload: entry.mutation.payload}}),
+      resourceType: entry.mutation.model,
+      result: /** @type {import("./sync-api-client-types.js").SyncReplayItem} */ ({conflict})
+    })
+  }
+
+  /**
+   * Exports the durable non-terminal mutations of the offline session's logs
+   * as one signed peer bundle for device-to-device transfer.
+   * @param {object} [options] - Export options.
+   * @param {import("./local-mutation-log.js").LocalMutationStatus[]} [options.statuses] - Statuses to export.
+   * @param {() => Date} [options.now] - Export clock.
+   * @returns {Promise<import("./peer-mutation-bundle.js").PeerMutationBundle>} - Signed peer bundle.
+   */
+  async exportPeerBundle(options = {}) {
+    return await this._runLifecycleWork(async (signal) => {
+      this._throwIfLifecycleAborted(signal)
+
+      return await this.offlineSession().exportBundle(options)
+    })
+  }
+
+  /**
+   * Imports a peer bundle into the local mutation log: every entry is verified
+   * against the configured backend public key before it is appended, and
+   * entries already present by idempotency key are skipped as duplicates.
+   * @param {object} args - Import args.
+   * @param {import("./peer-mutation-bundle.js").PeerMutationBundle} args.bundle - Peer bundle to import.
+   * @param {import("./local-mutation-log.js").default} [args.mutationLog] - Target log. Defaults to the session's first log.
+   * @returns {Promise<import("./peer-mutation-bundle.js").PeerMutationBundleImportResult>} - Import result (imported/rejected/skipped).
+   */
+  async importPeerBundle({bundle, mutationLog}) {
+    return await this._runLifecycleWork(async (signal) => {
+      this._throwIfLifecycleAborted(signal)
+
+      return await this.offlineSession().importBundle({bundle, mutationLog})
+    })
+  }
+
   /**
    * Records an authoritative remote observation so an in-flight acknowledgement
    * cannot rebase a successor across that observation.
@@ -1605,10 +1817,10 @@ function safeConflictVersion(value) {
 /**
  * Builds one resource config from a model's `static sync` declaration plus its
  * derived column metadata.
- * @param {{declaration: import("./sync-client-types.js").ModelSyncDeclaration, metadataModelClass: ReturnType<typeof JSON.parse>, modelClass: ReturnType<typeof JSON.parse>, resourceType: string}} args - Declaration args.
+ * @param {{declaration: import("./sync-client-types.js").ModelSyncDeclaration, metadataModelClass: ReturnType<typeof JSON.parse>, modelClass: ReturnType<typeof JSON.parse>, offlineConfigured?: boolean, resourceType: string}} args - Declaration args.
  * @returns {import("./sync-client-types.js").SyncClientResourceConfig} Derived resource config.
  */
-function resourceConfigFromSyncDeclaration({declaration, metadataModelClass, modelClass, resourceType}) {
+function resourceConfigFromSyncDeclaration({declaration, metadataModelClass, modelClass, offlineConfigured = false, resourceType}) {
   const normalizedDeclaration = declaration === true ? {} : declaration
 
   if (!normalizedDeclaration || typeof normalizedDeclaration !== "object" || Array.isArray(normalizedDeclaration)) {
@@ -1632,7 +1844,7 @@ function resourceConfigFromSyncDeclaration({declaration, metadataModelClass, mod
 
   const derived = derivedSyncAttributes({modelClass: metadataModelClass, resourceType})
 
-  if (conflictTracking) validateConflictTracking({conflictTracking, derived, resourceType})
+  if (conflictTracking) validateConflictTracking({conflictTracking, derived, offlineConfigured, resourceType})
 
   return {
     afterApply,
@@ -1656,19 +1868,26 @@ function resourceConfigFromSyncDeclaration({declaration, metadataModelClass, mod
 
 /**
  * Validates one resource's durable conflict-tracking declaration.
- * @param {{conflictTracking: import("./sync-client-types.js").SyncClientConflictTrackingConfig, derived: {booleanAttributes: string[], localOnlyAttributes: string[]}, resourceType: string}} args - Validation args.
+ * @param {{conflictTracking: import("./sync-client-types.js").SyncClientConflictTrackingConfig, derived: {booleanAttributes: string[], localOnlyAttributes: string[]}, offlineConfigured: boolean, resourceType: string}} args - Validation args.
  * @returns {void}
  */
-function validateConflictTracking({conflictTracking, derived, resourceType}) {
-  const requiredStrings = {
+function validateConflictTracking({conflictTracking, derived, offlineConfigured, resourceType}) {
+  const identityFields = {
     actorDeviceId: conflictTracking.actorDeviceId,
     actorUserId: conflictTracking.actorUserId,
     offlineGrantId: conflictTracking.offlineGrantId,
     policyHash: conflictTracking.policyHash
   }
 
-  for (const [key, value] of Object.entries(requiredStrings)) {
-    if (typeof value !== "string" || value.length === 0) throw new Error(`${resourceType} conflictTracking.${key} must be a non-empty string`)
+  for (const [key, value] of Object.entries(identityFields)) {
+    // Grants and policy hashes rotate at runtime: a declaration may provide a
+    // static string, a function resolving the value at queue time, or omit the
+    // key entirely when a `sync.client.offline` session supplies it.
+    if (value === undefined && offlineConfigured) continue
+    if (typeof value === "function") continue
+    if (typeof value !== "string" || value.length === 0) {
+      throw new Error(`${resourceType} conflictTracking.${key} must be a non-empty string, a function resolving one, or omitted when sync.client.offline supplies it`)
+    }
   }
   if (!conflictTracking.mutationLog || typeof conflictTracking.mutationLog.append !== "function") throw new Error(`${resourceType} conflictTracking.mutationLog must be a LocalMutationLog`)
   if (typeof conflictTracking.clientMutationId !== "function") throw new Error(`${resourceType} conflictTracking.clientMutationId must be a function`)
@@ -1744,6 +1963,30 @@ function normalizedTrack(track) {
   return track
 }
 
+/**
+ * Builds a framework-owned POSTer over the configured transport for a path
+ * chosen at call time (used by the long-offline session's bootstrap/replay
+ * endpoints, which live outside the sync.api mount path).
+ * @param {{requestContext: import("../remote-request-context.js").RemoteRequestContext, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.
+ * @returns {(path: string, payload: Record<string, ReturnType<typeof JSON.parse>>, options?: {signal?: AbortSignal}) => Promise<ReturnType<typeof JSON.parse>>} Path-selecting sync endpoint POSTer.
+ */
+function transportPathPoster({requestContext, transport}) {
+  return async (path, payload, options = {}) => {
+    const requestPayload = mergeRemoteRequestContext({
+      context: requestContext,
+      label: "Sync client request context",
+      params: payload
+    })
+    const response = await transport.post(path, requestPayload, {signal: options.signal})
+
+    if (!response || typeof response.json !== "function") {
+      throw new Error(`sync.client transport.post must resolve to a response with a json() method for ${path} (like the frontend-model websocket client)`)
+    }
+
+    return await response.json()
+  }
+}
+
 /**
  * Builds a framework-owned sync endpoint POSTer over the configured transport.
  * @param {{path: string, requestContext: import("../remote-request-context.js").RemoteRequestContext, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.