velocious 1.0.658 → 1.0.660

package/build/background-jobs/store.js

@@ -150,11 +150,15 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @param {object} args - Options.
    * @param {import("../configuration.js").default} args.configuration - Configuration.
    * @param {string} [args.databaseIdentifier] - Database identifier.
+   * @param {{now: () => number}} [args.clock] - Injectable persistence clock.
+   * @param {(producerProof: import("./types.js").BackgroundJobProducerProof) => void | Promise<void>} [args.afterOwnedProducerValidation] - Exact owned-enqueue validation hook.
    */
-  constructor({configuration, databaseIdentifier}) {
+  constructor({configuration, databaseIdentifier, clock, afterOwnedProducerValidation}) {
     super()
     this.configuration = configuration
     this.databaseIdentifier = databaseIdentifier
+    this.clock = clock || {now: () => Date.now()}
+    this.afterOwnedProducerValidation = afterOwnedProducerValidation
     this.logger = new Logger(this)
     this._readyPromise = null
     this._queueConcurrencyReconciled = false
@@ -321,23 +325,10 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
 
     await this._serializedCountMutation(async (db) => {
       if (options?.deduplicateWhileQueued) {
-        // Dedupe on the job's identity (name + args + queue), NOT its concurrency key, so a job
-        // keeps whatever concurrency it resolves to. Only an existing job scheduled no later than
-        // this enqueue can cover it; a retry backed off into the future must not suppress earlier
-        // work. Ordering returns the earliest covering job when several queued rows already exist.
-        const existing = await db
-          .newQuery()
-          .from(JOBS_TABLE)
-          .select("id")
-          .where({status: "queued", job_name: jobName, args_json: preparedJob.argsJson, queue: preparedJob.queue})
-          .where(`scheduled_at_ms <= ${db.quote(preparedJob.scheduledAtMs)}`)
-          .order("scheduled_at_ms ASC")
-          .limit(1)
-          .results()
-
-        if (existing[0]) {
-          resultJobId = String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (existing[0]).id)
+        const duplicateJobId = await this._deduplicatedQueuedJobId(db, preparedJob)
 
+        if (duplicateJobId) {
+          resultJobId = duplicateJobId
           return
         }
       }
@@ -349,6 +340,122 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     return resultJobId
   }
 
+  /**
+   * Atomically validates an exact producing handoff and enqueues its follow-up.
+   * Every exact request owns an internal durable replay identity, while queued
+   * deduplication can point several distinct producer events at one covering row.
+   * @param {object} args - Owned enqueue request.
+   * @param {string} args.jobName - Job name.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Arguments.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Options.
+   * @param {string} [args.producerInvocationId] - Stable identity for one owned enqueue invocation.
+   * @param {import("./types.js").BackgroundJobProducerProof} args.producerProof - Exact producer lease.
+   * @returns {Promise<string>} - Durable follow-up id.
+   */
+  async enqueueFromOwnedHandoff({jobName, args, options, producerInvocationId, producerProof}) {
+    await this.ensureReady()
+
+    const normalizedProducerProof = this._normalizeProducerProof(producerProof)
+    const normalizedProducerInvocationId = this._normalizeProducerInvocationId(producerInvocationId)
+    const preparedJob = this._prepareJob({jobName, args, options})
+
+    return await this._serializedCountMutation(async (db) => {
+      await this._validateOwnedProducerProof(db, normalizedProducerProof)
+      if (this.afterOwnedProducerValidation) await this.afterOwnedProducerValidation(normalizedProducerProof)
+
+      if (options?.idempotencyKey !== undefined) {
+        return await this._enqueueIdempotentlyInTransaction({
+          args: args || [],
+          countRevisionLocked: true,
+          db,
+          options,
+          preparedJob
+        })
+      }
+
+      return await this._enqueueOwnedReplayInTransaction({
+        db,
+        options: options || {},
+        preparedJob,
+        producerInvocationId: normalizedProducerInvocationId,
+        producerProof: normalizedProducerProof
+      })
+    })
+  }
+
+  /**
+   * Finds the earliest queued job that covers this enqueue's identity and time.
+   * @param {import("../database/drivers/base.js").default} db - Transaction connection.
+   * @param {PreparedBackgroundJob} preparedJob - Normalized job.
+   * @returns {Promise<string | null>} - Covering job id.
+   */
+  async _deduplicatedQueuedJobId(db, preparedJob) {
+    // Dedupe on the job's identity (name + args + queue), NOT its concurrency key, so a job
+    // keeps whatever concurrency it resolves to. Only an existing job scheduled no later than
+    // this enqueue can cover it; a retry backed off into the future must not suppress earlier
+    // work. Ordering returns the earliest covering job when several queued rows already exist.
+    const existing = await db
+      .newQuery()
+      .from(JOBS_TABLE)
+      .select("id")
+      .where({status: "queued", job_name: preparedJob.jobName, args_json: preparedJob.argsJson, queue: preparedJob.queue})
+      .where(`scheduled_at_ms <= ${db.quote(preparedJob.scheduledAtMs)}`)
+      .order("scheduled_at_ms ASC")
+      .limit(1)
+      .results()
+    const row = existing[0]
+
+    return row ? String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row).id) : null
+  }
+
+  /**
+   * Persists one internal exact-replay owner and its queued job in the caller's
+   * producer-validation transaction.
+   * @param {object} args - Transaction input.
+   * @param {import("../database/drivers/base.js").default} args.db - Transaction connection.
+   * @param {import("./types.js").BackgroundJobOptions} args.options - Enqueue options.
+   * @param {PreparedBackgroundJob} args.preparedJob - Normalized job.
+   * @param {string} args.producerInvocationId - Stable identity for one owned enqueue invocation.
+   * @param {import("./types.js").BackgroundJobProducerProof} args.producerProof - Exact producer lease.
+   * @returns {Promise<string>} - Stable replay job id.
+   */
+  async _enqueueOwnedReplayInTransaction({db, options, preparedJob, producerInvocationId, producerProof}) {
+    const requestDigest = this._ownedEnqueueRequestDigest({options, preparedJob})
+    const scopeDigest = this._ownedEnqueueScopeDigest({preparedJob, producerInvocationId, producerProof, requestDigest})
+    const idempotencyKey = `owned-handoff:${scopeDigest}`
+    const existing = await this._idempotencyOwnership(db, scopeDigest)
+    const baseOwnership = {
+      created_at_ms: preparedJob.createdAtMs,
+      idempotency_key: idempotencyKey,
+      job_name: preparedJob.jobName,
+      queue: preparedJob.queue,
+      request_digest: requestDigest,
+      scope_digest: scopeDigest
+    }
+
+    if (existing) {
+      this._validateIdempotencyOwnership({existing, ownership: {...baseOwnership, job_id: String(existing.job_id)}})
+      return String(existing.job_id)
+    }
+
+    const duplicateJobId = options.deduplicateWhileQueued
+      ? await this._deduplicatedQueuedJobId(db, preparedJob)
+      : null
+    const ownership = {...baseOwnership, job_id: duplicateJobId || preparedJob.jobId}
+    const claimed = await this._claimIdempotencyOwnership(db, ownership)
+
+    if (!claimed.created) {
+      this._validateIdempotencyOwnership({existing: claimed.row, ownership})
+      return String(claimed.row.job_id)
+    }
+    if (duplicateJobId) return duplicateJobId
+
+    await this._insertPreparedJob(db, {preparedJob, scheduleKey: null})
+    await this._recordCountDelta(db, {all: 1, queued: 1})
+
+    return preparedJob.jobId
+  }
+
   /**
    * Atomically owns one durable idempotency scope and creates its job exactly once.
    * @param {object} args - Enqueue input.
@@ -358,6 +465,25 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {Promise<string>} - Stable original job id.
    */
   async _enqueueIdempotently({args, options, preparedJob}) {
+    // Reuse ordinary enqueue transaction admission because this path changes
+    // the same durable count revision. The scope primary key remains the
+    // cross-process convergence owner.
+    return await this._idempotentEnqueueTransaction(async (db) => {
+      return await this._enqueueIdempotentlyInTransaction({args, db, options, preparedJob})
+    })
+  }
+
+  /**
+   * Owns or replays one public idempotency key inside the caller's transaction.
+   * @param {object} args - Transaction input.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job arguments.
+   * @param {boolean} [args.countRevisionLocked] - Whether the caller already owns count serialization.
+   * @param {import("../database/drivers/base.js").default} args.db - Transaction connection.
+   * @param {import("./types.js").BackgroundJobOptions} args.options - Job options.
+   * @param {PreparedBackgroundJob} args.preparedJob - Normalized job.
+   * @returns {Promise<string>} - Stable original job id.
+   */
+  async _enqueueIdempotentlyInTransaction({args, countRevisionLocked = false, db, options, preparedJob}) {
     const idempotencyKey = this._normalizeIdempotencyKey(options.idempotencyKey)
     const scopeDigest = this._idempotencyScopeDigest({idempotencyKey, jobName: preparedJob.jobName, queue: preparedJob.queue})
     const requestDigest = this._idempotencyRequestDigest({args, options, preparedJob})
@@ -378,33 +504,28 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       })
     }
 
