@storyshelf/core 0.6.2 → 0.7.0

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

@@ -0,0 +1,195 @@
+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";
+//#region 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);
+	}
+}
+//#endregion
+export { runJob };
+
+//# sourceMappingURL=run-job.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-job.mjs","names":[],"sources":["../../../src/capture/consumer/run-job.ts"],"sourcesContent":["/**\n * Run one claimed job to its end: pick the handler by kind, keep the lease (heartbeat and progress), then settle\n * the job on the queue (ack, retry with backoff, fail, or leave it to whoever owns it now).\n */\nimport type { PollableCaptureQueue } from \"../../adapters/capture-queue.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport { roundedTimings, runWithTimings } from \"../../utils/timing.ts\";\nimport { keepJobLease, type JobLeaseKeeper, type LeaseEnd } from \"../db-queue/keeper.ts\";\nimport type { QueueTimers } from \"../db-queue/timers.ts\";\nimport { reportFinished, type ConsumerMetrics, type JobOutcome } from \"./metrics.ts\";\nimport { backoffDelayMs, DEFAULT_BACKOFF_MS, isFinalAttempt } from \"./retry.ts\";\nimport type { ConsumerJob, KindHandler } from \"./types.ts\";\n\n/** What {@link runJob} needs from the consumer. */\nexport interface JobRuntime {\n  queue: PollableCaptureQueue;\n  /** Normalized registry. */\n  handlers: ReadonlyMap<string, KindHandler>;\n  maxRetries: number;\n  backoffMs?: number;\n  logger: Logger;\n  metrics?: ConsumerMetrics | undefined;\n  onProgress?: ((job: ConsumerJob) => void) | undefined;\n  now: () => number;\n  timers?: QueueTimers | undefined;\n  lease?: { renewEveryMs?: number; checkMs?: number } | undefined;\n}\n\n/** Why a job's handler stopped: it finished (or threw), or the queue took the job away. */\ntype Race = { kind: \"settled\"; error?: unknown } | { kind: \"ended\"; end: LeaseEnd };\n\n/** Run `job` in the slot the caller holds; never rejects. */\nexport async function runJob(rt: JobRuntime, job: ConsumerJob): Promise<void> {\n  const kind = job.kind ?? \"capture\";\n  const startedAt = rt.now();\n  const logger = rt.logger.child({\n    buildId: job.buildId,\n    jobId: job.jobId ?? job.receipt,\n    kind,\n    reqId: job.reqId,\n  });\n  const finish = (outcome: JobOutcome): void => {\n    reportFinished(rt.metrics, {\n      kind,\n      outcome,\n      durationMs: rt.now() - startedAt,\n      attempt: job.attempt ?? (job.attempts ?? 0) + 1,\n    });\n  };\n  try {\n    finish(await execute(rt, job, logger));\n  } catch (error) {\n    // Settling failed (the database is unreachable): the lease runs out and the queue redelivers.\n    logger.error({ err: error }, \"failed to settle job\");\n    finish(\"failed\");\n  }\n}\n\nasync function execute(rt: JobRuntime, job: ConsumerJob, logger: Logger): Promise<JobOutcome> {\n  const handler = rt.handlers.get(job.kind ?? \"capture\");\n  const refused = await refuse(rt, job, { handler, logger });\n  if (refused !== null || handler === undefined) {\n    return refused ?? \"unhandled\";\n  }\n  return await runHandler(rt, { job, handler, logger });\n}\n\n/** Fail a job nobody can run (no handler for its kind) or that is malformed; null when runnable. */\nasync function refuse(\n  rt: JobRuntime,\n  job: ConsumerJob,\n  held: { handler: KindHandler | undefined; logger: Logger },\n): Promise<JobOutcome | null> {\n  const { handler, logger } = held;\n  if (handler === undefined) {\n    logger.error(\"no handler registered for job kind; failing the job\");\n    await failJob(rt, job, `no handler registered for job kind \"${job.kind ?? \"capture\"}\"`, logger);\n    return \"unhandled\";\n  }\n  if (handler.accepts?.(job) === false) {\n    logger.warn({ attempts: job.attempts }, \"dropping malformed queue job\");\n    await failJob(rt, job, \"malformed job\", logger);\n    return \"dropped\";\n  }\n  return null;\n}\n\nasync function runHandler(\n  rt: JobRuntime,\n  held: { job: ConsumerJob; handler: KindHandler; logger: Logger },\n): Promise<JobOutcome> {\n  const { job, handler, logger } = held;\n  const keeper = keepLease(rt, job, logger);\n  const touch = (): void => {\n    keeper.touch();\n    rt.onProgress?.(job);\n  };\n  logger.info(\"consumer picked up job\");\n  const run = invoke(handler, job, { logger, touch });\n  try {\n    const raced = await Promise.race([run, endOf(keeper)]);\n    return raced.kind === \"ended\"\n      ? await abandon(rt, held, raced.end)\n      : await settle(rt, held, raced);\n  } finally {\n    keeper.stop();\n    run.catch(() => {});\n  }\n}\n\nfunction keepLease(rt: JobRuntime, job: ConsumerJob, logger: Logger): JobLeaseKeeper {\n  return keepJobLease(rt.queue, job, {\n    ...rt.lease,\n    now: rt.now,\n    ...(rt.timers === undefined ? {} : { timers: rt.timers }),\n    logger,\n  });\n}\n\n/** Run the handler, timing it; its failure is a value so the race can carry it. */\nasync function invoke(\n  handler: KindHandler,\n  job: ConsumerJob,\n  context: { logger: Logger; touch: () => void },\n): Promise<Race> {\n  try {\n    const { timings } = await runWithTimings(async () => {\n      await handler.run(job, context);\n    });\n    context.logger.info({ timings: roundedTimings(timings) }, \"consumer job timings\");\n    return { kind: \"settled\" };\n  } catch (error) {\n    return { kind: \"settled\", error };\n  }\n}\n\nasync function endOf(keeper: JobLeaseKeeper): Promise<Race> {\n  return { kind: \"ended\", end: await keeper.ended };\n}\n\n/** The handler returned: ack, or retry / fail on its error. */\nasync function settle(\n  rt: JobRuntime,\n  held: { job: ConsumerJob; handler: KindHandler; logger: Logger },\n  raced: Race & { kind: \"settled\" },\n): Promise<JobOutcome> {\n  if (!(\"error\" in raced)) {\n    await rt.queue.ack(held.job);\n    held.logger.info(\"consumer completed job\");\n    return \"completed\";\n  }\n  return await retryOrFail(rt, held, raced.error);\n}\n\n/** The handler threw: requeue with backoff, or fail the job on its last attempt. */\nasync function retryOrFail(\n  rt: JobRuntime,\n  held: { job: ConsumerJob; handler: KindHandler; logger: Logger },\n  error: unknown,\n): Promise<JobOutcome> {\n  const { job, logger } = held;\n  const message = error instanceof Error ? error.message : String(error);\n  const attempts = job.attempts ?? 0;\n  if (isFinalAttempt(job, rt.maxRetries)) {\n    await failJob(rt, job, message, logger);\n    logger.error({ err: error, attempts }, \"capture permanently failed\");\n    return \"failed\";\n  }\n  await requeue(rt, held, { error, message, attempts });\n  return \"retried\";\n}\n\n/** Put the job back with the next backoff delay. */\nasync function requeue(\n  rt: JobRuntime,\n  held: { job: ConsumerJob; handler: KindHandler; logger: Logger },\n  failure: { error: unknown; message: string; attempts: number },\n): Promise<void> {\n  const { backoff } = held.handler;\n  const delayMs = backoffDelayMs(\n    failure.attempts,\n    backoff?.baseMs ?? rt.backoffMs ?? DEFAULT_BACKOFF_MS,\n    backoff?.maxMs,\n  );\n  await rt.queue.nack(held.job, { requeue: true, delayMs, error: failure.message });\n  held.logger.warn(\n    { err: failure.error, attempts: failure.attempts, delayMs },\n    \"job failed, requeued\",\n  );\n}\n\n/**\n * The lease is gone or the job was cancelled while the handler ran: stop the work. A lost lease\n * means another consumer owns the job (it settles it); a cancel is settled here as `cancelled`.\n */\nasync function abandon(\n  rt: JobRuntime,\n  held: { job: ConsumerJob; handler: KindHandler; logger: Logger },\n  end: LeaseEnd,\n): Promise<JobOutcome> {\n  const { job, handler, logger } = held;\n  await handler.cancel?.(job).catch((error: unknown) => {\n    logger.warn({ err: error }, \"failed to cancel the running job\");\n  });\n  if (end === \"lost\") {\n    logger.warn(\"queue lease lost, aborting job\");\n    return \"lost\";\n  }\n  logger.info(\"job cancelled, aborting\");\n  await rt.queue.nack(job, { requeue: false, error: \"cancelled\" });\n  return \"cancelled\";\n}\n\n/**\n * Final failure: nack without requeue so the queue records it failed. A queue that does not count\n * attempts itself falls back to ack when the nack fails, so a poison job never loops; the database\n * queue (it states `maxAttempts`) ends the job by itself, so there a failed nack is left to it.\n */\nasync function failJob(\n  rt: JobRuntime,\n  job: ConsumerJob,\n  message: string,\n  logger: Logger,\n): Promise<void> {\n  try {\n    await rt.queue.nack(job, { requeue: false, error: message });\n  } catch (nackError) {\n    if (typeof job.maxAttempts === \"number\") {\n      throw nackError;\n    }\n    logger.warn({ err: nackError }, \"final nack failed, acknowledging the job instead\");\n    await rt.queue.ack(job);\n  }\n}\n"],"mappings":"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"}

