@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/queue/RunnableJob.js

@@ -0,0 +1,284 @@
+var _a;
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { ActiveRecord } from '../db/ActiveRecord.js';
+import { JobRunAttempt } from './JobRunAttempt.js';
+import { JobRunEvent } from './JobRunEvent.js';
+import { JobRunStoppedError } from './JobRunStoppedError.js';
+import { QueueTerminalError } from './QueueTerminalError.js';
+import { isQueueRetryLaterError } from './QueueRetryLaterError.js';
+/** Persisted lifecycle values; waiting includes scheduled retries, blocked requires an explicit new run. */
+export const JOB_RUN_STATUSES = ['waiting', 'running', 'blocked', 'completed', 'failed', 'cancelled'];
+/**
+ * A retained run with application-owned input, state and behaviour. Register only
+ * this base model in migrations; concrete job classes share its table. Jobs must
+ * use checkpoint/save for durable work and make external effects idempotent.
+ * Tenant and subject identities are immutable; applications authorize launches
+ * and reads. Queue serialization contains only the saved run ID and generation.
+ */
+export class RunnableJob extends ActiveRecord.define({
+    table: 'job_runs',
+    fields: field => ({
+        id: field.ulid(),
+        jobType: field.string({ column: 'job_type', required: true, length: 200, index: true }),
+        tenantId: field.string({ column: 'tenant_id', required: true, length: 100, indexes: [{ name: 'job_runs_tenant_history', columns: ['tenant_id', 'id'] }] }),
+        subjectId: field.string({ column: 'subject_id', length: 100, indexes: [{ name: 'job_runs_subject_history', columns: ['subject_id', 'id'] }] }),
+        actorId: field.string({ column: 'actor_id', length: 100 }),
+        parentRunId: field.string({ column: 'parent_run_id', length: 26, index: true }),
+        trigger: field.string({ required: true, default: 'manual', length: 40 }),
+        status: field.choice({ choices: [...JOB_RUN_STATUSES], required: true, default: 'waiting', index: true }),
+        input: field.json({ required: true, default: {}, comment: 'Immutable application inputs captured when the run is created.' }),
+        state: field.json({ required: true, default: {}, comment: 'Mutable application checkpoint for progress, diagnosis and explicit recovery; may contain private data.' }),
+        result: field.json({ comment: 'Application outcome or result summary, separate from mutable progress state.' }),
+        error: field.text(),
+        stage: field.string({ length: 200, comment: 'Job-owned current phase; lifecycle outcome is stored in status.' }),
+        completed: field.integer({ required: true, default: 0, comment: 'Job-owned processed unit count, e.g. pages scanned or 1 for one operation; not a completion flag.' }),
+        total: field.integer({ comment: 'Planned units in the same measure as completed; null when unknown.' }),
+        failures: field.integer({ required: true, default: 0, comment: 'Job-owned failed unit count; units may also be counted as completed. Job failure is recorded in status.' }),
+        attemptCount: field.integer({ column: 'attempt_count', required: true, default: 0 }),
+        deliveryKey: field.string({ column: 'delivery_key', length: 36 }),
+        leaseToken: field.string({ column: 'lease_token', length: 36 }),
+        cancelRequestedAt: field.timestamp({ column: 'cancel_requested_at' }),
+        queuedAt: field.timestamp({ column: 'queued_at' }),
+        startedAt: field.timestamp({ column: 'started_at' }),
+        heartbeatAt: field.timestamp({ column: 'heartbeat_at' }),
+        completedAt: field.timestamp({ column: 'completed_at' }),
+        createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+        updatedAt: field.timestamp({ column: 'updated_at', auto: 'update' }),
+    }),
+}) {
+    /** Stable name may be overridden to preserve queued identities across class renames. */
+    static jobName;
+    static #active = new AsyncLocalStorage();
+    /** Returns the active run for child dispatch correlation within this asynchronous execution only. */
+    static current() { return _a.#active.getStore(); }
+    #context = null;
+    #token = null;
+    #updates = Promise.resolve();
+    #stop = new AbortController();
+    #publishing = false;
+    /** Internal dispatch guard; a saved delivery cannot be enqueued twice through the public API. */
+    get publishingDelivery() { return this.#publishing; }
+    /** Cooperative abort signal. Application requests should combine it with their own deadline. */
+    get signal() { return this.#stop.signal; }
+    /** Loads the authoritative run through its concrete registered class, rejecting mismatched deliveries. */
+    static async fromJSON(data) {
+        if (typeof data.runId !== 'string' || typeof data.deliveryKey !== 'string')
+            throw new Error('Invalid runnable job reference.');
+        const run = await this.findOrFail(data.runId);
+        if (run.jobType !== (this.jobName ?? this.name) || run.deliveryKey !== data.deliveryKey)
+            throw new Error('Runnable job identity does not match its delivery.');
+        return run;
+    }
+    /** Saves a new run before dispatch. During execution, saves only application-owned fields under the attempt fence. */
+    async save() {
+        if (!this.isPersisted()) {
+            if (this.constructor === _a)
+                throw new Error('Create a concrete RunnableJob subclass.');
+            this.jobType = this.constructor.jobName ?? this.constructor.name;
+            return super.save();
+        }
+        if (!this.#token)
+            throw new Error('Existing run records may only be saved by their owning execution.');
+        const values = structuredClone({ state: this.state, result: this.result, stage: this.stage, completed: this.completed, total: this.total, failures: this.failures });
+        await this.#serializeUpdate(() => this.#write(values));
+        return this;
+    }
+    /** Serializes concurrent progress callbacks so state merges cannot lose another completed item's update. */
+    async checkpoint(update) {
+        await this.#serializeUpdate(async () => {
+            await this.assertActive();
+            update(this);
+            await this.#write({ state: this.state, result: this.result, stage: this.stage, completed: this.completed, total: this.total, failures: this.failures });
+        });
+    }
+    /** Checks delivery ownership and operator cancellation before launching or publishing another unit of work. */
+    async assertActive() {
+        this.signal.throwIfAborted();
+        await this.#context?.assertOwnership?.();
+        const row = await _a.where({ id: this.id, leaseToken: this.#token, status: 'running' }).first();
+        if (!this.#token || !row)
+            throw new Error('Runnable job execution ownership was lost.');
+        let cancellation = Boolean(row.cancelRequestedAt);
+        let parentId = row.parentRunId;
+        const visited = new Set();
+        while (!cancellation && parentId) {
+            if (visited.has(parentId) || visited.size >= 32)
+                throw new Error('Invalid run ancestry.');
+            visited.add(parentId);
+            const parent = await _a.find(parentId);
+            cancellation = Boolean(parent?.cancelRequestedAt);
+            parentId = parent?.parentRunId ?? null;
+        }
+        if (cancellation) {
+            const reason = new JobRunStoppedError('cancelled', 'Cancelled by the operator.');
+            this.#stop.abort(reason);
+            throw reason;
+        }
+    }
+    /** Appends bounded structured diagnostics; callers must omit credentials and private provider payloads. */
+    async log(message, data = {}, level = 'info') {
+        await this.assertActive();
+        if (JSON.stringify(data).length > 16000)
+            throw new Error('Job event data exceeds 16,000 characters.');
+        await JobRunEvent.create({ runId: this.id, tenantId: this.tenantId, attempt: this.attemptCount, message: message.slice(0, 1024), data, level }).save();
+    }
+    /** Stops launching further work until an operator creates a resumed run using the saved checkpoint. */
+    block(reason) { throw new JobRunStoppedError('blocked', reason); }
+    /** Resolves application-owned input/scope before first persistence. Override in a tenant-aware application base class. */
+    async prepare() { }
+    /** Saves a run and its dispatch generation before delivery. Failed dispatches remain visible in history. */
+    async enqueue(queue, options = {}) {
+        if (this.deliveryKey)
+            throw new Error('This run has already been dispatched.');
+        if (!this.isPersisted()) {
+            await this.prepare();
+            await this.save();
+        }
+        const key = randomUUID();
+        let reserved = false;
+        /** Reserves the delivery generation and publishes its small queue reference. */
+        const publish = async () => {
+            const changed = await _a.where({ id: this.id, status: 'waiting' }).whereNull('deliveryKey').patch({ deliveryKey: key, queuedAt: new Date() });
+            if (changed !== 1)
+                throw new Error('This run has already been dispatched.');
+            reserved = true;
+            this.deliveryKey = key;
+            this.#publishing = true;
+            try {
+                return await queue.dispatch(this, options);
+            }
+            finally {
+                this.#publishing = false;
+            }
+        };
+        try {
+            return queue.driverName === 'database'
+                ? await _a.getDb().transaction(transaction => ActiveRecord.withDb(transaction, publish))
+                : await publish();
+        }
+        catch (error) {
+            if (!reserved)
+                throw error;
+            const failedDispatch = _a.where({ id: this.id, status: 'waiting' });
+            if (queue.driverName === 'database')
+                failedDispatch.whereNull('deliveryKey');
+            else
+                failedDispatch.where('deliveryKey', key);
+            await failedDispatch.patch({ status: 'failed', error: `Dispatch failed: ${error instanceof Error ? error.message : String(error)}`, completedAt: new Date() });
+            throw error;
+        }
+    }
+    /** Produces a small immutable queue reference; never copies mutable model JSON into delivery storage. */
+    serialize() {
+        if (!this.isPersisted() || !this.deliveryKey)
+            throw new Error('Call run.enqueue(queue) before queueing a runnable record.');
+        return { job: this.jobType, displayName: this.jobType, data: { runId: this.id, deliveryKey: this.deliveryKey } };
+    }
+    /** Concrete application jobs implement their own bounded work, checkpoints and result publication. */
+    async handle(_context) { throw new Error('RunnableJob.handle must be implemented.'); }
+    /** Lifecycle is saved before delivery transitions; ordinary queue retry hooks are intentionally empty. */
+    async onRetry(_context) { }
+    /** Lifecycle is saved before delivery transitions, including terminal failure. */
+    async onFinalFailure(context) {
+        // A deadline can pass between handler failure and the driver's final disposition.
+        const error = context.error instanceof Error ? context.error.message : String(context.error);
+        await _a.getDb().transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            const changed = await _a.where({ id: this.id, status: 'waiting', attemptCount: this.attemptCount }).patch({ status: 'failed', error, completedAt: new Date() });
+            if (changed) {
+                await JobRunAttempt.where({ runId: this.id, attempt: this.attemptCount, status: 'retrying' }).patch({ status: 'failed', error });
+                await JobRunEvent.create({ runId: this.id, tenantId: this.tenantId, attempt: this.attemptCount, level: 'error', message: error.slice(0, 1024), data: { status: 'failed', queue: context.job.queue, deliveryId: context.job.id, jobUuid: context.job.payload.uuid, maxTries: context.job.payload.maxTries } }).save();
+                this.status = 'failed';
+            }
+        }));
+    }
+    /** Runs one fenced attempt. Expired delivery recovery preserves checkpoints and records the interrupted attempt. */
+    async execute(context) {
+        await context.assertOwnership?.();
+        this.#context = context;
+        this.#updates = Promise.resolve();
+        const token = randomUUID();
+        const claimed = await _a.getDb().transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            const raw = await _a.where('id', this.id).toKnex().forUpdate().first();
+            if (!raw)
+                throw new Error('Run no longer exists.');
+            const current = _a.fromDb(raw);
+            if (current.deliveryKey !== this.deliveryKey)
+                throw new Error('Run delivery was replaced.');
+            if (!['waiting', 'running'].includes(current.status ?? ''))
+                return false;
+            if (current.status === 'running')
+                await JobRunAttempt.where({ runId: this.id, status: 'running' }).patch({ status: 'interrupted', completedAt: new Date(), error: 'Worker reservation expired before completion.' });
+            const now = new Date();
+            const values = { status: 'running', leaseToken: token, attemptCount: (current.attemptCount ?? 0) + 1, startedAt: current.startedAt ?? now, heartbeatAt: now, completedAt: null, error: null };
+            await _a.where('id', this.id).patch(values);
+            this.assign({ ...current.toJSON(), ...values });
+            await JobRunAttempt.create({ runId: this.id, tenantId: this.tenantId, attempt: this.attemptCount, deliveryId: String(context.job.id), status: 'running', startedAt: now }).save();
+            return true;
+        }));
+        if (!claimed)
+            return;
+        this.#token = token;
+        this.#stop = new AbortController();
+        let heartbeat = Promise.resolve();
+        const timer = setInterval(() => {
+            heartbeat = heartbeat.then(async () => {
+                await this.assertActive();
+                await _a.where({ id: this.id, leaseToken: token }).patch({ heartbeatAt: new Date() });
+            }).catch(error => { this.#stop.abort(error); });
+        }, 10000);
+        try {
+            await this.log('Attempt started');
+            await _a.#active.run(this, () => this.handle(context));
+            await this.#updates;
+            await this.assertActive();
+            await this.#finish('completed', null);
+        }
+        catch (error) {
+            await this.#updates.catch(() => undefined);
+            await context.assertOwnership?.();
+            const stopped = error instanceof JobRunStoppedError;
+            const retry = context.willRetry ? context.willRetry(error) : isQueueRetryLaterError(error) || !(error instanceof QueueTerminalError) && context.job.attempts < context.job.payload.maxTries;
+            const status = stopped ? error.status : retry ? 'waiting' : 'failed';
+            await this.#finish(status, error instanceof Error ? error.message : String(error));
+            if (!stopped)
+                throw error;
+        }
+        finally {
+            clearInterval(timer);
+            await heartbeat;
+            this.#context = null;
+            this.#token = null;
+        }
+    }
+    /** Writes application-owned state with a database fence; unrelated runtime fields cannot be overwritten. */
+    async #write(values) {
+        await this.assertActive();
+        if (JSON.stringify(values).length > 1000000)
+            throw new Error('Run checkpoint exceeds one megabyte. Store large evidence separately.');
+        const count = await _a.where({ id: this.id, leaseToken: this.#token, status: 'running' }).whereNull('cancelRequestedAt').patch({ ...values, heartbeatAt: new Date(), updatedAt: new Date() });
+        if (count !== 1) {
+            await this.assertActive();
+            throw new Error('Runnable job checkpoint ownership was lost.');
+        }
+    }
+    /** Records terminal/retry state, attempt outcome and timeline in the same transaction. */
+    async #finish(status, error) {
+        await _a.getDb().transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            const now = new Date();
+            const changed = await _a.where({ id: this.id, leaseToken: this.#token, status: 'running' }).patch({ status, error, completedAt: status === 'waiting' ? null : now, heartbeatAt: now, leaseToken: null, updatedAt: now });
+            if (changed !== 1)
+                throw new Error('Runnable job completion ownership was lost.');
+            await JobRunAttempt.where({ runId: this.id, attempt: this.attemptCount, status: 'running' }).patch({ status: status === 'waiting' ? 'retrying' : status, error, completedAt: now });
+            await JobRunEvent.create({ runId: this.id, tenantId: this.tenantId, attempt: this.attemptCount, level: status === 'failed' ? 'error' : error ? 'warning' : 'info', message: error?.slice(0, 1024) ?? 'Run completed', data: { status, queue: this.#context?.job.queue, deliveryId: this.#context?.job.id, jobUuid: this.#context?.job.payload.uuid, maxTries: this.#context?.job.payload.maxTries } }).save();
+            this.status = status;
+        }));
+    }
+    /** Queues state writes on this instance while allowing callers to observe their own failures. */
+    #serializeUpdate(action) {
+        const next = this.#updates.then(action);
+        this.#updates = next;
+        return next;
+    }
+}
+_a = RunnableJob;

package/dist/queue/console.d.ts

@@ -29,8 +29,11 @@ export interface QueueConsoleCommand {
     close?: boolean;
     run(context: QueueConsoleCommandContext): void | Promise<void>;
 }
+/** Application bootstrap, named worker selections and extra commands shared by queue CLI invocations. */
 export interface QueueConsoleOptions {
     app: () => QueueConsoleApp;
+    /** Checked-in worker selections selected with --pool=<name>; credentials remain in the application environment. */
+    workers?: Readonly<Record<string, queue.QueueSelection>>;
     bootstrap?: () => void | Promise<void>;
     commands?: QueueConsoleCommand[];
     helpText?: string;
@@ -57,4 +60,9 @@ export declare function logQueueProcessResult(result: queue.QueueProcessResult,
  * @param options - Console logging options.
  */
 export declare function logQueueClaimed(job: queue.QueueJob, options?: QueueConsoleLogOptions): void;
+/**
+ * Resolves one worker selection from explicit CLI flags or a checked-in named pool.
+ * Pool admission cannot be silently broadened by combining it with queue flags.
+ */
+export declare function queueConsoleSelection(parsed: ParsedQueueConsoleArgs, workers?: QueueConsoleOptions['workers']): queue.QueueSelection;
 export {};

package/dist/queue/console.js

@@ -1,4 +1,5 @@
 import { parseJsonRecord, unknownErrorMessage } from '@db3.ai/pure';
+import { QueueWorker } from './QueueWorker.js';
 export async function runQueueConsole(options, argv = process.argv.slice(2)) {
     const parsed = parseQueueConsoleArgs(argv);
     switch (parsed.command) {
@@ -163,11 +164,10 @@ export function logQueueClaimed(job, options = {}) {
 async function bootstrap(options) {
     await options.bootstrap?.();
 }
+/** Runs a configured worker selection, with identical admission for one-shot and polling execution. */
 async function workQueue(options, parsed) {
-    const queue = queueConsoleOptionString(parsed, 'queue')
-        || parsed.args[0]
-        || process.env.QUEUE_NAME
-        || 'default';
+    const selection = queueConsoleSelection(parsed, options.workers);
+    const queue = selection.queues === '*' ? '*' : selection.queues?.join(', ') ?? 'default';
     const once = queueConsoleOptionBoolean(parsed, 'once');
     const verbose = queueConsoleVerbose(parsed);
     if (!once) {
@@ -175,26 +175,29 @@ async function workQueue(options, parsed) {
     }
     const app = options.app();
     if (once) {
-        if (verbose) {
-            console.log(`[queue] Checking "${queue}" once.`);
-        }
-        const result = await app.queue.workNextJob(queue, {
-            onClaimed: job => logQueueClaimed(job, {
+        try {
+            if (verbose) {
+                console.log(`[queue] Checking "${queue}" once.`);
+            }
+            const result = await new QueueWorker(app.queue, selection).workOnce({
+                onClaimed: job => logQueueClaimed(job, {
+                    verbose,
+                }),
+            });
+            if (!result) {
+                console.log(`[queue] No jobs available on "${queue}".`);
+                return;
+            }
+            logQueueProcessResult(result, {
                 verbose,
-            }),
-        });
-        if (!result) {
-            console.log(`[queue] No jobs available on "${queue}".`);
+            });
+        }
+        finally {
             await app.close();
-            return;
         }
-        logQueueProcessResult(result, {
-            verbose,
-        });
-        await app.close();
         return;
     }
-    const worker = app.queue.startWorker(queue, {
+    const worker = app.queue.startWorker(selection, {
         force: true,
         logger: app.log?.child({
             component: 'queue-worker',
@@ -223,6 +226,34 @@ async function workQueue(options, parsed) {
         void shutdown('SIGTERM');
     });
 }
+/**
+ * Resolves one worker selection from explicit CLI flags or a checked-in named pool.
+ * Pool admission cannot be silently broadened by combining it with queue flags.
+ */
+export function queueConsoleSelection(parsed, workers = {}) {
+    for (const flag of ['pool', 'queues', 'queue', 'exclude-queues']) {
+        if (Object.hasOwn(parsed.options, flag) && queueConsoleOptionString(parsed, flag) === undefined)
+            throw new Error(`--${flag} requires a non-empty value.`);
+    }
+    const pool = queueConsoleOptionString(parsed, 'pool');
+    const queues = queueConsoleOptionString(parsed, 'queues');
+    const single = queueConsoleOptionString(parsed, 'queue') || parsed.args[0];
+    const excluded = queueConsoleOptionString(parsed, 'exclude-queues');
+    if (pool) {
+        if (queues !== undefined || single !== undefined || excluded !== undefined)
+            throw new Error('--pool cannot be combined with queue selection flags.');
+        if (!Object.hasOwn(workers, pool))
+            throw new Error(`Unknown worker pool "${pool}".`);
+        return workers[pool];
+    }
+    if (queues !== undefined && single !== undefined)
+        throw new Error('Use --queues or --queue, not both.');
+    const names = queues ?? single ?? process.env.QUEUE_NAME ?? 'default';
+    return {
+        queues: names === '*' ? '*' : names.split(',').map(name => name.trim()),
+        excludeQueues: excluded === undefined ? [] : excluded.split(',').map(name => name.trim()),
+    };
+}
 async function dispatchQueueJob(app, parsed) {
     const name = parsed.args[0];
     if (!name) {
@@ -273,6 +304,9 @@ function defaultHelpText() {
 
 Options:
   --queue=<name>       Queue name, defaults to "default".
+  --queues=<names|*>  Worker queue names, comma-separated; quote '*'.
+  --exclude-queues=<names>  Exact queue names this worker cannot claim.
+  --pool=<name>        Checked-in worker selection; cannot combine with queue flags.
   --delay=<seconds>    Delay before the job is available.
   --tries=<count>      Maximum attempts before jobs_failed.
   --once               Process one available job, then exit.

package/dist/queue/contracts/QueueDriver.d.ts

@@ -46,8 +46,16 @@ export interface QueueFailedJob {
  * recording. Queue owns handler execution and retry decisions.
  */
 export interface QueueDriver {
+    /** Inspects pending, delayed, reserved and chained work for maintenance; callers must quiesce producers first. */
+    hasPendingJobs?(jobPrefix: string): Promise<boolean>;
     /** Driver name stored on failed job records and shown in diagnostics. */
     readonly name: QueueDriverName | string;
+    /**
+     * Discovers names with pending, delayed or reserved work in this driver's namespace.
+     * Required for wildcard workers; explicit selections do not need discovery.
+     * Returned names may disappear before a claim, which must still be atomic.
+     */
+    queueNames?(): Promise<string[]>;
     /**
      * Persists a job so a worker can claim it later.
      *

package/dist/queue/contracts/QueueJobRunner.d.ts

@@ -0,0 +1,4 @@
+/** Executes a complete claimed-job attempt, including retries and hooks, inside its owner's lifecycle gate. */
+export interface QueueJobRunner {
+    <T>(operation: () => Promise<T>): Promise<T>;
+}

package/dist/queue/contracts/QueueJobRunner.js

@@ -0,0 +1 @@
+export {};

package/dist/queue/contracts/QueuePayload.d.ts

@@ -82,7 +82,7 @@ export interface DispatchOptions {
     /**
      * Named queue/channel the job should be pushed onto.
      *
-     * Workers process one named queue at a time, so this lets callers route
+     * Workers select eligible named queues, so this lets callers route
      * different classes of work to different worker pools. When omitted, the
      * queue service uses its configured default queue name.
      */

package/dist/queue/contracts/QueueSelection.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Named queues a worker may consume. Selection never changes a job's queue.
+ * Wildcards discover queues within the configured driver connection/namespace;
+ * exclusions always win. Names are exact, with no glob or job-class matching.
+ */
+export interface QueueSelection {
+    /** Exact queue names, or all currently discoverable names. Defaults to the configured default queue. */
+    queues?: readonly string[] | '*';
+    /** Exact names that this worker must never claim, including when using '*'. */
+    excludeQueues?: readonly string[];
+}

package/dist/queue/contracts/QueueSelection.js

@@ -0,0 +1 @@
+export {};

package/dist/queue/contracts/QueueService.d.ts

@@ -1,6 +1,6 @@
 import type { QueueMonitor, QueueMonitorOptions } from '../queueMonitor.js';
 import type { QueueEvents } from '../QueueEvents.js';
-import type { QueueableJob } from '../QueueableJob.js';
+import type { QueueableJobContract as QueueableJob } from './QueueableJobContract.js';
 import type { QueueLifecycleErrorHandler } from './QueueEvents.js';
 import type { DispatchOptions, QueueDriverName, QueueJob, QueueJobId, QueueProcessResult } from './QueuePayload.js';
 import type { QueueRetryBackoffStrategy } from './QueueRetry.js';
@@ -8,6 +8,9 @@ import type { QueueDriver, QueueFailedJob } from './QueueDriver.js';
 import type { QueueableJobClass } from './QueueableJob.js';
 import type { QueueWorkerLifecycle, QueueWorkerOptions } from './QueueWorkerLifecycle.js';
 import type { RedisQueueDriverOptions } from './RedisQueueDriver.js';
+import type { QueueJobRunner } from './QueueJobRunner.js';
+import type { QueueWorkerSnapshot } from './QueueWorkerSnapshot.js';
+import type { QueueSelection } from './QueueSelection.js';
 /**
  * Function-style handler registered for a durable queued job name.
  */
@@ -27,6 +30,8 @@ export type QueueJobResolver = (context: QueueJobResolverContext) => QueueableJo
  * Queue service configuration shared by dispatching, processing, and worker startup.
  */
 export interface QueueOptions {
+    /** Receives serialized worker presence every ten seconds and on state changes; errors are isolated from job execution. */
+    onWorkerHeartbeat?: (snapshot: QueueWorkerSnapshot) => void | Promise<void>;
     /**
      * Default queue name used when dispatching or processing jobs without an explicit queue.
      */
@@ -101,6 +106,10 @@ export interface QueueWorkOptions {
  * Public queue service API used by application code and queueable jobs.
  */
 export interface QueueService {
+    /** Registers an owned set of stable names and returns idempotent runtime cleanup. */
+    registerJobs(owner: string, jobs: readonly QueueableJobClass[], run?: QueueJobRunner): () => void;
+    /** Checks all active storage, including chained work; unsupported drivers reject rather than assume empty. */
+    hasPendingJobs(jobPrefix: string): Promise<boolean>;
     /**
      * Always-on asynchronous queue lifecycle event dispatcher.
      */
@@ -189,11 +198,16 @@ export interface QueueService {
      */
     workNextJob(queue?: string, options?: QueueWorkOptions): Promise<QueueProcessResult | null>;
     /**
-     * Starts a polling worker for a named queue.
+     * Discovers names with pending work in the configured driver namespace.
+     * @throws When the driver does not implement wildcard discovery.
+     */
+    queueNames(): Promise<string[]>;
+    /**
+     * Starts a polling worker for a named queue or round-robin selection.
      *
-     * @param queue - Named queue/channel the worker should poll.
+     * @param queue - Exact queue name or named-queue selection the worker should poll.
      * @param options - Worker lifecycle and polling options.
      * @returns Worker lifecycle controls, or null when worker startup is disabled.
      */
-    startWorker(queue?: string, options?: QueueWorkerOptions): QueueWorkerLifecycle | null;
+    startWorker(queue?: string | QueueSelection, options?: QueueWorkerOptions): QueueWorkerLifecycle | null;
 }

package/dist/queue/contracts/QueueWorkerLifecycle.d.ts

@@ -55,11 +55,11 @@ export interface QueueWorkerLifecycle {
      */
     start(): void;
     /**
-     * Stops future polling ticks without aborting an active tick.
+     * Stops claiming further work without aborting the current job.
      */
     stop(): void;
     /**
-     * Stops future polling and resolves after the active tick has completed.
+     * Stops claiming further work and resolves after the current job has completed.
      */
     stopAndDrain(): Promise<void>;
 }

package/dist/queue/contracts/QueueWorkerSnapshot.d.ts

@@ -0,0 +1,14 @@
+import type { QueueSelection } from './QueueSelection.js';
+/** Process-scoped worker presence, independent of the queue transport and job payloads. */
+export interface QueueWorkerSnapshot {
+    id: string;
+    name: string;
+    hostname: string;
+    pid: number;
+    selection: QueueSelection;
+    status: 'idle' | 'busy' | 'stopping' | 'stopped';
+    currentQueue: string | null;
+    currentJobId: string | null;
+    startedAt: string;
+    heartbeatAt: string;
+}

package/dist/queue/contracts/QueueWorkerSnapshot.js

@@ -0,0 +1 @@
+export {};

package/dist/queue/contracts/QueueableJob.d.ts

@@ -1,5 +1,5 @@
 import type { Queue } from '../Queue.js';
-import type { QueueableJob } from '../QueueableJob.js';
+import type { QueueableJobContract } from './QueueableJobContract.js';
 import type { QueueJob, SerializedQueuedJob } from './QueuePayload.js';
 /**
  * Serialized queueable job payload stored before a driver wraps it in an envelope.
@@ -13,6 +13,10 @@ export interface QueueableJobContext {
     job: QueueJob;
     /** Queue service that is processing this job. */
     queue: Queue;
+    /** Confirms this delivery still belongs to the current worker before publishing effects. */
+    assertOwnership?(): Promise<void>;
+    /** Uses the queue retry policy, including deadline and backoff, for a failed attempt. */
+    willRetry?(error: unknown): boolean;
 }
 /**
  * Context passed after a failed attempt has safely been released for retry.
@@ -33,7 +37,7 @@ export interface QueueableJobFailureContext extends QueueableJobContext {
 /**
  * Constructor contract for serializable queueable job classes.
  */
-export interface QueueableJobClass<TJob extends QueueableJob = QueueableJob> {
+export interface QueueableJobClass<TJob extends QueueableJobContract = QueueableJobContract> {
     /** Runtime class name used as the default durable job name. */
     readonly name: string;
     /** Optional durable job name override. */
@@ -46,5 +50,5 @@ export interface QueueableJobClass<TJob extends QueueableJob = QueueableJob> {
      * @param data - JSON-safe data stored in the queue payload.
      * @returns Queueable job instance ready to handle.
      */
-    fromJSON(data: Record<string, unknown>): TJob;
+    fromJSON(data: Record<string, unknown>): TJob | Promise<TJob>;
 }

package/dist/queue/contracts/QueueableJobContract.d.ts

@@ -0,0 +1,12 @@
+import type { QueueableJobContext, QueueableJobFailureContext, QueueableJobRetryContext, SerializedQueueableJob } from './QueueableJob.js';
+/** Execution and delivery contract shared by command jobs and persisted runnable records. */
+export interface QueueableJobContract {
+    /** Serializes delivery data; persisted runs send only their identity and generation. */
+    serialize(): SerializedQueueableJob;
+    /** Performs application work after the queue has claimed delivery. */
+    handle(context: QueueableJobContext): Promise<void>;
+    /** Observes a committed retry; important state must not depend solely on this hook. */
+    onRetry(context: QueueableJobRetryContext): Promise<void>;
+    /** Observes a committed terminal failure. */
+    onFinalFailure(context: QueueableJobFailureContext): Promise<void>;
+}

package/dist/queue/contracts/QueueableJobContract.js

@@ -0,0 +1 @@
+export {};

package/dist/queue/contracts/index.d.ts

@@ -1,4 +1,5 @@
 export * from './QueueDriver.js';
+export * from './QueueSelection.js';
 export * from './QueueEvents.js';
 export * from './QueuePayload.js';
 export * from './QueueRetry.js';
@@ -7,3 +8,6 @@ export * from './QueueService.js';
 export * from './QueueWorkerLifecycle.js';
 export * from './RedisQueueDriver.js';
 export * from './CreateJob.js';
+export type { QueueJobRunner } from './QueueJobRunner.js';
+export * from './QueueableJobContract.js';
+export type { QueueWorkerSnapshot } from './QueueWorkerSnapshot.js';

package/dist/queue/contracts/index.js

@@ -1,4 +1,5 @@
 export * from './QueueDriver.js';
+export * from './QueueSelection.js';
 export * from './QueueEvents.js';
 export * from './QueuePayload.js';
 export * from './QueueRetry.js';
@@ -7,3 +8,4 @@ export * from './QueueService.js';
 export * from './QueueWorkerLifecycle.js';
 export * from './RedisQueueDriver.js';
 export * from './CreateJob.js';
+export * from './QueueableJobContract.js';

package/dist/queue/drivers/DatabaseQueueDriver.d.ts

@@ -12,6 +12,10 @@ export declare class DatabaseQueueDriver implements queue.QueueDriver {
      * @param db - Database service used for queue persistence.
      */
     constructor(db: Database);
+    /** Discovers queue names from the queue index, including delayed and reserved work. */
+    queueNames(): Promise<string[]>;
+    /** Scans active work in bounded pages during quiesced maintenance, including delayed and chained payloads. */
+    hasPendingJobs(jobPrefix: string): Promise<boolean>;
     /**
      * Persists a job in the `jobs` table.
      *