@storyshelf/core 0.6.2 → 0.8.0

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,37 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sweepOrphanedScratch } from "../scratch.mjs";
+import { configureImages, verifyImageEngine } from "../../diff.mjs";
+// 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");
+	}
+}
+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,95 @@
+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";
+/** 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;
+}
+export { CaptureConsumer, CaptureConsumerOptions, ConsumerConfig, ConsumerJob, JobHandlers, JobRunContext, KindHandler };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DispatchDeps } from "./dispatch.mjs";
+/** 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>;
+export { CrashFailureOutcome, failCrashedCapture };
+//# sourceMappingURL=crash-failure.d.mts.map

package/dist/capture/crash-failure.mjs

@@ -0,0 +1,69 @@
+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";
+// 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)));
+}
+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,30 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** 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;
+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,37 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// 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);
+}
+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,7 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "./types.mjs";
+/** Error recorded on a job whose last allowed attempt lost its lease. */
+declare const LEASE_EXHAUSTED_ERROR = "lease expired on the final attempt";
+export { LEASE_EXHAUSTED_ERROR };
+//# sourceMappingURL=claim.d.mts.map

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

@@ -0,0 +1,148 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { attemptRowId, isTerminalJob } from "../../models/capture-job.mjs";
+import { toDatabaseJob } from "./codec.mjs";
+import { isoAt } from "./clock.mjs";
+// src/capture/db-queue/claim.ts
+/**
+* The claim algorithm of the database queue. A poll probes for the oldest candidate row (a queued
+* job whose `visibleAt` passed, or a running attempt whose lease ran out), then claims the job's
+* next attempt by inserting its row: the unique key lets exactly one instance win. The winner
+* retires the expired attempt it replaced and marks the job row running.
+*/
+/** Candidates tried per poll when other instances win the race for them. */
+const MAX_CLAIM_TRIES = 3;
+/** Error recorded on a job whose last allowed attempt lost its lease. */
+const LEASE_EXHAUSTED_ERROR = "lease expired on the final attempt";
+/** Probe once and claim the job found; on a lost race, try the next candidate (a few times). */
+async function claimNext(rt) {
+	for (let tries = 0; tries < MAX_CLAIM_TRIES; tries += 1) {
+		const candidate = await rt.model.nextCandidate(rt.kinds, isoAt(rt));
+		if (candidate === null) return null;
+		const job = await claimCandidate(rt, candidate);
+		if (job !== null) return job;
+	}
+	return null;
+}
+/** Claim the job behind a candidate row; null when it is gone, over, exhausted or lost to a race. */
+async function claimCandidate(rt, candidate) {
+	if (candidate.entry === "job" && candidate.status !== "queued") {
+		await rt.model.clearVisibility(candidate.id, isoAt(rt));
+		return null;
+	}
+	const stale = candidate.entry === "attempt" ? candidate : null;
+	const job = stale === null ? candidate : await rt.model.get(candidate.jobId);
+	if (job === null || isTerminalJob(job) || stale !== null && stale.attempt < job.attempt) {
+		await retire(rt, stale);
+		return null;
+	}
+	return await claimNextAttempt(rt, job, stale);
+}
+/** Claim the attempt after the last one made, or fail the job when none is left. */
+async function claimNextAttempt(rt, job, stale) {
+	const made = Math.max(job.attempt, stale?.attempt ?? 0);
+	if (made >= job.maxAttempts) {
+		await exhaust(rt, job, stale);
+		return null;
+	}
+	return await claimAttempt(rt, job, made + 1, stale);
+}
+async function claimAttempt(rt, job, attempt, stale) {
+	const leaseUntil = isoAt(rt, rt.leaseMs);
+	if (!await rt.model.claim({
+		job,
+		attempt,
+		owner: rt.owner,
+		leaseUntil
+	}, isoAt(rt))) return stale === null ? await afterLostRace(rt, job, attempt) : null;
+	const fresh = await rt.model.get(job.jobId);
+	if (fresh === null || isTerminalJob(fresh)) {
+		await rt.model.finishAttempt(attemptRowId(job.jobId, attempt), "expired", isoAt(rt));
+		return null;
+	}
+	return await takeOver(rt, fresh, attempt, stale);
+}
+/**
+* Another instance holds attempt `attempt` of a job whose row still reads queued. Usually that
+* winner is about to mark the job running. If it died before doing so, its attempt's lease decides:
+* once expired, the attempt is claimed like any expired one; until then the job row is moved
+* behind that lease, so it does not sit at the head of the queue losing every claim. Only
+* `visibleAt` is written, never the status, so a winner that finished meanwhile keeps its outcome.
+*/
+async function afterLostRace(rt, job, attempt) {
+	const id = attemptRowId(job.jobId, attempt);
+	const expired = await rt.model.expiredAttempt(id, isoAt(rt));
+	if (expired !== null) return await claimCandidate(rt, expired);
+	await deferBehind(rt, job, await rt.model.get(id));
+	return null;
+}
+async function deferBehind(rt, job, holder) {
+	const current = await rt.model.get(job.jobId);
+	if (holder?.visibleAt && current?.status === "queued" && current.attempt === job.attempt) await rt.model.defer(job.jobId, holder.visibleAt, isoAt(rt));
+}
+/** The claim won: retire the attempt it replaced and record the new one on the job row. */
+async function takeOver(rt, job, attempt, stale) {
+	await retire(rt, stale);
+	await rt.model.markRunning(job.jobId, attempt, isoAt(rt));
+	rt.logger?.debug({
+		jobId: job.jobId,
+		attempt
+	}, "job claimed");
+	return toDatabaseJob(job, attempt, rt.leaseMs);
+}
+/** Mark an expired attempt row `expired`: it leaves the poll's range, and its holder sees `lost`. */
+async function retire(rt, stale) {
+	if (stale !== null) await rt.model.finishAttempt(stale.id, "expired", isoAt(rt));
+}
+/**
+* The final attempt lost its lease: the job fails (one limit covers failed attempts and lost
+* leases). Idempotent, so two instances finding the same row write the same outcome. If the late
+* holder finished after all, its `done` wins.
+*/
+async function exhaust(rt, job, stale) {
+	const now = isoAt(rt);
+	if (stale !== null && (await rt.model.get(stale.id))?.status === "done") {
+		await rt.model.finishJob(job.jobId, "done", now);
+		return;
+	}
+	await retire(rt, stale);
+	await rt.model.finishJob(job.jobId, "failed", now, LEASE_EXHAUSTED_ERROR);
+	rt.logger?.warn({
+		jobId: job.jobId,
+		attempts: job.attempt
+	}, "job failed: lease exhausted");
+	await reportExhausted(rt, job);
+}
+/** Sleep for `ms`, using injected timers when available. */
+async function sleep(rt, ms) {
+	if (rt.timers === void 0) {
+		await new Promise((resolve) => {
+			setTimeout(resolve, ms);
+		});
+		return;
+	}
+	await new Promise((resolve) => {
+		rt.timers?.setTimeout(resolve, ms);
+	});
+}
+/** Tell the host a job ended without any holder to record it; its failure never blocks the poll. */
+async function reportExhausted(rt, job) {
+	if (rt.onExhausted === void 0) return;
+	const attempts = 3;
+	for (let attempt = 1; attempt <= attempts; attempt += 1) try {
+		await rt.onExhausted(toDatabaseJob(job, job.attempt, rt.leaseMs), LEASE_EXHAUSTED_ERROR);
+		return;
+	} catch (error) {
+		rt.logger?.error({
+			err: error,
+			jobId: job.jobId,
+			attempt,
+			attempts
+		}, "exhausted-job hook failed");
+		if (attempt < attempts) await sleep(rt, 100 * attempt);
+	}
+}
+export { LEASE_EXHAUSTED_ERROR, claimCandidate, claimNext };
+
+//# sourceMappingURL=claim.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claim.mjs","names":[],"sources":["../../../src/capture/db-queue/claim.ts"],"sourcesContent":["/**\n * The claim algorithm of the database queue. A poll probes for the oldest candidate row (a queued\n * job whose `visibleAt` passed, or a running attempt whose lease ran out), then claims the job's\n * next attempt by inserting its row: the unique key lets exactly one instance win. The winner\n * retires the expired attempt it replaced and marks the job row running.\n */\nimport { attemptRowId, isTerminalJob } from \"../../models/capture-job.ts\";\nimport type { CaptureJobRow } from \"../../schema/capture-job.ts\";\nimport { isoAt } from \"./clock.ts\";\nimport { toDatabaseJob } from \"./codec.ts\";\nimport type { DatabaseJob, QueueRuntime } from \"./types.ts\";\n\n/** Candidates tried per poll when other instances win the race for them. */\nconst MAX_CLAIM_TRIES = 3;\n\n/** Error recorded on a job whose last allowed attempt lost its lease. */\nexport const LEASE_EXHAUSTED_ERROR = \"lease expired on the final attempt\";\n\n/** Probe once and claim the job found; on a lost race, try the next candidate (a few times). */\nexport async function claimNext(rt: QueueRuntime): Promise<DatabaseJob | null> {\n  for (let tries = 0; tries < MAX_CLAIM_TRIES; tries += 1) {\n    // oxlint-disable-next-line no-await-in-loop -- one candidate at a time, in order\n    const candidate = await rt.model.nextCandidate(rt.kinds, isoAt(rt));\n    if (candidate === null) {\n      return null;\n    }\n    // oxlint-disable-next-line no-await-in-loop -- see above\n    const job = await claimCandidate(rt, candidate);\n    if (job !== null) {\n      return job;\n    }\n  }\n  return null;\n}\n\n/** Claim the job behind a candidate row; null when it is gone, over, exhausted or lost to a race. */\nexport async function claimCandidate(\n  rt: QueueRuntime,\n  candidate: CaptureJobRow,\n): Promise<DatabaseJob | null> {\n  if (candidate.entry === \"job\" && candidate.status !== \"queued\") {\n    // A running job row put back in range by a late deferral (see `deferBehind`): not claimable.\n    await rt.model.clearVisibility(candidate.id, isoAt(rt));\n    return null;\n  }\n  const stale = candidate.entry === \"attempt\" ? candidate : null;\n  const job = stale === null ? candidate : await rt.model.get(candidate.jobId);\n  if (job === null || isTerminalJob(job) || (stale !== null && stale.attempt < job.attempt)) {\n    // Nothing left to claim: the expired attempt is just cleaned out of the poll's range.\n    await retire(rt, stale);\n    return null;\n  }\n  return await claimNextAttempt(rt, job, stale);\n}\n\n/** Claim the attempt after the last one made, or fail the job when none is left. */\nasync function claimNextAttempt(\n  rt: QueueRuntime,\n  job: CaptureJobRow,\n  stale: CaptureJobRow | null,\n): Promise<DatabaseJob | null> {\n  // An attempt row ahead of its job row belongs to a claimer that died before marking the job.\n  const made = Math.max(job.attempt, stale?.attempt ?? 0);\n  if (made >= job.maxAttempts) {\n    await exhaust(rt, job, stale);\n    return null;\n  }\n  return await claimAttempt(rt, job, made + 1, stale);\n}\n\nasync function claimAttempt(\n  rt: QueueRuntime,\n  job: CaptureJobRow,\n  attempt: number,\n  stale: CaptureJobRow | null,\n): Promise<DatabaseJob | null> {\n  const leaseUntil = isoAt(rt, rt.leaseMs);\n  const won = await rt.model.claim({ job, attempt, owner: rt.owner, leaseUntil }, isoAt(rt));\n  if (!won) {\n    return stale === null ? await afterLostRace(rt, job, attempt) : null;\n  }\n  const fresh = await rt.model.get(job.jobId);\n  if (fresh === null || isTerminalJob(fresh)) {\n    // Cancelled (or finished by a late holder) between the probe and the insert.\n    await rt.model.finishAttempt(attemptRowId(job.jobId, attempt), \"expired\", isoAt(rt));\n    return null;\n  }\n  return await takeOver(rt, fresh, attempt, stale);\n}\n\n/**\n * Another instance holds attempt `attempt` of a job whose row still reads queued. Usually that\n * winner is about to mark the job running. If it died before doing so, its attempt's lease decides:\n * once expired, the attempt is claimed like any expired one; until then the job row is moved\n * behind that lease, so it does not sit at the head of the queue losing every claim. Only\n * `visibleAt` is written, never the status, so a winner that finished meanwhile keeps its outcome.\n */\nasync function afterLostRace(\n  rt: QueueRuntime,\n  job: CaptureJobRow,\n  attempt: number,\n): Promise<DatabaseJob | null> {\n  const id = attemptRowId(job.jobId, attempt);\n  const expired = await rt.model.expiredAttempt(id, isoAt(rt));\n  if (expired !== null) {\n    return await claimCandidate(rt, expired);\n  }\n  await deferBehind(rt, job, await rt.model.get(id));\n  return null;\n}\n\nasync function deferBehind(\n  rt: QueueRuntime,\n  job: CaptureJobRow,\n  holder: CaptureJobRow | null,\n): Promise<void> {\n  const current = await rt.model.get(job.jobId);\n  if (holder?.visibleAt && current?.status === \"queued\" && current.attempt === job.attempt) {\n    await rt.model.defer(job.jobId, holder.visibleAt, isoAt(rt));\n  }\n}\n\n/** The claim won: retire the attempt it replaced and record the new one on the job row. */\nasync function takeOver(\n  rt: QueueRuntime,\n  job: CaptureJobRow,\n  attempt: number,\n  stale: CaptureJobRow | null,\n): Promise<DatabaseJob> {\n  await retire(rt, stale);\n  await rt.model.markRunning(job.jobId, attempt, isoAt(rt));\n  rt.logger?.debug({ jobId: job.jobId, attempt }, \"job claimed\");\n  return toDatabaseJob(job, attempt, rt.leaseMs);\n}\n\n/** Mark an expired attempt row `expired`: it leaves the poll's range, and its holder sees `lost`. */\nasync function retire(rt: QueueRuntime, stale: CaptureJobRow | null): Promise<void> {\n  if (stale !== null) {\n    await rt.model.finishAttempt(stale.id, \"expired\", isoAt(rt));\n  }\n}\n\n/**\n * The final attempt lost its lease: the job fails (one limit covers failed attempts and lost\n * leases). Idempotent, so two instances finding the same row write the same outcome. If the late\n * holder finished after all, its `done` wins.\n */\nasync function exhaust(\n  rt: QueueRuntime,\n  job: CaptureJobRow,\n  stale: CaptureJobRow | null,\n): Promise<void> {\n  const now = isoAt(rt);\n  if (stale !== null && (await rt.model.get(stale.id))?.status === \"done\") {\n    await rt.model.finishJob(job.jobId, \"done\", now);\n    return;\n  }\n  await retire(rt, stale);\n  await rt.model.finishJob(job.jobId, \"failed\", now, LEASE_EXHAUSTED_ERROR);\n  rt.logger?.warn({ jobId: job.jobId, attempts: job.attempt }, \"job failed: lease exhausted\");\n  await reportExhausted(rt, job);\n}\n\n/** Sleep for `ms`, using injected timers when available. */\nasync function sleep(rt: QueueRuntime, ms: number): Promise<void> {\n  if (rt.timers === undefined) {\n    await new Promise<void>((resolve) => {\n      setTimeout(resolve, ms);\n    });\n    return;\n  }\n  await new Promise<void>((resolve) => {\n    rt.timers?.setTimeout(resolve, ms);\n  });\n}\n\n/** Tell the host a job ended without any holder to record it; its failure never blocks the poll. */\nasync function reportExhausted(rt: QueueRuntime, job: CaptureJobRow): Promise<void> {\n  if (rt.onExhausted === undefined) {\n    return;\n  }\n  const attempts = 3;\n  for (let attempt = 1; attempt <= attempts; attempt += 1) {\n    try {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- sequential retries\n      await rt.onExhausted(toDatabaseJob(job, job.attempt, rt.leaseMs), LEASE_EXHAUSTED_ERROR);\n      return;\n    } catch (error) {\n      rt.logger?.error(\n        { err: error, jobId: job.jobId, attempt, attempts },\n        \"exhausted-job hook failed\",\n      );\n      if (attempt < attempts) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- sequential retries\n        await sleep(rt, 100 * attempt);\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAM,kBAAkB;;AAGxB,MAAa,wBAAwB;;AAGrC,eAAsB,UAAU,IAA+C;CAC7E,KAAK,IAAI,QAAQ,GAAG,QAAQ,iBAAiB,SAAS,GAAG;EAEvD,MAAM,YAAY,MAAM,GAAG,MAAM,cAAc,GAAG,OAAO,MAAM,EAAE,CAAC;EAClE,IAAI,cAAc,MAChB,OAAO;EAGT,MAAM,MAAM,MAAM,eAAe,IAAI,SAAS;EAC9C,IAAI,QAAQ,MACV,OAAO;CAEX;CACA,OAAO;AACT;;AAGA,eAAsB,eACpB,IACA,WAC6B;CAC7B,IAAI,UAAU,UAAU,SAAS,UAAU,WAAW,UAAU;EAE9D,MAAM,GAAG,MAAM,gBAAgB,UAAU,IAAI,MAAM,EAAE,CAAC;EACtD,OAAO;CACT;CACA,MAAM,QAAQ,UAAU,UAAU,YAAY,YAAY;CAC1D,MAAM,MAAM,UAAU,OAAO,YAAY,MAAM,GAAG,MAAM,IAAI,UAAU,KAAK;CAC3E,IAAI,QAAQ,QAAQ,cAAc,GAAG,KAAM,UAAU,QAAQ,MAAM,UAAU,IAAI,SAAU;EAEzF,MAAM,OAAO,IAAI,KAAK;EACtB,OAAO;CACT;CACA,OAAO,MAAM,iBAAiB,IAAI,KAAK,KAAK;AAC9C;;AAGA,eAAe,iBACb,IACA,KACA,OAC6B;CAE7B,MAAM,OAAO,KAAK,IAAI,IAAI,SAAS,OAAO,WAAW,CAAC;CACtD,IAAI,QAAQ,IAAI,aAAa;EAC3B,MAAM,QAAQ,IAAI,KAAK,KAAK;EAC5B,OAAO;CACT;CACA,OAAO,MAAM,aAAa,IAAI,KAAK,OAAO,GAAG,KAAK;AACpD;AAEA,eAAe,aACb,IACA,KACA,SACA,OAC6B;CAC7B,MAAM,aAAa,MAAM,IAAI,GAAG,OAAO;CAEvC,IAAI,CAAC,MADa,GAAG,MAAM,MAAM;EAAE;EAAK;EAAS,OAAO,GAAG;EAAO;CAAW,GAAG,MAAM,EAAE,CAAC,GAEvF,OAAO,UAAU,OAAO,MAAM,cAAc,IAAI,KAAK,OAAO,IAAI;CAElE,MAAM,QAAQ,MAAM,GAAG,MAAM,IAAI,IAAI,KAAK;CAC1C,IAAI,UAAU,QAAQ,cAAc,KAAK,GAAG;EAE1C,MAAM,GAAG,MAAM,cAAc,aAAa,IAAI,OAAO,OAAO,GAAG,WAAW,MAAM,EAAE,CAAC;EACnF,OAAO;CACT;CACA,OAAO,MAAM,SAAS,IAAI,OAAO,SAAS,KAAK;AACjD;;;;;;;;AASA,eAAe,cACb,IACA,KACA,SAC6B;CAC7B,MAAM,KAAK,aAAa,IAAI,OAAO,OAAO;CAC1C,MAAM,UAAU,MAAM,GAAG,MAAM,eAAe,IAAI,MAAM,EAAE,CAAC;CAC3D,IAAI,YAAY,MACd,OAAO,MAAM,eAAe,IAAI,OAAO;CAEzC,MAAM,YAAY,IAAI,KAAK,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;CACjD,OAAO;AACT;AAEA,eAAe,YACb,IACA,KACA,QACe;CACf,MAAM,UAAU,MAAM,GAAG,MAAM,IAAI,IAAI,KAAK;CAC5C,IAAI,QAAQ,aAAa,SAAS,WAAW,YAAY,QAAQ,YAAY,IAAI,SAC/E,MAAM,GAAG,MAAM,MAAM,IAAI,OAAO,OAAO,WAAW,MAAM,EAAE,CAAC;AAE/D;;AAGA,eAAe,SACb,IACA,KACA,SACA,OACsB;CACtB,MAAM,OAAO,IAAI,KAAK;CACtB,MAAM,GAAG,MAAM,YAAY,IAAI,OAAO,SAAS,MAAM,EAAE,CAAC;CACxD,GAAG,QAAQ,MAAM;EAAE,OAAO,IAAI;EAAO;CAAQ,GAAG,aAAa;CAC7D,OAAO,cAAc,KAAK,SAAS,GAAG,OAAO;AAC/C;;AAGA,eAAe,OAAO,IAAkB,OAA4C;CAClF,IAAI,UAAU,MACZ,MAAM,GAAG,MAAM,cAAc,MAAM,IAAI,WAAW,MAAM,EAAE,CAAC;AAE/D;;;;;;AAOA,eAAe,QACb,IACA,KACA,OACe;CACf,MAAM,MAAM,MAAM,EAAE;CACpB,IAAI,UAAU,SAAS,MAAM,GAAG,MAAM,IAAI,MAAM,EAAE,EAAA,EAAI,WAAW,QAAQ;EACvE,MAAM,GAAG,MAAM,UAAU,IAAI,OAAO,QAAQ,GAAG;EAC/C;CACF;CACA,MAAM,OAAO,IAAI,KAAK;CACtB,MAAM,GAAG,MAAM,UAAU,IAAI,OAAO,UAAU,KAAK,qBAAqB;CACxE,GAAG,QAAQ,KAAK;EAAE,OAAO,IAAI;EAAO,UAAU,IAAI;CAAQ,GAAG,6BAA6B;CAC1F,MAAM,gBAAgB,IAAI,GAAG;AAC/B;;AAGA,eAAe,MAAM,IAAkB,IAA2B;CAChE,IAAI,GAAG,WAAW,KAAA,GAAW;EAC3B,MAAM,IAAI,SAAe,YAAY;GACnC,WAAW,SAAS,EAAE;EACxB,CAAC;EACD;CACF;CACA,MAAM,IAAI,SAAe,YAAY;EACnC,GAAG,QAAQ,WAAW,SAAS,EAAE;CACnC,CAAC;AACH;;AAGA,eAAe,gBAAgB,IAAkB,KAAmC;CAClF,IAAI,GAAG,gBAAgB,KAAA,GACrB;CAEF,MAAM,WAAW;CACjB,KAAK,IAAI,UAAU,GAAG,WAAW,UAAU,WAAW,GACpD,IAAI;EAEF,MAAM,GAAG,YAAY,cAAc,KAAK,IAAI,SAAS,GAAG,OAAO,GAAG,qBAAqB;EACvF;CACF,SAAS,OAAO;EACd,GAAG,QAAQ,MACT;GAAE,KAAK;GAAO,OAAO,IAAI;GAAO;GAAS;EAAS,GAClD,2BACF;EACA,IAAI,UAAU,UAEZ,MAAM,MAAM,IAAI,MAAM,OAAO;CAEjC;AAEJ"}

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