package/dist/capture/consumer/startup.mjs

@@ -0,0 +1,38 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sweepOrphanedScratch } from "../scratch.mjs";
+import { configureImages, verifyImageEngine } from "../../diff.mjs";
+//#region src/capture/consumer/startup.ts
+/**
+* Only touch the process-wide image settings when asked, so a consumer created next to an app in
+* one process does not undo the app's own `images`/`compare` options.
+*/
+function applyImageSettings(images, compare) {
+	if (images || compare) configureImages({
+		engine: images?.engine,
+		threads: compare?.threads
+	});
+}
+/** Check that the image engine loads; a consumer that cannot diff must not claim jobs. */
+async function ensureImageEngine(logger) {
+	try {
+		await verifyImageEngine();
+	} catch (error) {
+		logger.error({ err: error }, "image engine cannot load; capture consumer stopping");
+		throw error;
+	}
+}
+/** Sweep scratch left by a killed run; failures are logged, never fatal. */
+async function sweepScratch(scratchDir, logger) {
+	if (scratchDir === void 0) return;
+	try {
+		await sweepOrphanedScratch(scratchDir, { logger });
+	} catch (error) {
+		logger.warn({ err: error }, "scratch sweep failed");
+	}
+}
+//#endregion
+export { applyImageSettings, ensureImageEngine, sweepScratch };
+
+//# sourceMappingURL=startup.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"startup.mjs","names":[],"sources":["../../../src/capture/consumer/startup.ts"],"sourcesContent":["/** What the consumer does before it polls: process-wide image settings, the engine check, scratch sweep. */\nimport type { ShelfCompareOptions, ShelfImagesOptions } from \"../../config.ts\";\nimport { configureImages, verifyImageEngine } from \"../../diff/index.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport { sweepOrphanedScratch } from \"../scratch.ts\";\n\n/**\n * Only touch the process-wide image settings when asked, so a consumer created next to an app in\n * one process does not undo the app's own `images`/`compare` options.\n */\nexport function applyImageSettings(\n  images?: ShelfImagesOptions,\n  compare?: ShelfCompareOptions,\n): void {\n  if (images || compare) {\n    configureImages({ engine: images?.engine, threads: compare?.threads });\n  }\n}\n\n/** Check that the image engine loads; a consumer that cannot diff must not claim jobs. */\nexport async function ensureImageEngine(logger: Logger): Promise<void> {\n  try {\n    await verifyImageEngine();\n  } catch (error) {\n    logger.error({ err: error }, \"image engine cannot load; capture consumer stopping\");\n    throw error;\n  }\n}\n\n/** Sweep scratch left by a killed run; failures are logged, never fatal. */\nexport async function sweepScratch(scratchDir: string | undefined, logger: Logger): Promise<void> {\n  if (scratchDir === undefined) {\n    return;\n  }\n  try {\n    await sweepOrphanedScratch(scratchDir, { logger });\n  } catch (error) {\n    logger.warn({ err: error }, \"scratch sweep failed\");\n  }\n}\n"],"mappings":";;;;;;;;;;AAUA,SAAgB,mBACd,QACA,SACM;CACN,IAAI,UAAU,SACZ,gBAAgB;EAAE,QAAQ,QAAQ;EAAQ,SAAS,SAAS;CAAQ,CAAC;AAEzE;;AAGA,eAAsB,kBAAkB,QAA+B;CACrE,IAAI;EACF,MAAM,kBAAkB;CAC1B,SAAS,OAAO;EACd,OAAO,MAAM,EAAE,KAAK,MAAM,GAAG,qDAAqD;EAClF,MAAM;CACR;AACF;;AAGA,eAAsB,aAAa,YAAgC,QAA+B;CAChG,IAAI,eAAe,KAAA,GACjB;CAEF,IAAI;EACF,MAAM,qBAAqB,YAAY,EAAE,OAAO,CAAC;CACnD,SAAS,OAAO;EACd,OAAO,KAAK,EAAE,KAAK,MAAM,GAAG,sBAAsB;CACpD;AACF"}

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

