@gobing-ai/ts-infra 0.4.13 → 0.4.15

package/dist/scheduler/node.d.ts

@@ -1,12 +1,31 @@
+/**
+ * Node.js scheduler adapter using a simple setInterval-based approach.
+ * No external cron library dependency — cron expressions are parsed minimally.
+ */
 import type { ScheduledAction, SchedulerAdapter } from './types';
+/** Constructor options for {@link NodeSchedulerAdapter}. */
+export interface NodeSchedulerAdapterConfig {
+    /**
+     * 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.
+     * Defaults to 30000 (matching `DBQueueConsumer`).
+     */
+    readonly drainTimeoutMs?: number;
+}
 /**
  * Scheduler adapter for Node.js using a setInterval-based approach.
  * No external cron library dependency — cron expressions are parsed minimally.
+ *
+ * `stop()` drains in-flight ticks, bounded by `drainTimeoutMs` (ADR-024): an
+ * action already running when `stop()` is called is awaited rather than torn
+ * down, which would leave a half-written row or a half-flushed batch.
  */
 export declare class NodeSchedulerAdapter implements SchedulerAdapter {
     private readonly entries;
+    private readonly drainTimeoutMs;
     private running;
-    constructor();
+    private readonly inflight;
+    constructor(config?: NodeSchedulerAdapterConfig);
     register(cron: string, action: ScheduledAction): void;
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/scheduler/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/scheduler/node.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAoCjE;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,OAAO,CAAS;;IAIxB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAU/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,OAAO,CAAC,UAAU;YAOJ,gBAAgB;CAYjC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/scheduler/node.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAoCjE,4DAA4D;AAC5D,MAAM,WAAW,0BAA0B;IACvC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;gBAEzC,MAAM,GAAE,0BAA+B;IAUnD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAU/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,OAAO,CAAC,UAAU;YAiBJ,gBAAgB;CAYjC"}

package/dist/scheduler/node.js

@@ -2,6 +2,7 @@
  * Node.js scheduler adapter using a simple setInterval-based approach.
  * No external cron library dependency — cron expressions are parsed minimally.
  */
+import { settleWithin } from '../internals/drain.js';
 import { getLogger } from '../logger.js';
 import { getSchedulerJobDuration, getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal, } from '../telemetry/metrics.js';
 /** Simple helper to parse cron-like interval strings into milliseconds. */
@@ -34,11 +35,23 @@ function parseInterval(cron) {
 /**
  * Scheduler adapter for Node.js using a setInterval-based approach.
  * No external cron library dependency — cron expressions are parsed minimally.
+ *
+ * `stop()` drains in-flight ticks, bounded by `drainTimeoutMs` (ADR-024): an
+ * action already running when `stop()` is called is awaited rather than torn
+ * down, which would leave a half-written row or a half-flushed batch.
  */
 export class NodeSchedulerAdapter {
     entries = [];
+    drainTimeoutMs;
     running = false;
-    constructor() { }
+    inflight = new Set();
+    constructor(config = {}) {
+        const { drainTimeoutMs } = config;
+        if (drainTimeoutMs !== undefined && (!Number.isFinite(drainTimeoutMs) || drainTimeoutMs < 0)) {
+            throw new RangeError(`NodeSchedulerAdapter drainTimeoutMs must be a non-negative finite number; received ${drainTimeoutMs}`);
+        }
+        this.drainTimeoutMs = drainTimeoutMs ?? 30_000;
+    }
     register(cron, action) {
         this.entries.push({ cron, action });
         if (this.running) {
@@ -64,12 +77,30 @@ export class NodeSchedulerAdapter {
                 entry.timer = undefined;
             }
         }
+        // Drain in-flight ticks, bounded by a shared absolute deadline. clearInterval
+        // cancels future ticks but not one already executing; without this wait a tick
+        // mid-action when stop() is called would keep running after stop() resolves,
+        // tearing down a half-written row or half-flushed batch (ADR-024).
+        const deadline = Date.now() + this.drainTimeoutMs;
+        for (const p of [...this.inflight]) {
+            await settleWithin(p, deadline);
+        }
     }
     startEntry(entry) {
         if (entry.timer)
             return;
         const interval = parseInterval(entry.cron);
-        entry.timer = setInterval(this._onScheduledTick.bind(this, entry), interval);
+        // setInterval discards the async handler's returned promise, so capture it
+        // here for stop() to drain. _onScheduledTick never rejects (try/catch),
+        // so the cleanup runs on both paths with no unhandled-rejection risk.
+        entry.timer = setInterval(() => {
+            const tick = this._onScheduledTick(entry);
+            this.inflight.add(tick);
+            const cleanup = () => {
+                this.inflight.delete(tick);
+            };
+            tick.then(cleanup, cleanup);
+        }, interval);
     }
     async _onScheduledTick(entry) {
         const startMs = performance.now();

package/dist/scheduler/types.d.ts

@@ -3,7 +3,13 @@
  */
 /** Signature for scheduled action handlers. */
 export type ScheduledAction = () => Promise<void>;
-/** Abstract scheduler interface — implementations for Node (node-cron) and Cloudflare. */
+/**
+ * Abstract scheduler interface — implementations for Node and Cloudflare.
+ *
+ * `stop()` cancels future ticks and drains any currently-executing tick,
+ * bounded by an implementation-configured timeout (see ADR-024). A stuck
+ * action is abandoned at the deadline rather than blocking shutdown forever.
+ */
 export interface SchedulerAdapter {
     register(cron: string, action: ScheduledAction): void;
     start(): Promise<void>;

package/dist/scheduler/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/scheduler-node.d.ts

@@ -1,2 +1,2 @@
-export { NodeSchedulerAdapter } from './scheduler/node';
+export { NodeSchedulerAdapter, type NodeSchedulerAdapterConfig } from './scheduler/node';
 //# sourceMappingURL=scheduler-node.d.ts.map

package/dist/scheduler-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler-node.d.ts","sourceRoot":"","sources":["../src/scheduler-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"scheduler-node.d.ts","sourceRoot":"","sources":["../src/scheduler-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,KAAK,0BAA0B,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.4.13",
+    "version": "0.4.15",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -78,12 +78,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.13",
+        "@gobing-ai/ts-utils": "^0.4.15",
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.13",
-        "@gobing-ai/ts-runtime": "^0.4.13",
+        "@gobing-ai/ts-db": "^0.4.15",
+        "@gobing-ai/ts-runtime": "^0.4.15",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -116,8 +116,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.13",
-        "@gobing-ai/ts-runtime": "^0.4.13",
+        "@gobing-ai/ts-db": "^0.4.15",
+        "@gobing-ai/ts-runtime": "^0.4.15",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/application-node.ts

@@ -265,12 +265,19 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
         typeof logFilePath === 'string' ? { ...loggingOpts, fileSink: createFileSink(logFilePath) } : loggingOpts;
 
     // ── Scheduler adapter ───────────────────────────────────────────────
+    // Honour a caller-supplied `SchedulerOptions.adapter` (documented injection
+    // point, application/types.ts:82) instead of unconditionally overwriting
+    // it. Only default-construct a NodeSchedulerAdapter when none was provided.
+    // `drainTimeoutMs` (ADR-024) is reachable by passing a pre-built adapter;
+    // the auto-wired default keeps the 30000 ms bound (CHANGELOG.md:16).
     const schedulerConfig: SchedulerOptions = {};
-    const rawSched = { ...schedulerOpts } as Record<string, unknown>;
-    if (rawSched.enabled === true) {
+    if (schedulerOpts.enabled === true) {
         schedulerConfig.enabled = true;
         schedulerConfig.autoStart = schedulerOpts.autoStart;
-        schedulerConfig.adapter = new NodeSchedulerAdapter();
+        schedulerConfig.adapter = schedulerOpts.adapter ?? new NodeSchedulerAdapter();
+        if (schedulerOpts.entries) {
+            schedulerConfig.entries = schedulerOpts.entries;
+        }
     }
 
     // ── Node-owned plugins ──────────────────────────────────────────────

package/src/events.ts

@@ -1,14 +1,18 @@
 /**
  * Infrastructure-level event definitions for ts-infra observability.
  *
- * Mirrors the package-local pattern in `@gobing-ai/ts-ai-runner` (`events.ts`):
- * these maps define the infra-level event *contract*. ts-infra itself currently
- * emits only `queue.stats` (`QueueStatsAction`) and `scheduler.job.executed`
- * (`wrapScheduledHandler`); the remaining events are contracts for the consuming
- * app or higher-level wiring to emit on the same bus. Application-domain events
- * (history import, HTTP server, …) belong to the consuming app, not this
- * library. Process events belong to `@gobing-ai/ts-runtime` (the owner of
- * `ProcessExecutor`) and are intentionally not re-exported here.
+ * These maps define the infra-level event *contract* for the consumers of
+ * `@gobing-ai/ts-infra`. ts-infra emits `queue.*` (DBJobQueue / DBQueueConsumer),
+ * `scheduler.job.executed` (`wrapScheduledHandler`), and `db.connection.error`
+ * (DB wiring). Application-domain events (history import, HTTP server, …) belong
+ * to the consuming app, not this library. Process events belong to
+ * `@gobing-ai/ts-runtime` (the owner of `ProcessExecutor`) and are intentionally
+ * not re-exported here.
+ *
+ * **Metadata-only invariant:** every `queue.*` detail object is correlator-grade —
+ * it carries job identity, timing, and retry counters only, and NEVER embeds the
+ * job business payload `T` (which may contain prompts, tokens, PII, or large
+ * blobs). Inspect job bodies via the Jobs DAO when needed.
  *
  * Consume via `EventBus<InfraEvents>` or compose individual maps into a wider
  * app event map.
@@ -26,22 +30,82 @@ export interface DbConnectionErrorDetail {
     adapter: string;
 }
 
-/** Payload for `queue.job.failed` — a job exhausted retries. */
-export interface QueueJobFailedDetail {
+/** Shared job identity correlators present on every `queue.job.*` event. */
+export interface QueueJobRef {
+    /** Job id. */
     jobId: string;
+    /** Job type (the handler registration key). */
     type: string;
+}
+
+/** Payload for `queue.job.enqueued` — a new job was added to the queue. */
+export interface QueueJobEnqueuedDetail extends QueueJobRef {
+    /** Epoch ms when the job was enqueued. */
+    enqueuedAt: number;
+    /** Max retry count from `EnqueueOptions.maxRetries`, when supplied. */
+    maxRetries?: number;
+    /** Requested delay before the job becomes ready (ms), from `EnqueueOptions.delay`. */
+    delayMs?: number;
+    /** Job TTL in ms, from `EnqueueOptions.ttlMs`. */
+    ttlMs?: number;
+}
+
+/** Payload for `queue.consumer.started` — the polling loop began. */
+export interface QueueConsumerStartedDetail {
+    /** Epoch ms when the consumer was started. */
+    startedAt: number;
+    /** Polling interval in ms. */
+    pollInterval: number;
+    /** Claim batch size per poll cycle. */
+    batchSize: number;
+    /** Maximum concurrent in-flight handlers. */
+    maxConcurrency: number;
+    /** Visibility-timeout window in ms. */
+    visibilityTimeout: number;
+}
+
+/** Payload for `queue.consumer.stopped` — the polling loop was halted. */
+export interface QueueConsumerStoppedDetail {
+    /** Epoch ms when `stop()` was called. */
+    stoppedAt: number;
+    /** Drain deadline in ms applied to in-flight handlers at stop time. */
+    drainTimeoutMs: number;
+    /** In-flight handler count observed at stop time. */
+    inFlightAtStop: number;
+    /** `true` when all in-flight handlers completed within the drain deadline. */
+    drained: boolean;
+}
+
+/** Payload for `queue.job.completed` — a job ran to success. */
+export interface QueueJobCompletedDetail extends QueueJobRef {
+    /** Handler wall-clock duration in ms. */
+    durationMs: number;
+    /** Attempts counter on the job row at success (0 on the first successful run). */
+    attempt: number;
+}
+
+/** Payload for `queue.job.failed` — a job exhausted retries. */
+export interface QueueJobFailedDetail extends QueueJobRef {
+    /** Error message from the final attempt. */
     error: string;
-    /** Attempt number (0-indexed, incremented after each failure). */
+    /** 1-based attempt number of the failure. */
     attempt: number;
+    /** Maximum retry count configured for the job. */
+    maxRetries: number;
+    /** Handler wall-clock duration in ms, when measured at the failing attempt. */
+    durationMs?: number;
 }
 
 /** Payload for `queue.job.retrying` — a job will be retried after backoff. */
-export interface QueueJobRetryingDetail {
-    jobId: string;
-    type: string;
+export interface QueueJobRetryingDetail extends QueueJobRef {
+    /** 1-based attempt number of the failure that triggers this retry. */
     attempt: number;
+    /** Maximum retry count configured for the job. */
+    maxRetries: number;
     /** When the next retry will fire (epoch ms). */
     nextRetryAt: number;
+    /** Error message that caused this retry. */
+    error: string;
 }
 
 /** Payload for `scheduler.job.executed`. */
@@ -76,13 +140,13 @@ export type DbEvents = {
 /** Job-queue lifecycle events emitted by the queue and its consumer. */
 export type QueueEvents = {
     /** A new job was enqueued. */
-    'queue.job.enqueued': (detail: { jobId: string; type: string }) => void;
+    'queue.job.enqueued': (detail: QueueJobEnqueuedDetail) => void;
     /** Consumer polling loop started. */
-    'queue.consumer.started': () => void;
-    /** Consumer stopped. */
-    'queue.consumer.stopped': () => void;
+    'queue.consumer.started': (detail: QueueConsumerStartedDetail) => void;
+    /** Consumer polling loop stopped. */
+    'queue.consumer.stopped': (detail: QueueConsumerStoppedDetail) => void;
     /** A job completed successfully. */
-    'queue.job.completed': (detail: { jobId: string; type: string }) => void;
+    'queue.job.completed': (detail: QueueJobCompletedDetail) => void;
     /** A job exhausted retries and is permanently failed. */
     'queue.job.failed': (detail: QueueJobFailedDetail) => void;
     /** A job will be retried after backoff. */

package/src/index.ts

@@ -30,8 +30,13 @@ export type {
     DbConnectionErrorDetail,
     DbEvents,
     InfraEvents,
+    QueueConsumerStartedDetail,
+    QueueConsumerStoppedDetail,
     QueueEvents,
+    QueueJobCompletedDetail,
+    QueueJobEnqueuedDetail,
     QueueJobFailedDetail,
+    QueueJobRef,
     QueueJobRetryingDetail,
     SchedulerEvents,
     SchedulerJobExecutedDetail,

package/src/internals/drain.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal drain primitives shared by adapters that bound a shutdown wait on
+ * in-flight work (DB queue consumer, Node scheduler).
+ *
+ * WHY: two adapters had near-identical "await this in-flight thing but not
+ * forever" logic. Centralizing the bound keeps the two shapes from drifting
+ * and documents the contract once. Not re-exported from the package barrel —
+ * consumers depend on adapter behaviour, not this helper.
+ */
+
+/**
+ * Resolve when `promise` settles or when `deadline` passes, whichever comes first.
+ *
+ * Never rejects: a rejected promise ends the wait the same way a fulfilled one
+ * does. `deadline` is an absolute epoch-ms timestamp (not a duration) so a single
+ * bound can be shared across several awaited promises without compounding.
+ */
+export function settleWithin(promise: Promise<void>, deadline: number): Promise<void> {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return Promise.resolve();
+    const { promise: settled, resolve } = Promise.withResolvers<void>();
+    const timer = setTimeout(resolve, remaining);
+    const done = (): void => {
+        clearTimeout(timer);
+        resolve();
+    };
+    promise.then(done, done);
+    return settled;
+}

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

@@ -1,6 +1,14 @@
 import type { QueueJobDao, QueueJobRecord, QueueStats } from '@gobing-ai/ts-db';
 import type { EventBus } from '../event-bus/event-bus';
-import type { QueueEvents } from '../events';
+import type {
+    QueueConsumerStoppedDetail,
+    QueueEvents,
+    QueueJobCompletedDetail,
+    QueueJobEnqueuedDetail,
+    QueueJobFailedDetail,
+    QueueJobRetryingDetail,
+} from '../events';
+import { settleWithin } from '../internals/drain';
 import { getLogger, type Logger } from '../logger';
 import {
     getQueueJobCompletedTotal,
@@ -27,7 +35,7 @@ export class DBJobQueue<T = unknown> implements JobQueue<T> {
     async enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string> {
         const id = await this.dao.enqueue(type, payload, options);
         getQueueJobEnqueuedTotal().add(1, { type });
-        await this.events?.emit('queue.job.enqueued', { jobId: id, type });
+        await this.events?.emit('queue.job.enqueued', enqueuedDetail(id, type, options));
         return id;
     }
 
@@ -36,7 +44,8 @@ export class DBJobQueue<T = unknown> implements JobQueue<T> {
         getQueueJobEnqueuedTotal().add(jobs.length);
         if (this.events) {
             for (const [index, jobId] of ids.entries()) {
-                await this.events.emit('queue.job.enqueued', { jobId, type: jobs[index]?.type ?? 'unknown' });
+                const job = jobs[index];
+                await this.events.emit('queue.job.enqueued', enqueuedDetail(jobId, job?.type ?? 'unknown', job));
             }
         }
         return ids;
@@ -47,6 +56,18 @@ export class DBJobQueue<T = unknown> implements JobQueue<T> {
     }
 }
 
+/**
+ * Build the `queue.job.enqueued` correlator detail, filling optional retry/delay/TTL
+ * fields only when supplied. Shared by single and batch enqueue so both emit one shape.
+ */
+function enqueuedDetail(jobId: string, type: string, options: EnqueueOptions | undefined): QueueJobEnqueuedDetail {
+    const detail: QueueJobEnqueuedDetail = { jobId, type, enqueuedAt: Date.now() };
+    if (options && options.maxRetries !== undefined) detail.maxRetries = options.maxRetries;
+    if (options && options.delay !== undefined) detail.delayMs = options.delay;
+    if (options && options.ttlMs !== undefined) detail.ttlMs = options.ttlMs;
+    return detail;
+}
+
 /** DB-backed queue consumer with polling, retry, and visibility-timeout handling. */
 export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private readonly handlers = new Map<string, JobHandler<T>>();
@@ -61,6 +82,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private timer: ReturnType<typeof setTimeout> | null = null;
     private running = false;
     private inFlight = 0;
+    private pollPromise: Promise<void> | null = null;
 
     constructor(
         private readonly dao: QueueJobDao,
@@ -84,7 +106,13 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         if (this.running) return;
         this.running = true;
         this.schedule(0);
-        await this.events?.emit('queue.consumer.started');
+        await this.events?.emit('queue.consumer.started', {
+            startedAt: Date.now(),
+            pollInterval: this.pollInterval,
+            batchSize: this.batchSize,
+            maxConcurrency: this.maxConcurrency,
+            visibilityTimeout: this.visibilityTimeout,
+        });
     }
 
     async stop(): Promise<void> {
@@ -96,10 +124,29 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         }
 
         const deadline = Date.now() + this.drainTimeoutMs;
+
+        // Wait for an already-running poll cycle before consulting `inFlight`.
+        // `inFlight` is only incremented once claimReady() has resolved, so a stop()
+        // landing between the timer firing and that increment would see 0, exit the
+        // drain loop immediately, and report `drained: true` while the cycle went on
+        // to claim and process jobs after stop() resolved.
+        const pending = this.pollPromise;
+        if (pending !== null) {
+            await settleWithin(pending, deadline);
+        }
+
         while (this.inFlight > 0 && Date.now() < deadline) {
             await sleep(10);
         }
-        if (wasRunning) await this.events?.emit('queue.consumer.stopped');
+        if (wasRunning) {
+            const detail: QueueConsumerStoppedDetail = {
+                stoppedAt: Date.now(),
+                drainTimeoutMs: this.drainTimeoutMs,
+                inFlightAtStop: this.inFlight,
+                drained: this.inFlight === 0,
+            };
+            await this.events?.emit('queue.consumer.stopped', detail);
+        }
     }
 
     async stats(): Promise<QueueStats> {
@@ -137,7 +184,12 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
 
     private schedule(delay: number): void {
         this.timer = setTimeout(() => {
-            void this.poll();
+            // Retained so stop() can await the cycle it interrupts; poll() contains its
+            // own errors, so this promise settles rather than rejecting.
+            const cycle = this.poll().finally(() => {
+                if (this.pollPromise === cycle) this.pollPromise = null;
+            });
+            this.pollPromise = cycle;
         }, delay);
     }
 
@@ -164,7 +216,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);
+            await this.failOrRetry(record, error, 0);
             return;
         }
         return traceAsync('queue.job.process', async () => {
@@ -176,7 +228,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
 
             const handler = this.handlers.get(job.type);
             if (handler === undefined) {
-                await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`));
+                await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`), 0);
                 return;
             }
 
@@ -184,12 +236,20 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
             try {
                 await handler(job);
                 await this.dao.markCompleted(job.id);
+                const durationMs = performance.now() - startMs;
                 getQueueJobCompletedTotal().add(1, { type: job.type });
-                getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
-                await this.events?.emit('queue.job.completed', { jobId: job.id, type: job.type });
+                getQueueJobProcessingDuration().record(durationMs, { type: job.type });
+                const completed: QueueJobCompletedDetail = {
+                    jobId: job.id,
+                    type: job.type,
+                    durationMs: Number.isFinite(durationMs) ? durationMs : 0,
+                    attempt: job.attempts,
+                };
+                await this.events?.emit('queue.job.completed', completed);
             } catch (error) {
-                getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
-                await this.failOrRetry(job, error);
+                const durationMs = performance.now() - startMs;
+                getQueueJobProcessingDuration().record(durationMs, { type: job.type });
+                await this.failOrRetry(job, error, Number.isFinite(durationMs) ? durationMs : 0);
             }
         });
     }
@@ -197,30 +257,37 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private async failOrRetry(
         job: Pick<Job<T>, 'id' | 'type' | 'attempts' | 'maxRetries'>,
         error: unknown,
+        durationMs: number,
     ): 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);
             getQueueJobFailedTotal().add(1, { type: job.type });
-            await this.events?.emit('queue.job.failed', {
+            const failed: QueueJobFailedDetail = {
                 jobId: job.id,
                 type: job.type,
                 error: message,
                 attempt: attempts,
-            });
+                maxRetries: job.maxRetries,
+                durationMs,
+            };
+            await this.events?.emit('queue.job.failed', failed);
             return;
         }
 
         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.events?.emit('queue.job.retrying', {
+        const retrying: QueueJobRetryingDetail = {
             jobId: job.id,
             type: job.type,
             attempt: attempts,
+            maxRetries: job.maxRetries,
             nextRetryAt,
-        });
+            error: message,
+        };
+        await this.events?.emit('queue.job.retrying', retrying);
     }
 }
 
@@ -241,7 +308,9 @@ function toJob<T>(record: QueueJobRecord): Job<T> {
 }
 
 function sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    const { promise, resolve } = Promise.withResolvers<void>();
+    setTimeout(resolve, ms);
+    return promise;
 }
 
 function positiveIntegerConfig(name: string, value: number): number {

package/src/job-queue/types.ts

@@ -15,6 +15,7 @@ export interface Job<T = unknown> {
     payload: T;
     status: 'pending' | 'processing' | 'completed' | 'failed';
     attempts: number;
+    /** Total attempts allowed, not retries *after* the first — a job fails once `attempts >= maxRetries`. */
     maxRetries: number;
     createdAt: number;
     updatedAt: number;
@@ -25,6 +26,7 @@ export interface Job<T = unknown> {
 
 /** Options for enqueuing a job: retry policy, delay, and TTL. */
 export interface EnqueueOptions {
+    /** Total attempts allowed (default 3) — `maxRetries: 1` runs the job once with no retry. */
     maxRetries?: number;
     delay?: number;
     ttlMs?: number;
@@ -56,11 +58,14 @@ export interface QueueConsumerConfig {
     visibilityTimeout?: number;
     baseDelay?: number;
     maxDelay?: number;
+    /** Upper bound (ms, default 30_000) on how long `stop()` waits for in-flight work to drain. */
     drainTimeoutMs?: number;
     /**
-     * Optional bus for queue lifecycle events: `queue.consumer.started` /
-     * `queue.consumer.stopped` and `queue.job.completed` / `queue.job.failed` /
-     * `queue.job.retrying`. Omitting it leaves the consumer silent (default).
+     * Optional bus for queue lifecycle events with correlator-grade detail payloads:
+     * `queue.consumer.started` / `queue.consumer.stopped` (config snapshot + drain
+     * outcome), `queue.job.enqueued` / `queue.job.completed` / `queue.job.failed` /
+     * `queue.job.retrying`. Details carry job identity, timing, and retry counters
+     * only — never the business payload `T`. Omitting it leaves the consumer silent.
      */
     events?: EventBus<QueueEvents>;
 }
@@ -69,6 +74,11 @@ export interface QueueConsumerConfig {
 export interface QueueConsumer<T = unknown> {
     register(type: string, handler: JobHandler<T>): void;
     start(): Promise<void>;
+    /**
+     * 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.
+     */
     stop(): Promise<void>;
     stats(): Promise<QueueStats>;
 }

package/src/scheduler/cloudflare.ts

@@ -39,6 +39,13 @@ export class CloudflareSchedulerAdapter implements SchedulerAdapter {
         // The `scheduled()` handler should call `handleScheduledEvent()`.
     }
 
+    /**
+     * No-op drain. Cloudflare Workers fire Cron Triggers externally — this adapter
+     * owns no timer to cancel — and `handleScheduledEvent` already bounds each
+     * in-flight action via `ctx.waitUntil()`, the runtime's own drain. So there is
+     * nothing for stop() to await here; clearing registrations is the full contract
+     * (ADR-024).
+     */
     async stop(): Promise<void> {
         this.entries.clear();
     }