@storyshelf/core 0.6.2 → 0.8.0

package/dist/capture/consumer/index.mjs

@@ -0,0 +1,138 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { createShelfLogger } from "../../logger.mjs";
+import { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, backoffDelayMs, isFinalAttempt } from "./retry.mjs";
+import { REAL_TIMERS } from "../db-queue/timers.mjs";
+import { startPollLoop } from "../db-queue/poll-loop.mjs";
+import { recommendedBuildConcurrency } from "../../utils/resources.mjs";
+import { captureDispatchDeps, createCaptureHandler } from "./capture-handler.mjs";
+import { MIN_BLOCKING_POLL_MS, idleDelayMs, isFastEmptyPoll } from "./idle.mjs";
+import { startSlotLoop } from "./loop.mjs";
+import { DEFAULT_SAMPLE_MS, sampleQueue, startQueueSampling } from "./metrics.mjs";
+import { runJob } from "./run-job.mjs";
+import { applyImageSettings, ensureImageEngine, sweepScratch } from "./startup.mjs";
+// src/capture/consumer/index.ts
+/** Create a consumer of `options.queue`; nothing runs until `start()`. */
+function createCaptureConsumer(options) {
+	applyImageSettings(options.images, options.compare);
+	const logger = options.logger ?? createShelfLogger();
+	options.queue.setLogger?.(logger.child({ component: options.queue.metadata.kind }));
+	const rt = buildRuntime(options, logger);
+	const slots = options.config?.concurrency ?? recommendedBuildConcurrency();
+	let session = null;
+	let requestStop = null;
+	let stopRequested = false;
+	return {
+		isRunning: () => session !== null,
+		start: async () => {
+			if (session !== null) return;
+			const stopped = Promise.withResolvers();
+			stopRequested = false;
+			requestStop = () => {
+				stopRequested = true;
+				stopped.resolve(null);
+			};
+			session = consume({
+				options,
+				rt,
+				slots,
+				stopped: stopped.promise,
+				isStopped: () => stopRequested
+			});
+			await session.finally(() => {
+				session = null;
+			});
+		},
+		stop: async () => {
+			requestStop?.();
+			await session?.catch(() => {});
+		}
+	};
+}
+/** One start-to-drain session: sweep, check the engine, poll until stopped, drain. */
+async function consume(c) {
+	const { options, rt } = c;
+	const sweep = sweepScratch(options.scratchDir ?? options.capture?.scratchDir, rt.logger);
+	try {
+		await ensureImageEngine(rt.logger);
+		if (!c.isStopped()) await pollUntilStopped(c);
+	} finally {
+		await sweep;
+	}
+}
+/** Poll (and sample the queue) until `stop()`, then drain the jobs in flight. */
+async function pollUntilStopped(c) {
+	const { options, rt } = c;
+	const loop = startLoop(c);
+	const stopSampling = startQueueSampling(options.queue, options.metrics, {
+		now: rt.now,
+		timers: rt.timers ?? REAL_TIMERS,
+		logger: rt.logger
+	});
+	await c.stopped;
+	stopSampling();
+	await loop.stop();
+}
+/** The database queue sets its own cadence; any other queue is polled in a slot loop. */
+function startLoop(c) {
+	const { options, rt } = c;
+	const run = async (job) => {
+		await runJob(rt, job);
+	};
+	if (isDatabaseQueue(options.queue)) return startPollLoop({
+		queue: options.queue,
+		slots: c.slots,
+		run,
+		logger: rt.logger,
+		now: rt.now,
+		...options.cadence === void 0 ? {} : { cadence: options.cadence },
+		...options.random === void 0 ? {} : { random: options.random }
+	});
+	const waitSeconds = options.config?.waitTimeSeconds ?? 20;
+	return startSlotLoop({
+		queue: options.queue,
+		slots: c.slots,
+		waitMs: waitSeconds * 1e3,
+		run,
+		logger: rt.logger,
+		now: rt.now,
+		timers: options.timers
+	});
+}
+function isDatabaseQueue(queue) {
+	return typeof queue.waitForWork === "function";
+}
+function buildRuntime(options, logger) {
+	return {
+		queue: options.queue,
+		handlers: registry(options, logger),
+		maxRetries: options.config?.maxRetries ?? 2,
+		backoffMs: options.config?.backoffMs ?? 1e3,
+		logger,
+		metrics: options.metrics,
+		onProgress: options.onProgress,
+		now: options.now ?? Date.now,
+		timers: options.timers,
+		lease: options.lease
+	};
+}
+/** `capture` wired to the core dispatch, then the explicit handlers on top. */
+function registry(options, logger) {
+	const all = {};
+	if (options.capture !== void 0) all.capture = createCaptureHandler({
+		enqueue: async (job) => {
+			await options.queue.enqueue(job);
+		},
+		maxRetries: options.config?.maxRetries,
+		...options.capture,
+		logger
+	});
+	Object.assign(all, options.handlers);
+	const map = /* @__PURE__ */ new Map();
+	for (const [kind, handler] of Object.entries(all)) if (handler !== void 0) map.set(kind, typeof handler === "function" ? { run: handler } : handler);
+	return map;
+}
+export { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_SAMPLE_MS, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, MIN_BLOCKING_POLL_MS, backoffDelayMs, captureDispatchDeps, createCaptureConsumer, createCaptureHandler, idleDelayMs, isFastEmptyPoll, isFinalAttempt, sampleQueue };
+
+//# sourceMappingURL=index.mjs.map