@@ -0,0 +1,97 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { ShelfCompareOptions, ShelfImagesOptions } from "../../config.mjs";
+import { PollableCaptureQueue, PollableJob } from "../../adapter/capture-queue.mjs";
+import { CaptureJobKind } from "../../schema/capture-job.mjs";
+import { PollCadence } from "../db-queue/cadence.mjs";
+import { QueueTimers } from "../db-queue/timers.mjs";
+import { CaptureHandlerOptions } from "./capture-handler.mjs";
+import { ConsumerMetrics } from "./metrics.mjs";
+import { RetryConfig } from "./retry.mjs";
+//#region src/capture/consumer/types.d.ts
+/** A polled job as the consumer sees it: database jobs carry the extra fields, others omit them. */
+type ConsumerJob = PollableJob & {
+  /** Job kind; absent on queues that only carry capture jobs (remote, IPC). */
+  kind?: CaptureJobKind;
+  /** Id of the job row (database queue). */
+  jobId?: string;
+  /** Attempt number from 1 (database queue). */
+  attempt?: number;
+  maxAttempts?: number;
+  /** Kind-specific fields given at enqueue. */
+  data?: Record<string, unknown>;
+};
+/** What a handler gets besides the job. */
+interface JobRunContext {
+  /** Logger scoped to the job (`buildId`, `jobId`, `kind`). */
+  logger: Logger;
+  /** Report progress: renews the job's lease (throttled) and tells the host (`onProgress`). */
+  touch(): void;
+}
+/** The code that runs jobs of one kind. */
+interface KindHandler {
+  /** Run the job; resolve to ack it, reject to retry (or fail it on its last attempt). */
+  run(job: ConsumerJob, context: JobRunContext): Promise<void>;
+  /** Whether the job is well-formed; a job that is not is failed without retries. */
+  accepts?(job: ConsumerJob): boolean;
+  /** Retry delay of this kind: `baseMs * 2^n` capped at `maxMs`; defaults to the consumer's. */
+  backoff?: {
+    baseMs: number;
+    maxMs: number;
+  };
+  /** Stop a running job (lease lost or cancelled); must tolerate a job that already ended. */
+  cancel?(job: ConsumerJob): Promise<void>;
+}
+/** Handler registry by job kind; a plain function is shorthand for `{ run }`. */
+type JobHandlers = Partial<Record<CaptureJobKind, KindHandler | KindHandler["run"] | undefined>>;
+/** Consumer tuning. */
+interface ConsumerConfig extends RetryConfig {
+  /** Jobs run at once; default sized from the CPU and memory the process can use. */
+  concurrency?: number;
+  /** Long-poll wait for queues that block inside `poll` (default 20, max 20). */
+  waitTimeSeconds?: number;
+}
+/** Options of {@link createCaptureConsumer}. */
+interface CaptureConsumerOptions {
+  /** Queue to consume: the database queue, or the IPC queue of a forked child. */
+  queue: PollableCaptureQueue;
+  /** Capture jobs: wires the `capture` kind to the core dispatch (shorthand for `handlers.capture`). */
+  capture?: Omit<CaptureHandlerOptions, "enqueue" | "logger"> & Partial<Pick<CaptureHandlerOptions, "enqueue">>;
+  /** Handlers by kind; `publish` and `notify` register here. Overrides `capture`'s. */
+  handlers?: JobHandlers;
+  config?: ConsumerConfig;
+  /** Scratch directory swept at start; defaults to `capture.scratchDir`. */
+  scratchDir?: string;
+  /** Image engine, as the server's `images` option; `start()` fails when it cannot load. */
+  images?: ShelfImagesOptions;
+  /** Diff pool size, as the server's `compare` option. */
+  compare?: ShelfCompareOptions;
+  /** Called whenever a running job makes progress (the forked child reports it to its parent). */
+  onProgress?: (job: ConsumerJob) => void;
+  /** Optional observation hooks; core does not depend on any metrics library. */
+  metrics?: ConsumerMetrics;
+  logger?: Logger;
+  /** Clock and timers (tests inject a manual clock). */
+  now?: () => number;
+  timers?: QueueTimers;
+  /** Poll cadence of the database queue (default ADR 0006's). */
+  cadence?: PollCadence;
+  random?: () => number;
+  /** Lease renewal throttle and state-check interval overrides (tests). */
+  lease?: {
+    renewEveryMs?: number;
+    checkMs?: number;
+  };
+}
+/** Handle returned by {@link createCaptureConsumer}. */
+interface CaptureConsumer {
+  /** Start consuming. Resolves once stopped and drained; rejects when the image engine cannot load. */
+  start(): Promise<void>;
+  /** Stop polling and wait for the jobs in flight to finish (SIGTERM drain). */
+  stop(): Promise<void>;
+  isRunning(): boolean;
+}
+//#endregion
+export { CaptureConsumer, CaptureConsumerOptions, ConsumerConfig, ConsumerJob, JobHandlers, JobRunContext, KindHandler };
+//# sourceMappingURL=types.d.mts.map

