velocious 1.0.637 → 1.0.639

package/README.md

@@ -13,7 +13,7 @@
 * 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, 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))
+* 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, registration-local tenant subscription partitioning, 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 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))
@@ -674,10 +674,13 @@ import useModelClassEvent from "velocious/build/src/frontend-models/use-model-cl
 
 useModelClassEvent(Subscription, ["create", "update"], () => {
   void loadSubscriptionStatus()
+}, {
+  query: Subscription.where({workspaceId}),
+  requestContext: {workspaceId}
 })
 ```
 
-`useCreatedEvent`, `useUpdatedEvent`, and `useDestroyedEvent` are also available. `useUpdatedEvent` and `useDestroyedEvent` accept either a model class or model instance. Lifecycle subscriptions accept the same projection options as frontend-model queries for event records, including `select`, `preload`, `withCount`, `abilities`, and `queryData`.
+`useCreatedEvent`, `useUpdatedEvent`, and `useDestroyedEvent` are also available. `useUpdatedEvent` and `useDestroyedEvent` accept either a model class or model instance. Lifecycle subscriptions accept the same projection options as frontend-model queries for event records, including `select`, `preload`, `withCount`, `abilities`, and `queryData`. Pass a registration-local `requestContext` when several tenant routes for the same model can be mounted concurrently. Omitting it inherits the configured transport context; passing `{}` explicitly replaces that context with an unscoped registration. Velocious captures it immutably, sends it to the tenant resolver, and partitions server subscriptions by its value: equal contexts retain multiplexing, while distinct contexts never share an event-filter request. The backend must still authorize the resolved tenant; request context is not proof of access.
 
 Frontend-model `group(...)` is attribute/path based and does not accept raw SQL fragments. Use model/relationship shapes (for example `Task.group({project: {account: ["id"]}})`) so grouping resolves through known relationships and mapped columns.
 Frontend-model `where(...)` supports nested relationship descriptors (for example `Task.where({project: {creatingUser: {reference: "owner-b"}}})`) and does not accept raw SQL fragments.
@@ -2392,7 +2395,7 @@ candidate without waiting for retired work to finish.
 
 Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options, or by deriving the key in a hydrated job instance's non-static `concurrencyKey()` method. Explicit enqueue options win. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
 
-Production apps can listen for `background-job-failed` (or its `all-error` mirror) to report accepted failed attempts, including retry and terminal-state metadata, and for `background-job-orphaned` to react to a specific job the main process reclaimed after its worker died mid-run — e.g. enqueue a targeted recovery for the work it left behind, instead of only polling for the aftermath. Orphan handlers run before the sweep waits for reclaimed jobs to be dispatched, so a stalled dispatcher does not delay application recovery. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).
+Production apps can listen for `background-job-failed` (or its `all-error` mirror) to report accepted failed attempts, including retry and terminal-state metadata. Process-level pooled-runner failures also carry one shared `context.runnerFailure` snapshot for every affected job, with active handoff identities, runner/worker lifecycle and PIDs, exit code/signal, termination reason, and an explicit nullable OOM verdict. Listen for `background-job-orphaned` to react to a specific job the main process reclaimed after its worker died mid-run — e.g. enqueue a targeted recovery for the work it left behind, instead of only polling for the aftermath. Orphan handlers run before the sweep waits for reclaimed jobs to be dispatched, so a stalled dispatcher does not delay application recovery. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).
 
 ## Setup
 

package/build/background-jobs/main.js

@@ -1668,6 +1668,7 @@ export default class BackgroundJobsMain {
           handoffId: message.handoffId,
           handedOffAtMs: message.handedOffAtMs,
           job: failedJob,
+          runnerFailure: message.runnerFailure,
           workerId: message.workerId
         })
       }
@@ -1686,10 +1687,10 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs emit background job failed.
-   * @param {{error: ReturnType<typeof JSON.parse>, handoffId?: string, handedOffAtMs?: number, job: import("./types.js").BackgroundJobRow, workerId?: string}} args - Failure event data.
+   * @param {{error: ReturnType<typeof JSON.parse>, handoffId?: string, handedOffAtMs?: number, job: import("./types.js").BackgroundJobRow, runnerFailure?: import("./types.js").PooledRunnerFailure, workerId?: string}} args - Failure event data.
    * @returns {void}
    */
-  _emitBackgroundJobFailed({error, handoffId, handedOffAtMs, job, workerId}) {
+  _emitBackgroundJobFailed({error, handoffId, handedOffAtMs, job, runnerFailure, workerId}) {
     const normalizedError = this._normalizeFailureError(error)
     const payload = {
       context: {
@@ -1700,6 +1701,7 @@ export default class BackgroundJobsMain {
         jobId: job.id,
         jobName: job.jobName,
         maxRetries: job.maxRetries,
+        runnerFailure,
         stage: "background-job-failed",
         status: job.status,
         terminal: job.status === "failed" || job.status === "orphaned",

package/build/background-jobs/status-reporter.js

@@ -47,9 +47,10 @@ export default class BackgroundJobsStatusReporter {
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.
+   * @param {import("./types.js").PooledRunnerFailure} [args.runnerFailure] - Pooled-child process failure provenance.
    * @returns {Promise<void>} - Resolves when reported.
    */
-  async report({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId}) {
+  async report({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure}) {
     const config = this.configuration.getBackgroundJobsConfig()
     const host = this.host || config.host
     const port = typeof this.port === "number" ? this.port : config.port
@@ -73,7 +74,8 @@ export default class BackgroundJobsStatusReporter {
             handoffId,
             workerId,
             handedOffAtMs,
-            error: error ? normalizeBackgroundJobError(error) : undefined
+            error: error ? normalizeBackgroundJobError(error) : undefined,
+            runnerFailure
           })
         },
         onMessage: ({message, resolve, reject}) => {
@@ -100,17 +102,18 @@ export default class BackgroundJobsStatusReporter {
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.
+   * @param {import("./types.js").PooledRunnerFailure} [args.runnerFailure] - Pooled-child process failure provenance.
    * @param {number} [args.maxDurationMs] - Max duration for retries.
    * @param {boolean} [args.retryPersistErrors] - Retry a `BackgroundJobUpdateError` (main's `job-update-error`, i.e. a transient DB failure while persisting the terminal status) instead of throwing immediately. Off by default so short-lived forked/spawned runners keep failing loudly and exit non-zero to be reclaimed; on for the long-lived worker, which cannot exit-to-reclaim and would otherwise strand the job in `handed_off`.
    * @returns {Promise<void>} - Resolves when reported.
    */
-  async reportWithRetry({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, maxDurationMs, retryPersistErrors = false}) {
+  async reportWithRetry({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure, maxDurationMs, retryPersistErrors = false}) {
     let attempt = 0
     const startTime = Date.now()
 
     while (true) {
       try {
-        await this.report({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId})
+        await this.report({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure})
         return
       } catch (error) {
         // A `BackgroundJobUpdateError` means main answered `job-update-error`, which it

package/build/background-jobs/types.js

@@ -6,6 +6,39 @@
 /** @typedef {"candidate" | "active" | "retired"} BackgroundJobsGenerationInitialState */
 /** @typedef {"starting" | "candidate" | "active" | "retiring" | "retired" | "stopped"} BackgroundJobsGenerationLifecycleState */
 /** @typedef {"missing-generation" | "unexpected-generation" | "malformed-generation" | "generation-mismatch" | "worker-admission-retired" | "worker-has-no-recoverable-handoffs"} BackgroundJobsGenerationRejectionReason */
+/** @typedef {"exit" | "process-error" | "ipc-send"} PooledRunnerFailureOrigin */
+/** @typedef {"starting" | "running" | "retiring"} PooledRunnerLifecycleState */
+/** @typedef {"unexpected" | "job-timeout" | "worker-shutdown-timeout"} PooledRunnerTerminationReason */
+/** @typedef {"running" | "retiring" | "stopping"} BackgroundJobsWorkerLifecycleState */
+/**
+ * @typedef {object} PooledRunnerActiveJob
+ * @property {string | null} handoffId - Durable handoff lease id.
+ * @property {number | null} handedOffAtMs - Durable handoff timestamp.
+ * @property {string} jobId - Durable background job id.
+ * @property {string} jobName - Registered job class name.
+ * @property {string} workerId - Worker identity persisted with the handoff.
+ */
+/**
+ * One process-failure snapshot shared by every job lost with a pooled child.
+ * @typedef {object} PooledRunnerFailure
+ * @property {PooledRunnerActiveJob[]} activeJobs - Jobs that were in flight when the child failed, ordered by job id.
+ * @property {number | null} exitCode - Child exit code, or null for signal/process errors.
+ * @property {string | null} generationId - Release generation identity, or null in legacy mode.
+ * @property {boolean | null} oomKilled - False when the observed exit rules OOM out; null when an unexpected SIGKILL cannot be distinguished from an OOM kill without supervisor/kernel evidence.
+ * @property {PooledRunnerFailureOrigin} origin - Worker observation that initiated failure handling.
+ * @property {number} runnerAgeMs - Child age when failure handling started.
+ * @property {number} runnerCreatedAtMs - Child creation timestamp.
+ * @property {boolean} runnerDetached - Whether the runner owned a detached process group.
+ * @property {number} runnerJobsRun - Previously acknowledged jobs handled by the child.
+ * @property {PooledRunnerLifecycleState} runnerLifecycle - Child lifecycle immediately before recovery.
+ * @property {number | null} runnerPid - Child process id when available.
+ * @property {import("node:child_process").ChildProcess["signalCode"]} signal - Child termination signal when available.
+ * @property {PooledRunnerTerminationReason} terminationReason - Why the worker expected or did not expect termination.
+ * @property {string | null} timeoutJobId - Job whose timeout initiated child termination, or null.
+ * @property {string} workerId - Stable generation-qualified worker id.
+ * @property {BackgroundJobsWorkerLifecycleState} workerLifecycle - Parent worker lifecycle immediately before recovery.
+ * @property {number} workerPid - Parent worker process id.
+ */
 /**
  * @typedef {object} LocalBackgroundJobsClock
  * @property {() => number} now - Current epoch milliseconds.
@@ -140,6 +173,7 @@
  * @property {string | undefined} handoffId - Handoff lease id from the worker report.
  * @property {number | undefined} handedOffAtMs - Handoff timestamp from the worker report.
  * @property {string | undefined} workerId - Worker id from the worker report.
+ * @property {PooledRunnerFailure | undefined} runnerFailure - Shared pooled-child process failure provenance.
  */
 /**
  * @typedef {"worker" | "client" | "reporter"} BackgroundJobSocketRole
@@ -162,7 +196,7 @@
  * @typedef {{type: "cancel-scheduled-error", error?: string}} BackgroundJobCancelScheduledErrorMessage
  * @typedef {{type: "job", payload: BackgroundJobPayload}} BackgroundJobJobMessage
  * @typedef {{type: "job-complete", jobId: string, handoffId?: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobCompleteMessage
- * @typedef {{type: "job-failed", jobId: string, error?: ReturnType<typeof JSON.parse>, handoffId?: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobFailedMessage
+ * @typedef {{type: "job-failed", jobId: string, error?: ReturnType<typeof JSON.parse>, handoffId?: string, workerId?: string, handedOffAtMs?: number, runnerFailure?: PooledRunnerFailure}} BackgroundJobFailedMessage
  * @typedef {{type: "job-reschedule", jobId: string, delayMs: number, handoffId?: string, workerId?: string, handedOffAtMs?: number}} BackgroundJobRescheduleMessage
  * @typedef {{type: "job-updated", jobId: string}} BackgroundJobUpdatedMessage
  * @typedef {{type: "job-update-error", jobId: string, error?: string}} BackgroundJobUpdateErrorMessage

package/build/background-jobs/worker.js

@@ -22,6 +22,26 @@ import BackgroundJobsGenerationHandshakeTimeoutError, { DEFAULT_GENERATION_HANDS
  * @property {ReturnType<typeof setTimeout> | null} timer - The pending timeout timer, cleared on exit.
  * @property {ReturnType<typeof setTimeout> | null} sigkillTimer - The pending SIGKILL grace timer, cleared on exit.
  */
+/**
+ * @typedef {object} PooledJobEntry
+ * @property {import("./types.js").BackgroundJobPayload & {id: string}} payload - Durable job payload.
+ * @property {(value: void) => void} [resolve] - Completion resolver.
+ * @property {Promise<void>} [pooledJob] - Tracked pooled-job promise.
+ * @property {ReturnType<typeof setTimeout> | null} [timeoutTimer] - Per-job timeout timer.
+ */
+/**
+ * @typedef {object} PooledChildState
+ * @property {number} createdAtMs - Child creation timestamp.
+ * @property {number} jobsRun - Acknowledged jobs completed by this child.
+ * @property {Map<string, PooledJobEntry>} inflight - Jobs currently owned by this child.
+ * @property {number} lastDispatchSeq - Round-robin dispatch sequence.
+ * @property {boolean} retiring - Whether this child is draining before retirement.
+ * @property {boolean} [started] - Whether the child completed its startup handshake.
+ * @property {boolean} [settling] - Whether failure handling already owns this child.
+ * @property {ReturnType<typeof setTimeout> | null} [timeoutSigkillTimer] - Pending timeout SIGKILL timer.
+ * @property {import("./types.js").PooledRunnerTerminationReason} [terminationReason] - Expected termination reason.
+ * @property {string} [timeoutJobId] - Job whose timeout initiated termination.
+ */
 /** Grace period after SIGTERM before a lingering process runner is SIGKILLed. */
 const FORKED_CHILD_SIGKILL_GRACE_MS = 5000
 /**
@@ -234,7 +254,7 @@ export default class BackgroundJobsWorker {
     this.pooledJobQueueTrackers = new Map()
     /** @type {Set<import("node:child_process").ChildProcess>} */
     this.pooledChildren = new Set()
-    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, pooledJob?: Promise<void>, timeoutTimer?: ReturnType<typeof setTimeout> | null}>, lastDispatchSeq: number, retiring: boolean, started?: boolean, settling?: boolean, timeoutSigkillTimer?: ReturnType<typeof setTimeout> | null}>} */
+    /** @type {Map<import("node:child_process").ChildProcess, PooledChildState>} */
     this.pooledChildStates = new Map()
     /** @type {WeakSet<Promise<void>>} */
     this._pooledStartupFailureJobs = new WeakSet()
@@ -511,6 +531,11 @@ export default class BackgroundJobsWorker {
     if (this.inflightProcessChildren.size === 0) return
 
     for (const child of this.inflightProcessChildren) {
+      const pooledState = this.pooledChildStates.get(child)
+      if (pooledState && pooledState.inflight.size > 0 && !pooledState.terminationReason) {
+        pooledState.terminationReason = "worker-shutdown-timeout"
+      }
+
       try {
         child.kill("SIGTERM")
       } catch {
@@ -1046,7 +1071,7 @@ export default class BackgroundJobsWorker {
     try {
       child.send({type: "job", payload, sharedTransactionBroker: this._pooledJobSharedTransactionBrokerConfig()})
     } catch (error) {
-      void this._handlePooledChildFailure({child, error})
+      void this._handlePooledChildFailure({child, error, origin: "ipc-send"})
     }
 
     return pooledJob
@@ -1131,7 +1156,10 @@ export default class BackgroundJobsWorker {
     const state = this.pooledChildStates.get(child)
 
     // Already settling/gone, or the job finished in the race with this timer.
-    if (!state || state.settling || !state.inflight.has(jobId)) return
+    if (!state || state.settling || state.terminationReason || !state.inflight.has(jobId)) return
+
+    state.terminationReason = "job-timeout"
+    state.timeoutJobId = jobId
 
     try {
       child.kill("SIGTERM")
@@ -1163,8 +1191,20 @@ export default class BackgroundJobsWorker {
     this.inflightProcessChildren.add(child)
     this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), lastDispatchSeq: 0, retiring: false, started: false})
     child.on("message", (message) => this._handlePooledChildMessage({child, message}))
-    child.once("exit", (code, signal) => this._handlePooledChildFailure({child, error: new Error(`Pooled background job runner exited: code=${code} signal=${signal || "none"}`)}))
-    child.once("error", (error) => this._handlePooledChildFailure({child, error}))
+    child.once("exit", (exitCode, signal) => this._handlePooledChildFailure({
+      child,
+      error: new Error(`Pooled background job runner exited: code=${exitCode} signal=${signal || "none"}`),
+      exitCode,
+      origin: "exit",
+      signal
+    }))
+    child.once("error", (error) => this._handlePooledChildFailure({
+      child,
+      error,
+      exitCode: child.exitCode,
+      origin: "process-error",
+      signal: child.signalCode
+    }))
     return child
   }
 
@@ -1271,9 +1311,12 @@ export default class BackgroundJobsWorker {
    * @param {object} args - Failure details.
    * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
    * @param {ReturnType<typeof JSON.parse>} args.error - Failure.
+   * @param {number | null} [args.exitCode] - Child exit code when observed.
+   * @param {import("./types.js").PooledRunnerFailureOrigin} [args.origin] - Worker observation that initiated recovery.
+   * @param {import("node:child_process").ChildProcess["signalCode"]} [args.signal] - Child termination signal when observed.
    * @returns {Promise<void>}
    */
-  async _handlePooledChildFailure({child, error}) {
+  async _handlePooledChildFailure({child, error, exitCode = null, origin = "process-error", signal = null}) {
     const state = this.pooledChildStates.get(child)
     if (state?.settling) return
     if (state) {
@@ -1289,6 +1332,9 @@ export default class BackgroundJobsWorker {
     this.inflightProcessChildren.delete(child)
 
     const entries = state ? [...state.inflight.values()] : []
+    const runnerFailure = state
+      ? this._pooledRunnerFailure({child, exitCode, origin, signal, state})
+      : undefined
     if (state) state.inflight.clear()
     this.pooledChildStates.delete(child)
 
@@ -1299,6 +1345,7 @@ export default class BackgroundJobsWorker {
         error,
         handoffId: entry.payload.handoffId,
         handedOffAtMs: entry.payload.handedOffAtMs,
+        runnerFailure,
         workerId: entry.payload.workerId || this.workerId
       })
       if (entry.resolve) entry.resolve(undefined)
@@ -1326,6 +1373,51 @@ export default class BackgroundJobsWorker {
     await Promise.allSettled(failureReports)
   }
 
+  /**
+   * Captures one stable process snapshot before the failed child's state is removed.
+   * @param {object} args - Failure details.
+   * @param {import("node:child_process").ChildProcess} args.child - Failed pooled child.
+   * @param {number | null} args.exitCode - Child exit code when observed.
+   * @param {import("./types.js").PooledRunnerFailureOrigin} args.origin - Worker observation that initiated recovery.
+   * @param {import("node:child_process").ChildProcess["signalCode"]} args.signal - Child termination signal when observed.
+   * @param {PooledChildState} args.state - Child state immediately before recovery.
+   * @returns {import("./types.js").PooledRunnerFailure} - Shared failure provenance.
+   */
+  _pooledRunnerFailure({child, exitCode, origin, signal, state}) {
+    const terminationReason = state.terminationReason ?? "unexpected"
+    const workerLifecycle = this.shouldStop ? "stopping" : this.isRetiring ? "retiring" : "running"
+    const runnerLifecycle = state.started === false ? "starting" : state.retiring ? "retiring" : "running"
+    const activeJobs = [...state.inflight.values()]
+      .map((entry) => ({
+        handoffId: entry.payload.handoffId ?? null,
+        handedOffAtMs: entry.payload.handedOffAtMs ?? null,
+        jobId: entry.payload.id,
+        jobName: entry.payload.jobName,
+        workerId: entry.payload.workerId ?? this.workerId
+      }))
+      .sort((left, right) => left.jobId.localeCompare(right.jobId))
+
+    return Object.freeze({
+      activeJobs,
+      exitCode,
+      generationId: this.generationId ?? null,
+      oomKilled: signal === "SIGKILL" && terminationReason === "unexpected" ? null : false,
+      origin,
+      runnerAgeMs: Math.max(0, Date.now() - state.createdAtMs),
+      runnerCreatedAtMs: state.createdAtMs,
+      runnerDetached: false,
+      runnerJobsRun: state.jobsRun,
+      runnerLifecycle,
+      runnerPid: child.pid ?? null,
+      signal,
+      terminationReason,
+      timeoutJobId: state.timeoutJobId ?? null,
+      workerId: this.workerId,
+      workerLifecycle,
+      workerPid: process.pid
+    })
+  }
+
   /**
    * Runs run job inline.
    * @param {import("./types.js").BackgroundJobPayload} payload - Payload.
@@ -1655,9 +1747,10 @@ export default class BackgroundJobsWorker {
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.
+   * @param {import("./types.js").PooledRunnerFailure} [args.runnerFailure] - Pooled-child process failure provenance.
    * @returns {Promise<void>} - Resolves when reported.
    */
-  async _reportJobResult({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId}) {
+  async _reportJobResult({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure}) {
     if (!this.statusReporter) return
 
     try {
@@ -1665,7 +1758,7 @@ export default class BackgroundJobsWorker {
       // long-lived and cannot exit to trigger orphan reclaim, so dropping the
       // completion here would strand the job in `handed_off` forever — fatal for a
       // `max_concurrency: 1` job (a stranded row blocks every future run).
-      await this.statusReporter.reportWithRetry({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, retryPersistErrors: true})
+      await this.statusReporter.reportWithRetry({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure, retryPersistErrors: true})
     } catch (reportError) {
       console.error("Background job status reporting failed:", reportError)
     }
@@ -1683,15 +1776,16 @@ export default class BackgroundJobsWorker {
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.
+   * @param {import("./types.js").PooledRunnerFailure} [args.runnerFailure] - Pooled-child process failure provenance.
    * @returns {void}
    */
-  _reportJobResultInBackground({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId}) {
+  _reportJobResultInBackground({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure}) {
     /**
      * Defines report.
      * @type {Promise<void>} */
     let report
 
-    report = this._reportJobResult({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId}).finally(() => {
+    report = this._reportJobResult({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure}).finally(() => {
       this.inflightReports.delete(report)
     })
 

package/build/frontend-models/base.js

@@ -1779,6 +1779,17 @@ function frontendModelRequestContext() {
   return captureFrontendModelRemoteRequestContext(configuredContext)
 }
 
+/**
+ * Captures the explicit lifecycle context or falls back to the configured transport context.
+ * @param {import("../remote-request-context.js").RemoteRequestContext | undefined} requestContext - Registration-local context.
+ * @returns {import("../remote-request-context.js").RemoteRequestContext} Frozen context snapshot.
+ */
+function frontendModelEventRequestContext(requestContext) {
+  if (requestContext === undefined) return frontendModelRequestContext()
+
+  return captureFrontendModelRemoteRequestContext(requestContext)
+}
+
 /**
  * Runs ensure frontend model instance listener.
  * @param {FrontendModelEventSubscription} sub - Event subscription bucket.
@@ -1799,6 +1810,27 @@ function ensureFrontendModelInstanceListener(sub, id, instance) {
   return listener
 }
 
+/**
+ * Removes one instance callback entry and tears down an empty listener/subscription bucket.
+ * @param {FrontendModelEventSubscription} sub - Event subscription bucket.
+ * @param {string} id - Model id.
+ * @param {(listener: {instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}) => void} removeEntry - Callback entry removal.
+ * @returns {void}
+ */
+function removeFrontendModelInstanceListenerEntry(sub, id, removeEntry) {
+  const current = sub.instanceListeners.get(id)
+
+  if (!current) return
+
+  removeEntry(current)
+
+  if (current.updateCallbacks.size === 0 && current.destroyCallbacks.size === 0) {
+    sub.instanceListeners.delete(id)
+  }
+
+  sub.maybeTeardown()
+}
+
 /**
  * Runs frontend model command url.
  * @param {string} resourcePath - Resource path prefix.
@@ -3723,8 +3755,9 @@ export default class FrontendModelBase {
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
   static async onCreate(callback, options = {}) {
-    const sub = ensureFrontendModelEventSubscription(this, frontendModelRequestContext())
-    const entry = {callback, ...frontendModelEventOptionsPayload(this, options)}
+    const {requestContext, ...eventOptionsPayload} = frontendModelEventOptionsPayload(this, options)
+    const sub = ensureFrontendModelEventSubscription(this, frontendModelEventRequestContext(requestContext))
+    const entry = {callback, ...eventOptionsPayload}
 
     return await sub.registerClassCallback(sub.classCreateCallbacks, entry)
   }
@@ -3737,8 +3770,9 @@ export default class FrontendModelBase {
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
   static async onUpdate(callback, options = {}) {
-    const sub = ensureFrontendModelEventSubscription(this, frontendModelRequestContext())
-    const entry = {callback, ...frontendModelEventOptionsPayload(this, options)}
+    const {requestContext, ...eventOptionsPayload} = frontendModelEventOptionsPayload(this, options)
+    const sub = ensureFrontendModelEventSubscription(this, frontendModelEventRequestContext(requestContext))
+    const entry = {callback, ...eventOptionsPayload}
 
     return await sub.registerClassCallback(sub.classUpdateCallbacks, entry)
   }
@@ -3753,7 +3787,8 @@ export default class FrontendModelBase {
   static async onDestroy(callback, options = {}) {
     assertNoDestroyEventFilter(this, options)
 
-    const sub = ensureFrontendModelEventSubscription(this, frontendModelRequestContext())
+    const {requestContext} = frontendModelEventOptionsPayload(this, options)
+    const sub = ensureFrontendModelEventSubscription(this, frontendModelEventRequestContext(requestContext))
     const entry = {callback}
 
     return await sub.registerClassCallback(sub.classDestroyCallbacks, entry)
@@ -3771,24 +3806,23 @@ export default class FrontendModelBase {
   async onUpdate(callback, options = {}) {
     const self = /** @type {ReturnType<typeof JSON.parse>} */ (this)
     const ModelClass = frontendModelClassFor(this)
-    const sub = ensureFrontendModelEventSubscription(ModelClass, frontendModelRequestContext())
+    const {requestContext, ...eventOptionsPayload} = frontendModelEventOptionsPayload(ModelClass, options)
+    const sub = ensureFrontendModelEventSubscription(ModelClass, frontendModelEventRequestContext(requestContext))
     const id = String(self.id())
-    const entry = {callback, ...frontendModelEventOptionsPayload(ModelClass, options)}
+    const entry = {callback, ...eventOptionsPayload}
     const listener = ensureFrontendModelInstanceListener(sub, id, this)
 
     listener.updateCallbacks.add(entry)
-    await sub.ensureSubscribed()
-
-    return () => {
-      const current = sub.instanceListeners.get(id)
 
-      if (!current) return
-      current.updateCallbacks.delete(entry)
+    try {
+      await sub.ensureSubscribed()
+    } catch (error) {
+      removeFrontendModelInstanceListenerEntry(sub, id, (current) => current.updateCallbacks.delete(entry))
+      throw error
+    }
 
-      if (current.updateCallbacks.size === 0 && current.destroyCallbacks.size === 0) {
-        sub.instanceListeners.delete(id)
-      }
-      sub.maybeTeardown()
+    return () => {
+      removeFrontendModelInstanceListenerEntry(sub, id, (current) => current.updateCallbacks.delete(entry))
     }
   }
 
@@ -3804,24 +3838,23 @@ export default class FrontendModelBase {
 
     assertNoDestroyEventFilter(ModelClass, options)
 
-    const sub = ensureFrontendModelEventSubscription(ModelClass, frontendModelRequestContext())
+    const {requestContext} = frontendModelEventOptionsPayload(ModelClass, options)
+    const sub = ensureFrontendModelEventSubscription(ModelClass, frontendModelEventRequestContext(requestContext))
     const id = String(self.id())
     const entry = {callback}
     const listener = ensureFrontendModelInstanceListener(sub, id, this)
 
     listener.destroyCallbacks.add(entry)
-    await sub.ensureSubscribed()
 
-    return () => {
-      const current = sub.instanceListeners.get(id)
-
-      if (!current) return
-      current.destroyCallbacks.delete(entry)
+    try {
+      await sub.ensureSubscribed()
+    } catch (error) {
+      removeFrontendModelInstanceListenerEntry(sub, id, (current) => current.destroyCallbacks.delete(entry))
+      throw error
+    }
 
-      if (current.updateCallbacks.size === 0 && current.destroyCallbacks.size === 0) {
-        sub.instanceListeners.delete(id)
-      }
-      sub.maybeTeardown()
+    return () => {
+      removeFrontendModelInstanceListenerEntry(sub, id, (current) => current.destroyCallbacks.delete(entry))
     }
   }
 

package/build/frontend-models/query.js

@@ -39,9 +39,15 @@ import isPlainObject from "../utils/plain-object.js"
  * @property {string[] | Record<string, string[]>} [abilities] - Ability actions to compute per record.
  * @property {string | Array<string | Record<string, FrontendModelTransportValue>> | Record<string, FrontendModelTransportValue>} [queryData] - Backend query data names/spec.
  */
+/**
+ * FrontendModelEventRoutingOptions type.
+ * @typedef {object} FrontendModelEventRoutingOptions
+ * @property {FrontendModelQuery<import("./base.js").FrontendModelClass>} [query] - Query whose filters match events and whose projections shape event records.
+ * @property {import("../remote-request-context.js").RemoteRequestContext} [requestContext] - Registration-local remote routing context. Its captured value partitions lifecycle server subscriptions and replaces the transport-wide context for this registration.
+ */
 /**
  * Defines this typedef.
- * @typedef {FrontendModelProjectionOptions & {query?: FrontendModelQuery<import("./base.js").FrontendModelClass>}} FrontendModelEventOptionsObject
+ * @typedef {FrontendModelProjectionOptions & FrontendModelEventRoutingOptions} FrontendModelEventOptionsObject
  */
 /**
  * FrontendModelEventOptions type.
@@ -69,12 +75,16 @@ import isPlainObject from "../utils/plain-object.js"
  * @typedef {FrontendModelEventFilterPayload & {key: string}} FrontendModelEventFilterPayloadEntry
  */
 /**
- * FrontendModelEventOptionsPayload type.
- * @typedef {object} FrontendModelEventOptionsPayload
+ * FrontendModelEventQueryPayload type.
+ * @typedef {object} FrontendModelEventQueryPayload
  * @property {string | null} eventFilterKey - Stable event filter key, or null when no filter is present.
  * @property {FrontendModelEventFilterPayload | null} eventFilterPayload - Normalized event filter payload, or null when unfiltered.
  * @property {FrontendModelProjectionPayload} projectionPayload - Normalized event serialization projection payload.
  */
+/**
+ * FrontendModelEventOptionsPayload type.
+ * @typedef {FrontendModelEventQueryPayload & {requestContext: import("../remote-request-context.js").RemoteRequestContext | undefined}} FrontendModelEventOptionsPayload
+ */
 /**
  * FrontendModelSort type.
  * @typedef {object} FrontendModelSort
@@ -1829,7 +1839,7 @@ export default class FrontendModelQuery {
 
   /**
    * Returns the eventOptionsPayload result.
-   * @returns {FrontendModelEventOptionsPayload} - Combined event filter and projection payload.
+   * @returns {FrontendModelEventQueryPayload} - Combined event filter and projection payload.
    */
   eventOptionsPayload() {
     const eventFilterPayload = this.eventFilterPayload()
@@ -2236,5 +2246,10 @@ function frontendModelEventQuery(modelClass, options = {}) {
  * @returns {FrontendModelEventOptionsPayload} - Normalized event subscription payload.
  */
 export function frontendModelEventOptionsPayload(modelClass, options = {}) {
-  return frontendModelEventQuery(modelClass, options).eventOptionsPayload()
+  const requestContext = options instanceof FrontendModelQuery ? undefined : options.requestContext
+
+  return {
+    ...frontendModelEventQuery(modelClass, options).eventOptionsPayload(),
+    requestContext
+  }
 }

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

@@ -1,6 +1,6 @@
 // @ts-check
 
-import {captureRemoteRequestContext, mergeRemoteRequestContext} from "../remote-request-context.js"
+import {captureRemoteRequestContext, mergeRemoteRequestContext, remoteRequestContextKey} from "../remote-request-context.js"
 
 const RESERVED_KEYS = ["commandType", "customPath", "model", "payload", "requestContext", "requestId", "requests"]
 const REQUEST_CONTEXT_LABEL = "Frontend model request context"
@@ -17,6 +17,18 @@ export function captureFrontendModelRemoteRequestContext(value) {
   })
 }
 
+/**
+ * Builds the canonical identity for one frontend-model remote request context.
+ * @param {ReturnType<typeof JSON.parse> | undefined} value - Context value.
+ * @returns {string} Stable serialized context key.
+ */
+export function frontendModelRemoteRequestContextKey(value) {
+  return JSON.stringify({
+    context: remoteRequestContextKey(captureFrontendModelRemoteRequestContext(value)),
+    present: value !== undefined
+  })
+}
+
 /**
  * Merges captured context into frontend-model command or subscription params.
  * @template {Record<string, ReturnType<typeof JSON.parse>>} TParams