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

package/src/notifications/contracts/Notification.ts

@@ -0,0 +1,65 @@
+import type { InAppMessage, InAppScope } from '../../in-app';
+import type { MailMessage } from '../../mail';
+
+/** Framework delivery channels currently supported by notification classes. */
+export type NotificationChannel = 'inApp' | 'mail';
+
+/** Minimum persisted identity accepted by the notification service. */
+export interface NotificationUser {
+	/** Stable application identity used for delivery ownership and deduplication. */
+	id: string | null;
+}
+
+/**
+ * Application-owned notification content and routing policy.
+ *
+ * Channel renderers return data only. They must not persist messages, contact
+ * providers or depend on an active HTTP request.
+ */
+export interface Notification<TUser extends NotificationUser = NotificationUser> {
+	/** Stable application-owned type used for inbox filtering and deduplication. */
+	readonly type: string;
+
+	/**
+	 * Selects delivery channels for one resolved user.
+	 *
+	 * @param user - Persisted recipient, available for future preference checks.
+	 * @returns Distinct supported channels to deliver.
+	 */
+	via(user: TUser): readonly NotificationChannel[];
+
+	/**
+	 * Resolves recipient scope for authorization and inbox queries.
+	 *
+	 * @param user - Persisted recipient receiving this occurrence.
+	 * @returns Account scope by default, or an application-owned scope.
+	 */
+	scope?(user: TUser): InAppScope;
+
+	/**
+	 * Returns a stable business identity used to deduplicate retries.
+	 *
+	 * @param user - Persisted recipient receiving this occurrence.
+	 * @returns Application-owned occurrence key, or undefined for no deduplication.
+	 */
+	key?(user: TUser): string | undefined;
+
+	/**
+	 * Renders durable in-app content when `via()` selects `inApp`.
+	 *
+	 * @param user - Persisted recipient receiving this occurrence.
+	 * @returns Validated content stored in the recipient's inbox.
+	 */
+	toInApp?(user: TUser): InAppMessage;
+
+	/**
+	 * Renders email content when `via()` selects `mail`.
+	 *
+	 * @param user - Persisted recipient receiving this occurrence.
+	 * @returns Provider-neutral mail content ready for the configured transport.
+	 */
+	toMail?(user: TUser): MailMessage;
+}
+
+/** User model or stable ID accepted by notification delivery. */
+export type NotificationRecipient<TUser extends NotificationUser> = TUser | string;

package/src/notifications/contracts/NotificationDelivery.ts

@@ -0,0 +1,11 @@
+import type { InAppAcceptance } from '../../in-app';
+import type { MailDelivery } from '../../mail';
+/** Accepted channel outcomes for one resolved user. */
+export interface NotificationDelivery {
+	/** Stable recipient identity. */
+	userId: string;
+	/** Durable in-app acceptance, or null when the notification omitted the channel. */
+	inApp: InAppAcceptance | null;
+	/** Mail transport acceptance, or null when the renderer omitted the channel. */
+	mail: MailDelivery | null;
+}

package/src/notifications/contracts/index.ts

@@ -0,0 +1,2 @@
+export * from './Notification';
+export * from './NotificationDelivery';

package/src/notifications/examples/ReportReadyNotification.ts

@@ -0,0 +1,31 @@
+import type { Notification } from '@db3.ai/app/notifications';
+import type { UserIdentity } from '@db3.ai/app/auth';
+
+/** Example code-owned notification with explicit in-app and email renderers. */
+export class ReportReadyNotification implements Notification<UserIdentity> {
+	readonly type = 'report.ready';
+
+	/** Creates a report-ready notification for one report occurrence. */
+	constructor(private readonly reportId: string) {}
+
+	/** Selects durable in-app and email delivery for this recipient. */
+	via(_user: UserIdentity) {
+		return ['inApp', 'mail'] as const;
+	}
+
+	/** Returns the report occurrence identity used to deduplicate retries. */
+	key(_user: UserIdentity) {
+		return this.reportId;
+	}
+
+	/** Returns the durable inbox content. */
+	toInApp(_user: UserIdentity) {
+		return { title: 'Your report is ready', body: 'Open the report to review it.', presentation: 'banner' as const };
+	}
+
+	/** Returns provider-neutral email content. */
+	toMail(user: UserIdentity) {
+		if (!user.email) throw new Error('Report notification requires a recipient email.');
+		return { to: user.email, subject: 'Your report is ready', text: 'Open the app to review it.' };
+	}
+}

package/src/notifications/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts';
+export { Notifications } from './Notifications';

