@storyshelf/core 0.6.2 → 0.8.0

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

@@ -0,0 +1,68 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { isTerminalJob, parseAttemptRowId } from "../../models/capture-job.mjs";
+import { isoAt } from "./clock.mjs";
+import { claimNext } from "./claim.mjs";
+// src/capture/db-queue/poll.ts
+/** Longest a nack may delay a retry; larger delays are clamped. */
+const MAX_NACK_DELAY_MS = 36e5;
+/**
+* Claim one job. Probes once; with `waitMs`, an empty probe waits for a local enqueue (or the
+* timeout) and probes once more only when woken, so an idle wait costs a single probe.
+*/
+async function pollJob(rt, options) {
+	const since = rt.wake.version();
+	rt.pollVersion = since;
+	const job = await claimNext(rt);
+	const waitMs = options?.waitMs ?? 0;
+	if (job !== null || waitMs <= 0) return job;
+	return await rt.wake.wait(waitMs, since) ? await claimNext(rt) : null;
+}
+/** The attempt succeeded: its row and the job row become `done` (a cancelled job stays cancelled). */
+async function ackJob(rt, job) {
+	const ref = attemptRef(job);
+	const now = isoAt(rt);
+	await rt.model.finishAttempt(ref.receipt, "done", now);
+	if ((await rt.model.get(ref.jobId))?.status !== "cancelled") await rt.model.finishJob(ref.jobId, "done", now);
+}
+/**
+* The attempt failed. Only the current holder settles the job: a holder whose attempt was taken
+* over (its row is no longer `running`, or the job moved on to a later attempt) writes nothing, so a
+* stale holder can never requeue or fail a job another instance is running.
+*/
+async function nackJob(rt, job, options = {}) {
+	const ref = attemptRef(job);
+	if ((await rt.model.get(ref.receipt))?.status !== "running") return;
+	await rt.model.finishAttempt(ref.receipt, "failed", isoAt(rt), options.error ?? null);
+	const row = await rt.model.get(ref.jobId);
+	if (row === null || isTerminalJob(row) || row.attempt !== ref.attempt) return;
+	await settleFailure(rt, row, options);
+}
+/** Cancelled, final, or retried after `delayMs` (clamped to `[0, MAX_NACK_DELAY_MS]`). */
+async function settleFailure(rt, row, options) {
+	const now = isoAt(rt);
+	const error = options.error ?? null;
+	if (row.cancelRequestedAt !== null) {
+		await rt.model.finishJob(row.jobId, "cancelled", now, error);
+		return;
+	}
+	if (options.requeue === false || row.attempt >= row.maxAttempts) {
+		await rt.model.finishJob(row.jobId, "failed", now, error ?? "failed");
+		return;
+	}
+	const delayMs = Math.min(Math.max(options.delayMs ?? 0, 0), MAX_NACK_DELAY_MS);
+	await rt.model.requeue(row.jobId, isoAt(rt, delayMs), error, now);
+}
+/** The attempt a polled job refers to, from its receipt (`<jobId>:<attempt>`). */
+function attemptRef(job) {
+	const parsed = job.receipt === void 0 ? null : parseAttemptRowId(job.receipt);
+	if (parsed === null || job.receipt === void 0) throw new Error("not a database queue job: missing or malformed receipt");
+	return {
+		receipt: job.receipt,
+		...parsed
+	};
+}
+export { MAX_NACK_DELAY_MS, ackJob, attemptRef, nackJob, pollJob };
+
+//# sourceMappingURL=poll.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"poll.mjs","names":[],"sources":["../../../src/capture/db-queue/poll.ts"],"sourcesContent":["/** `poll` / `ack` / `nack` of the database queue: claim, finish and retry-with-backoff of attempts. */\nimport type { PollableJob } from \"../../adapters/capture-queue.ts\";\nimport { isTerminalJob, parseAttemptRowId } from \"../../models/capture-job.ts\";\nimport type { CaptureJobRow } from \"../../schema/capture-job.ts\";\nimport { claimNext } from \"./claim.ts\";\nimport { isoAt } from \"./clock.ts\";\nimport type { DatabaseJob, QueueRuntime } from \"./types.ts\";\n\n/** Longest a nack may delay a retry; larger delays are clamped. */\nexport const MAX_NACK_DELAY_MS = 60 * 60_000;\n\n/** Options of `nack`, as `PollableCaptureQueue` defines them. */\nexport interface NackOptions {\n  requeue?: boolean;\n  delayMs?: number;\n  error?: string;\n}\n\n/**\n * Claim one job. Probes once; with `waitMs`, an empty probe waits for a local enqueue (or the\n * timeout) and probes once more only when woken, so an idle wait costs a single probe.\n */\nexport async function pollJob(\n  rt: QueueRuntime,\n  options?: { waitMs?: number },\n): Promise<DatabaseJob | null> {\n  const since = rt.wake.version();\n  rt.pollVersion = since;\n  const job = await claimNext(rt);\n  const waitMs = options?.waitMs ?? 0;\n  if (job !== null || waitMs <= 0) {\n    return job;\n  }\n  return (await rt.wake.wait(waitMs, since)) ? await claimNext(rt) : null;\n}\n\n/** The attempt succeeded: its row and the job row become `done` (a cancelled job stays cancelled). */\nexport async function ackJob(rt: QueueRuntime, job: PollableJob): Promise<void> {\n  const ref = attemptRef(job);\n  const now = isoAt(rt);\n  await rt.model.finishAttempt(ref.receipt, \"done\", now);\n  if ((await rt.model.get(ref.jobId))?.status !== \"cancelled\") {\n    await rt.model.finishJob(ref.jobId, \"done\", now);\n  }\n}\n\n/**\n * The attempt failed. Only the current holder settles the job: a holder whose attempt was taken\n * over (its row is no longer `running`, or the job moved on to a later attempt) writes nothing, so a\n * stale holder can never requeue or fail a job another instance is running.\n */\nexport async function nackJob(\n  rt: QueueRuntime,\n  job: PollableJob,\n  options: NackOptions = {},\n): Promise<void> {\n  const ref = attemptRef(job);\n  if ((await rt.model.get(ref.receipt))?.status !== \"running\") {\n    return;\n  }\n  await rt.model.finishAttempt(ref.receipt, \"failed\", isoAt(rt), options.error ?? null);\n  const row = await rt.model.get(ref.jobId);\n  if (row === null || isTerminalJob(row) || row.attempt !== ref.attempt) {\n    return;\n  }\n  await settleFailure(rt, row, options);\n}\n\n/** Cancelled, final, or retried after `delayMs` (clamped to `[0, MAX_NACK_DELAY_MS]`). */\nasync function settleFailure(\n  rt: QueueRuntime,\n  row: CaptureJobRow,\n  options: NackOptions,\n): Promise<void> {\n  const now = isoAt(rt);\n  const error = options.error ?? null;\n  if (row.cancelRequestedAt !== null) {\n    await rt.model.finishJob(row.jobId, \"cancelled\", now, error);\n    return;\n  }\n  if (options.requeue === false || row.attempt >= row.maxAttempts) {\n    await rt.model.finishJob(row.jobId, \"failed\", now, error ?? \"failed\");\n    return;\n  }\n  const delayMs = Math.min(Math.max(options.delayMs ?? 0, 0), MAX_NACK_DELAY_MS);\n  await rt.model.requeue(row.jobId, isoAt(rt, delayMs), error, now);\n}\n\n/** The attempt a polled job refers to, from its receipt (`<jobId>:<attempt>`). */\nexport function attemptRef(job: PollableJob): { receipt: string; jobId: string; attempt: number } {\n  const parsed = job.receipt === undefined ? null : parseAttemptRowId(job.receipt);\n  if (parsed === null || job.receipt === undefined) {\n    throw new Error(\"not a database queue job: missing or malformed receipt\");\n  }\n  return { receipt: job.receipt, ...parsed };\n}\n"],"mappings":";;;;;;;;AASA,MAAa,oBAAoB;;;;;AAajC,eAAsB,QACpB,IACA,SAC6B;CAC7B,MAAM,QAAQ,GAAG,KAAK,QAAQ;CAC9B,GAAG,cAAc;CACjB,MAAM,MAAM,MAAM,UAAU,EAAE;CAC9B,MAAM,SAAS,SAAS,UAAU;CAClC,IAAI,QAAQ,QAAQ,UAAU,GAC5B,OAAO;CAET,OAAQ,MAAM,GAAG,KAAK,KAAK,QAAQ,KAAK,IAAK,MAAM,UAAU,EAAE,IAAI;AACrE;;AAGA,eAAsB,OAAO,IAAkB,KAAiC;CAC9E,MAAM,MAAM,WAAW,GAAG;CAC1B,MAAM,MAAM,MAAM,EAAE;CACpB,MAAM,GAAG,MAAM,cAAc,IAAI,SAAS,QAAQ,GAAG;CACrD,KAAK,MAAM,GAAG,MAAM,IAAI,IAAI,KAAK,EAAA,EAAI,WAAW,aAC9C,MAAM,GAAG,MAAM,UAAU,IAAI,OAAO,QAAQ,GAAG;AAEnD;;;;;;AAOA,eAAsB,QACpB,IACA,KACA,UAAuB,CAAC,GACT;CACf,MAAM,MAAM,WAAW,GAAG;CAC1B,KAAK,MAAM,GAAG,MAAM,IAAI,IAAI,OAAO,EAAA,EAAI,WAAW,WAChD;CAEF,MAAM,GAAG,MAAM,cAAc,IAAI,SAAS,UAAU,MAAM,EAAE,GAAG,QAAQ,SAAS,IAAI;CACpF,MAAM,MAAM,MAAM,GAAG,MAAM,IAAI,IAAI,KAAK;CACxC,IAAI,QAAQ,QAAQ,cAAc,GAAG,KAAK,IAAI,YAAY,IAAI,SAC5D;CAEF,MAAM,cAAc,IAAI,KAAK,OAAO;AACtC;;AAGA,eAAe,cACb,IACA,KACA,SACe;CACf,MAAM,MAAM,MAAM,EAAE;CACpB,MAAM,QAAQ,QAAQ,SAAS;CAC/B,IAAI,IAAI,sBAAsB,MAAM;EAClC,MAAM,GAAG,MAAM,UAAU,IAAI,OAAO,aAAa,KAAK,KAAK;EAC3D;CACF;CACA,IAAI,QAAQ,YAAY,SAAS,IAAI,WAAW,IAAI,aAAa;EAC/D,MAAM,GAAG,MAAM,UAAU,IAAI,OAAO,UAAU,KAAK,SAAS,QAAQ;EACpE;CACF;CACA,MAAM,UAAU,KAAK,IAAI,KAAK,IAAI,QAAQ,WAAW,GAAG,CAAC,GAAG,iBAAiB;CAC7E,MAAM,GAAG,MAAM,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,GAAG,OAAO,GAAG;AAClE;;AAGA,SAAgB,WAAW,KAAuE;CAChG,MAAM,SAAS,IAAI,YAAY,KAAA,IAAY,OAAO,kBAAkB,IAAI,OAAO;CAC/E,IAAI,WAAW,QAAQ,IAAI,YAAY,KAAA,GACrC,MAAM,IAAI,MAAM,wDAAwD;CAE1E,OAAO;EAAE,SAAS,IAAI;EAAS,GAAG;CAAO;AAC3C"}

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

