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

package/src/queue/contracts/QueueService.ts

@@ -1,6 +1,6 @@
 import type { QueueMonitor, QueueMonitorOptions } from '../queueMonitor';
 import type { QueueEvents } from '../QueueEvents';
-import type { QueueableJob } from '../QueueableJob';
+import type { QueueableJobContract as QueueableJob } from './QueueableJobContract';
 import type { QueueLifecycleErrorHandler } from './QueueEvents';
 import type { DispatchOptions, QueueDriverName, QueueJob, QueueJobId, QueueProcessResult } from './QueuePayload';
 import type { QueueRetryBackoffStrategy } from './QueueRetry';
@@ -8,6 +8,9 @@ import type { QueueDriver, QueueFailedJob } from './QueueDriver';
 import type { QueueableJobClass } from './QueueableJob';
 import type { QueueWorkerLifecycle, QueueWorkerOptions } from './QueueWorkerLifecycle';
 import type { RedisQueueDriverOptions } from './RedisQueueDriver';
+import type { QueueJobRunner } from './QueueJobRunner';
+import type { QueueWorkerSnapshot } from './QueueWorkerSnapshot';
+import type { QueueSelection } from './QueueSelection';
 
 /**
  * Function-style handler registered for a durable queued job name.
@@ -33,6 +36,8 @@ export type QueueJobResolver = (
  * 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.
 	 */
@@ -109,6 +114,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.
 	 */
@@ -209,11 +218,17 @@ 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/src/queue/contracts/QueueWorkerLifecycle.ts

@@ -60,12 +60,12 @@ 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/src/queue/contracts/QueueWorkerSnapshot.ts

@@ -0,0 +1,15 @@
+import type { QueueSelection } from './QueueSelection';
+
+/** 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/src/queue/contracts/QueueableJob.ts

@@ -1,5 +1,5 @@
 import type { Queue } from '../Queue';
-import type { QueueableJob } from '../QueueableJob';
+import type { QueueableJobContract } from './QueueableJobContract';
 import type { QueueJob, SerializedQueuedJob } from './QueuePayload';
 
 /**
@@ -15,6 +15,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;
 }
 
 /**
@@ -38,7 +42,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. */
@@ -52,5 +56,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/src/queue/contracts/QueueableJobContract.ts

@@ -0,0 +1,13 @@
+import type { QueueableJobContext, QueueableJobFailureContext, QueueableJobRetryContext, SerializedQueueableJob } from './QueueableJob';
+
+/** 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/src/queue/contracts/index.ts

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

package/src/queue/drivers/DatabaseQueueDriver.ts

@@ -2,6 +2,7 @@ import { ActiveRecord, RecordValidationError, withQueryMonitorCategory, type Dat
 import { FailedJob } from '../FailedJob';
 import { QueuedJob } from '../QueuedJob';
 import type * as queue from '../contracts';
+import { jobEnvelopeHasPrefix } from '../jobEnvelopeHasPrefix';
 
 /**
  * Queue driver that stores pending and failed jobs in the app database.
@@ -16,6 +17,26 @@ export class DatabaseQueueDriver implements queue.QueueDriver {
 	 */
 	constructor(private readonly db: Database) {}
 
