velocious 1.0.662 → 1.0.664

package/README.md

@@ -15,7 +15,7 @@
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, including committed counter-cache parent updates, 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))
+* Declarative client sync scopes with per-scope cursors, generation-fenced identity replacement and selected-scope cache reset, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery and reconnect gap closure, computed server-publish scope metadata, 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 conflict snapshots that retain submitted aliases in conflict metadata while keying `serverModel` by canonical model attributes (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))
@@ -2614,7 +2614,7 @@ actual state sources must still agree.
 
 `maxConcurrentInlineJobs` (default: `4`) caps how many `executionMode: "inline"` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores; select it with `executionMode: "forked"`.
 
-New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. Workers advertise that exact free-slot count and the main consumes one slot per durable handoff, allowing one readiness notification to fill the pool. If an initialized child exits unexpectedly, the worker immediately advertises the freed capacity while failure reports retry; the replacement is spawned lazily by the next dispatch, and a pre-startup crash does not trigger a respawn loop. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
+New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. Workers advertise that exact free-slot count and the main consumes one slot per durable handoff, allowing one readiness notification to fill the pool. If an initialized child exits unexpectedly, the worker immediately advertises the freed capacity while failure reports retry; the replacement is spawned lazily by the next dispatch, and a pre-startup crash does not trigger a respawn loop. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. Pooled jobs also persist acceptance evidence (`child_received_at_ms`, `child_started_at_ms`, `child_instance_id`, `child_pid`) so a handed-off job can be told apart from one whose runner never picked it up. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
 
 Cold pooled jobs share one atomic model-bootstrap phase. If that phase fails, all
 waiting jobs receive the failure; a later job in the surviving child cannot run
