velocious 1.0.658 → 1.0.660

package/README.md

@@ -879,7 +879,7 @@ Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle
 Frontend-model HTTP requests always use `credentials: "include"` so shared custom commands can set session cookies without app-level transport overrides.
 
 Unexpected frontend-model endpoint failures return their original message and full stack trace by default in every environment, including production. Responses use `errorType: "internal_error"`, a server-generated `correlationId` shared with the matching framework-error report, and the established `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields without adding irrelevant debug fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
-Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors.
+Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors. Shared index payloads reject unknown top-level keys per request, including wrapper nesting such as `payload.query.where`; use `payload.where` directly.
 Invalid frontend-model write attributes and attachment names, including attributes rejected by `permittedParams()`, return the specific safe error message with `velocious.code: "frontend-model-attribute-error"` and are not emitted as framework errors.
 To mask unexpected internal details, explicitly opt out for the application configuration:
 
@@ -2442,6 +2442,16 @@ the new main. Deploy and HTTP/WebSocket drain completion are independent of this
 potentially hours-long lifecycle. See [release-generation
 draining](docs/background-jobs.md#release-generation-draining).
 
+Jobs that remain owned by a retired generation may still use the unchanged
+`performLater()` / `performLaterWithOptions()` APIs to create follow-up work.
+Velocious carries the producer's exact handoff through its asynchronous
+execution context and atomically validates that lease with insertion or queued
+deduplication. Each call has its own internal replay identity, so two identical
+calls create distinct jobs unless the caller explicitly requests queued
+deduplication or durable idempotency. The retired main commits and wakes the
+queue but never dispatches the follow-up; the active generation owns that work.
+Ordinary retired enqueue, replace, and cancel requests remain rejected.
+
 Velocious provides the opt-in generation protocol; production still requires a
 supervisor that preserves old generation units and release pins, and a deploy
 coordinator that retires the old generation before activating the healthy

package/build/background-jobs/adapter.js

@@ -14,6 +14,14 @@ export default class BackgroundJobsAdapter {
    */
   supportsReleaseScopedGenerations() { return false }
 
+  /**
+   * Declares atomic producer-handoff validation plus enqueue support. A
+   * generation-capable adapter must override this together with
+   * `enqueueFromOwnedHandoff`.
+   * @returns {boolean} - Whether atomic owned enqueue is supported.
+   */
+  supportsOwnedEnqueueFromHandoff() { return false }
+
   /**
    * Ensures the adapter can accept work.
    * @returns {Promise<void>} - Resolves when ready.
@@ -64,6 +72,13 @@ export default class BackgroundJobsAdapter {
    */
   async enqueue(_args) { throw new Error("BackgroundJobsAdapter#enqueue is not implemented") }
 
+  /**
+   * Atomically validates an exact producing handoff and enqueues its follow-up.
+   * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions, producerInvocationId?: string, producerProof: import("./types.js").BackgroundJobProducerProof}} _args - Owned enqueue request.
+   * @returns {Promise<string>} - Job id.
+   */
+  async enqueueFromOwnedHandoff(_args) { throw new Error("BackgroundJobsAdapter#enqueueFromOwnedHandoff is not implemented") }
+
   /**
    * Replaces the owner of a stable schedule key.
    * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Replacement request.

package/build/background-jobs/client.js

@@ -44,9 +44,11 @@ export default class BackgroundJobsClient {
    * @param {string} args.jobName - Job name.
    * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @param {string} [args.producerInvocationId] - Stable identity for one owned enqueue invocation.
+   * @param {import("./types.js").BackgroundJobProducerProof} [args.producerProof] - Exact internal producer handoff.
    * @returns {Promise<string>} - Job id.
    */
-  async enqueue({jobName, args, options}) {
+  async enqueue({jobName, args, options, producerInvocationId, producerProof}) {
     const request = await this._request()
 
     return await timeout({
@@ -59,7 +61,9 @@ export default class BackgroundJobsClient {
           type: "enqueue",
           jobName,
           args,
-          options
+          options,
+          ...(producerInvocationId ? {producerInvocationId} : {}),
+          ...(producerProof ? {producerProof} : {})
         })
       },
       onMessage: ({message, resolve, reject}) => {

package/build/background-jobs/execution-context.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { AsyncLocalStorage } from "node:async_hooks"
+
+/** @type {AsyncLocalStorage<import("./types.js").BackgroundJobProducerProof>} */
+const producerProofStorage = new AsyncLocalStorage()
+
+/**
+ * Returns the exact producer handoff for the current asynchronous job chain.
+ * @returns {import("./types.js").BackgroundJobProducerProof | undefined} - Current producer proof.
+ */
+export function currentBackgroundJobProducerProof() {
+  return producerProofStorage.getStore()
+}
+
+/**
+ * Runs one job-owned asynchronous chain with an immutable producer proof.
+ * @template T
+ * @param {import("./types.js").BackgroundJobProducerProof} producerProof - Exact producer handoff.
+ * @param {() => T} callback - Job-owned work.
+ * @returns {T} - Callback result.
+ */
+export function runWithBackgroundJobProducerProof(producerProof, callback) {
+  return producerProofStorage.run(Object.freeze({...producerProof}), callback)
+}
+
+/**
+ * Runs under a payload's exact lease when all fencing fields are present.
+ * Legacy payloads without a complete lease retain their existing behavior.
+ * @template T
+ * @param {import("./types.js").BackgroundJobPayload} payload - Persisted runner payload.
+ * @param {() => T} callback - Job-owned work.
+ * @returns {T} - Callback result.
+ */
+export function runWithBackgroundJobPayload(payload, callback) {
+  const handedOffAtMs = payload.handedOffAtMs
+  if (!payload.id || !payload.handoffId || !payload.workerId || handedOffAtMs === undefined || !Number.isSafeInteger(handedOffAtMs)) {
+    return callback()
+  }
+
+  return runWithBackgroundJobProducerProof({
+    handedOffAtMs,
+    handoffId: payload.handoffId,
+    jobId: payload.id,
+    workerId: payload.workerId
+  }, callback)
+}

package/build/background-jobs/job-runner.js

@@ -4,6 +4,7 @@ import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobRegistry from "./job-registry.js"
 import BackgroundJobsStatusReporter from "./status-reporter.js"
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import { runWithBackgroundJobPayload } from "./execution-context.js"
 import { closeRunnerConnections } from "./runner-graceful-shutdown.js"
 
 const BEACON_READY_TIMEOUT_MS = 5000
@@ -116,8 +117,10 @@ export default async function runJobPayload(payload, {closeConnections = true, m
 
   try {
     try {
-      await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
-        await perform.apply(jobInstance, jobArgs)
+      await runWithBackgroundJobPayload(payload, async () => {
+        await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
+          await perform.apply(jobInstance, jobArgs)
+        })
       })
     } catch (error) {
       if (error instanceof BackgroundJobRescheduleSignal) {

package/build/background-jobs/job.js

@@ -1,6 +1,9 @@
 // @ts-check
 
+import { randomUUID } from "node:crypto"
+
 import configurationResolver from "../configuration-resolver.js"
+import { currentBackgroundJobProducerProof } from "./execution-context.js"
 import PlatformVelociousJob from "./platform-job.js"
 import {
   cancelScheduledBackgroundJobForConfiguration,
@@ -24,8 +27,16 @@ export default class VelociousJob extends PlatformVelociousJob {
   static async performLater(...args) {
     const configuration = await configurationResolver()
     const {jobArgs, jobOptions} = this._splitArgsAndOptions(args)
+    const producerProof = currentBackgroundJobProducerProof()
 
-    return await enqueueBackgroundJobForConfiguration({configuration, JobClass: this, jobArgs, jobOptions})
+    return await enqueueBackgroundJobForConfiguration({
+      configuration,
+      JobClass: this,
+      jobArgs,
+      jobOptions,
+      producerProof,
+      producerInvocationId: producerProof ? randomUUID() : undefined
+    })
   }
 
   /**
@@ -37,8 +48,16 @@ export default class VelociousJob extends PlatformVelociousJob {
    */
   static async performLaterWithOptions({args, options}) {
     const configuration = await configurationResolver()
+    const producerProof = currentBackgroundJobProducerProof()
 
-    return await enqueueBackgroundJobForConfiguration({configuration, JobClass: this, jobArgs: args, jobOptions: options})
+    return await enqueueBackgroundJobForConfiguration({
+      configuration,
+      JobClass: this,
+      jobArgs: args,
+      jobOptions: options,
+      producerProof,
+      producerInvocationId: producerProof ? randomUUID() : undefined
+    })
   }
 
   /**

package/build/background-jobs/main.js

@@ -201,7 +201,7 @@ export default class BackgroundJobsMain {
     this._pollTimer = undefined
     /**
      * Narrows the runtime value to the documented type.
-     * @type {ReturnType<typeof setTimeout> | undefined} */
+     * @type {ReturnType<typeof setTimeout> | number | undefined} */
     this._scheduledTimer = undefined
     /**
      * Narrows the runtime value to the documented type.
@@ -291,6 +291,9 @@ export default class BackgroundJobsMain {
       if (this.generationId && !this.adapter.supportsReleaseScopedGenerations()) {
         throw new Error("The configured background jobs adapter does not support release-scoped generations")
       }
+      if (this.generationId && !this.adapter.supportsOwnedEnqueueFromHandoff()) {
+        throw new Error("The configured background jobs adapter does not support atomic owned-handoff enqueue")
+      }
 
       if (!this.generationId || this.initialGenerationState !== "candidate") {
         this.startupHandoffSnapshot = await this._generationOwnedHandoffSnapshot()
@@ -411,7 +414,7 @@ export default class BackgroundJobsMain {
    * @returns {void} */
   _clearTimers() {
     if (this._pollTimer) clearInterval(this._pollTimer)
-    if (this._scheduledTimer) clearTimeout(this._scheduledTimer)
+    if (this._scheduledTimer) this.clock.clearTimeout(this._scheduledTimer)
     if (this._errorRetryTimer) clearTimeout(this._errorRetryTimer)
     if (this._orphanTimer) clearInterval(this._orphanTimer)
     if (this._workerStaleTimer) clearInterval(this._workerStaleTimer)
@@ -670,7 +673,7 @@ export default class BackgroundJobsMain {
   /** Clears timers that can initiate new global dispatch or schedule work. */
   _clearDispatchTimers() {
     if (this._pollTimer) clearInterval(this._pollTimer)
-    if (this._scheduledTimer) clearTimeout(this._scheduledTimer)
+    if (this._scheduledTimer) this.clock.clearTimeout(this._scheduledTimer)
     if (this._errorRetryTimer) clearTimeout(this._errorRetryTimer)
     this._pollTimer = undefined
     this._scheduledTimer = undefined
@@ -1151,10 +1154,10 @@ export default class BackgroundJobsMain {
    */
   async _handleClientSocketMessage({jsonSocket, message}) {
     if (this.generationId && (this.lifecycleState === "retiring" || this.lifecycleState === "retired")) {
-      if (message?.type === "enqueue") jsonSocket.send({type: "enqueue-error", error: "Background jobs generation is retired"})
+      if (message?.type === "enqueue" && !message.producerProof) jsonSocket.send({type: "enqueue-error", error: "Background jobs generation is retired"})
       if (message?.type === "replace-scheduled") jsonSocket.send({type: "replace-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type === "cancel-scheduled") jsonSocket.send({type: "cancel-scheduled-error", error: "Background jobs generation is retired"})
-      return
+      if (message?.type !== "enqueue" || !message.producerProof) return
     }
 
     if (message?.type === "enqueue") {
@@ -1473,15 +1476,26 @@ export default class BackgroundJobsMain {
    */
   async _handleEnqueue({jsonSocket, message}) {
     try {
-      const jobId = await this.store.enqueue({
+      if (this.generationId
+        && typeof message.producerProof?.workerId === "string"
+        && !workerIdBelongsToGeneration({generationId: this.generationId, workerId: message.producerProof.workerId})) {
+        throw VelociousError.safe("Background job producer handoff belongs to another generation.", {
+          code: "background-job-producer-generation-mismatch"
+        })
+      }
+
+      const request = {
         jobName: message.jobName,
         args: message.args || [],
         options: message.options || {}
-      })
+      }
+      const jobId = this.generationId && message.producerProof
+        ? await this.store.enqueueFromOwnedHandoff({...request, producerInvocationId: message.producerInvocationId, producerProof: message.producerProof})
+        : await this.store.enqueue(request)
 
       jsonSocket.send({type: "enqueued", jobId})
       this._notifyEnqueued()
-      await this._drain()
+      if (this.lifecycleState === "active") await this._drain()
     } catch (error) {
       this._handleClientMutationError({
         context: {jobName: message.jobName, stage: "background-job-enqueue"},
@@ -2295,7 +2309,7 @@ export default class BackgroundJobsMain {
    */
   async _armScheduledTimer() {
     if (this._scheduledTimer) {
-      clearTimeout(this._scheduledTimer)
+      this.clock.clearTimeout(this._scheduledTimer)
       this._scheduledTimer = undefined
     }
 
@@ -2318,7 +2332,7 @@ export default class BackgroundJobsMain {
 
     if (typeof delay !== "number") return
 
-    this._scheduledTimer = setTimeout(() => {
+    this._scheduledTimer = this.clock.setTimeout(() => {
       this._scheduledTimer = undefined
       void this._drain()
     }, delay)

package/build/background-jobs/runtime.js

@@ -49,9 +49,11 @@ export async function enqueueBackgroundJob({JobClass, jobArgs, jobOptions}) {
  * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
  * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
  * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @param {string} [args.producerInvocationId] - Stable identity for one owned enqueue invocation.
+ * @param {import("./types.js").BackgroundJobProducerProof} [args.producerProof] - Exact internal producer handoff.
  * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
  */
-export async function enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions}) {
+export async function enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions, producerInvocationId, producerProof}) {
   const resolvedJobOptions = JobClass._withJobContext({jobArgs, jobOptions})
 
   if (configuration.getBackgroundJobsConfig().mode === "inline") {
@@ -83,7 +85,9 @@ export async function enqueueBackgroundJobForConfiguration({configuration, JobCl
   return await client.enqueue({
     jobName: JobClass.jobName(),
     args: jobArgs,
-    options: resolvedJobOptions
+    options: resolvedJobOptions,
+    producerInvocationId,
+    producerProof
   })
 }
 

package/build/background-jobs/sql-adapter.js

@@ -10,6 +10,12 @@ export default class SqlBackgroundJobsAdapter extends BackgroundJobsStore {
    */
   supportsReleaseScopedGenerations() { return true }
 
+  /**
+   * Declares atomic owned-handoff enqueue support.
+   * @returns {boolean} - The SQL transaction validates ownership and enqueues atomically.
+   */
+  supportsOwnedEnqueueFromHandoff() { return true }
+
   /**
    * Ensures the built-in SQL schema during migration.
    * @param {{dbs: Record<string, import("../database/drivers/base.js").default>}} args - Migrated databases.