package/dist/capture/crash-failure.d.mts

@@ -0,0 +1,25 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DispatchDeps } from "./dispatch.mjs";
+//#region src/capture/crash-failure.d.ts
+/** What {@link failCrashedCapture} did. */
+type CrashFailureOutcome =
+/** The build was failed. */
+"failed" |
+/** The shard was failed; other shards are still open, and the last of them finishes the build. */
+"shard-failed" |
+/** The shard was the last one open: the build was finalized (failed, with this shard's stories). */
+"finalized" |
+/** The build had already ended (or is gone): nothing to do. */
+"skipped";
+/**
+ * Fail a capture job that crashed its worker past its retries. Safe to call for a build that has
+ * since ended: it is left alone.
+ */
+declare function failCrashedCapture(deps: DispatchDeps, job: {
+  buildId: string;
+  shard?: string | undefined;
+}, error: string): Promise<CrashFailureOutcome>;
+//#endregion
+export { CrashFailureOutcome, failCrashedCapture };
+//# sourceMappingURL=crash-failure.d.mts.map

package/dist/capture/crash-failure.mjs

@@ -0,0 +1,70 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { CaptureAttemptModel } from "../models/capture-attempt.mjs";
+import { BuildModel } from "../models/build.mjs";
+import { CaptureShardModel } from "../models/capture-shard.mjs";
+import { ProjectModel } from "../models/project.mjs";
+import { reduceBuild } from "./shards/reduce.mjs";
+//#region src/capture/crash-failure.ts
+/**
+* The terminal path for a capture job the forked parent gave up on because the child kept dying on
+* it (ADR 0005 phase 3). The child never got to record the failure, so the parent writes it: the
+* build fails, or, for a shard, the shard row fails and the build is reduced like any other end.
+*/
+/**
+* Fail a capture job that crashed its worker past its retries. Safe to call for a build that has
+* since ended: it is left alone.
+*/
+async function failCrashedCapture(deps, job, error) {
+	const outcome = job.shard ? await failShard(deps, job.buildId, job.shard, error) : await failBuild(deps, job.buildId, error);
+	if (outcome !== "skipped") deps.logger.error({
+		buildId: job.buildId,
+		shard: job.shard,
+		outcome,
+		error
+	}, "capture kept crashing its worker; failed it");
+	return outcome;
+}
+async function failBuild(deps, buildId, error) {
+	const loaded = await load(deps, buildId);
+	if (!loaded || loaded.build.status !== "capturing" && loaded.build.status !== "pending") return "skipped";
+	await closeOpenAttempts(deps, buildId, error);
+	await new BuildModel(deps.db, deps.tables).setStatus(buildId, "failed");
+	await deps.buildState.request(buildId);
+	return "failed";
+}
+async function failShard(deps, buildId, shardId, error) {
+	await new CaptureShardModel(deps.db).fail(shardId, error);
+	const loaded = await load(deps, buildId);
+	if (loaded?.build.status !== "capturing") return "skipped";
+	const summary = await reduceBuild({
+		options: deps.jobOptions,
+		...loaded
+	});
+	if (!summary) return "shard-failed";
+	await closeFinalized(deps, loaded, summary, error);
+	return "finalized";
+}
+/** The crashed shard was the last one: close the plan's attempt and report the build's end. */
+async function closeFinalized(deps, loaded, summary, error) {
+	if (summary.attemptId) await new CaptureAttemptModel(deps.db, deps.tables).markFinished(summary.attemptId, "failed", error, summary);
+	await deps.buildState.request(loaded.build.id);
+}
+async function load(deps, buildId) {
+	const build = await new BuildModel(deps.db, deps.tables).get(buildId);
+	const project = build ? await new ProjectModel(deps.db, deps.tables).get(build.projectId) : null;
+	return build && project ? {
+		build,
+		project
+	} : null;
+}
+async function closeOpenAttempts(deps, buildId, error) {
+	const attempts = new CaptureAttemptModel(deps.db, deps.tables);
+	const open = (await attempts.listByBuild(buildId)).filter((attempt) => attempt.status === "queued" || attempt.status === "running");
+	await Promise.all(open.map(async (attempt) => await attempts.markFinished(attempt.id, "failed", error)));
+}
+//#endregion
+export { failCrashedCapture };
+
+//# sourceMappingURL=crash-failure.mjs.map

