nuxt-cf-jobs 0.5.2 → 0.6.1

package/dist/cli/index.mjs

@@ -201,6 +201,22 @@ function forgetSql(id, t = defaultTableNames) {
 function flushSql(queue, t = defaultTableNames) {
   return `DELETE FROM ${t.failed} ${queue ? `WHERE queue = ${sqlString(queue)}` : ""}`.trimEnd();
 }
+function pruneCompletedJobsSql(hours, t = defaultTableNames) {
+  return `DELETE FROM ${t.jobs} WHERE completed_at IS NOT NULL AND completed_at <= unixepoch() - ${sqlInt(hours * 3600)}`;
+}
+function pruneFailedJobsSql(hours, t = defaultTableNames) {
+  return `DELETE FROM ${t.failed} WHERE failed_at <= unixepoch() - ${sqlInt(hours * 3600)}`;
+}
+function pruneFinishedBatchesSql(hours, t = defaultTableNames) {
+  return `DELETE FROM ${t.batches} WHERE finished_at IS NOT NULL AND finished_at <= unixepoch() - ${sqlInt(hours * 3600)}`;
+}
+function pruneSql(opts, t = defaultTableNames) {
+  return [
+    pruneCompletedJobsSql(opts.completedHours, t),
+    pruneFailedJobsSql(opts.failedHours, t),
+    pruneFinishedBatchesSql(opts.batchesHours, t)
+  ].join(";\n");
+}
 function clearSql(filters = {}, t = defaultTableNames) {
   return `DELETE FROM ${t.jobs}
 ${andClauses(
@@ -586,6 +602,36 @@ const clear = defineCommand({
 `);
   }
 });
