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

package/dist/queue/drivers/DatabaseQueueDriver.js

@@ -1,6 +1,7 @@
 import { ActiveRecord, RecordValidationError, withQueryMonitorCategory } from '../../db/index.js';
 import { FailedJob } from '../FailedJob.js';
 import { QueuedJob } from '../QueuedJob.js';
+import { jobEnvelopeHasPrefix } from '../jobEnvelopeHasPrefix.js';
 /**
  * Queue driver that stores pending and failed jobs in the app database.
  */
@@ -15,6 +16,28 @@ export class DatabaseQueueDriver {
     constructor(db) {
         this.db = db;
     }
+    /** Discovers queue names from the queue index, including delayed and reserved work. */
+    async queueNames() {
+        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) {
+        if (!(await this.db.knex.schema.hasTable(QueuedJob.table)))
+            return false;
+        let after = 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.
      *
@@ -22,7 +45,8 @@ export class DatabaseQueueDriver {
      * @returns Database id of the queued job record.
      */
     async push(job) {
-        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,
@@ -39,7 +63,7 @@ export class DatabaseQueueDriver {
                 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);
         }));
     }
@@ -93,7 +117,7 @@ export class DatabaseQueueDriver {
      * @returns True when the current attempt still owns the job.
      */
     async touch(job, _retryAfterSeconds) {
-        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/dist/queue/drivers/RedisQueueDriver.d.ts

@@ -29,6 +29,13 @@ export declare class RedisQueueDriver implements queue.QueueDriver {
      * @returns Redis queue job id.
      */
     push<TData extends Record<string, unknown>>(job: queue.QueueDriverPushInput<TData>): Promise<queue.QueueJobId>;
+    /**
+     * Discovers queue names from ready/delayed/reserved keys without reading payloads.
+     * SCAN includes existing queues written before this capability was introduced.
+     */
+    queueNames(): Promise<string[]>;
+    /** Scans active Redis payloads during quiesced maintenance; includes delayed, reserved and chained jobs. */
+    hasPendingJobs(jobPrefix: string): Promise<boolean>;
     /**
      * Claims the next available job from a Redis queue.
      *

package/dist/queue/drivers/RedisQueueDriver.js

@@ -1,5 +1,6 @@
 import { createClient } from '@redis/client';
 import { unknownErrorMessage } from '@db3.ai/pure';
+import { jobEnvelopeHasPrefix } from '../jobEnvelopeHasPrefix.js';
 const PUSH_SCRIPT = `
 local id = tostring(redis.call('INCR', KEYS[1]))
 local record = cjson.decode(ARGV[1])
@@ -171,6 +172,42 @@ export class RedisQueueDriver {
         ]);
         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() {
+        const prefix = `${this.#key('queues')}:`;
+        const pattern = prefix.replace(/[\\*?\[\]]/g, '\\$&') + '*';
+        const names = new Set();
+        let cursor = '0';
+        do {
+            const [next, keys] = await this.#command(['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) {
+        let cursor = '0';
+        do {
+            const result = await this.#command(['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]);
+                if (jobEnvelopeHasPrefix(record.payload, jobPrefix))
+                    return true;
+            }
+        } while (cursor !== '0');
+        return false;
+    }
     /**
      * Claims the next available job from a Redis queue.
      *

package/dist/queue/index.d.ts

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

package/dist/queue/index.js

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

package/dist/queue/jobEnvelopeHasPrefix.d.ts

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

package/dist/queue/jobEnvelopeHasPrefix.js

@@ -0,0 +1,4 @@
+/** Checks active work and nested chained continuations without inspecting application-owned payload data. */
+export function jobEnvelopeHasPrefix(envelope, prefix) {
+    return envelope.job.startsWith(prefix) || Boolean(envelope.chained?.some(job => jobEnvelopeHasPrefix(job, prefix)));
+}

package/dist/scheduler/ScheduledEvent.d.ts

@@ -5,7 +5,7 @@ import type * as scheduler from './contracts/index.js';
 export declare abstract class ScheduledEvent {
     abstract readonly kind: scheduler.ScheduledTaskKind;
     protected configuredName: string | null;
-    protected configuredFrequency: scheduler.DailyScheduleFrequency | null;
+    protected configuredFrequency: scheduler.ScheduleFrequency | null;
     protected configuredTimezone: string;
     /**
      * Sets the stable identity used for deduplication and history.
@@ -14,6 +14,10 @@ export declare abstract class ScheduledEvent {
      * @returns This scheduled event.
      */
     name(name: string): this;
+    /** Schedules one occurrence for each evaluated UTC minute, independent of timezone. */
+    everyMinute(): this;
+    /** Schedules one occurrence at minute zero of each UTC hour, independent of timezone. */
+    hourly(): this;
     /**
      * Schedules this task every day at local midnight.
      *
@@ -38,7 +42,7 @@ export declare 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;
     /**
@@ -54,9 +58,9 @@ export declare abstract class ScheduledEvent {
      */
     protected resolvedName(): string;
     /**
-     * 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;
     /**

package/dist/scheduler/ScheduledEvent.js

@@ -23,6 +23,16 @@ export class ScheduledEvent {
         this.configuredName = normalized;
         return this;
     }
+    /** Schedules one occurrence for each evaluated UTC minute, independent of timezone. */
+    everyMinute() {
+        this.configuredFrequency = { type: 'minute' };
+        return this;
+    }
+    /** Schedules one occurrence at minute zero of each UTC hour, independent of timezone. */
+    hourly() {
+        this.configuredFrequency = { type: 'hourly' };
+        return this;
+    }
     /**
      * Schedules this task every day at local midnight.
      *
@@ -58,10 +68,14 @@ export 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) {
         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, this.configuredTimezone);
     }
     /**
@@ -94,9 +108,9 @@ export class ScheduledEvent {
         return name;
     }
     /**
-     * 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.
      */
     frequency() {
         if (!this.configuredFrequency) {

package/dist/scheduler/ScheduledJob.d.ts

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

package/dist/scheduler/Scheduler.d.ts

@@ -31,6 +31,11 @@ export declare class Scheduler {
      * @returns Fluent scheduled call definition.
      */
     call(callback: scheduler.ScheduledCallHandler): ScheduledCall;
+    /**
+     * 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): scheduler.ScheduleRegistration;
     /**
      * Returns validated normalized definitions in registration order.
      *

package/dist/scheduler/Scheduler.js

@@ -13,6 +13,8 @@ export class Scheduler {
     database;
     queue;
     #events = [];
+    #owners = new Map();
+    #groups = new Set();
     #unsubscribeQueueEvents;
     /**
      * Creates a scheduler and attaches durable queue lifecycle recording.
@@ -50,13 +52,57 @@ export class Scheduler {
         this.#events.push(event);
         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, configure, run = operation => operation()) {
+        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 = [];
+        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; },
+        });
+        if (declaration && typeof declaration.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() {
-        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();
         for (const definition of definitions) {
             if (names.has(definition.name)) {
@@ -93,36 +139,54 @@ export class Scheduler {
             failures: [],
         };
         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 () => {
+                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;
-            }
-            result.claimed += 1;
-            try {
-                if (event instanceof ScheduledJob) {
-                    await this.dispatchJob(event, occurrence);
-                    result.dispatched += 1;
+                if (!occurrence) {
+                    result.skipped += 1;
+                    return;
                 }
-                else if (event instanceof ScheduledCall) {
-                    await this.runCall(event, occurrence);
-                    result.completed += 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;
+                    }
+                }
+                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) });
                 }
-            }
-            catch (error) {
-                await this.failOccurrence(occurrence, error);
-                result.failures.push({
-                    name: definition.name,
-                    error: errorDetails(error),
-                });
             }
         }
         result.finishedAt = new Date();

package/dist/scheduler/SchedulerCheckpointRecord.d.ts

@@ -0,0 +1,16 @@
+import { ActiveRecord } from '../db/index.js';
+import type { SchedulerCheckpoint } from './contracts/index.js';
+declare const SchedulerCheckpointRecord_base: import("../db/index.js").DefinedActiveRecord<typeof ActiveRecord, {
+    id: import("../db/index.js").UlidField;
+    name: import("../db/index.js").StringField;
+    value: import("../db/index.js").JsonField<{
+        evaluatedFor: string;
+    } | null>;
+    updatedAt: import("../db/index.js").TimestampField;
+}>;
+/** Durable scheduler restart progress; register this model in the application's migration registry. */
+export declare class SchedulerCheckpointRecord extends SchedulerCheckpointRecord_base {
+    /** Returns restart persistence for one stable scheduler name; concurrent saves never regress progress. */
+    static checkpoint(name?: string): SchedulerCheckpoint;
+}
+export {};

package/dist/scheduler/SchedulerCheckpointRecord.js

@@ -0,0 +1,53 @@
+import { ActiveRecord } from '../db/index.js';
+/** Durable scheduler restart progress; register this model in the application's migration registry. */
+export class SchedulerCheckpointRecord extends ActiveRecord.define({
+    table: 'scheduler_checkpoints',
+    fields: field => ({
+        id: field.ulid(),
+        name: field.string({ required: true, length: 120, unique: true }),
+        value: field.json({ required: true }),
+        updatedAt: field.timestamp({ column: 'updated_at', auto: 'update' }),
+    }),
+}) {
+    /** Returns restart persistence for one stable scheduler name; concurrent saves never regress progress. */
+    static checkpoint(name = 'default') {
+        return {
+            /** Establishes coverage before the first dispatch without resetting an existing scheduler. */
+            async load(firstMinute) {
+                let record = await SchedulerCheckpointRecord.where('name', name).first();
+                if (!record) {
+                    try {
+                        record = await SchedulerCheckpointRecord.create({ name, value: { evaluatedFor: new Date(firstMinute.getTime() - 60_000).toISOString() } }).save();
+                    }
+                    catch (error) {
+                        record = await SchedulerCheckpointRecord.where('name', name).first();
+                        if (!record)
+                            throw error;
+                    }
+                }
+                return checkpointMinute(record.value.evaluatedFor);
+            },
+            /** Advances only a valid, initialized UTC-minute cursor under a database row lock. */
+            async save(evaluatedFor) {
+                const minute = checkpointMinute(evaluatedFor.toISOString());
+                await SchedulerCheckpointRecord.getDb().transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+                    const row = await SchedulerCheckpointRecord.where('name', name).toKnex().forUpdate().first();
+                    if (!row)
+                        throw new Error('Scheduler checkpoint must be initialized before advancing it.');
+                    const record = SchedulerCheckpointRecord.fromDb(row);
+                    if (checkpointMinute(record.value.evaluatedFor).getTime() >= minute.getTime())
+                        return;
+                    record.value = { evaluatedFor: minute.toISOString() };
+                    await record.save();
+                }));
+            },
+        };
+    }
+}
+/** Rejects corrupt progress rather than silently skipping an unknown scheduling window. */
+function checkpointMinute(value) {
+    const minute = new Date(typeof value === 'string' ? value : NaN);
+    if (!Number.isFinite(minute.getTime()) || minute.getTime() % 60_000 !== 0)
+        throw new Error('Scheduler checkpoint requires a valid UTC minute.');
+    return minute;
+}

package/dist/scheduler/SchedulerWorker.d.ts

@@ -14,7 +14,9 @@ export declare class SchedulerWorker {
      */
     constructor(schedulerService: Scheduler, options?: scheduler.SchedulerWorkerOptions);
     /**
-     * Runs immediately, then evaluates at each subsequent wall-clock minute.
+     * Evaluates every uncovered minute in order, including time spent dispatching
+     * earlier batches. Catch-up yields after sixty minutes without discarding work.
+     * A durable checkpoint resumes coverage across replacement processes.
      *
      * @throws Error when the same worker instance is started twice.
      */
@@ -23,10 +25,6 @@ export declare class SchedulerWorker {
      * Requests graceful shutdown and interrupts the current minute wait.
      */
     stop(): void;
-    /**
-     * Evaluates one scheduler minute and reports failures without ending work.
-     */
-    private runTick;
 }
 /**
  * Calculates the delay from one instant to the next UTC minute boundary.

package/dist/scheduler/SchedulerWorker.js

@@ -1,4 +1,8 @@
+import { utcMinute } from './scheduleTime.js';
 const DEFAULT_SLOW_TICK_WARNING_MS = 50_000;
+const MINUTE_MS = 60_000;
+const MAX_MINUTES_PER_BATCH = 60;
+const FAILED_TICK_RETRY_MS = 1_000;
 /**
  * Long-running minute-aligned process adapter around Scheduler.runDue().
  */
@@ -7,6 +11,9 @@ export class SchedulerWorker {
     #running = false;
     #abortController = null;
     #now;
+    #nextMinute = null;
+    #onTick;
+    #checkpoint;
     #sleep;
     #logger;
     #slowTickWarningMs;
@@ -18,6 +25,8 @@ export class SchedulerWorker {
      */
     constructor(schedulerService, options = {}) {
         this.schedulerService = schedulerService;
+        this.#onTick = options.onTick;
+        this.#checkpoint = options.checkpoint;
         this.#now = options.now ?? (() => new Date());
         this.#sleep = options.sleep ?? schedulerSleep;
         this.#logger = options.logger ?? consoleSchedulerLogger();
@@ -25,7 +34,9 @@ export class SchedulerWorker {
             ?? DEFAULT_SLOW_TICK_WARNING_MS;
     }
     /**
-     * Runs immediately, then evaluates at each subsequent wall-clock minute.
+     * Evaluates every uncovered minute in order, including time spent dispatching
+     * earlier batches. Catch-up yields after sixty minutes without discarding work.
+     * A durable checkpoint resumes coverage across replacement processes.
      *
      * @throws Error when the same worker instance is started twice.
      */
@@ -36,11 +47,30 @@ export class SchedulerWorker {
         this.#running = true;
         this.#abortController = new AbortController();
         try {
+            if (this.#nextMinute === null) {
+                const firstMinute = utcMinute(this.#now());
+                const previous = await this.#checkpoint?.load(firstMinute);
+                this.#nextMinute = previous ? utcMinute(previous).getTime() + MINUTE_MS : firstMinute.getTime();
+            }
+            let batchSize = 0;
             while (this.#running) {
-                await this.runTick();
-                if (!this.#running)
-                    break;
-                await this.#sleep(millisecondsUntilNextMinute(this.#now()), this.#abortController.signal);
+                const now = this.#now();
+                const currentMinute = utcMinute(now).getTime();
+                if (this.#nextMinute <= currentMinute) {
+                    const completed = await this.#runTick(new Date(this.#nextMinute));
+                    if (completed)
+                        this.#nextMinute += MINUTE_MS;
+                    if (!this.#running)
+                        break;
+                    if (!completed || ++batchSize >= MAX_MINUTES_PER_BATCH) {
+                        await this.#sleep(completed ? 1 : FAILED_TICK_RETRY_MS, this.#abortController.signal);
+                        batchSize = 0;
+                    }
+                    continue;
+                }
+                batchSize = 0;
+                // An early timer or backward clock step must not skip or repeat a minute.
+                await this.#sleep(Math.min(MINUTE_MS, Math.max(1, this.#nextMinute - now.getTime())), this.#abortController.signal);
             }
         }
         finally {
@@ -56,12 +86,22 @@ export class SchedulerWorker {
         this.#abortController?.abort();
     }
     /**
-     * Evaluates one scheduler minute and reports failures without ending work.
+     * Evaluates one fixed minute, preserving progress only after the whole batch.
+     * Recorded event failures remain visible and do not prevent later minutes;
+     * incomplete evaluations and checkpoint failures retry this same minute.
+     *
+     * @param evaluatedFor - Original scheduled minute, independent of dispatch duration.
+     * @returns Whether the complete minute was evaluated and its checkpoint saved.
      */
-    async runTick() {
+    async #runTick(evaluatedFor) {
         const startedAt = performance.now();
+        let completed = false;
         try {
-            const result = await this.schedulerService.runDue(this.#now());
+            const result = await this.schedulerService.runDue(evaluatedFor);
+            if (result.failures.length === 0)
+                await this.#onTick?.(result);
+            await this.#checkpoint?.save(evaluatedFor);
+            completed = true;
             if (result.due > 0 || result.failures.length > 0) {
                 this.#logger.info(`[scheduler] ${result.evaluatedFor.toISOString()} due=${result.due} claimed=${result.claimed} dispatched=${result.dispatched} completed=${result.completed} skipped=${result.skipped} failed=${result.failures.length}.`);
             }
@@ -70,12 +110,13 @@ export class SchedulerWorker {
             }
         }
         catch (error) {
-            this.#logger.error('[scheduler] Tick failed; the worker will continue.', error);
+            this.#logger.error(`[scheduler] Evaluation for ${evaluatedFor.toISOString()} did not finish; retrying the same minute.`, error);
         }
         const durationMs = performance.now() - startedAt;
         if (durationMs >= this.#slowTickWarningMs) {
             this.#logger.warn(`[scheduler] Tick took ${Math.round(durationMs)}ms; inline calls should remain short.`);
         }
+        return completed;
     }
 }
 /**
@@ -96,13 +137,16 @@ export function millisecondsUntilNextMinute(now) {
  */
 async function schedulerSleep(delayMs, signal) {
     await new Promise(resolve => {
-        const timeout = setTimeout(resolve, delayMs);
-        signal.addEventListener('abort', () => {
+        /** Clears the timer and its abort subscription on either completion path. */
+        const finish = () => {
             clearTimeout(timeout);
+            signal.removeEventListener('abort', finish);
             resolve();
-        }, {
-            once: true,
-        });
+        };
+        const timeout = setTimeout(finish, delayMs);
+        signal.addEventListener('abort', finish, { once: true });
+        if (signal.aborted)
+            finish();
     });
 }
 /**