package/dist/capture/consumer/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/capture/consumer/index.ts"],"sourcesContent":["/**\n * The capture consumer (ADR 0006, decisions 4 and 11): consumes any `PollableCaptureQueue` (the\n * database queue, the IPC queue of a forked capture child) and runs a handler per\n * job `kind`. A slot is taken before polling, a failing job is retried with exponential backoff\n * until its last attempt, the lease is kept by the job's progress, a lost lease or a cancel stops\n * the run, and `stop()` drains the jobs in flight.\n *\n * ```ts\n * const consumer = createCaptureConsumer({\n *   queue: createDatabaseCaptureQueue(db),\n *   capture: { db, storage, runner, scratchDir },\n *   config: { concurrency: 2 },\n * });\n * consumer.start(); // resolves after stop()\n * // on SIGTERM: await consumer.stop();\n * ```\n */\nimport type { PollableCaptureQueue } from \"../../adapters/capture-queue.ts\";\nimport { createShelfLogger, type Logger } from \"../../logger.ts\";\nimport { recommendedBuildConcurrency } from \"../../utils/resources.ts\";\nimport { startPollLoop, type PollLoop } from \"../db-queue/poll-loop.ts\";\nimport { REAL_TIMERS } from \"../db-queue/timers.ts\";\nimport type { DatabaseCaptureQueue } from \"../db-queue/types.ts\";\nimport { createCaptureHandler } from \"./capture-handler.ts\";\nimport { startSlotLoop } from \"./loop.ts\";\nimport { startQueueSampling } from \"./metrics.ts\";\nimport { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS } from \"./retry.ts\";\nimport { runJob, type JobRuntime } from \"./run-job.ts\";\nimport { applyImageSettings, ensureImageEngine, sweepScratch } from \"./startup.ts\";\nimport type {\n  CaptureConsumer,\n  CaptureConsumerOptions,\n  ConsumerJob,\n  JobHandlers,\n  KindHandler,\n} from \"./types.ts\";\n\n/** Create a consumer of `options.queue`; nothing runs until `start()`. */\nexport function createCaptureConsumer(options: CaptureConsumerOptions): CaptureConsumer {\n  applyImageSettings(options.images, options.compare);\n  const logger = options.logger ?? createShelfLogger();\n  options.queue.setLogger?.(logger.child({ component: options.queue.metadata.kind }));\n  const rt = buildRuntime(options, logger);\n  const slots = options.config?.concurrency ?? recommendedBuildConcurrency();\n  let session: Promise<void> | null = null;\n  let requestStop: (() => void) | null = null;\n  let stopRequested = false;\n  return {\n    isRunning: () => session !== null,\n    start: async () => {\n      if (session !== null) {\n        return;\n      }\n      const stopped = Promise.withResolvers<null>();\n      stopRequested = false;\n      requestStop = (): void => {\n        stopRequested = true;\n        stopped.resolve(null);\n      };\n      session = consume({\n        options,\n        rt,\n        slots,\n        stopped: stopped.promise,\n        isStopped: () => stopRequested,\n      });\n      await session.finally(() => {\n        session = null;\n      });\n    },\n    stop: async () => {\n      requestStop?.();\n      await session?.catch(() => {});\n    },\n  };\n}\n\ninterface Consuming {\n  options: CaptureConsumerOptions;\n  rt: JobRuntime;\n  slots: number;\n  /** Resolves when `stop()` was called. */\n  stopped: Promise<null>;\n  isStopped: () => boolean;\n}\n\n/** One start-to-drain session: sweep, check the engine, poll until stopped, drain. */\nasync function consume(c: Consuming): Promise<void> {\n  const { options, rt } = c;\n  const sweep = sweepScratch(options.scratchDir ?? options.capture?.scratchDir, rt.logger);\n  try {\n    await ensureImageEngine(rt.logger);\n    if (!c.isStopped()) {\n      await pollUntilStopped(c);\n    }\n  } finally {\n    await sweep;\n  }\n}\n\n/** Poll (and sample the queue) until `stop()`, then drain the jobs in flight. */\nasync function pollUntilStopped(c: Consuming): Promise<void> {\n  const { options, rt } = c;\n  const loop = startLoop(c);\n  const stopSampling = startQueueSampling(options.queue, options.metrics, {\n    now: rt.now,\n    timers: rt.timers ?? REAL_TIMERS,\n    logger: rt.logger,\n  });\n  await c.stopped;\n  stopSampling();\n  await loop.stop();\n}\n\n/** The database queue sets its own cadence; any other queue is polled in a slot loop. */\nfunction startLoop(c: Consuming): PollLoop {\n  const { options, rt } = c;\n  const run = async (job: ConsumerJob): Promise<void> => {\n    await runJob(rt, job);\n  };\n  if (isDatabaseQueue(options.queue)) {\n    return startPollLoop({\n      queue: options.queue,\n      slots: c.slots,\n      run,\n      logger: rt.logger,\n      now: rt.now,\n      ...(options.cadence === undefined ? {} : { cadence: options.cadence }),\n      ...(options.random === undefined ? {} : { random: options.random }),\n    });\n  }\n  const waitSeconds = options.config?.waitTimeSeconds ?? DEFAULT_WAIT_TIME_SECONDS;\n  return startSlotLoop({\n    queue: options.queue,\n    slots: c.slots,\n    waitMs: waitSeconds * 1000,\n    run,\n    logger: rt.logger,\n    now: rt.now,\n    timers: options.timers,\n  });\n}\n\nfunction isDatabaseQueue(queue: PollableCaptureQueue): queue is DatabaseCaptureQueue {\n  return typeof (queue as Partial<DatabaseCaptureQueue>).waitForWork === \"function\";\n}\n\nfunction buildRuntime(options: CaptureConsumerOptions, logger: Logger): JobRuntime {\n  return {\n    queue: options.queue,\n    handlers: registry(options, logger),\n    maxRetries: options.config?.maxRetries ?? DEFAULT_MAX_RETRIES,\n    backoffMs: options.config?.backoffMs ?? DEFAULT_BACKOFF_MS,\n    logger,\n    metrics: options.metrics,\n    onProgress: options.onProgress,\n    now: options.now ?? Date.now,\n    timers: options.timers,\n    lease: options.lease,\n  };\n}\n\n/** `capture` wired to the core dispatch, then the explicit handlers on top. */\nfunction registry(options: CaptureConsumerOptions, logger: Logger): Map<string, KindHandler> {\n  const all: JobHandlers = {};\n  if (options.capture !== undefined) {\n    all.capture = createCaptureHandler({\n      enqueue: async (job) => {\n        await options.queue.enqueue(job);\n      },\n      maxRetries: options.config?.maxRetries,\n      ...options.capture,\n      logger,\n    });\n  }\n  Object.assign(all, options.handlers);\n  const map = new Map<string, KindHandler>();\n  for (const [kind, handler] of Object.entries(all)) {\n    if (handler !== undefined) {\n      map.set(kind, typeof handler === \"function\" ? { run: handler } : handler);\n    }\n  }\n  return map;\n}\n\nexport {\n  captureDispatchDeps,\n  createCaptureHandler,\n  type CaptureHandlerOptions,\n} from \"./capture-handler.ts\";\nexport { idleDelayMs, isFastEmptyPoll, MIN_BLOCKING_POLL_MS } from \"./idle.ts\";\nexport {\n  DEFAULT_SAMPLE_MS,\n  sampleQueue,\n  type ConsumerMetrics,\n  type JobFinishedEvent,\n  type JobOutcome,\n  type QueueSample,\n} from \"./metrics.ts\";\nexport {\n  backoffDelayMs,\n  DEFAULT_BACKOFF_MS,\n  DEFAULT_MAX_RETRIES,\n  DEFAULT_WAIT_TIME_SECONDS,\n  isFinalAttempt,\n  MAX_BACKOFF_MS,\n  type RetryConfig,\n} from \"./retry.ts\";\nexport type {\n  CaptureConsumer,\n  CaptureConsumerOptions,\n  ConsumerConfig,\n  ConsumerJob,\n  JobHandlers,\n  JobRunContext,\n  KindHandler,\n} from \"./types.ts\";\n"],"mappings":"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"}

