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

package/dist/queue/Queue.js

@@ -1,3 +1,5 @@
+import { RunnableJob } from './RunnableJob.js';
+import { QueueTerminalError } from './QueueTerminalError.js';
 import { randomUUID } from 'node:crypto';
 import { DatabaseQueueDriver } from './drivers/DatabaseQueueDriver.js';
 import { RedisQueueDriver } from './drivers/RedisQueueDriver.js';
@@ -16,7 +18,9 @@ import { isQueueRetryLaterError } from './QueueRetryLaterError.js';
 export class Queue {
     db;
     options;
+    #jobClasses = new Map();
     handlers = new Map();
+    #ownedJobs = new Map();
     driver;
     monitor;
     events;
@@ -35,11 +39,52 @@ export class Queue {
         }
     }
     /**
-     * Returns the queue lifecycle monitor attached to this queue, when enabled.
+     * Returns the configured transport name for atomic database dispatch.
      */
+    get driverName() { return this.driver.name; }
+    /** Reports worker presence through the application-owned sink without changing delivery semantics. */
+    async reportWorker(snapshot) {
+        await this.options.onWorkerHeartbeat?.(snapshot);
+    }
+    /** Returns the optional queue lifecycle monitor. */
     get queueMonitor() {
         return this.monitor;
     }
