@storyshelf/core 0.6.1 → 0.7.0

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

@@ -0,0 +1,94 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { ulid } from "../../utils/ulid.mjs";
+import { attemptRowId, isTerminalJob } from "../../models/capture-job.mjs";
+import { encodePayload, toQueueEntry } from "./codec.mjs";
+import { isoAt } from "./clock.mjs";
+//#region src/capture/db-queue/operations.ts
+/** Insert a queued job row and wake this instance's poller; resolves to the job id. */
+async function enqueueJob(rt, job) {
+	const id = ulid();
+	const now = isoAt(rt);
+	await rt.model.create({
+		id,
+		kind: job.kind,
+		buildId: job.buildId ?? null,
+		shardId: job.shard ?? null,
+		maxAttempts: job.maxAttempts ?? rt.maxAttempts,
+		payload: encodePayload(job)
+	}, now);
+	rt.logger?.info({
+		jobId: id,
+		kind: job.kind,
+		buildId: job.buildId
+	}, "job queued");
+	rt.wake.notify();
+	return id;
+}
+/**
+* The kinds the queue's views (`status`, `active`, `recent`, `cancel`) show: every polled kind but
+* `notify` (unless it is the only one), whose many short delivery jobs would bury a build's capture and publish jobs.
+*/
+function viewKinds(rt) {
+	const shown = rt.kinds.filter((kind) => kind !== "notify");
+	return shown.length > 0 ? shown : rt.kinds;
+}
+/** `CaptureQueue.enqueue`: a capture job for a build or one of its shards. */
+async function enqueueCapture(rt, job) {
+	await enqueueJob(rt, {
+		...job,
+		kind: "capture"
+	});
+}
+/** The build's own job most recently queued, as a queue entry. */
+async function statusOf(rt, buildId) {
+	const row = await rt.model.latestForBuild(buildId, viewKinds(rt));
+	return row === null ? null : toQueueEntry(row);
+}
+/** Queued and running jobs of this queue's kinds on every instance, oldest first. */
+async function activeEntries(rt) {
+	return (await rt.model.listActive(viewKinds(rt))).map((row) => toQueueEntry(row));
+}
+/** The newest jobs of this queue's kinds, newest first. */
+async function recentEntries(rt, limit) {
+	return (await rt.model.listRecent(viewKinds(rt), limit)).map((row) => toQueueEntry(row));
+}
+/**
+* Cancel a job (by job id) or every unfinished job of a build (by build id), of every kind that
+* shares the table (capture, publish and notify), whichever kinds this queue polls. A queued job ends `cancelled` at once; a running one is flagged on its job row and on
+* its current attempt row, so the holder sees it on its next renewal or cancel check.
+*/
+async function cancelJobs(rt, id) {
+	const targets = (await targetsOf(rt, id)).filter((row) => !isTerminalJob(row));
+	await Promise.all(targets.map(async (row) => {
+		await cancelOne(rt, row);
+	}));
+	if (targets.length > 0) rt.logger?.info({
+		id,
+		jobs: targets.length
+	}, "cancel requested");
+	return targets.length > 0;
+}
+async function targetsOf(rt, id) {
+	const row = await rt.model.get(id);
+	if (row?.entry === "job") return [row];
+	return await rt.model.listForBuild(id);
+}
+async function cancelOne(rt, row) {
+	const now = isoAt(rt);
+	await rt.model.flagCancel(row.jobId, now);
+	if (row.status === "queued") {
+		await rt.model.finishJob(row.jobId, "cancelled", now);
+		await flagAttempt(rt, attemptRowId(row.jobId, row.attempt + 1), now);
+		return;
+	}
+	await flagAttempt(rt, attemptRowId(row.jobId, row.attempt), now);
+}
+async function flagAttempt(rt, attemptId, now) {
+	if ((await rt.model.get(attemptId))?.status === "running") await rt.model.flagCancel(attemptId, now);
+}
+//#endregion
+export { activeEntries, cancelJobs, enqueueCapture, enqueueJob, recentEntries, statusOf };
+
+//# sourceMappingURL=operations.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.mjs","names":[],"sources":["../../../src/capture/db-queue/operations.ts"],"sourcesContent":["/** Enqueue, cancel and the cross-instance views (`status`/`active`/`recent`) of the database queue. */\nimport type { CaptureJob, QueueEntry } from \"../../adapters/capture-queue.ts\";\nimport { attemptRowId, isTerminalJob } from \"../../models/capture-job.ts\";\nimport type { CaptureJobKind, CaptureJobRow } from \"../../schema/capture-job.ts\";\nimport { ulid } from \"../../utils/ulid.ts\";\nimport { isoAt } from \"./clock.ts\";\nimport { encodePayload, toQueueEntry } from \"./codec.ts\";\nimport type { QueueJobInput, QueueRuntime } from \"./types.ts\";\n\n/** Insert a queued job row and wake this instance's poller; resolves to the job id. */\nexport async function enqueueJob(rt: QueueRuntime, job: QueueJobInput): Promise<string> {\n  const id = ulid();\n  const now = isoAt(rt);\n  await rt.model.create(\n    {\n      id,\n      kind: job.kind,\n      buildId: job.buildId ?? null,\n      shardId: job.shard ?? null,\n      maxAttempts: job.maxAttempts ?? rt.maxAttempts,\n      payload: encodePayload(job),\n    },\n    now,\n  );\n  rt.logger?.info({ jobId: id, kind: job.kind, buildId: job.buildId }, \"job queued\");\n  rt.wake.notify();\n  return id;\n}\n\n/**\n * The kinds the queue's views (`status`, `active`, `recent`, `cancel`) show: every polled kind but\n * `notify` (unless it is the only one), whose many short delivery jobs would bury a build's capture and publish jobs.\n */\nfunction viewKinds(rt: QueueRuntime): readonly CaptureJobKind[] {\n  const shown = rt.kinds.filter((kind) => kind !== \"notify\");\n  return shown.length > 0 ? shown : rt.kinds;\n}\n\n/** `CaptureQueue.enqueue`: a capture job for a build or one of its shards. */\nexport async function enqueueCapture(rt: QueueRuntime, job: CaptureJob): Promise<void> {\n  await enqueueJob(rt, { ...job, kind: \"capture\" });\n}\n\n/** The build's own job most recently queued, as a queue entry. */\nexport async function statusOf(rt: QueueRuntime, buildId: string): Promise<QueueEntry | null> {\n  const row = await rt.model.latestForBuild(buildId, viewKinds(rt));\n  return row === null ? null : toQueueEntry(row);\n}\n\n/** Queued and running jobs of this queue's kinds on every instance, oldest first. */\nexport async function activeEntries(rt: QueueRuntime): Promise<QueueEntry[]> {\n  return (await rt.model.listActive(viewKinds(rt))).map((row) => toQueueEntry(row));\n}\n\n/** The newest jobs of this queue's kinds, newest first. */\nexport async function recentEntries(rt: QueueRuntime, limit: number): Promise<QueueEntry[]> {\n  return (await rt.model.listRecent(viewKinds(rt), limit)).map((row) => toQueueEntry(row));\n}\n\n/**\n * Cancel a job (by job id) or every unfinished job of a build (by build id), of every kind that\n * shares the table (capture, publish and notify), whichever kinds this queue polls. A queued job ends `cancelled` at once; a running one is flagged on its job row and on\n * its current attempt row, so the holder sees it on its next renewal or cancel check.\n */\nexport async function cancelJobs(rt: QueueRuntime, id: string): Promise<boolean> {\n  const targets = (await targetsOf(rt, id)).filter((row) => !isTerminalJob(row));\n  await Promise.all(\n    targets.map(async (row) => {\n      await cancelOne(rt, row);\n    }),\n  );\n  if (targets.length > 0) {\n    rt.logger?.info({ id, jobs: targets.length }, \"cancel requested\");\n  }\n  return targets.length > 0;\n}\n\nasync function targetsOf(rt: QueueRuntime, id: string): Promise<CaptureJobRow[]> {\n  const row = await rt.model.get(id);\n  if (row?.entry === \"job\") {\n    return [row];\n  }\n  return await rt.model.listForBuild(id);\n}\n\nasync function cancelOne(rt: QueueRuntime, row: CaptureJobRow): Promise<void> {\n  const now = isoAt(rt);\n  // The flag goes first: it is never cleared, so a claim racing this cancel still sees it.\n  await rt.model.flagCancel(row.jobId, now);\n  if (row.status === \"queued\") {\n    await rt.model.finishJob(row.jobId, \"cancelled\", now);\n    // A claimer may have inserted the next attempt between our read and the write above.\n    await flagAttempt(rt, attemptRowId(row.jobId, row.attempt + 1), now);\n    return;\n  }\n  await flagAttempt(rt, attemptRowId(row.jobId, row.attempt), now);\n}\n\nasync function flagAttempt(rt: QueueRuntime, attemptId: string, now: string): Promise<void> {\n  const attempt = await rt.model.get(attemptId);\n  if (attempt?.status === \"running\") {\n    await rt.model.flagCancel(attemptId, now);\n  }\n}\n"],"mappings":";;;;;;;;;AAUA,eAAsB,WAAW,IAAkB,KAAqC;CACtF,MAAM,KAAK,KAAK;CAChB,MAAM,MAAM,MAAM,EAAE;CACpB,MAAM,GAAG,MAAM,OACb;EACE;EACA,MAAM,IAAI;EACV,SAAS,IAAI,WAAW;EACxB,SAAS,IAAI,SAAS;EACtB,aAAa,IAAI,eAAe,GAAG;EACnC,SAAS,cAAc,GAAG;CAC5B,GACA,GACF;CACA,GAAG,QAAQ,KAAK;EAAE,OAAO;EAAI,MAAM,IAAI;EAAM,SAAS,IAAI;CAAQ,GAAG,YAAY;CACjF,GAAG,KAAK,OAAO;CACf,OAAO;AACT;;;;;AAMA,SAAS,UAAU,IAA6C;CAC9D,MAAM,QAAQ,GAAG,MAAM,QAAQ,SAAS,SAAS,QAAQ;CACzD,OAAO,MAAM,SAAS,IAAI,QAAQ,GAAG;AACvC;;AAGA,eAAsB,eAAe,IAAkB,KAAgC;CACrF,MAAM,WAAW,IAAI;EAAE,GAAG;EAAK,MAAM;CAAU,CAAC;AAClD;;AAGA,eAAsB,SAAS,IAAkB,SAA6C;CAC5F,MAAM,MAAM,MAAM,GAAG,MAAM,eAAe,SAAS,UAAU,EAAE,CAAC;CAChE,OAAO,QAAQ,OAAO,OAAO,aAAa,GAAG;AAC/C;;AAGA,eAAsB,cAAc,IAAyC;CAC3E,QAAQ,MAAM,GAAG,MAAM,WAAW,UAAU,EAAE,CAAC,EAAA,CAAG,KAAK,QAAQ,aAAa,GAAG,CAAC;AAClF;;AAGA,eAAsB,cAAc,IAAkB,OAAsC;CAC1F,QAAQ,MAAM,GAAG,MAAM,WAAW,UAAU,EAAE,GAAG,KAAK,EAAA,CAAG,KAAK,QAAQ,aAAa,GAAG,CAAC;AACzF;;;;;;AAOA,eAAsB,WAAW,IAAkB,IAA8B;CAC/E,MAAM,WAAW,MAAM,UAAU,IAAI,EAAE,EAAA,CAAG,QAAQ,QAAQ,CAAC,cAAc,GAAG,CAAC;CAC7E,MAAM,QAAQ,IACZ,QAAQ,IAAI,OAAO,QAAQ;EACzB,MAAM,UAAU,IAAI,GAAG;CACzB,CAAC,CACH;CACA,IAAI,QAAQ,SAAS,GACnB,GAAG,QAAQ,KAAK;EAAE;EAAI,MAAM,QAAQ;CAAO,GAAG,kBAAkB;CAElE,OAAO,QAAQ,SAAS;AAC1B;AAEA,eAAe,UAAU,IAAkB,IAAsC;CAC/E,MAAM,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE;CACjC,IAAI,KAAK,UAAU,OACjB,OAAO,CAAC,GAAG;CAEb,OAAO,MAAM,GAAG,MAAM,aAAa,EAAE;AACvC;AAEA,eAAe,UAAU,IAAkB,KAAmC;CAC5E,MAAM,MAAM,MAAM,EAAE;CAEpB,MAAM,GAAG,MAAM,WAAW,IAAI,OAAO,GAAG;CACxC,IAAI,IAAI,WAAW,UAAU;EAC3B,MAAM,GAAG,MAAM,UAAU,IAAI,OAAO,aAAa,GAAG;EAEpD,MAAM,YAAY,IAAI,aAAa,IAAI,OAAO,IAAI,UAAU,CAAC,GAAG,GAAG;EACnE;CACF;CACA,MAAM,YAAY,IAAI,aAAa,IAAI,OAAO,IAAI,OAAO,GAAG,GAAG;AACjE;AAEA,eAAe,YAAY,IAAkB,WAAmB,KAA4B;CAE1F,KAAI,MADkB,GAAG,MAAM,IAAI,SAAS,EAAA,EAC/B,WAAW,WACtB,MAAM,GAAG,MAAM,WAAW,WAAW,GAAG;AAE5C"}

