velocious 1.0.621 → 1.0.622

package/src/frontend-model-controller.js

@@ -16,6 +16,7 @@ import {requestDetails} from "./error-reporting/request-details.js"
 import RoutesResolver from "./routes/resolver.js"
 import {ValidationError} from "./database/record/index.js"
 import RecordNotFoundError from "./database/record/record-not-found-error.js"
+import {captureFrontendModelRemoteRequestContext, mergeFrontendModelRemoteRequestContext} from "./frontend-models/remote-request-context.js"
 import { normalizeDateStringForWrite } from "./database/datetime-storage.js"
 import VelociousError from "./velocious-error.js"
 import isDate from "./utils/is-date.js"
@@ -4360,13 +4361,17 @@ export default class FrontendModelController extends Controller {
       }
 
       try {
+        const requestContext = captureFrontendModelRemoteRequestContext(requestEntry?.requestContext)
         let responsePayload
 
         if (isBuiltInCommand) {
-          const commandParams = {
-            ...(payload && typeof payload === "object" ? payload : {}),
-            model
-          }
+          const commandParams = mergeFrontendModelRemoteRequestContext(
+            requestContext,
+            {
+              ...(payload && typeof payload === "object" ? payload : {}),
+              model
+            }
+          )
 
           responsePayload = await this.withFrontendModelParams(commandParams, async () => {
             return await this.withFrontendModelRequestContext(commandParams, this.response(), async () => {
@@ -4376,7 +4381,8 @@ export default class FrontendModelController extends Controller {
         } else {
           responsePayload = await this.frontendApiCustomCommandPayload({
             customPath,
-            payload
+            payload,
+            requestContext
           })
         }
 
@@ -4415,9 +4421,10 @@ export default class FrontendModelController extends Controller {
    * @param {object} args - Arguments.
    * @param {string} args.customPath - Custom backend route path.
    * @param {ReturnType<typeof JSON.parse>} args.payload - Request payload.
+   * @param {import("./remote-request-context.js").RemoteRequestContext} args.requestContext - Captured remote request context.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Parsed JSON response payload.
    */
-  async frontendApiCustomCommandPayload({customPath, payload}) {
+  async frontendApiCustomCommandPayload({customPath, payload, requestContext}) {
     const configuration = this.getConfiguration()
     const response = new Response({configuration})
     const resolver = new RoutesResolver({
@@ -4449,10 +4456,13 @@ export default class FrontendModelController extends Controller {
     const viewPath = routeHookMatch?.viewPath || `${configuration.getDirectory()}/src/routes/${controller}`
     resolver.routeHookControllerClass = routeHookMatch?.controllerClass
     const controllerClass = await resolver.resolveControllerClass({controllerPath})
-    const controllerParams = {
-      ...((payload && typeof payload === "object") ? payload : {}),
-      ...resolver.params
-    }
+    const controllerParams = mergeFrontendModelRemoteRequestContext(
+      requestContext,
+      {
+        ...((payload && typeof payload === "object") ? payload : {}),
+        ...resolver.params
+      }
+    )
     const controllerInstance = new controllerClass({
       action,
       configuration,

package/src/frontend-models/base.js

@@ -12,6 +12,8 @@ import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportV
 import runWithTransportDeadline from "./transport-deadline.js"
 import {REQUEST_TIME_ZONE_HEADER, validateTimeZone} from "../time-zone.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
+import {remoteRequestContextKey} from "../remote-request-context.js"
+import {captureFrontendModelRemoteRequestContext, mergeFrontendModelRemoteRequestContext} from "./remote-request-context.js"
 import {bufferOutgoingEvent, clearBufferedOutgoingEvents, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
 import {defineModelScope} from "../utils/model-scope.js"
 import isPlainObject from "../utils/plain-object.js"
@@ -132,6 +134,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * @property {string | (() => string | undefined | null)} [websocketUrl] - Optional websocket URL. When set, Velocious creates and manages its own websocket client internally. Subscriptions use the websocket; CRUD uses HTTP and falls back gracefully. Example: `"ws://localhost:3006/websocket"`.
  * @property {{post: (path: string, body?: ReturnType<typeof JSON.parse>, options?: {headers?: Record<string, string>, signal?: AbortSignal}) => Promise<{json: () => ReturnType<typeof JSON.parse>}>, subscribe: (channel: string, options: {params?: Record<string, ReturnType<typeof JSON.parse>>}, callback: (payload: ReturnType<typeof JSON.parse>) => void) => (() => void), subscribeAndWait?: (channel: string, options: {params?: Record<string, ReturnType<typeof JSON.parse>>}, callback: (payload: ReturnType<typeof JSON.parse>) => void) => Promise<(() => void)>}} [websocketClient] - Optional websocket client for shared frontend-model API requests and subscriptions. Its `post` receives the bounded-deadline `signal` and should forward it into the underlying transport so the deadline can abort the live request and its response-body read.
  * @property {Record<string, string> | (() => Record<string, string>)} [requestHeaders] - Extra HTTP/WS headers to attach to every frontend-model API request. Pass a function to compute them at request time (for example to include the current locale).
+ * @property {import("../remote-request-context.js").RemoteRequestContext | (() => import("../remote-request-context.js").RemoteRequestContext | undefined | null)} [requestContext] - Immutable scalar context captured independently when each operation or event subscription starts and sent for remote tenant/ability resolution.
  * @property {number | (() => number | undefined | null)} [timeout] - Bounded deadline in milliseconds covering connection, response headers, and response-body consumption for each frontend-model API request. On expiry the live fetch/adapter request is aborted (built on awaitery's `timeout`) and awaitery's `TimeoutError` is thrown, so callers can classify a timeout via `error instanceof TimeoutError`. Pass a function to resolve it per request. Falsy/absent means no deadline.
  * @property {AbortSignal | (() => AbortSignal | undefined | null)} [signal] - Optional caller/session AbortSignal composed with the deadline. Aborting it cancels the live request (for example on session shutdown or offline transition); the resulting abort error stays distinguishable from a timeout. Pass a function to resolve the current signal per request.
  * @property {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>}} [sessionStore] - Optional sessionId persistence hook forwarded to the internal `VelociousWebsocketClient` so WS sessions can be resumed across page reloads / app restarts.
@@ -157,8 +160,9 @@ const QUERY_DATA_KEY = "__queryData"
 const ABILITIES_KEY = "__abilities"
 /**
  * Pending shared frontend model requests.
- * @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: FrontendModelClass, payload: Record<string, ReturnType<typeof JSON.parse>>, requestId: string, resolve: (response: Record<string, ReturnType<typeof JSON.parse>>) => void, reject: (error: ReturnType<typeof JSON.parse>) => void, resourcePath?: string | null}>} */
+ * @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: FrontendModelClass, payload: Record<string, ReturnType<typeof JSON.parse>>, requestContext: import("../remote-request-context.js").RemoteRequestContext, requestId: string, resolve: (response: Record<string, ReturnType<typeof JSON.parse>>) => void, reject: (error: ReturnType<typeof JSON.parse>) => void, resourcePath?: string | null}>} */
 let pendingSharedFrontendModelRequests = []
+
 let sharedFrontendModelRequestId = 0
 let sharedFrontendModelFlushScheduled = false
 let activeFrontendModelTransportRequestCount = 0
@@ -1450,9 +1454,11 @@ class FrontendModelEventSubscription {
   /**
    * Runs constructor.
    * @param {FrontendModelClass} ModelClass - Frontend model class for this subscription bucket.
+   * @param {import("../remote-request-context.js").RemoteRequestContext} requestContext - Captured subscription context.
    */
-  constructor(ModelClass) {
+  constructor(ModelClass, requestContext) {
     this.ModelClass = ModelClass
+    this.requestContext = requestContext
     /**
      * Narrows the runtime value to the documented type.
      * @type {Set<FrontendModelModelEventCallbackEntry>} */
@@ -1530,11 +1536,14 @@ class FrontendModelEventSubscription {
         }
       : {}
 
-    return {
-      model: this.ModelClass.getModelName(),
-      ...eventFilterParams,
-      ...projectionPayload
-    }
+    return mergeFrontendModelRemoteRequestContext(
+      this.requestContext,
+      {
+        model: this.ModelClass.getModelName(),
+        ...eventFilterParams,
+        ...projectionPayload
+      }
+    )
   }
 
   /**
@@ -1681,41 +1690,79 @@ class FrontendModelEventSubscription {
       || this.instanceListeners.size > 0
 
     if (hasAnyListener) return
-    if (!this.channelHandle) return
 
-    try {
-      this.channelHandle.close()
-    } catch (error) {
-      console.error(error)
+    if (this.channelHandle) {
+      try {
+        this.channelHandle.close()
+      } catch (error) {
+        console.error(error)
+      }
     }
 
     this.channelHandle = null
     this.readyPromise = null
     this.subscriptionParamsKey = null
+    releaseFrontendModelEventSubscription(this)
   }
 }
 
 /**
  * Frontend model event subscriptions.
- * @type {WeakMap<FrontendModelClass, FrontendModelEventSubscription>} */
+ * @type {WeakMap<FrontendModelClass, Map<string, FrontendModelEventSubscription>>} */
 const frontendModelEventSubscriptions = new WeakMap()
 
 /**
  * Runs ensure frontend model event subscription.
  * @param {FrontendModelClass} ModelClass - Model class.
+ * @param {import("../remote-request-context.js").RemoteRequestContext} requestContext - Captured subscription context.
  * @returns {FrontendModelEventSubscription} - Per-class subscription helper.
  */
-function ensureFrontendModelEventSubscription(ModelClass) {
-  let sub = frontendModelEventSubscriptions.get(ModelClass)
+function ensureFrontendModelEventSubscription(ModelClass, requestContext) {
+  let subscriptions = frontendModelEventSubscriptions.get(ModelClass)
+
+  if (!subscriptions) {
+    subscriptions = new Map()
+    frontendModelEventSubscriptions.set(ModelClass, subscriptions)
+  }
+
+  const contextKey = remoteRequestContextKey(requestContext)
+  let sub = subscriptions.get(contextKey)
 
   if (!sub) {
-    sub = new FrontendModelEventSubscription(ModelClass)
-    frontendModelEventSubscriptions.set(ModelClass, sub)
+    sub = new FrontendModelEventSubscription(ModelClass, requestContext)
+    subscriptions.set(contextKey, sub)
   }
 
   return sub
 }
 
+/**
+ * Removes an empty context bucket so switching through many tenants does not retain every snapshot.
+ * @param {FrontendModelEventSubscription} subscription - Empty subscription bucket.
+ * @returns {void}
+ */
+function releaseFrontendModelEventSubscription(subscription) {
+  const subscriptions = frontendModelEventSubscriptions.get(subscription.ModelClass)
+  const contextKey = remoteRequestContextKey(subscription.requestContext)
+
+  if (subscriptions?.get(contextKey) !== subscription) return
+
+  subscriptions.delete(contextKey)
+  if (subscriptions.size === 0) frontendModelEventSubscriptions.delete(subscription.ModelClass)
+}
+
+/**
+ * Captures the current frontend-model transport context for one operation.
+ * @returns {import("../remote-request-context.js").RemoteRequestContext} Frozen context snapshot.
+ */
+function frontendModelRequestContext() {
+  const configuredContext = typeof frontendModelTransportConfig.requestContext === "function"
+    ? frontendModelTransportConfig.requestContext()
+    : frontendModelTransportConfig.requestContext
+
+  return captureFrontendModelRemoteRequestContext(configuredContext)
+}
+
 /**
  * Runs ensure frontend model instance listener.
  * @param {FrontendModelEventSubscription} sub - Event subscription bucket.
@@ -2007,6 +2054,7 @@ async function flushPendingSharedFrontendModelRequests() {
           customPath: request.customPath,
           model: request.modelClass.getModelName(),
           payload: request.payload,
+          ...(Object.keys(request.requestContext).length > 0 ? {requestContext: request.requestContext} : {}),
           requestId: request.requestId
         }
       }
@@ -2015,6 +2063,7 @@ async function flushPendingSharedFrontendModelRequests() {
         commandType: request.commandType,
         model: request.modelClass.getModelName(),
         payload: request.payload,
+        ...(Object.keys(request.requestContext).length > 0 ? {requestContext: request.requestContext} : {}),
         requestId: request.requestId
       }
     })
@@ -3016,6 +3065,10 @@ export default class FrontendModelBase {
       frontendModelTransportConfig.requestHeaders = config.requestHeaders
     }
 
+    if (Object.prototype.hasOwnProperty.call(config, "requestContext")) {
+      frontendModelTransportConfig.requestContext = config.requestContext
+    }
+
     if (Object.prototype.hasOwnProperty.call(config, "timeout")) {
       frontendModelTransportConfig.timeout = config.timeout
     }
@@ -3286,9 +3339,14 @@ export default class FrontendModelBase {
       throw new Error("subscribeWebsocketChannel requires configureTransport({websocketUrl})")
     }
 
-    const {signal, timeoutMs, ...channelOptions} = options
+    const {params, signal, timeoutMs, ...channelOptions} = options
+    const requestContext = frontendModelRequestContext()
+    const scopedParams = mergeFrontendModelRemoteRequestContext(requestContext, params === undefined ? {} : params)
     const startupControls = frontendModelWebsocketStartupControls({signal, timeoutMs})
-    const handle = client.subscribeChannel(channelType, {...channelOptions, ...startupControls})
+    const scopedParamsOption = params === undefined && Object.keys(requestContext).length === 0
+      ? {}
+      : {params: scopedParams}
+    const handle = client.subscribeChannel(channelType, {...channelOptions, ...scopedParamsOption, ...startupControls})
 
     if (typeof client.connect === "function") {
       void client.connect(startupControls).catch(() => handle.close())
@@ -3649,7 +3707,7 @@ export default class FrontendModelBase {
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
   static async onCreate(callback, options = {}) {
-    const sub = ensureFrontendModelEventSubscription(this)
+    const sub = ensureFrontendModelEventSubscription(this, frontendModelRequestContext())
     const entry = {callback, ...frontendModelEventOptionsPayload(this, options)}
 
     sub.classCreateCallbacks.add(entry)
@@ -3669,7 +3727,7 @@ export default class FrontendModelBase {
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
   static async onUpdate(callback, options = {}) {
-    const sub = ensureFrontendModelEventSubscription(this)
+    const sub = ensureFrontendModelEventSubscription(this, frontendModelRequestContext())
     const entry = {callback, ...frontendModelEventOptionsPayload(this, options)}
 
     sub.classUpdateCallbacks.add(entry)
@@ -3691,7 +3749,7 @@ export default class FrontendModelBase {
   static async onDestroy(callback, options = {}) {
     assertNoDestroyEventFilter(this, options)
 
-    const sub = ensureFrontendModelEventSubscription(this)
+    const sub = ensureFrontendModelEventSubscription(this, frontendModelRequestContext())
     const entry = {callback}
 
     sub.classDestroyCallbacks.add(entry)
@@ -3715,7 +3773,7 @@ export default class FrontendModelBase {
   async onUpdate(callback, options = {}) {
     const self = /** @type {ReturnType<typeof JSON.parse>} */ (this)
     const ModelClass = frontendModelClassFor(this)
-    const sub = ensureFrontendModelEventSubscription(ModelClass)
+    const sub = ensureFrontendModelEventSubscription(ModelClass, frontendModelRequestContext())
     const id = String(self.id())
     const entry = {callback, ...frontendModelEventOptionsPayload(ModelClass, options)}
     const listener = ensureFrontendModelInstanceListener(sub, id, this)
@@ -3748,7 +3806,7 @@ export default class FrontendModelBase {
 
     assertNoDestroyEventFilter(ModelClass, options)
 
-    const sub = ensureFrontendModelEventSubscription(ModelClass)
+    const sub = ensureFrontendModelEventSubscription(ModelClass, frontendModelRequestContext())
     const id = String(self.id())
     const entry = {callback}
     const listener = ensureFrontendModelInstanceListener(sub, id, this)
@@ -4596,6 +4654,8 @@ export default class FrontendModelBase {
     const commandName = this.commandName(commandType)
     const timeZone = frontendModelTransportTimeZone()
     const serializedPayload = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(payload, {timeZone}))
+    const requestContext = frontendModelRequestContext()
+    const requestPayload = mergeFrontendModelRemoteRequestContext(requestContext, serializedPayload)
     const resourcePath = this.resourcePath()
     const containsAttachmentUpload = frontendModelPayloadContainsAttachmentUpload(serializedPayload)
     const useSharedTransport = !containsAttachmentUpload
@@ -4608,6 +4668,7 @@ export default class FrontendModelBase {
           commandType,
           modelClass: this,
           payload: serializedPayload,
+          requestContext,
           reject,
           requestId: `${++sharedFrontendModelRequestId}`,
           resolve,
@@ -4635,7 +4696,7 @@ export default class FrontendModelBase {
       },
       async (signal) => {
         const directResponse = await fetch(url, {
-          body: JSON.stringify(serializedPayload),
+          body: JSON.stringify(requestPayload),
           credentials: "include",
           headers: frontendModelRequestHeaders(timeZone),
           method: "POST",
@@ -4675,6 +4736,9 @@ export default class FrontendModelBase {
     const {commandName, commandType, memberId = null, payload, resourcePath} = args
     const timeZone = frontendModelTransportTimeZone()
     const serializedPayload = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(payload, {timeZone}))
+    const requestContext = frontendModelRequestContext()
+
+    mergeFrontendModelRemoteRequestContext(requestContext, serializedPayload)
     const customPath = frontendModelCustomCommandPath({
       commandName,
       memberId,
@@ -4688,6 +4752,7 @@ export default class FrontendModelBase {
         customPath,
         modelClass: this,
         payload: serializedPayload,
+        requestContext,
         reject,
         requestId: `${++sharedFrontendModelRequestId}`,
         resolve

package/src/frontend-models/remote-request-context.js

@@ -0,0 +1,29 @@
+// @ts-check
+
+import {captureRemoteRequestContext, mergeRemoteRequestContext} from "../remote-request-context.js"
+
+const RESERVED_KEYS = ["commandType", "customPath", "model", "payload", "requestContext", "requestId", "requests"]
+const REQUEST_CONTEXT_LABEL = "Frontend model request context"
+
+/**
+ * Captures one frontend-model operation's immutable remote request context.
+ * @param {ReturnType<typeof JSON.parse> | undefined} value - Configured or untrusted context value.
+ * @returns {import("../remote-request-context.js").RemoteRequestContext} Frozen context snapshot.
+ */
+export function captureFrontendModelRemoteRequestContext(value) {
+  return captureRemoteRequestContext(value, {
+    label: REQUEST_CONTEXT_LABEL,
+    reservedKeys: RESERVED_KEYS
+  })
+}
+
+/**
+ * Merges captured context into frontend-model command or subscription params.
+ * @template {Record<string, ReturnType<typeof JSON.parse>>} TParams
+ * @param {import("../remote-request-context.js").RemoteRequestContext} context - Captured context.
+ * @param {TParams} params - Framework-owned params.
+ * @returns {TParams & import("../remote-request-context.js").RemoteRequestContext} Merged params.
+ */
+export function mergeFrontendModelRemoteRequestContext(context, params) {
+  return mergeRemoteRequestContext({context, label: REQUEST_CONTEXT_LABEL, params})
+}

package/src/http-client/websocket-client.js

@@ -26,6 +26,8 @@ export default class VelociousWebsocketClient extends SnapReqWebSocketClient {
     this.reconnectGeneration = 0
     /** @type {Set<Promise<void>>} */
     this.runningReconnectTasks = new Set()
+    /** @type {Promise<void> | null} */
+    this.gracefulClosePromise = null
   }
 
   /**
@@ -55,6 +57,36 @@ export default class VelociousWebsocketClient extends SnapReqWebSocketClient {
     }
   }
 
+  /**
+   * Closes the WebSocket as a normal shutdown so the server permanently
+   * releases resumable session state.
+   * @returns {Promise<void>} - Resolves once closed.
+   */
+  async close() {
+    if (this.gracefulClosePromise) return await this.gracefulClosePromise
+
+    this.autoReconnect = false
+    const socket = this.socket
+    const closePromise = (async () => {
+      if (socket && socket.readyState === socket.OPEN) {
+        await new Promise((resolve) => {
+          socket.addEventListener("close", () => resolve(undefined), {once: true})
+          socket.close(1000)
+        })
+      }
+
+      await super.close()
+    })()
+
+    this.gracefulClosePromise = closePromise
+
+    try {
+      await closePromise
+    } finally {
+      if (this.gracefulClosePromise === closePromise) this.gracefulClosePromise = null
+    }
+  }
+
   /**
    * Stops reconnect, drains work that already passed SnapReq's reconnect guard,
    * and clears state changed by a stale attempt while it settled.

package/src/http-server/client/websocket-session.js

@@ -39,6 +39,7 @@ const WEBSOCKET_OPCODE_CLOSE = 0x8
 const WEBSOCKET_OPCODE_PING = 0x9
 const WEBSOCKET_OPCODE_PONG = 0xA
 
+const WEBSOCKET_CLOSE_NORMAL = 1000
 const WEBSOCKET_CLOSE_POLICY_VIOLATION = 1008
 const WEBSOCKET_INBOUND_BACKLOG_CLOSE_REASON = "Inbound message backlog exceeded"
 const WEBSOCKET_MAX_CLOSE_REASON_BYTES = 123
@@ -785,8 +786,10 @@ export default class VelociousHttpServerClientWebsocketSession {
       }
 
       if (opcode === WEBSOCKET_OPCODE_CLOSE) {
+        const allowResume = payload.length < 2 || payload.readUInt16BE(0) !== WEBSOCKET_CLOSE_NORMAL
+
         this.sendGoodbye(this.client)
-        this._handleClose()
+        this._handleClose({allowResume})
         continue
       }
 

package/src/remote-request-context.js

@@ -0,0 +1,97 @@
+// @ts-check
+
+import VelociousError from "./velocious-error.js"
+import isPlainObject from "./utils/plain-object.js"
+
+/** @typedef {Readonly<Record<string, string | number | boolean>>} RemoteRequestContext */
+
+const UNSAFE_CONTEXT_KEYS = new Set(["__proto__", "constructor", "prototype"])
+
+/**
+ * Captures and validates immutable scalar context for one remote operation.
+ * @param {ReturnType<typeof JSON.parse> | undefined} value - Configured context value.
+ * @param {object} [args] - Validation options.
+ * @param {string} [args.label] - Context label used in errors.
+ * @param {Iterable<string>} [args.reservedKeys] - Framework-owned keys unavailable to context.
+ * @returns {RemoteRequestContext} Frozen context snapshot.
+ */
+export function captureRemoteRequestContext(value, {label = "Remote request context", reservedKeys = []} = {}) {
+  if (value === undefined || value === null) return Object.freeze({})
+
+  if (!isPlainObject(value)) {
+    throw remoteRequestContextError(`${label} must be a plain object of scalar values`)
+  }
+
+  const reservedKeySet = new Set(reservedKeys)
+  /** @type {Record<string, string | number | boolean>} */
+  const context = {}
+
+  for (const key of Object.keys(value).sort()) {
+    if (!key.trim()) throw remoteRequestContextError(`${label} keys must be non-blank strings`)
+    if (UNSAFE_CONTEXT_KEYS.has(key) || reservedKeySet.has(key)) {
+      throw remoteRequestContextError(`${label} key ${JSON.stringify(key)} is reserved by the framework`)
+    }
+
+    const contextValue = value[key]
+
+    if (!remoteRequestContextScalar(contextValue)) {
+      throw remoteRequestContextError(`${label} key ${JSON.stringify(key)} must contain a string, finite number, or boolean scalar`)
+    }
+
+    context[key] = contextValue
+  }
+
+  return Object.freeze(context)
+}
+
+/**
+ * Merges captured context into framework request params without ambiguity.
+ * @template {Record<string, ReturnType<typeof JSON.parse>>} TParams
+ * @param {object} args - Merge arguments.
+ * @param {RemoteRequestContext} args.context - Captured context.
+ * @param {string} [args.label] - Context label used in errors.
+ * @param {TParams} args.params - Framework-owned request params.
+ * @returns {TParams & RemoteRequestContext} Merged params, or the original params when unscoped.
+ */
+export function mergeRemoteRequestContext({context, label = "Remote request context", params}) {
+  const contextKeys = Object.keys(context)
+
+  if (contextKeys.length === 0) return params
+
+  for (const key of contextKeys) {
+    if (Object.hasOwn(params, key)) {
+      throw remoteRequestContextError(`${label} key ${JSON.stringify(key)} is reserved by the request payload`)
+    }
+  }
+
+  return {...params, ...context}
+}
+
+/**
+ * Returns a stable identity for an immutable captured context.
+ * @param {RemoteRequestContext} context - Captured context.
+ * @returns {string} Stable serialized key.
+ */
+export function remoteRequestContextKey(context) {
+  return JSON.stringify(context)
+}
+
+/**
+ * Checks whether a value is a supported request-context scalar.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate scalar.
+ * @returns {value is string | number | boolean} Whether the value is supported.
+ */
+function remoteRequestContextScalar(value) {
+  if (["string", "boolean"].includes(typeof value)) return true
+
+  return typeof value === "number" && Number.isFinite(value)
+}
+
+/**
+ * Builds a client-safe request-context validation error.
+ * @param {string} message - Safe validation message.
+ * @returns {VelociousError} Validation error.
+ */
+function remoteRequestContextError(message) {
+  return VelociousError.safe(message, {code: "remote-request-context-invalid", errorType: "validation_error"})
+}

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

@@ -90,6 +90,7 @@
  * @typedef {object} SyncClientOptions
  * @property {import("../configuration.js").default} [configuration] - Configuration owning the registered models, the `sync.client` block, and the scope-store database. Defaults to the current configuration.
  * @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 {import("../remote-request-context.js").RemoteRequestContext} [requestContext] - Immutable scalar context captured for this client and sent with every pull, replay, and realtime subscription.
  * @property {import("./sync-scope-store.js").default} [scopeStore] - Scope store override (tests).
  * @property {ReturnType<typeof JSON.parse>} [syncModel] - Pending-sync model override. Defaults to the registered "Sync" model.
  * @property {string} [databaseIdentifier] - Tenant database identifier; required with tenantHandle.
@@ -109,6 +110,7 @@
  * @property {(payload: import("./sync-api-client-types.js").SyncChangesRequest & {scope: SerializedSyncScope}) => Promise<import("./sync-api-client-types.js").SyncChangesResponse>} postChanges - Posts one changes request.
  * @property {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}) => 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.
  * @property {Record<string, SyncClientResourceConfig>} resources - Derived resource policies keyed by resource/model name.
  * @property {ReturnType<typeof JSON.parse>} syncModel - Local pending-sync model class.
  * @property {string} [databaseIdentifier] - Tenant-scoped database identifier.

package/src/sync/sync-client.js

@@ -3,6 +3,7 @@
 import Configuration from "../configuration.js"
 import {isBooleanColumnType} from "../database/column-types.js"
 import Logger from "../logger.js"
+import {captureRemoteRequestContext, mergeRemoteRequestContext} from "../remote-request-context.js"
 import restArgsError from "../utils/rest-args-error.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
 
@@ -28,6 +29,20 @@ const DEFAULT_TRACKED_OPERATIONS = ["create", "update"]
 /** Attribute names treated as client-local sync bookkeeping when deriving localOnlyAttributes. */
 const LOCAL_BOOKKEEPING_ATTRIBUTE_NAMES = ["createdAt", "updatedAt", "lastSyncChangeAt"]
 
+const SYNC_REQUEST_RESERVED_KEYS = [
+  "afterId",
+  "afterServerSequence",
+  "afterUpdatedAt",
+  "authenticationToken",
+  "limit",
+  "scope",
+  "syncs",
+  "upstreamRefresh",
+  "upToId",
+  "upToServerSequence",
+  "upToUpdatedAt"
+]
+
 /** @type {WeakMap<Configuration, SyncClient>} */
 const syncClientsByConfiguration = new WeakMap()
 
@@ -56,11 +71,15 @@ export default class SyncClient {
    * @param {import("./sync-client-types.js").SyncClientOptions} [options] - Optional overrides.
    */
   constructor(options = {}) {
-    const {configuration = Configuration.current(), databaseIdentifier, legacyCursor, scopeStore, syncModel, tenantHandle, ...restOptions} = options
+    const {configuration = Configuration.current(), databaseIdentifier, legacyCursor, requestContext, scopeStore, syncModel, tenantHandle, ...restOptions} = options
 
     restArgsError(restOptions)
 
     const clientConfiguration = configuration.getSyncConfiguration().client
+    const capturedRequestContext = captureRemoteRequestContext(requestContext, {
+      label: "Sync client request context",
+      reservedKeys: SYNC_REQUEST_RESERVED_KEYS
+    })
 
     if (!clientConfiguration) {
       throw new Error("SyncClient requires a sync.client configuration block: new Configuration({sync: {client: {authenticationToken, transport}}})")
@@ -121,9 +140,10 @@ export default class SyncClient {
       isOnline: clientConfiguration.isOnline,
       legacyCursor,
       onError: clientConfiguration.onError,
-      postChanges: transportPoster({path: `${clientConfiguration.mountPath}/changes`, transport: clientConfiguration.transport}),
-      postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, 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,
+      requestContext: capturedRequestContext,
       resources,
       syncModel: resolvedSyncModel,
       tenantHandle,
@@ -1267,12 +1287,17 @@ function normalizedTrack(track) {
 
 /**
  * Builds a framework-owned sync endpoint POSTer over the configured transport.
- * @param {{path: string, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.
+ * @param {{path: string, requestContext: import("../remote-request-context.js").RemoteRequestContext, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.
  * @returns {(payload: Record<string, ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>} Sync endpoint POSTer.
  */
-function transportPoster({path, transport}) {
+function transportPoster({path, requestContext, transport}) {
   return async (payload) => {
-    const response = await transport.post(path, payload)
+    const requestPayload = mergeRemoteRequestContext({
+      context: requestContext,
+      label: "Sync client request context",
+      params: payload
+    })
+    const response = await transport.post(path, requestPayload)
 
     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)`)