package/dist/capture/consumer/loop.mjs

@@ -0,0 +1,109 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { REAL_TIMERS } from "../db-queue/timers.mjs";
+import { idleDelayMs, isFastEmptyPoll } from "./idle.mjs";
+// src/capture/consumer/loop.ts
+/** Pause after a failed poll. */
+const POLL_ERROR_DELAY_MS = 1e3;
+/** Start consuming `queue` with `slots` concurrent jobs. */
+function startSlotLoop(options) {
+	const state = {
+		busy: 0,
+		stopped: false,
+		emptyStreak: 0,
+		inFlight: /* @__PURE__ */ new Set(),
+		nudge: () => {}
+	};
+	const done = loop(options, state);
+	return {
+		get busy() {
+			return state.busy;
+		},
+		stop: async () => {
+			state.stopped = true;
+			state.nudge();
+			await done;
+			await Promise.allSettled(state.inFlight);
+		}
+	};
+}
+async function loop(options, state) {
+	while (!state.stopped) await step(options, state);
+}
+async function step(options, state) {
+	if (state.busy >= options.slots) {
+		await sleep(state, options.timers, null);
+		return;
+	}
+	state.busy += 1;
+	const polled = await pollTimed(options, state);
+	if (polled.job === null) {
+		state.busy -= 1;
+		await afterEmpty(options, state, polled.elapsedMs);
+	} else {
+		state.emptyStreak = 0;
+		launch(options, state, polled.job);
+	}
+}
+/** One poll with its duration; `elapsedMs` is null when the poll failed. */
+async function pollTimed(options, state) {
+	const now = options.now ?? Date.now;
+	const startedAt = now();
+	const job = await pollOnce(options, state);
+	return job === void 0 ? {
+		job: null,
+		elapsedMs: null
+	} : {
+		job,
+		elapsedMs: now() - startedAt
+	};
+}
+/** Back off after an empty poll that did not block, or after a failed one (`elapsed` null). */
+async function afterEmpty(options, state, elapsedMs) {
+	if (elapsedMs === null) {
+		await sleep(state, options.timers, POLL_ERROR_DELAY_MS);
+		return;
+	}
+	state.emptyStreak = isFastEmptyPoll(elapsedMs) ? state.emptyStreak + 1 : 0;
+	if (state.emptyStreak > 0) await sleep(state, options.timers, idleDelayMs(state.emptyStreak));
+}
+/** The next job, null when empty, undefined when the poll failed (logged). */
+async function pollOnce(options, state) {
+	if (state.stopped) return null;
+	try {
+		return await options.queue.poll({ waitMs: options.waitMs });
+	} catch (error) {
+		options.logger.error({ err: error }, "poll failed");
+		return;
+	}
+}
+function launch(options, state, job) {
+	const running = options.run(job).catch((error) => {
+		options.logger.error({
+			err: error,
+			buildId: job.buildId
+		}, "job run failed");
+	}).finally(() => {
+		state.busy -= 1;
+		state.inFlight.delete(running);
+		state.nudge();
+	});
+	state.inFlight.add(running);
+}
+/** Wait for `ms` (or, without one, for a nudge); a nudge (slot freed, stop) ends it early. */
+async function sleep(state, timers, ms) {
+	if (state.stopped) return;
+	const { promise, resolve } = Promise.withResolvers();
+	const wake = () => {
+		resolve(null);
+	};
+	const clock = timers ?? REAL_TIMERS;
+	const handle = ms === null ? null : clock.setTimeout(wake, ms);
+	state.nudge = wake;
+	await promise;
+	if (handle !== null) clock.clearTimeout(handle);
+}
+export { POLL_ERROR_DELAY_MS, startSlotLoop };
+
+//# sourceMappingURL=loop.mjs.map