@@ -0,0 +1,10 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** Timer seam of the database queue: production uses the global timers, tests a manual clock. */
+/** The two timer calls the queue, its wake signal and the lease keeper make. */
+interface QueueTimers {
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+export { QueueTimers };
+//# sourceMappingURL=timers.d.mts.map

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

@@ -0,0 +1,36 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/db-queue/timers.ts
+/** Global timers, unref'd so a waiting poll or a lease check never holds the process open. */
+const REAL_TIMERS = {
+	setTimeout: (callback, ms) => {
+		const handle = setTimeout(callback, Math.max(0, ms));
+		handle.unref?.();
+		return handle;
+	},
+	clearTimeout: (handle) => {
+		clearTimeout(handle);
+	}
+};
+/** Call `callback` every `ms` until the returned stop function runs; built on `setTimeout`. */
+function repeatEvery(timers, ms, callback) {
+	let handle;
+	let stopped = false;
+	const arm = () => {
+		handle = timers.setTimeout(() => {
+			if (!stopped) {
+				callback();
+				arm();
+			}
+		}, ms);
+	};
+	arm();
+	return () => {
+		stopped = true;
+		timers.clearTimeout(handle);
+	};
+}
+export { REAL_TIMERS, repeatEvery };
+
+//# sourceMappingURL=timers.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timers.mjs","names":[],"sources":["../../../src/capture/db-queue/timers.ts"],"sourcesContent":["/** Timer seam of the database queue: production uses the global timers, tests a manual clock. */\n\n/** The two timer calls the queue, its wake signal and the lease keeper make. */\nexport interface QueueTimers {\n  setTimeout(callback: () => void, ms: number): unknown;\n  clearTimeout(handle: unknown): void;\n}\n\n/** Global timers, unref'd so a waiting poll or a lease check never holds the process open. */\nexport const REAL_TIMERS: QueueTimers = {\n  setTimeout: (callback, ms) => {\n    const handle = setTimeout(callback, Math.max(0, ms));\n    handle.unref?.();\n    return handle;\n  },\n  clearTimeout: (handle) => {\n    clearTimeout(handle as ReturnType<typeof setTimeout>);\n  },\n};\n\n/** Call `callback` every `ms` until the returned stop function runs; built on `setTimeout`. */\nexport function repeatEvery(timers: QueueTimers, ms: number, callback: () => void): () => void {\n  let handle: unknown;\n  let stopped = false;\n  const arm = (): void => {\n    handle = timers.setTimeout(() => {\n      if (!stopped) {\n        callback();\n        arm();\n      }\n    }, ms);\n  };\n  arm();\n  return () => {\n    stopped = true;\n    timers.clearTimeout(handle);\n  };\n}\n"],"mappings":";;;;;AASA,MAAa,cAA2B;CACtC,aAAa,UAAU,OAAO;EAC5B,MAAM,SAAS,WAAW,UAAU,KAAK,IAAI,GAAG,EAAE,CAAC;EACnD,OAAO,QAAQ;EACf,OAAO;CACT;CACA,eAAe,WAAW;EACxB,aAAa,MAAuC;CACtD;AACF;;AAGA,SAAgB,YAAY,QAAqB,IAAY,UAAkC;CAC7F,IAAI;CACJ,IAAI,UAAU;CACd,MAAM,YAAkB;EACtB,SAAS,OAAO,iBAAiB;GAC/B,IAAI,CAAC,SAAS;IACZ,SAAS;IACT,IAAI;GACN;EACF,GAAG,EAAE;CACP;CACA,IAAI;CACJ,aAAa;EACX,UAAU;EACV,OAAO,aAAa,MAAM;CAC5B;AACF"}

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

@@ -0,0 +1,81 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { AdapterLifecycle } from "../../adapter/metadata.mjs";
+import { CaptureJob, LeaseRenewal, PollableCaptureQueue, PollableJob } from "../../adapter/capture-queue.mjs";
+import { CaptureJobKind } from "../../schema/capture-job.mjs";
+import { QueueTimers } from "./timers.mjs";
+import "../../models/capture-job.mjs";
+/** Options of {@link createDatabaseCaptureQueue}. */
+interface DatabaseCaptureQueueOptions {
+  /** Job kinds this instance polls (default `["capture"]`); enqueue accepts every kind. */
+  kinds?: readonly CaptureJobKind[];
+  /** Lease granted per attempt, renewed by a heartbeat and by progress (default {@link DEFAULT_LEASE_MS}, 5 min; `testing.leaseSeconds`). */
+  leaseMs?: number;
+  /** Retries after the first attempt (`testing.retries`, default 2: three attempts in total). */
+  retries?: number;
+  /** Identity written on the attempt rows this instance holds (default host, pid and a random tag). */
+  owner?: string;
+  /** Clock in epoch ms (default `Date.now`); tests inject one to drive leases and visibility. */
+  now?: () => number;
+  /** Timers of the local wake wait (default the global timers); tests inject a manual clock. */
+  timers?: QueueTimers;
+  /** Explicit logger override; the host normally binds one through `setLogger`. */
+  logger?: Logger;
+  /**
+   * Called after a job failed because its last attempt lost its lease: nothing was running to
+   * record the failure, so the host writes it (a build left `capturing`). May run on every
+   * instance that finds the job, so it must be idempotent; a throw is logged and ignored.
+   */
+  onExhausted?: (job: DatabaseJob, error: string) => Promise<void>;
+}
+/** Default lease per attempt: long enough for a slow stage, short enough to recover a crash. */
+declare const DEFAULT_LEASE_MS: number;
+/** Default `testing.retries` (ADR 0006, decision 11). */
+declare const DEFAULT_RETRIES = 2;
+/** A job of any kind, as `enqueueJob` takes it. */
+interface QueueJobInput {
+  kind: CaptureJobKind;
+  /** Build the job works on; notify jobs may have none. */
+  buildId?: string | null;
+  /** `capture_shards` row, for a shard capture job. */
+  shard?: string;
+  reqId?: string;
+  traceparent?: string;
+  /** Kind-specific fields (channel id, zip key, …), stored as JSON. */
+  data?: Record<string, unknown>;
+  /** Attempts allowed in total for this job; defaults to the queue's (`retries` + 1). */
+  maxAttempts?: number;
+}
+/** A job claimed from the database queue. */
+interface DatabaseJob extends PollableJob {
+  /** Id of the job row (`receipt` is the attempt row, `<jobId>:<attempt>`). */
+  jobId: string;
+  kind: CaptureJobKind;
+  /** Attempt number, from 1 (`attempts` is the number made before this one). */
+  attempt: number;
+  maxAttempts: number;
+  /** Kind-specific fields given at enqueue. */
+  data: Record<string, unknown>;
+}
+/** The database queue: a {@link PollableCaptureQueue} plus multi-kind enqueue and a local wake. */
+interface DatabaseCaptureQueue extends PollableCaptureQueue {
+  readonly lifecycle: AdapterLifecycle;
+  poll(options?: {
+    waitMs?: number;
+  }): Promise<DatabaseJob | null>;
+  extend(job: PollableJob): Promise<LeaseRenewal>;
+  /** Put a job of any kind on the queue; resolves to its job id. */
+  enqueueJob(job: QueueJobInput): Promise<string>;
+  /** Cancel a job by job id, or every unfinished job of a build (every kind) by build id. */
+  cancel(id: string): Promise<boolean>;
+  /** Read the job's state without renewing its lease (the 5 s cancel check). */
+  inspect(job: PollableJob): Promise<LeaseRenewal>;
+  /**
+   * Resolve true when this instance enqueues a job (including one enqueued since the last `poll`
+   * began, so no wake-up is lost), false after `ms`.
+   */
+  waitForWork(ms: number): Promise<boolean>;
+}
+export { DEFAULT_LEASE_MS, DEFAULT_RETRIES, DatabaseCaptureQueue, DatabaseCaptureQueueOptions, DatabaseJob, QueueJobInput };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1,11 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/db-queue/types.ts
+/** Default lease per attempt: long enough for a slow stage, short enough to recover a crash. */
+const DEFAULT_LEASE_MS = 3e5;
+/** Default `testing.retries` (ADR 0006, decision 11). */
+const DEFAULT_RETRIES = 2;
+export { DEFAULT_LEASE_MS, DEFAULT_RETRIES };
+
+//# sourceMappingURL=types.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../src/capture/db-queue/types.ts"],"sourcesContent":["/** Option, job and runtime types of the database capture queue. */\nimport type {\n  CaptureJob,\n  LeaseRenewal,\n  PollableCaptureQueue,\n  PollableJob,\n} from \"../../adapters/capture-queue.ts\";\nimport type { AdapterLifecycle } from \"../../adapters/metadata.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport type { CaptureJobModel } from \"../../models/capture-job.ts\";\nimport type { CaptureJobKind } from \"../../schema/capture-job.ts\";\nimport type { QueueTimers } from \"./timers.ts\";\nimport type { WakeSignal } from \"./wake.ts\";\n\n/** Options of {@link createDatabaseCaptureQueue}. */\nexport interface DatabaseCaptureQueueOptions {\n  /** Job kinds this instance polls (default `[\"capture\"]`); enqueue accepts every kind. */\n  kinds?: readonly CaptureJobKind[];\n  /** Lease granted per attempt, renewed by a heartbeat and by progress (default {@link DEFAULT_LEASE_MS}, 5 min; `testing.leaseSeconds`). */\n  leaseMs?: number;\n  /** Retries after the first attempt (`testing.retries`, default 2: three attempts in total). */\n  retries?: number;\n  /** Identity written on the attempt rows this instance holds (default host, pid and a random tag). */\n  owner?: string;\n  /** Clock in epoch ms (default `Date.now`); tests inject one to drive leases and visibility. */\n  now?: () => number;\n  /** Timers of the local wake wait (default the global timers); tests inject a manual clock. */\n  timers?: QueueTimers;\n  /** Explicit logger override; the host normally binds one through `setLogger`. */\n  logger?: Logger;\n  /**\n   * Called after a job failed because its last attempt lost its lease: nothing was running to\n   * record the failure, so the host writes it (a build left `capturing`). May run on every\n   * instance that finds the job, so it must be idempotent; a throw is logged and ignored.\n   */\n  onExhausted?: (job: DatabaseJob, error: string) => Promise<void>;\n}\n\n/** Default lease per attempt: long enough for a slow stage, short enough to recover a crash. */\nexport const DEFAULT_LEASE_MS = 5 * 60_000;\n\n/** Default `testing.retries` (ADR 0006, decision 11). */\nexport const DEFAULT_RETRIES = 2;\n\n/** A job of any kind, as `enqueueJob` takes it. */\nexport interface QueueJobInput {\n  kind: CaptureJobKind;\n  /** Build the job works on; notify jobs may have none. */\n  buildId?: string | null;\n  /** `capture_shards` row, for a shard capture job. */\n  shard?: string;\n  reqId?: string;\n  traceparent?: string;\n  /** Kind-specific fields (channel id, zip key, …), stored as JSON. */\n  data?: Record<string, unknown>;\n  /** Attempts allowed in total for this job; defaults to the queue's (`retries` + 1). */\n  maxAttempts?: number;\n}\n\n/** A job claimed from the database queue. */\nexport interface DatabaseJob extends PollableJob {\n  /** Id of the job row (`receipt` is the attempt row, `<jobId>:<attempt>`). */\n  jobId: string;\n  kind: CaptureJobKind;\n  /** Attempt number, from 1 (`attempts` is the number made before this one). */\n  attempt: number;\n  maxAttempts: number;\n  /** Kind-specific fields given at enqueue. */\n  data: Record<string, unknown>;\n}\n\n/** The database queue: a {@link PollableCaptureQueue} plus multi-kind enqueue and a local wake. */\nexport interface DatabaseCaptureQueue extends PollableCaptureQueue {\n  readonly lifecycle: AdapterLifecycle;\n  poll(options?: { waitMs?: number }): Promise<DatabaseJob | null>;\n  extend(job: PollableJob): Promise<LeaseRenewal>;\n  /** Put a job of any kind on the queue; resolves to its job id. */\n  enqueueJob(job: QueueJobInput): Promise<string>;\n  /** Cancel a job by job id, or every unfinished job of a build (every kind) by build id. */\n  cancel(id: string): Promise<boolean>;\n  /** Read the job's state without renewing its lease (the 5 s cancel check). */\n  inspect(job: PollableJob): Promise<LeaseRenewal>;\n  /**\n   * Resolve true when this instance enqueues a job (including one enqueued since the last `poll`\n   * began, so no wake-up is lost), false after `ms`.\n   */\n  waitForWork(ms: number): Promise<boolean>;\n}\n\n/** State shared by the queue's modules. */\nexport interface QueueRuntime {\n  model: CaptureJobModel;\n  kinds: readonly CaptureJobKind[];\n  leaseMs: number;\n  maxAttempts: number;\n  owner: string;\n  now: () => number;\n  timers?: QueueTimers;\n  wake: WakeSignal;\n  /** Wake version read when the latest poll began. */\n  pollVersion: number;\n  logger?: Logger;\n  onExhausted?: DatabaseCaptureQueueOptions[\"onExhausted\"];\n}\n\n/** The capture-shaped job `enqueue` takes, re-exported for the modules. */\nexport type { CaptureJob };\n"],"mappings":";;;;;AAuCA,MAAa,mBAAmB;;AAGhC,MAAa,kBAAkB"}

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

@@ -0,0 +1,47 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { REAL_TIMERS } from "./timers.mjs";
+// src/capture/db-queue/wake.ts
+/** In-process wake signal: an enqueue on this instance wakes its waiting poller at once. */
+/** Create a wake signal over `timers` (unref'd globals by default). */
+function createWakeSignal(timers = REAL_TIMERS) {
+	const waiters = /* @__PURE__ */ new Set();
+	let closed = false;
+	let notifies = 0;
+	const settleAll = (woken) => {
+		for (const settle of waiters) settle(woken);
+		waiters.clear();
+	};
+	return {
+		notify: () => {
+			notifies += 1;
+			settleAll(true);
+		},
+		version: () => notifies,
+		wait: async (ms, since) => {
+			if (closed || since !== void 0 && since !== notifies) return !closed;
+			return await waitFor(timers, waiters, ms);
+		},
+		close: () => {
+			closed = true;
+			settleAll(false);
+		}
+	};
+}
+async function waitFor(timers, waiters, ms) {
+	const { promise, resolve } = Promise.withResolvers();
+	const timer = timers.setTimeout(() => {
+		waiters.delete(settle);
+		resolve(false);
+	}, ms);
+	const settle = (woken) => {
+		timers.clearTimeout(timer);
+		resolve(woken);
+	};
+	waiters.add(settle);
+	return await promise;
+}
+export { createWakeSignal };
+
+//# sourceMappingURL=wake.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wake.mjs","names":[],"sources":["../../../src/capture/db-queue/wake.ts"],"sourcesContent":["/** In-process wake signal: an enqueue on this instance wakes its waiting poller at once. */\nimport { REAL_TIMERS, type QueueTimers } from \"./timers.ts\";\n\n/** Wakes waiters on local enqueue; other instances find the job on their next poll. */\nexport interface WakeSignal {\n  /** Wake every current waiter. */\n  notify(): void;\n  /** Count of notifies so far; pass it to `wait` to catch a notify that came before the wait. */\n  version(): number;\n  /**\n   * Resolve true when notified, false after `ms` or once closed. With `since`, resolve true at once\n   * if a notify came after that version was read (no lost wake-up between a probe and its wait).\n   */\n  wait(ms: number, since?: number): Promise<boolean>;\n  /** Release every waiter (false) and make later waits resolve at once; idempotent. */\n  close(): void;\n}\n\n/** Create a wake signal over `timers` (unref'd globals by default). */\nexport function createWakeSignal(timers: QueueTimers = REAL_TIMERS): WakeSignal {\n  const waiters = new Set<(woken: boolean) => void>();\n  let closed = false;\n  let notifies = 0;\n  const settleAll = (woken: boolean): void => {\n    for (const settle of waiters) {\n      settle(woken);\n    }\n    waiters.clear();\n  };\n  return {\n    notify: () => {\n      notifies += 1;\n      settleAll(true);\n    },\n    version: () => notifies,\n    wait: async (ms, since) => {\n      if (closed || (since !== undefined && since !== notifies)) {\n        return !closed;\n      }\n      return await waitFor(timers, waiters, ms);\n    },\n    close: () => {\n      closed = true;\n      settleAll(false);\n    },\n  };\n}\n\nasync function waitFor(\n  timers: QueueTimers,\n  waiters: Set<(woken: boolean) => void>,\n  ms: number,\n): Promise<boolean> {\n  const { promise, resolve } = Promise.withResolvers<boolean>();\n  const timer = timers.setTimeout(() => {\n    waiters.delete(settle);\n    resolve(false);\n  }, ms);\n  const settle = (woken: boolean): void => {\n    timers.clearTimeout(timer);\n    resolve(woken);\n  };\n  waiters.add(settle);\n  return await promise;\n}\n"],"mappings":";;;;;;;AAmBA,SAAgB,iBAAiB,SAAsB,aAAyB;CAC9E,MAAM,0BAAU,IAAI,IAA8B;CAClD,IAAI,SAAS;CACb,IAAI,WAAW;CACf,MAAM,aAAa,UAAyB;EAC1C,KAAK,MAAM,UAAU,SACnB,OAAO,KAAK;EAEd,QAAQ,MAAM;CAChB;CACA,OAAO;EACL,cAAc;GACZ,YAAY;GACZ,UAAU,IAAI;EAChB;EACA,eAAe;EACf,MAAM,OAAO,IAAI,UAAU;GACzB,IAAI,UAAW,UAAU,KAAA,KAAa,UAAU,UAC9C,OAAO,CAAC;GAEV,OAAO,MAAM,QAAQ,QAAQ,SAAS,EAAE;EAC1C;EACA,aAAa;GACX,SAAS;GACT,UAAU,KAAK;EACjB;CACF;AACF;AAEA,eAAe,QACb,QACA,SACA,IACkB;CAClB,MAAM,EAAE,SAAS,YAAY,QAAQ,cAAuB;CAC5D,MAAM,QAAQ,OAAO,iBAAiB;EACpC,QAAQ,OAAO,MAAM;EACrB,QAAQ,KAAK;CACf,GAAG,EAAE;CACL,MAAM,UAAU,UAAyB;EACvC,OAAO,aAAa,KAAK;EACzB,QAAQ,KAAK;CACf;CACA,QAAQ,IAAI,MAAM;CAClB,OAAO,MAAM;AACf"}

package/dist/capture/design.mjs

@@ -0,0 +1,38 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/design.ts
+/**
+* Resolve a story's design URL. `storyshelf.figma` (plain string) wins over the
+* `design` addon shape (`string | {url} | {type,url} | {type,url}[]`, first URL wins).
+*/
+function extractDesignUrl(parameters, parse) {
+	const explicit = parameters?.storyshelf?.figma;
+	const raw = typeof explicit === "string" && explicit.trim() !== "" ? explicit : firstDesignUrl(parameters?.design);
+	if (raw === void 0 || raw.trim() === "") return {};
+	const parsed = parse(raw);
+	return parsed ? { url: parsed.url } : { invalid: raw };
+}
+/** First URL of the `design` addon value, whatever shape it takes. */
+function firstDesignUrl(value) {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const url = firstDesignUrl(item);
+			if (url !== void 0) return url;
+		}
+		return;
+	}
+	const url = value?.url;
+	return typeof url === "string" ? url : void 0;
+}
+/** Log (once per story) design values that were declared but are not usable Figma URLs. */
+function logInvalidDesigns(logger, stories) {
+	for (const story of stories) if (story.designInvalid !== void 0) logger?.warn({
+		storyId: story.id,
+		design: story.designInvalid
+	}, "ignored invalid design url");
+}
+export { extractDesignUrl, logInvalidDesigns };
+
+//# sourceMappingURL=design.mjs.map

