velocious 1.0.666 → 1.0.668

package/README.md

@@ -32,12 +32,13 @@
 * 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))
+* Websocket channel primitives for 1:N pub/sub over the shared session socket (`channel-subscribe` protocol): `matches()`-routed streams, interest-gated event-log persistence with 10-minute retention, stream-scoped `lastEventId` replay with `channel-replay-gap` gap reporting, and `{liveOnly: true}` channels that never reach the replay log (see [docs/websocket-channels.md](docs/websocket-channels.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))
 * 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))
@@ -125,7 +126,7 @@ Maintainers cutting a package release must follow the [Velocious release runbook
 
 # Docker development environment
 
-The checked-in root `Dockerfile` and `compose.yml` define one canonical `dev` service used by humans, CI, and agent systems alike (see [docs/docker-development-environment.md](docs/docker-development-environment.md)). The image is Ubuntu 26.04 LTS (pinned by digest) with Node.js 24.x from signed NodeSource, the universal apt coding/debugging baseline, and the newest published provider CLIs; it is source-independent — no project source is copied and no project dependencies are installed at image build time.
+The checked-in root `Dockerfile` and `compose.yml` define one canonical `dev` service used by humans, CI, and agent systems alike (see [docs/docker-development-environment.md](docs/docker-development-environment.md)). The image is Ubuntu 26.04 LTS (pinned by digest) with Node.js 24.x from signed NodeSource, the universal apt coding/debugging baseline, the newest published retained provider CLIs, and owner-pinned native Qwen Code 0.23.3; it is source-independent — no project source is copied and no project dependencies are installed at image build time.
 
 Prerequisites: Docker with the Compose v2 plugin, and this repository checked out at `$DEV_HOME_PATH/velocious` (default `DEV_HOME_PATH`: `/home/dev`).
 
@@ -179,10 +180,13 @@ Baselines are generated against a fresh checkout (no generated dummy `configurat
 # Testing
 
 Application tests may import the testing DSL from the independent public package.
-`@velocious/testing` `0.0.12` is the declaration and execution engine. Compatible
-installed copies share one protocol-1/schema-3 default registry. Velocious adapts each
-package-owned attempt with its database, request, profiling, and cleanup behavior; the
-existing Velocious facade exports the same declaration DSL and remains supported.
+`@velocious/testing` `0.0.14` owns framework-neutral discovery, filtering,
+execution, reporting, deterministic weighted grouping, profiling, and timing
+manifests. Compatible installed copies share one protocol-1/schema-3 default registry.
+Velocious retains application/configuration startup, database and transaction
+lifecycle, browser execution, environment handling, framework profile spans, and
+report translation. Existing Velocious import paths remain supported as thin
+delegating compatibility facades.
 
 ```js
 import {describe, expect, it} from "@velocious/testing"
@@ -245,7 +249,9 @@ export default async function configureTesting() {
 }
 ```
 
-Retry flaky tests by setting a retry count on the test args.
+Retry flaky tests by setting a retry count on the test args, or set CLI defaults for
+retries and lifecycle timeout. Import repeatable global setup before the testing
+configuration and test declarations with `--setup`.
 
 ```js
 describe("Tasks", () => {
@@ -253,6 +259,10 @@ it("retries a flaky check", {retry: 2}, async () => {})
 })
 ```
 
+```bash
+npx velocious test --retry=2 --timeout=30000 --setup=spec/setup.js spec/
+```
+
 Velocious prints the slowest tests after every run so suite hotspots are easy to spot. Each line shows the duration, full description and `file:line`.
 
 ```bash
@@ -295,7 +305,7 @@ npx velocious test:timing-manifest:merge --output tmp/test-timings.json \
 See [test profiling](docs/test-profiling.md) for lifecycle accounting, custom
 activity spans, schema, and privacy guarantees.
 
-Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`. Both `@velocious/testing` and the backward-compatible `velocious/build/src/testing/test.js` facade are supported imports; the Velocious runner consumes public-package declarations and adds the framework-specific database, request, profiling, and cleanup behavior.
+Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`. Both `@velocious/testing` and the backward-compatible `velocious/build/src/testing/test.js` facade are supported imports; the Velocious runner consumes public-package declarations and adds the framework-specific startup, database, request, browser, profile-span, and cleanup behavior.
 
 ```js
 import {waitForEvent} from "velocious/build/src/testing/test.js"
@@ -880,7 +890,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:
 
@@ -2224,6 +2234,16 @@ socket.send(JSON.stringify({
 }))
 ```
 
+### V2 channel registration, replay, and live-only channels
+
+`configuration.registerWebsocketChannel(name, ChannelClass)` registers a channel class for the `channel-subscribe` protocol — distinct from the `websocketChannelResolver` above, which serves the legacy `{type: "subscribe"}` path. Subscribers are routed by the class's `matches(broadcastParams)`, and publishers emit with `configuration.broadcastToChannel(name, broadcastParams, body)`.
+
+- **Stream-scoped replay.** Delivered `channel-message` frames carry the server `eventId`; a client can pass its last-seen `lastEventId` on (re)subscribe and the server replays only the persisted events belonging to that subscription's stream (10-minute retention, written only while the channel is interested). A checkpoint that expired or belongs to a different stream reports `channel-replay-gap` and the subscription continues with live delivery.
+- **Live-only channels.** `registerWebsocketChannel(name, ChannelClass, {liveOnly: true})` declares a channel that must never reach the replay event log; marking one interested throws, and the persistence decision rejects it even if stale interest state exists.
+- **Replayable params.** Channel classes can override the static `replayableBroadcastParams(broadcastParams)` hook to control which broadcast params are persisted for replay (for example, stripping server-only values).
+
+See [docs/websocket-channels.md](docs/websocket-channels.md) for the full wire protocol, V1/V2 gap semantics, and lifecycle guarantees.
+
 ## Raw websocket handlers
 
 If you need to accept custom websocket message formats (for example, a vendor that does not use the Velocious request/subscribe protocol), provide a `websocketMessageHandlerResolver` in your configuration. It receives the upgrade request and can return a handler object with `onOpen`, `onMessage`, `onClose`, and `onError` hooks:
@@ -2723,7 +2743,16 @@ 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.
 
@@ -2817,7 +2846,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,12 +1,82 @@
 // @ts-check
 
-import timeout, {TimeoutError} 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 {
   /**
@@ -236,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/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.