+const prune = defineCommand({
+  meta: { name: "prune", description: "Delete terminal rows past retention (artisan queue:prune-batches + queue:prune-failed)" },
+  args: {
+    ...sharedArgs,
+    "completed-hours": { type: "string", description: "Completed-jobs retention in hours", default: "24" },
+    "failed-hours": { type: "string", description: "Failed-jobs retention in hours", default: "168" },
+    "batches-hours": { type: "string", description: "Finished-batches retention in hours", default: "72" },
+    "yes": { type: "boolean", alias: "y", description: "Skip confirmation", default: false }
+  },
+  async run({ args }) {
+    const { target, tables } = context(args);
+    const hours = {
+      completedHours: Number(args["completed-hours"]),
+      failedHours: Number(args["failed-hours"]),
+      batchesHours: Number(args["batches-hours"])
+    };
+    if (Object.values(hours).some((h) => !Number.isFinite(h) || h < 0)) {
+      process$1.stderr.write(`${color.red("\u2717")} --*-hours must be non-negative numbers.
+`);
+      process$1.exitCode = 1;
+      return;
+    }
+    const scope = `completed >${hours.completedHours}h, failed >${hours.failedHours}h, batches >${hours.batchesHours}h`;
+    if (!await confirm(`Prune ${scope} (${target.remote ? "remote" : "local"})?`, args.yes))
+      return;
+    await execD1(target, `${pruneSql(hours, tables)};`);
+    process$1.stdout.write(`${color.green("\u2713")} Pruned ${scope}.
+`);
+  }
+});
 const migrate = defineCommand({
   meta: { name: "migrate", description: "Create the job tables/indexes in D1" },
   args: {
@@ -658,7 +704,7 @@ const main = defineCommand({
     description: "Inspect and manage nuxt-cf-jobs durable jobs in Cloudflare D1"
   },
   args: sharedArgs,
-  subCommands: { status, jobs, failed, retry, forget, flush, clear, migrate, schedule, tasks },
+  subCommands: { status, jobs, failed, retry, forget, flush, clear, prune, migrate, schedule, tasks },
   async run({ args, rawArgs }) {
     if (rawArgs.length === 0 || rawArgs.every((a) => a.startsWith("-")))
       await runStatus(args);

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "configKey": "cfJobs",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -131,6 +131,7 @@ const module$1 = defineNuxtModule({
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     nuxt.options.alias["#cf-jobs/server"] = resolver.resolve("./runtime/server");
+    nuxt.options.alias["#cf-jobs/cloudflare"] = resolver.resolve("./runtime/server/cloudflare");
     addServerImports([
       { name: "defineJob", from: resolver.resolve("./runtime/server/registry") },
       { name: "defineScheduledTask", from: resolver.resolve("./runtime/server/scheduled") }

package/dist/runtime/server/batch.d.ts

@@ -96,6 +96,7 @@ export declare function createJobBatch<Name extends string = string, Payload ext
 export interface BatchProgress {
     batchId: string;
     name: string | null;
+    siteId: string | null;
     completed: number;
     total: number;
     failed: number;

package/dist/runtime/server/batch.js

@@ -103,6 +103,7 @@ function toProgress(batch) {
   return {
     batchId: batch.id,
     name: batch.name,
+    siteId: batch.siteId,
     completed: batch.totalJobs - batch.pendingJobs,
     total: batch.totalJobs,
     failed: batch.failedJobs,

package/dist/runtime/server/cloudflare.d.ts

@@ -0,0 +1,46 @@
+import type { JobMetricsEvent, JobMetricsSink } from './metrics.js';
+/**
+ * Minimal structural shape of a Cloudflare Analytics Engine binding
+ * (`AnalyticsEngineDataset`). Declared locally so this module needs no
+ * `@cloudflare/workers-types` dependency; the real binding is assignable.
+ */
+export interface AnalyticsEngineDataset {
+    writeDataPoint: (point: {
+        indexes?: string[];
+        blobs?: Array<string | null>;
+        doubles?: number[];
+    }) => void;
+}
+export type AnalyticsEngineDataPoint = Parameters<AnalyticsEngineDataset['writeDataPoint']>[0];
+export interface AnalyticsEngineSinkOptions {
+    /**
+     * Override the event → data-point mapping. Mind the Analytics Engine limits:
+     * at most ONE index (≤96 bytes), ≤20 doubles, and blobs totalling ≤5120 bytes.
+     */
+    toDataPoint?: (event: JobMetricsEvent) => AnalyticsEngineDataPoint;
+}
+/**
+ * Default mapping. `queue` is the single index (the natural rollup key); status
+ * and jobType ride as blobs for filtering; duration + attempts as doubles for
+ * latency/retry aggregates.
+ */
+export declare function defaultJobDataPoint(event: JobMetricsEvent): AnalyticsEngineDataPoint;
+/** Build a sink that writes each event to the given Analytics Engine dataset. */
+export declare function createAnalyticsEngineSink(dataset: AnalyticsEngineDataset, opts?: AnalyticsEngineSinkOptions): JobMetricsSink;
+export interface ResolveAnalyticsEngineSinkOptions extends AnalyticsEngineSinkOptions {
+    /** Env binding name of the Analytics Engine dataset (e.g. `'JOB_ANALYTICS'`). */
+    binding: string;
+    /**
+     * Sink used when the binding is absent (local dev / not yet provisioned) — so
+     * wiring this in is a safe no-op until the dataset exists. Defaults to
+     * {@link noopMetricsSink}; pass `createConsoleMetricsSink()` for dev logs.
+     */
+    fallback?: JobMetricsSink;
+}
+/**
+ * Resolve an Analytics Engine sink from a Workers `env`, degrading to a fallback
+ * (no-op by default) when the binding is missing or malformed. This is the
+ * "provide the binding name, it just works" entry point — drop it straight into
+ * a repository's hooks via `metricsSinkToRepoHooks`.
+ */
+export declare function resolveAnalyticsEngineSink(env: Record<string, unknown> | undefined, opts: ResolveAnalyticsEngineSinkOptions): JobMetricsSink;

package/dist/runtime/server/cloudflare.js

@@ -0,0 +1,31 @@
+import { noopMetricsSink } from "./metrics.js";
+export function defaultJobDataPoint(event) {
+  return {
+    indexes: [event.queue],
+    blobs: [event.queue, event.jobType, event.status, event.error ?? null],
+    // doubles are positional — keep this order stable (the AE SQL API references
+    // double1..double6). duration, attempts, then the reported execution stats.
+    doubles: [
+      event.durationMs ?? 0,
+      event.attempts,
+      event.rowsFetched ?? 0,
+      event.rowsInserted ?? 0,
+      event.d1RowsRead ?? 0,
+      event.d1RowsWritten ?? 0
+    ]
+  };
+}
+export function createAnalyticsEngineSink(dataset, opts = {}) {
+  const toDataPoint = opts.toDataPoint ?? defaultJobDataPoint;
+  return {
+    record(event) {
+      dataset.writeDataPoint(toDataPoint(event));
+    }
+  };
+}
+export function resolveAnalyticsEngineSink(env, opts) {
+  const dataset = env?.[opts.binding];
+  if (dataset && typeof dataset.writeDataPoint === "function")
+    return createAnalyticsEngineSink(dataset, opts);
+  return opts.fallback ?? noopMetricsSink;
+}

package/dist/runtime/server/d1.d.ts

@@ -1,4 +1,4 @@
-import type { DurableJobFailureRepository, DurableJobLifecycle, DurableJobRecord, DurableJobRecoveryRepository, DurableJobRepository, ReleaseDurableJobOptions } from './outbox.js';
+import type { DurableJobFailureRepository, DurableJobLifecycle, DurableJobPruneRepository, DurableJobRecord, DurableJobRecoveryRepository, DurableJobRepository, ReleaseDurableJobOptions } from './outbox.js';
 export interface D1PreparedStatementLike<T = unknown> {
     bind: (...values: unknown[]) => D1PreparedStatementLike<T>;
     run: () => Promise<{
@@ -108,7 +108,7 @@ export interface D1InsertJobsResult<Queue extends string = string> {
     inserted: Array<DurableJobRecord<Queue>>;
     chunks: D1InsertJobsChunkResult[];
 }
-export type D1DurableJobRepository<Queue extends string = string> = DurableJobRepository<Queue, DurableJobRecord<Queue>> & DurableJobRecoveryRepository<Queue, D1DurableJobRecord<Queue>> & DurableJobLifecycle<D1DurableJobRecord<Queue>> & DurableJobFailureRepository & {
+export type D1DurableJobRepository<Queue extends string = string> = DurableJobRepository<Queue, DurableJobRecord<Queue>> & DurableJobRecoveryRepository<Queue, D1DurableJobRecord<Queue>> & DurableJobLifecycle<D1DurableJobRecord<Queue>> & DurableJobFailureRepository & DurableJobPruneRepository & {
     migrate: () => Promise<void>;
     insertJobs: (records: readonly DurableJobRecord<Queue>[], opts?: {
         batchSize?: number;

package/dist/runtime/server/d1.js

@@ -14,6 +14,8 @@ export const d1DurableJobMigrationSql = [
   "CREATE INDEX IF NOT EXISTS idx_jobs_batch ON jobs (batch_id)",
   "CREATE INDEX IF NOT EXISTS idx_jobs_trace ON jobs (trace_id)",
   "CREATE INDEX IF NOT EXISTS idx_jobs_sync_dedup ON jobs (site_id, job_type)",
+  // Partial index backing pruneCompletedJobs (completed_at IS NOT NULL AND <= ?).
+  "CREATE INDEX IF NOT EXISTS idx_jobs_completed_at ON jobs (completed_at) WHERE completed_at IS NOT NULL",
   "CREATE UNIQUE INDEX IF NOT EXISTS idx_jobs_unique_active ON jobs (unique_key) WHERE unique_key IS NOT NULL AND completed_at IS NULL AND failed_at IS NULL",
   "CREATE INDEX IF NOT EXISTS idx_failed_jobs_queue ON failed_jobs (queue)",
   "CREATE INDEX IF NOT EXISTS idx_failed_jobs_site ON failed_jobs (site_id)",
@@ -23,6 +25,7 @@ export const d1DurableJobMigrationSql = [
 export function createD1DurableJobRepository(db, opts = {}) {
   const jobsTable = opts.jobsTable ?? "jobs";
   const failedJobsTable = opts.failedJobsTable ?? "failed_jobs";
+  const batchesTable = opts.batchesTable ?? "job_batches";
   const insertJobSql = `
     INSERT OR IGNORE INTO ${jobsTable} (
       id, queue, job_type, batch_id, user_id, site_id, partner_id, trace_id, unique_key, payload,
@@ -116,12 +119,26 @@ export function createD1DurableJobRepository(db, opts = {}) {
       return "in-flight";
     },
     async completeJob(job, result) {
-      const durationMs = result && typeof result === "object" && "durationMs" in result && typeof result.durationMs === "number" ? result.durationMs : null;
+      const stats = readResultStat(result);
+      const reportedDuration = stats("durationMs");
+      const durationMs = reportedDuration ?? (job.reserved_at != null ? (currentUnixSeconds() - job.reserved_at) * 1e3 : null);
       await db.prepare(`
         UPDATE ${jobsTable}
-        SET completed_at = unixepoch(), reserved_at = NULL, duration_ms = COALESCE(?, duration_ms)
+        SET completed_at = unixepoch(), reserved_at = NULL,
+            duration_ms = COALESCE(?, duration_ms),
+            rows_fetched = COALESCE(?, rows_fetched),
+            rows_inserted = COALESCE(?, rows_inserted),
+            d1_rows_read = COALESCE(?, d1_rows_read),
+            d1_rows_written = COALESCE(?, d1_rows_written)
         WHERE id = ?
-      `).bind(durationMs, job.id).run();
+      `).bind(
+        durationMs,
+        stats("rowsFetched") ?? null,
+        stats("rowsInserted") ?? null,
+        stats("d1RowsRead") ?? null,
+        stats("d1RowsWritten") ?? null,
+        job.id
+      ).run();
       fireHook(() => opts.onJobCompleted?.({ job, durationMs, result }));
     },
     async failJob(job, error) {
@@ -235,12 +252,54 @@ export function createD1DurableJobRepository(db, opts = {}) {
         siteId: job.site_id,
         userId: job.user_id
       };
+    },
+    async pruneCompletedJobs(query) {
+      return await pruneInChunks(db, jobsTable, "completed_at IS NOT NULL AND completed_at <= ?", query);
+    },
+    async pruneFailedJobs(query) {
+      return await pruneInChunks(db, failedJobsTable, "failed_at <= ?", query);
+    },
+    async pruneFinishedBatches(query) {
+      return await pruneInChunks(
+        db,
+        batchesTable,
+        `finished_at IS NOT NULL AND finished_at <= ? AND NOT EXISTS (SELECT 1 FROM ${jobsTable} WHERE ${jobsTable}.batch_id = ${batchesTable}.id)`,
+        query
+      );
     }
   };
 }
+const DEFAULT_PRUNE_CHUNK = 1e3;
+async function pruneInChunks(db, table, whereClause, query) {
+  const chunk = Math.max(1, query.limit ?? DEFAULT_PRUNE_CHUNK);
+  const sql = `
+    DELETE FROM ${table}
+    WHERE id IN (
+      SELECT id FROM ${table}
+      WHERE ${whereClause}
+      LIMIT ?
+    )
+  `;
+  let total = 0;
+  for (; ; ) {
+    const result = await db.prepare(sql).bind(query.before, chunk).run();
+    const changes = result.meta?.changes ?? 0;
+    total += changes;
+    if (changes < chunk)
+      break;
+  }
+  return total;
+}
 function currentUnixSeconds() {
   return Math.floor(Date.now() / 1e3);
 }
+function readResultStat(result) {
+  const obj = result && typeof result === "object" ? result : void 0;
+  return (key) => {
+    const v = obj?.[key];
+    return typeof v === "number" ? v : void 0;
+  };
+}
 function fireHook(fn) {
   try {
     const result = fn();

package/dist/runtime/server/index.d.ts

@@ -3,12 +3,14 @@ export * from './batch.js';
 export * from './d1.js';
 export * from './dispatch.js';
 export * from './errors.js';
+export * from './metrics.js';
 export * from './outbox.js';
 export * from './policy.js';
 export { CF_QUEUE_MAX_BATCH_BYTES, CF_QUEUE_MAX_BATCH_SIZE, CF_QUEUE_MAX_DELAY_SECONDS, CF_QUEUE_MAX_MESSAGE_BYTES, createJobQueue, defineCfJobsQueues, exponentialBackoff, resolveNitroTaskEnv, resolveQueueBindingName, } from './queue.js';
 export type { JobQueuePublisher, QueueSource } from './queue.js';
 export * from './registry.js';
 export * from './result.js';
+export * from './runtime.js';
 export * from './scheduled.js';
 export * from './schema.js';
 export * from './types.js';

package/dist/runtime/server/index.js

@@ -3,6 +3,7 @@ export * from "./batch.js";
 export * from "./d1.js";
 export * from "./dispatch.js";
 export * from "./errors.js";
+export * from "./metrics.js";
 export * from "./outbox.js";
 export * from "./policy.js";
 export {
@@ -18,6 +19,7 @@ export {
 } from "./queue.js";
 export * from "./registry.js";
 export * from "./result.js";
+export * from "./runtime.js";
 export * from "./scheduled.js";
 export * from "./schema.js";
 export * from "./types.js";

package/dist/runtime/server/metrics.d.ts

@@ -0,0 +1,53 @@
+import type { D1DurableJobRepositoryOptions } from './d1.js';
+export type JobMetricStatus = 'completed' | 'failed' | 'released';
+/**
+ * One terminal-ish job lifecycle event, engine-neutral. `released` is a
+ * deliberate retry (`ctx.release()` / a handler throw) rather than a terminal
+ * state, but it is worth recording for retry-rate dashboards.
+ */
+export interface JobMetricsEvent {
+    jobId: string;
+    queue: string;
+    jobType: string;
+    status: JobMetricStatus;
+    attempts: number;
+    /** Wall-clock duration when known (completed jobs); null otherwise. */
+    durationMs: number | null;
+    batchId: string | null;
+    siteId: string | null;
+    userId: number | null;
+    /** Present for `failed` / `released` (the release reason). */
+    error?: string;
+    rowsFetched?: number;
+    rowsInserted?: number;
+    d1RowsRead?: number;
+    d1RowsWritten?: number;
+}
+export interface JobMetricsSink {
+    record: (event: JobMetricsEvent) => void | Promise<void>;
+}
+/**
+ * Adapt a {@link JobMetricsSink} to the repository's lifecycle hooks. Spread the
+ * result into {@link D1DurableJobRepositoryOptions}:
+ *
+ * ```ts
+ * createD1DurableJobRepository(db, { ...metricsSinkToRepoHooks(sink) })
+ * ```
+ *
+ * The repo invokes these via its own `fireHook` (swallows sync throws + async
+ * rejections), so a misbehaving sink can never break a job's lifecycle.
+ */
+export declare function metricsSinkToRepoHooks(sink: JobMetricsSink): Pick<D1DurableJobRepositoryOptions, 'onJobCompleted' | 'onJobFailed' | 'onJobReleased'>;
+/**
+ * Fan an event out to several sinks, isolating each so one throwing/rejecting
+ * sink never starves the others (the repo guards the outermost call, but a sink
+ * combined here is also reachable directly).
+ */
+export declare function combineMetricsSinks(...sinks: JobMetricsSink[]): JobMetricsSink;
+/**
+ * A console sink — a zero-dependency default for local dev where no real metrics
+ * engine binding exists. Pass your own `log` to route elsewhere.
+ */
+export declare function createConsoleMetricsSink(log?: (event: JobMetricsEvent) => void): JobMetricsSink;
+/** A sink that records nothing — the safe default when metrics are unconfigured. */
+export declare const noopMetricsSink: JobMetricsSink;

package/dist/runtime/server/metrics.js

@@ -0,0 +1,59 @@
+const STAT_KEYS = ["rowsFetched", "rowsInserted", "d1RowsRead", "d1RowsWritten"];
+function readStats(result) {
+  if (!result || typeof result !== "object")
+    return {};
+  const out = {};
+  for (const k of STAT_KEYS) {
+    const v = result[k];
+    if (typeof v === "number")
+      out[k] = v;
+  }
+  return out;
+}
+function toEvent(job, status, extra) {
+  return {
+    jobId: job.id,
+    queue: job.queue,
+    jobType: job.job_type,
+    status,
+    attempts: job.attempts,
+    durationMs: extra.durationMs ?? null,
+    batchId: job.batch_id,
+    siteId: job.site_id,
+    userId: job.user_id,
+    error: extra.error
+  };
+}
+export function metricsSinkToRepoHooks(sink) {
+  return {
+    onJobCompleted({ job, durationMs, result }) {
+      return sink.record({ ...toEvent(job, "completed", { durationMs }), ...readStats(result) });
+    },
+    onJobFailed({ job, error }) {
+      return sink.record(toEvent(job, "failed", { durationMs: job.duration_ms ?? null, error }));
+    },
+    onJobReleased({ job, opts }) {
+      return sink.record(toEvent(job, "released", { error: opts?.error }));
+    }
+  };
+}
+export function combineMetricsSinks(...sinks) {
+  return {
+    record(event) {
+      for (const sink of sinks) {
+        try {
+          const result = sink.record(event);
+          if (result && typeof result.then === "function")
+            result.catch(() => {
+            });
+        } catch {
+        }
+      }
+    }
+  };
+}
+export function createConsoleMetricsSink(log = (event) => console.debug("[cf-jobs:metric]", event)) {
+  return { record: log };
+}
+export const noopMetricsSink = { record() {
+} };

package/dist/runtime/server/outbox.d.ts

@@ -122,6 +122,54 @@ export interface DurableJobRecoveryRepository<Queue extends string = string, Rec
     findStaleReservedJobs?: (query: DurableJobStaleRecoveryQuery) => Promise<Record[]>;
     releaseStaleReservedJobs?: (query: DurableJobStaleRecoveryQuery) => Promise<number>;
 }
+export interface PruneDurableJobsQuery {
+    /** Unix-seconds cutoff: terminal rows with a timestamp at or before this are deleted. */
+    before: number;
+    /**
+     * Max rows deleted per statement. Implementations chunk the delete in a loop
+     * (D1 caps rows touched per statement), so the full backlog older than `before`
+     * is removed regardless of this value. Defaults to the implementation's chunk size.
+     */
+    limit?: number;
+}
+/**
+ * Pruning the three terminal-row tables (Laravel `queue:prune-batches` /
+ * `queue:prune-failed` parity). Each method deletes only rows that are genuinely
+ * terminal (completed / failed / finished) and older than `before`, returning the
+ * total deleted. In-flight rows (`completed_at`/`failed_at`/`finished_at` IS NULL)
+ * are never touched.
+ */
+export interface DurableJobPruneRepository {
+    /** Delete `jobs` rows with `completed_at <= before` (soft-completed, kept for observability). */
+    pruneCompletedJobs: (query: PruneDurableJobsQuery) => Promise<number>;
+    /** Delete `job_batches` rows with `finished_at <= before` (terminal batches). */
+    pruneFinishedBatches: (query: PruneDurableJobsQuery) => Promise<number>;
+    /** Delete `failed_jobs` rows with `failed_at <= before`. */
+    pruneFailedJobs: (query: PruneDurableJobsQuery) => Promise<number>;
+}
+export interface PruneDurableJobsOptions {
+    /** Cutoff for `completeJob`-soft-completed `jobs` rows. Omit to skip. */
+    completedBefore?: number;
+    /** Cutoff for terminal `job_batches` rows. Omit to skip. */
+    finishedBatchesBefore?: number;
+    /** Cutoff for `failed_jobs` rows. Omit to skip. */
+    failedBefore?: number;
+    /** Per-statement chunk size forwarded to each prune method. */
+    limit?: number;
+}
+export interface PruneDurableJobsResult {
+    completedJobs: number;
+    finishedBatches: number;
+    failedJobs: number;
+}
+/**
+ * Convenience over {@link DurableJobPruneRepository} that prunes all three tables
+ * with independent cutoffs. Ordering matters: `jobs.batch_id` FKs `job_batches(id)`,
+ * so member jobs (completed + failed) are pruned BEFORE their batches — otherwise a
+ * batch delete can violate the FK where D1 enforces it. A cutoff left `undefined`
+ * skips that table (the corresponding count is 0).
+ */
+export declare function pruneDurableJobs(repository: DurableJobPruneRepository, opts: PruneDurableJobsOptions): Promise<PruneDurableJobsResult>;
 export interface PrepareDurableJobOptions<Name extends string, Payload extends object, Queue extends string> {
     name: Name;
     payload: Payload;
@@ -231,7 +279,7 @@ export interface RunDurableJobMessageOptions<StoredJob, Job extends Dispatchable
     message: Pick<QueueMessage<Message>, 'body' | 'ack' | 'retry'>;
     lifecycle: Pick<DurableJobLifecycle<StoredJob, CompleteResult, FailOptions>, 'claimJob' | 'resolveClaimMiss' | 'completeJob' | 'failJob' | 'releaseJob'>;
     registry: {
-        getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined;
+        getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined | Promise<JobHandler<unknown, Env, Db, Logger> | undefined>;
         getJobDefinition?: (name: string) => JobDefinition<string, unknown, string, Env, Db, Logger> | undefined;
     };
     toDispatchableJob: (job: StoredJob) => Job;
@@ -252,6 +300,55 @@ export interface RunDurableJobMessageOptions<StoredJob, Job extends Dispatchable
         job: StoredJob;
         dispatch: DispatchResult;
     }) => unknown | Promise<unknown>;
+    /**
+     * Laravel worker model: a handler that throws is retried until `attempts`
+     * reaches the job's max, then failed (→ `failed_jobs`) instead of released for
+     * another try. Supply this to read the stored job's max so the consumer — not
+     * just the queue transport's `max_retries` — enforces the per-job attempt cap.
+     * Omit to keep retrying every throw (the transport/DLQ then decides terminal).
+     */
+    maxAttemptsOf?: (job: StoredJob) => number | undefined;
+    /**
+     * Per-job scope created right after claim: `wrapDispatch` wraps the handler run
+     * (e.g. AsyncLocalStorage telemetry), `onSettled` observes every terminal/
+     * released outcome (e.g. write a run-log row). Both close over the same scope so
+     * the wrapper's collected data is available to the observer.
+     */
+    createJobScope?: (storedJob: StoredJob) => DurableJobScope<StoredJob>;
+    /**
+     * Decide whether a THROWN error is terminal (→ `failed_jobs`) vs released for
+     * retry. Overrides the default `attempts >= maxAttemptsOf` so callers can, e.g.,
+     * never fail on transient infra errors. `maxAttempts` is `maxAttemptsOf`'s value.
+     */
+    isPermanentFailure?: (input: {
+        error: unknown;
+        storedJob: StoredJob;
+        attempts: number;
+        maxAttempts: number | undefined;
+    }) => boolean;
+    /**
+     * Dispatch the job payload's `then`/`catch`/`finally` continuations after a
+     * terminal outcome: `then`+`finally` on success, `catch`+`finally` on terminal
+     * failure, none on a release/retry.
+     */
+    dispatchContinuations?: (input: {
+        storedJob: StoredJob;
+        stage: DurableJobContinuationStage;
+    }) => void | Promise<void>;
+}
+export interface DurableJobSettlement<StoredJob> {
+    storedJob: StoredJob;
+    status: RunDurableJobMessageResult['status'];
+    /** Wall-clock ms from claim to settle. */
+    durationMs: number;
+    /** True when the job reached a terminal failure (not a release/retry). */
+    permanent: boolean;
+    /** The error for failed/released/exhausted outcomes (raw, for the caller to classify). */
+    error?: unknown;
+}
+export interface DurableJobScope<StoredJob> {
+    wrapDispatch?: (run: () => Promise<DispatchResult>) => Promise<DispatchResult>;
+    onSettled?: (settlement: DurableJobSettlement<StoredJob>) => void | Promise<void>;
 }
 /**
  * Outcome of {@link runDurableJobMessage}, discriminated on `status` so each
@@ -264,6 +361,8 @@ export interface RunDurableJobMessageOptions<StoredJob, Job extends Dispatchable
  * - `errored`: the handler threw an unexpected defect; the message is retried and
  *   `error` carries the defect as a `handler-threw` `JobError` (`error.cause` is the
  *   original throw). Distinct from `released` (a deliberate `ctx.release()`).
+ * - `exhausted`: the handler threw AND `attempts` reached `maxAttemptsOf` — the job
+ *   was failed (→ `failed_jobs`) rather than retried. Terminal.
  */
 export type RunDurableJobMessageResult = {
     status: 'invalid-message';
@@ -285,5 +384,8 @@ export type RunDurableJobMessageResult = {
 } | {
     status: 'errored';
     error: JobError;
+} | {
+    status: 'exhausted';
+    error: JobError;
 };
 export declare function runDurableJobMessage<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown, FailOptions = unknown>(opts: RunDurableJobMessageOptions<StoredJob, Job, Message, Env, Db, Logger, CompleteResult, FailOptions>): Promise<RunDurableJobMessageResult>;

package/dist/runtime/server/outbox.js

@@ -8,6 +8,12 @@ import { err, ok, unwrapResult } from "./result.js";
 function byteLength(value) {
   return typeof Buffer !== "undefined" ? Buffer.byteLength(value, "utf8") : new TextEncoder().encode(value).byteLength;
 }
+export async function pruneDurableJobs(repository, opts) {
+  const completedJobs = typeof opts.completedBefore === "number" ? await repository.pruneCompletedJobs({ before: opts.completedBefore, limit: opts.limit }) : 0;
+  const failedJobs = typeof opts.failedBefore === "number" ? await repository.pruneFailedJobs({ before: opts.failedBefore, limit: opts.limit }) : 0;
+  const finishedBatches = typeof opts.finishedBatchesBefore === "number" ? await repository.pruneFinishedBatches({ before: opts.finishedBatchesBefore, limit: opts.limit }) : 0;
+  return { completedJobs, failedJobs, finishedBatches };
+}
 export async function prepareDurableJobResult(opts) {
   const now = opts.now ?? Math.floor(Date.now() / 1e3);
   const definition = opts.definition ?? opts.registry?.getJobDefinition?.(opts.name);
@@ -221,31 +227,75 @@ export async function runDurableJobMessage(opts) {
   }
   const storedJob = claimed.job;
   const job = opts.toDispatchableJob(storedJob);
+  const reportedStats = {};
+  const reportStats = (s) => {
+    for (const k of ["rowsFetched", "rowsInserted", "d1RowsRead", "d1RowsWritten"]) {
+      if (typeof s[k] === "number")
+        reportedStats[k] = (reportedStats[k] ?? 0) + s[k];
+    }
+  };
+  const scope = opts.createJobScope?.(storedJob);
+  const startedMs = Date.now();
+  const settle = async (status, permanent, error) => {
+    await scope?.onSettled?.({ storedJob, status, durationMs: Date.now() - startedMs, permanent, error });
+  };
+  const continuations = async (...stages) => {
+    for (const stage of stages)
+      await opts.dispatchContinuations?.({ storedJob, stage });
+  };
   try {
-    const dispatch = await dispatchRegisteredJob({
+    const runOnce = () => dispatchRegisteredJob({
       registry: opts.registry,
       job,
-      createContext: (input) => opts.createJobContext({ ...input, storedJob })
+      createContext: async (input) => ({ ...await opts.createJobContext({ ...input, storedJob }), reportStats })
     });
+    const dispatch = await (scope?.wrapDispatch ? scope.wrapDispatch(runOnce) : runOnce());
     if (!dispatch.success) {
       if (opts.failDispatchFailure !== false)
         await failDurableJob(opts.lifecycle, storedJob, dispatch.error ? formatJobError(dispatch.error) : "Job dispatch failed");
+      await settle("dispatch-failed", true, dispatch.error);
+      await continuations("catch", "finally");
       opts.message.ack();
       return { status: "dispatch-failed", dispatch, error: dispatch.error };
     }
     if (dispatch.control?.handled) {
-      opts.message.ack();
-      return { status: dispatch.control.action === "failed" ? "failed" : "released", dispatch };
+      if (dispatch.control.action === "failed") {
+        await failDurableJob(opts.lifecycle, storedJob, dispatch.control.error ?? "Job failed via ctx.fail()");
+        await settle("failed", true, dispatch.control.error);
+        await continuations("catch", "finally");
+        opts.message.ack();
+        return { status: "failed", dispatch };
+      }
+      const delaySeconds = dispatch.control.delaySeconds ?? 0;
+      await releaseDurableJob(opts.lifecycle, storedJob, { delaySeconds, error: dispatch.control.error });
+      await settle("released", false, dispatch.control.error);
+      opts.message.retry({ delaySeconds });
+      return { status: "released", dispatch };
     }
-    await completeDurableJob(opts.lifecycle, storedJob, await opts.completeResult?.({ job: storedJob, dispatch }));
+    const result = await opts.completeResult?.({ job: storedJob, dispatch });
+    const hasStats = Object.keys(reportedStats).length > 0;
+    const completeWith = hasStats ? { ...result && typeof result === "object" ? result : {}, ...reportedStats } : result;
+    await completeDurableJob(opts.lifecycle, storedJob, completeWith);
+    await settle("completed", false);
+    await continuations("then", "finally");
     opts.message.ack();
     return { status: "completed", dispatch };
   } catch (error) {
+    const maxAttempts = opts.maxAttemptsOf?.(storedJob);
+    const permanent = opts.isPermanentFailure ? opts.isPermanentFailure({ error, storedJob, attempts: job.attempts, maxAttempts }) : typeof maxAttempts === "number" && job.attempts >= maxAttempts;
+    if (permanent) {
+      await failDurableJob(opts.lifecycle, storedJob, describeCause(error));
+      await settle("exhausted", true, error);
+      await continuations("catch", "finally");
+      opts.message.ack();
+      return { status: "exhausted", error: jobErrors.handlerThrew(error) };
+    }
     const delaySeconds = typeof opts.retryDelaySeconds === "function" ? opts.retryDelaySeconds({ error, job: storedJob }) : opts.retryDelaySeconds ?? 0;
     await releaseDurableJob(opts.lifecycle, storedJob, {
       delaySeconds,
       error: describeCause(error)
     });
+    await settle("errored", false, error);
     opts.message.retry({ delaySeconds });
     return { status: "errored", error: jobErrors.handlerThrew(error) };
   }

package/dist/runtime/server/runtime.d.ts

@@ -0,0 +1,195 @@
+import type { BatchProgress, DurableBatchStore, SettleBatchMemberOptions, SettleBatchMemberResult } from './batch.js';
+import type { D1DatabaseLike, D1DurableJobRecord, D1DurableJobRepository } from './d1.js';
+import type { JobMetricsSink } from './metrics.js';
+import type { CreateJobBatchOptions, CreateJobBatchResult, DurableJobContinuationStage, DurableJobRecord, DurableJobScope, EnqueueDurableJobResult, PruneDurableJobsOptions, PruneDurableJobsResult, QueuePublisher, RunDurableJobMessageOptions, RunDurableJobMessageResult } from './outbox.js';
+import type { DispatchableJob, JobDefinition, JobHandler, QueueBatch, QueueMessage } from './types.js';
+export interface RunDurableJobBatchMessageOptions<StoredJob, Job extends DispatchableJob, Message extends {
+    jobId: string;
+    queue: string;
+} = {
+    jobId: string;
+    queue: string;
+}, Env = unknown, Db = unknown, Logger = unknown> extends RunDurableJobMessageOptions<StoredJob, Job, Message, Env, Db, Logger> {
+    store: DurableBatchStore;
+    /** Run the winning settle's `onFinish`. Defaults to nothing. */
+    dispatchOnFinish?: SettleBatchMemberOptions['dispatchOnFinish'];
+    /** Notified after each settle with the batch's progress (live UI / telemetry). */
+    onBatchProgress?: (progress: BatchProgress) => void | Promise<void>;
+}
+export interface RunDurableJobBatchMessageResult {
+    run: RunDurableJobMessageResult;
+    settled: SettleBatchMemberResult | null;
+}
+/**
+ * Run one queue message through the full durable lifecycle, then settle its
+ * batch. Only terminal outcomes (`completed` / `failed` / `dispatch-failed`)
+ * settle — a `released`/`errored` message will re-run, so settling it would
+ * double-count. The settle's progress is forwarded to `onBatchProgress`, always
+ * awaited so `onFinish` has fired before this resolves.
+ */
+export declare function runDurableJobBatchMessage<StoredJob, Job extends DispatchableJob, Message extends {
+    jobId: string;
+    queue: string;
+} = {
+    jobId: string;
+    queue: string;
+}, Env = unknown, Db = unknown, Logger = unknown>(opts: RunDurableJobBatchMessageOptions<StoredJob, Job, Message, Env, Db, Logger>): Promise<RunDurableJobBatchMessageResult>;
+export interface RunLightweightMessageOptions<Env = unknown, Db = unknown, Logger = unknown> {
+    message: Pick<QueueMessage, 'id' | 'body' | 'attempts' | 'ack' | 'retry'>;
+    registry: DurableJobsRuntimeRegistry<Env, Db, Logger>;
+    createJobContext: ConsumerContextFactory<Env, Db, Logger>;
+    /** Per-isolate dedup of at-least-once redeliveries. Return true to drop. */
+    isDuplicate?: (id: string | undefined) => boolean;
+    /** Diagnostic sink for dropped/invalid messages (no throw). */
+    onLog?: (event: {
+        stage: string;
+        taskName?: string;
+        error?: string;
+    }) => void;
+}
+export type RunLightweightMessageResult = {
+    status: 'invalid' | 'duplicate' | 'dispatch-failed' | 'released' | 'completed' | 'errored';
+};
+export declare function runLightweightMessage<Env, Db, Logger>(opts: RunLightweightMessageOptions<Env, Db, Logger>): Promise<RunLightweightMessageResult>;
+export interface ConsumeQueueBatchOptions<Queue extends string, Env, Db, Logger> {
+    batch: QueueBatch;
+    repository: D1DurableJobRepository<Queue>;
+    store: DurableBatchStore;
+    registry: DurableJobsRuntimeRegistry<Env, Db, Logger>;
+    createJobContext: ConsumerContextFactory<Env, Db, Logger>;
+    dispatchOnFinish?: SettleBatchMemberOptions['dispatchOnFinish'];
+    onBatchProgress?: (progress: BatchProgress) => void | Promise<void>;
+    retryDelaySeconds?: RunDurableJobMessageOptions<unknown, DispatchableJob>['retryDelaySeconds'];
+    /** Defaults to a `-dlq` suffix check. */
+    isDlqQueue?: (queue: string) => boolean;
+    isDuplicate?: (id: string | undefined) => boolean;
+    onLog?: (event: {
+        stage: string;
+        queue?: string;
+        taskName?: string;
+        jobId?: string;
+        error?: string;
+    }) => void;
+    createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
+    isPermanentFailure?: (input: {
+        error: unknown;
+        storedJob: D1DurableJobRecord<Queue>;
+        attempts: number;
+        maxAttempts: number | undefined;
+    }) => boolean;
+    dispatchContinuations?: (input: {
+        storedJob: D1DurableJobRecord<Queue>;
+        stage: DurableJobContinuationStage;
+    }) => void | Promise<void>;
+    /**
+     * Soft batch CPU budget (ms). Before each message, if the batch has run longer
+     * than this, the remaining messages are retried instead of processed — so a
+     * heavy batch can't blow the Worker CPU limit mid-message.
+     */
+    maxBatchCpuMs?: number;
+    /** Delay (s) for messages deferred by the CPU guard. Default 5. */
+    cpuGuardRetryDelaySeconds?: number;
+}
+/**
+ * Process one CF queue batch end-to-end — the loop both apps hand-roll:
+ * - a DLQ-queue batch settles each durable member (failed) so a CF-exhausted
+ *   message can't hang its batch;
+ * - `{ jobId }` envelopes take the durable path (claim → run → settle + progress);
+ * - `{ _task }` payloads take the lightweight path.
+ */
+export declare function consumeQueueBatch<Queue extends string, Env, Db, Logger>(opts: ConsumeQueueBatchOptions<Queue, Env, Db, Logger>): Promise<void>;
+export interface DurableJobsRuntimeRegistry<Env = unknown, Db = unknown, Logger = unknown> {
+    /** May resolve async for lazily-loaded jobs (dispatchRegisteredJob awaits it). */
+    getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined | Promise<JobHandler<unknown, Env, Db, Logger> | undefined>;
+    getJobDefinition?: (name: string) => JobDefinition<string, unknown, string, Env, Db, Logger> | undefined;
+    getJobRoute?: (name: string) => {
+        queue: string;
+        jobType: string;
+    } | undefined;
+}
+type ConsumerMessage = RunDurableJobMessageOptions<unknown, DispatchableJob>['message'];
+type ConsumerContextFactory<Env, Db, Logger> = RunDurableJobMessageOptions<unknown, DispatchableJob, {
+    jobId: string;
+    queue: string;
+}, Env, Db, Logger>['createJobContext'];
+export interface CreateDurableJobsRuntimeOptions<Queue extends string = string, Env = unknown, Db = unknown, Logger = unknown> {
+    /** Raw D1 binding. The repo + batch store are built from it. */
+    db: D1DatabaseLike;
+    /** Worker `env`, used to resolve queue bindings. */
+    env: Record<string, unknown>;
+    registry: DurableJobsRuntimeRegistry<Env, Db, Logger>;
+    /** Map a logical queue to its `env` binding name. */
+    resolveQueueBinding: (queue: Queue) => string | undefined;
+    /** Build the per-job context (db, log, control, …). */
+    createJobContext: ConsumerContextFactory<Env, Db, Logger>;
+    /** Laravel `retry_after` — reclaim a reservation older than this on claim. */
+    reclaimAfterSeconds?: number;
+    /** Telemetry sink; wired into the repo's lifecycle hooks automatically. */
+    metricsSink?: JobMetricsSink;
+    /** Notified after each batch settle. */
+    onBatchProgress?: (progress: BatchProgress) => void | Promise<void>;
+    /** Override how a batch's onFinish continuation runs (default: durable enqueue). */
+    dispatchOnFinish?: SettleBatchMemberOptions['dispatchOnFinish'];
+    /** Per-throw retry backoff for the consumer. */
+    retryDelaySeconds?: RunDurableJobMessageOptions<unknown, DispatchableJob>['retryDelaySeconds'];
+    onMissingBinding?: (queue: Queue, count: number) => void | Promise<void>;
+    /** Classify a queue as a dead-letter queue (defaults to a `-dlq` suffix check). */
+    isDlqQueue?: (queue: string) => boolean;
+    /**
+     * Per-isolate dedup set for the lightweight `_task` path. Pass a module-level
+     * Set so redeliveries dedup across invocations (durable jobs are claim-guarded,
+     * so they don't need this).
+     */
+    dedup?: Set<string>;
+    /** Diagnostic log sink for DLQ / dropped lightweight messages. */
+    onLog?: (event: {
+        stage: string;
+        queue?: string;
+        taskName?: string;
+        jobId?: string;
+        error?: string;
+    }) => void;
+    /** Per-job scope: wrap dispatch (e.g. telemetry) + observe each settlement. */
+    createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
+    /** Decide whether a thrown error is terminal (default: attempts >= max). */
+    isPermanentFailure?: (input: {
+        error: unknown;
+        storedJob: D1DurableJobRecord<Queue>;
+        attempts: number;
+        maxAttempts: number | undefined;
+    }) => boolean;
+    /** Dispatch then/catch/finally payload continuations after a terminal outcome. */
+    dispatchContinuations?: (input: {
+        storedJob: D1DurableJobRecord<Queue>;
+        stage: DurableJobContinuationStage;
+    }) => void | Promise<void>;
+    /** Soft per-batch CPU budget (ms); remaining messages are deferred once exceeded. */
+    maxBatchCpuMs?: number;
+    /** Delay (s) for CPU-guard-deferred messages. Default 5. */
+    cpuGuardRetryDelaySeconds?: number;
+}
+export interface DurableJobsRuntime<Queue extends string = string> {
+    repository: D1DurableJobRepository<Queue>;
+    store: DurableBatchStore;
+    publisher: QueuePublisher<Queue>;
+    /** Durably enqueue a prepared record (persist row + dispatch message). */
+    enqueue: (record: DurableJobRecord<Queue>, opts?: {
+        delaySeconds?: number;
+    }) => Promise<EnqueueDurableJobResult>;
+    /** Register + dispatch a batch; `onFinish` fires once every member settles. */
+    createBatch: (opts: Omit<CreateJobBatchOptions<string, Record<string, unknown>, Queue>, 'store' | 'repository' | 'publisher'>) => Promise<CreateJobBatchResult>;
+    /** Run one durable queue message end-to-end (lifecycle + batch settle + progress). */
+    consumeMessage: (message: ConsumerMessage) => Promise<RunDurableJobBatchMessageResult>;
+    /** Process a whole CF queue batch (DLQ + durable + lightweight) — the consumer entrypoint. */
+    consumeBatch: (batch: QueueBatch) => Promise<void>;
+    /** Prune terminal rows (completed jobs / finished batches / failed jobs). */
+    prune: (opts: PruneDurableJobsOptions) => Promise<PruneDurableJobsResult>;
+}
+/**
+ * Bundle the durable-jobs verbs behind one factory so consumers stop
+ * hand-assembling repo + store + publisher + enqueue + batch + consumer loop.
+ * The metrics sink is wired into the repo here (no `metricsSinkToRepoHooks` at
+ * call sites), and `onFinish` continuations are enqueued durably by default.
+ */
+export declare function createDurableJobsRuntime<Queue extends string = string, Env = unknown, Db = unknown, Logger = unknown>(opts: CreateDurableJobsRuntimeOptions<Queue, Env, Db, Logger>): DurableJobsRuntime<Queue>;
+export {};

package/dist/runtime/server/runtime.js

@@ -0,0 +1,218 @@
+import { createD1DurableBatchStore, createJobBatch, settleBatchMember } from "./batch.js";
+import { createD1DurableJobRepository } from "./d1.js";
+import { dispatchRegisteredJob } from "./dispatch.js";
+import { formatJobError } from "./errors.js";
+import { metricsSinkToRepoHooks } from "./metrics.js";
+import { createQueuePublisher, enqueueDurableJob, prepareDurableJob, pruneDurableJobs, runDurableJobMessage } from "./outbox.js";
+import { resolveJobRetryDelay } from "./policy.js";
+export async function runDurableJobBatchMessage(opts) {
+  const run = await runDurableJobMessage(opts);
+  const terminal = run.status === "completed" || run.status === "failed" || run.status === "dispatch-failed" || run.status === "exhausted";
+  if (!terminal)
+    return { run, settled: null };
+  const jobId = opts.getJobId?.(opts.message.body) ?? opts.message.body.jobId;
+  if (!jobId)
+    return { run, settled: null };
+  const settled = await settleBatchMember({
+    store: opts.store,
+    jobId,
+    failed: run.status !== "completed",
+    dispatchOnFinish: opts.dispatchOnFinish
+  });
+  if (settled.progress && opts.onBatchProgress)
+    await opts.onBatchProgress(settled.progress);
+  return { run, settled };
+}
+export async function runLightweightMessage(opts) {
+  const { message, registry, createJobContext } = opts;
+  const body = message.body ?? {};
+  const taskName = typeof body._task === "string" ? body._task : "";
+  const definition = taskName ? registry.getJobDefinition?.(taskName) : void 0;
+  if (!definition) {
+    opts.onLog?.({ stage: "invalid_payload", taskName, error: taskName ? `No handler for task: ${taskName}` : "No _task in payload" });
+    message.ack();
+    return { status: "invalid" };
+  }
+  if (opts.isDuplicate?.(message.id)) {
+    message.ack();
+    return { status: "duplicate" };
+  }
+  const job = {
+    id: `${taskName}:${typeof body.jobId === "string" ? body.jobId : crypto.randomUUID()}`,
+    queue: definition.queue ?? "",
+    payload: body,
+    attempts: message.attempts,
+    batchId: null,
+    siteId: typeof body.siteId === "string" ? body.siteId : null,
+    userId: typeof body.userId === "number" ? body.userId : null
+  };
+  try {
+    const dispatch = await dispatchRegisteredJob({
+      registry,
+      job,
+      createContext: ({ control }) => createJobContext({ job, storedJob: job, taskName, payload: job.payload, control })
+    });
+    if (!dispatch.success) {
+      opts.onLog?.({ stage: "invalid_payload", taskName, error: dispatch.error ? formatJobError(dispatch.error) : "invalid payload" });
+      message.ack();
+      return { status: "dispatch-failed" };
+    }
+    if (dispatch.control?.action === "released") {
+      message.retry({ delaySeconds: dispatch.control.delaySeconds ?? 0 });
+      return { status: "released" };
+    }
+    message.ack();
+    return { status: "completed" };
+  } catch (error) {
+    const delaySeconds = resolveJobRetryDelay(definition, message.attempts);
+    opts.onLog?.({ stage: "unexpected", taskName, error: error instanceof Error ? error.message : String(error) });
+    message.retry({ delaySeconds });
+    return { status: "errored" };
+  }
+}
+function defaultIsDlqQueue(queue) {
+  return queue.includes("-dlq");
+}
+export async function consumeQueueBatch(opts) {
+  const isDlq = opts.isDlqQueue ?? defaultIsDlqQueue;
+  if (isDlq(opts.batch.queue)) {
+    for (const message of opts.batch.messages) {
+      const body = message.body ?? {};
+      const jobId = typeof body.jobId === "string" ? body.jobId : void 0;
+      opts.onLog?.({ stage: "dlq", queue: opts.batch.queue, taskName: typeof body._task === "string" ? body._task : void 0, jobId });
+      if (jobId) {
+        const claimed = await opts.repository.claimJob(jobId).catch(() => null);
+        if (claimed) {
+          await opts.repository.failJob(claimed, "Exhausted retries (dead-letter queue)").catch(() => {
+          });
+          await settleBatchMember({ store: opts.store, jobId, failed: true, dispatchOnFinish: opts.dispatchOnFinish }).then((r) => r.progress && opts.onBatchProgress ? opts.onBatchProgress(r.progress) : void 0).catch(() => {
+          });
+        }
+      }
+      message.ack();
+    }
+    return;
+  }
+  const batchStartedMs = Date.now();
+  const cpuBudget = opts.maxBatchCpuMs;
+  for (const message of opts.batch.messages) {
+    if (cpuBudget != null && Date.now() - batchStartedMs > cpuBudget) {
+      message.retry({ delaySeconds: opts.cpuGuardRetryDelaySeconds ?? 5 });
+      continue;
+    }
+    const body = message.body ?? {};
+    const jobId = typeof body.jobId === "string" ? body.jobId : void 0;
+    if (jobId) {
+      await runDurableJobBatchMessage({
+        message,
+        lifecycle: opts.repository,
+        registry: opts.registry,
+        store: opts.store,
+        toDispatchableJob: opts.repository.toDispatchableJob,
+        createJobContext: opts.createJobContext,
+        retryDelaySeconds: opts.retryDelaySeconds,
+        // Honour the stored job's attempt cap (Laravel worker model).
+        maxAttemptsOf: (stored) => stored.max_attempts,
+        createJobScope: opts.createJobScope,
+        isPermanentFailure: opts.isPermanentFailure,
+        dispatchContinuations: opts.dispatchContinuations,
+        dispatchOnFinish: opts.dispatchOnFinish,
+        onBatchProgress: opts.onBatchProgress
+      });
+    } else {
+      await runLightweightMessage({
+        message,
+        registry: opts.registry,
+        createJobContext: opts.createJobContext,
+        isDuplicate: opts.isDuplicate,
+        onLog: opts.onLog
+      });
+    }
+  }
+}
+const DEFAULT_DEDUP_CAPACITY = 1024;
+function makeIsDuplicate(seen) {
+  if (!seen)
+    return void 0;
+  return (id) => {
+    if (!id)
+      return false;
+    if (seen.has(id))
+      return true;
+    seen.add(id);
+    if (seen.size > DEFAULT_DEDUP_CAPACITY) {
+      const first = seen.values().next().value;
+      if (first !== void 0)
+        seen.delete(first);
+    }
+    return false;
+  };
+}
+export function createDurableJobsRuntime(opts) {
+  const repository = createD1DurableJobRepository(opts.db, {
+    reclaimAfterSeconds: opts.reclaimAfterSeconds,
+    ...opts.metricsSink ? metricsSinkToRepoHooks(opts.metricsSink) : {}
+  });
+  const store = createD1DurableBatchStore(opts.db);
+  const publisher = createQueuePublisher(
+    opts.env,
+    opts.resolveQueueBinding,
+    { onMissingBinding: opts.onMissingBinding }
+  );
+  const dispatchOnFinish = opts.dispatchOnFinish ?? (async ({ continuation, batch }) => {
+    const c = continuation;
+    try {
+      const record = await prepareDurableJob({ name: c.name, payload: c.payload, registry: opts.registry });
+      await enqueueDurableJob(repository, publisher, record);
+    } catch (error) {
+      opts.onLog?.({ stage: "onfinish-failed", taskName: c.name, jobId: batch.id, error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+  const isDuplicate = makeIsDuplicate(opts.dedup);
+  return {
+    repository,
+    store,
+    publisher,
+    enqueue: (record, enqueueOpts) => enqueueDurableJob(repository, publisher, record, enqueueOpts),
+    createBatch: (batchOpts) => createJobBatch({
+      store,
+      repository,
+      publisher,
+      ...batchOpts
+    }),
+    consumeMessage: (message) => runDurableJobBatchMessage({
+      message,
+      lifecycle: repository,
+      registry: opts.registry,
+      store,
+      toDispatchableJob: repository.toDispatchableJob,
+      createJobContext: opts.createJobContext,
+      retryDelaySeconds: opts.retryDelaySeconds,
+      maxAttemptsOf: (stored) => stored.max_attempts,
+      createJobScope: opts.createJobScope,
+      isPermanentFailure: opts.isPermanentFailure,
+      dispatchContinuations: opts.dispatchContinuations,
+      dispatchOnFinish,
+      onBatchProgress: opts.onBatchProgress
+    }),
+    consumeBatch: (batch) => consumeQueueBatch({
+      batch,
+      repository,
+      store,
+      registry: opts.registry,
+      createJobContext: opts.createJobContext,
+      dispatchOnFinish,
+      onBatchProgress: opts.onBatchProgress,
+      retryDelaySeconds: opts.retryDelaySeconds,
+      isDlqQueue: opts.isDlqQueue,
+      isDuplicate,
+      onLog: opts.onLog,
+      createJobScope: opts.createJobScope,
+      isPermanentFailure: opts.isPermanentFailure,
+      dispatchContinuations: opts.dispatchContinuations,
+      maxBatchCpuMs: opts.maxBatchCpuMs,
+      cpuGuardRetryDelaySeconds: opts.cpuGuardRetryDelaySeconds
+    }),
+    prune: (pruneOpts) => pruneDurableJobs(repository, pruneOpts)
+  };
+}

package/dist/runtime/server/schema.js

@@ -55,6 +55,7 @@ export const cfJobs = sqliteTable("jobs", {
   index("idx_jobs_batch").on(t.batchId),
   index("idx_jobs_trace").on(t.traceId),
   index("idx_jobs_sync_dedup").on(t.siteId, t.jobType),
+  index("idx_jobs_completed_at").on(t.completedAt).where(sql`completed_at IS NOT NULL`),
   uniqueIndex("idx_jobs_unique_active").on(t.uniqueKey).where(sql`unique_key IS NOT NULL AND completed_at IS NULL AND failed_at IS NULL`)
 ]);
 export const cfFailedJobs = sqliteTable("failed_jobs", {

package/dist/runtime/server/types.d.ts

@@ -60,6 +60,17 @@ export interface JobControlResult {
     delaySeconds?: number;
     error?: string;
 }
+/**
+ * Per-run execution stats a handler can report (rows touched, D1 reads/writes).
+ * Reported via {@link JobContext.reportStats}; the consumer persists them to the
+ * job row + forwards them to the metrics sink. Multiple calls accumulate (sum).
+ */
+export interface JobRunStats {
+    rowsFetched?: number;
+    rowsInserted?: number;
+    d1RowsRead?: number;
+    d1RowsWritten?: number;
+}
 export interface JobContext<Env, Db, Logger> {
     env: Env;
     jobId: string;
@@ -69,6 +80,12 @@ export interface JobContext<Env, Db, Logger> {
     log: Logger;
     release: (delaySeconds: number) => Promise<void>;
     fail: (error: string) => Promise<void>;
+    /**
+     * Report execution stats (rows fetched/inserted, D1 reads/writes) for metrics +
+     * observability. Injected by the durable consumer; optional so plain handlers
+     * and hand-built contexts need not provide it.
+     */
+    reportStats?: (stats: JobRunStats) => void;
 }
 export type JobHandler<Payload, Env, Db, Logger> = (payload: Payload, ctx: JobContext<Env, Db, Logger>) => Promise<void>;
 export type JobFailedHandler<Payload, Env, Db, Logger> = (payload: Payload, ctx: JobContext<Env, Db, Logger>, error: unknown) => Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "type": "module",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Nuxt module for typed Cloudflare queue jobs.",
   "author": {
     "name": "Harlan Wilton",
@@ -23,6 +23,11 @@
       "import": "./dist/runtime/server/index.js",
       "default": "./dist/runtime/server/index.js"
     },
+    "./cloudflare": {
+      "types": "./dist/runtime/server/cloudflare.d.ts",
+      "import": "./dist/runtime/server/cloudflare.js",
+      "default": "./dist/runtime/server/cloudflare.js"
+    },
     "./d1": {
       "types": "./dist/runtime/server/d1.d.ts",
       "import": "./dist/runtime/server/d1.js",
@@ -46,6 +51,9 @@
       "server": [
         "dist/runtime/server/index.d.ts"
       ],
+      "cloudflare": [
+        "dist/runtime/server/cloudflare.d.ts"
+      ],
       "d1": [
         "dist/runtime/server/d1.d.ts"
       ],