@@ -2729,7 +2729,7 @@ Set `deduplicateWhileQueued: true` to coalesce an enqueue onto the earliest iden
 
 Use `options: {idempotencyKey}` when producer replay must converge on the original durable job across every state and even after terminal-job pruning. Ownership is scoped to the resolved job class name, resolved queue, and key; reusing that scope with changed canonical arguments or behavior-affecting options fails. This is distinct from queued-only deduplication, and ownership rows are intentionally retained until a future explicit reconciliation/deletion policy. See [durable idempotent enqueue](docs/background-jobs.md#durable-idempotent-enqueue).
 
-The Node producer rejects and destroys its one-shot socket when the main closes before acknowledging or when an enqueue acknowledgement stalls for 5 seconds. Because the main may already have committed the job, this is an ambiguous outcome. A call made by an executing generation-owned job automatically makes one recovery attempt with its exact internal producer proof and per-call invocation identity, but never after a pre-send generation failure or explicit enqueue rejection. Ordinary enqueues are not retried automatically: replay one with the same durable `idempotencyKey` to recover the original job id without creating a duplicate. Direct `BackgroundJobsClient` users can set a different bounded `enqueueTimeoutMs` constructor option. See [durable idempotent enqueue](docs/background-jobs.md#durable-idempotent-enqueue).
+The Node producer gives connection/handshake and post-send acknowledgement separate bounded phases, so connection or generation-handshake latency does not consume the 5-second `enqueued` acknowledgement budget. It rejects and destroys its one-shot socket when either phase stalls or when the main closes before acknowledging. Because the main may already have committed the job, a post-send failure is an ambiguous outcome. A call made by an executing generation-owned job automatically makes one recovery attempt with its exact internal producer proof and per-call invocation identity, but never after a pre-send generation failure or explicit enqueue rejection. Ordinary enqueues are not retried automatically: replay one with the same durable `idempotencyKey` to recover the original job id without creating a duplicate. Direct `BackgroundJobsClient` users can set a different bounded `enqueueTimeoutMs` constructor option for both phases. See [durable idempotent enqueue](docs/background-jobs.md#durable-idempotent-enqueue).
 
 Select a non-default runtime explicitly with `options: {executionMode: "inline" | "forked" | "spawned"}`.
 

package/build/background-jobs/adapter.js

@@ -129,6 +129,15 @@ export default class BackgroundJobsAdapter {
    */
   async markCompleted(_args) { throw new Error("BackgroundJobsAdapter#markCompleted is not implemented") }
 
+  /**
+   * Records pooled-child acceptance evidence (received/started timestamps plus
+   * runner identity) for a handed-off job, fenced by its active handoff lease.
+   * Only the fields supplied are written.
+   * @param {{jobId: string, handoffId?: string, workerId?: string, handedOffAtMs?: number, receivedAtMs?: number, startedAtMs?: number, childInstanceId?: string, childPid?: number}} _args - Acceptance report.
+   * @returns {Promise<boolean>} - Whether the fenced report was accepted.
+   */
+  async markChildAccepted(_args) { throw new Error("BackgroundJobsAdapter#markChildAccepted is not implemented") }
+
   /**
    * Returns a handed-off job to its schedule.
    * @param {{jobId: string, delayMs: number, handoffId?: string, workerId?: string, handedOffAtMs?: number}} _args - Reschedule report.

package/build/background-jobs/client.js

@@ -66,18 +66,44 @@ export default class BackgroundJobsClient {
      */
     const enqueueAttempt = async (attemptAcknowledgement) => {
       const request = await this._request()
-
-      return await timeout({
-        errorMessage: `Background job enqueue acknowledgement timed out after ${this.enqueueTimeoutMs}ms`,
+      const requestAbortController = new AbortController()
+      const timeoutErrorMessage = `Background job enqueue acknowledgement timed out after ${this.enqueueTimeoutMs}ms`
+      /**
+       * Resolves the pre-send phase when the mutation has entered the socket.
+       * @type {() => void}
+       */
+      let markRequestSent = () => {}
+      const requestSent = new Promise((resolve) => {
+        markRequestSent = () => resolve(undefined)
+      })
+      /**
+       * Applies the configured deadline independently to one request phase.
+       * @template T
+       * @param {() => Promise<T>} callback - Phase work.
+       * @returns {Promise<T>} - Phase result.
+       */
+      const withEnqueueTimeout = async (callback) => await timeout({
+        errorMessage: timeoutErrorMessage,
         timeout: this.enqueueTimeoutMs
-      }, async ({control}) => await request.run({
-        signal: control.signal,
+      }, async ({control}) => {
+        const abortRequest = () => requestAbortController.abort(control.signal.reason)
+
+        control.signal.addEventListener("abort", abortRequest)
+        try {
+          return await callback()
+        } finally {
+          control.signal.removeEventListener("abort", abortRequest)
+        }
+      })
+      const requestPromise = request.run({
+        signal: requestAbortController.signal,
         onConnect: (jsonSocket) => {
           jsonSocket.send(message)
           if (attemptAcknowledgement) {
             attemptAcknowledgement.generationFenced = Boolean(request.generationId)
             attemptAcknowledgement.requestSent = true
           }
+          markRequestSent()
         },
         onMessage: ({message, resolve, reject}) => {
           if (message?.type === "enqueued") {
@@ -90,7 +116,11 @@ export default class BackgroundJobsClient {
             reject(new Error(message.error || "Failed to enqueue job"))
           }
         }
-      }))
+      })
+
+      await withEnqueueTimeout(async () => await Promise.race([requestSent, requestPromise]))
+
+      return await withEnqueueTimeout(async () => await requestPromise)
     }
 
     try {

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

@@ -82,10 +82,11 @@ function runnerProcessTitle(JobClass, payload) {
  * @param {object} [options] - Runner options.
  * @param {boolean} [options.closeConnections] - Whether to gracefully close framework connections after the job.
  * @param {boolean} [options.manageProcessTitle] - Whether to set the per-job process title and restore it afterwards. Off for concurrent pooled runners, where interleaved snapshot/restore of the single process-wide `process.title` would corrupt it; the pooled child owns an aggregate title instead.
+ * @param {() => void} [options.onPerformStart] - Observation hook fired once, immediately before perform runs (with its connection acquired). Pooled runners use it to report that the job actually started. Must not throw into the job.
  * @param {string} [options.processType] - Generic application process type.
  * @returns {Promise<"completed" | "rescheduled">} - Acknowledged outcome.
  */
-export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true, processType = "background-jobs-runner"} = {}) {
+export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true, onPerformStart, processType = "background-jobs-runner"} = {}) {
   const configuration = await configurationResolver()
   configuration.setCurrent()
   await configuration.initialize({type: processType})
@@ -119,6 +120,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
     try {
       await runWithBackgroundJobPayload(payload, async () => {
         await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
+          if (onPerformStart) onPerformStart()
           await perform.apply(jobInstance, jobArgs)
         })
       })

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

@@ -133,6 +133,13 @@ export default class LocalBackgroundJobsAdapter extends BackgroundJobsAdapter {
    */
   async markCompleted(args) { return await this.store.markCompleted(args) }
 
+  /**
+   * Records pooled-child acceptance evidence for a local handoff.
+   * @param {{jobId: string, handoffId?: string, receivedAtMs?: number, startedAtMs?: number, childInstanceId?: string, childPid?: number}} args - Acceptance report.
+   * @returns {Promise<boolean>} - Whether accepted.
+   */
+  async markChildAccepted(args) { return await this.store.markChildAccepted(args) }
+
   /**
    * Acknowledges an explicit local reschedule.
    * @param {{jobId: string, delayMs: number, handoffId?: string}} args - Reschedule report.

package/build/background-jobs/local-store.js

@@ -49,7 +49,11 @@ const EXPECTED_JOB_COLUMNS = [
   "failed_at_ms",
   "last_error",
   "concurrency_key",
-  "max_concurrency"
+  "max_concurrency",
+  "child_received_at_ms",
+  "child_started_at_ms",
+  "child_instance_id",
+  "child_pid"
 ]
 const EXPECTED_CONCURRENCY_COLUMNS = ["concurrency_key", "max_concurrency", "active_count"]
 /** @type {WeakMap<import("../configuration.js").default, Map<string, Promise<void>>>} */
@@ -202,6 +206,7 @@ export default class LocalBackgroundJobsStore {
       await db.createTable(this._jobsTableData())
       changed = true
     } else {
+      if (await this._ensureJobColumns(db)) changed = true
       await this._assertColumns(db, LOCAL_BACKGROUND_JOBS_TABLE, EXPECTED_JOB_COLUMNS)
     }
 
@@ -232,6 +237,45 @@ export default class LocalBackgroundJobsStore {
     return changed
   }
 
+  /**
+   * Idempotently adds columns from the current jobs table definition that an
+   * existing local table is missing, so an upgraded framework finds a
+   * compatible schema instead of failing the column assertion.
+   * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+   * @returns {Promise<boolean>} - Whether a column was added.
+   */
+  async _ensureJobColumns(db) {
+    db.clearSchemaCache()
+    const table = await db.getTableByNameOrFail(LOCAL_BACKGROUND_JOBS_TABLE)
+    const tableData = new TableData(LOCAL_BACKGROUND_JOBS_TABLE)
+    let added = false
+
+    for (const column of this._jobsTableData().getColumns()) {
+      if (await table.getColumnByName(column.getName())) continue
+      if (column.getPrimaryKey()) continue
+
+      const columnArgs = /** @type {{null: boolean, maxLength?: number}} */ ({null: column.getNull() !== false})
+      const maxLength = column.getMaxLength()
+
+      if (typeof maxLength === "number") columnArgs.maxLength = maxLength
+
+      const type = column.getType()
+      if (type === "string") tableData.string(column.getName(), columnArgs)
+      else if (type === "text") tableData.text(column.getName(), columnArgs)
+      else if (type === "bigint") tableData.bigint(column.getName(), columnArgs)
+      else if (type === "integer") tableData.integer(column.getName(), columnArgs)
+      else if (type === "boolean") tableData.boolean(column.getName(), columnArgs)
+      else continue
+      added = true
+    }
+
+    if (!added) return false
+
+    for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+    db.clearSchemaCache()
+    return true
+  }
+
   /**
    * Builds the migration ledger table definition.
    * @returns {TableData} - Migration ledger table.
@@ -272,6 +316,10 @@ export default class LocalBackgroundJobsStore {
     table.text("last_error", {null: true})
     table.string("concurrency_key", {null: true})
     table.integer("max_concurrency", {null: true})
+    table.bigint("child_received_at_ms", {null: true})
+    table.bigint("child_started_at_ms", {null: true})
+    table.string("child_instance_id", {null: true})
+    table.integer("child_pid", {null: true})
     table.addIndex(new TableIndex(["status", "scheduled_at_ms", "created_at_ms", "id"], {name: LOCAL_BACKGROUND_JOBS_INDEX_NAMES[0]}))
     table.addIndex(new TableIndex(["queue", "status", "created_at_ms"], {name: LOCAL_BACKGROUND_JOBS_INDEX_NAMES[1]}))
     table.addIndex(new TableIndex(["args_digest"], {name: LOCAL_BACKGROUND_JOBS_INDEX_NAMES[2]}))
@@ -708,7 +756,7 @@ export default class LocalBackgroundJobsStore {
       const handedOffAtMs = this.clock.now()
       const affectedRows = await this._updateAffectedRows(db, {
         conditions: {id: jobId, status: "queued"},
-        data: {handed_off_at_ms: handedOffAtMs, handoff_id: handoffId, status: "handed_off", worker_id: workerId || "local"},
+        data: {...this._clearedChildAcceptanceData(), handed_off_at_ms: handedOffAtMs, handoff_id: handoffId, status: "handed_off", worker_id: workerId || "local"},
         tableName: LOCAL_BACKGROUND_JOBS_TABLE
       })
 
@@ -763,6 +811,7 @@ export default class LocalBackgroundJobsStore {
       const affectedRows = await this._updateAffectedRows(db, {
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"},
         data: {
+          ...this._clearedChildAcceptanceData(),
           handed_off_at_ms: null,
           handoff_id: null,
           scheduled_at_ms: this.clock.now(),
@@ -802,6 +851,43 @@ export default class LocalBackgroundJobsStore {
     }))
   }
 
+  /**
+   * Records pooled-child acceptance evidence for an active handoff. Only the
+   * fields supplied are written, fenced by the exact active handoff lease.
+   * @param {object} args - Acceptance report.
+   * @param {string} args.jobId - Job id.
+   * @param {string} [args.handoffId] - Handoff lease id.
+   * @param {number} [args.receivedAtMs] - Epoch ms the runner child received the job.
+   * @param {number} [args.startedAtMs] - Epoch ms the job's perform started in the child.
+   * @param {string} [args.childInstanceId] - Stable pooled child identity.
+   * @param {number} [args.childPid] - Pooled child OS pid.
+   * @returns {Promise<boolean>} - Whether the lease won.
+   */
+  async markChildAccepted({jobId, handoffId, receivedAtMs, startedAtMs, childInstanceId, childPid}) {
+    await this.ensureReady()
+
+    return await this._withDb(async (connection) => await this._mutate(connection, async (db) => {
+      const job = await this._getJob(db, jobId)
+
+      if (!this._acceptsHandoff(job, handoffId)) return false
+
+      const data = {}
+      if (typeof receivedAtMs === "number") data.child_received_at_ms = receivedAtMs
+      if (typeof startedAtMs === "number") data.child_started_at_ms = startedAtMs
+      if (typeof childInstanceId === "string") data.child_instance_id = childInstanceId
+      if (typeof childPid === "number") data.child_pid = childPid
+      if (Object.keys(data).length === 0) return false
+
+      const affectedRows = await this._updateAffectedRows(db, {
+        conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"},
+        data,
+        tableName: LOCAL_BACKGROUND_JOBS_TABLE
+      })
+
+      return affectedRows === 1
+    }))
+  }
+
   /**
    * Applies a fenced reschedule without consuming an attempt.
    * @param {{jobId: string, handoffId?: string, delayMs: number}} args - Reschedule report.
@@ -819,6 +905,7 @@ export default class LocalBackgroundJobsStore {
       const affectedRows = await this._updateAffectedRows(db, {
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"},
         data: {
+          ...this._clearedChildAcceptanceData(),
           handed_off_at_ms: null,
           handoff_id: null,
           scheduled_at_ms: rescheduledBackgroundJobAtMs(delayMs, this.clock.now()),
@@ -917,7 +1004,9 @@ export default class LocalBackgroundJobsStore {
     }
 
     if (willRetry) {
-      Object.assign(data, {scheduled_at_ms: nowMs + retryDelayMs(attempts)})
+      // A retry starts a fresh handoff with a possibly different runner, so the
+      // previous child's acceptance evidence must not leak into the next attempt.
+      Object.assign(data, {scheduled_at_ms: nowMs + retryDelayMs(attempts), ...this._clearedChildAcceptanceData()})
     } else {
       Object.assign(data, {failed_at_ms: nowMs})
     }
@@ -934,6 +1023,7 @@ export default class LocalBackgroundJobsStore {
 
     return {
       ...job,
+      ...(willRetry ? this._clearedChildAcceptanceRow() : {}),
       attempts,
       failedAtMs: willRetry ? job.failedAtMs : nowMs,
       handedOffAtMs: null,
@@ -945,6 +1035,22 @@ export default class LocalBackgroundJobsStore {
     }
   }
 
+  /**
+   * Returns the database data that clears pooled-child acceptance evidence.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Cleared acceptance columns.
+   */
+  _clearedChildAcceptanceData() {
+    return {child_instance_id: null, child_pid: null, child_received_at_ms: null, child_started_at_ms: null}
+  }
+
+  /**
+   * Returns the row-shape counterpart of the cleared acceptance columns.
+   * @returns {Pick<import("./types.js").BackgroundJobRow, "childInstanceId" | "childPid" | "childReceivedAtMs" | "childStartedAtMs">} - Cleared acceptance fields.
+   */
+  _clearedChildAcceptanceRow() {
+    return {childInstanceId: null, childPid: null, childReceivedAtMs: null, childStartedAtMs: null}
+  }
+
   /**
    * Ensures that a durable concurrency counter exists with the required cap.
    * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
@@ -1106,6 +1212,10 @@ export default class LocalBackgroundJobsStore {
     return {
       args: parsedArgs,
       attempts: this._numberOrNull(row.attempts),
+      childInstanceId: row.child_instance_id === null || row.child_instance_id === undefined ? null : String(row.child_instance_id),
+      childPid: this._numberOrNull(row.child_pid),
+      childReceivedAtMs: this._numberOrNull(row.child_received_at_ms),
+      childStartedAtMs: this._numberOrNull(row.child_started_at_ms),
       completedAtMs: this._numberOrNull(row.completed_at_ms),
       concurrencyKey: row.concurrency_key === null || row.concurrency_key === undefined ? null : String(row.concurrency_key),
       createdAtMs: this._numberOrNull(row.created_at_ms),

package/build/background-jobs/main.js

@@ -1219,6 +1219,11 @@ export default class BackgroundJobsMain {
       }
       return
     }
+    if (message?.type === "job-accepted") {
+      await this._handleJobAccepted({jsonSocket, message})
+      return
+    }
+
     if (message?.type === "job-complete") {
       await this._handleJobComplete({jsonSocket, message})
       return
@@ -1234,6 +1239,35 @@ export default class BackgroundJobsMain {
     }
   }
 
+  /**
+   * Persists pooled-child acceptance evidence for an active handoff. The
+   * report is diagnostic: a stale lease (job already reclaimed or terminal)
+   * answers the same `job-updated` acknowledgement as an accepted report, and
+   * only a store failure answers `job-update-error` so the worker can retry.
+   * @param {object} args - Options.
+   * @param {JsonSocket} args.jsonSocket - JSON socket.
+   * @param {import("./types.js").BackgroundJobAcceptedMessage} args.message - Message.
+   * @returns {Promise<void>} - Resolves when handled.
+   */
+  async _handleJobAccepted({jsonSocket, message}) {
+    try {
+      await this.store.markChildAccepted({
+        childInstanceId: message.childInstanceId,
+        childPid: message.childPid,
+        handedOffAtMs: message.handedOffAtMs,
+        handoffId: message.handoffId,
+        jobId: message.jobId,
+        receivedAtMs: message.receivedAtMs,
+        startedAtMs: message.startedAtMs,
+        workerId: message.workerId
+      })
+      jsonSocket.send({type: "job-updated", jobId: message.jobId})
+    } catch (error) {
+      this._reportJobUpdateFailure({error, jobId: message.jobId, stage: "background-job-accepted"})
+      jsonSocket.send({type: "job-update-error", jobId: message.jobId, error: "Failed to update job"})
+    }
+  }
+
   /**
    * Requires the complete durable lease identity before a generation-mode
    * reporter can mutate a job. Legacy reporters keep their permissive protocol.
@@ -1241,7 +1275,7 @@ export default class BackgroundJobsMain {
    * @returns {boolean} - Whether the report lacks its exact generation lease.
    */
   _generationReportIsInvalid(message) {
-    if (message?.type !== "job-complete" && message?.type !== "job-failed" && message?.type !== "job-reschedule") return false
+    if (message?.type !== "job-accepted" && message?.type !== "job-complete" && message?.type !== "job-failed" && message?.type !== "job-reschedule") return false
     const generationId = this.generationId
     if (!generationId) return false
 

package/build/background-jobs/pooled-runner-child.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import { randomUUID } from "node:crypto"
 import runJobPayload, { BackgroundJobPerformedFailure } from "./job-runner.js"
 import { closeRunnerConnections, closeRunnerFrameworkConnections, currentConfigurationOrNull } from "./runner-graceful-shutdown.js"
 import setRunnerProcessTitle from "./runner-process-title.js"
@@ -7,6 +8,8 @@ import PooledRunnerBrokerIdentity from "./pooled-runner-broker-identity.js"
 import { runWithSharedTransactionBrokerConfig } from "../testing/shared-transaction-proxy-driver.js"
 
 const BASE_PROCESS_TITLE = "velocious background-jobs-runner"
+/** Stable identity of this pooled child process for the life of the process. */
+const childInstanceId = randomUUID()
 
 setRunnerProcessTitle()
 
@@ -57,6 +60,39 @@ function updateProcessTitle() {
   process.title = count > 0 ? `${BASE_PROCESS_TITLE}: ${count} ${count === 1 ? "job" : "jobs"}` : BASE_PROCESS_TITLE
 }
 
+/**
+ * Reports one acceptance observation (job received / perform started) to the
+ * worker over IPC. The message carries the job's exact handoff lease so the
+ * worker can persist it fenced without any other lookup. Send failures are
+ * swallowed: a dead IPC channel is terminal for this child (the disconnect
+ * handler owns shutdown), and losing acceptance evidence must never fail the
+ * job itself.
+ * @param {"job-received" | "job-started"} type - Observation kind.
+ * @param {import("./types.js").BackgroundJobPayload & {id: string}} payload - Job payload carrying the handoff lease.
+ * @param {number} observedAtMs - Epoch ms of the observation.
+ * @returns {void}
+ */
+function sendChildAcceptance(type, payload, observedAtMs) {
+  if (!process.send) return
+
+  const message = {
+    childInstanceId,
+    childPid: process.pid,
+    handedOffAtMs: payload.handedOffAtMs,
+    handoffId: payload.handoffId,
+    jobId: payload.id,
+    type,
+    workerId: payload.workerId,
+    ...(type === "job-received" ? {receivedAtMs: observedAtMs} : {startedAtMs: observedAtMs})
+  }
+
+  try {
+    process.send(message)
+  } catch {
+    // The IPC channel is already gone; the disconnect handler owns shutdown.
+  }
+}
+
 /**
  * Checks whether an IPC value is a runnable pooled job message.
  * @param {ReturnType<typeof JSON.parse>} message - IPC message.
@@ -114,6 +150,7 @@ async function runJob(payload, sharedTransactionBroker) {
         return await runJobPayload(payload, {
           closeConnections: false,
           manageProcessTitle: false,
+          onPerformStart: () => sendChildAcceptance("job-started", payload, Date.now()),
           processType: "background-jobs-pooled-runner"
         })
       })
@@ -143,6 +180,7 @@ function handleMessage(message) {
 
   runningJobIds.add(message.payload.id)
   updateProcessTitle()
+  sendChildAcceptance("job-received", message.payload, Date.now())
   void runJob(message.payload, message.sharedTransactionBroker || {expected: false})
 }
 

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

@@ -92,6 +92,102 @@ export default class BackgroundJobsStatusReporter {
     })
   }
 
+  /**
+   * Runs report child accepted.
+   * @param {object} args - Options.
+   * @param {string} args.jobId - Job id.
+   * @param {string} [args.handoffId] - Handoff lease id.
+   * @param {string} [args.workerId] - Worker id.
+   * @param {number} [args.handedOffAtMs] - Handed off timestamp.
+   * @param {number} [args.receivedAtMs] - Epoch ms the runner child received the job.
+   * @param {number} [args.startedAtMs] - Epoch ms the job's perform started in the child.
+   * @param {string} [args.childInstanceId] - Stable pooled child identity.
+   * @param {number} [args.childPid] - Pooled child OS pid.
+   * @returns {Promise<void>} - Resolves when reported.
+   */
+  async reportChildAccepted({jobId, handoffId, workerId, handedOffAtMs, receivedAtMs, startedAtMs, childInstanceId, childPid}) {
+    const config = this.configuration.getBackgroundJobsConfig()
+    const host = this.host || config.host
+    const port = typeof this.port === "number" ? this.port : config.port
+    const {generationId} = this.configuration.resolveBackgroundJobsGenerationConfig({
+      generationId: this.explicitGenerationId,
+      sourceName: "BackgroundJobsStatusReporter"
+    })
+
+    await timeout({timeout: this.attemptTimeoutMs}, async ({control}) => {
+      const request = new BackgroundJobsSocketRequest({host, port, role: "reporter", generationHandshakeTimeoutMs: this.generationHandshakeTimeoutMs, generationId})
+
+      this._lastRequest = request
+
+      await request.run({
+        signal: control.signal,
+        onConnect: (jsonSocket) => {
+          jsonSocket.send({
+            type: "job-accepted",
+            jobId,
+            handoffId,
+            workerId,
+            handedOffAtMs,
+            receivedAtMs,
+            startedAtMs,
+            childInstanceId,
+            childPid
+          })
+        },
+        onMessage: ({message, resolve, reject}) => {
+          if (message?.type === "job-updated" && message.jobId === jobId) {
+            resolve(undefined)
+            return
+          }
+
+          if (message?.type === "job-update-error" && message.jobId === jobId) {
+            reject(new BackgroundJobUpdateError(message.error || "Job update failed"))
+          }
+        }
+      })
+    })
+  }
+
+  /**
+   * Runs report child accepted with retry. Acceptance evidence is diagnostic
+   * rather than terminal, so a transient main/DB failure retries only until
+   * `maxDurationMs` elapses and then gives up instead of stranding the report.
+   * @param {object} args - Options.
+   * @param {string} args.jobId - Job id.
+   * @param {string} [args.handoffId] - Handoff lease id.
+   * @param {string} [args.workerId] - Worker id.
+   * @param {number} [args.handedOffAtMs] - Handed off timestamp.
+   * @param {number} [args.receivedAtMs] - Epoch ms the runner child received the job.
+   * @param {number} [args.startedAtMs] - Epoch ms the job's perform started in the child.
+   * @param {string} [args.childInstanceId] - Stable pooled child identity.
+   * @param {number} [args.childPid] - Pooled child OS pid.
+   * @param {number} args.maxDurationMs - Max duration for retries.
+   * @returns {Promise<void>} - Resolves when reported or the budget elapses.
+   */
+  async reportChildAcceptedWithRetry({jobId, handoffId, workerId, handedOffAtMs, receivedAtMs, startedAtMs, childInstanceId, childPid, maxDurationMs}) {
+    let attempt = 0
+    const startTime = Date.now()
+
+    while (true) {
+      try {
+        await this.reportChildAccepted({jobId, handoffId, workerId, handedOffAtMs, receivedAtMs, startedAtMs, childInstanceId, childPid})
+        return
+      } catch (error) {
+        attempt += 1
+        const delaySeconds = Math.min(30, 0.5 * attempt)
+
+        this.logger.debug(() => ["Background job child-acceptance report failed, retrying", error])
+
+        if (Date.now() - startTime >= maxDurationMs) {
+          this.logger.warn(() => ["Background job child-acceptance report timed out, giving up", error])
+          throw error
+        }
+
+        await wait(delaySeconds)
+      }
+    }
+  }
+
   /**
    * Runs report with retry.
    * @param {object} args - Options.
@@ -104,7 +200,7 @@ export default class BackgroundJobsStatusReporter {
    * @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`.
+   * @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 trigger orphan reclaim and would otherwise drop the completion and strand the row in `handed_off`.
    * @returns {Promise<void>} - Resolves when reported.
    */
   async reportWithRetry({jobId, status, delayMs, error, handoffId, handedOffAtMs, workerId, runnerFailure, maxDurationMs, retryPersistErrors = false}) {