package/dist/capture/crash-failure.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-failure.mjs","names":[],"sources":["../../src/capture/crash-failure.ts"],"sourcesContent":["/**\n * The terminal path for a capture job the forked parent gave up on because the child kept dying on\n * it (ADR 0005 phase 3). The child never got to record the failure, so the parent writes it: the\n * build fails, or, for a shard, the shard row fails and the build is reduced like any other end.\n */\nimport { BuildModel } from \"../models/build.ts\";\nimport { CaptureAttemptModel } from \"../models/capture-attempt.ts\";\nimport { CaptureShardModel } from \"../models/capture-shard.ts\";\nimport { ProjectModel } from \"../models/project.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { DispatchDeps } from \"./dispatch.ts\";\nimport { reduceBuild, type FinalSummary } from \"./shards/reduce.ts\";\n\n/** What {@link failCrashedCapture} did. */\nexport type CrashFailureOutcome =\n  /** The build was failed. */\n  | \"failed\"\n  /** The shard was failed; other shards are still open, and the last of them finishes the build. */\n  | \"shard-failed\"\n  /** The shard was the last one open: the build was finalized (failed, with this shard's stories). */\n  | \"finalized\"\n  /** The build had already ended (or is gone): nothing to do. */\n  | \"skipped\";\n\n/**\n * Fail a capture job that crashed its worker past its retries. Safe to call for a build that has\n * since ended: it is left alone.\n */\nexport async function failCrashedCapture(\n  deps: DispatchDeps,\n  job: { buildId: string; shard?: string | undefined },\n  error: string,\n): Promise<CrashFailureOutcome> {\n  const outcome = job.shard\n    ? await failShard(deps, job.buildId, job.shard, error)\n    : await failBuild(deps, job.buildId, error);\n  if (outcome !== \"skipped\") {\n    deps.logger.error(\n      { buildId: job.buildId, shard: job.shard, outcome, error },\n      \"capture kept crashing its worker; failed it\",\n    );\n  }\n  return outcome;\n}\n\nasync function failBuild(\n  deps: DispatchDeps,\n  buildId: string,\n  error: string,\n): Promise<CrashFailureOutcome> {\n  const loaded = await load(deps, buildId);\n  if (!loaded || (loaded.build.status !== \"capturing\" && loaded.build.status !== \"pending\")) {\n    return \"skipped\";\n  }\n  await closeOpenAttempts(deps, buildId, error);\n  await new BuildModel(deps.db, deps.tables).setStatus(buildId, \"failed\");\n  await deps.buildState.request(buildId);\n  return \"failed\";\n}\n\nasync function failShard(\n  deps: DispatchDeps,\n  buildId: string,\n  shardId: string,\n  error: string,\n): Promise<CrashFailureOutcome> {\n  await new CaptureShardModel(deps.db).fail(shardId, error);\n  const loaded = await load(deps, buildId);\n  if (loaded?.build.status !== \"capturing\") {\n    return \"skipped\";\n  }\n  const summary = await reduceBuild({ options: deps.jobOptions, ...loaded });\n  if (!summary) {\n    return \"shard-failed\";\n  }\n  await closeFinalized(deps, loaded, summary, error);\n  return \"finalized\";\n}\n\n/** The crashed shard was the last one: close the plan's attempt and report the build's end. */\nasync function closeFinalized(\n  deps: DispatchDeps,\n  loaded: { build: Build; project: Project },\n  summary: FinalSummary,\n  error: string,\n): Promise<void> {\n  if (summary.attemptId) {\n    await new CaptureAttemptModel(deps.db, deps.tables).markFinished(\n      summary.attemptId,\n      \"failed\",\n      error,\n      summary,\n    );\n  }\n  await deps.buildState.request(loaded.build.id);\n}\n\nasync function load(\n  deps: DispatchDeps,\n  buildId: string,\n): Promise<{ build: Build; project: Project } | null> {\n  const build = await new BuildModel(deps.db, deps.tables).get(buildId);\n  const project = build ? await new ProjectModel(deps.db, deps.tables).get(build.projectId) : null;\n  return build && project ? { build, project } : null;\n}\n\nasync function closeOpenAttempts(\n  deps: DispatchDeps,\n  buildId: string,\n  error: string,\n): Promise<void> {\n  const attempts = new CaptureAttemptModel(deps.db, deps.tables);\n  const open = (await attempts.listByBuild(buildId)).filter(\n    (attempt) => attempt.status === \"queued\" || attempt.status === \"running\",\n  );\n  await Promise.all(\n    open.map(async (attempt) => await attempts.markFinished(attempt.id, \"failed\", error)),\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6BA,eAAsB,mBACpB,MACA,KACA,OAC8B;CAC9B,MAAM,UAAU,IAAI,QAChB,MAAM,UAAU,MAAM,IAAI,SAAS,IAAI,OAAO,KAAK,IACnD,MAAM,UAAU,MAAM,IAAI,SAAS,KAAK;CAC5C,IAAI,YAAY,WACd,KAAK,OAAO,MACV;EAAE,SAAS,IAAI;EAAS,OAAO,IAAI;EAAO;EAAS;CAAM,GACzD,6CACF;CAEF,OAAO;AACT;AAEA,eAAe,UACb,MACA,SACA,OAC8B;CAC9B,MAAM,SAAS,MAAM,KAAK,MAAM,OAAO;CACvC,IAAI,CAAC,UAAW,OAAO,MAAM,WAAW,eAAe,OAAO,MAAM,WAAW,WAC7E,OAAO;CAET,MAAM,kBAAkB,MAAM,SAAS,KAAK;CAC5C,MAAM,IAAI,WAAW,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,UAAU,SAAS,QAAQ;CACtE,MAAM,KAAK,WAAW,QAAQ,OAAO;CACrC,OAAO;AACT;AAEA,eAAe,UACb,MACA,SACA,SACA,OAC8B;CAC9B,MAAM,IAAI,kBAAkB,KAAK,EAAE,CAAC,CAAC,KAAK,SAAS,KAAK;CACxD,MAAM,SAAS,MAAM,KAAK,MAAM,OAAO;CACvC,IAAI,QAAQ,MAAM,WAAW,aAC3B,OAAO;CAET,MAAM,UAAU,MAAM,YAAY;EAAE,SAAS,KAAK;EAAY,GAAG;CAAO,CAAC;CACzE,IAAI,CAAC,SACH,OAAO;CAET,MAAM,eAAe,MAAM,QAAQ,SAAS,KAAK;CACjD,OAAO;AACT;;AAGA,eAAe,eACb,MACA,QACA,SACA,OACe;CACf,IAAI,QAAQ,WACV,MAAM,IAAI,oBAAoB,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,aAClD,QAAQ,WACR,UACA,OACA,OACF;CAEF,MAAM,KAAK,WAAW,QAAQ,OAAO,MAAM,EAAE;AAC/C;AAEA,eAAe,KACb,MACA,SACoD;CACpD,MAAM,QAAQ,MAAM,IAAI,WAAW,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,IAAI,OAAO;CACpE,MAAM,UAAU,QAAQ,MAAM,IAAI,aAAa,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,IAAI,MAAM,SAAS,IAAI;CAC5F,OAAO,SAAS,UAAU;EAAE;EAAO;CAAQ,IAAI;AACjD;AAEA,eAAe,kBACb,MACA,SACA,OACe;CACf,MAAM,WAAW,IAAI,oBAAoB,KAAK,IAAI,KAAK,MAAM;CAC7D,MAAM,QAAQ,MAAM,SAAS,YAAY,OAAO,EAAA,CAAG,QAChD,YAAY,QAAQ,WAAW,YAAY,QAAQ,WAAW,SACjE;CACA,MAAM,QAAQ,IACZ,KAAK,IAAI,OAAO,YAAY,MAAM,SAAS,aAAa,QAAQ,IAAI,UAAU,KAAK,CAAC,CACtF;AACF"}