package/dist/capture/design.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.mjs","names":[],"sources":["../../src/capture/design.ts"],"sourcesContent":["/** Design-source extraction from Storybook story parameters (`design` addon + `storyshelf.figma`). */\n\n/** Story parameters relevant to design linking, as serialized in the Storybook index. */\nexport interface DesignParameters {\n  design?: unknown;\n  storyshelf?: { figma?: unknown };\n}\n\n/** Parses a declared link into its canonical URL; null when no design provider accepts it. */\nexport type DesignUrlParser = (raw: string) => { url: string } | null;\n\n/** Outcome of extraction: a valid design URL, a rejected raw value, or nothing declared. */\nexport interface DesignExtraction {\n  url?: string;\n  /** Raw value that was declared but is not a usable design URL (logged by the caller). */\n  invalid?: string;\n}\n\n/**\n * Resolve a story's design URL. `storyshelf.figma` (plain string) wins over the\n * `design` addon shape (`string | {url} | {type,url} | {type,url}[]`, first URL wins).\n */\nexport function extractDesignUrl(\n  parameters: DesignParameters | undefined,\n  parse: DesignUrlParser,\n): DesignExtraction {\n  const explicit = parameters?.storyshelf?.figma;\n  const raw =\n    typeof explicit === \"string\" && explicit.trim() !== \"\"\n      ? explicit\n      : firstDesignUrl(parameters?.design);\n  if (raw === undefined || raw.trim() === \"\") return {};\n  const parsed = parse(raw);\n  return parsed ? { url: parsed.url } : { invalid: raw };\n}\n\n/** First URL of the `design` addon value, whatever shape it takes. */\nfunction firstDesignUrl(value: unknown): string | undefined {\n  if (typeof value === \"string\") return value;\n  if (Array.isArray(value)) {\n    for (const item of value as unknown[]) {\n      const url = firstDesignUrl(item);\n      if (url !== undefined) return url;\n    }\n    return undefined;\n  }\n  const url = (value as { url?: unknown } | null | undefined)?.url;\n  return typeof url === \"string\" ? url : undefined;\n}\n\n/** Log (once per story) design values that were declared but are not usable Figma URLs. */\nexport function logInvalidDesigns(\n  logger: { warn(obj: object, msg: string): void } | undefined,\n  stories: readonly { id: string; designInvalid?: string }[],\n): void {\n  for (const story of stories) {\n    if (story.designInvalid !== undefined) {\n      logger?.warn(\n        { storyId: story.id, design: story.designInvalid },\n        \"ignored invalid design url\",\n      );\n    }\n  }\n}\n"],"mappings":";;;;;;;;AAsBA,SAAgB,iBACd,YACA,OACkB;CAClB,MAAM,WAAW,YAAY,YAAY;CACzC,MAAM,MACJ,OAAO,aAAa,YAAY,SAAS,KAAK,MAAM,KAChD,WACA,eAAe,YAAY,MAAM;CACvC,IAAI,QAAQ,KAAA,KAAa,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC;CACpD,MAAM,SAAS,MAAM,GAAG;CACxB,OAAO,SAAS,EAAE,KAAK,OAAO,IAAI,IAAI,EAAE,SAAS,IAAI;AACvD;;AAGA,SAAS,eAAe,OAAoC;CAC1D,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,KAAK,MAAM,QAAQ,OAAoB;GACrC,MAAM,MAAM,eAAe,IAAI;GAC/B,IAAI,QAAQ,KAAA,GAAW,OAAO;EAChC;EACA;CACF;CACA,MAAM,MAAO,OAAgD;CAC7D,OAAO,OAAO,QAAQ,WAAW,MAAM,KAAA;AACzC;;AAGA,SAAgB,kBACd,QACA,SACM;CACN,KAAK,MAAM,SAAS,SAClB,IAAI,MAAM,kBAAkB,KAAA,GAC1B,QAAQ,KACN;EAAE,SAAS,MAAM;EAAI,QAAQ,MAAM;CAAc,GACjD,4BACF;AAGN"}