+    /** Registers app-owned stable job names atomically and returns cleanup for this process only. */
+    registerJobs(owner, jobs, run = operation => operation()) {
+        if (!/^[a-z][a-z0-9_]{0,39}$/.test(owner))
+            throw new Error('Invalid queue job owner.');
+        const names = new Set();
+        for (const Job of jobs) {
+            const name = queueableJobName(Job);
+            if (!isQueueableJobClass(Job) || !Job.jobName?.startsWith(`${owner}.`) || names.has(name) || this.handlers.has(name))
+                throw new Error(`Invalid or duplicate owned job "${name}"; use an explicit ${owner}. jobName.`);
+            names.add(name);
+        }
+        for (const Job of jobs) {
+            this.registerJob(Job);
+            this.#ownedJobs.set(queueableJobName(Job), { Job, run });
+        }
+        let closed = false;
+        return () => {
+            if (closed)
+                return;
+            closed = true;
+            for (const name of names) {
+                this.handlers.delete(name);
+                this.#jobClasses.delete(name);
+                this.#ownedJobs.delete(name);
+            }
+        };
+    }
+    /** Checks active, delayed, reserved and chained payloads after producers have been quiesced. */
+    async hasPendingJobs(jobPrefix) {
+        if (!jobPrefix.trim())
+            throw new Error('A non-empty job prefix is required.');
+        if (!this.driver.hasPendingJobs)
+            throw new Error(`Queue driver "${this.driver.name}" cannot inspect outstanding app work.`);
+        return this.driver.hasPendingJobs(jobPrefix);
+    }
     /**
      * Returns recent terminal failures from the configured queue driver.
      *
@@ -87,6 +132,8 @@ export class Queue {
      * Registers an async handler for a named job payload.
      */
     registerHandler(name, handler) {
+        if (this.#ownedJobs.has(name))
+            throw new Error(`Job "${name}" belongs to an owned registration.`);
         this.handlers.set(name, job => {
             return {
                 handle: () => handler(job),
@@ -102,11 +149,30 @@ export class Queue {
         if (!isQueueableJobClass(Job)) {
             throw new Error('Queue.registerJob requires a QueueableJob class.');
         }
-        this.handlers.set(queueableJobName(Job), job => {
-            const instance = queueableJobFromJSON(Job, job.payload.data);
+        const owned = this.#ownedJobs.get(queueableJobName(Job));
+        if (owned) {
+            if (owned.Job !== Job)
+                throw new Error(`Job "${queueableJobName(Job)}" belongs to another registration.`);
+            return;
+        }
+        this.#jobClasses.set(queueableJobName(Job), Job);
+        this.handlers.set(queueableJobName(Job), async (job) => {
+            const instance = await queueableJobFromJSON(Job, job.payload.data);
             const context = this.createQueueableJobContext(job);
+            let retryDelay;
+            context.willRetry = error => {
+                retryDelay ??= queueRetryDelaySeconds(job.payload.backoff ?? this.resolveRetryBackoff(), job.attempts);
+                return isQueueRetryLaterError(error) || !(error instanceof QueueTerminalError) && job.attempts < job.payload.maxTries && !queueRetryDeadlineReached(job.payload.retryUntil, retryDelay, unixTimestamp());
+            };
+            context.assertOwnership = async () => {
+                const error = await this.confirmLease(job, this.retryAfterSeconds(), 'checkpoint');
+                if (error)
+                    throw error;
+            };
             return {
-                handle: () => instance.handle(context),
+                retainsFailure: instance instanceof RunnableJob,
+                get retryDelaySeconds() { return retryDelay; },
+                handle: () => instance instanceof RunnableJob ? instance.execute(context) : instance.handle(context),
                 onRetry: (error, delaySeconds) => instance.onRetry({
                     ...context,
                     error,
@@ -120,6 +186,21 @@ export class Queue {
         });
     }
     async dispatch(job, dataOrOptions = {}, maybeOptions = {}) {
+        const dispatchedName = typeof job === 'string' ? job : queueableJobName(job.constructor);
+        const Registered = this.#jobClasses.get(dispatchedName);
+        // Applications can register a retained implementation of a framework job.
+        if (Registered?.prototype instanceof RunnableJob && !(job instanceof RunnableJob)) {
+            const input = typeof job === 'string' ? dataOrOptions : job.serialize().data;
+            return this.dispatch(new Registered(input), typeof job === 'string' ? maybeOptions : dataOrOptions);
+        }
+        if (job instanceof RunnableJob && !job.publishingDelivery) {
+            const parent = RunnableJob.current();
+            if (parent) {
+                await parent.assertActive();
+                job.parentRunId ??= parent.id;
+            }
+            return job.enqueue(this, dataOrOptions);
+        }
         const serialized = isQueueableJob(job) ? job.serialize() : null;
         const name = resolveDispatchedJobName(job, serialized?.job);
         const options = serialized ? dataOrOptions : maybeOptions;
@@ -179,6 +260,26 @@ export class Queue {
         });
         if (!job)
             return null;
+        const owned = this.#ownedJobs.get(job.payload.job);
+        if (!owned)
+            return this.#workClaimedJob(job, retryAfterSeconds, options);
+        let entered = false;
+        try {
+            return await owned.run(async () => { entered = true; return this.#workClaimedJob(job, retryAfterSeconds, options); });
+        }
+        catch (error) {
+            if (entered)
+                throw error;
+            // Admission was refused before app code ran. Retain the job without consuming an attempt.
+            if (!(await this.driver.defer(job, 30)))
+                return this.recordLostLease(job, performance.now(), this.lostLeaseError(job, 'defer'));
+            const deferred = { ...job, attempts: Math.max(0, job.attempts - 1) };
+            await this.publishJobEvent('deferred', deferred, { delaySeconds: 30, error });
+            return { job: deferred, status: 'deferred', delaySeconds: 30, error };
+        }
+    }
+    /** Processes an already claimed job and completes its durable transition and hooks before releasing ownership. */
+    async #workClaimedJob(job, retryAfterSeconds, options) {
         options.onClaimed?.(job);
         await this.publishJobEvent('claimed', job);
         let execution = null;
@@ -237,10 +338,12 @@ export class Queue {
                     error,
                 };
             }
-            const delaySeconds = queueRetryDelaySeconds(job.payload.backoff ?? this.resolveRetryBackoff(), job.attempts);
+            const delaySeconds = execution?.retryDelaySeconds ?? queueRetryDelaySeconds(job.payload.backoff ?? this.resolveRetryBackoff(), job.attempts);
             const retryDeadlineReached = queueRetryDeadlineReached(job.payload.retryUntil, delaySeconds, unixTimestamp());
-            if (job.attempts >= job.payload.maxTries || retryDeadlineReached) {
-                const failed = await this.driver.fail(job, error);
+            if (error instanceof QueueTerminalError || job.attempts >= job.payload.maxTries || retryDeadlineReached) {
+                const failed = execution?.retainsFailure
+                    ? await this.driver.delete(job)
+                    : await this.driver.fail(job, error);
                 if (!failed) {
                     return await this.recordLostLease(job, startedAt, this.lostLeaseError(job, 'fail'));
                 }
@@ -378,12 +481,22 @@ export class Queue {
         return new Error(`Queue attempt ${job.attempts} no longer owns ${job.payload.job} job ${String(job.id)}; refused to ${operation}.`);
     }
     /**
-     * Starts a polling worker for a queue unless workers are disabled by configuration.
+     * Discovers named queues without reading or changing job payloads.
+     * @throws When a custom driver does not implement wildcard discovery.
+     */
+    async queueNames() {
+        if (!this.driver.queueNames)
+            throw new Error(`Queue driver "${this.driver.name}" does not support wildcard queue discovery.`);
+        return this.driver.queueNames();
+    }
+    /**
+     * Starts a polling worker for a named queue or selection unless disabled.
+     * @example queue.startWorker({ queues: '*', excludeQueues: ['articles'] });
      */
     startWorker(queue = process.env.QUEUE_NAME || this.options.queue || 'default', options = {}) {
         if (this.workerDisabled() && !options.force)
             return null;
-        const worker = new QueueWorker(this, queue, options.intervalMs ?? this.workerIntervalMs(), options.maxJobsPerTick ?? this.maxJobsPerTick(), options.logger, options.verbose ?? false);
+        const worker = new QueueWorker(this, typeof queue === 'string' ? queue : { ...queue, queues: queue.queues ?? [this.options.queue || 'default'] }, options.intervalMs ?? this.workerIntervalMs(), options.maxJobsPerTick ?? this.maxJobsPerTick(), options.logger, options.verbose ?? false);
         worker.start();
         return worker;
     }

package/dist/queue/QueueTerminalError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stops a queue delivery immediately, preserving its failed-job record and hooks.
+ * Use for a durable failure that ordinary retries cannot repair. Applications
+ * still own partial output and progress; explicit replay remains a separate act.
+ */
+export declare class QueueTerminalError extends Error {
+    /** Creates an immediately terminal queue failure with a safe explanation. */
+    constructor(message: string);
+}

package/dist/queue/QueueTerminalError.js

@@ -0,0 +1,12 @@
+/**
+ * Stops a queue delivery immediately, preserving its failed-job record and hooks.
+ * Use for a durable failure that ordinary retries cannot repair. Applications
+ * still own partial output and progress; explicit replay remains a separate act.
+ */
+export class QueueTerminalError extends Error {
+    /** Creates an immediately terminal queue failure with a safe explanation. */
+    constructor(message) {
+        super(message);
+        this.name = 'QueueTerminalError';
+    }
+}

package/dist/queue/QueueWorker.d.ts

@@ -2,7 +2,7 @@ import type { Queue } from './Queue.js';
 import type * as queue from './contracts/index.js';
 export type { QueueLogger, QueueWorkerLifecycle, QueueWorkerOptions } from './contracts/index.js';
 /**
- * Polls one queue and asks Queue to process available jobs.
+ * Polls eligible named queues in round-robin order, executing one job at a time.
  *
  * The worker intentionally owns only timer and lifecycle behavior. It delegates claims,
  * handler execution, retries, and failure recording back to Queue.
@@ -10,25 +10,32 @@ export type { QueueLogger, QueueWorkerLifecycle, QueueWorkerOptions } from './co
 export declare class QueueWorker implements queue.QueueWorkerLifecycle {
     #private;
     private readonly queueManager;
-    private readonly queue;
     private readonly logger?;
     private readonly verbose;
+    private readonly queue;
     private timer;
     private readonly intervalMs;
     private readonly maxJobsPerTick;
-    constructor(queueManager: Queue, queue?: string, intervalMs?: number, maxJobsPerTick?: number, logger?: queue.QueueLogger | undefined, verbose?: boolean);
+    /** Creates a worker without starting its polling loop; workOnce can be used for bounded execution. */
+    constructor(queueManager: Queue, selection?: string | queue.QueueSelection, intervalMs?: number, maxJobsPerTick?: number, logger?: queue.QueueLogger | undefined, verbose?: boolean);
     /**
      * Starts the worker with an immediate tick followed by interval-based polling.
      */
     start(): void;
     /**
-     * Stops future polling ticks. Any already-running tick is allowed to finish.
+     * Stops future claims. An already-running job is allowed to finish.
      */
     stop(): void;
     /**
-     * Stops future polling and waits for the active queue tick to finish.
+     * Stops future claims and waits for the current job, including timer-free execution.
      */
     stopAndDrain(): Promise<void>;
+    /**
+     * Processes at most one eligible job, rotating after each claim and skipping empty queues.
+     * Wildcard discovery is refreshed on every call, including after an idle poll.
+     * Concurrent calls are rejected so one worker cannot occupy multiple execution slots.
+     */
+    workOnce(options?: queue.QueueWorkOptions): Promise<queue.QueueProcessResult | null>;
     /**
      * Starts one tick when the previous tick is no longer running.
      */

package/dist/queue/QueueWorker.js

@@ -1,30 +1,47 @@
+import { QueueWorkerReporter } from './QueueWorkerReporter.js';
 import { unknownErrorMessage } from '@db3.ai/pure';
 const DEFAULT_WORKER_INTERVAL_MS = 1000;
 const MIN_WORKER_INTERVAL_MS = 100;
 const DEFAULT_MAX_JOBS_PER_TICK = 5;
 const MIN_MAX_JOBS_PER_TICK = 1;
 /**
- * Polls one queue and asks Queue to process available jobs.
+ * Polls eligible named queues in round-robin order, executing one job at a time.
  *
  * The worker intentionally owns only timer and lifecycle behavior. It delegates claims,
  * handler execution, retries, and failure recording back to Queue.
  */
 export class QueueWorker {
     queueManager;
-    queue;
     logger;
     verbose;
+    #presence;
     #activeTick = null;
+    #activeJob = null;
+    #lastQueue = null;
+    #stopping = false;
+    #queues;
+    #excludeQueues;
+    queue;
     timer = null;
     intervalMs;
     maxJobsPerTick;
-    constructor(queueManager, queue = 'default', intervalMs = Number(process.env.QUEUE_WORKER_INTERVAL_MS || DEFAULT_WORKER_INTERVAL_MS), maxJobsPerTick = Number(process.env.QUEUE_WORKER_MAX_JOBS_PER_TICK || DEFAULT_MAX_JOBS_PER_TICK), logger, verbose = false) {
+    /** Creates a worker without starting its polling loop; workOnce can be used for bounded execution. */
+    constructor(queueManager, selection = 'default', intervalMs = Number(process.env.QUEUE_WORKER_INTERVAL_MS || DEFAULT_WORKER_INTERVAL_MS), maxJobsPerTick = Number(process.env.QUEUE_WORKER_MAX_JOBS_PER_TICK || DEFAULT_MAX_JOBS_PER_TICK), logger, verbose = false) {
         this.queueManager = queueManager;
-        this.queue = queue;
         this.logger = logger;
         this.verbose = verbose;
+        const requested = typeof selection === 'string' ? { queues: [selection] } : selection;
+        this.#queues = requested.queues === '*' ? '*' : normalizeQueueNames(requested.queues ?? ['default']);
+        if (this.#queues !== '*' && this.#queues.length === 0)
+            throw new Error('A worker must select at least one queue.');
+        this.#excludeQueues = new Set(normalizeQueueNames(requested.excludeQueues ?? []));
+        if (this.#queues !== '*' && this.#queues.every(name => this.#excludeQueues.has(name)))
+            throw new Error('Worker queue exclusions leave no eligible queues.');
+        this.queue = (this.#queues === '*' ? '*' : this.#queues.join(', '))
+            + (this.#excludeQueues.size ? ` excluding ${[...this.#excludeQueues].join(', ')}` : '');
         this.intervalMs = normalizeWorkerIntervalMs(intervalMs);
         this.maxJobsPerTick = normalizeMaxJobsPerTick(maxJobsPerTick);
+        this.#presence = new QueueWorkerReporter({ queues: this.#queues, excludeQueues: [...this.#excludeQueues] }, snapshot => this.queueManager.reportWorker(snapshot), this.logger);
     }
     /**
      * Starts the worker with an immediate tick followed by interval-based polling.
@@ -32,18 +49,25 @@ export class QueueWorker {
     start() {
         if (this.timer)
             return;
+        this.#stopping = false;
         this.logger?.info(this.verbose
             ? `[queue] Worker started for "${this.queue}" (interval ${this.intervalMs}ms, max ${this.maxJobsPerTick} jobs/tick).`
             : `[queue] Worker started for "${this.queue}".`);
-        this.startTick();
+        this.#presence.start();
         this.timer = setInterval(() => {
             this.startTick();
         }, this.intervalMs);
+        this.startTick();
     }
     /**
-     * Stops future polling ticks. Any already-running tick is allowed to finish.
+     * Stops future claims. An already-running job is allowed to finish.
      */
     stop() {
+        this.#stopping = true;
+        if (this.#activeJob)
+            this.#presence.update('stopping');
+        else
+            void this.#presence.stop();
         if (!this.timer)
             return;
         clearInterval(this.timer);
@@ -51,13 +75,67 @@ export class QueueWorker {
         this.logger?.info(`[queue] Worker stopped for "${this.queue}".`);
     }
     /**
-     * Stops future polling and waits for the active queue tick to finish.
+     * Stops future claims and waits for the current job, including timer-free execution.
      */
     async stopAndDrain() {
         this.stop();
         if (this.#activeTick) {
             await this.#activeTick;
         }
+        await this.#activeJob;
+        await this.#presence.stop();
+    }
+    /**
+     * Processes at most one eligible job, rotating after each claim and skipping empty queues.
+     * Wildcard discovery is refreshed on every call, including after an idle poll.
+     * Concurrent calls are rejected so one worker cannot occupy multiple execution slots.
+     */
+    async workOnce(options = {}) {
+        if (this.#activeJob)
+            throw new Error('This queue worker is already processing a job.');
+        if (this.#stopping)
+            return null;
+        this.#presence.start();
+        const pending = this.#workOnce(options);
+        this.#activeJob = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            this.#activeJob = null;
+            if (this.#stopping || !this.timer)
+                await this.#presence.stop();
+            else
+                this.#presence.update('idle');
+        }
+    }
+    /** Resolves eligible names and delegates each atomic claim to the queue service. */
+    async #workOnce(options) {
+        const names = (this.#queues === '*' ? [...new Set(await this.queueManager.queueNames())].sort() : [...this.#queues])
+            .filter(name => !this.#excludeQueues.has(name));
+        let start = 0;
+        if (this.#lastQueue !== null) {
+            const previous = names.indexOf(this.#lastQueue);
+            start = previous >= 0 ? previous + 1 : names.findIndex(name => name > this.#lastQueue);
+            if (start < 0 || start >= names.length)
+                start = 0;
+        }
+        for (let offset = 0; offset < names.length && !this.#stopping; offset++) {
+            const name = names[(start + offset) % names.length];
+            const result = await this.queueManager.workNextJob(name, {
+                ...options,
+                onClaimed: job => {
+                    this.#lastQueue = name;
+                    this.#presence.update('busy', job.queue, String(job.id));
+                    options.onClaimed?.(job);
+                },
+            });
+            if (result) {
+                this.#lastQueue = name;
+                return result;
+            }
+        }
+        return null;
     }
     /**
      * Starts one tick when the previous tick is no longer running.
@@ -79,8 +157,8 @@ export class QueueWorker {
     async tick() {
         let processedThisTick = 0;
         try {
-            for (let processed = 0; processed < this.maxJobsPerTick; processed += 1) {
-                const result = await this.queueManager.workNextJob(this.queue, {
+            for (let processed = 0; processed < this.maxJobsPerTick && !this.#stopping; processed += 1) {
+                const result = await this.workOnce({
                     onClaimed: job => this.logClaimed(job),
                 });
                 if (!result) {
@@ -173,6 +251,13 @@ export class QueueWorker {
     }
 }
 export { QueueWorker as DatabaseQueueWorker };
+/** Validates and copies exact queue names so caller mutations cannot alter worker admission. */
+function normalizeQueueNames(names) {
+    if (!Array.isArray(names) || names.some(name => typeof name !== 'string' || !name.trim() || name !== name.trim() || name === '*')) {
+        throw new Error('Queue names must be non-empty exact names; use queues: "*" to select all queues.');
+    }
+    return [...new Set(names)];
+}
 /**
  * Formats a singular or plural word for a count.
  *

package/dist/queue/QueueWorkerReporter.d.ts

@@ -0,0 +1,17 @@
+import type { QueueWorkerSnapshot, QueueSelection, QueueLogger } from './contracts/index.js';
+/** Serializes small presence writes; a slow or unavailable sink cannot build an unbounded backlog or stop jobs. */
+export declare class QueueWorkerReporter {
+    #private;
+    private readonly publish;
+    private readonly logger?;
+    /** Creates an identity unique to this worker, including multiple workers in the same process. */
+    constructor(selection: QueueSelection, publish: (snapshot: QueueWorkerSnapshot) => Promise<void>, logger?: QueueLogger | undefined);
+    /** Starts liveness updates, including while a long job is awaiting network work. */
+    start(): void;
+    /** Updates the latest state without queuing one database write per job or poll. */
+    update(status: QueueWorkerSnapshot['status'], currentQueue?: string | null, currentJobId?: string | null): void;
+    /** Stops timers immediately and flushes a final state when the worker drains. */
+    stop(): Promise<void>;
+    /** Coalesces concurrent updates and isolates sink errors from claims and handlers. */
+    flush(): Promise<void>;
+}

package/dist/queue/QueueWorkerReporter.js

@@ -0,0 +1,71 @@
+import { hostname } from 'node:os';
+import { ulid } from '@db3.ai/pure/ulid';
+/** Serializes small presence writes; a slow or unavailable sink cannot build an unbounded backlog or stop jobs. */
+export class QueueWorkerReporter {
+    publish;
+    logger;
+    #snapshot;
+    #timer = null;
+    #pending = null;
+    #dirty = false;
+    /** Creates an identity unique to this worker, including multiple workers in the same process. */
+    constructor(selection, publish, logger) {
+        this.publish = publish;
+        this.logger = logger;
+        const now = new Date().toISOString();
+        this.#snapshot = { id: ulid(), name: process.env.QUEUE_WORKER_NAME || 'queue-worker', hostname: hostname(), pid: process.pid, selection, status: 'idle', currentQueue: null, currentJobId: null, startedAt: now, heartbeatAt: now };
+    }
+    /** Starts liveness updates, including while a long job is awaiting network work. */
+    start() {
+        if (this.#timer)
+            return;
+        this.#timer = setInterval(() => { void this.flush(); }, 10_000);
+        this.#timer.unref();
+        this.update('idle');
+        void this.flush();
+    }
+    /** Updates the latest state without queuing one database write per job or poll. */
+    update(status, currentQueue = null, currentJobId = null) {
+        if (status === 'stopping') {
+            currentQueue = this.#snapshot.currentQueue;
+            currentJobId = this.#snapshot.currentJobId;
+        }
+        if (this.#snapshot.status === status && this.#snapshot.currentQueue === currentQueue && this.#snapshot.currentJobId === currentJobId)
+            return;
+        this.#snapshot = { ...this.#snapshot, status, currentQueue, currentJobId };
+        void this.flush();
+    }
+    /** Stops timers immediately and flushes a final state when the worker drains. */
+    async stop() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = null;
+        this.update('stopped');
+        await this.flush();
+    }
+    /** Coalesces concurrent updates and isolates sink errors from claims and handlers. */
+    async flush() {
+        this.#dirty = true;
+        if (this.#pending)
+            return this.#pending;
+        this.#pending = this.#drain();
+        try {
+            await this.#pending;
+        }
+        finally {
+            this.#pending = null;
+        }
+    }
+    /** Writes the most recent immutable snapshot, retaining changes made while a write was pending. */
+    async #drain() {
+        while (this.#dirty) {
+            this.#dirty = false;
+            try {
+                await this.publish(structuredClone({ ...this.#snapshot, heartbeatAt: new Date().toISOString() }));
+            }
+            catch {
+                this.logger?.warn?.('[queue] Unable to publish worker presence.');
+            }
+        }
+    }
+}

package/dist/queue/QueueableJob.d.ts

@@ -81,7 +81,7 @@ export declare abstract class QueueableJob<TData extends Record<string, unknown>
  * @param value - Unknown value to inspect.
  * @returns True when the value is a queueable job instance.
  */
-export declare function isQueueableJob(value: unknown): value is QueueableJob;
+export declare function isQueueableJob(value: unknown): value is queue.QueueableJobContract;
 /**
  * Returns true when a class looks like a QueueableJob subclass.
  *
@@ -106,4 +106,4 @@ export declare function queueableJobName(Job: queue.QueueableJobClass | {
  * @param data - JSON payload data stored in the queue envelope.
  * @returns Rehydrated queueable job instance.
  */
-export declare function queueableJobFromJSON(Job: queue.QueueableJobClass, data: Record<string, unknown>): QueueableJob;
+export declare function queueableJobFromJSON(Job: queue.QueueableJobClass, data: Record<string, unknown>): queue.QueueableJobContract | Promise<queue.QueueableJobContract>;

package/dist/queue/RunnableJob.d.ts

@@ -0,0 +1,78 @@
+import { ActiveRecord } from '../db/ActiveRecord.js';
+import type { Queue } from './Queue.js';
+import type { DispatchOptions, QueueJobId, QueueableJobContext, QueueableJobContract, QueueableJobFailureContext, QueueableJobRetryContext, SerializedQueueableJob } from './contracts/index.js';
+/** Persisted lifecycle values; waiting includes scheduled retries, blocked requires an explicit new run. */
+export declare const JOB_RUN_STATUSES: readonly ["waiting", "running", "blocked", "completed", "failed", "cancelled"];
+declare const RunnableJob_base: import("../db/index.js").DefinedActiveRecord<typeof ActiveRecord, {
+    id: import("../db/index.js").UlidField;
+    jobType: import("../db/index.js").StringField;
+    tenantId: import("../db/index.js").StringField;
+    subjectId: import("../db/index.js").StringField;
+    actorId: import("../db/index.js").StringField;
+    parentRunId: import("../db/index.js").StringField;
+    trigger: import("../db/index.js").StringField;
+    status: import("../db/index.js").ChoiceStringField;
+    input: import("../db/index.js").JsonField<Record<string, unknown> | null>;
+    state: import("../db/index.js").JsonField<Record<string, unknown> | null>;
+    result: import("../db/index.js").JsonField<Record<string, unknown> | null>;
+    error: import("../db/index.js").TextField;
+    stage: import("../db/index.js").StringField;
+    completed: import("../db/index.js").IntegerField;
+    total: import("../db/index.js").IntegerField;
+    failures: import("../db/index.js").IntegerField;
+    attemptCount: import("../db/index.js").IntegerField;
+    deliveryKey: import("../db/index.js").StringField;
+    leaseToken: import("../db/index.js").StringField;
+    cancelRequestedAt: import("../db/index.js").TimestampField;
+    queuedAt: import("../db/index.js").TimestampField;
+    startedAt: import("../db/index.js").TimestampField;
+    heartbeatAt: import("../db/index.js").TimestampField;
+    completedAt: import("../db/index.js").TimestampField;
+    createdAt: import("../db/index.js").TimestampField;
+    updatedAt: import("../db/index.js").TimestampField;
+}>;
+/**
+ * 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 declare class RunnableJob extends RunnableJob_base implements QueueableJobContract {
+    #private;
+    /** Stable name may be overridden to preserve queued identities across class renames. */
+    static jobName?: string;
+    /** Returns the active run for child dispatch correlation within this asynchronous execution only. */
+    static current(): RunnableJob | undefined;
+    /** Internal dispatch guard; a saved delivery cannot be enqueued twice through the public API. */
+    get publishingDelivery(): boolean;
+    /** Cooperative abort signal. Application requests should combine it with their own deadline. */
+    get signal(): AbortSignal;
+    /** Loads the authoritative run through its concrete registered class, rejecting mismatched deliveries. */
+    static fromJSON<T extends typeof RunnableJob>(this: T, data: Record<string, unknown>): Promise<InstanceType<T>>;
+    /** Saves a new run before dispatch. During execution, saves only application-owned fields under the attempt fence. */
+    save(): Promise<this>;
+    /** Serializes concurrent progress callbacks so state merges cannot lose another completed item's update. */
+    checkpoint(update: (run: this) => void): Promise<void>;
+    /** Checks delivery ownership and operator cancellation before launching or publishing another unit of work. */
+    assertActive(): Promise<void>;
+    /** Appends bounded structured diagnostics; callers must omit credentials and private provider payloads. */
+    log(message: string, data?: Record<string, unknown>, level?: 'info' | 'warning' | 'error'): Promise<void>;
+    /** Stops launching further work until an operator creates a resumed run using the saved checkpoint. */
+    block(reason: string): never;
+    /** Resolves application-owned input/scope before first persistence. Override in a tenant-aware application base class. */
+    prepare(): Promise<void>;
+    /** Saves a run and its dispatch generation before delivery. Failed dispatches remain visible in history. */
+    enqueue(queue: Queue, options?: DispatchOptions): Promise<QueueJobId>;
+    /** Produces a small immutable queue reference; never copies mutable model JSON into delivery storage. */
+    serialize(): SerializedQueueableJob;
+    /** Concrete application jobs implement their own bounded work, checkpoints and result publication. */
+    handle(_context: QueueableJobContext): Promise<void>;
+    /** Lifecycle is saved before delivery transitions; ordinary queue retry hooks are intentionally empty. */
+    onRetry(_context: QueueableJobRetryContext): Promise<void>;
+    /** Lifecycle is saved before delivery transitions, including terminal failure. */
+    onFinalFailure(context: QueueableJobFailureContext): Promise<void>;
+    /** Runs one fenced attempt. Expired delivery recovery preserves checkpoints and records the interrupted attempt. */
+    execute(context: QueueableJobContext): Promise<void>;
+}
+export {};