package/dist/capture/db-queue/cadence.d.mts

@@ -0,0 +1,32 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/db-queue/cadence.d.ts
+/** Poll and cancel-check cadence of the database queue (ADR 0006, decision 11). */
+/** Poll interval of an idle instance. */
+declare const IDLE_POLL_MS = 15000;
+/** Poll interval while jobs were recently queued or found. */
+declare const ACTIVE_POLL_MS = 2000;
+/** How long after the last job seen an instance keeps polling at the active rate. */
+declare const ACTIVE_WINDOW_MS = 60000;
+/** Each delay is stretched by up to this fraction (never shortened, so idle stays ≥ 15 s). */
+declare const POLL_JITTER = 0.2;
+/** How often a running job reads its own row for cancel. */
+declare const CANCEL_CHECK_MS = 5000;
+/** Tunable cadence; tests shrink it, production uses the defaults above. */
+interface PollCadence {
+  idleMs: number;
+  activeMs: number;
+  activeWindowMs: number;
+  jitter: number;
+}
+/** The cadence ADR 0006 fixes. */
+declare const DEFAULT_CADENCE: PollCadence;
+/**
+ * Delay before the next poll: the active interval while the last job was seen (found by a poll or
+ * queued locally) within the active window, otherwise the idle interval; plus jitter in
+ * `[0, jitter)` of it, so instances started together drift apart instead of probing in lockstep.
+ */
+declare function nextPollDelay(lastWorkAt: number | null, now: number, cadence?: PollCadence, random?: () => number): number;
+//#endregion
+export { ACTIVE_POLL_MS, ACTIVE_WINDOW_MS, CANCEL_CHECK_MS, DEFAULT_CADENCE, IDLE_POLL_MS, POLL_JITTER, PollCadence, nextPollDelay };
+//# sourceMappingURL=cadence.d.mts.map

