velocious 1.0.665 → 1.0.667

package/README.md

@@ -37,7 +37,7 @@
 * Explicit database-free in-process HTTP applications with optional request and buffered-response byte limits (see [docs/http-server.md](docs/http-server.md#database-free-applications))
 * 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, 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))
+* Durable one-off background-job scheduling with exact epoch timestamps plus stable replacement, cancellation, normalized readback, and duplicate-free wake across Node SQL/TCP and Browser/Expo local SQLite adapters (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.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))
@@ -880,7 +880,7 @@ Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle
 Frontend-model HTTP requests always use `credentials: "include"` so shared custom commands can set session cookies without app-level transport overrides.
 
 Unexpected frontend-model endpoint failures return their original message and full stack trace by default in every environment, including production. Responses use `errorType: "internal_error"`, a server-generated `correlationId` shared with the matching framework-error report, and the established `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields without adding irrelevant debug fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
-Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors. Shared index payloads reject unknown top-level keys per request, including wrapper nesting such as `payload.query.where`; use `payload.where` directly.
+Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors. Shared index payloads reject unknown top-level keys per request, including wrapper nesting such as `payload.query.where`; use `payload.where` directly. Legacy shared index callers may send `payload.authenticationToken`, which is extracted into request context before validation; it is not a query option, `requestContext.authenticationToken` wins when both are present, and unrelated unknown keys still fail. See [frontend-model transport](docs/frontend-models.md#core-transport).
 Invalid frontend-model write attributes and attachment names, including attributes rejected by `permittedParams()`, return the specific safe error message with `velocious.code: "frontend-model-attribute-error"` and are not emitted as framework errors.
 To mask unexpected internal details, explicitly opt out for the application configuration:
 
@@ -2723,13 +2723,22 @@ const result = await MyJob.replaceScheduled({
 await MyJob.cancelScheduled(`event:${eventId}:reminder:24h`)
 ```
 
-A queued owner is atomically cancelled during replacement/cancellation. Its acknowledgement waits for the corresponding dispatch drain lifecycle; if another drain is already active, the request coalesces and waits for its re-drain and future-job timer re-arm instead of acknowledging early. A `previousStatus` or cancellation `outcome` of `"handed_off"` means the worker may already be running; Velocious removes or replaces key ownership but does not claim that JavaScript stopped. Store a generation/revision in application state, pass it to the job, and re-check it immediately before irreversible effects. Stable keys and full result shapes are documented in [Scheduling One-Off Background Jobs](docs/scheduled-background-job-enqueue.md#replacing-or-cancelling-a-logical-schedule).
+Read the durable owner/history or expedite the same queued row without creating another job:
+
+```js
+const scheduled = await MyJob.getScheduledJob(`event:${eventId}:reminder:24h`, {
+  includeLatestTerminal: true
+})
+const wake = await MyJob.wakeScheduled(`event:${eventId}:reminder:24h`)
+```
+
+A queued owner is atomically cancelled during replacement/cancellation. On Node/TCP, its acknowledgement waits for the corresponding main-process dispatch drain lifecycle. The local adapter commits an adapter-owned transaction before its dispatcher wake runs; inside an ambient application transaction, the mutation and wake remain deferred to that outer commit. Readback returns normalized public jobs, including the transaction-assigned `scheduleOrder` used for causal history ordering; Node retains the per-key order high-water mark when terminal history is pruned. Wake moves only a future queued owner's eligibility to now while preserving its id, attempts, last error, and lineage; repeated calls never enqueue duplicates. A `previousStatus`, cancellation `outcome`, or wake `outcome` of `"handed_off"` means the worker may already be running; Velocious removes or replaces key ownership where appropriate but does not claim that JavaScript stopped. Store a generation/revision in application state, pass it to the job, and re-check it immediately before irreversible effects. Stable keys and full result shapes are documented in [Scheduling One-Off Background Jobs](docs/scheduled-background-job-enqueue.md#replacing-or-cancelling-a-logical-schedule).
 
 Set `deduplicateWhileQueued: true` to coalesce an enqueue onto the earliest identical queued job with the same job name, arguments, and queue when that existing job is scheduled no later than the new request. A retry backed off into the future does not suppress a new immediate enqueue, while repeated immediate triggers and equal or later schedules still coalesce.
 
 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 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).