-    // Reuse ordinary enqueue transaction admission because this path changes
-    // the same durable count revision. The scope primary key remains the
-    // cross-process convergence owner.
-    return await this._idempotentEnqueueTransaction(async (db) => {
-      const existing = await this._idempotencyOwnership(db, scopeDigest)
+    const existing = await this._idempotencyOwnership(db, scopeDigest)
 
-      if (existing) {
-        this._validateIdempotencyOwnership({existing, ownership})
-        await this._validateMailDeliveryOperation(db, {jobId: String(existing.job_id), mailOperationInput})
-        return String(existing.job_id)
-      }
+    if (existing) {
+      this._validateIdempotencyOwnership({existing, ownership})
+      await this._validateMailDeliveryOperation(db, {jobId: String(existing.job_id), mailOperationInput})
+      return String(existing.job_id)
+    }
 
-      const claimed = await this._claimIdempotencyOwnership(db, ownership)
+    const claimed = await this._claimIdempotencyOwnership(db, ownership)
 
-      if (!claimed.created) {
-        this._validateIdempotencyOwnership({existing: claimed.row, ownership})
-        await this._validateMailDeliveryOperation(db, {jobId: String(claimed.row.job_id), mailOperationInput})
-        return String(claimed.row.job_id)
-      }
+    if (!claimed.created) {
+      this._validateIdempotencyOwnership({existing: claimed.row, ownership})
+      await this._validateMailDeliveryOperation(db, {jobId: String(claimed.row.job_id), mailOperationInput})
+      return String(claimed.row.job_id)
+    }
 
-      await this._lockCountRevision(db)
-      await this._insertPreparedJob(db, {preparedJob, scheduleKey: null})
-      await this._persistMailDeliveryOperation(db, {jobId: preparedJob.jobId, mailOperationInput, createdAtMs: preparedJob.createdAtMs})
-      await this._recordCountDelta(db, {all: 1, queued: 1})
+    if (!countRevisionLocked) await this._lockCountRevision(db)
+    await this._insertPreparedJob(db, {preparedJob, scheduleKey: null})
+    await this._persistMailDeliveryOperation(db, {jobId: preparedJob.jobId, mailOperationInput, createdAtMs: preparedJob.createdAtMs})
+    await this._recordCountDelta(db, {all: 1, queued: 1})
 
-      return preparedJob.jobId
-    })
+    return preparedJob.jobId
   }
 
   /**
@@ -625,6 +746,126 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     return idempotencyKey
   }
 
+  /**
+   * Canonical request identity for an internal owned-handoff replay.
+   * Immediate enqueue wall time and generated job ids remain excluded.
+   * @param {object} args - Digest input.
+   * @param {import("./types.js").BackgroundJobOptions} args.options - Enqueue options.
+   * @param {PreparedBackgroundJob} args.preparedJob - Normalized job.
+   * @returns {string} - SHA-256 digest.
+   */
+  _ownedEnqueueRequestDigest({options, preparedJob}) {
+    const serialized = stableJsonStringify({
+      argsJson: preparedJob.argsJson,
+      concurrency: preparedJob.concurrency,
+      deduplicateWhileQueued: options.deduplicateWhileQueued === true,
+      executionMode: preparedJob.executionMode,
+      format: "velocious-background-job-owned-enqueue-v1",
+      jobName: preparedJob.jobName,
+      maxRetries: preparedJob.maxRetries,
+      queue: preparedJob.queue,
+      scheduledAtMs: options.scheduledAtMs === undefined ? null : preparedJob.scheduledAtMs,
+      scheduling: options.scheduledAtMs === undefined ? "immediate" : "scheduled",
+      ...(preparedJob.timeoutMs === null ? {} : {timeoutMs: preparedJob.timeoutMs})
+    })
+
+    return createHash("sha256").update(serialized).digest("hex")
+  }
+
+  /**
+   * Isolates internal producer replay ownership from caller idempotency scopes.
+   * @param {object} args - Scope input.
+   * @param {PreparedBackgroundJob} args.preparedJob - Normalized job.
+   * @param {string} args.producerInvocationId - Stable identity for one owned enqueue invocation.
+   * @param {import("./types.js").BackgroundJobProducerProof} args.producerProof - Exact producer lease.
+   * @param {string} args.requestDigest - Canonical request digest.
+   * @returns {string} - SHA-256 scope digest.
+   */
+  _ownedEnqueueScopeDigest({preparedJob, producerInvocationId, producerProof, requestDigest}) {
+    return createHash("sha256")
+      .update(stableJsonStringify({
+        format: "velocious-background-job-owned-enqueue-scope-v1",
+        jobName: preparedJob.jobName,
+        producerInvocationId,
+        producerProof,
+        queue: preparedJob.queue,
+        requestDigest
+      }))
+      .digest("hex")
+  }
+
+  /**
+   * Validates the untrusted identity of one producer-owned enqueue invocation.
+   * @param {string | undefined} producerInvocationId - Producer invocation identity.
+   * @returns {string} - Validated identity.
+   */
+  _normalizeProducerInvocationId(producerInvocationId) {
+    if (typeof producerInvocationId !== "string" || producerInvocationId.length === 0) {
+      throw VelociousError.safe("Background job producer invocation id is invalid.", {
+        code: "background-job-producer-invocation-id-invalid"
+      })
+    }
+
+    return producerInvocationId
+  }
+
+  /**
+   * Validates the untrusted transport shape before transaction admission.
+   * @param {import("./types.js").BackgroundJobProducerProof} producerProof - Producer proof.
+   * @returns {import("./types.js").BackgroundJobProducerProof} - Normalized immutable proof.
+   */
+  _normalizeProducerProof(producerProof) {
+    const exactKeys = ["handedOffAtMs", "handoffId", "jobId", "workerId"]
+    const keys = producerProof && typeof producerProof === "object" ? Object.keys(producerProof) : []
+    const valid = producerProof
+      && typeof producerProof === "object"
+      && keys.length === exactKeys.length
+      && keys.every((key) => exactKeys.includes(key))
+      && typeof producerProof.jobId === "string"
+      && producerProof.jobId.length > 0
+      && typeof producerProof.handoffId === "string"
+      && producerProof.handoffId.length > 0
+      && typeof producerProof.workerId === "string"
+      && producerProof.workerId.length > 0
+      && Number.isSafeInteger(producerProof.handedOffAtMs)
+      && producerProof.handedOffAtMs >= 0
+
+    if (!valid) {
+      throw VelociousError.safe("Background job producer proof is invalid.", {
+        code: "background-job-producer-proof-invalid"
+      })
+    }
+
+    return Object.freeze({
+      handedOffAtMs: producerProof.handedOffAtMs,
+      handoffId: producerProof.handoffId,
+      jobId: producerProof.jobId,
+      workerId: producerProof.workerId
+    })
+  }
+
+  /**
+   * Confirms exact active ownership while the enqueue transaction holds the
+   * shared mutation fence used by terminal producer transitions.
+   * @param {import("../database/drivers/base.js").default} db - Transaction connection.
+   * @param {import("./types.js").BackgroundJobProducerProof} producerProof - Exact producer lease.
+   * @returns {Promise<void>} - Resolves while ownership remains exact.
+   */
+  async _validateOwnedProducerProof(db, producerProof) {
+    const producer = await this._getJobRowById(db, producerProof.jobId)
+    const owned = producer
+      && producer.status === "handed_off"
+      && producer.handoffId === producerProof.handoffId
+      && producer.workerId === producerProof.workerId
+      && producer.handedOffAtMs === producerProof.handedOffAtMs
+
+    if (!owned) {
+      throw VelociousError.safe("Background job producer handoff is no longer owned.", {
+        code: "background-job-producer-handoff-not-owned"
+      })
+    }
+  }
+
   /**
    * Replaces the queued owner of a stable schedule key with a new one-off job.
    * A handed-off owner is left running and reported truthfully.
@@ -791,7 +1032,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next matching queued job.
    */
   async _nextQueuedJob({db, scheduledAtOperator, executionMode}) {
-    const now = Date.now()
+    const now = this.clock.now()
     let query = db
       .newQuery()
       .from(JOBS_TABLE)
@@ -999,7 +1240,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
   async markHandedOff({jobId, handoffId = randomUUID(), workerId}) {
     await this.ensureReady()
 
-    const handedOffAtMs = Date.now()
+    const handedOffAtMs = this.clock.now()
 
     return await this._serializedCountMutation(async (db) => {
       const selectedJob = await this._getJobRowById(db, jobId)
@@ -1061,7 +1302,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
         tableName: JOBS_TABLE,
         data: {
           status: "completed",
-          completed_at_ms: Date.now()
+          completed_at_ms: this.clock.now()
         },
         conditions: this._activeHandoffConditions(job)
       })
@@ -1134,7 +1375,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
         tableName: JOBS_TABLE,
         data: {
           status: "queued",
-          scheduled_at_ms: Date.now(),
+          scheduled_at_ms: this.clock.now(),
           handed_off_at_ms: null,
           handoff_id: null,
           worker_id: null
@@ -1291,7 +1532,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     await this.ensureReady()
 
     return await this._serializedCountMutation(async (db) => {
-      const cutoff = Date.now() - orphanedAfterMs
+      const cutoff = this.clock.now() - orphanedAfterMs
       const query = db
         .newQuery()
         .from(JOBS_TABLE)
@@ -1386,7 +1627,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
   async pruneTerminalJobs({completedTtlMs = null, failedTtlMs = null, batchSize = 1000} = {}) {
     await this.ensureReady()
 
-    const now = Date.now()
+    const now = this.clock.now()
     const size = batchSize > 0 ? batchSize : 1000
     let deleted = 0
 
@@ -1505,7 +1746,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {PreparedBackgroundJob} - Prepared job.
    */
   _prepareJob({args, jobName, options}) {
-    const createdAtMs = Date.now()
+    const createdAtMs = this.clock.now()
     const queue = this._normalizeQueue(options)
 
     return {
@@ -1612,7 +1853,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Future eligibility timestamp.
    */
   _rescheduledAtMs(delayMs) {
-    return rescheduledBackgroundJobAtMs(delayMs, Date.now())
+    return rescheduledBackgroundJobAtMs(delayMs, this.clock.now())
   }
 
   /**
@@ -2238,7 +2479,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Updated job row when the lease transition won.
    */
   async _applyFailure({db, job, error, markOrphaned, conditions}) {
-    const now = Date.now()
+    const now = this.clock.now()
     const nextAttempt = (job.attempts || 0) + 1
     const maxRetries = this._normalizeMaxRetries(job.maxRetries)
     const shouldRetry = nextAttempt <= maxRetries

package/build/background-jobs/types.js

@@ -10,6 +10,15 @@
 /** @typedef {"starting" | "running" | "retiring"} PooledRunnerLifecycleState */
 /** @typedef {"unexpected" | "job-timeout" | "worker-shutdown-timeout"} PooledRunnerTerminationReason */
 /** @typedef {"running" | "retiring" | "stopping"} BackgroundJobsWorkerLifecycleState */
+/**
+ * Exact durable handoff ownership carried by an executing job when it produces
+ * follow-up work.
+ * @typedef {object} BackgroundJobProducerProof
+ * @property {string} jobId - Producing job id.
+ * @property {string} handoffId - Producing handoff lease id.
+ * @property {string} workerId - Worker identity persisted with the handoff.
+ * @property {number} handedOffAtMs - Durable handoff timestamp.
+ */
 /**
  * @typedef {object} PooledRunnerActiveJob
  * @property {string | null} handoffId - Durable handoff lease id.
@@ -84,7 +93,7 @@
  */
 /**
  * @typedef {object} BackgroundJobsProducer
- * @property {(args: {jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}) => Promise<string>} enqueue - Enqueues a job.
+ * @property {(args: {jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions, producerInvocationId?: string, producerProof?: BackgroundJobProducerProof}) => Promise<string>} enqueue - Enqueues a job.
  * @property {(args: {scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}) => Promise<BackgroundJobReplacementResult>} replaceScheduled - Replaces a stable schedule.
  * @property {(args: {scheduleKey: string}) => Promise<BackgroundJobCancellationResult>} cancelScheduled - Cancels a stable schedule.
  */
@@ -200,7 +209,7 @@
  * @typedef {{type: "ready", acceptsForked?: boolean, acceptsInline?: boolean, acceptsPooled?: boolean, acceptsSpawned?: boolean, availablePooledSlots?: number}} BackgroundJobReadyMessage
  * @typedef {{type: "draining"}} BackgroundJobDrainingMessage
  * @typedef {{type: "heartbeat", workerId?: string}} BackgroundJobHeartbeatMessage
- * @typedef {{type: "enqueue", jobName: string, args?: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}} BackgroundJobEnqueueMessage
+ * @typedef {{type: "enqueue", jobName: string, args?: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions, producerInvocationId?: string, producerProof?: BackgroundJobProducerProof}} BackgroundJobEnqueueMessage
  * @typedef {{type: "enqueued", jobId: string}} BackgroundJobEnqueuedMessage
  * @typedef {{type: "enqueue-error", error?: string}} BackgroundJobEnqueueErrorMessage
  * @typedef {{type: "replace-scheduled", scheduleKey: string, jobName: string, args?: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}} BackgroundJobReplaceScheduledMessage

package/build/background-jobs/worker.js

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url"
 import shutdownLifecycle, { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
 import performBackgroundJob from "./perform-job.js"
+import { runWithBackgroundJobPayload } from "./execution-context.js"
 import { createGenerationWorkerId } from "./generation-identity.js"
 import BackgroundJobsGenerationHandshakeTimeoutError, { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
 
@@ -1430,13 +1431,15 @@ export default class BackgroundJobsWorker {
     const registry = new BackgroundJobRegistry({configuration})
     await registry.load()
     const JobClass = registry.getJobByName(payload.jobName)
-    await performBackgroundJob({
-      configuration,
-      JobClass,
-      jobArgs: payload.args || [],
-      jobOptions: payload.options || {},
-      name: `Background job worker inline: ${payload.jobName}`,
-      payload
+    await runWithBackgroundJobPayload(payload, async () => {
+      await performBackgroundJob({
+        configuration,
+        JobClass,
+        jobArgs: payload.args || [],
+        jobOptions: payload.options || {},
+        name: `Background job worker inline: ${payload.jobName}`,
+        payload
+      })
     })
   }
 

package/build/frontend-model-controller.js

@@ -10,7 +10,7 @@ import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigura
 import {createOfflineGrantFromBootstrap, verifyOfflineGrant} from "./sync/offline-grant.js"
 import {serverChangeFeedStoreForConfiguration} from "./sync/server-change-feed.js"
 import {mutationIdempotencyKey, verifySignedMutation} from "./sync/device-identity.js"
-import {FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
+import {assertFrontendModelIndexPayload, FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
 import {assignSafeProperty, deserializeFrontendModelTransportValue, isBackendModelInstance, serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
 import {requestDetails} from "./error-reporting/request-details.js"
 import RoutesResolver from "./routes/resolver.js"
@@ -4455,14 +4455,27 @@ export default class FrontendModelController extends Controller {
       }
 
       try {
+        let indexPayload = {}
+
+        if (commandType === "index") {
+          try {
+            indexPayload = assertFrontendModelIndexPayload(payload)
+          } catch (error) {
+            throwFrontendModelQueryErrorForParserError(error)
+          }
+        }
+
         const requestContext = captureFrontendModelRemoteRequestContext(requestEntry?.requestContext)
         let responsePayload
 
         if (isBuiltInCommand) {
+          const commandPayload = commandType === "index"
+            ? indexPayload
+            : (payload && typeof payload === "object" ? payload : {})
           const commandParams = mergeFrontendModelRemoteRequestContext(
             requestContext,
             {
-              ...(payload && typeof payload === "object" ? payload : {}),
+              ...commandPayload,
               model
             }
           )

package/build/frontend-models/query.js

@@ -118,6 +118,28 @@ export class FrontendModelQueryError extends Error {
   }
 }
 
+const FRONTEND_MODEL_INDEX_PAYLOAD_KEYS = new Set([
+  "abilities",
+  "count",
+  "distinct",
+  "group",
+  "joins",
+  "limit",
+  "offset",
+  "page",
+  "perPage",
+  "pluck",
+  "preload",
+  "queryData",
+  "ransack",
+  "searches",
+  "select",
+  "selectsExtra",
+  "sort",
+  "where",
+  "withCount"
+])
+
 /**
  * Builds a query descriptor error.
  * @param {string} message - Error message.
@@ -127,6 +149,27 @@ function frontendModelQueryError(message) {
   return new FrontendModelQueryError(message)
 }
 
+/**
+ * Asserts the raw payload accepted by a shared frontend-model index command.
+ * @param {ReturnType<typeof JSON.parse>} payload - Raw index payload.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Valid index payload.
+ */
+export function assertFrontendModelIndexPayload(payload) {
+  if (payload == null) return {}
+
+  if (!isPlainObject(payload)) {
+    throw frontendModelQueryError("Expected frontend-model index payload to be a plain object")
+  }
+
+  for (const payloadKey of Object.keys(payload)) {
+    if (!FRONTEND_MODEL_INDEX_PAYLOAD_KEYS.has(payloadKey)) {
+      throw frontendModelQueryError(`Unknown frontend-model index payload key "${payloadKey}"`)
+    }
+  }
+
+  return payload
+}
+
 /**
  * Runs the normalizePreload helper.
  * @param {import("../database/query/index.js").NestedPreloadRecord | string | Array<string | import("../database/query/index.js").NestedPreloadRecord> | boolean | undefined | null} preload - Preload shorthand.

package/build/src/background-jobs/adapter.d.ts

@@ -11,6 +11,13 @@ export default class BackgroundJobsAdapter {
      * @returns {boolean} - Whether generation mode is supported.
      */
     supportsReleaseScopedGenerations(): boolean;
+    /**
+     * 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(): boolean;
     /**
      * Ensures the adapter can accept work.
      * @returns {Promise<void>} - Resolves when ready.
@@ -56,6 +63,18 @@ export default class BackgroundJobsAdapter {
         args: Array<ReturnType<typeof JSON.parse>>;
         options?: import("./types.js").BackgroundJobOptions;
     }): Promise<string>;
+    /**
+     * 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.
+     */
+    enqueueFromOwnedHandoff(_args: {
+        jobName: string;
+        args: Array<ReturnType<typeof JSON.parse>>;
+        options?: import("./types.js").BackgroundJobOptions;
+        producerInvocationId?: string;
+        producerProof: import("./types.js").BackgroundJobProducerProof;
+    }): Promise<string>;
     /**
      * 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/src/background-jobs/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/adapter.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/adapter.js"],"names":[],"mappings":"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"}