package/dist/capture/db-queue/poll-loop.d.mts

@@ -0,0 +1,30 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { PollCadence } from "./cadence.mjs";
+import { DatabaseCaptureQueue, DatabaseJob } from "./types.mjs";
+//#region src/capture/db-queue/poll-loop.d.ts
+/** Options of {@link startPollLoop}. */
+interface PollLoopOptions {
+  queue: Pick<DatabaseCaptureQueue, "poll" | "waitForWork">;
+  /** Jobs this instance runs at once (`testing.concurrency`). */
+  slots: number;
+  /** Run one claimed job to its end (ack or nack it); rejections are logged, never fatal. */
+  run: (job: DatabaseJob) => Promise<void>;
+  cadence?: PollCadence;
+  now?: () => number;
+  random?: () => number;
+  logger?: Logger;
+}
+/** Handle on a running poll loop. */
+interface PollLoop {
+  /** Jobs running right now. */
+  readonly busy: number;
+  /** Stop polling and wait for the jobs in flight to finish; idempotent. */
+  stop(): Promise<void>;
+}
+/** Start polling `queue` with `slots` concurrent jobs. */
+declare function startPollLoop(options: PollLoopOptions): PollLoop;
+//#endregion
+export { PollLoop, PollLoopOptions, startPollLoop };
+//# sourceMappingURL=poll-loop.d.mts.map

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