+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. Only a post-send acknowledgement deadline raises `BackgroundJobEnqueueAcknowledgementTimeoutError`, an Awaitery `TimeoutError` subtype with code `BACKGROUND_JOB_ENQUEUE_ACKNOWLEDGEMENT_TIMEOUT` and frozen, payload-free attempt history. The error proves the request was sent but cannot say whether the main committed it. 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. If that replay also times out, the final typed error describes both timed-out attempts. 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"}`.
 
@@ -2817,7 +2826,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. 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).
+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, starting that grace only after active ownership completes its initial startup drain, then returns absent workers' leases 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/background-jobs/adapter-client.js

@@ -42,4 +42,26 @@ export default class BackgroundJobsAdapterClient {
 
     return await adapter.cancelScheduled(scheduleKey)
   }
+
+  /**
+   * Reads a stable schedule through the configured adapter.
+   * @param {{scheduleKey: string, includeLatestTerminal?: boolean}} args - Lookup request.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+   */
+  async getScheduledJob({scheduleKey, includeLatestTerminal}) {
+    const adapter = await this.configuration.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.getScheduledJob(scheduleKey, {includeLatestTerminal})
+  }
+
+  /**
+   * Wakes a stable schedule through the configured adapter.
+   * @param {{scheduleKey: string}} args - Wake request.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+   */
+  async wakeScheduled({scheduleKey}) {
+    const adapter = await this.configuration.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.wakeScheduled(scheduleKey)
+  }
 }

package/build/background-jobs/adapter.js

