@gobing-ai/ts-infra 0.4.59 → 0.4.62

package/src/job-queue/db-job-queue.ts

@@ -7,6 +7,7 @@ import type {
     QueueJobFailedDetail,
     QueueJobRetryingDetail,
 } from '../events';
+import { resolveExecutionTimeoutMs, runWithExecutionDeadline } from '../execution-policy';
 import { settleWithin } from '../internals/drain';
 import { getLogger, type Logger } from '../logger';
 import {
@@ -67,7 +68,7 @@ function enqueuedDetail(jobId: string, type: string, options: EnqueueOptions | u
     return detail;
 }
 
-/** DB-backed queue consumer with polling, retry, and visibility-timeout handling. */
+/** DB-backed queue consumer with polling, retry, lease ownership, and execution-deadline handling. */
 export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private readonly handlers = new Map<string, JobHandler<T>>();
     private readonly pollInterval: number;
@@ -77,6 +78,11 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private readonly baseDelay: number;
     private readonly maxDelay: number;
     private readonly drainTimeoutMs: number;
+    private readonly drainPolicy: 'bounded' | 'drain-to-completion';
+    /** Default execution policy for jobs without their own persisted decision; `null` = unlimited. */
+    private readonly defaultTimeoutMs: number | null;
+    /** Live attempts owned by this consumer, keyed by job id — the target of `cancel()`. */
+    private readonly activeAttempts = new Map<string, { controller: AbortController; state: AttemptState }>();
     /**
      * Validated event sink: the bus plus the non-empty queue name its lifecycle rows
      * require (ADR-068). `undefined` for silent consumers — no `events`, no identity.
@@ -98,6 +104,19 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         this.baseDelay = nonNegativeFiniteConfig('baseDelay', config.baseDelay ?? 1_000);
         this.maxDelay = nonNegativeFiniteConfig('maxDelay', config.maxDelay ?? 60_000);
         this.drainTimeoutMs = nonNegativeFiniteConfig('drainTimeoutMs', config.drainTimeoutMs ?? 30_000);
+        this.drainPolicy = config.drainPolicy ?? 'bounded';
+        if (
+            config.defaultTimeoutMs !== undefined &&
+            config.defaultTimeoutMs !== null &&
+            (typeof config.defaultTimeoutMs !== 'number' ||
+                !Number.isInteger(config.defaultTimeoutMs) ||
+                config.defaultTimeoutMs <= 0)
+        ) {
+            throw new RangeError(
+                `Queue consumer defaultTimeoutMs must be a positive integer or null; received ${String(config.defaultTimeoutMs)}`,
+            );
+        }
+        this.defaultTimeoutMs = config.defaultTimeoutMs ?? null;
         this.eventSink = resolveEventSink(config);
     }
 
@@ -131,6 +150,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
             this.timer = null;
         }
 
+        const drainToCompletion = this.drainPolicy === 'drain-to-completion';
         const deadline = Date.now() + this.drainTimeoutMs;
 
         // Wait for an already-running poll cycle before consulting `inFlight`.
@@ -140,11 +160,25 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         // to claim and process jobs after stop() resolved.
         const pending = this.pollPromise;
         if (pending !== null) {
-            await settleWithin(pending, deadline);
+            if (drainToCompletion) {
+                await pending;
+            } else {
+                await settleWithin(pending, deadline);
+            }
         }
 
-        while (this.inFlight > 0 && Date.now() < deadline) {
-            await sleep(10);
+        if (drainToCompletion) {
+            // Shutdown policy (A21): wait for every in-flight attempt to settle,
+            // however long that takes. Leases keep renewing while we wait.
+            while (this.inFlight > 0) {
+                await sleep(10);
+            }
+        } else {
+            while (this.inFlight > 0 && Date.now() < deadline) {
+                await sleep(10);
+            }
+            // Bounded drain expiry (A21): attempts still running keep ownership —
+            // their leases keep renewing and they are acknowledged when they settle.
         }
         if (wasRunning) {
             const drained = this.inFlight === 0;
@@ -162,6 +196,14 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         }
     }
 
+    async cancel(jobId: string): Promise<boolean> {
+        const attempt = this.activeAttempts.get(jobId);
+        if (attempt === undefined) return false;
+        attempt.state.cancelled = true;
+        attempt.controller.abort();
+        return true;
+    }
+
     async stats(): Promise<QueueStats> {
         return this.dao.getStats();
     }
@@ -172,7 +214,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
             await this.dao.resetStuckJobs(this.visibilityTimeout);
             await this.dao.failExpiredJobs();
 
-            const jobs = await this.dao.claimReady(this.batchSize);
+            const jobs = await this.dao.claimReady(this.batchSize, { leaseMs: this.visibilityTimeout });
             let processed = 0;
 
             for (let index = 0; index < jobs.length; index += this.maxConcurrency) {
@@ -229,7 +271,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         } catch (error) {
             // Corrupt payload — the job can never parse; route it through the
             // retry/fail path instead of rejecting the whole batch.
-            await this.failOrRetry(record, error, 0);
+            await this.failOrRetry(record, error, 0, record.attemptToken ?? undefined);
             return;
         }
         return traceAsync('queue.job.process', async () => {
@@ -240,43 +282,146 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
             });
 
             const handler = this.handlers.get(job.type);
+            const token = record.attemptToken ?? undefined;
             if (handler === undefined) {
-                await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`), 0);
+                await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`), 0, token);
                 return;
             }
 
-            const startMs = performance.now();
+            // Per-attempt ownership (A21): the fresh claim token fences every
+            // acknowledgement, and the external controller carries lease-loss and
+            // manual cancellation into the shared deadline clock.
+            let attemptWake: (() => void) | undefined;
+            const attempt: AttemptState = { lost: false, cancelled: false, settled: false };
+            const attemptAbort = new AbortController();
+            if (token !== undefined) {
+                const { promise: settledSignal, resolve: resolveSettled } = Promise.withResolvers<void>();
+                attempt.settledSignal = settledSignal;
+                attemptWake = resolveSettled;
+                // Shares the `attempt` object reference so cancel() mutations are
+                // visible in the outcome dispatch below.
+                this.activeAttempts.set(record.id, { controller: attemptAbort, state: attempt });
+            }
+            const renewal =
+                token === undefined
+                    ? undefined
+                    : this.renewUntilSettled(record.id, token, attempt, attemptAbort).catch(() => {});
             try {
-                await handler(job);
-                await this.dao.markCompleted(job.id);
+                const resolvedTimeout = resolveExecutionTimeoutMs(
+                    `job "${job.type}"`,
+                    record.timeoutUnlimited === 1 ? null : (record.timeoutMs ?? undefined),
+                    this.defaultTimeoutMs,
+                );
+                const startMs = performance.now();
+                const outcome = await runWithExecutionDeadline((context) => handler(job, context), {
+                    timeoutMs: resolvedTimeout,
+                    signal: attemptAbort.signal,
+                });
+                attempt.settled = true;
+                attemptWake?.();
                 const durationMs = performance.now() - startMs;
-                getQueueJobCompletedTotal().add(1, { type: job.type });
-                getQueueJobProcessingDuration().record(durationMs, { type: job.type });
-                const completed: QueueJobCompletedDetail = {
-                    jobId: job.id,
+                getQueueJobProcessingDuration().record(Number.isFinite(durationMs) ? durationMs : 0, {
                     type: job.type,
-                    durationMs: Number.isFinite(durationMs) ? durationMs : 0,
-                    attempt: job.attempts,
-                    severity: 'info',
-                };
-                await this.eventSink?.bus.emit('queue.job.completed', completed);
-            } catch (error) {
-                const durationMs = performance.now() - startMs;
-                getQueueJobProcessingDuration().record(durationMs, { type: job.type });
-                await this.failOrRetry(job, error, Number.isFinite(durationMs) ? durationMs : 0);
+                });
+
+                if (attempt.lost) {
+                    // Ownership was lost: the row now belongs to a replacement attempt
+                    // claimed through the expired lease. Fence every acknowledgement —
+                    // a stale ack must never mutate the replacement's work (R4).
+                    queueLogger().warn('queue attempt lost lease ownership; acknowledgement fenced', {
+                        jobId: record.id,
+                        type: job.type,
+                        outcome: outcome.outcome,
+                    });
+                    return;
+                }
+
+                if (outcome.outcome === 'error') {
+                    await this.failOrRetry(job, outcome.error, Number.isFinite(durationMs) ? durationMs : 0, token);
+                } else if (outcome.timedOut) {
+                    // Deadline expiry is a failure like any other, reported only after
+                    // the handler has settled — even if it ignored the abort.
+                    await this.failOrRetry(job, outcome.error, Number.isFinite(durationMs) ? durationMs : 0, token);
+                } else if (attempt.cancelled) {
+                    // Manual cancellation is terminal: settle, then fail without retry.
+                    const message = 'job cancelled';
+                    const applied = await this.dao.markFailed(record.id, job.attempts + 1, message, token);
+                    if (applied) {
+                        getQueueJobFailedTotal().add(1, { type: job.type });
+                        await this.eventSink?.bus.emit('queue.job.failed', {
+                            jobId: job.id,
+                            type: job.type,
+                            error: message,
+                            attempt: job.attempts + 1,
+                            maxRetries: job.maxRetries,
+                            durationMs: Number.isFinite(durationMs) ? durationMs : 0,
+                            severity: 'warning',
+                        });
+                    }
+                } else {
+                    await this.dao.markCompleted(record.id, token);
+                    getQueueJobCompletedTotal().add(1, { type: job.type });
+                    const completed: QueueJobCompletedDetail = {
+                        jobId: job.id,
+                        type: job.type,
+                        durationMs: Number.isFinite(durationMs) ? durationMs : 0,
+                        attempt: job.attempts,
+                        severity: 'info',
+                    };
+                    await this.eventSink?.bus.emit('queue.job.completed', completed);
+                }
+            } finally {
+                attempt.settled = true;
+                attemptWake?.();
+                if (renewal !== undefined) await renewal;
+                if (token !== undefined) this.activeAttempts.delete(record.id);
             }
         });
     }
 
+    /**
+     * Extend the attempt's lease on an interval derived from the visibility
+     * timeout, proving this consumer is still alive and working. A failed or
+     * erroring renewal means ownership was lost: abort the attempt so the
+     * handler can stop, and mark the attempt fenced.
+     */
+    private async renewUntilSettled(
+        id: string,
+        token: string,
+        attempt: AttemptState,
+        attemptAbort: AbortController,
+    ): Promise<void> {
+        const intervalMs = Math.max(1, Math.floor(this.visibilityTimeout / 3));
+        while (!attempt.settled) {
+            // Settle-aware wait: wakes early when the attempt finishes so a long
+            // visibility timeout never delays acknowledgement past the handler.
+            await Promise.race([sleep(intervalMs), attempt.settledSignal]);
+            if (attempt.settled) return;
+            let renewed = false;
+            try {
+                renewed = await this.dao.renewLease(id, token, this.visibilityTimeout);
+            } catch {
+                renewed = false; // DB unavailability is treated like ownership loss
+            }
+            if (attempt.settled) return;
+            if (!renewed) {
+                attempt.lost = true;
+                attemptAbort.abort();
+                return;
+            }
+        }
+    }
+
     private async failOrRetry(
         job: Pick<Job<T>, 'id' | 'type' | 'attempts' | 'maxRetries'>,
         error: unknown,
         durationMs: number,
+        attemptToken?: string,
     ): Promise<void> {
         const attempts = job.attempts + 1;
         const message = error instanceof Error ? error.message : String(error);
         if (attempts >= job.maxRetries) {
-            await this.dao.markFailed(job.id, attempts, message);
+            await this.dao.markFailed(job.id, attempts, message, attemptToken);
             getQueueJobFailedTotal().add(1, { type: job.type });
             const failed: QueueJobFailedDetail = {
                 jobId: job.id,
@@ -293,7 +438,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
 
         const delay = Math.min(this.maxDelay, this.baseDelay * 2 ** Math.max(0, attempts - 1));
         const nextRetryAt = Date.now() + delay;
-        await this.dao.markForRetry(job.id, attempts, message, nextRetryAt);
+        await this.dao.markForRetry(job.id, attempts, message, nextRetryAt, attemptToken);
         const retrying: QueueJobRetryingDetail = {
             jobId: job.id,
             type: job.type,
@@ -307,6 +452,18 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     }
 }
 
+/** Live per-attempt state shared between `processJob`, the renewal loop, and `cancel()`. */
+type AttemptState = {
+    /** Set when the lease was lost — the attempt's acknowledgements are fenced. */
+    lost: boolean;
+    /** Set by a manual `cancel()` — the attempt is failed without retry after settling. */
+    cancelled: boolean;
+    /** Set once the handler has settled — stops the renewal loop. */
+    settled: boolean;
+    /** Resolved when the attempt settles so the renewal wait wakes early. */
+    settledSignal?: Promise<void>;
+};
+
 function toJob<T>(record: QueueJobRecord): Job<T> {
     return {
         id: record.id,
@@ -320,6 +477,8 @@ function toJob<T>(record: QueueJobRecord): Job<T> {
         nextRetryAt: record.nextRetryAt,
         lastError: record.lastError,
         processingAt: record.processingAt,
+        // Persisted job policy: explicit unlimited stays `null`, absence stays undefined.
+        timeoutMs: record.timeoutUnlimited === 1 ? null : (record.timeoutMs ?? undefined),
     };
 }
 

package/src/job-queue/types.ts

@@ -7,8 +7,9 @@
 
 import type { EventBus } from '../event-bus/event-bus';
 import type { QueueEvents } from '../events';
+import type { ExecutionContext } from '../execution-policy';
 
-/** A queued job with status tracking, retry metadata, and timestamps. */
+/** A queued job with status tracking, retry metadata, timestamps, and its persisted execution policy. */
 export interface Job<T = unknown> {
     id: string;
     type: string;
@@ -22,14 +23,27 @@ export interface Job<T = unknown> {
     nextRetryAt: number | null;
     lastError: string | null;
     processingAt: number | null;
+    /**
+     * Job-level execution policy as persisted: a positive integer ms deadline,
+     * explicit `null` = unlimited, or `undefined` = no job-level decision (the
+     * consumer default applies). Never the resolved per-attempt value.
+     */
+    timeoutMs?: number | null;
 }
 
-/** Options for enqueuing a job: retry policy, delay, and TTL. */
+/** Options for enqueuing a job: retry policy, delay, TTL, and execution policy. */
 export interface EnqueueOptions {
     /** Total attempts allowed (default 3) — `maxRetries: 1` runs the job once with no retry. */
     maxRetries?: number;
     delay?: number;
     ttlMs?: number;
+    /**
+     * Job execution policy persisted with the row: a positive integer ms
+     * deadline, explicit `null` = unlimited (disables this job's deadline),
+     * omitted = no job-level decision (consumers apply their own default).
+     * Invalid explicit values are rejected before the row is created.
+     */
+    timeoutMs?: number | null;
 }
 
 /** Producer interface for the job queue — enqueue single jobs or batches. */
@@ -39,8 +53,12 @@ export interface JobQueue<T = unknown> {
     stats(): Promise<QueueStats>;
 }
 
-/** Async handler that processes a single job. */
-export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
+/**
+ * Async handler that processes a single job. The context carries the shared
+ * execution deadline clock for this attempt; single-argument handlers stay
+ * assignable.
+ */
+export type JobHandler<T = unknown> = (job: Job<T>, context: ExecutionContext) => Promise<void>;
 
 /** Aggregate statistics for a job queue: counts by status. */
 export interface QueueStats {
@@ -50,7 +68,7 @@ export interface QueueStats {
     failed: number;
 }
 
-/** Configuration for a queue consumer: polling, concurrency, and backoff. */
+/** Configuration for a queue consumer: polling, concurrency, backoff, and the default execution policy. */
 export interface QueueConsumerConfig {
     pollInterval?: number;
     batchSize?: number;
@@ -60,6 +78,20 @@ export interface QueueConsumerConfig {
     maxDelay?: number;
     /** Upper bound (ms, default 30_000) on how long `stop()` waits for in-flight work to drain. */
     drainTimeoutMs?: number;
+    /**
+     * Shutdown drain policy (A21). `'bounded'` (default): `stop()` gives up after
+     * `drainTimeoutMs`; attempts still running keep their leases, keep renewing, and
+     * are acknowledged when they settle. `'drain-to-completion'`: `stop()` waits for
+     * all in-flight attempts to settle, however long that takes.
+     */
+    drainPolicy?: 'bounded' | 'drain-to-completion';
+    /**
+     * Default execution policy for jobs without their own persisted decision
+     * (A21): a positive integer ms deadline or explicit `null` = unlimited.
+     * First-match-wins: an explicit job option — including job `null` — beats
+     * this default; absence inherits it.
+     */
+    defaultTimeoutMs?: number | null;
     /**
      * Identity of the queue this consumer polls. Runtime-required whenever `events` is
      * configured (ADR-068): an observable consumer must never emit an anonymous lifecycle
@@ -81,10 +113,18 @@ export interface QueueConsumerConfig {
 export interface QueueConsumer<T = unknown> {
     register(type: string, handler: JobHandler<T>): void;
     start(): Promise<void>;
+    /**
+     * Request cooperative cancellation of a claimed attempt (A21). The context
+     * signal aborts with reason `'cancelled'`; the attempt is allowed to settle
+     * and is then failed without retry. Resolves `false` when the job is not
+     * currently owned by this consumer.
+     */
+    cancel(jobId: string): Promise<boolean>;
     /**
      * Stop polling and drain work already in flight, including a poll cycle that has
-     * claimed nothing yet. Resolves once the drain completes or `drainTimeoutMs`
-     * elapses — whichever comes first, so a hung handler cannot block shutdown.
+     * claimed nothing yet. Under the default `'bounded'` policy this resolves once the
+     * drain completes or `drainTimeoutMs` elapses; `'drain-to-completion'` ignores the
+     * bound and waits for every in-flight attempt.
      */
     stop(): Promise<void>;
     stats(): Promise<QueueStats>;

package/src/scheduler/cloudflare.ts

@@ -2,6 +2,8 @@
  * Cloudflare Workers scheduler adapter using Cron Triggers.
  * Uses minimal local type declarations — no @cloudflare/workers-types dependency.
  */
+
+import { unlimitedExecutionContext } from '../execution-policy';
 import {
     getSchedulerJobDuration,
     getSchedulerJobExecutedTotal,
@@ -60,7 +62,7 @@ export class CloudflareSchedulerAdapter implements SchedulerAdapter {
             const startMs = performance.now();
             getSchedulerJobExecutedTotal().add(1, { cron: event.cron });
             ctx.waitUntil(
-                action()
+                action(unlimitedExecutionContext())
                     .catch((error: unknown) => {
                         getSchedulerJobFailedTotal().add(1, { cron: event.cron });
                         throw error;

package/src/scheduler/index.ts

@@ -12,5 +12,10 @@ export {
 } from './action';
 export { initScheduler } from './factory';
 export { NoopSchedulerAdapter } from './noop';
-export type { ScheduledAction, SchedulerAdapter, SchedulerJobConfig } from './types';
+export type {
+    ScheduledAction,
+    ScheduledActionOptions,
+    SchedulerAdapter,
+    SchedulerJobConfig,
+} from './types';
 export { wrapScheduledHandler } from './wrap-handler';

package/src/scheduler/node.ts

@@ -6,7 +6,9 @@
  * internal `scheduler/cron.ts` grammar shared with `application-node.ts`.
  */
 
+import { type ExecutionDeadlineMs, resolveExecutionTimeoutMs, runWithExecutionDeadline } from '../execution-policy';
 import { settleWithin } from '../internals/drain';
+import { getLogger } from '../logger';
 import {
     getSchedulerJobDuration,
     getSchedulerJobExecutedTotal,
@@ -60,6 +62,7 @@ type ScheduledEntry =
           cron: string;
           action: ScheduledAction;
           intervalMs: number;
+          timeoutMs: ExecutionDeadlineMs;
           timer?: ReturnType<typeof setInterval>;
       }
     | {
@@ -68,11 +71,18 @@ type ScheduledEntry =
           action: ScheduledAction;
           expr: CronExpression;
           target: number;
+          timeoutMs: ExecutionDeadlineMs;
           timer?: ReturnType<typeof setTimeout>;
       };
 
 /** Constructor options for {@link NodeSchedulerAdapter}. */
 export interface NodeSchedulerAdapterConfig {
+    /**
+     * Default execution policy (A21) for entries registered without their own
+     * `timeoutMs` option: a positive integer ms deadline or explicit `null` =
+     * unlimited. Invalid values throw at construction.
+     */
+    readonly timeoutMs?: number | null;
     /**
      * Upper bound (ms) on how long `stop()` waits for an in-flight tick to settle.
      * A hung action is abandoned at this deadline so it cannot block shutdown.
@@ -98,6 +108,7 @@ export interface NodeSchedulerAdapterConfig {
 export class NodeSchedulerAdapter implements SchedulerAdapter {
     private readonly entries: ScheduledEntry[] = [];
     private readonly drainTimeoutMs: number;
+    private readonly defaultTimeoutMs: ExecutionDeadlineMs;
     private readonly now: () => number;
     private running = false;
     private readonly inflight = new Set<Promise<void>>();
@@ -110,30 +121,39 @@ export class NodeSchedulerAdapter implements SchedulerAdapter {
             );
         }
         this.drainTimeoutMs = drainTimeoutMs ?? 30_000;
+        this.defaultTimeoutMs = resolveExecutionTimeoutMs('NodeSchedulerAdapter', config.timeoutMs ?? undefined);
         this.now = now ?? (() => Date.now());
     }
 
-    register(cron: string, action: ScheduledAction): void {
+    register(cron: string, action: ScheduledAction, options?: { timeoutMs?: number | null }): void {
         // Fail at registration time: an unsupported expression must never reach
         // start(), where it would otherwise create a silently-wrong interval
         // (task 0060 F7) or a never-firing cron (task 0734 R1).
-        const entry = this.parseEntry(cron, action);
+        const entry = this.parseEntry(cron, action, options);
         this.entries.push(entry);
         if (this.running) {
             this.startEntry(entry);
         }
     }
 
-    private parseEntry(cron: string, action: ScheduledAction): ScheduledEntry {
+    private parseEntry(cron: string, action: ScheduledAction, options?: { timeoutMs?: number | null }): ScheduledEntry {
+        // Resolve the entry's execution policy now: an explicit option (including
+        // explicit null) wins, absence inherits the adapter default. Invalid
+        // options throw here rather than leaving a tick to discover it mid-flight.
+        const timeoutMs = resolveExecutionTimeoutMs(
+            `scheduler entry "${cron}"`,
+            options?.timeoutMs,
+            this.defaultTimeoutMs,
+        );
         const intervalMs = parseInterval(cron);
         if (intervalMs !== undefined) {
-            return { kind: 'interval', cron, action, intervalMs };
+            return { kind: 'interval', cron, action, intervalMs, timeoutMs };
         }
         // Real five-field cron. Validate and verify a next occurrence exists at
         // registration (bounded scan) so an unsatisfiable expression fails here.
         const expr = parseCronExpression(cron);
         const target = nextCronTime(expr, this.now()).getTime();
-        return { kind: 'cron', cron, action, expr, target };
+        return { kind: 'cron', cron, action, expr, target, timeoutMs };
     }
 
     async start(): Promise<void> {
@@ -247,7 +267,20 @@ export class NodeSchedulerAdapter implements SchedulerAdapter {
         const startMs = performance.now();
         getSchedulerJobExecutedTotal().add(1, { cron: entry.cron });
         try {
-            await entry.action();
+            // One shared deadline clock per tick (A21): expiry aborts the
+            // context and the action is always awaited to settlement. Timeout
+            // counts as a failure; the adapter keeps ticking.
+            const outcome = await runWithExecutionDeadline(entry.action, { timeoutMs: entry.timeoutMs });
+            if (outcome.timedOut) {
+                getSchedulerJobFailedTotal().add(1, { cron: entry.cron });
+                getLogger('scheduler').warn('scheduled tick exceeded its execution deadline', {
+                    cron: entry.cron,
+                    timeoutMs: entry.timeoutMs,
+                    elapsedMs: Math.round(outcome.elapsedMs),
+                });
+            } else if (outcome.outcome === 'error') {
+                getSchedulerJobFailedTotal().add(1, { cron: entry.cron });
+            }
         } catch {
             // Swallow — scheduler errors should not crash the process
             getSchedulerJobFailedTotal().add(1, { cron: entry.cron });

package/src/scheduler/types.ts

@@ -2,8 +2,25 @@
  * Scheduler types and interface.
  */
 
-/** Signature for scheduled action handlers. */
-export type ScheduledAction = () => Promise<void>;
+import type { ExecutionContext } from '../execution-policy';
+
+/**
+ * Signature for scheduled action handlers. The context carries the shared
+ * execution-deadline clock for this tick (A21); zero-argument handlers stay
+ * assignable — notably the Cloudflare adapter, which invokes actions with an
+ * unlimited execution context (no wall-clock deadline on that runtime).
+ */
+export type ScheduledAction = (context: ExecutionContext) => Promise<void>;
+
+/** Per-entry execution policy options for {@link SchedulerAdapter.register}. */
+export interface ScheduledActionOptions {
+    /**
+     * Execution policy for this entry's ticks: a positive integer ms deadline,
+     * explicit `null` = unlimited, omitted = inherit the adapter default.
+     * Invalid explicit values throw at registration time.
+     */
+    timeoutMs?: number | null;
+}
 
 /**
  * Abstract scheduler interface — implementations for Node and Cloudflare.
@@ -13,7 +30,7 @@ export type ScheduledAction = () => Promise<void>;
  * action is abandoned at the deadline rather than blocking shutdown forever.
  */
 export interface SchedulerAdapter {
-    register(cron: string, action: ScheduledAction): void;
+    register(cron: string, action: ScheduledAction, options?: ScheduledActionOptions): void;
     start(): Promise<void>;
     stop(): Promise<void>;
 }
@@ -28,5 +45,17 @@ export interface SchedulerAdapter {
  * command handler.
  */
 export type SchedulerJobConfig =
-    | { readonly name: string; readonly command: string; readonly intervalMinutes: number; readonly cron?: never }
-    | { readonly name: string; readonly command: string; readonly cron: string; readonly intervalMinutes?: never };
+    | {
+          readonly name: string;
+          readonly command: string;
+          readonly intervalMinutes: number;
+          readonly cron?: never;
+          readonly timeoutMs?: number | null;
+      }
+    | {
+          readonly name: string;
+          readonly command: string;
+          readonly cron: string;
+          readonly intervalMinutes?: never;
+          readonly timeoutMs?: number | null;
+      };

package/src/scheduler/wrap-handler.ts

@@ -1,5 +1,6 @@
 import type { EventBus } from '../event-bus/event-bus';
 import type { SchedulerEvents } from '../events';
+import type { ExecutionContext } from '../execution-policy';
 import { addSpanAttributes, addSpanEvent, traceAsync } from '../telemetry/tracing';
 import type { ScheduledAction } from './types';
 
@@ -25,7 +26,7 @@ export function wrapScheduledHandler(
     action: ScheduledAction,
     systemBus?: EventBus<SchedulerEvents> | null,
 ): ScheduledAction {
-    return async () => {
+    return async (context: ExecutionContext) => {
         const startTime = performance.now();
 
         return traceAsync('scheduler.job', async (span) => {
@@ -33,7 +34,7 @@ export function wrapScheduledHandler(
 
             let execError: string | undefined;
             try {
-                await action();
+                await action(context);
             } catch (error) {
                 execError = error instanceof Error ? error.message : String(error);
                 addSpanEvent('scheduler.job.error', { 'scheduler.error': execError });