@gobing-ai/ts-infra 0.4.13 → 0.4.15

package/README.md

@@ -247,6 +247,8 @@ const queue = new DBJobQueue<{ to: string; subject: string }>(dao);
 await queue.enqueue(
     'send-email',
     { to: 'alice@example.com', subject: 'Welcome' },
+    // maxRetries is a total attempt budget, not retries after the first:
+    // 5 means up to 5 attempts, and `maxRetries: 1` runs the job once with no retry.
     { maxRetries: 5, delay: 1_000, ttlMs: 86_400_000 },
 );
 
@@ -271,6 +273,8 @@ const processed = await consumer.processOnce();
 
 The consumer claims ready jobs, resets stuck processing jobs after the visibility timeout, retries failed jobs with exponential backoff, and marks expired jobs failed through `QueueJobDao`. Corrupt payloads are failed individually without rejecting the batch. Poll-cycle errors are logged and retried on the next cycle — a single DAO hiccup will not crash the process.
 
+`stop()` drains gracefully: it stops polling, then waits for work already in flight — including a poll cycle that has claimed nothing yet — before resolving. The wait is capped by `drainTimeoutMs` (default 30s) so a stuck handler cannot block shutdown; when the cap is hit, `queue.consumer.stopped` reports `drained: false` with the outstanding `inFlightAtStop` count.
+
 **Queue lifecycle events** are opt-in through the injected `EventBus`:
 
 ```ts

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

@@ -1 +1 @@
-{"version":3,"file":"application-node.d.ts","sourceRoot":"","sources":["../src/application-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,OAAO,KAAK,EACR,2BAA2B,EAC3B,uBAAuB,EAEvB,kBAAkB,EAClB,qBAAqB,EAGrB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EACnB,MAAM,qBAAqB,CAAC;AAM7B,kGAAkG;AAClG,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B;AAgHD;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACnE,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW;IAChG,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAC5D,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,cAAc,CAAC;QACzB,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAChC,SAAS,CAAC,EAAE,6BAA6B,CAAC;QAC1C,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAChC,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC;IACjF,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvF,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,CACZ,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,EAC5C,MAAM,EAAE,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EACjG,OAAO,EAAE,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,GACrD,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAgIlD"}
+{"version":3,"file":"application-node.d.ts","sourceRoot":"","sources":["../src/application-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,OAAO,KAAK,EACR,2BAA2B,EAC3B,uBAAuB,EAEvB,kBAAkB,EAClB,qBAAqB,EAGrB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EACnB,MAAM,qBAAqB,CAAC;AAM7B,kGAAkG;AAClG,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B;AAgHD;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACnE,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW;IAChG,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAC5D,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,cAAc,CAAC;QACzB,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAChC,SAAS,CAAC,EAAE,6BAA6B,CAAC;QAC1C,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAChC,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC;IACjF,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvF,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,CACZ,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,EAC5C,MAAM,EAAE,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EACjG,OAAO,EAAE,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,GACrD,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAuIlD"}

package/dist/application-node.js

@@ -169,12 +169,19 @@ export async function runNodeApplication(options) {
     const logFilePath = yamlBootstrap.logging?.filePath;
     const loggingConfig = 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 = {};
-    const rawSched = { ...schedulerOpts };
-    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 ──────────────────────────────────────────────
     const plugins = [];

package/dist/events.d.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.
@@ -21,21 +25,76 @@ export interface DbConnectionErrorDetail {
     /** Adapter type (e.g. 'sqlite', 'd1'). */
     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`. */
 export interface SchedulerJobExecutedDetail {
@@ -64,19 +123,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/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIpD,yCAAyC;AACzC,MAAM,WAAW,uBAAuB;IACpC,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,0BAA0B;IACvC,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACjB;AAID,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG;IACnB,uCAAuC;IACvC,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,iCAAiC;IACjC,qBAAqB,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;CACpE,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG;IACtB,8BAA8B;IAC9B,oBAAoB,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,qCAAqC;IACrC,wBAAwB,EAAE,MAAM,IAAI,CAAC;IACrC,wBAAwB;IACxB,wBAAwB,EAAE,MAAM,IAAI,CAAC;IACrC,oCAAoC;IACpC,qBAAqB,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACzE,yDAAyD;IACzD,kBAAkB,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC3D,2CAA2C;IAC3C,oBAAoB,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAC/D,oDAAoD;IACpD,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG;IAC1B,yDAAyD;IACzD,wBAAwB,EAAE,CAAC,MAAM,EAAE,0BAA0B,KAAK,IAAI,CAAC;CAC1E,CAAC;AAEF,yBAAyB;AACzB,MAAM,MAAM,eAAe,GAAG;IAC1B,wDAAwD;IACxD,mBAAmB,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAChE,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -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.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { APIClient, type APIClientConfig, APIError, type RawHttpResponse, type RawRequestOptions, type RequestOptions, } from './api-client';
 export { type AsyncEventJobPayload, attachDefaultObservers, attachFileObserver, attachLogObserver, attachTelemetryObserver, type BusLifecycleEvents, createLifecycleBus, EventBus, type EventMap, type FileObserverWriter, type SubscribeOptions, } from './event-bus/index';
-export type { ApiClientEvents, ApiRequestErrorDetail, DbConnectionErrorDetail, DbEvents, InfraEvents, QueueEvents, QueueJobFailedDetail, QueueJobRetryingDetail, SchedulerEvents, SchedulerJobExecutedDetail, } from './events';
+export type { ApiClientEvents, ApiRequestErrorDetail, DbConnectionErrorDetail, DbEvents, InfraEvents, QueueConsumerStartedDetail, QueueConsumerStoppedDetail, QueueEvents, QueueJobCompletedDetail, QueueJobEnqueuedDetail, QueueJobFailedDetail, QueueJobRef, QueueJobRetryingDetail, SchedulerEvents, SchedulerJobExecutedDetail, } from './events';
 export type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig, QueueStats, } from './job-queue/index';
 export { getLogger, type InitLoggerOptions, initializeLogger, type Logger, type LogLevel, setLoggerMuted, } from './logger';
 export { ActionRegistry, type CreateDefaultRegistryOptions, createDefaultRegistry, HealthPingAction, type HealthPingWriter, initScheduler, LogAction, NoopSchedulerAdapter, QueueStatsAction, type QueueStatsDaoProvider, type ScheduledAction, type SchedulerAction, type SchedulerAdapter, toScheduledAction, wrapScheduledHandler, } from './scheduler/index';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,SAAS,EACT,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACR,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,QAAQ,EACR,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,0BAA0B,GAC7B,MAAM,UAAU,CAAC;AAElB,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACH,SAAS,EACT,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,cAAc,GACjB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACH,cAAc,EACd,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,GACX,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,SAAS,EACT,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACR,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,QAAQ,EACR,WAAW,EACX,0BAA0B,EAC1B,0BAA0B,EAC1B,WAAW,EACX,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,0BAA0B,GAC7B,MAAM,UAAU,CAAC;AAElB,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACH,SAAS,EACT,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,cAAc,GACjB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACH,cAAc,EACd,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,GACX,MAAM,mBAAmB,CAAC"}