@@ -0,0 +1,11 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/db-queue/clock.ts
+/** ISO-8601 time `plusMs` from now on the queue's clock. */
+function isoAt(rt, plusMs = 0) {
+	return new Date(rt.now() + plusMs).toISOString();
+}
+export { isoAt };
+
+//# sourceMappingURL=clock.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clock.mjs","names":[],"sources":["../../../src/capture/db-queue/clock.ts"],"sourcesContent":["/** Time of the database queue: every timestamp it writes or compares comes from the runtime clock. */\nimport type { QueueRuntime } from \"./types.ts\";\n\n/** ISO-8601 time `plusMs` from now on the queue's clock. */\nexport function isoAt(rt: Pick<QueueRuntime, \"now\">, plusMs = 0): string {\n  return new Date(rt.now() + plusMs).toISOString();\n}\n"],"mappings":";;;;;AAIA,SAAgB,MAAM,IAA+B,SAAS,GAAW;CACvE,OAAO,IAAI,KAAK,GAAG,IAAI,IAAI,MAAM,CAAC,CAAC,YAAY;AACjD"}

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

@@ -0,0 +1,75 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { attemptRowId } from "../../models/capture-job.mjs";
+// src/capture/db-queue/codec.ts
+/** Serialize the request id, trace context and kind-specific fields of a job; null when empty. */
+function encodePayload(job) {
+	const stored = {};
+	if (job.reqId !== void 0) stored.reqId = job.reqId;
+	if (job.traceparent !== void 0) stored.traceparent = job.traceparent;
+	if (job.data !== void 0 && Object.keys(job.data).length > 0) stored.data = job.data;
+	return Object.keys(stored).length === 0 ? null : JSON.stringify(stored);
+}
+/** Parse a stored payload. A malformed one (a poison row) decodes as empty rather than throwing. */
+function decodePayload(raw) {
+	if (raw === null || raw === "") return {};
+	try {
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? pickPayload(parsed) : {};
+	} catch {
+		return {};
+	}
+}
+/** The job handed to a consumer for attempt `attempt` of a job row. */
+function toDatabaseJob(row, attempt, leaseMs) {
+	const payload = decodePayload(row.payload);
+	return withOptional({
+		buildId: row.buildId ?? "",
+		jobId: row.jobId,
+		kind: row.kind,
+		attempt,
+		attempts: attempt - 1,
+		maxAttempts: row.maxAttempts,
+		receipt: attemptRowId(row.jobId, attempt),
+		leaseMs,
+		data: payload.data ?? {}
+	}, row, payload);
+}
+/** The queue-view entry of a job row. */
+function toQueueEntry(row) {
+	const entry = {
+		buildId: row.buildId ?? "",
+		status: entryStatus(row.status),
+		queuedAt: row.createdAt
+	};
+	if (row.shardId !== null) entry.shard = row.shardId;
+	if (row.startedAt !== null) entry.startedAt = row.startedAt;
+	if (row.finishedAt !== null) entry.finishedAt = row.finishedAt;
+	if (row.error !== null) entry.error = row.error;
+	return entry;
+}
+function withOptional(job, row, payload) {
+	if (row.shardId !== null) job.shard = row.shardId;
+	if (payload.reqId !== void 0) job.reqId = payload.reqId;
+	if (payload.traceparent !== void 0) job.traceparent = payload.traceparent;
+	return job;
+}
+function entryStatus(status) {
+	if (status === "done") return "completed";
+	if (status === "expired") return "failed";
+	return status;
+}
+function pickPayload(parsed) {
+	const stored = {};
+	if (typeof parsed["reqId"] === "string") stored.reqId = parsed["reqId"];
+	if (typeof parsed["traceparent"] === "string") stored.traceparent = parsed["traceparent"];
+	if (isRecord(parsed["data"])) stored.data = parsed["data"];
+	return stored;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export { decodePayload, encodePayload, toDatabaseJob, toQueueEntry };
+
+//# sourceMappingURL=codec.mjs.map