+	/** Discovers queue names from the queue index, including delayed and reserved work. */
+	async queueNames(): Promise<string[]> {
+		return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+			const rows = await QueuedJob.query().toKnex().distinct('queue').orderBy('queue');
+			return rows.map(row => String(row.queue));
+		}));
+	}
+
+	/** Scans active work in bounded pages during quiesced maintenance, including delayed and chained payloads. */
+	async hasPendingJobs(jobPrefix: string): Promise<boolean> {
+		if (!(await this.db.knex.schema.hasTable(QueuedJob.table))) return false;
+		let after: number | string = 0;
+		while (true) {
+			const rows = await this.db.knex(QueuedJob.table).select('id', 'payload').where('id', '>', after).orderBy('id').limit(100);
+			for (const row of rows) if (jobEnvelopeHasPrefix(typeof row.payload === 'string' ? JSON.parse(row.payload) : row.payload, jobPrefix)) return true;
+			if (rows.length < 100) return false;
+			after = rows[rows.length - 1].id;
+		}
+	}
+
 	/**
 	 * Persists a job in the `jobs` table.
 	 *
@@ -25,7 +46,8 @@ export class DatabaseQueueDriver implements queue.QueueDriver {
 	async push<TData extends Record<string, unknown>>(
 		job: queue.QueueDriverPushInput<TData>,
 	): Promise<queue.QueueJobId> {
-		return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+		const connection = ActiveRecord.getScopedDb() ?? this.db.knex;
+		return withQueueQueryCategory(() => ActiveRecord.withDb(connection, async () => {
 			const record = QueuedJob.create({
 				queue: job.queue,
 				payload: job.payload,
@@ -45,7 +67,7 @@ export class DatabaseQueueDriver implements queue.QueueDriver {
 				isInsert: true,
 				onlyDirty: false,
 			});
-			const [jobId] = await this.db.knex(QueuedJob.table).insert(row);
+			const [jobId] = await connection(QueuedJob.table).insert(row);
 
 			return Number(jobId);
 		}));
@@ -109,7 +131,7 @@ export class DatabaseQueueDriver implements queue.QueueDriver {
 	 * @returns True when the current attempt still owns the job.
 	 */
 	async touch(job: queue.QueueJob, _retryAfterSeconds: number): Promise<boolean> {
-		return withQueueQueryCategory(() => ActiveRecord.withDb(this.db.knex, async () => {
+		return withQueueQueryCategory(() => ActiveRecord.withDb(ActiveRecord.getScopedDb() ?? this.db.knex, async () => {
 			const updated = await QueuedJob
 				.where('id', job.id)
 				.where('attempts', job.attempts)

package/src/queue/drivers/RedisQueueDriver.ts

@@ -2,6 +2,7 @@ import { createClient, type RedisArgument, type RedisClientOptions, type RedisCl
 import { unknownErrorMessage } from '@db3.ai/pure';
 
 import type * as queue from '../contracts';
+import { jobEnvelopeHasPrefix } from '../jobEnvelopeHasPrefix';
 
 type RedisCommandArgument = string | number;
 type ResolvedRedisQueueDriverOptions = Required<Pick<queue.RedisQueueDriverOptions, 'host' | 'port' | 'keyPrefix' | 'connectionTimeoutMs'>> & queue.RedisQueueDriverOptions;
@@ -208,6 +209,41 @@ export class RedisQueueDriver implements queue.QueueDriver {
 		return String(id);
 	}
 
+	/**
+	 * Discovers queue names from ready/delayed/reserved keys without reading payloads.
+	 * SCAN includes existing queues written before this capability was introduced.
+	 */
+	async queueNames(): Promise<string[]> {
+		const prefix = `${this.#key('queues')}:`;
+		const pattern = prefix.replace(/[\\*?\[\]]/g, '\\$&') + '*';
+		const names = new Set<string>();
+		let cursor = '0';
+		do {
+			const [next, keys] = await this.#command<[string, string[]]>(['SCAN', cursor, 'MATCH', pattern, 'COUNT', 100]);
+			cursor = String(next);
+			for (const key of keys) {
+				if (!key.startsWith(prefix)) continue;
+				const suffix = key.slice(prefix.length).match(/^(.*):(ready|delayed|reserved)$/);
+				if (suffix?.[1]) names.add(suffix[1]);
+			}
+		} while (cursor !== '0');
+		return [...names].sort();
+	}
+
+	/** Scans active Redis payloads during quiesced maintenance; includes delayed, reserved and chained jobs. */
+	async hasPendingJobs(jobPrefix: string): Promise<boolean> {
+		let cursor = '0';
+		do {
+			const result = await this.#command<[string, string[]]>(['HSCAN', this.#jobsKey(), cursor, 'COUNT', 100]);
+			cursor = String(result[0]);
+			for (let index = 1; index < result[1].length; index += 2) {
+				const record = JSON.parse(result[1][index]) as RedisQueuedJobRecord;
+				if (jobEnvelopeHasPrefix(record.payload, jobPrefix)) return true;
+			}
+		} while (cursor !== '0');
+		return false;
+	}
+
 	/**
 	 * Claims the next available job from a Redis queue.
 	 *

package/src/queue/examples/runQueueSelection.ts

@@ -0,0 +1,34 @@
+import { pathToFileURL } from 'node:url';
+import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
+import { FailedJob, QueuedJob, QueueWorker } from '@db3.ai/app/queue';
+import { App } from '@db3.ai/app/server';
+
+/**
+ * Demonstrates protected and shared workers using real durable named queues.
+ * Creates a disposable database and closes it even when processing fails.
+ * Handlers represent local work only; no external services are contacted.
+ */
+export async function runQueueSelection() {
+	const database = await createGeneratedTestDatabase('queue_selection');
+	const application = new App({ db: database.db, queue: { queueMonitor: false } });
+	try {
+		await application.db.install(QueuedJob, FailedJob);
+		const handled: string[] = [];
+		application.queue.registerHandler('example.work', async job => { handled.push(job.queue); });
+		for (const queue of ['articles', 'article-images', 'default']) {
+			await application.queue.dispatch('example.work', {}, { queue });
+		}
+		const general = new QueueWorker(application.queue, { queues: '*', excludeQueues: ['articles', 'article-images'] });
+		const shared = new QueueWorker(application.queue, { queues: '*' });
+		await general.workOnce();
+		const protectedIdle = await general.workOnce() === null;
+		while (await shared.workOnce()) { /* Drain remaining eligible work. */ }
+		return { handled, protectedIdle, remaining: await QueuedJob.query().count() };
+	} finally {
+		try { await application.close(); } finally { await database.destroy(); }
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	console.log(JSON.stringify(await runQueueSelection(), null, 2));
+}

package/src/queue/index.ts

@@ -11,3 +11,10 @@ export * from './drivers/DatabaseQueueDriver';
 export * from './drivers/RedisQueueDriver';
 export * from './contracts';
 export * from './createJob';
+
+export * from './QueueTerminalError';
+
+export * from './RunnableJob';
+export * from './JobRunAttempt';
+export * from './JobRunEvent';
+export * from './JobRunStoppedError';

package/src/queue/jobEnvelopeHasPrefix.ts

@@ -0,0 +1,6 @@
+import type { SerializedQueuedJob } from './contracts';
+
+/** Checks active work and nested chained continuations without inspecting application-owned payload data. */
+export function jobEnvelopeHasPrefix(envelope: Pick<SerializedQueuedJob, 'job' | 'chained'>, prefix: string): boolean {
+	return envelope.job.startsWith(prefix) || Boolean(envelope.chained?.some(job => jobEnvelopeHasPrefix(job, prefix)));
+}

package/src/scheduler/README.md

@@ -1,7 +1,7 @@
 # Scheduler
 
 The framework scheduler keeps recurring definitions in application code and
-stores one durable occurrence for every due named minute. It supports daily
+stores one durable occurrence for every due named minute. It supports minute and daily
 jobs and short inline calls:
 
 ```ts
@@ -28,10 +28,10 @@ A `QueueableJob` class uses its durable job name as the schedule name, so
 stable name because function identity is not durable. Names must be unique
 within one application schedule.
 
-The first implementation intentionally supports only `daily()` and
-`dailyAt('HH:mm')`. Times use UTC unless `.timezone(...)` selects an IANA
-timezone. The scheduler evaluates the current minute only; it does not run
-missed historical minutes after downtime.
+Use `everyMinute()` for bounded background collection, or `daily()` and
+`dailyAt('HH:mm')` for daily work. Minute schedules are independent of timezone;
+daily times use UTC unless `.timezone(...)` selects an IANA timezone. The worker covers every elapsed UTC minute in order. Applications
+can provide durable progress to preserve that coverage across downtime.
 
 ## Runtime
 
@@ -51,8 +51,12 @@ There are two execution boundaries:
 
 - `scheduler.runDue()` evaluates one minute and is suitable for cron or a
   one-off framework command.
-- `SchedulerWorker` evaluates immediately, waits to the next minute boundary,
-  and repeats without overlapping ticks in the same process.
+- `SchedulerWorker` starts with the current minute, then evaluates every minute
+  through the current clock time without overlapping ticks in one process.
+  All tasks due in a minute retain that original due time, even if dispatching
+  them crosses several later minutes. Those later minutes are evaluated next.
+  Late or early timers cannot discard minutes. Catch-up yields after sixty
+  evaluations to allow shutdown and other work; it does not truncate the backlog.
 
 Run one dedicated scheduler process in production. Multiple processes are
 still safe: `scheduled_occurrences` has a unique `(name, scheduled_for)` claim,
@@ -62,6 +66,30 @@ Scheduled jobs are the preferred path. The scheduler only creates and
 dispatches the job; queue workers perform the expensive work. `call()` runs
 inside the scheduler process, so reserve it for short operations.
 
+### Durable worker progress
+
+Register `SchedulerCheckpointRecord` in the application's migration model registry,
+then pass `SchedulerCheckpointRecord.checkpoint('my-scheduler')` as `checkpoint`
+to `SchedulerWorker` or `runSchedulerConsole`. It persists restart progress in
+`scheduler_checkpoints`, with atomic initialization and monotonic updates.
+A custom `SchedulerCheckpoint` can supply another backend. Its operations are:
+
+- `load(firstMinute)` atomically establishes the minute immediately before
+  `firstMinute` on first use, or returns the existing last evaluated UTC minute.
+- `save(evaluatedFor)` durably advances that minute after the complete batch.
+  Concurrent writers must never move it backwards.
+
+Coverage is saved before dispatch; replacement workers resume after the cursor.
+Occurrence claims deduplicate replay. Without a checkpoint, startup begins in the
+current minute. A liveness timestamp cannot establish which minute was evaluated.
+
+An incomplete evaluation or failed checkpoint write retries the same minute
+after one second. Individual event failures are recorded as failed occurrences;
+they do not prevent the rest of that batch or later minutes from being evaluated.
+Catch-up uses currently registered definitions and invokes factories at the time
+of dispatch. Business-date-sensitive jobs must define their own date policy.
+One-off `scheduler:run`, list and history commands leave the worker cursor alone.
+
 ## Occurrence History
 
 `ScheduledOccurrence` owns the `scheduled_occurrences` table. Its lifecycle
@@ -132,8 +160,21 @@ or runs an application's historical schedules. The website includes the exact
 consumer-copyable test. Framework contributors run
 `npm run test:service --workspace packages/app -- scheduler`.
 
+The [elapsed-window runner](./examples/runSchedulerWindow.ts) demonstrates a
+boundary crossed during a heartbeat and a slow batch spanning the next minute,
+using the real SQL queue and a controlled clock. Run
+`npx tsx examples/runSchedulerWindow.ts` with the same dedicated test credentials.
+
 A daily local time may not occur during a spring DST transition and may map to
 two UTC minutes during an autumn transition. Claims are keyed by UTC minute,
-not by a local business date. There is no catch-up or exactly-once side-effect
-guarantee. Claims and queue dispatch are separate operations; monitor and
+not by a local business date. A nonexistent DST wall-clock minute is not a
+missed UTC evaluation. There is no exactly-once side-effect guarantee.
+Claims and queue dispatch are separate operations; monitor and
 reconcile occurrences left claimed by an interrupted dispatch.
+
+`SchedulerWorkerOptions.onTick` (also accepted by the scheduler console) lets
+an application persist a successful tick heartbeat, with `result.evaluatedFor`
+identifying the covered minute. It runs only when `runDue` returns without
+failures. Hook failures are logged and cause the same minute to be reconsidered.
+An independent monitor must detect stale heartbeats; scheduler self-logging
+cannot detect a scheduler process that has stopped.

package/src/scheduler/ScheduledEvent.ts

@@ -7,7 +7,7 @@ import { dailyScheduleIsDue, normalizeDailyTime, normalizeScheduleTimezone } fro
 export abstract class ScheduledEvent {
 	abstract readonly kind: scheduler.ScheduledTaskKind;
 	protected configuredName: string | null = null;
-	protected configuredFrequency: scheduler.DailyScheduleFrequency | null = null;
+	protected configuredFrequency: scheduler.ScheduleFrequency | null = null;
 	protected configuredTimezone = 'UTC';
 
 	/**
@@ -32,6 +32,18 @@ export abstract class ScheduledEvent {
 		return this;
 	}
 
+	/** Schedules one occurrence for each evaluated UTC minute, independent of timezone. */
+	everyMinute(): this {
+		this.configuredFrequency = { type: 'minute' };
+		return this;
+	}
+
+	/** Schedules one occurrence at minute zero of each UTC hour, independent of timezone. */
+	hourly(): this {
+		this.configuredFrequency = { type: 'hourly' };
+		return this;
+	}
+
 	/**
 	 * Schedules this task every day at local midnight.
 	 *
@@ -72,11 +84,14 @@ export abstract class ScheduledEvent {
 	 * Returns whether this event is due at one canonical UTC minute.
 	 *
 	 * @param instant - UTC minute being evaluated.
-	 * @returns True when the configured daily time matches.
+	 * @returns True when the configured frequency matches a valid minute.
 	 */
 	isDue(instant: Date): boolean {
 		const frequency = this.frequency();
 
+		if (frequency.type === 'minute') return Number.isFinite(instant.getTime());
+		if (frequency.type === 'hourly') return Number.isFinite(instant.getTime()) && instant.getUTCMinutes() === 0;
+
 		return dailyScheduleIsDue(
 			instant,
 			frequency.time,
@@ -119,11 +134,11 @@ export abstract class ScheduledEvent {
 	}
 
 	/**
-	 * Returns the daily frequency or throws when none was configured.
+	 * Returns the frequency or throws when none was configured.
 	 *
-	 * @returns Configured daily frequency.
+	 * @returns Configured frequency.
 	 */
-	private frequency(): scheduler.DailyScheduleFrequency {
+	private frequency(): scheduler.ScheduleFrequency {
 		if (!this.configuredFrequency) {
 			throw new Error(`Scheduled event "${this.resolvedName()}" requires a frequency.`);
 		}

package/src/scheduler/ScheduledJob.ts

@@ -1,4 +1,4 @@
-import { isQueueableJob, isQueueableJobClass, queueableJobName, type QueueableJob } from '../queue';
+import { isQueueableJob, isQueueableJobClass, queueableJobName, type QueueableJobContract as QueueableJob } from '../queue';
 import type * as scheduler from './contracts';
 import { ScheduledEvent } from './ScheduledEvent';
 

package/src/scheduler/Scheduler.ts

@@ -14,6 +14,8 @@ import { utcMinute } from './scheduleTime';
  */
 export class Scheduler {
 	readonly #events: ScheduledEvent[] = [];
+	readonly #owners = new Map<ScheduledEvent, { owner: string; run: scheduler.ScheduleRunner }>();
+	readonly #groups = new Set<string>();
 	readonly #unsubscribeQueueEvents: () => void;
 
 	/**
@@ -61,13 +63,47 @@ export class Scheduler {
 		return event;
 	}
 
+	/**
+	 * Atomically registers an owned schedule group. Declarations are synchronous and do not execute jobs.
+	 * Names are prefixed with the owner unless already namespaced. Failed declarations register nothing.
+	 */
+	register(owner: string, configure: (schedule: scheduler.Schedule) => void, run: scheduler.ScheduleRunner = operation => operation()): scheduler.ScheduleRegistration {
+		if (!/^[a-z][a-z0-9_]{0,39}$/.test(owner) || this.#groups.has(owner)) throw new Error(`Invalid or duplicate schedule owner "${owner}".`);
+		const events: ScheduledEvent[] = [];
+		const declaration = configure({
+			/** Collects a queued declaration without attaching it to the running scheduler yet. */
+			job: source => { const event = new ScheduledJob(source); events.push(event); return event; },
+			/** Collects a short callback under the same group ownership. */
+			call: handler => { const event = new ScheduledCall(handler); events.push(event); return event; },
+		}) as unknown;
+		if (declaration && typeof (declaration as Promise<unknown>).then === 'function') throw new Error('Schedule declarations must be synchronous.');
+		const names = new Set(this.definitions().map(definition => definition.name));
+		const definitions = events.map(event => {
+			const name = event.definition().name;
+			if (!name.startsWith(`${owner}.`)) event.name(`${owner}.${name}`);
+			const definition = { ...event.definition(), owner };
+			if (names.has(definition.name)) throw new Error(`Duplicate scheduled event name "${definition.name}".`);
+			names.add(definition.name);
+			return definition;
+		});
+		this.#groups.add(owner);
+		for (const event of events) { this.#events.push(event); this.#owners.set(event, { owner, run }); }
+		let closed = false;
+		return { definitions, close: () => {
+			if (closed) return;
+			closed = true;
+			for (const event of events) { this.#events.splice(this.#events.indexOf(event), 1); this.#owners.delete(event); }
+			this.#groups.delete(owner);
+		} };
+	}
+
 	/**
 	 * Returns validated normalized definitions in registration order.
 	 *
 	 * @returns Registered scheduler definitions.
 	 */
 	definitions(): scheduler.ScheduledTaskDefinition[] {
-		const definitions = this.#events.map(event => event.definition());
+		const definitions = this.#events.map(event => ({ ...event.definition(), ...(this.#owners.has(event) ? { owner: this.#owners.get(event)!.owner } : {}) }));
 		const names = new Set<string>();
 
 		for (const definition of definitions) {
@@ -111,37 +147,47 @@ export class Scheduler {
 		};
 
 		for (const event of dueEvents) {
-			const definition = event.definition();
-			const occurrence = await ActiveRecord.withDb(this.database.knex, () => {
-				return ScheduledOccurrence.claim({
-					name: definition.name,
-					kind: definition.kind,
-					scheduledFor: evaluatedFor,
-					jobName: definition.jobName,
+			const owner = this.#owners.get(event);
+			/** Runs a complete occurrence inside its registration owner's lifecycle gate. */
+			const execute = async (): Promise<void> => {
+				if (!this.#events.includes(event)) { result.skipped++; return; }
+				const definition = event.definition();
+				const occurrence = await ActiveRecord.withDb(this.database.knex, () => {
+					return ScheduledOccurrence.claim({
+						name: definition.name,
+						kind: definition.kind,
+						scheduledFor: evaluatedFor,
+						jobName: definition.jobName,
+					});
 				});
-			});
 
-			if (!occurrence) {
-				result.skipped += 1;
-				continue;
-			}
+				if (!occurrence) {
+					result.skipped += 1;
+					return;
+				}
 
-			result.claimed += 1;
+				result.claimed += 1;
 
-			try {
-				if (event instanceof ScheduledJob) {
-					await this.dispatchJob(event, occurrence);
-					result.dispatched += 1;
-				} else if (event instanceof ScheduledCall) {
-					await this.runCall(event, occurrence);
-					result.completed += 1;
+				try {
+					if (event instanceof ScheduledJob) {
+						await this.dispatchJob(event, occurrence);
+						result.dispatched += 1;
+					} else if (event instanceof ScheduledCall) {
+						await this.runCall(event, occurrence);
+						result.completed += 1;
+					}
+				} catch (error) {
+					await this.failOccurrence(occurrence, error);
+					result.failures.push({
+						name: definition.name,
+						error: errorDetails(error),
+					});
 				}
-			} catch (error) {
-				await this.failOccurrence(occurrence, error);
-				result.failures.push({
-					name: definition.name,
-					error: errorDetails(error),
-				});
+			};
+			if (!owner) await execute();
+			else {
+				try { await owner.run(execute); }
+				catch (error) { result.failures.push({ name: event.definition().name, error: errorDetails(error) }); }
 			}
 		}