package/dist/internals/drain.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare function settleWithin(promise: Promise<void>, deadline: number): Promise<void>;
+//# sourceMappingURL=drain.d.ts.map

package/dist/internals/drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../src/internals/drain.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpF"}

package/dist/internals/drain.js

@@ -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, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        return Promise.resolve();
+    const { promise: settled, resolve } = Promise.withResolvers();
+    const timer = setTimeout(resolve, remaining);
+    const done = () => {
+        clearTimeout(timer);
+        resolve();
+    };
+    promise.then(done, done);
+    return settled;
+}

package/dist/job-queue/db-job-queue.d.ts

@@ -29,6 +29,7 @@ export declare class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private timer;
     private running;
     private inFlight;
+    private pollPromise;
     constructor(dao: QueueJobDao, config?: QueueConsumerConfig);
     register(type: string, handler: JobHandler<T>): void;
     start(): Promise<void>;

package/dist/job-queue/db-job-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-job-queue.d.ts","sourceRoot":"","sources":["../../src/job-queue/db-job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAS7C,OAAO,KAAK,EAAE,cAAc,EAAO,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQ7G,kFAAkF;AAClF,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IAEnD,QAAQ,CAAC,GAAG,EAAE,WAAW;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBADf,GAAG,EAAE,WAAW,EACR,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,YAAA;IAG7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAW3F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;CAGrC;AAED,qFAAqF;AACrF,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAe7D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAdxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;gBAGA,GAAG,EAAE,WAAW,EACjC,MAAM,GAAE,mBAAwB;IAYpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAI9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAerB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAIlC,sFAAsF;IAChF,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IA4BpC,OAAO,CAAC,QAAQ;YAMF,IAAI;YAgBJ,UAAU;YAqCV,WAAW;CA4B5B"}
+{"version":3,"file":"db-job-queue.d.ts","sourceRoot":"","sources":["../../src/job-queue/db-job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAER,WAAW,EAKd,MAAM,WAAW,CAAC;AAUnB,OAAO,KAAK,EAAE,cAAc,EAAO,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQ7G,kFAAkF;AAClF,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IAEnD,QAAQ,CAAC,GAAG,EAAE,WAAW;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBADf,GAAG,EAAE,WAAW,EACR,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,YAAA;IAG7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAY3F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;CAGrC;AAcD,qFAAqF;AACrF,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAgB7D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAfxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAA8B;gBAG5B,GAAG,EAAE,WAAW,EACjC,MAAM,GAAE,mBAAwB;IAYpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAI9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCrB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAIlC,sFAAsF;IAChF,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IA4BpC,OAAO,CAAC,QAAQ;YAWF,IAAI;YAgBJ,UAAU;YA6CV,WAAW;CAmC5B"}

package/dist/job-queue/db-job-queue.js

@@ -1,3 +1,4 @@
+import { settleWithin } from '../internals/drain.js';
 import { getLogger } from '../logger.js';
 import { getQueueJobCompletedTotal, getQueueJobEnqueuedTotal, getQueueJobFailedTotal, getQueueJobProcessingDuration, } from '../telemetry/metrics.js';
 import { addSpanAttributes, traceAsync } from '../telemetry/tracing.js';
@@ -18,7 +19,7 @@ export class DBJobQueue {
     async enqueue(type, payload, options) {
         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;
     }
     async enqueueBatch(jobs) {
@@ -26,7 +27,8 @@ export class DBJobQueue {
         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;
@@ -35,6 +37,20 @@ export class DBJobQueue {
         return this.dao.getStats();
     }
 }
+/**
+ * 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, type, options) {
+    const detail = { 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 {
     dao;
@@ -50,6 +66,7 @@ export class DBQueueConsumer {
     timer = null;
     running = false;
     inFlight = 0;
+    pollPromise = null;
     constructor(dao, config = {}) {
         this.dao = dao;
         this.pollInterval = nonNegativeFiniteConfig('pollInterval', config.pollInterval ?? 1_000);
@@ -69,7 +86,13 @@ export class DBQueueConsumer {
             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() {
         const wasRunning = this.running;
@@ -79,11 +102,27 @@ export class DBQueueConsumer {
             this.timer = null;
         }
         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 = {
+                stoppedAt: Date.now(),
+                drainTimeoutMs: this.drainTimeoutMs,
+                inFlightAtStop: this.inFlight,
+                drained: this.inFlight === 0,
+            };
+            await this.events?.emit('queue.consumer.stopped', detail);
+        }
     }
     async stats() {
         return this.dao.getStats();
@@ -114,7 +153,13 @@ export class DBQueueConsumer {
     }
     schedule(delay) {
         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);
     }
     async poll() {
@@ -144,7 +189,7 @@ export class DBQueueConsumer {
         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 () => {
@@ -155,46 +200,60 @@ export class DBQueueConsumer {
             });
             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;
             }
             const startMs = performance.now();
             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 = {
+                    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);
             }
         });
     }
-    async failOrRetry(job, error) {
+    async failOrRetry(job, error, durationMs) {
         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 = {
                 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 = {
             jobId: job.id,
             type: job.type,
             attempt: attempts,
+            maxRetries: job.maxRetries,
             nextRetryAt,
-        });
+            error: message,
+        };
+        await this.events?.emit('queue.job.retrying', retrying);
     }
 }
 function toJob(record) {
@@ -213,7 +272,9 @@ function toJob(record) {
     };
 }
 function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    const { promise, resolve } = Promise.withResolvers();
+    setTimeout(resolve, ms);
+    return promise;
 }
 function positiveIntegerConfig(name, value) {
     if (!Number.isInteger(value) || value <= 0) {

package/dist/job-queue/types.d.ts

@@ -13,6 +13,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;
@@ -22,6 +23,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;
@@ -52,11 +54,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>;
 }
@@ -64,6 +69,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/dist/job-queue/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/job-queue/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,yEAAyE;AACzE,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAED,iDAAiD;AACjD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/job-queue/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,yEAAyE;AACzE,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAED,iDAAiD;AACjD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC"}

package/dist/scheduler/cloudflare.d.ts

@@ -18,6 +18,13 @@ export declare class CloudflareSchedulerAdapter implements SchedulerAdapter {
     constructor();
     register(cron: string, action: ScheduledAction): void;
     start(): Promise<void>;
+    /**
+     * 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).
+     */
     stop(): Promise<void>;
     /**
      * Handle a Cloudflare Workers Cron Trigger event.

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

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/scheduler/cloudflare.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,UAAU,gBAAgB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,UAAU,cAAc;IACpB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,gBAAgB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;;IAI9D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAI/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;CAmB3E"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/scheduler/cloudflare.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,UAAU,gBAAgB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,UAAU,cAAc;IACpB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,gBAAgB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;;IAI9D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAI/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;CAmB3E"}

package/dist/scheduler/cloudflare.js

@@ -19,6 +19,13 @@ export class CloudflareSchedulerAdapter {
         // Cloudflare Workers use cron triggers defined in wrangler.toml.
         // 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() {
         this.entries.clear();
     }