velocious 1.0.620 → 1.0.622

package/README.md

@@ -13,9 +13,9 @@
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
 * Optional Rampway-owned durable deployment control plane mounted through the standard routes DSL on Velocious 1.0.577 or newer (see [docs/rampway-integration.md](docs/rampway-integration.md))
 * Controllers and views for HTTP endpoints
-* Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md) and [docs/websocket-channels.md](docs/websocket-channels.md))
+* Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses, immutable per-operation remote request context, and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md), [docs/remote-request-context.md](docs/remote-request-context.md), and [docs/websocket-channels.md](docs/websocket-channels.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see the [shared-resource sync developer guide](docs/shared-resource-sync-guide.md) and [offline sync architecture](docs/offline-sync.md))
-* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery, and immutable-handle project clients whose queues, scopes, cursors, receipts, conflicts, pulls, and reconnect catch-up stay in one physical tenant database (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
+* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery, and immutable-handle project clients whose local database state plus remote pull/replay/realtime request context stay tenant-bound through reconnect (see [docs/sync-client.md](docs/sync-client.md), [docs/remote-request-context.md](docs/remote-request-context.md), and [docs/offline-sync.md](docs/offline-sync.md))
 * Reactive `useLiveQuery(Model.where(...))` queries for default databases plus immutable-handle tenant live-query sources whose committed events and refreshes stay on the captured physical tenant (see [docs/live-queries.md](docs/live-queries.md))
 * Server-side sync envelope replay orchestration for app-owned sync receivers, including allowlisted authoritative values for conflict resolution (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
 * Self-sustaining sync feeds: upstream imports triggered by the changes pull itself, with framework-owned coalescing and throttling (see [docs/sync-upstream-imports.md](docs/sync-upstream-imports.md))
@@ -797,6 +797,7 @@ When your frontend app calls a backend on another host/port (or under a path pre
 import FrontendModelBase from "velocious/build/src/frontend-models/base.js"
 
 FrontendModelBase.configureTransport({
+  requestContext: () => ({projectId: currentProject.id, routingEpoch: currentProject.routingEpoch}),
   url: "http://127.0.0.1:4501/frontend-models",
   timeZone: () => Intl.DateTimeFormat().resolvedOptions().timeZone
 })
@@ -805,6 +806,7 @@ FrontendModelBase.configureTransport({
 Available transport options:
 
 - `url` (can also be a relative path like `"/frontend-models"` on web)
+- `requestContext` (a scalar plain object or synchronous function returning one) captures immutable remote tenant-routing params independently for each CRUD/custom command and event subscription. See [docs/remote-request-context.md](docs/remote-request-context.md).
 - `timeZone` (an IANA timezone string or a function returning one). Browser clients auto-detect this when it is not configured. Frontend-model datetime strings without an explicit timezone are interpreted in this request timezone and stored/queried as UTC instants.
 - `timeout` (milliseconds or a function returning milliseconds) bounds each request, while `signal` (an `AbortSignal` or a function returning one) supports caller cancellation. See [docs/frontend-models.md](docs/frontend-models.md#core-transport) for timeout and cancellation behavior.
 
@@ -2016,6 +2018,8 @@ await client.close()
 
 For long-lived Node clients, the constructor also accepts opt-in liveness options (all default off, so browser/Expo usage is unchanged): `webSocketImplementation` (inject Node's `ws`, since the global/undici WebSocket exposes neither protocol ping nor an unref-able socket), `heartbeatIntervalMs` (a ping heartbeat that drops a socket whose peer stops ponging, so a client notices a vanished server), and `unref` (unref the underlying socket so an idle connection can't keep the process alive on its own). See [docs/websocket-channels.md](docs/websocket-channels.md).
 
+`await client.close()` is a final graceful shutdown that releases resumable server-session state; unexpected transport drops remain resumable. See [the WebSocket channel lifecycle guarantees](docs/websocket-channels.md#lifecycle-guarantees-phase-1b).
+
 ## Subscribe to events
 
 ```js

package/build/background-jobs/store.js

@@ -7,7 +7,7 @@ import TableData from "../database/table-data/index.js"
 import VelociousError from "../velocious-error.js"
 import BackgroundJobRecord from "./job-record.js"
 import normalizeBackgroundJobError from "./normalize-error.js"
-import {coordinateSharedTransactionConnection} from "../testing/shared-transaction-connection-coordinator.js"
+import { coordinateSharedTransactionConnection } from "../testing/shared-transaction-connection-coordinator.js"
 import stableJsonStringify from "../utils/stable-json.js"
 import {
   BACKGROUND_JOB_EXECUTION_MODES,

package/build/database/drivers/base.js

@@ -171,7 +171,7 @@ import TableColumn from "../table-data/table-column.js"
 import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
 import { optionalPositiveInteger } from "typanic"
-import { coordinateSharedTransactionConnection } from "../../testing/shared-transaction-connection-coordinator.js"
+import {coordinateSharedTransactionConnection, runWithoutSharedTransactionCoordinatorOwner} from "../../testing/shared-transaction-connection-coordinator.js"
 import { currentTestProfileContext } from "../../testing/test-profile-context.js"
 import sha256Hex from "../../utils/sha256-hex.js"
 
@@ -341,9 +341,22 @@ export default class VelociousDatabaseDriversBase {
     this._transactionCompletionPromise = Promise.resolve()
     this._resolveTransactionCompletion = undefined
     this._transactionsActionsMutex = new Mutex()
+    this._physicalConnectionMutex = new Mutex()
     this._schemaCache = new Map()
   }
 
+  /**
+   * Serializes access to one physical database session.
+   * @template T
+   * @param {() => Promise<T>} callback - Physical driver operation.
+   * @returns {Promise<T>} - Operation result.
+   */
+  async _runPhysicalConnectionRequest(callback) {
+    return await this._physicalConnectionMutex.sync(async () => {
+      return await runWithoutSharedTransactionCoordinatorOwner(this, callback)
+    })
+  }
+
   /**
    * Cleans driver-specific session state before this logical connection is reusable.
    * Drivers whose physical sessions cannot be safely reset should dispose them here.
@@ -2014,7 +2027,9 @@ export default class VelociousDatabaseDriversBase {
         let failed = true
 
         try {
-          const affectedRows = await this._affectedRowsActual(sql)
+          const affectedRows = await this._runPhysicalConnectionRequest(
+            async () => await this._affectedRowsActual(sql)
+          )
 
           failed = false
           return affectedRows
@@ -2096,7 +2111,9 @@ export default class VelociousDatabaseDriversBase {
         let failed = true
 
         try {
-          const result = await this._queryActual(sql, options)
+          const result = await this._runPhysicalConnectionRequest(
+            async () => await this._queryActual(sql, options)
+          )
 
           failed = false
           return result

package/build/database/drivers/mssql/index.js

@@ -558,52 +558,58 @@ export default class VelociousDatabaseDriversMssql extends Base{
   }
 
   async _startTransactionAction() {
-    if (this._currentTransaction) throw new Error("A transaction is already running")
-    if (!this.connection) await this.connect()
+    await this._runPhysicalConnectionRequest(async () => {
+      if (this._currentTransaction) throw new Error("A transaction is already running")
+      if (!this.connection) await this.connect()
 
-    this._currentTransaction = new mssql.Transaction(this.connection)
+      this._currentTransaction = new mssql.Transaction(this.connection)
 
-    try {
-      await this._currentTransaction.begin()
-    } catch (error) {
-      this._currentTransaction = null
-      throw error
-    }
+      try {
+        await this._currentTransaction.begin()
+      } catch (error) {
+        this._currentTransaction = null
+        throw error
+      }
+    })
   }
 
   async _commitTransactionAction() {
-    if (!this._currentTransaction) throw new Error("A transaction isn't running")
+    await this._runPhysicalConnectionRequest(async () => {
+      if (!this._currentTransaction) throw new Error("A transaction isn't running")
 
-    await this._currentTransaction.commit()
-    this._currentTransaction = null
+      await this._currentTransaction.commit()
+      this._currentTransaction = null
+    })
   }
 
   async _rollbackTransactionAction() {
-    if (!this._currentTransaction) {
-      this.logger.debug("A transaction isn't running - ignoring because that can happen if something else has failed in the db")
-      return
-    }
+    await this._runPhysicalConnectionRequest(async () => {
+      if (!this._currentTransaction) {
+        this.logger.debug("A transaction isn't running - ignoring because that can happen if something else has failed in the db")
+        return
+      }
 
-    try {
-      await this._currentTransaction.rollback()
-    } catch (transactionRollbackError) {
-      // When SQL Server has already aborted the transaction (e.g., a
-      // stale concurrent request triggered XACT_ABORT), the
-      // mssql.Transaction.rollback() call fails because the
-      // Transaction object is dead.  Issue a raw ROLLBACK on the
-      // underlying connection to clear SQL Server's session-level
-      // aborted-transaction state so the connection is usable for the
-      // next BEGIN TRANSACTION.
-      this.logger.warn("Transaction.rollback() failed, clearing session state with raw ROLLBACK", {
-        error: transactionRollbackError instanceof Error ? transactionRollbackError.message : transactionRollbackError
-      })
-
-      const request = new mssql.Request(this.connection)
-
-      await request.query("IF @@TRANCOUNT > 0 ROLLBACK")
-    } finally {
-      this._currentTransaction = null
-    }
+      try {
+        await this._currentTransaction.rollback()
+      } catch (transactionRollbackError) {
+        // When SQL Server has already aborted the transaction (e.g., a
+        // stale concurrent request triggered XACT_ABORT), the
+        // mssql.Transaction.rollback() call fails because the
+        // Transaction object is dead.  Issue a raw ROLLBACK on the
+        // underlying connection to clear SQL Server's session-level
+        // aborted-transaction state so the connection is usable for the
+        // next BEGIN TRANSACTION.
+        this.logger.warn("Transaction.rollback() failed, clearing session state with raw ROLLBACK", {
+          error: transactionRollbackError instanceof Error ? transactionRollbackError.message : transactionRollbackError
+        })
+
+        const request = new mssql.Request(this.connection)
+
+        await request.query("IF @@TRANCOUNT > 0 ROLLBACK")
+      } finally {
+        this._currentTransaction = null
+      }
+    })
   }
 
   /**

package/build/environment-handlers/base.js

@@ -54,6 +54,15 @@ export default class VelociousEnvironmentHandlerBase {
    */
   runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
 
+  /**
+   * Runs work without inherited shared-transaction ownership for one connection.
+   * @template T
+   * @param {import("../database/drivers/base.js").default} _connection - Physical connection whose owner is cleared.
+   * @param {() => T} callback - Physical connection work.
+   * @returns {T} - Callback result.
+   */
+  runWithoutSharedTransactionCoordinatorOwner(_connection, callback) { return callback() }
+
   /**
    * Runs work without inherited shared-transaction coordinator ownership.
    * @template T

package/build/environment-handlers/node.js

@@ -154,6 +154,22 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
   }
 
+  /**
+   * Runs work without inherited shared-transaction ownership for one connection.
+   * @template T
+   * @param {import("../database/drivers/base.js").default} connection - Physical connection whose owner is cleared.
+   * @param {() => T} callback - Physical connection work.
+   * @returns {T} - Callback result.
+   */
+  runWithoutSharedTransactionCoordinatorOwner(connection, callback) {
+    if (!this._sharedTransactionCoordinatorAsyncLocalStorage) return callback()
+
+    const owners = new Map(this._sharedTransactionCoordinatorAsyncLocalStorage.getStore())
+
+    owners.delete(connection)
+    return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
+  }
+
   /**
    * Runs work without inherited shared-transaction coordinator ownership.
    * @template T

package/build/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/build/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/build/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})
+}