package/dist/capture/diff-record.mjs

@@ -1,18 +1,38 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { diffImages } from "../diff/engine.mjs";
-import { DEFAULT_DIFF_OPTIONS } from "../diff/options.mjs";
-//#region src/capture/diff-record.ts
+import { DEFAULT_DIFF_OPTIONS, diffImagesAsync } from "@storyshelf/image";
+// src/capture/diff-record.ts
+/** Diff a stored screenshot against a baseline and persist the overlay; shared by capture and re-diff. */
 /** Per-story `diffThreshold` when it is a finite number in 0..1; otherwise the project threshold. */
 function resolvePixelThreshold(projectThreshold, override) {
 	return typeof override === "number" && Number.isFinite(override) && override >= 0 && override <= 1 ? override : projectThreshold;
 }
+/**
+* Content-addressed screenshots share a path exactly when their bytes are equal, so the diff is
+* empty without reading either image. Dimensions are not known (nothing was read) and report 0.
+*/
+function samePathResult() {
+	const unread = {
+		width: 0,
+		height: 0
+	};
+	return {
+		passed: true,
+		diffPixels: 0,
+		diffRatio: 0,
+		diffImage: null,
+		baselineDimensions: unread,
+		currentDimensions: unread,
+		sizeChanged: false
+	};
+}
 /** Read two stored PNGs and diff them with the project's thresholds (optionally a per-story pixel threshold). */
 async function diffStoredScreenshots(storage, project, baselinePath, currentPath, diffThreshold) {
+	if (baselinePath === currentPath) return samePathResult();
 	const current = await storage.read(currentPath);
 	const previous = await storage.read(baselinePath);
-	return diffImages(previous, current, {
+	return await diffImagesAsync(previous, current, {
 		...DEFAULT_DIFF_OPTIONS,
 		pixelThreshold: resolvePixelThreshold(project.pixelThreshold, diffThreshold),
 		maxDiffRatio: project.maxDiffRatio
@@ -24,7 +44,6 @@ async function writeDiffOverlay(storage, path, result, passed) {
 	await storage.write(path, result.diffImage);
 	return path;
 }
-//#endregion
 export { diffStoredScreenshots, resolvePixelThreshold, writeDiffOverlay };
 
 //# sourceMappingURL=diff-record.mjs.map

package/dist/capture/diff-record.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"diff-record.mjs","names":[],"sources":["../../src/capture/diff-record.ts"],"sourcesContent":["/** Diff a stored screenshot against a baseline and persist the overlay; shared by capture and re-diff. */\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { diffImages } from \"../diff/engine.ts\";\nimport { DEFAULT_DIFF_OPTIONS, type DiffResult } from \"../diff/options.ts\";\n\n/** Project thresholds that drive a diff. */\nexport interface DiffThresholds {\n  pixelThreshold: number;\n  maxDiffRatio: number;\n}\n\n/** Per-story `diffThreshold` when it is a finite number in 0..1; otherwise the project threshold. */\nexport function resolvePixelThreshold(projectThreshold: number, override?: number): number {\n  const valid = typeof override === \"number\" && Number.isFinite(override);\n  return valid && override >= 0 && override <= 1 ? override : projectThreshold;\n}\n\n/** Read two stored PNGs and diff them with the project's thresholds (optionally a per-story pixel threshold). */\nexport async function diffStoredScreenshots(\n  storage: StorageAdapter,\n  project: DiffThresholds,\n  baselinePath: string,\n  currentPath: string,\n  diffThreshold?: number,\n): Promise<DiffResult> {\n  const current = await storage.read(currentPath);\n  const previous = await storage.read(baselinePath);\n  return diffImages(previous, current, {\n    ...DEFAULT_DIFF_OPTIONS,\n    pixelThreshold: resolvePixelThreshold(project.pixelThreshold, diffThreshold),\n    maxDiffRatio: project.maxDiffRatio,\n  });\n}\n\n/** Write the diff overlay for a failing diff; returns the stored path, or null when none applies. */\nexport async function writeDiffOverlay(\n  storage: StorageAdapter,\n  path: string,\n  result: Pick<DiffResult, \"diffImage\">,\n  passed: boolean,\n): Promise<string | null> {\n  if (passed || !result.diffImage) {\n    return null;\n  }\n  await storage.write(path, result.diffImage);\n  return path;\n}\n"],"mappings":";;;;;;;AAYA,SAAgB,sBAAsB,kBAA0B,UAA2B;CAEzF,OADc,OAAO,aAAa,YAAY,OAAO,SAAS,QAAQ,KACtD,YAAY,KAAK,YAAY,IAAI,WAAW;AAC9D;;AAGA,eAAsB,sBACpB,SACA,SACA,cACA,aACA,eACqB;CACrB,MAAM,UAAU,MAAM,QAAQ,KAAK,WAAW;CAC9C,MAAM,WAAW,MAAM,QAAQ,KAAK,YAAY;CAChD,OAAO,WAAW,UAAU,SAAS;EACnC,GAAG;EACH,gBAAgB,sBAAsB,QAAQ,gBAAgB,aAAa;EAC3E,cAAc,QAAQ;CACxB,CAAC;AACH;;AAGA,eAAsB,iBACpB,SACA,MACA,QACA,QACwB;CACxB,IAAI,UAAU,CAAC,OAAO,WACpB,OAAO;CAET,MAAM,QAAQ,MAAM,MAAM,OAAO,SAAS;CAC1C,OAAO;AACT"}
+{"version":3,"file":"diff-record.mjs","names":[],"sources":["../../src/capture/diff-record.ts"],"sourcesContent":["/** Diff a stored screenshot against a baseline and persist the overlay; shared by capture and re-diff. */\nimport { DEFAULT_DIFF_OPTIONS, diffImagesAsync, type DiffResult } from \"@storyshelf/image\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\n\n/** Project thresholds that drive a diff. */\nexport interface DiffThresholds {\n  pixelThreshold: number;\n  maxDiffRatio: number;\n}\n\n/** Per-story `diffThreshold` when it is a finite number in 0..1; otherwise the project threshold. */\nexport function resolvePixelThreshold(projectThreshold: number, override?: number): number {\n  const valid = typeof override === \"number\" && Number.isFinite(override);\n  return valid && override >= 0 && override <= 1 ? override : projectThreshold;\n}\n\n/**\n * Content-addressed screenshots share a path exactly when their bytes are equal, so the diff is\n * empty without reading either image. Dimensions are not known (nothing was read) and report 0.\n */\nfunction samePathResult(): DiffResult {\n  const unread = { width: 0, height: 0 };\n  return {\n    passed: true,\n    diffPixels: 0,\n    diffRatio: 0,\n    diffImage: null,\n    baselineDimensions: unread,\n    currentDimensions: unread,\n    sizeChanged: false,\n  };\n}\n\n/** Read two stored PNGs and diff them with the project's thresholds (optionally a per-story pixel threshold). */\nexport async function diffStoredScreenshots(\n  storage: StorageAdapter,\n  project: DiffThresholds,\n  baselinePath: string,\n  currentPath: string,\n  diffThreshold?: number,\n): Promise<DiffResult> {\n  if (baselinePath === currentPath) {\n    return samePathResult();\n  }\n  const current = await storage.read(currentPath);\n  const previous = await storage.read(baselinePath);\n  return await diffImagesAsync(previous, current, {\n    ...DEFAULT_DIFF_OPTIONS,\n    pixelThreshold: resolvePixelThreshold(project.pixelThreshold, diffThreshold),\n    maxDiffRatio: project.maxDiffRatio,\n  });\n}\n\n/** Write the diff overlay for a failing diff; returns the stored path, or null when none applies. */\nexport async function writeDiffOverlay(\n  storage: StorageAdapter,\n  path: string,\n  result: Pick<DiffResult, \"diffImage\">,\n  passed: boolean,\n): Promise<string | null> {\n  if (passed || !result.diffImage) {\n    return null;\n  }\n  await storage.write(path, result.diffImage);\n  return path;\n}\n"],"mappings":";;;;;;;AAWA,SAAgB,sBAAsB,kBAA0B,UAA2B;CAEzF,OADc,OAAO,aAAa,YAAY,OAAO,SAAS,QAAQ,KACtD,YAAY,KAAK,YAAY,IAAI,WAAW;AAC9D;;;;;AAMA,SAAS,iBAA6B;CACpC,MAAM,SAAS;EAAE,OAAO;EAAG,QAAQ;CAAE;CACrC,OAAO;EACL,QAAQ;EACR,YAAY;EACZ,WAAW;EACX,WAAW;EACX,oBAAoB;EACpB,mBAAmB;EACnB,aAAa;CACf;AACF;;AAGA,eAAsB,sBACpB,SACA,SACA,cACA,aACA,eACqB;CACrB,IAAI,iBAAiB,aACnB,OAAO,eAAe;CAExB,MAAM,UAAU,MAAM,QAAQ,KAAK,WAAW;CAC9C,MAAM,WAAW,MAAM,QAAQ,KAAK,YAAY;CAChD,OAAO,MAAM,gBAAgB,UAAU,SAAS;EAC9C,GAAG;EACH,gBAAgB,sBAAsB,QAAQ,gBAAgB,aAAa;EAC3E,cAAc,QAAQ;CACxB,CAAC;AACH;;AAGA,eAAsB,iBACpB,SACA,MACA,QACA,QACwB;CACxB,IAAI,UAAU,CAAC,OAAO,WACpB,OAAO;CAET,MAAM,QAAQ,MAAM,MAAM,OAAO,SAAS;CAC1C,OAAO;AACT"}

package/dist/capture/dispatch.d.mts

@@ -1,36 +1,39 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { DatabaseAdapter } from "../adapter/database.mjs";
-import { GitHostProvider } from "../adapter/git-host.mjs";
 import { Logger } from "../logger.mjs";
-import { SecretInput } from "../utils/encrypt.mjs";
+import { DatabaseAdapter } from "../adapter/database.mjs";
 import { BuildTables } from "../models/build.mjs";
 import { CaptureAttemptTables } from "../models/capture-attempt.mjs";
 import { CaptureLogTables } from "../models/capture-log.mjs";
 import { ProjectTables } from "../models/project.mjs";
+import { JobLease } from "./job-lease.mjs";
 import { CaptureJobOptions } from "./orchestrator.mjs";
-import { StatusConfigTables } from "../models/status-config.mjs";
-//#region src/capture/dispatch.d.ts
+import { BuildStatePublisher } from "./build-state/types.mjs";
 /** Build the queue's job runner: post pending, apply skip rules, capture, report. */
-declare function createDispatchJob(deps: DispatchDeps): (job: CaptureDispatchJob) => Promise<void>;
+declare function createDispatchJob(deps: DispatchDeps): (job: CaptureDispatchJob, lease?: JobLease) => Promise<void>;
 /** Table handles required by dispatch. */
-type DispatchTables = BuildTables & ProjectTables & StatusConfigTables & CaptureAttemptTables & CaptureLogTables;
+type DispatchTables = BuildTables & ProjectTables & CaptureAttemptTables & CaptureLogTables;
 /** Dependencies for building the capture queue's job runner. */
 interface DispatchDeps {
   db: DatabaseAdapter;
   tables: DispatchTables;
   jobOptions: CaptureJobOptions;
-  gitHosts: GitHostProvider[];
-  secret: SecretInput;
+  /** Shows a build's current state on its git channels; called at every transition. */
+  buildState: BuildStatePublisher;
   logger: Logger;
+  /** Redeliveries the queue allows a failing job; a shard's last try is its final word. */
+  maxRetries?: number | undefined;
 }
 /** A queued capture job. */
 interface CaptureDispatchJob {
   buildId: string;
+  /** A `capture_shards` row to render; absent for the build's own (plan or whole-build) job. */
+  shard?: string | undefined;
+  /** Times the queue has already delivered this job and seen it fail. */
+  attempts?: number | undefined;
   reqId?: string;
   /** W3C `traceparent` continuing the enqueueing request's trace. */
   traceparent?: string;
 }
-//#endregion
 export { CaptureDispatchJob, DispatchDeps, DispatchTables, createDispatchJob };
 //# sourceMappingURL=dispatch.d.mts.map