velocious 1.0.630 → 1.0.632

package/README.md

@@ -32,11 +32,12 @@
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
 * Translated model attributes with current-locale relationship sorting (see [docs/translations.md](docs/translations.md))
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
+* Rails-style application process initializer teardown with immutable process identity, reverse idempotent shutdown, and explicit HTTP/background-job ownership (see [docs/application-process-lifecycle.md](docs/application-process-lifecycle.md))
 * Configurable HTTP server worker handlers plus backpressured, descriptor-only file responses with completion callbacks (see [docs/http-server.md](docs/http-server.md))
 * Default-on buffered HTTP response compression with Brotli/gzip content negotiation, global and per-response opt-outs, and HEAD-correct representation headers (see [docs/http-server.md](docs/http-server.md#response-compression))
-* Background jobs with Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, including failure events and authorized database-scoped dashboard count snapshots/deltas. Release-directory integrations have a required release-scoped jobs-main/worker generation and asynchronous retirement compliance target that current startup adoption does not implement end to end (see [docs/background-jobs.md](docs/background-jobs.md), [docs/local-background-jobs.md](docs/local-background-jobs.md), and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
+* Background jobs with Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, including failure events, authorized database-scoped dashboard counts, and an opt-in release-scoped main/worker generation protocol with acknowledged activation, asynchronous retirement, and retired-main recovery. Production compliance additionally requires downstream supervisor retention/activation ordering and release pins (see [docs/background-jobs.md](docs/background-jobs.md), [docs/local-background-jobs.md](docs/local-background-jobs.md), and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
 * Durable one-off background-job scheduling with exact epoch timestamps (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.md))
-* Rails-style request and database query logging (see [docs/logging.md](docs/logging.md))
+* Rails-style request and database query logging with structured credential redaction (see [docs/logging.md](docs/logging.md))
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
 * Trusted reverse proxy handling for `request.remoteAddress()` (see [docs/trusted-proxies.md](docs/trusted-proxies.md))
 * In-process driver schema metadata caching (see [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md))
@@ -60,6 +61,12 @@ npx velocious init
 
 By default, Velocious looks for your configuration in `src/config/configuration.js`. If you keep the configuration elsewhere, make sure your app imports it early and calls `configuration.setCurrent()`.
 
+Application initializers may implement `teardown()` and inspect their frozen
+`getProcessContext()` value. Long-lived process owners call
+`configuration.shutdown()` before framework connection cleanup; see the
+[application process lifecycle guide](docs/application-process-lifecycle.md) for
+promise identity, errors, process types, and pooled/forked runner semantics.
+
 # Node SQLite driver
 
 Projects using `velocious/build/src/database/drivers/sqlite/index.js` must install its optional peer dependencies:
@@ -1908,7 +1915,8 @@ const configuration = new Configuration({
     console: false,            // disable console output
     file: true,                // enable file output
     directory: "/custom/logs", // optional, defaults to "<project>/log" in Node
-    filePath: "/tmp/app.log"   // optional explicit path
+    filePath: "/tmp/app.log",  // optional explicit path
+    sensitiveNames: ["integrationPin"] // optional app-specific additions
   }
 })
 ```
@@ -1969,6 +1977,8 @@ Model queries use operation names such as `Task Load`, `Task Count`, `Task Pluck
 
 Query logging defaults to off in the `test` environment to keep CI output quiet and is skipped when no output emits `info`. Override it with `logging: {queryLogging: true}` when a test build should write SQL timing logs, and use the normal logging output settings to send those logs to console or file.
 
+- **Credential redaction**: Request headers, parsed body/params, nested arrays, URL queries, WebSocket authentication params, rendered SQL diagnostics, and request/frontend-model errors are redacted before formatting and output fan-out. Defaults match common authorization, authentication, credential, password, secret, token, API-key, cookie/session, and base64-content name variants case-insensitively. Add application names with `logging.sensitiveNames`; entries must be non-blank strings. Exact request-scoped values are replaced in SQL/error text while safe fields, SQL shape, timing, source lines, error class/backtrace, and correlation metadata remain visible. Import `LOG_REDACTION_MARKER` from `velocious/build/src/log-redactor.js` when code needs to compare the deterministic marker. See [logging and credential redaction](docs/logging.md#credential-redaction).
+
 ## Listen for framework errors
 
 Velocious emits framework errors (including uncaught controller action errors) on the configuration error event bus:
@@ -2321,6 +2331,11 @@ 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).
 
+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
+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).
@@ -2365,7 +2380,11 @@ export default new Configuration({
     pooledRunnerMaxRssBytes: 536870912,
     pooledRunnerMaxLifetimeMs: 3600000,
     dispatchStrategy: "beacon",
-    jobTimeoutMs: null
+    jobTimeoutMs: null,
+    // Release-directory deployments opt in with one exact id and local socket:
+    generationId: "release-20260828.1",
+    initialGenerationState: "candidate",
+    lifecycleSocketPath: "/srv/app/releases/20260828.1/run/background-jobs.sock"
   }
 })
 ```
@@ -2428,8 +2447,32 @@ VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY=beacon
 VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS=1000
 VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS=indefinite
 VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS=5400000
+# Opt-in release generation values (omit all three for exact legacy behavior):
+VELOCIOUS_BACKGROUND_JOBS_GENERATION_ID=release-20260828.1
+VELOCIOUS_BACKGROUND_JOBS_INITIAL_GENERATION_STATE=candidate
+VELOCIOUS_BACKGROUND_JOBS_LIFECYCLE_SOCKET_PATH=/srv/app/releases/20260828.1/run/background-jobs.sock
 ```
 