package/dist/capture/consumer/loop.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.mjs","names":[],"sources":["../../../src/capture/consumer/loop.ts"],"sourcesContent":["/**\n * The slot-aware poll loop for queues that are not the database queue: a slot is taken BEFORE\n * polling (polling first would leave a job idle while every slot is busy, and its lease, a remote\n * queue's visibility or the forked parent's progress lease, would run out), polls block inside the\n * queue where they can, and an empty poll that returns at once backs off instead of spinning.\n */\nimport type { PollableCaptureQueue } from \"../../adapters/capture-queue.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport type { PollLoop } from \"../db-queue/poll-loop.ts\";\nimport { REAL_TIMERS, type QueueTimers } from \"../db-queue/timers.ts\";\nimport { idleDelayMs, isFastEmptyPoll } from \"./idle.ts\";\nimport type { ConsumerJob } from \"./types.ts\";\n\n/** Pause after a failed poll. */\nexport const POLL_ERROR_DELAY_MS = 1000;\n\n/** Options of {@link startSlotLoop}. */\nexport interface SlotLoopOptions {\n  queue: PollableCaptureQueue;\n  slots: number;\n  /** Long-poll wait handed to `poll`. */\n  waitMs: number;\n  /** Run one claimed job to its end; must not reject. */\n  run: (job: ConsumerJob) => Promise<void>;\n  logger: Logger;\n  now?: () => number;\n  timers?: QueueTimers;\n}\n\ninterface LoopState {\n  busy: number;\n  stopped: boolean;\n  emptyStreak: number;\n  inFlight: Set<Promise<void>>;\n  /** Resolves the current wait (slot freed, backoff sleep, stop) early. */\n  nudge: () => void;\n}\n\n/** Start consuming `queue` with `slots` concurrent jobs. */\nexport function startSlotLoop(options: SlotLoopOptions): PollLoop {\n  const state: LoopState = {\n    busy: 0,\n    stopped: false,\n    emptyStreak: 0,\n    inFlight: new Set(),\n    nudge: () => {},\n  };\n  const done = loop(options, state);\n  return {\n    get busy() {\n      return state.busy;\n    },\n    stop: async () => {\n      state.stopped = true;\n      state.nudge();\n      await done;\n      await Promise.allSettled(state.inFlight);\n    },\n  };\n}\n\nasync function loop(options: SlotLoopOptions, state: LoopState): Promise<void> {\n  while (!state.stopped) {\n    // oxlint-disable-next-line no-await-in-loop -- one step at a time is the loop\n    await step(options, state);\n  }\n}\n\nasync function step(options: SlotLoopOptions, state: LoopState): Promise<void> {\n  if (state.busy >= options.slots) {\n    await sleep(state, options.timers, null);\n    return;\n  }\n  // The slot is held from here: released again unless a job came back to run in it.\n  state.busy += 1;\n  const polled = await pollTimed(options, state);\n  if (polled.job === null) {\n    state.busy -= 1;\n    await afterEmpty(options, state, polled.elapsedMs);\n  } else {\n    state.emptyStreak = 0;\n    launch(options, state, polled.job);\n  }\n}\n\n/** One poll with its duration; `elapsedMs` is null when the poll failed. */\nasync function pollTimed(\n  options: SlotLoopOptions,\n  state: LoopState,\n): Promise<{ job: ConsumerJob | null; elapsedMs: number | null }> {\n  const now = options.now ?? Date.now;\n  const startedAt = now();\n  const job = await pollOnce(options, state);\n  return job === undefined ? { job: null, elapsedMs: null } : { job, elapsedMs: now() - startedAt };\n}\n\n/** Back off after an empty poll that did not block, or after a failed one (`elapsed` null). */\nasync function afterEmpty(\n  options: SlotLoopOptions,\n  state: LoopState,\n  elapsedMs: number | null,\n): Promise<void> {\n  if (elapsedMs === null) {\n    await sleep(state, options.timers, POLL_ERROR_DELAY_MS);\n    return;\n  }\n  // Queues without long-poll return instantly; back off instead of spinning.\n  state.emptyStreak = isFastEmptyPoll(elapsedMs) ? state.emptyStreak + 1 : 0;\n  if (state.emptyStreak > 0) {\n    await sleep(state, options.timers, idleDelayMs(state.emptyStreak));\n  }\n}\n\n/** The next job, null when empty, undefined when the poll failed (logged). */\nasync function pollOnce(\n  options: SlotLoopOptions,\n  state: LoopState,\n): Promise<ConsumerJob | null | undefined> {\n  if (state.stopped) {\n    return null;\n  }\n  try {\n    return await options.queue.poll({ waitMs: options.waitMs });\n  } catch (error) {\n    options.logger.error({ err: error }, \"poll failed\");\n    return undefined;\n  }\n}\n\nfunction launch(options: SlotLoopOptions, state: LoopState, job: ConsumerJob): void {\n  const running = options\n    .run(job)\n    .catch((error: unknown) => {\n      options.logger.error({ err: error, buildId: job.buildId }, \"job run failed\");\n    })\n    .finally(() => {\n      state.busy -= 1;\n      state.inFlight.delete(running);\n      state.nudge();\n    });\n  state.inFlight.add(running);\n}\n\n/** Wait for `ms` (or, without one, for a nudge); a nudge (slot freed, stop) ends it early. */\nasync function sleep(\n  state: LoopState,\n  timers: QueueTimers | undefined,\n  ms: number | null,\n): Promise<void> {\n  if (state.stopped) {\n    return;\n  }\n  const { promise, resolve } = Promise.withResolvers<null>();\n  const wake = (): void => {\n    resolve(null);\n  };\n  const clock = timers ?? REAL_TIMERS;\n  const handle = ms === null ? null : clock.setTimeout(wake, ms);\n  state.nudge = wake;\n  await promise;\n  if (handle !== null) {\n    clock.clearTimeout(handle);\n  }\n}\n"],"mappings":";;;;;;;AAcA,MAAa,sBAAsB;;AAyBnC,SAAgB,cAAc,SAAoC;CAChE,MAAM,QAAmB;EACvB,MAAM;EACN,SAAS;EACT,aAAa;EACb,0BAAU,IAAI,IAAI;EAClB,aAAa,CAAC;CAChB;CACA,MAAM,OAAO,KAAK,SAAS,KAAK;CAChC,OAAO;EACL,IAAI,OAAO;GACT,OAAO,MAAM;EACf;EACA,MAAM,YAAY;GAChB,MAAM,UAAU;GAChB,MAAM,MAAM;GACZ,MAAM;GACN,MAAM,QAAQ,WAAW,MAAM,QAAQ;EACzC;CACF;AACF;AAEA,eAAe,KAAK,SAA0B,OAAiC;CAC7E,OAAO,CAAC,MAAM,SAEZ,MAAM,KAAK,SAAS,KAAK;AAE7B;AAEA,eAAe,KAAK,SAA0B,OAAiC;CAC7E,IAAI,MAAM,QAAQ,QAAQ,OAAO;EAC/B,MAAM,MAAM,OAAO,QAAQ,QAAQ,IAAI;EACvC;CACF;CAEA,MAAM,QAAQ;CACd,MAAM,SAAS,MAAM,UAAU,SAAS,KAAK;CAC7C,IAAI,OAAO,QAAQ,MAAM;EACvB,MAAM,QAAQ;EACd,MAAM,WAAW,SAAS,OAAO,OAAO,SAAS;CACnD,OAAO;EACL,MAAM,cAAc;EACpB,OAAO,SAAS,OAAO,OAAO,GAAG;CACnC;AACF;;AAGA,eAAe,UACb,SACA,OACgE;CAChE,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,YAAY,IAAI;CACtB,MAAM,MAAM,MAAM,SAAS,SAAS,KAAK;CACzC,OAAO,QAAQ,KAAA,IAAY;EAAE,KAAK;EAAM,WAAW;CAAK,IAAI;EAAE;EAAK,WAAW,IAAI,IAAI;CAAU;AAClG;;AAGA,eAAe,WACb,SACA,OACA,WACe;CACf,IAAI,cAAc,MAAM;EACtB,MAAM,MAAM,OAAO,QAAQ,QAAQ,mBAAmB;EACtD;CACF;CAEA,MAAM,cAAc,gBAAgB,SAAS,IAAI,MAAM,cAAc,IAAI;CACzE,IAAI,MAAM,cAAc,GACtB,MAAM,MAAM,OAAO,QAAQ,QAAQ,YAAY,MAAM,WAAW,CAAC;AAErE;;AAGA,eAAe,SACb,SACA,OACyC;CACzC,IAAI,MAAM,SACR,OAAO;CAET,IAAI;EACF,OAAO,MAAM,QAAQ,MAAM,KAAK,EAAE,QAAQ,QAAQ,OAAO,CAAC;CAC5D,SAAS,OAAO;EACd,QAAQ,OAAO,MAAM,EAAE,KAAK,MAAM,GAAG,aAAa;EAClD;CACF;AACF;AAEA,SAAS,OAAO,SAA0B,OAAkB,KAAwB;CAClF,MAAM,UAAU,QACb,IAAI,GAAG,CAAC,CACR,OAAO,UAAmB;EACzB,QAAQ,OAAO,MAAM;GAAE,KAAK;GAAO,SAAS,IAAI;EAAQ,GAAG,gBAAgB;CAC7E,CAAC,CAAC,CACD,cAAc;EACb,MAAM,QAAQ;EACd,MAAM,SAAS,OAAO,OAAO;EAC7B,MAAM,MAAM;CACd,CAAC;CACH,MAAM,SAAS,IAAI,OAAO;AAC5B;;AAGA,eAAe,MACb,OACA,QACA,IACe;CACf,IAAI,MAAM,SACR;CAEF,MAAM,EAAE,SAAS,YAAY,QAAQ,cAAoB;CACzD,MAAM,aAAmB;EACvB,QAAQ,IAAI;CACd;CACA,MAAM,QAAQ,UAAU;CACxB,MAAM,SAAS,OAAO,OAAO,OAAO,MAAM,WAAW,MAAM,EAAE;CAC7D,MAAM,QAAQ;CACd,MAAM;CACN,IAAI,WAAW,MACb,MAAM,aAAa,MAAM;AAE7B"}