package/dist/capture/db-queue/cadence.mjs

@@ -0,0 +1,38 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/db-queue/cadence.ts
+/** Poll and cancel-check cadence of the database queue (ADR 0006, decision 11). */
+/** Poll interval of an idle instance. */
+const IDLE_POLL_MS = 15e3;
+/** Poll interval while jobs were recently queued or found. */
+const ACTIVE_POLL_MS = 2e3;
+/** How long after the last job seen an instance keeps polling at the active rate. */
+const ACTIVE_WINDOW_MS = 6e4;
+/** Each delay is stretched by up to this fraction (never shortened, so idle stays ≥ 15 s). */
+const POLL_JITTER = .2;
+/** How often a running job reads its own row for cancel. */
+const CANCEL_CHECK_MS = 5e3;
+/** The cadence ADR 0006 fixes. */
+const DEFAULT_CADENCE = {
+	idleMs: IDLE_POLL_MS,
+	activeMs: ACTIVE_POLL_MS,
+	activeWindowMs: ACTIVE_WINDOW_MS,
+	jitter: POLL_JITTER
+};
+/**
+* Delay before the next poll: the active interval while the last job was seen (found by a poll or
+* queued locally) within the active window, otherwise the idle interval; plus jitter in
+* `[0, jitter)` of it, so instances started together drift apart instead of probing in lockstep.
+*/
+function nextPollDelay(lastWorkAt, now, cadence = DEFAULT_CADENCE, random = Math.random) {
+	const base = lastWorkAt !== null && now - lastWorkAt < cadence.activeWindowMs ? cadence.activeMs : cadence.idleMs;
+	return Math.round(base * (1 + cadence.jitter * clampUnit(random())));
+}
+function clampUnit(value) {
+	return Math.min(Math.max(value, 0), .999999);
+}
+//#endregion
+export { ACTIVE_POLL_MS, ACTIVE_WINDOW_MS, CANCEL_CHECK_MS, DEFAULT_CADENCE, IDLE_POLL_MS, POLL_JITTER, nextPollDelay };
+
+//# sourceMappingURL=cadence.mjs.map