@@ -0,0 +1,89 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DEFAULT_CADENCE, nextPollDelay } from "./cadence.mjs";
+//#region src/capture/db-queue/poll-loop.ts
+/** Start polling `queue` with `slots` concurrent jobs. */
+function startPollLoop(options) {
+	const state = {
+		busy: 0,
+		stopped: false,
+		lastWorkAt: null,
+		inFlight: /* @__PURE__ */ new Set(),
+		nudge: () => {}
+	};
+	const done = loop(options, state);
+	return {
+		get busy() {
+			return state.busy;
+		},
+		stop: async () => {
+			state.stopped = true;
+			state.nudge();
+			await done;
+			await Promise.allSettled(state.inFlight);
+		}
+	};
+}
+async function loop(options, state) {
+	const now = options.now ?? Date.now;
+	while (!state.stopped) await step(options, state, now);
+}
+/** One turn: wait for a slot (no poll while all are busy), else probe once and run or idle. */
+async function step(options, state, now) {
+	if (state.busy >= options.slots) {
+		await nudged(state);
+		return;
+	}
+	const job = await pollOnce(options);
+	if (job === null) {
+		await idle(options, state, now);
+		return;
+	}
+	state.lastWorkAt = now();
+	launch(options, state, job);
+}
+async function pollOnce(options) {
+	try {
+		return await options.queue.poll();
+	} catch (error) {
+		options.logger?.warn({ err: error }, "queue poll failed");
+		return null;
+	}
+}
+async function idle(options, state, now) {
+	const delay = nextPollDelay(state.lastWorkAt, now(), options.cadence ?? DEFAULT_CADENCE, options.random);
+	if (await Promise.race([options.queue.waitForWork(delay), nudged(state).then(() => false)])) state.lastWorkAt = now();
+}
+function launch(options, state, job) {
+	state.busy += 1;
+	const running = runSafely(options, job).finally(() => {
+		state.busy -= 1;
+		state.inFlight.delete(running);
+		state.nudge();
+	});
+	state.inFlight.add(running);
+}
+async function runSafely(options, job) {
+	try {
+		await options.run(job);
+	} catch (error) {
+		options.logger?.error({
+			err: error,
+			jobId: job.jobId
+		}, "queue job run failed");
+	}
+}
+/** A promise the next nudge (slot freed, stop) resolves. */
+async function nudged(state) {
+	if (state.stopped) return;
+	const { promise, resolve } = Promise.withResolvers();
+	state.nudge = () => {
+		resolve(null);
+	};
+	await promise;
+}
+//#endregion
+export { startPollLoop };
+
+//# sourceMappingURL=poll-loop.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"poll-loop.mjs","names":[],"sources":["../../../src/capture/db-queue/poll-loop.ts"],"sourcesContent":["/**\n * The slot-aware poll loop over the database queue: an instance polls only while it has a free\n * slot, at the cadence of `cadence.ts`, and dispatches at once on a local enqueue. Each claimed job\n * runs in a slot; the caller's `run` owns ack/nack and the lease. The full consumer (retries, the\n * final-attempt rule, drain on SIGTERM) builds on this loop.\n */\nimport type { Logger } from \"../../logger.ts\";\nimport { DEFAULT_CADENCE, nextPollDelay, type PollCadence } from \"./cadence.ts\";\nimport type { DatabaseCaptureQueue, DatabaseJob } from \"./types.ts\";\n\n/** Options of {@link startPollLoop}. */\nexport interface PollLoopOptions {\n  queue: Pick<DatabaseCaptureQueue, \"poll\" | \"waitForWork\">;\n  /** Jobs this instance runs at once (`testing.concurrency`). */\n  slots: number;\n  /** Run one claimed job to its end (ack or nack it); rejections are logged, never fatal. */\n  run: (job: DatabaseJob) => Promise<void>;\n  cadence?: PollCadence;\n  now?: () => number;\n  random?: () => number;\n  logger?: Logger;\n}\n\n/** Handle on a running poll loop. */\nexport interface PollLoop {\n  /** Jobs running right now. */\n  readonly busy: number;\n  /** Stop polling and wait for the jobs in flight to finish; idempotent. */\n  stop(): Promise<void>;\n}\n\ninterface LoopState {\n  busy: number;\n  stopped: boolean;\n  lastWorkAt: number | null;\n  inFlight: Set<Promise<void>>;\n  /** Resolves the current idle wait early (slot freed or stop). */\n  nudge: () => void;\n}\n\n/** Start polling `queue` with `slots` concurrent jobs. */\nexport function startPollLoop(options: PollLoopOptions): PollLoop {\n  const state: LoopState = {\n    busy: 0,\n    stopped: false,\n    lastWorkAt: null,\n    inFlight: new Set(),\n    nudge: () => {},\n  };\n  const done = loop(options, state);\n  return {\n    get busy() {\n      return state.busy;\n    },\n    stop: async () => {\n      state.stopped = true;\n      state.nudge();\n      await done;\n      await Promise.allSettled(state.inFlight);\n    },\n  };\n}\n\nasync function loop(options: PollLoopOptions, state: LoopState): Promise<void> {\n  const now = options.now ?? Date.now;\n  while (!state.stopped) {\n    // oxlint-disable-next-line no-await-in-loop -- one step at a time is the loop\n    await step(options, state, now);\n  }\n}\n\n/** One turn: wait for a slot (no poll while all are busy), else probe once and run or idle. */\nasync function step(options: PollLoopOptions, state: LoopState, now: () => number): Promise<void> {\n  if (state.busy >= options.slots) {\n    await nudged(state);\n    return;\n  }\n  const job = await pollOnce(options);\n  if (job === null) {\n    await idle(options, state, now);\n    return;\n  }\n  state.lastWorkAt = now();\n  launch(options, state, job);\n}\n\nasync function pollOnce(options: PollLoopOptions): Promise<DatabaseJob | null> {\n  try {\n    return await options.queue.poll();\n  } catch (error) {\n    options.logger?.warn({ err: error }, \"queue poll failed\");\n    return null;\n  }\n}\n\nasync function idle(options: PollLoopOptions, state: LoopState, now: () => number): Promise<void> {\n  const delay = nextPollDelay(\n    state.lastWorkAt,\n    now(),\n    options.cadence ?? DEFAULT_CADENCE,\n    options.random,\n  );\n  const woken = await Promise.race([\n    options.queue.waitForWork(delay),\n    nudged(state).then(() => false),\n  ]);\n  if (woken) {\n    state.lastWorkAt = now();\n  }\n}\n\nfunction launch(options: PollLoopOptions, state: LoopState, job: DatabaseJob): void {\n  state.busy += 1;\n  const running = runSafely(options, job).finally(() => {\n    state.busy -= 1;\n    state.inFlight.delete(running);\n    state.nudge();\n  });\n  state.inFlight.add(running);\n}\n\nasync function runSafely(options: PollLoopOptions, job: DatabaseJob): Promise<void> {\n  try {\n    await options.run(job);\n  } catch (error) {\n    options.logger?.error({ err: error, jobId: job.jobId }, \"queue job run failed\");\n  }\n}\n\n/** A promise the next nudge (slot freed, stop) resolves. */\nasync function nudged(state: LoopState): Promise<void> {\n  if (state.stopped) {\n    return;\n  }\n  const { promise, resolve } = Promise.withResolvers<null>();\n  state.nudge = (): void => {\n    resolve(null);\n  };\n  await promise;\n}\n"],"mappings":";;;;;;AAyCA,SAAgB,cAAc,SAAoC;CAChE,MAAM,QAAmB;EACvB,MAAM;EACN,SAAS;EACT,YAAY;EACZ,0BAAU,IAAI,IAAI;EAClB,aAAa,CAAC;CAChB;CACA,MAAM,OAAO,KAAK,SAAS,KAAK;CAChC,OAAO;EACL,IAAI,OAAO;GACT,OAAO,MAAM;EACf;EACA,MAAM,YAAY;GAChB,MAAM,UAAU;GAChB,MAAM,MAAM;GACZ,MAAM;GACN,MAAM,QAAQ,WAAW,MAAM,QAAQ;EACzC;CACF;AACF;AAEA,eAAe,KAAK,SAA0B,OAAiC;CAC7E,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,OAAO,CAAC,MAAM,SAEZ,MAAM,KAAK,SAAS,OAAO,GAAG;AAElC;;AAGA,eAAe,KAAK,SAA0B,OAAkB,KAAkC;CAChG,IAAI,MAAM,QAAQ,QAAQ,OAAO;EAC/B,MAAM,OAAO,KAAK;EAClB;CACF;CACA,MAAM,MAAM,MAAM,SAAS,OAAO;CAClC,IAAI,QAAQ,MAAM;EAChB,MAAM,KAAK,SAAS,OAAO,GAAG;EAC9B;CACF;CACA,MAAM,aAAa,IAAI;CACvB,OAAO,SAAS,OAAO,GAAG;AAC5B;AAEA,eAAe,SAAS,SAAuD;CAC7E,IAAI;EACF,OAAO,MAAM,QAAQ,MAAM,KAAK;CAClC,SAAS,OAAO;EACd,QAAQ,QAAQ,KAAK,EAAE,KAAK,MAAM,GAAG,mBAAmB;EACxD,OAAO;CACT;AACF;AAEA,eAAe,KAAK,SAA0B,OAAkB,KAAkC;CAChG,MAAM,QAAQ,cACZ,MAAM,YACN,IAAI,GACJ,QAAQ,WAAW,iBACnB,QAAQ,MACV;CAKA,IAAI,MAJgB,QAAQ,KAAK,CAC/B,QAAQ,MAAM,YAAY,KAAK,GAC/B,OAAO,KAAK,CAAC,CAAC,WAAW,KAAK,CAChC,CAAC,GAEC,MAAM,aAAa,IAAI;AAE3B;AAEA,SAAS,OAAO,SAA0B,OAAkB,KAAwB;CAClF,MAAM,QAAQ;CACd,MAAM,UAAU,UAAU,SAAS,GAAG,CAAC,CAAC,cAAc;EACpD,MAAM,QAAQ;EACd,MAAM,SAAS,OAAO,OAAO;EAC7B,MAAM,MAAM;CACd,CAAC;CACD,MAAM,SAAS,IAAI,OAAO;AAC5B;AAEA,eAAe,UAAU,SAA0B,KAAiC;CAClF,IAAI;EACF,MAAM,QAAQ,IAAI,GAAG;CACvB,SAAS,OAAO;EACd,QAAQ,QAAQ,MAAM;GAAE,KAAK;GAAO,OAAO,IAAI;EAAM,GAAG,sBAAsB;CAChF;AACF;;AAGA,eAAe,OAAO,OAAiC;CACrD,IAAI,MAAM,SACR;CAEF,MAAM,EAAE,SAAS,YAAY,QAAQ,cAAoB;CACzD,MAAM,cAAoB;EACxB,QAAQ,IAAI;CACd;CACA,MAAM;AACR"}

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

@@ -0,0 +1,10 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "../../adapter/capture-queue.mjs";
+import "./types.mjs";
+//#region src/capture/db-queue/poll.d.ts
+/** Longest a nack may delay a retry; larger delays are clamped. */
+declare const MAX_NACK_DELAY_MS: number;
+//#endregion
+export { MAX_NACK_DELAY_MS };
+//# sourceMappingURL=poll.d.mts.map

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

@@ -0,0 +1,69 @@
+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";
+//#region 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
+	};
+}
+//#endregion
+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,12 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/db-queue/timers.d.ts
+/** 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;
+}
+//#endregion
+export { QueueTimers };
+//# sourceMappingURL=timers.d.mts.map

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

@@ -0,0 +1,37 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region 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);
+	};
+}
+//#endregion
+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,83 @@
+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";
+//#region src/capture/db-queue/types.d.ts
+/** 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>;
+}
+//#endregion
+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,12 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region 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;
+//#endregion
+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  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,48 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { REAL_TIMERS } from "./timers.mjs";
+//#region 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;
+}
+//#endregion
+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,39 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region 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");
+}
+//#endregion
+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"}