package/dist/capture/consumer/metrics.d.mts

@@ -0,0 +1,39 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "../../logger.mjs";
+import { PollableCaptureQueue } from "../../adapter/capture-queue.mjs";
+import { CaptureJobKind } from "../../schema/capture-job.mjs";
+/** How a consumed job ended. */
+type JobOutcome = "completed" | "retried" | "failed" | "cancelled" | "lost" | "dropped" | "unhandled";
+/** A job the consumer finished with. */
+interface JobFinishedEvent {
+  kind: CaptureJobKind;
+  outcome: JobOutcome;
+  /** Wall time from claim to settle. */
+  durationMs: number;
+  /** Delivery number from 1. */
+  attempt: number;
+}
+/** A reading of the queue's backlog. */
+interface QueueSample {
+  /** Jobs waiting to be claimed. */
+  depth: number;
+  /** Jobs running anywhere. */
+  running: number;
+  /** Age of the oldest waiting job; 0 when none waits. */
+  oldestAgeMs: number;
+}
+/** Hooks the host may pass. Both are optional and must not throw. */
+interface ConsumerMetrics {
+  jobFinished?(event: JobFinishedEvent): void;
+  /** Called every `sampleEveryMs` with the queue's depth and oldest waiting job. Costs one read. */
+  queueSample?(sample: QueueSample): void;
+  /** Sampling interval (default {@link DEFAULT_SAMPLE_MS}); sampling is off without `queueSample`. */
+  sampleEveryMs?: number;
+}
+/** Default interval between queue samples. */
+declare const DEFAULT_SAMPLE_MS = 30000;
+/** Read the backlog of `queue` from its `active()` view. */
+declare function sampleQueue(queue: PollableCaptureQueue, now: number): Promise<QueueSample>;
+export { ConsumerMetrics, DEFAULT_SAMPLE_MS, JobFinishedEvent, JobOutcome, QueueSample, sampleQueue };
+//# sourceMappingURL=metrics.d.mts.map

package/dist/capture/consumer/metrics.mjs

@@ -0,0 +1,37 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { repeatEvery } from "../db-queue/timers.mjs";
+// src/capture/consumer/metrics.ts
+/** Default interval between queue samples. */
+const DEFAULT_SAMPLE_MS = 3e4;
+/** Read the backlog of `queue` from its `active()` view. */
+async function sampleQueue(queue, now) {
+	const entries = await queue.active();
+	const waiting = entries.filter((entry) => entry.status === "queued");
+	let oldest = Number.POSITIVE_INFINITY;
+	for (const entry of waiting) oldest = Math.min(oldest, Date.parse(entry.queuedAt));
+	return {
+		depth: waiting.length,
+		running: entries.length - waiting.length,
+		oldestAgeMs: waiting.length === 0 ? 0 : Math.max(0, now - oldest)
+	};
+}
+/** Start sampling when the host asked for it; returns the stop function. */
+function startQueueSampling(queue, metrics, env) {
+	if (metrics?.queueSample === void 0) return () => {};
+	return repeatEvery(env.timers, metrics.sampleEveryMs ?? 3e4, () => {
+		sampleQueue(queue, env.now()).then((sample) => metrics.queueSample?.(sample), (error) => {
+			env.logger.warn({ err: error }, "queue sample failed");
+		});
+	});
+}
+/** Tell the host a job ended; a throwing hook never reaches the consumer. */
+function reportFinished(metrics, event) {
+	try {
+		metrics?.jobFinished?.(event);
+	} catch {}
+}
+export { DEFAULT_SAMPLE_MS, reportFinished, sampleQueue, startQueueSampling };
+
+//# sourceMappingURL=metrics.mjs.map