package/src/queue/JobRunAttempt.ts

@@ -0,0 +1,17 @@
+import { ActiveRecord } from '../db/ActiveRecord';
+
+/** Retains each execution boundary, including attempts interrupted before a handler could fail itself. */
+export class JobRunAttempt extends ActiveRecord.define({
+	table: 'job_run_attempts',
+	fields: field => ({
+		id: field.ulid(),
+		runId: field.string({ column: 'run_id', required: true, length: 26, index: true }),
+		tenantId: field.string({ column: 'tenant_id', required: true, length: 100, index: true }),
+		attempt: field.integer({ required: true }),
+		deliveryId: field.string({ column: 'delivery_id', required: true, length: 100 }),
+		status: field.string({ required: true, length: 30 }),
+		error: field.text(),
+		startedAt: field.timestamp({ column: 'started_at', required: true }),
+		completedAt: field.timestamp({ column: 'completed_at' }),
+	}),
+}) {}

package/src/queue/JobRunEvent.ts

@@ -0,0 +1,16 @@
+import { ActiveRecord } from '../db/ActiveRecord';
+
+/** Append-only diagnostic evidence for a run; applications control access and retention. */
+export class JobRunEvent extends ActiveRecord.define({
+	table: 'job_run_events',
+	fields: field => ({
+		id: field.ulid(),
+		runId: field.string({ column: 'run_id', required: true, length: 26, index: true }),
+		tenantId: field.string({ column: 'tenant_id', required: true, length: 100, index: true }),
+		attempt: field.integer({ required: true, default: 0 }),
+		level: field.choice({ choices: ['info', 'warning', 'error'], required: true, default: 'info' }),
+		message: field.string({ required: true, length: 1024 }),
+		data: field.json<Record<string, unknown>>(),
+		createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+	}),
+}) {}

package/src/queue/JobRunStoppedError.ts

@@ -0,0 +1,8 @@
+/** Cooperative stop requested by an operator or a job-owned blocking policy. */
+export class JobRunStoppedError extends Error {
+	/** Captures a durable stop reason without treating expected stops as provider exceptions. */
+	constructor(readonly status: 'blocked' | 'cancelled', message: string) {
+		super(message);
+		this.name = 'JobRunStoppedError';
+	}
+}

package/src/queue/Queue.ts

@@ -1,3 +1,6 @@
+import { RunnableJob } from './RunnableJob';
+import type { QueueableJobContract as QueueableJob } from './contracts/QueueableJobContract';
+import { QueueTerminalError } from './QueueTerminalError';
 import { randomUUID } from 'node:crypto';
 
 import type { Database } from '../db';
@@ -7,7 +10,7 @@ import { enableDefaultQueueMonitor, type QueueMonitor } from './queueMonitor';
 import { QueueEvents } from './QueueEvents';
 import { queueRetryDeadlineReached, queueRetryDelaySeconds, queueRetryUntil, resolveQueueRetryBackoff, type QueueRetryBackoffDefaults } from './RetryPolicy';
 import { QueueWorker } from './QueueWorker';
-import { isQueueableJob, isQueueableJobClass, queueableJobFromJSON, queueableJobName, type QueueableJob } from './QueueableJob';
+import { isQueueableJob, isQueueableJobClass, queueableJobFromJSON, queueableJobName } from './QueueableJob';
 import { isQueueRetryLaterError } from './QueueRetryLaterError';
 import type * as queue from './contracts';
 