@@ -93,6 +93,21 @@ export default class BackgroundJobsAdapter {
    */
   async cancelScheduled(_scheduleKey) { throw new Error("BackgroundJobsAdapter#cancelScheduled is not implemented") }
 
+  /**
+   * Reads current stable ownership and optional terminal history.
+   * @param {string} _scheduleKey - Stable schedule key.
+   * @param {{includeLatestTerminal?: boolean}} [_options] - Lookup options.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized public jobs.
+   */
+  async getScheduledJob(_scheduleKey, _options = {}) { throw new Error("BackgroundJobsAdapter#getScheduledJob is not implemented") }
+
+  /**
+   * Expedites a future queued stable owner without changing its identity.
+   * @param {string} _scheduleKey - Stable schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+   */
+  async wakeScheduled(_scheduleKey) { throw new Error("BackgroundJobsAdapter#wakeScheduled is not implemented") }
+
   /**
    * Finds the next eligible job.
    * @param {{executionMode?: import("./types.js").BackgroundJobExecutionMode | import("./types.js").BackgroundJobExecutionMode[]}} [_args] - Dequeue filters.

package/build/background-jobs/client.js

@@ -1,11 +1,82 @@
 // @ts-check
 
-import timeout from "awaitery/build/timeout.js"
+import timeout, { TimeoutError } from "awaitery/build/timeout.js"
 import configurationResolver from "../configuration-resolver.js"
+import isPlainObject from "../utils/plain-object.js"
+import BackgroundJobEnqueueAcknowledgementTimeoutError from "./enqueue-acknowledgement-timeout-error.js"
 import BackgroundJobsSocketRequest from "./socket-request.js"
 import { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
+import { BACKGROUND_JOB_ACTIVE_STATUSES, BACKGROUND_JOB_EXECUTION_MODES, BACKGROUND_JOB_STATUSES, BACKGROUND_JOB_TERMINAL_STATUSES } from "./job-semantics.js"
 
 const DEFAULT_ENQUEUE_TIMEOUT_MS = 5000
+const BACKGROUND_JOB_WAKE_OUTCOMES = ["woken", "already_due", "handed_off", "not_found"]
+const BACKGROUND_JOB_NULLABLE_NUMBER_FIELDS = [
+  "attempts",
+  "childPid",
+  "childReceivedAtMs",
+  "childStartedAtMs",
+  "completedAtMs",
+  "createdAtMs",
+  "failedAtMs",
+  "handedOffAtMs",
+  "maxConcurrency",
+  "maxRetries",
+  "orphanedAtMs",
+  "scheduleOrder",
+  "scheduledAtMs",
+  "timeoutMs"
+]
+const BACKGROUND_JOB_NULLABLE_STRING_FIELDS = ["childInstanceId", "concurrencyKey", "handoffId", "lastError", "scheduleKey", "workerId"]
+
+/**
+ * Checks a required nullable number from a normalized wire row.
+ * @param {ReturnType<typeof JSON.parse>} value - Field value.
+ * @returns {boolean} - Whether the field is null or a finite number.
+ */
+function isNullableBackgroundJobNumber(value) {
+  return value === null || (typeof value === "number" && Number.isFinite(value))
+}
+
+/**
+ * Checks a required nullable string from a normalized wire row.
+ * @param {ReturnType<typeof JSON.parse>} value - Field value.
+ * @returns {boolean} - Whether the field is null or a string.
+ */
+function isNullableBackgroundJobString(value) {
+  return value === null || typeof value === "string"
+}
+
+/**
+ * Checks that a transport job uses the normalized public camel-case shape.
+ * @param {ReturnType<typeof JSON.parse>} value - Transport value.
+ * @returns {value is import("./types.js").BackgroundJobRow} - Whether normalized.
+ */
+function isNormalizedBackgroundJob(value) {
+  if (!isPlainObject(value)) return false
+
+  const job = value
+
+  return typeof job.id === "string"
+    && typeof job.jobName === "string"
+    && Array.isArray(job.args)
+    && BACKGROUND_JOB_EXECUTION_MODES.some((executionMode) => executionMode === job.executionMode)
+    && typeof job.queue === "string"
+    && BACKGROUND_JOB_STATUSES.some((status) => status === job.status)
+    && BACKGROUND_JOB_NULLABLE_NUMBER_FIELDS.every((field) => isNullableBackgroundJobNumber(job[field]))
+    && BACKGROUND_JOB_NULLABLE_STRING_FIELDS.every((field) => isNullableBackgroundJobString(job[field]))
+}
+
+/**
+ * Describes an unexpected protocol response without echoing its payload.
+ * @param {string} operation - Public operation name.
+ * @param {import("./types.js").BackgroundJobSocketMessage} message - Response.
+ * @returns {Error} - Protocol error.
+ */
+function unexpectedResponseError(operation, message) {
+  const responseType = message && typeof message.type === "string" ? message.type : "missing type"
+
+  return new Error(`Unexpected ${operation} response: ${responseType}`)
+}
 
 export default class BackgroundJobsClient {
   /**
@@ -57,17 +128,36 @@ export default class BackgroundJobsClient {
       ...(producerInvocationId ? {producerInvocationId} : {}),
       ...(producerProof ? {producerProof} : {})
     }
-    const acknowledgement = {explicitlyRejected: false, generationFenced: false, requestSent: false}
+    /**
+     * Creates safe observations for one attempt without retaining request data.
+     * @param {object} args - Attempt identity.
+     * @param {"initial" | "owned_replay"} args.attemptKind - Initial attempt or owned replay.
+     * @param {number} args.attemptNumber - One-based attempt number.
+     * @returns {import("./enqueue-acknowledgement-timeout-error.js").BackgroundJobEnqueueAttempt} - Mutable attempt observations.
+     */
+    const newAttemptObservation = ({attemptKind, attemptNumber}) => ({
+      acknowledgementWaitElapsedMs: 0,
+      attemptElapsedMs: 0,
+      attemptKind,
+      attemptNumber,
+      explicitlyRejected: false,
+      generationFenced: false,
+      requestSent: false
+    })
     /**
      * Sends one enqueue attempt. An owned caller may replay this exact message
      * once when transport acknowledgement remains ambiguous after send.
-     * @param {{explicitlyRejected: boolean, generationFenced: boolean, requestSent: boolean} | undefined} attemptAcknowledgement - First-attempt observations.
+     * @param {import("./enqueue-acknowledgement-timeout-error.js").BackgroundJobEnqueueAttempt} attemptObservation - Mutable attempt observations.
+     * @param {Readonly<Array<import("./enqueue-acknowledgement-timeout-error.js").BackgroundJobEnqueueAttempt>>} previousAttempts - Earlier timed-out attempts.
      * @returns {Promise<string>} - Job id.
      */
-    const enqueueAttempt = async (attemptAcknowledgement) => {
+    const enqueueAttempt = async (attemptObservation, previousAttempts) => {
+      const attemptStartedAtMs = Date.now()
       const request = await this._request()
       const requestAbortController = new AbortController()
       const timeoutErrorMessage = `Background job enqueue acknowledgement timed out after ${this.enqueueTimeoutMs}ms`
+      /** @type {number | undefined} */
+      let requestSentAtMs
       /**
        * Resolves the pre-send phase when the mutation has entered the socket.
        * @type {() => void}
@@ -99,10 +189,9 @@ export default class BackgroundJobsClient {
         signal: requestAbortController.signal,
         onConnect: (jsonSocket) => {
           jsonSocket.send(message)
-          if (attemptAcknowledgement) {
-            attemptAcknowledgement.generationFenced = Boolean(request.generationId)
-            attemptAcknowledgement.requestSent = true
-          }
+          attemptObservation.generationFenced = Boolean(request.generationId)
+          attemptObservation.requestSent = true
+          requestSentAtMs = Date.now()
           markRequestSent()
         },
         onMessage: ({message, resolve, reject}) => {
@@ -112,7 +201,7 @@ export default class BackgroundJobsClient {
           }
 
           if (message?.type === "enqueue-error") {
-            if (attemptAcknowledgement) attemptAcknowledgement.explicitlyRejected = true
+            attemptObservation.explicitlyRejected = true
             reject(new Error(message.error || "Failed to enqueue job"))
           }
         }
@@ -120,16 +209,43 @@ export default class BackgroundJobsClient {
 
       await withEnqueueTimeout(async () => await Promise.race([requestSent, requestPromise]))
 
-      return await withEnqueueTimeout(async () => await requestPromise)
+      try {
+        return await withEnqueueTimeout(async () => await requestPromise)
+      } catch (error) {
+        if (!(error instanceof TimeoutError)) throw error
+        if (requestSentAtMs === undefined) throw new Error("Background job enqueue acknowledgement wait started before the request was sent", {cause: error})
+
+        const timedOutAtMs = Date.now()
+        // The fired timer proves its logical deadline even when the adjustable wall clock reports a shorter interval.
+        const acknowledgementWaitElapsedMs = Math.max(this.enqueueTimeoutMs, timedOutAtMs - requestSentAtMs)
+
+        attemptObservation.acknowledgementWaitElapsedMs = acknowledgementWaitElapsedMs
+        attemptObservation.attemptElapsedMs = Math.max(acknowledgementWaitElapsedMs, timedOutAtMs - attemptStartedAtMs)
+
+        throw new BackgroundJobEnqueueAcknowledgementTimeoutError({
+          acknowledgementTimeoutMs: this.enqueueTimeoutMs,
+          attemptHistory: [...previousAttempts, attemptObservation],
+          cause: error,
+          generationId: request.generationId,
+          jobName,
+          producerInvocationId,
+          producerProofPresent: Boolean(producerProof)
+        })
+      }
     }
 
+    const initialAttempt = newAttemptObservation({attemptKind: "initial", attemptNumber: 1})
+
     try {
-      return await enqueueAttempt(acknowledgement)
+      return await enqueueAttempt(initialAttempt, [])
     } catch (error) {
-      if (!producerInvocationId || !producerProof || !acknowledgement.generationFenced || !acknowledgement.requestSent || acknowledgement.explicitlyRejected) throw error
-    }
+      if (!producerInvocationId || !producerProof || !initialAttempt.generationFenced || !initialAttempt.requestSent || initialAttempt.explicitlyRejected) throw error
+
+      const previousAttempts = error instanceof BackgroundJobEnqueueAcknowledgementTimeoutError ? error.attemptHistory : []
+      const replayAttempt = newAttemptObservation({attemptKind: "owned_replay", attemptNumber: 2})
 
-    return await enqueueAttempt(undefined)
+      return await enqueueAttempt(replayAttempt, previousAttempts)
+    }
   }
 
   /**
@@ -190,4 +306,80 @@ export default class BackgroundJobsClient {
       }
     })
   }
+
+  /**
+   * Reads current stable ownership and optional terminal history.
+   * @param {{scheduleKey: string, includeLatestTerminal?: boolean}} args - Lookup request.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+   */
+  async getScheduledJob({scheduleKey, includeLatestTerminal}) {
+    const request = await this._request()
+
+    return await request.run({
+      onConnect: (jsonSocket) => {
+        jsonSocket.send({type: "get-scheduled-job", scheduleKey, includeLatestTerminal})
+      },
+      onMessage: ({message, resolve, reject}) => {
+        if (message?.type === "scheduled-job") {
+          const {currentJob, latestTerminalJob} = message
+          const currentJobValid = currentJob === null
+            || (isNormalizedBackgroundJob(currentJob) && BACKGROUND_JOB_ACTIVE_STATUSES.some((status) => status === currentJob.status))
+          const latestTerminalJobValid = latestTerminalJob === null
+            || (isNormalizedBackgroundJob(latestTerminalJob) && BACKGROUND_JOB_TERMINAL_STATUSES.some((status) => status === latestTerminalJob.status))
+
+          if (!currentJobValid || !latestTerminalJobValid) {
+            reject(new Error("Invalid getScheduledJob response: expected normalized public job values"))
+            return
+          }
+
+          resolve({currentJob, latestTerminalJob})
+          return
+        }
+
+        if (message?.type === "get-scheduled-job-error") {
+          reject(new Error(message.error || "Failed to read scheduled job"))
+          return
+        }
+
+        reject(unexpectedResponseError("getScheduledJob", message))
+      }
+    })
+  }
+
+  /**
+   * Expedites a future queued stable owner without changing job identity.
+   * @param {{scheduleKey: string}} args - Wake request.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+   */
+  async wakeScheduled({scheduleKey}) {
+    const request = await this._request()
+
+    return await request.run({
+      onConnect: (jsonSocket) => {
+        jsonSocket.send({type: "wake-scheduled", scheduleKey})
+      },
+      onMessage: ({message, resolve, reject}) => {
+        if (message?.type === "schedule-woken") {
+          const outcome = message.outcome
+          const knownOutcome = BACKGROUND_JOB_WAKE_OUTCOMES.includes(outcome)
+          const validJobId = outcome === "not_found" ? message.jobId === null : typeof message.jobId === "string" && message.jobId.length > 0
+
+          if (!knownOutcome || !validJobId) {
+            reject(new Error("Invalid wakeScheduled response"))
+            return
+          }
+
+          resolve({jobId: message.jobId, outcome})
+          return
+        }
+
+        if (message?.type === "wake-scheduled-error") {
+          reject(new Error(message.error || "Failed to wake scheduled job"))
+          return
+        }
+
+        reject(unexpectedResponseError("wakeScheduled", message))
+      }
+    })
+  }
 }

package/build/background-jobs/enqueue-acknowledgement-timeout-error.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+import {TimeoutError} from "awaitery/build/timeout.js"
+
+/**
+ * @typedef {object} BackgroundJobEnqueueAttempt
+ * @property {number} acknowledgementWaitElapsedMs - Time spent waiting for the acknowledgement after send.
+ * @property {number} attemptElapsedMs - Total attempt time including connection and generation fencing.
+ * @property {"initial" | "owned_replay"} attemptKind - Initial attempt or the one eligible owned replay.
+ * @property {number} attemptNumber - One-based attempt number.
+ * @property {boolean} explicitlyRejected - Whether the main explicitly rejected the enqueue.
+ * @property {boolean} generationFenced - Whether the configured generation accepted the connection before send.
+ * @property {boolean} requestSent - Whether the enqueue request entered the socket.
+ */
+
+/** Safe typed failure for an ambiguous post-send enqueue acknowledgement timeout. */
+export default class BackgroundJobEnqueueAcknowledgementTimeoutError extends TimeoutError {
+  /**
+   * Builds an enqueue acknowledgement timeout error without request payload or connection details.
+   * @param {object} args - Safe timeout context.
+   * @param {number} args.acknowledgementTimeoutMs - Configured post-send acknowledgement deadline.
+   * @param {Array<BackgroundJobEnqueueAttempt>} args.attemptHistory - Safe observations for timed-out attempts.
+   * @param {TimeoutError} [args.cause] - Original Awaitery timeout.
+   * @param {string} [args.generationId] - Accepted release generation identity.
+   * @param {string} args.jobName - Resolved job class name.
+   * @param {string} [args.producerInvocationId] - Owned enqueue invocation identity.
+   * @param {boolean} args.producerProofPresent - Whether the request carried an internal producer proof.
+   */
+  constructor({acknowledgementTimeoutMs, attemptHistory, cause, generationId, jobName, producerInvocationId, producerProofPresent}) {
+    super(`Background job enqueue acknowledgement timed out after ${acknowledgementTimeoutMs}ms`, cause ? {cause} : undefined)
+
+    this.name = "BackgroundJobEnqueueAcknowledgementTimeoutError"
+    /** @type {"BACKGROUND_JOB_ENQUEUE_ACKNOWLEDGEMENT_TIMEOUT"} */
+    this.code = "BACKGROUND_JOB_ENQUEUE_ACKNOWLEDGEMENT_TIMEOUT"
+    this.acknowledgementTimeoutMs = acknowledgementTimeoutMs
+    this.attemptHistory = Object.freeze(attemptHistory.map((attempt) => Object.freeze({
+      acknowledgementWaitElapsedMs: attempt.acknowledgementWaitElapsedMs,
+      attemptElapsedMs: attempt.attemptElapsedMs,
+      attemptKind: attempt.attemptKind,
+      attemptNumber: attempt.attemptNumber,
+      explicitlyRejected: attempt.explicitlyRejected,
+      generationFenced: attempt.generationFenced,
+      requestSent: attempt.requestSent
+    })))
+    this.generationId = generationId
+    this.jobName = jobName
+    this.producerInvocationId = producerInvocationId
+    this.producerProofPresent = producerProofPresent
+  }
+}

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

@@ -8,6 +8,36 @@ export const DEFAULT_BACKGROUND_JOB_QUEUE = "default"
 export const QUEUE_CONCURRENCY_KEY_PREFIX = "queue:"
 /** @type {import("./types.js").BackgroundJobExecutionMode[]} */
 export const BACKGROUND_JOB_EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
+/** @type {import("./types.js").BackgroundJobActiveStatus[]} */
+export const BACKGROUND_JOB_ACTIVE_STATUSES = ["queued", "handed_off"]
+/** @type {import("./types.js").BackgroundJobTerminalStatus[]} */
+export const BACKGROUND_JOB_TERMINAL_STATUSES = ["cancelled", "completed", "failed", "orphaned"]
+/** @type {import("./types.js").BackgroundJobStatus[]} */
+export const BACKGROUND_JOB_STATUSES = [...BACKGROUND_JOB_ACTIVE_STATUSES, ...BACKGROUND_JOB_TERMINAL_STATUSES]
+
+/**
+ * Normalizes persisted or transported job status vocabulary.
+ * @param {string} value - Candidate status.
+ * @returns {import("./types.js").BackgroundJobStatus} - Known status.
+ */
+export function normalizeBackgroundJobStatus(value) {
+  const status = BACKGROUND_JOB_STATUSES.find((candidate) => candidate === value)
+
+  if (status) return status
+
+  throw new Error(`Unknown background job status: ${value}`)
+}
+
+/**
+ * Validates a stable logical schedule key at every persistence boundary.
+ * @param {string} scheduleKey - Stable schedule key.
+ * @returns {string} - Validated key.
+ */
+export function normalizeBackgroundJobScheduleKey(scheduleKey) {
+  if (typeof scheduleKey === "string" && scheduleKey.length > 0 && scheduleKey.length <= 255) return scheduleKey
+
+  throw VelociousError.safe("background job scheduleKey must be a non-empty string of at most 255 characters")
+}
 
 /**
  * Normalizes a job queue.

package/build/background-jobs/job.js

@@ -8,7 +8,9 @@ import PlatformVelociousJob from "./platform-job.js"
 import {
   cancelScheduledBackgroundJobForConfiguration,
   enqueueBackgroundJobForConfiguration,
-  replaceScheduledBackgroundJobForConfiguration
+  getScheduledBackgroundJobForConfiguration,
+  replaceScheduledBackgroundJobForConfiguration,
+  wakeScheduledBackgroundJobForConfiguration
 } from "./runtime.js"
 
 /**
@@ -84,4 +86,27 @@ export default class VelociousJob extends PlatformVelociousJob {
 
     return await cancelScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
   }
+
+  /**
+   * Reads current ownership and optional terminal history for a stable key.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @param {{includeLatestTerminal?: boolean}} [options] - Lookup options.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized stable schedule jobs.
+   */
+  static async getScheduledJob(scheduleKey, options = {}) {
+    const configuration = await configurationResolver()
+
+    return await getScheduledBackgroundJobForConfiguration({configuration, scheduleKey, ...options})
+  }
+
+  /**
+   * Expedites a future queued owner without creating another job.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Wake result.
+   */
+  static async wakeScheduled(scheduleKey) {
+    const configuration = await configurationResolver()
+
+    return await wakeScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
+  }
 }

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

@@ -67,18 +67,46 @@ export default class LocalBackgroundJobsAdapter extends BackgroundJobsAdapter {
   }
 
   /**
-   * Rejects stable-key cancellation, which is outside the local adapter contract.
-   * @param {string} _scheduleKey - Unsupported stable key.
-   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Never resolves.
+   * Cancels or detaches the current owner of a stable schedule key.
+   * @param {string} scheduleKey - Stable schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
    */
-  async cancelScheduled(_scheduleKey) { throw new Error("cancelScheduled is not supported by the local background-jobs adapter") }
+  async cancelScheduled(scheduleKey) {
+    await this.ensureReady()
+    return await this.store.cancelScheduled(scheduleKey)
+  }
+
+  /**
+   * Replaces the current 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.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  async replaceScheduled(args) {
+    await this.ensureReady()
+    this.registry.resolve(args.jobName)
+    return await this.store.replaceScheduled(args)
+  }
 
   /**
-   * Rejects stable-key replacement, which is outside the local adapter contract.
-   * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Unsupported request.
-   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Never resolves.
+   * Reads stable ownership and optional terminal history.
+   * @param {string} scheduleKey - Stable schedule key.
+   * @param {{includeLatestTerminal?: boolean}} [options] - Lookup options.
+   * @returns {Promise<import("./types.js").BackgroundJobScheduledLookupResult>} - Normalized local jobs.
    */
-  async replaceScheduled(_args) { throw new Error("replaceScheduled is not supported by the local background-jobs adapter") }
+  async getScheduledJob(scheduleKey, options) {
+    await this.ensureReady()
+    return await this.store.getScheduledJob(scheduleKey, options)
+  }
+
+  /**
+   * Makes a future queued stable owner due without replacing it.
+   * @param {string} scheduleKey - Stable schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobWakeResult>} - Exact wake result.
+   */
+  async wakeScheduled(scheduleKey) {
+    await this.ensureReady()
+    return await this.store.wakeScheduled(scheduleKey)
+  }
 
   /**
    * Finds the next eligible local job.