package/dist/capture/consumer/metrics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.mjs","names":[],"sources":["../../../src/capture/consumer/metrics.ts"],"sourcesContent":["/**\n * Optional observation hooks of the consumer. Core owns no metrics library (the single OTEL owner is\n * `@storyshelf/observability`); the app adapts these two callbacks to its instruments.\n */\nimport type { PollableCaptureQueue } from \"../../adapters/capture-queue.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport type { CaptureJobKind } from \"../../schema/capture-job.ts\";\nimport { repeatEvery, type QueueTimers } from \"../db-queue/timers.ts\";\n\n/** How a consumed job ended. */\nexport type JobOutcome =\n  | \"completed\"\n  | \"retried\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"lost\"\n  | \"dropped\"\n  | \"unhandled\";\n\n/** A job the consumer finished with. */\nexport interface JobFinishedEvent {\n  kind: CaptureJobKind;\n  outcome: JobOutcome;\n  /** Wall time from claim to settle. */\n  durationMs: number;\n  /** Delivery number from 1. */\n  attempt: number;\n}\n\n/** A reading of the queue's backlog. */\nexport interface QueueSample {\n  /** Jobs waiting to be claimed. */\n  depth: number;\n  /** Jobs running anywhere. */\n  running: number;\n  /** Age of the oldest waiting job; 0 when none waits. */\n  oldestAgeMs: number;\n}\n\n/** Hooks the host may pass. Both are optional and must not throw. */\nexport interface ConsumerMetrics {\n  jobFinished?(event: JobFinishedEvent): void;\n  /** Called every `sampleEveryMs` with the queue's depth and oldest waiting job. Costs one read. */\n  queueSample?(sample: QueueSample): void;\n  /** Sampling interval (default {@link DEFAULT_SAMPLE_MS}); sampling is off without `queueSample`. */\n  sampleEveryMs?: number;\n}\n\n/** Default interval between queue samples. */\nexport const DEFAULT_SAMPLE_MS = 30_000;\n\n/** Read the backlog of `queue` from its `active()` view. */\nexport async function sampleQueue(queue: PollableCaptureQueue, now: number): Promise<QueueSample> {\n  const entries = await queue.active();\n  const waiting = entries.filter((entry) => entry.status === \"queued\");\n  let oldest = Number.POSITIVE_INFINITY;\n  for (const entry of waiting) {\n    oldest = Math.min(oldest, Date.parse(entry.queuedAt));\n  }\n  return {\n    depth: waiting.length,\n    running: entries.length - waiting.length,\n    oldestAgeMs: waiting.length === 0 ? 0 : Math.max(0, now - oldest),\n  };\n}\n\n/** Start sampling when the host asked for it; returns the stop function. */\nexport function startQueueSampling(\n  queue: PollableCaptureQueue,\n  metrics: ConsumerMetrics | undefined,\n  env: { now: () => number; timers: QueueTimers; logger: Logger },\n): () => void {\n  if (metrics?.queueSample === undefined) {\n    return () => {};\n  }\n  return repeatEvery(env.timers, metrics.sampleEveryMs ?? DEFAULT_SAMPLE_MS, () => {\n    sampleQueue(queue, env.now()).then(\n      (sample) => metrics.queueSample?.(sample),\n      (error: unknown) => {\n        env.logger.warn({ err: error }, \"queue sample failed\");\n      },\n    );\n  });\n}\n\n/** Tell the host a job ended; a throwing hook never reaches the consumer. */\nexport function reportFinished(\n  metrics: ConsumerMetrics | undefined,\n  event: JobFinishedEvent,\n): void {\n  try {\n    metrics?.jobFinished?.(event);\n  } catch {\n    // A metrics hook must never break job handling.\n  }\n}\n"],"mappings":";;;;;;AAiDA,MAAa,oBAAoB;;AAGjC,eAAsB,YAAY,OAA6B,KAAmC;CAChG,MAAM,UAAU,MAAM,MAAM,OAAO;CACnC,MAAM,UAAU,QAAQ,QAAQ,UAAU,MAAM,WAAW,QAAQ;CACnE,IAAI,SAAS,OAAO;CACpB,KAAK,MAAM,SAAS,SAClB,SAAS,KAAK,IAAI,QAAQ,KAAK,MAAM,MAAM,QAAQ,CAAC;CAEtD,OAAO;EACL,OAAO,QAAQ;EACf,SAAS,QAAQ,SAAS,QAAQ;EAClC,aAAa,QAAQ,WAAW,IAAI,IAAI,KAAK,IAAI,GAAG,MAAM,MAAM;CAClE;AACF;;AAGA,SAAgB,mBACd,OACA,SACA,KACY;CACZ,IAAI,SAAS,gBAAgB,KAAA,GAC3B,aAAa,CAAC;CAEhB,OAAO,YAAY,IAAI,QAAQ,QAAQ,iBAAA,WAA0C;EAC/E,YAAY,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,MAC3B,WAAW,QAAQ,cAAc,MAAM,IACvC,UAAmB;GAClB,IAAI,OAAO,KAAK,EAAE,KAAK,MAAM,GAAG,qBAAqB;EACvD,CACF;CACF,CAAC;AACH;;AAGA,SAAgB,eACd,SACA,OACM;CACN,IAAI;EACF,SAAS,cAAc,KAAK;CAC9B,QAAQ,CAER;AACF"}

package/dist/capture/consumer/retry.d.mts

@@ -0,0 +1,31 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { PollableJob } from "../../adapter/capture-queue.mjs";
+/** Retries after the first attempt before a job is failed for good (three attempts in total). */
+declare const DEFAULT_MAX_RETRIES = 2;
+/** Base of the exponential retry delay: the n-th retry waits `base * 2^n` ms. */
+declare const DEFAULT_BACKOFF_MS = 1000;
+/** Longest a retry waits, however many attempts were made. */
+declare const MAX_BACKOFF_MS = 30000;
+/** Long-poll wait handed to queues that block inside `poll` (SQS, Redis, Service Bus, IPC). */
+declare const DEFAULT_WAIT_TIME_SECONDS = 20;
+/** Retry knobs of the consumer. */
+interface RetryConfig {
+  /** Retries after the first attempt (default {@link DEFAULT_MAX_RETRIES}). */
+  maxRetries?: number;
+  /** Base delay of the exponential backoff in ms (default {@link DEFAULT_BACKOFF_MS}). */
+  backoffMs?: number;
+}
+/** Delay before retry number `attempts` (0 = the first retry): `base * 2^attempts`, capped. */
+declare function backoffDelayMs(attempts: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Whether this delivery is the job's last. A queue that enforces its own limit (the database queue
+ * stamps `maxAttempts` on every job and fails the job when the last attempt is nacked) decides:
+ * `attempt >= maxAttempts`. For queues that only count deliveries, `attempts >= maxRetries`.
+ */
+declare function isFinalAttempt(job: PollableJob & {
+  attempt?: number;
+  maxAttempts?: number;
+}, maxRetries?: number): boolean;
+export { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, RetryConfig, backoffDelayMs, isFinalAttempt };
+//# sourceMappingURL=retry.d.mts.map