@@ -20,6 +23,10 @@ interface QueueJobExecution {
 	handle(): Promise<void>;
 	onRetry?(error: unknown, delaySeconds: number): Promise<void>;
 	onFinalFailure?(error: unknown): Promise<void>;
+	/** Runnable records retain their own terminal history. */
+	retainsFailure?: boolean;
+	/** Reuses the jitter sample used to persist a retained run outcome. */
+	retryDelaySeconds?: number;
 }
 
 /**
@@ -36,7 +43,9 @@ type QueueJobExecutionFactory = (
  * callers can either process one job at a time or start a worker loop over the same API.
  */
 export class Queue implements queue.QueueService {
+	#jobClasses = new Map<string, queue.QueueableJobClass>();
 	private readonly handlers = new Map<string, QueueJobExecutionFactory>();
+	readonly #ownedJobs = new Map<string, { Job: queue.QueueableJobClass; run: queue.QueueJobRunner }>();
 	private readonly driver: queue.QueueDriver;
 	private readonly monitor: QueueMonitor | null;
 	readonly events: QueueEvents;
@@ -59,12 +68,45 @@ export class Queue implements queue.QueueService {
 	}
 
 	/**
-	 * Returns the queue lifecycle monitor attached to this queue, when enabled.
+	 * Returns the configured transport name for atomic database dispatch.
 	 */
+	get driverName(): string { return this.driver.name; }
+
+	/** Reports worker presence through the application-owned sink without changing delivery semantics. */
+	async reportWorker(snapshot: queue.QueueWorkerSnapshot): Promise<void> {
+		await this.options.onWorkerHeartbeat?.(snapshot);
+	}
+
+	/** Returns the optional queue lifecycle monitor. */
 	get queueMonitor(): QueueMonitor | null {
 		return this.monitor;
 	}
 
+	/** Registers app-owned stable job names atomically and returns cleanup for this process only. */
+	registerJobs(owner: string, jobs: readonly queue.QueueableJobClass[], run: queue.QueueJobRunner = operation => operation()): () => void {
+		if (!/^[a-z][a-z0-9_]{0,39}$/.test(owner)) throw new Error('Invalid queue job owner.');
+		const names = new Set<string>();
+		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: string): Promise<boolean> {
+		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.
 	 *
@@ -130,6 +172,7 @@ export class Queue implements queue.QueueService {
 		name: string,
 		handler: queue.JobHandler<TData>,
 	): void {
+		if (this.#ownedJobs.has(name)) throw new Error(`Job "${name}" belongs to an owned registration.`);
 		this.handlers.set(name, job => {
 			return {
 				handle: () => handler(job as queue.QueueJob<TData>),
@@ -147,12 +190,29 @@ export class Queue implements queue.QueueService {
 			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: number | undefined;
+			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,
@@ -185,6 +245,18 @@ export class Queue implements queue.QueueService {
 		dataOrOptions: Record<string, unknown> | queue.DispatchOptions = {},
 		maybeOptions: queue.DispatchOptions = {},
 	): Promise<queue.QueueJobId> {
+		const dispatchedName = typeof job === 'string' ? job : queueableJobName(job.constructor as queue.QueueableJobClass);
+		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 as queue.DispatchOptions);
+		}
+		if (job instanceof RunnableJob && !job.publishingDelivery) {
+			const parent = RunnableJob.current();
+			if (parent) { await parent.assertActive(); job.parentRunId ??= parent.id; }
+			return job.enqueue(this, dataOrOptions as queue.DispatchOptions);
+		}
 		const serialized = isQueueableJob(job) ? job.serialize() : null;
 		const name = resolveDispatchedJobName(job, serialized?.job);
 		const options = serialized ? dataOrOptions as queue.DispatchOptions : maybeOptions;
@@ -265,6 +337,23 @@ export class Queue implements queue.QueueService {
 
 		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: queue.QueueJob, retryAfterSeconds: number, options: queue.QueueWorkOptions): Promise<queue.QueueProcessResult> {
 		options.onClaimed?.(job);
 		await this.publishJobEvent('claimed', job);
 
@@ -346,7 +435,7 @@ export class Queue implements queue.QueueService {
 				};
 			}
 
-			const delaySeconds = queueRetryDelaySeconds(
+			const delaySeconds = execution?.retryDelaySeconds ?? queueRetryDelaySeconds(
 				job.payload.backoff ?? this.resolveRetryBackoff(),
 				job.attempts,
 			);
@@ -356,8 +445,10 @@ export class Queue implements queue.QueueService {
 				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(
@@ -549,17 +640,27 @@ export class Queue implements queue.QueueService {
 	}
 
 	/**
-	 * 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(): Promise<string[]> {
+		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',
+		queue: string | queue.QueueSelection = process.env.QUEUE_NAME || this.options.queue || 'default',
 		options: queue.QueueWorkerOptions = {},
 	): QueueWorker | null {
 		if (this.workerDisabled() && !options.force) return null;
 
 		const worker = new QueueWorker(
 			this,
-			queue,
+			typeof queue === 'string' ? queue : { ...queue, queues: queue.queues ?? [this.options.queue || 'default'] },
 			options.intervalMs ?? this.workerIntervalMs(),
 			options.maxJobsPerTick ?? this.maxJobsPerTick(),
 			options.logger,

package/src/queue/QueueTerminalError.ts

@@ -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: string) {
+		super(message);
+		this.name = 'QueueTerminalError';
+	}
+}

package/src/queue/QueueWorker.ts

@@ -1,3 +1,4 @@
+import { QueueWorkerReporter } from './QueueWorkerReporter';
 import { unknownErrorMessage } from '@db3.ai/pure';
 
 import type { Queue } from './Queue';
@@ -11,27 +12,43 @@ 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 implements queue.QueueWorkerLifecycle {
+	readonly #presence: QueueWorkerReporter;
 	#activeTick: Promise<void> | null = null;
+	#activeJob: Promise<queue.QueueProcessResult | null> | null = null;
+	#lastQueue: string | null = null;
+	#stopping = false;
+	readonly #queues: readonly string[] | '*';
+	readonly #excludeQueues: ReadonlySet<string>;
+	private readonly queue: string;
 	private timer: NodeJS.Timeout | null = null;
 	private readonly intervalMs: number;
 	private readonly maxJobsPerTick: number;
 
+	/** Creates a worker without starting its polling loop; workOnce can be used for bounded execution. */
 	constructor(
 		private readonly queueManager: Queue,
-		private readonly queue = 'default',
+		selection: string | queue.QueueSelection = '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),
 		private readonly logger?: queue.QueueLogger,
 		private readonly verbose = false,
 	) {
+		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);
 	}
 
 	/**
@@ -39,20 +56,24 @@ export class QueueWorker implements queue.QueueWorkerLifecycle {
 	 */
 	start(): void {
 		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(): void {
+		this.#stopping = true;
+		if (this.#activeJob) this.#presence.update('stopping'); else void this.#presence.stop();
 		if (!this.timer) return;
 
 		clearInterval(this.timer);
@@ -61,7 +82,7 @@ export class QueueWorker implements queue.QueueWorkerLifecycle {
 	}
 
 	/**
-	 * 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(): Promise<void> {
 		this.stop();
@@ -69,6 +90,56 @@ export class QueueWorker implements queue.QueueWorkerLifecycle {
 		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: queue.QueueWorkOptions = {}): Promise<queue.QueueProcessResult | null> {
+		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: queue.QueueWorkOptions): Promise<queue.QueueProcessResult | null> {
+		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;
 	}
 
 	/**
@@ -94,8 +165,8 @@ export class QueueWorker implements queue.QueueWorkerLifecycle {
 		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),
 				});
 
@@ -226,6 +297,14 @@ export class QueueWorker implements queue.QueueWorkerLifecycle {
 
 export { QueueWorker as DatabaseQueueWorker };
 
+/** Validates and copies exact queue names so caller mutations cannot alter worker admission. */
+function normalizeQueueNames(names: readonly string[]): string[] {
+	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/src/queue/QueueWorkerReporter.ts

@@ -0,0 +1,59 @@
+import { hostname } from 'node:os';
+import { ulid } from '@db3.ai/pure/ulid';
+import type { QueueWorkerSnapshot, QueueSelection, QueueLogger } from './contracts';
+
+/** Serializes small presence writes; a slow or unavailable sink cannot build an unbounded backlog or stop jobs. */
+export class QueueWorkerReporter {
+	#snapshot: QueueWorkerSnapshot;
+	#timer: ReturnType<typeof setInterval> | null = null;
+	#pending: Promise<void> | null = null;
+	#dirty = false;
+
+	/** Creates an identity unique to this worker, including multiple workers in the same process. */
+	constructor(selection: QueueSelection, private readonly publish: (snapshot: QueueWorkerSnapshot) => Promise<void>, private readonly logger?: QueueLogger) {
+		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(): void {
+		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: QueueWorkerSnapshot['status'], currentQueue: string | null = null, currentJobId: string | null = null): void {
+		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(): Promise<void> {
+		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(): Promise<void> {
+		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(): Promise<void> {
+		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/src/queue/QueueableJob.ts

@@ -118,7 +118,7 @@ export abstract class QueueableJob<TData extends Record<string, unknown> = Recor
  * @param value - Unknown value to inspect.
  * @returns True when the value is a queueable job instance.
  */
-export function isQueueableJob(value: unknown): value is QueueableJob {
+export function isQueueableJob(value: unknown): value is queue.QueueableJobContract {
 	return Boolean(
 		value
 		&& typeof value === 'object'
@@ -162,6 +162,6 @@ export function queueableJobName(Job: queue.QueueableJobClass | { name: string;
  * @param data - JSON payload data stored in the queue envelope.
  * @returns Rehydrated queueable job instance.
  */
-export function queueableJobFromJSON(Job: queue.QueueableJobClass, data: Record<string, unknown>): QueueableJob {
+export function queueableJobFromJSON(Job: queue.QueueableJobClass, data: Record<string, unknown>): queue.QueueableJobContract | Promise<queue.QueueableJobContract> {
 	return Job.fromJSON(data);
 }