package/dist/capture/db-queue/cadence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.mjs","names":[],"sources":["../../../src/capture/db-queue/cadence.ts"],"sourcesContent":["/** Poll and cancel-check cadence of the database queue (ADR 0006, decision 11). */\n\n/** Poll interval of an idle instance. */\nexport const IDLE_POLL_MS = 15_000;\n/** Poll interval while jobs were recently queued or found. */\nexport const ACTIVE_POLL_MS = 2000;\n/** How long after the last job seen an instance keeps polling at the active rate. */\nexport const ACTIVE_WINDOW_MS = 60_000;\n/** Each delay is stretched by up to this fraction (never shortened, so idle stays ≥ 15 s). */\nexport const POLL_JITTER = 0.2;\n/** How often a running job reads its own row for cancel. */\nexport const CANCEL_CHECK_MS = 5000;\n\n/** Tunable cadence; tests shrink it, production uses the defaults above. */\nexport interface PollCadence {\n  idleMs: number;\n  activeMs: number;\n  activeWindowMs: number;\n  jitter: number;\n}\n\n/** The cadence ADR 0006 fixes. */\nexport const DEFAULT_CADENCE: PollCadence = {\n  idleMs: IDLE_POLL_MS,\n  activeMs: ACTIVE_POLL_MS,\n  activeWindowMs: ACTIVE_WINDOW_MS,\n  jitter: POLL_JITTER,\n};\n\n/**\n * Delay before the next poll: the active interval while the last job was seen (found by a poll or\n * queued locally) within the active window, otherwise the idle interval; plus jitter in\n * `[0, jitter)` of it, so instances started together drift apart instead of probing in lockstep.\n */\nexport function nextPollDelay(\n  lastWorkAt: number | null,\n  now: number,\n  cadence: PollCadence = DEFAULT_CADENCE,\n  random: () => number = Math.random,\n): number {\n  const active = lastWorkAt !== null && now - lastWorkAt < cadence.activeWindowMs;\n  const base = active ? cadence.activeMs : cadence.idleMs;\n  return Math.round(base * (1 + cadence.jitter * clampUnit(random())));\n}\n\nfunction clampUnit(value: number): number {\n  return Math.min(Math.max(value, 0), 0.999999);\n}\n"],"mappings":";;;;;;AAGA,MAAa,eAAe;;AAE5B,MAAa,iBAAiB;;AAE9B,MAAa,mBAAmB;;AAEhC,MAAa,cAAc;;AAE3B,MAAa,kBAAkB;;AAW/B,MAAa,kBAA+B;CAC1C,QAAQ;CACR,UAAU;CACV,gBAAgB;CAChB,QAAQ;AACV;;;;;;AAOA,SAAgB,cACd,YACA,KACA,UAAuB,iBACvB,SAAuB,KAAK,QACpB;CAER,MAAM,OADS,eAAe,QAAQ,MAAM,aAAa,QAAQ,iBAC3C,QAAQ,WAAW,QAAQ;CACjD,OAAO,KAAK,MAAM,QAAQ,IAAI,QAAQ,SAAS,UAAU,OAAO,CAAC,EAAE;AACrE;AAEA,SAAS,UAAU,OAAuB;CACxC,OAAO,KAAK,IAAI,KAAK,IAAI,OAAO,CAAC,GAAG,OAAQ;AAC9C"}

package/dist/capture/db-queue/claim.d.mts

@@ -0,0 +1,9 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "./types.mjs";
+//#region src/capture/db-queue/claim.d.ts
+/** Error recorded on a job whose last allowed attempt lost its lease. */
+declare const LEASE_EXHAUSTED_ERROR = "lease expired on the final attempt";
+//#endregion
+export { LEASE_EXHAUSTED_ERROR };
+//# sourceMappingURL=claim.d.mts.map