package/dist/capture/consumer/retry.mjs

@@ -0,0 +1,33 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/consumer/retry.ts
+/** Retries after the first attempt before a job is failed for good (three attempts in total). */
+const DEFAULT_MAX_RETRIES = 2;
+/** Base of the exponential retry delay: the n-th retry waits `base * 2^n` ms. */
+const DEFAULT_BACKOFF_MS = 1e3;
+/** Longest a retry waits, however many attempts were made. */
+const MAX_BACKOFF_MS = 3e4;
+/** Long-poll wait handed to queues that block inside `poll` (SQS, Redis, Service Bus, IPC). */
+const DEFAULT_WAIT_TIME_SECONDS = 20;
+/** Delay before retry number `attempts` (0 = the first retry): `base * 2^attempts`, capped. */
+function backoffDelayMs(attempts, baseMs = DEFAULT_BACKOFF_MS, maxMs = MAX_BACKOFF_MS) {
+	return Math.min(maxMs, baseMs * 2 ** attempts);
+}
+/**
+* Whether this delivery is the job's last. A queue that enforces its own limit (the database queue
+* stamps `maxAttempts` on every job and fails the job when the last attempt is nacked) decides:
+* `attempt >= maxAttempts`. For queues that only count deliveries, `attempts >= maxRetries`.
+*/
+function isFinalAttempt(job, maxRetries = 2) {
+	const attempts = job.attempts ?? 0;
+	if (typeof job.maxAttempts === "number") return (job.attempt ?? attempts + 1) >= job.maxAttempts;
+	return attempts >= maxRetries;
+}
+/** Retries a job may still get, as the capture dispatch counts them (`maxAttempts - 1` when known). */
+function retriesOf(job, fallback = 2) {
+	return typeof job.maxAttempts === "number" ? Math.max(0, job.maxAttempts - 1) : fallback;
+}
+export { DEFAULT_BACKOFF_MS, DEFAULT_MAX_RETRIES, DEFAULT_WAIT_TIME_SECONDS, MAX_BACKOFF_MS, backoffDelayMs, isFinalAttempt, retriesOf };
+
+//# sourceMappingURL=retry.mjs.map

package/dist/capture/consumer/retry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.mjs","names":[],"sources":["../../../src/capture/consumer/retry.ts"],"sourcesContent":["/**\n * Retry policy of the capture consumer, in one place: how many times a failing job is redelivered,\n * how long each retry waits, and which delivery is the last. The numbers match ADR 0006,\n * decision 11 (`testing.retries` defaults to 2: three attempts in total).\n */\nimport type { PollableJob } from \"../../adapters/capture-queue.ts\";\n\n/** Retries after the first attempt before a job is failed for good (three attempts in total). */\nexport const DEFAULT_MAX_RETRIES = 2;\n/** Base of the exponential retry delay: the n-th retry waits `base * 2^n` ms. */\nexport const DEFAULT_BACKOFF_MS = 1000;\n/** Longest a retry waits, however many attempts were made. */\nexport const MAX_BACKOFF_MS = 30_000;\n/** Long-poll wait handed to queues that block inside `poll` (SQS, Redis, Service Bus, IPC). */\nexport const DEFAULT_WAIT_TIME_SECONDS = 20;\n\n/** Retry knobs of the consumer. */\nexport interface RetryConfig {\n  /** Retries after the first attempt (default {@link DEFAULT_MAX_RETRIES}). */\n  maxRetries?: number;\n  /** Base delay of the exponential backoff in ms (default {@link DEFAULT_BACKOFF_MS}). */\n  backoffMs?: number;\n}\n\n/** Delay before retry number `attempts` (0 = the first retry): `base * 2^attempts`, capped. */\nexport function backoffDelayMs(\n  attempts: number,\n  baseMs: number = DEFAULT_BACKOFF_MS,\n  maxMs: number = MAX_BACKOFF_MS,\n): number {\n  return Math.min(maxMs, baseMs * 2 ** attempts);\n}\n\n/**\n * Whether this delivery is the job's last. A queue that enforces its own limit (the database queue\n * stamps `maxAttempts` on every job and fails the job when the last attempt is nacked) decides:\n * `attempt >= maxAttempts`. For queues that only count deliveries, `attempts >= maxRetries`.\n */\nexport function isFinalAttempt(\n  job: PollableJob & { attempt?: number; maxAttempts?: number },\n  maxRetries: number = DEFAULT_MAX_RETRIES,\n): boolean {\n  const attempts = job.attempts ?? 0;\n  if (typeof job.maxAttempts === \"number\") {\n    return (job.attempt ?? attempts + 1) >= job.maxAttempts;\n  }\n  return attempts >= maxRetries;\n}\n\n/** Retries a job may still get, as the capture dispatch counts them (`maxAttempts - 1` when known). */\nexport function retriesOf(\n  job: PollableJob & { maxAttempts?: number },\n  fallback: number = DEFAULT_MAX_RETRIES,\n): number {\n  return typeof job.maxAttempts === \"number\" ? Math.max(0, job.maxAttempts - 1) : fallback;\n}\n"],"mappings":";;;;;AAQA,MAAa,sBAAsB;;AAEnC,MAAa,qBAAqB;;AAElC,MAAa,iBAAiB;;AAE9B,MAAa,4BAA4B;;AAWzC,SAAgB,eACd,UACA,SAAiB,oBACjB,QAAgB,gBACR;CACR,OAAO,KAAK,IAAI,OAAO,SAAS,KAAK,QAAQ;AAC/C;;;;;;AAOA,SAAgB,eACd,KACA,aAAA,GACS;CACT,MAAM,WAAW,IAAI,YAAY;CACjC,IAAI,OAAO,IAAI,gBAAgB,UAC7B,QAAQ,IAAI,WAAW,WAAW,MAAM,IAAI;CAE9C,OAAO,YAAY;AACrB;;AAGA,SAAgB,UACd,KACA,WAAA,GACQ;CACR,OAAO,OAAO,IAAI,gBAAgB,WAAW,KAAK,IAAI,GAAG,IAAI,cAAc,CAAC,IAAI;AAClF"}

package/dist/capture/consumer/run-job.mjs