+Activate or retire that exact generation with one acknowledged local request:
+
+```sh
+npx velocious background-jobs:activate --generation release-20260828.1 --socket /srv/app/releases/20260828.1/run/background-jobs.sock
+npx velocious background-jobs:retire --generation release-20260828.1 --socket /srv/app/releases/20260828.1/run/background-jobs.sock
+```
+
+Each lifecycle command sends one request with no retry and has a hard 10000ms
+deadline; `--timeout-ms` accepts 1 through 25000ms. Generation-aware workers,
+clients, and reporters require their hello acknowledgement before readiness or
+mutation and bound it to 4000ms by default.
+
+Generation ids supplied through config, environment, API, or CLI must be
+identical and match `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`; invalid or conflicting
+identity fails before listening. Omit generation settings to preserve legacy
+worker ids, protocol, disconnect recovery, and custom-adapter compatibility.
+An ID-only configuration derives `candidate`; that default does not conflict
+with an explicit API/CLI `active` or `retired` recovery state, while multiple
+actual state sources must still agree.
+
 `VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS` (default: `indefinite`) bounds how long a `background-jobs-worker` waits for in-flight jobs on `SIGTERM`/`SIGINT` before terminating any forked or spawned child runners still running. The default waits for jobs to finish and never interrupts a running job; a positive finite cap is a per-worker shutdown control for an explicitly requested process stop, not the normal deploy-completion mechanism. During release retirement, the old jobs-main and workers may drain for hours after deploy returns. See [docs/background-jobs.md](docs/background-jobs.md#worker-shutdown-and-process-job-draining).
 
 `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"`.
@@ -2637,7 +2680,7 @@ Each job must define exactly one of `every` or `cron`. Cron times are evaluated
 
 ## Persistence and retries
 
-Jobs are persisted in the configured database (`backgroundJobs.databaseIdentifier`) in an internal `background_jobs` table. When a worker picks a job, the main generates a unique lease id before asking the adapter to mark the job handed off, and the worker reports completion or failure back to the main process. If that persistence call has an ambiguous result, only the exact caller-generated lease is conditionally returned; failed recovery is retained for the dispatch error-retry path, so worker admission and concurrency do not remain stranded and a newer lease is never reclaimed. Custom adapters must persist a supplied `markHandedOff({handoffId})` exactly; built-in adapters continue generating one for legacy direct callers that omit it. If a worker socket disconnects unexpectedly, only the leases handed to that exact socket are immediately returned to the queue; late reports are fenced by lease id so they cannot mutate a newer attempt. This recovery is at-least-once and may repeat application side effects if the disconnected attempt had already started them. Gracefully draining workers keep their leases while they finish. Startup reconnection/adoption is an abnormal crash/legacy-recovery facility, not the normal deploy topology: during ordinary release retirement the old main remains alive and owns its old workers, and they must not reconnect to the new main. A production integration that restarts jobs-main every deploy and depends on worker adoption is not compliant with the release-generation contract. See [release-generation draining](docs/background-jobs.md#release-generation-draining) and [worker disconnect recovery](docs/background-jobs.md#worker-disconnect-recovery).
+Jobs are persisted in the configured database (`backgroundJobs.databaseIdentifier`) in an internal `background_jobs` table. When a worker picks a job, the main generates a unique lease id before asking the adapter to mark the job handed off, and the worker reports completion or failure back to the main process. If that persistence call has an ambiguous result, only the exact caller-generated lease is conditionally returned; failed recovery is retained for the dispatch error-retry path, so worker admission and concurrency do not remain stranded and a newer lease is never reclaimed. Custom adapters must persist a supplied `markHandedOff({handoffId})` exactly; built-in adapters continue generating one for legacy direct callers that omit it. A legacy worker disconnect returns only that socket's leases immediately. Generation mode instead preserves the exact leases through reconnect grace for the same qualified worker, then returns them to the global queue on expiry. Late reports are fenced by generation-qualified worker id, lease id, and handoff time so they cannot mutate a newer attempt. This recovery is at-least-once and may repeat application side effects if the disconnected attempt had already started them. A release-retiring worker revokes readiness but retains heartbeat, its unchanged old endpoint, exact-generation reconnect, accepted work, child execution, durable reports, and acknowledgements until its drain settles; retiring/retired mains reject new identities and never grant reconnecting workers readiness. Startup reconnection/adoption is an abnormal crash/legacy-recovery facility, not the normal deploy topology: during ordinary release retirement the old main remains alive and owns its old workers, and they must not reconnect to the new main. A production integration that restarts jobs-main on every deploy and depends on worker adoption is not compliant with the release-generation contract. See [release-generation draining](docs/background-jobs.md#release-generation-draining) and [worker disconnect recovery](docs/background-jobs.md#worker-disconnect-recovery).
 
 Failed jobs are re-queued with backoff and retried up to 10 times by default (10s, 1m, 10m, 1h, then +1h per retry). You can override the retry limit per job:
 

package/build/application.js

@@ -9,6 +9,7 @@ import SyncPublisher from "./sync/sync-publisher.js"
 import SyncWebsocketChannel from "./sync/sync-websocket-channel.js"
 import websocketEventsHost from "./http-server/websocket-events-host.js"
 import restArgsError from "./utils/rest-args-error.js"
+import { runShutdownSteps } from "./utils/shutdown-lifecycle.js"
 
 /**
  * HttpServerConfiguration type.
@@ -40,6 +41,8 @@ export default class VelociousApplication {
      * Stores the http server lock value.
      * @type {HttpServerLock | undefined} */
     this.httpServerLock = undefined
+    /** @type {Promise<void> | undefined} */
+    this._stopPromise = undefined
   }
 
   /**
@@ -186,17 +189,34 @@ export default class VelociousApplication {
    * Runs stop.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async stop() {
-    await this.logger.debug("Stopping server")
+  stop() {
+    if (!this._stopPromise) this._stopPromise = this._stop()
 
-    try {
-      await this.httpServer?.stop()
-      this.configuration._httpServerInstance = undefined
-      await this.configuration.disconnectBeacon()
-      await this.configuration.closeDatabaseConnections()
-    } finally {
-      await this.releaseHttpServerLock()
-    }
+    return this._stopPromise
+  }
+
+  /**
+   * Stops application and framework resources.
+   * @returns {Promise<void>} - Resolves after every application and framework close succeeds.
+   */
+  async _stop() {
+    await runShutdownSteps({
+      message: "Application and framework shutdown failed",
+      steps: [
+        async () => await this.logger.debug("Stopping server"),
+        async () => {
+          try {
+            await this.httpServer?.stop()
+          } finally {
+            this.configuration._httpServerInstance = undefined
+          }
+        },
+        async () => await this.configuration.shutdown(),
+        async () => await this.configuration.disconnectBeacon(),
+        async () => await this.configuration.closeDatabaseConnections(),
+        async () => await this.releaseHttpServerLock()
+      ]
+    })
   }
 
   /**

package/build/background-jobs/adapter.js

@@ -6,6 +6,14 @@
  * separate concerns.
  */
 export default class BackgroundJobsAdapter {
+  /**
+   * Declares exact durable fencing support for release-scoped generations.
+   * Third-party adapters must override this only after implementing the full
+   * snapshot, owner, report, and recovery contract.
+   * @returns {boolean} - Whether generation mode is supported.
+   */
+  supportsReleaseScopedGenerations() { return false }
+
   /**
    * Ensures the adapter can accept work.
    * @returns {Promise<void>} - Resolves when ready.

package/build/background-jobs/client.js

@@ -3,6 +3,7 @@
 import timeout from "awaitery/build/timeout.js"
 import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobsSocketRequest from "./socket-request.js"
+import { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
 
 const DEFAULT_ENQUEUE_TIMEOUT_MS = 5000
 
@@ -12,10 +13,14 @@ export default class BackgroundJobsClient {
    * @param {object} [args] - Options.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration.
    * @param {number} [args.enqueueTimeoutMs] - Maximum time to wait for an enqueue acknowledgement in milliseconds (default: 5000).
+   * @param {number} [args.generationHandshakeTimeoutMs] - Maximum time to wait for generation acknowledgement (default: 4000).
+   * @param {string} [args.generationId] - Explicit release generation identity.
    */
-  constructor({configuration, enqueueTimeoutMs = DEFAULT_ENQUEUE_TIMEOUT_MS} = {}) {
+  constructor({configuration, enqueueTimeoutMs = DEFAULT_ENQUEUE_TIMEOUT_MS, generationHandshakeTimeoutMs = DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, generationId} = {}) {
     this.configurationPromise = configuration ? Promise.resolve(configuration) : configurationResolver()
     this.enqueueTimeoutMs = enqueueTimeoutMs
+    this.generationHandshakeTimeoutMs = validateGenerationHandshakeTimeoutMs(generationHandshakeTimeoutMs)
+    this.explicitGenerationId = generationId
   }
 
   /**
@@ -25,8 +30,12 @@ export default class BackgroundJobsClient {
   async _request() {
     const configuration = await this.configurationPromise
     const {host, port} = configuration.getBackgroundJobsConfig()
+    const {generationId} = configuration.resolveBackgroundJobsGenerationConfig({
+      generationId: this.explicitGenerationId,
+      sourceName: "BackgroundJobsClient"
+    })
 
-    return new BackgroundJobsSocketRequest({host, port, role: "client"})
+    return new BackgroundJobsSocketRequest({host, port, role: "client", generationHandshakeTimeoutMs: this.generationHandshakeTimeoutMs, generationId})
   }
 
   /**

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

@@ -10,8 +10,8 @@ import setRunnerProcessTitle from "./runner-process-title.js"
 // which jobs are running, how many of each, and which are eating resources.
 setRunnerProcessTitle()
 
-let finishing = false
-let shuttingDown = false
+/** @type {Promise<void> | undefined} */
+let shutdownPromise
 
 /**
  * Closes the runner's connections — releasing any advisory lock a killed-mid-job
@@ -21,12 +21,15 @@ let shuttingDown = false
  * @param {number} exitCode - Process exit code.
  * @returns {Promise<void>}
  */
-async function shutdownRunner(exitCode) {
-  if (shuttingDown || finishing) return
-  shuttingDown = true
+function shutdownRunner(exitCode) {
+  if (shutdownPromise) return shutdownPromise
 
-  await closeRunnerConnections(currentConfigurationOrNull())
-  process.exit(exitCode)
+  shutdownPromise = (async () => {
+    await closeRunnerConnections(currentConfigurationOrNull())
+    process.exit(exitCode)
+  })()
+
+  return shutdownPromise
 }
 
 /**
@@ -45,25 +48,13 @@ function isJobMessage(message) {
 /**
  * Runs finish.
  * @param {number} exitCode - Process exit code.
- * @returns {void}
+ * @returns {Promise<void>}
  */
-function finish(exitCode) {
-  finishing = true
-  process.exitCode = exitCode
-
-  if (process.connected && process.disconnect) {
-    process.disconnect()
+async function finish(exitCode) {
+  if (process.send) {
+    await new Promise((resolve) => process.send?.({type: "job-reported"}, () => resolve(undefined)))
   }
-
-  setImmediate(() => process.exit(exitCode))
-}
-
-/**
- * Runs report job finished.
- * @returns {void}
- */
-function reportJobFinished() {
-  if (process.send) process.send({type: "job-reported"})
+  await shutdownRunner(exitCode)
 }
 
 /**
@@ -79,7 +70,10 @@ async function runJobMessage(message) {
   // The per-job process title (and its restore) is set inside runJobPayload,
   // which reads the job class's `static processTitle`. This process boots with
   // the base "velocious background-jobs-runner" title set at module load above.
-  await runJobPayload(message.payload, {closeConnections: false})
+  await runJobPayload(message.payload, {
+    closeConnections: false,
+    processType: "background-jobs-forked-runner"
+  })
 }
 
 /**
@@ -88,15 +82,17 @@ async function runJobMessage(message) {
  * @returns {Promise<void>} - Resolves after completion is reported.
  */
 async function handleJobMessage(message) {
+  let exitCode
+
   try {
     await runJobMessage(message)
-    reportJobFinished()
-    finish(0)
+    exitCode = 0
   } catch (error) {
-    reportJobFinished()
     console.error("Forked background job runner failed:", error)
-    finish(1)
+    exitCode = 1
   }
+
+  await finish(exitCode)
 }
 
 for (const signal of ["SIGTERM", "SIGINT"]) {
@@ -104,7 +100,7 @@ for (const signal of ["SIGTERM", "SIGINT"]) {
 }
 
 process.once("disconnect", () => {
-  if (!finishing) void shutdownRunner(0)
+  void shutdownRunner(0)
 })
 
 process.once("message", (message) => {

package/build/background-jobs/generation-handshake-timeout-error.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+export const DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS = 4000
+
+/** Actionable failure for an unacknowledged generation hello. */
+export default class BackgroundJobsGenerationHandshakeTimeoutError extends Error {
+  /**
+   * Creates an actionable generation-handshake deadline failure.
+   * @param {object} args - Timeout context.
+   * @param {string} args.endpoint - Main endpoint.
+   * @param {string} args.generationId - Expected generation.
+   * @param {"worker" | "client" | "reporter"} args.role - Initiating peer role.
+   * @param {number} args.timeoutMs - Handshake deadline.
+   */
+  constructor({endpoint, generationId, role, timeoutMs}) {
+    super(`Background jobs ${role} generation handshake for ${generationId} timed out after ${timeoutMs}ms at ${endpoint}`)
+    this.name = "BackgroundJobsGenerationHandshakeTimeoutError"
+  }
+}
+
+/**
+ * Validates a generation handshake deadline.
+ * @param {number} timeoutMs - Candidate deadline.
+ * @returns {number} - Valid deadline.
+ */
+export function validateGenerationHandshakeTimeoutMs(timeoutMs) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647) {
+    throw new TypeError("generationHandshakeTimeoutMs must be an integer between 1 and 2147483647")
+  }
+
+  return timeoutMs
+}

package/build/background-jobs/generation-identity.js

@@ -0,0 +1,160 @@
+// @ts-check
+
+import { utf8ByteLength } from "../utils/utf8-byte-length.js"
+
+/**
+ * @typedef {object} GenerationValueSource
+ * @property {string} name - Human-readable source name.
+ * @property {boolean} present - Whether the source was explicitly supplied.
+ * @property {ReturnType<typeof JSON.parse> | undefined} value - Supplied value.
+ */
+
+const GENERATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const WORKER_INSTANCE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const INITIAL_GENERATION_STATES = new Set(["candidate", "active", "retired"])
+
+/**
+ * Validates one release generation identifier.
+ * @param {ReturnType<typeof JSON.parse> | undefined} value - Candidate value.
+ * @param {string} [sourceName] - Source label for failures.
+ * @returns {string} - Valid generation id.
+ */
+export function validateGenerationId(value, sourceName = "background jobs generationId") {
+  if (typeof value !== "string" || !GENERATION_ID_PATTERN.test(value)) {
+    throw new TypeError(`${sourceName} must match ${GENERATION_ID_PATTERN}`)
+  }
+
+  return value
+}
+
+/**
+ * Resolves explicitly present generation identity sources without precedence.
+ * @param {GenerationValueSource[]} sources - Identity sources.
+ * @returns {string | undefined} - Identical resolved identity or legacy unset.
+ */
+export function resolveGenerationId(sources) {
+  const presentSources = sources.filter((source) => source.present)
+
+  if (presentSources.length === 0) return undefined
+
+  const values = presentSources.map((source) => validateGenerationId(source.value, source.name))
+  const generationId = values[0]
+
+  if (values.some((value) => value !== generationId)) {
+    const names = presentSources.map((source) => source.name).join(", ")
+
+    throw new Error(`Conflicting background jobs generation identities from: ${names}`)
+  }
+
+  return generationId
+}
+
+/**
+ * Resolves the boot lifecycle state.
+ * @param {GenerationValueSource[]} sources - State sources.
+ * @param {string | undefined} generationId - Resolved generation identity.
+ * @returns {import("./types.js").BackgroundJobsGenerationInitialState | "active"} - Boot state.
+ */
+export function resolveInitialGenerationState(sources, generationId) {
+  const presentSources = sources.filter((source) => source.present)
+
+  if (presentSources.length === 0) return generationId ? "candidate" : "active"
+  if (!generationId) throw new Error("backgroundJobs.initialGenerationState requires backgroundJobs.generationId")
+
+  const values = presentSources.map((source) => {
+    if (typeof source.value !== "string" || !INITIAL_GENERATION_STATES.has(source.value)) {
+      throw new TypeError(`${source.name} must be "candidate", "active", or "retired"`)
+    }
+
+    return /** @type {import("./types.js").BackgroundJobsGenerationInitialState} */ (source.value)
+  })
+  const state = values[0]
+
+  if (values.some((value) => value !== state)) {
+    const names = presentSources.map((source) => source.name).join(", ")
+
+    throw new Error(`Conflicting background jobs initialGenerationState values from: ${names}`)
+  }
+
+  return state
+}
+
+/**
+ * Resolves the optional release-local lifecycle socket path.
+ * @param {GenerationValueSource[]} sources - Path sources.
+ * @param {string | undefined} generationId - Resolved generation identity.
+ * @returns {string | undefined} - Absolute Unix socket path.
+ */
+export function resolveLifecycleSocketPath(sources, generationId) {
+  const presentSources = sources.filter((source) => source.present)
+
+  if (presentSources.length === 0) return undefined
+  if (!generationId) throw new Error("backgroundJobs.lifecycleSocketPath requires backgroundJobs.generationId")
+
+  const values = presentSources.map((source) => {
+    if (typeof source.value !== "string" || !source.value.startsWith("/") || source.value.includes("\0")) {
+      throw new TypeError(`${source.name} must be an absolute Unix socket path`)
+    }
+
+    if (utf8ByteLength(source.value) > 103) {
+      throw new TypeError(`${source.name} must be at most 103 UTF-8 bytes for portable Unix socket support`)
+    }
+
+    return source.value
+  })
+  const socketPath = values[0]
+
+  if (values.some((value) => value !== socketPath)) {
+    const names = presentSources.map((source) => source.name).join(", ")
+
+    throw new Error(`Conflicting background jobs lifecycle socket paths from: ${names}`)
+  }
+
+  return socketPath
+}
+
+/**
+ * Creates the exact durable worker owner token.
+ * @param {object} args - Owner parts.
+ * @param {string} args.generationId - Release generation.
+ * @param {string} args.workerInstanceId - Worker process UUID.
+ * @returns {string} - Generation-qualified durable worker id.
+ */
+export function createGenerationWorkerId({generationId, workerInstanceId}) {
+  validateGenerationId(generationId)
+  if (!WORKER_INSTANCE_ID_PATTERN.test(workerInstanceId)) throw new TypeError("workerInstanceId must be a UUID")
+
+  return `${generationId}:${workerInstanceId}`
+}
+
+/**
+ * Parses a generation-qualified durable worker id.
+ * @param {ReturnType<typeof JSON.parse>} workerId - Durable worker id.
+ * @returns {{generationId: string, workerInstanceId: string} | null} - Parsed owner or null.
+ */
+export function parseGenerationWorkerId(workerId) {
+  if (typeof workerId !== "string") return null
+
+  const separatorIndex = workerId.indexOf(":")
+  if (separatorIndex < 1 || separatorIndex !== workerId.lastIndexOf(":")) return null
+
+  const generationId = workerId.slice(0, separatorIndex)
+  const workerInstanceId = workerId.slice(separatorIndex + 1)
+
+  if (!GENERATION_ID_PATTERN.test(generationId) || !WORKER_INSTANCE_ID_PATTERN.test(workerInstanceId)) return null
+
+  return {generationId, workerInstanceId}
+}
+
+/**
+ * Checks exact parsed generation ownership.
+ * @param {object} args - Ownership query.
+ * @param {string} args.generationId - Expected generation.
+ * @param {ReturnType<typeof JSON.parse>} args.workerId - Durable worker id.
+ * @returns {boolean} - Whether the parsed owner belongs to the generation.
+ */
+export function workerIdBelongsToGeneration({generationId, workerId}) {
+  const parsed = parseGenerationWorkerId(workerId)
+
+  return parsed?.generationId === generationId
+}

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 { closeRunnerConnections } from "./runner-graceful-shutdown.js"
 
 const BEACON_READY_TIMEOUT_MS = 5000
 
@@ -80,12 +81,13 @@ 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 {string} [options.processType] - Generic application process type.
  * @returns {Promise<"completed" | "rescheduled">} - Acknowledged outcome.
  */
-export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true} = {}) {
+export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true, processType = "background-jobs-runner"} = {}) {
   const configuration = await configurationResolver()
   configuration.setCurrent()
-  await configuration.initialize({type: "background-jobs-runner"})
+  await configuration.initialize({type: processType})
   await connectBeacon(configuration)
   const reporter = new BackgroundJobsStatusReporter({configuration})
 
@@ -167,11 +169,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
     // one) doesn't misreport a finished job as still running.
     if (manageProcessTitle) process.title = previousTitle
     if (closeConnections) {
-      try {
-        await configuration.disconnectBeacon()
-      } finally {
-        await configuration.closeDatabaseConnections()
-      }
+      await closeRunnerConnections(configuration)
     }
   }
 }