@@ -0,0 +1,194 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { roundedTimings, runWithTimings } from "../../utils/timing.mjs";
+import { backoffDelayMs, isFinalAttempt } from "./retry.mjs";
+import { keepJobLease } from "../db-queue/keeper.mjs";
+import { reportFinished } from "./metrics.mjs";
+// src/capture/consumer/run-job.ts
+/** Run `job` in the slot the caller holds; never rejects. */
+async function runJob(rt, job) {
+	const kind = job.kind ?? "capture";
+	const startedAt = rt.now();
+	const logger = rt.logger.child({
+		buildId: job.buildId,
+		jobId: job.jobId ?? job.receipt,
+		kind,
+		reqId: job.reqId
+	});
+	const finish = (outcome) => {
+		reportFinished(rt.metrics, {
+			kind,
+			outcome,
+			durationMs: rt.now() - startedAt,
+			attempt: job.attempt ?? (job.attempts ?? 0) + 1
+		});
+	};
+	try {
+		finish(await execute(rt, job, logger));
+	} catch (error) {
+		logger.error({ err: error }, "failed to settle job");
+		finish("failed");
+	}
+}
+async function execute(rt, job, logger) {
+	const handler = rt.handlers.get(job.kind ?? "capture");
+	const refused = await refuse(rt, job, {
+		handler,
+		logger
+	});
+	if (refused !== null || handler === void 0) return refused ?? "unhandled";
+	return await runHandler(rt, {
+		job,
+		handler,
+		logger
+	});
+}
+/** Fail a job nobody can run (no handler for its kind) or that is malformed; null when runnable. */
+async function refuse(rt, job, held) {
+	const { handler, logger } = held;
+	if (handler === void 0) {
+		logger.error("no handler registered for job kind; failing the job");
+		await failJob(rt, job, `no handler registered for job kind "${job.kind ?? "capture"}"`, logger);
+		return "unhandled";
+	}
+	if (handler.accepts?.(job) === false) {
+		logger.warn({ attempts: job.attempts }, "dropping malformed queue job");
+		await failJob(rt, job, "malformed job", logger);
+		return "dropped";
+	}
+	return null;
+}
+async function runHandler(rt, held) {
+	const { job, handler, logger } = held;
+	const keeper = keepLease(rt, job, logger);
+	const touch = () => {
+		keeper.touch();
+		rt.onProgress?.(job);
+	};
+	logger.info("consumer picked up job");
+	const run = invoke(handler, job, {
+		logger,
+		touch
+	});
+	try {
+		const raced = await Promise.race([run, endOf(keeper)]);
+		return raced.kind === "ended" ? await abandon(rt, held, raced.end) : await settle(rt, held, raced);
+	} finally {
+		keeper.stop();
+		run.catch(() => {});
+	}
+}
+function keepLease(rt, job, logger) {
+	return keepJobLease(rt.queue, job, {
+		...rt.lease,
+		now: rt.now,
+		...rt.timers === void 0 ? {} : { timers: rt.timers },
+		logger
+	});
+}
+/** Run the handler, timing it; its failure is a value so the race can carry it. */
+async function invoke(handler, job, context) {
+	try {
+		const { timings } = await runWithTimings(async () => {
+			await handler.run(job, context);
+		});
+		context.logger.info({ timings: roundedTimings(timings) }, "consumer job timings");
+		return { kind: "settled" };
+	} catch (error) {
+		return {
+			kind: "settled",
+			error
+		};
+	}
+}
+async function endOf(keeper) {
+	return {
+		kind: "ended",
+		end: await keeper.ended
+	};
+}
+/** The handler returned: ack, or retry / fail on its error. */
+async function settle(rt, held, raced) {
+	if (!("error" in raced)) {
+		await rt.queue.ack(held.job);
+		held.logger.info("consumer completed job");
+		return "completed";
+	}
+	return await retryOrFail(rt, held, raced.error);
+}
+/** The handler threw: requeue with backoff, or fail the job on its last attempt. */
+async function retryOrFail(rt, held, error) {
+	const { job, logger } = held;
+	const message = error instanceof Error ? error.message : String(error);
+	const attempts = job.attempts ?? 0;
+	if (isFinalAttempt(job, rt.maxRetries)) {
+		await failJob(rt, job, message, logger);
+		logger.error({
+			err: error,
+			attempts
+		}, "capture permanently failed");
+		return "failed";
+	}
+	await requeue(rt, held, {
+		error,
+		message,
+		attempts
+	});
+	return "retried";
+}
+/** Put the job back with the next backoff delay. */
+async function requeue(rt, held, failure) {
+	const { backoff } = held.handler;
+	const delayMs = backoffDelayMs(failure.attempts, backoff?.baseMs ?? rt.backoffMs ?? 1e3, backoff?.maxMs);
+	await rt.queue.nack(held.job, {
+		requeue: true,
+		delayMs,
+		error: failure.message
+	});
+	held.logger.warn({
+		err: failure.error,
+		attempts: failure.attempts,
+		delayMs
+	}, "job failed, requeued");
+}
+/**
+* The lease is gone or the job was cancelled while the handler ran: stop the work. A lost lease
+* means another consumer owns the job (it settles it); a cancel is settled here as `cancelled`.
+*/
+async function abandon(rt, held, end) {
+	const { job, handler, logger } = held;
+	await handler.cancel?.(job).catch((error) => {
+		logger.warn({ err: error }, "failed to cancel the running job");
+	});
+	if (end === "lost") {
+		logger.warn("queue lease lost, aborting job");
+		return "lost";
+	}
+	logger.info("job cancelled, aborting");
+	await rt.queue.nack(job, {
+		requeue: false,
+		error: "cancelled"
+	});
+	return "cancelled";
+}
+/**
+* Final failure: nack without requeue so the queue records it failed. A queue that does not count
+* attempts itself falls back to ack when the nack fails, so a poison job never loops; the database
+* queue (it states `maxAttempts`) ends the job by itself, so there a failed nack is left to it.
+*/
+async function failJob(rt, job, message, logger) {
+	try {
+		await rt.queue.nack(job, {
+			requeue: false,
+			error: message
+		});
+	} catch (nackError) {
+		if (typeof job.maxAttempts === "number") throw nackError;
+		logger.warn({ err: nackError }, "final nack failed, acknowledging the job instead");
+		await rt.queue.ack(job);
+	}
+}
+export { runJob };
+
+//# sourceMappingURL=run-job.mjs.map