@storyshelf/core 0.6.2 → 0.8.0

package/dist/capture/dispatch.mjs

@@ -1,40 +1,51 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { BuildModel } from "../models/build.mjs";
+import { redactSecrets } from "../utils/redact.mjs";
 import { CaptureAttemptModel, emitAttemptLog } from "../models/capture-attempt.mjs";
+import { BuildModel } from "../models/build.mjs";
+import { SignedUrlLifetimeError } from "./token-chunks.mjs";
+import { CaptureShardModel } from "../models/capture-shard.mjs";
 import { ProjectModel } from "../models/project.mjs";
 import { executeCaptureJob } from "./orchestrator.mjs";
-import { postStatusesForBuild } from "./status-fanout.mjs";
 import { CaptureLogModel } from "../models/capture-log.mjs";
-import { hasApprovedBuildForSha, isAlreadyMerged } from "./skip-checks.mjs";
-//#region src/capture/dispatch.ts
+import { leaseProgress } from "./progress.mjs";
+import { executeCaptureShard } from "./shards/execute.mjs";
+import { hasApprovedBuildForSha } from "./skip-checks.mjs";
+// src/capture/dispatch.ts
 /** Build the queue's job runner: post pending, apply skip rules, capture, report. */
 function createDispatchJob(deps) {
-	return async (job) => {
-		const target = await loadJobTarget(deps, job);
-		if (!target) return;
-		const pendingUrl = `/projects/${target.project.slug}/builds/${job.buildId}`;
-		await postPending(deps, target.project, pendingUrl, target.build.gitSha);
-		const { attempt, recordLog } = await beginAttempt(deps, target.project, target.build, job.reqId);
-		const ctx = {
-			deps,
-			build: target.build,
-			project: target.project,
-			pendingUrl,
-			attempt,
-			recordLog
-		};
-		if (await maybeSkipMerged(ctx) || await maybeSkipDuplicate(ctx)) return;
-		await runAndReport(ctx, job);
+	return async (job, lease) => {
+		await (job.shard ? runShardJob(deps, {
+			...job,
+			shard: job.shard
+		}, lease) : runBuildJob(deps, job, lease));
+	};
+}
+/** The build's own job: post pending, apply skip rules, capture (or plan), report. */
+async function runBuildJob(deps, job, lease) {
+	const target = await loadJobTarget(deps, job);
+	if (!target) return;
+	await deps.buildState.request(job.buildId);
+	const { attempt, recordLog } = await beginAttempt(deps, target.project, target.build, job.reqId, lease);
+	const ctx = {
+		deps,
+		build: target.build,
+		project: target.project,
+		attempt,
+		recordLog,
+		progress: leaseProgress(lease)
 	};
+	if (await maybeSkipDuplicate(ctx)) return;
+	await runAndReport(ctx, job);
 }
 /** Open a new attempt row for this run and return its log recorder. */
-async function beginAttempt(deps, project, build, reqId) {
+async function beginAttempt(deps, project, build, reqId, lease) {
 	const attempts = new CaptureAttemptModel(deps.db, deps.tables);
 	const logs = new CaptureLogModel(deps.db, deps.tables);
 	const attempt = await attempts.startAttempt(project.id, build.id, reqId);
 	const recordLog = async (level, message, fields) => {
+		lease?.touch();
 		await logs.append(project.id, build.id, attempt.id, level, message, fields);
 	};
 	await emitAttemptLog(recordLog, deps.logger, "info", "capture queued", {
@@ -54,41 +65,10 @@ async function finishAttempt(ctx, status, error, counts) {
 }
 /** Full error text for an attempt row (message plus stack when available). */
 function errorText(reason) {
-	if (reason instanceof Error) return reason.stack ?? reason.message;
-	return String(reason);
-}
-async function postPending(deps, project, url, sha) {
-	await postStatusesForBuild({
-		db: deps.db,
-		tables: deps.tables,
-		project,
-		sha,
-		status: "pending",
-		url,
-		providers: deps.gitHosts,
-		secret: deps.secret,
-		logger: deps.logger
-	}).catch((error) => {
-		deps.logger.error({ err: error }, "failed to post pending status");
-	});
-}
-async function postTerminal(deps, project, url, sha, status) {
-	await postStatusesForBuild({
-		db: deps.db,
-		tables: deps.tables,
-		project,
-		sha,
-		status,
-		url,
-		providers: deps.gitHosts,
-		secret: deps.secret,
-		logger: deps.logger
-	}).catch((error) => {
-		deps.logger.error({ err: error }, "failed to post terminal status");
-	});
+	return redactSecrets(reason instanceof Error ? reason.stack ?? reason.message : String(reason));
 }
 async function approveWithoutCapture(ctx, reason) {
-	const { deps, build, project, pendingUrl } = ctx;
+	const { deps, build } = ctx;
 	deps.logger.info({
 		buildId: build.id,
 		sha: build.gitSha,
@@ -100,25 +80,7 @@ async function approveWithoutCapture(ctx, reason) {
 	});
 	await finishAttempt(ctx, "completed");
 	await new BuildModel(deps.db, deps.tables).setStatus(build.id, "approved").catch(() => {});
-	await postTerminal(deps, project, pendingUrl, build.gitSha, "success").catch(() => {});
-}
-async function maybeSkipMerged(ctx) {
-	const { deps, build, project } = ctx;
-	if (build.isDefault) return false;
-	if (await isAlreadyMerged({
-		providers: deps.gitHosts,
-		sha: build.gitSha,
-		branch: build.gitBranch,
-		secret: deps.secret,
-		db: deps.db,
-		tables: deps.tables,
-		projectId: project.id,
-		logger: deps.logger
-	}).catch(() => false)) {
-		await approveWithoutCapture(ctx, "skipping capture — already merged");
-		return true;
-	}
-	return false;
+	await deps.buildState.request(build.id);
 }
 async function maybeSkipDuplicate(ctx) {
 	const { deps, build, project } = ctx;
@@ -128,17 +90,14 @@ async function maybeSkipDuplicate(ctx) {
 	}
 	return false;
 }
-/** Map a terminal build status to its check-run state. */
-function terminalState(status) {
-	if (status === "approved") return "success";
-	if (status === "rejected" || status === "failed") return "failure";
-	return null;
-}
-/** Post the terminal status for a finished capture. */
-async function reportTerminalStatus(ctx, buildId) {
-	const { deps, build, project, pendingUrl } = ctx;
-	const terminal = terminalState((await new BuildModel(deps.db, deps.tables).get(buildId))?.status);
-	if (terminal) await postTerminal(deps, project, pendingUrl, build.gitSha, terminal);
+/** A sharded build's attempt stays open: the worker that finishes the last shard closes it. */
+async function finishUnlessSharded(ctx, summary) {
+	if (summary.shards) {
+		await emitAttemptLog(ctx.recordLog, ctx.deps.logger, "info", "capture sharded", { shards: summary.shards });
+		return;
+	}
+	await finishAttempt(ctx, "completed", void 0, summary);
+	await ctx.deps.buildState.request(ctx.build.id);
 }
 async function runAndReport(ctx, job) {
 	const { deps, build } = ctx;
@@ -148,7 +107,7 @@ async function runAndReport(ctx, job) {
 		attemptNo: ctx.attempt.attemptNo
 	});
 	try {
-		await finishAttempt(ctx, "completed", void 0, await executeCaptureJob({
+		await finishUnlessSharded(ctx, await executeCaptureJob({
 			buildId: job.buildId,
 			reqId: job.reqId,
 			traceparent: job.traceparent,
@@ -157,38 +116,32 @@ async function runAndReport(ctx, job) {
 				attemptNo: ctx.attempt.attemptNo,
 				projectId: ctx.project.id
 			},
-			recordLog: ctx.recordLog
+			recordLog: ctx.recordLog,
+			progress: ctx.progress
 		}, deps.jobOptions));
-		await reportTerminalStatus(ctx, job.buildId);
 	} catch (error) {
-		await finishAttempt(ctx, "failed", errorText(error));
-		await postStatusesForBuild({
-			db: deps.db,
-			tables: deps.tables,
-			project: ctx.project,
-			sha: build.gitSha,
-			status: "failure",
-			url: ctx.pendingUrl,
-			providers: deps.gitHosts,
-			secret: deps.secret,
-			logger: deps.logger
-		}).catch(() => {});
-		throw error;
+		await reportFailure(ctx, error);
 	}
 }
+/** Record a failed run, then rethrow so the job is redelivered, unless another try cannot help. */
+async function reportFailure(ctx, error) {
+	const { deps, build } = ctx;
+	await finishAttempt(ctx, "failed", errorText(error));
+	await deps.buildState.request(build.id);
+	if (error instanceof SignedUrlLifetimeError) {
+		deps.logger.error({
+			buildId: build.id,
+			err: error
+		}, "capture not retried");
+		return;
+	}
+	throw error;
+}
 /** Load the build + project for a job, running orphan jobs directly. */
 async function loadJobTarget(deps, job) {
 	const build = await new BuildModel(deps.db, deps.tables).get(job.buildId);
-	if (!build) {
-		await executeCaptureJob({
-			buildId: job.buildId,
-			reqId: job.reqId,
-			traceparent: job.traceparent
-		}, deps.jobOptions);
-		return null;
-	}
-	const project = await new ProjectModel(deps.db, deps.tables).get(build.projectId);
-	if (!project) {
+	const project = build ? await new ProjectModel(deps.db, deps.tables).get(build.projectId) : null;
+	if (!build || !project) {
 		await executeCaptureJob({
 			buildId: job.buildId,
 			reqId: job.reqId,
@@ -201,7 +154,45 @@ async function loadJobTarget(deps, job) {
 		project
 	};
 }
-//#endregion
+/**
+* Run one render shard. Only the run that finalized the build closes the plan's attempt and posts
+* the terminal status, whether its shard succeeded or failed; every other run leaves them alone.
+*/
+async function runShardJob(deps, job, lease) {
+	const final = (job.attempts ?? 0) >= (deps.maxRetries ?? 0);
+	await executeCaptureShard({
+		buildId: job.buildId,
+		shard: job.shard,
+		reqId: job.reqId,
+		final,
+		progress: leaseProgress(lease),
+		onFinalized: async (summary, error) => {
+			await closeShardedBuild(deps, job.buildId, summary, error);
+		}
+	}, deps.jobOptions);
+}
+/** End the plan's attempt with the finalizer's counts and report the build's terminal status. */
+async function closeShardedBuild(deps, buildId, summary, error) {
+	if (!await loadClosing(deps, buildId)) return;
+	const failure = error === void 0 ? summary.error : errorText(error);
+	const failed = failure !== void 0 || summary.buildStatus === "failed";
+	const attemptId = summary.attemptId ?? await planAttemptId(deps, buildId);
+	if (attemptId) await new CaptureAttemptModel(deps.db, deps.tables).markFinished(attemptId, failed ? "failed" : "completed", failure, summary).catch((closeError) => {
+		deps.logger.error({ err: closeError }, "failed to close attempt");
+	});
+	await deps.buildState.request(buildId);
+}
+async function planAttemptId(deps, buildId) {
+	return (await new CaptureShardModel(deps.db).plan(buildId))?.attemptId ?? null;
+}
+async function loadClosing(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;
+}
 export { createDispatchJob };
 
 //# sourceMappingURL=dispatch.mjs.map

package/dist/capture/dispatch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../src/capture/dispatch.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { GitHostProvider } from \"../adapters/git-host/index.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport { BuildModel, type BuildTables } from \"../models/build.ts\";\nimport {\n  CaptureAttemptModel,\n  emitAttemptLog,\n  type AttemptLogRecorder,\n  type CaptureAttemptTables,\n} from \"../models/capture-attempt.ts\";\nimport { CaptureLogModel, type CaptureLogTables } from \"../models/capture-log.ts\";\nimport { ProjectModel, type ProjectTables } from \"../models/project.ts\";\nimport type { StatusConfigTables } from \"../models/status-config.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { CaptureAttempt } from \"../schema/capture-attempt.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { SecretInput } from \"../utils/encrypt.ts\";\nimport { executeCaptureJob, type CaptureJobOptions } from \"./orchestrator.ts\";\nimport { hasApprovedBuildForSha, isAlreadyMerged } from \"./skip-checks.ts\";\nimport { postStatusesForBuild } from \"./status-fanout.ts\";\n\n/** Build the queue's job runner: post pending, apply skip rules, capture, report. */\nexport function createDispatchJob(deps: DispatchDeps): (job: CaptureDispatchJob) => Promise<void> {\n  return async (job: CaptureDispatchJob): Promise<void> => {\n    const target = await loadJobTarget(deps, job);\n    if (!target) {\n      return;\n    }\n    const pendingUrl = `/projects/${target.project.slug}/builds/${job.buildId}`;\n    await postPending(deps, target.project, pendingUrl, target.build.gitSha);\n    const { attempt, recordLog } = await beginAttempt(\n      deps,\n      target.project,\n      target.build,\n      job.reqId,\n    );\n    const ctx: JobContext = {\n      deps,\n      build: target.build,\n      project: target.project,\n      pendingUrl,\n      attempt,\n      recordLog,\n    };\n    if ((await maybeSkipMerged(ctx)) || (await maybeSkipDuplicate(ctx))) {\n      return;\n    }\n    await runAndReport(ctx, job);\n  };\n}\n\n/** Table handles required by dispatch. */\nexport type DispatchTables = BuildTables &\n  ProjectTables &\n  StatusConfigTables &\n  CaptureAttemptTables &\n  CaptureLogTables;\n\n/** Dependencies for building the capture queue's job runner. */\nexport interface DispatchDeps {\n  db: DatabaseAdapter;\n  tables: DispatchTables;\n  jobOptions: CaptureJobOptions;\n  gitHosts: GitHostProvider[];\n  secret: SecretInput;\n  logger: Logger;\n}\n\n/** A queued capture job. */\nexport interface CaptureDispatchJob {\n  buildId: string;\n  reqId?: string;\n  /** W3C `traceparent` continuing the enqueueing request's trace. */\n  traceparent?: string;\n}\n\ninterface JobContext {\n  deps: DispatchDeps;\n  build: Build;\n  project: Project;\n  pendingUrl: string;\n  attempt: CaptureAttempt;\n  recordLog: AttemptLogRecorder;\n}\n\n/** Open a new attempt row for this run and return its log recorder. */\nasync function beginAttempt(\n  deps: DispatchDeps,\n  project: Project,\n  build: Build,\n  reqId: string | undefined,\n): Promise<{ attempt: CaptureAttempt; recordLog: AttemptLogRecorder }> {\n  const attempts = new CaptureAttemptModel(deps.db, deps.tables);\n  const logs = new CaptureLogModel(deps.db, deps.tables);\n  const attempt = await attempts.startAttempt(project.id, build.id, reqId);\n  const recordLog: AttemptLogRecorder = async (level, message, fields) => {\n    await logs.append(project.id, build.id, attempt.id, level, message, fields);\n  };\n  await emitAttemptLog(recordLog, deps.logger, \"info\", \"capture queued\", {\n    buildId: build.id,\n    attemptNo: attempt.attemptNo,\n  });\n  return { attempt, recordLog };\n}\n\n/** Close the attempt row with its terminal status, counts, and error. */\nasync function finishAttempt(\n  ctx: JobContext,\n  status: \"completed\" | \"failed\" | \"cancelled\",\n  error?: string,\n  counts?: { storyCount: number; failedCount: number },\n): Promise<void> {\n  const { deps, attempt } = ctx;\n  await new CaptureAttemptModel(deps.db, deps.tables).markFinished(\n    attempt.id,\n    status,\n    error,\n    counts,\n  );\n  await emitAttemptLog(\n    ctx.recordLog,\n    deps.logger,\n    status === \"failed\" ? \"error\" : \"info\",\n    `capture ${status}`,\n    { attemptNo: attempt.attemptNo },\n  );\n}\n\n/** Full error text for an attempt row (message plus stack when available). */\nfunction errorText(reason: unknown): string {\n  if (reason instanceof Error) {\n    return reason.stack ?? reason.message;\n  }\n  return String(reason);\n}\n\nasync function postPending(\n  deps: DispatchDeps,\n  project: Project,\n  url: string,\n  sha: string,\n): Promise<void> {\n  await postStatusesForBuild({\n    db: deps.db,\n    tables: deps.tables,\n    project,\n    sha,\n    status: \"pending\",\n    url,\n    providers: deps.gitHosts,\n    secret: deps.secret,\n    logger: deps.logger,\n  }).catch((error: unknown) => {\n    deps.logger.error({ err: error }, \"failed to post pending status\");\n  });\n}\n\nasync function postTerminal(\n  deps: DispatchDeps,\n  project: Project,\n  url: string,\n  sha: string,\n  status: \"success\" | \"failure\",\n): Promise<void> {\n  await postStatusesForBuild({\n    db: deps.db,\n    tables: deps.tables,\n    project,\n    sha,\n    status,\n    url,\n    providers: deps.gitHosts,\n    secret: deps.secret,\n    logger: deps.logger,\n  }).catch((error: unknown) => {\n    deps.logger.error({ err: error }, \"failed to post terminal status\");\n  });\n}\n\nasync function approveWithoutCapture(ctx: JobContext, reason: string): Promise<void> {\n  const { deps, build, project, pendingUrl } = ctx;\n  deps.logger.info({ buildId: build.id, sha: build.gitSha, branch: build.gitBranch }, reason);\n  await emitAttemptLog(ctx.recordLog, deps.logger, \"info\", reason, {\n    sha: build.gitSha,\n    branch: build.gitBranch,\n  });\n  await finishAttempt(ctx, \"completed\");\n  await new BuildModel(deps.db, deps.tables).setStatus(build.id, \"approved\").catch(() => {}); // Intentionally empty — fire-and-forget\n  await postTerminal(deps, project, pendingUrl, build.gitSha, \"success\").catch(() => {}); // Intentionally empty — fire-and-forget\n}\n\nasync function maybeSkipMerged(ctx: JobContext): Promise<boolean> {\n  const { deps, build, project } = ctx;\n  if (build.isDefault) {\n    return false;\n  }\n  const merged = await isAlreadyMerged({\n    providers: deps.gitHosts,\n    sha: build.gitSha,\n    branch: build.gitBranch,\n    secret: deps.secret,\n    db: deps.db,\n    tables: deps.tables,\n    projectId: project.id,\n    logger: deps.logger,\n  }).catch(() => false);\n  if (merged) {\n    await approveWithoutCapture(ctx, \"skipping capture — already merged\");\n    return true;\n  }\n  return false;\n}\n\nasync function maybeSkipDuplicate(ctx: JobContext): Promise<boolean> {\n  const { deps, build, project } = ctx;\n  const dup = await hasApprovedBuildForSha(\n    deps.db,\n    deps.tables,\n    project.id,\n    build.gitSha,\n    build.id,\n  );\n  if (dup) {\n    await approveWithoutCapture(ctx, \"skipping capture — duplicate sha already approved\");\n    return true;\n  }\n  return false;\n}\n\n/** Map a terminal build status to its check-run state. */\nfunction terminalState(status: string | undefined): \"success\" | \"failure\" | null {\n  if (status === \"approved\") {\n    return \"success\";\n  }\n  if (status === \"rejected\" || status === \"failed\") {\n    return \"failure\";\n  }\n  return null;\n}\n\n/** Post the terminal status for a finished capture. */\nasync function reportTerminalStatus(ctx: JobContext, buildId: string): Promise<void> {\n  const { deps, build, project, pendingUrl } = ctx;\n  const updated = await new BuildModel(deps.db, deps.tables).get(buildId);\n  const terminal = terminalState(updated?.status);\n  if (terminal) {\n    await postTerminal(deps, project, pendingUrl, build.gitSha, terminal);\n  }\n}\n\nasync function runAndReport(ctx: JobContext, job: CaptureDispatchJob): Promise<void> {\n  const { deps, build } = ctx;\n  await new CaptureAttemptModel(deps.db, deps.tables).markRunning(ctx.attempt.id);\n  await emitAttemptLog(ctx.recordLog, deps.logger, \"info\", \"capture started\", {\n    buildId: build.id,\n    attemptNo: ctx.attempt.attemptNo,\n  });\n  try {\n    const summary = await executeCaptureJob(\n      {\n        buildId: job.buildId,\n        reqId: job.reqId,\n        traceparent: job.traceparent,\n        attempt: {\n          id: ctx.attempt.id,\n          attemptNo: ctx.attempt.attemptNo,\n          projectId: ctx.project.id,\n        },\n        recordLog: ctx.recordLog,\n      },\n      deps.jobOptions,\n    );\n    await finishAttempt(ctx, \"completed\", undefined, summary);\n    await reportTerminalStatus(ctx, job.buildId);\n  } catch (error: unknown) {\n    await finishAttempt(ctx, \"failed\", errorText(error));\n    await postStatusesForBuild({\n      db: deps.db,\n      tables: deps.tables,\n      project: ctx.project,\n      sha: build.gitSha,\n      status: \"failure\",\n      url: ctx.pendingUrl,\n      providers: deps.gitHosts,\n      secret: deps.secret,\n      logger: deps.logger,\n    }).catch(() => {\n      // Ignore: status post failure already logged\n    });\n    throw error;\n  }\n}\n\n/** Load the build + project for a job, running orphan jobs directly. */\nasync function loadJobTarget(\n  deps: DispatchDeps,\n  job: CaptureDispatchJob,\n): Promise<{ build: Build; project: Project } | null> {\n  const builds = new BuildModel(deps.db, deps.tables);\n  const build = await builds.get(job.buildId);\n  if (!build) {\n    await executeCaptureJob(\n      { buildId: job.buildId, reqId: job.reqId, traceparent: job.traceparent },\n      deps.jobOptions,\n    );\n    return null;\n  }\n  const project = await new ProjectModel(deps.db, deps.tables).get(build.projectId);\n  if (!project) {\n    await executeCaptureJob(\n      { buildId: job.buildId, reqId: job.reqId, traceparent: job.traceparent },\n      deps.jobOptions,\n    );\n    return null;\n  }\n  return { build, project };\n}\n"],"mappings":";;;;;;;;;;;;AAsBA,SAAgB,kBAAkB,MAAgE;CAChG,OAAO,OAAO,QAA2C;EACvD,MAAM,SAAS,MAAM,cAAc,MAAM,GAAG;EAC5C,IAAI,CAAC,QACH;EAEF,MAAM,aAAa,aAAa,OAAO,QAAQ,KAAK,UAAU,IAAI;EAClE,MAAM,YAAY,MAAM,OAAO,SAAS,YAAY,OAAO,MAAM,MAAM;EACvE,MAAM,EAAE,SAAS,cAAc,MAAM,aACnC,MACA,OAAO,SACP,OAAO,OACP,IAAI,KACN;EACA,MAAM,MAAkB;GACtB;GACA,OAAO,OAAO;GACd,SAAS,OAAO;GAChB;GACA;GACA;EACF;EACA,IAAK,MAAM,gBAAgB,GAAG,KAAO,MAAM,mBAAmB,GAAG,GAC/D;EAEF,MAAM,aAAa,KAAK,GAAG;CAC7B;AACF;;AAqCA,eAAe,aACb,MACA,SACA,OACA,OACqE;CACrE,MAAM,WAAW,IAAI,oBAAoB,KAAK,IAAI,KAAK,MAAM;CAC7D,MAAM,OAAO,IAAI,gBAAgB,KAAK,IAAI,KAAK,MAAM;CACrD,MAAM,UAAU,MAAM,SAAS,aAAa,QAAQ,IAAI,MAAM,IAAI,KAAK;CACvE,MAAM,YAAgC,OAAO,OAAO,SAAS,WAAW;EACtE,MAAM,KAAK,OAAO,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,OAAO,SAAS,MAAM;CAC5E;CACA,MAAM,eAAe,WAAW,KAAK,QAAQ,QAAQ,kBAAkB;EACrE,SAAS,MAAM;EACf,WAAW,QAAQ;CACrB,CAAC;CACD,OAAO;EAAE;EAAS;CAAU;AAC9B;;AAGA,eAAe,cACb,KACA,QACA,OACA,QACe;CACf,MAAM,EAAE,MAAM,YAAY;CAC1B,MAAM,IAAI,oBAAoB,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,aAClD,QAAQ,IACR,QACA,OACA,MACF;CACA,MAAM,eACJ,IAAI,WACJ,KAAK,QACL,WAAW,WAAW,UAAU,QAChC,WAAW,UACX,EAAE,WAAW,QAAQ,UAAU,CACjC;AACF;;AAGA,SAAS,UAAU,QAAyB;CAC1C,IAAI,kBAAkB,OACpB,OAAO,OAAO,SAAS,OAAO;CAEhC,OAAO,OAAO,MAAM;AACtB;AAEA,eAAe,YACb,MACA,SACA,KACA,KACe;CACf,MAAM,qBAAqB;EACzB,IAAI,KAAK;EACT,QAAQ,KAAK;EACb;EACA;EACA,QAAQ;EACR;EACA,WAAW,KAAK;EAChB,QAAQ,KAAK;EACb,QAAQ,KAAK;CACf,CAAC,CAAC,CAAC,OAAO,UAAmB;EAC3B,KAAK,OAAO,MAAM,EAAE,KAAK,MAAM,GAAG,+BAA+B;CACnE,CAAC;AACH;AAEA,eAAe,aACb,MACA,SACA,KACA,KACA,QACe;CACf,MAAM,qBAAqB;EACzB,IAAI,KAAK;EACT,QAAQ,KAAK;EACb;EACA;EACA;EACA;EACA,WAAW,KAAK;EAChB,QAAQ,KAAK;EACb,QAAQ,KAAK;CACf,CAAC,CAAC,CAAC,OAAO,UAAmB;EAC3B,KAAK,OAAO,MAAM,EAAE,KAAK,MAAM,GAAG,gCAAgC;CACpE,CAAC;AACH;AAEA,eAAe,sBAAsB,KAAiB,QAA+B;CACnF,MAAM,EAAE,MAAM,OAAO,SAAS,eAAe;CAC7C,KAAK,OAAO,KAAK;EAAE,SAAS,MAAM;EAAI,KAAK,MAAM;EAAQ,QAAQ,MAAM;CAAU,GAAG,MAAM;CAC1F,MAAM,eAAe,IAAI,WAAW,KAAK,QAAQ,QAAQ,QAAQ;EAC/D,KAAK,MAAM;EACX,QAAQ,MAAM;CAChB,CAAC;CACD,MAAM,cAAc,KAAK,WAAW;CACpC,MAAM,IAAI,WAAW,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,UAAU,MAAM,IAAI,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;CACzF,MAAM,aAAa,MAAM,SAAS,YAAY,MAAM,QAAQ,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AACvF;AAEA,eAAe,gBAAgB,KAAmC;CAChE,MAAM,EAAE,MAAM,OAAO,YAAY;CACjC,IAAI,MAAM,WACR,OAAO;CAYT,IAAI,MAViB,gBAAgB;EACnC,WAAW,KAAK;EAChB,KAAK,MAAM;EACX,QAAQ,MAAM;EACd,QAAQ,KAAK;EACb,IAAI,KAAK;EACT,QAAQ,KAAK;EACb,WAAW,QAAQ;EACnB,QAAQ,KAAK;CACf,CAAC,CAAC,CAAC,YAAY,KAAK,GACR;EACV,MAAM,sBAAsB,KAAK,mCAAmC;EACpE,OAAO;CACT;CACA,OAAO;AACT;AAEA,eAAe,mBAAmB,KAAmC;CACnE,MAAM,EAAE,MAAM,OAAO,YAAY;CAQjC,IAAI,MAPc,uBAChB,KAAK,IACL,KAAK,QACL,QAAQ,IACR,MAAM,QACN,MAAM,EACR,GACS;EACP,MAAM,sBAAsB,KAAK,mDAAmD;EACpF,OAAO;CACT;CACA,OAAO;AACT;;AAGA,SAAS,cAAc,QAA0D;CAC/E,IAAI,WAAW,YACb,OAAO;CAET,IAAI,WAAW,cAAc,WAAW,UACtC,OAAO;CAET,OAAO;AACT;;AAGA,eAAe,qBAAqB,KAAiB,SAAgC;CACnF,MAAM,EAAE,MAAM,OAAO,SAAS,eAAe;CAE7C,MAAM,WAAW,eAAc,MADT,IAAI,WAAW,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,IAAI,OAAO,EAAA,EAC9B,MAAM;CAC9C,IAAI,UACF,MAAM,aAAa,MAAM,SAAS,YAAY,MAAM,QAAQ,QAAQ;AAExE;AAEA,eAAe,aAAa,KAAiB,KAAwC;CACnF,MAAM,EAAE,MAAM,UAAU;CACxB,MAAM,IAAI,oBAAoB,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,YAAY,IAAI,QAAQ,EAAE;CAC9E,MAAM,eAAe,IAAI,WAAW,KAAK,QAAQ,QAAQ,mBAAmB;EAC1E,SAAS,MAAM;EACf,WAAW,IAAI,QAAQ;CACzB,CAAC;CACD,IAAI;EAeF,MAAM,cAAc,KAAK,aAAa,KAAA,GAAW,MAd3B,kBACpB;GACE,SAAS,IAAI;GACb,OAAO,IAAI;GACX,aAAa,IAAI;GACjB,SAAS;IACP,IAAI,IAAI,QAAQ;IAChB,WAAW,IAAI,QAAQ;IACvB,WAAW,IAAI,QAAQ;GACzB;GACA,WAAW,IAAI;EACjB,GACA,KAAK,UACP,CACwD;EACxD,MAAM,qBAAqB,KAAK,IAAI,OAAO;CAC7C,SAAS,OAAgB;EACvB,MAAM,cAAc,KAAK,UAAU,UAAU,KAAK,CAAC;EACnD,MAAM,qBAAqB;GACzB,IAAI,KAAK;GACT,QAAQ,KAAK;GACb,SAAS,IAAI;GACb,KAAK,MAAM;GACX,QAAQ;GACR,KAAK,IAAI;GACT,WAAW,KAAK;GAChB,QAAQ,KAAK;GACb,QAAQ,KAAK;EACf,CAAC,CAAC,CAAC,YAAY,CAEf,CAAC;EACD,MAAM;CACR;AACF;;AAGA,eAAe,cACb,MACA,KACoD;CAEpD,MAAM,QAAQ,MAAM,IADD,WAAW,KAAK,IAAI,KAAK,MACnB,CAAC,CAAC,IAAI,IAAI,OAAO;CAC1C,IAAI,CAAC,OAAO;EACV,MAAM,kBACJ;GAAE,SAAS,IAAI;GAAS,OAAO,IAAI;GAAO,aAAa,IAAI;EAAY,GACvE,KAAK,UACP;EACA,OAAO;CACT;CACA,MAAM,UAAU,MAAM,IAAI,aAAa,KAAK,IAAI,KAAK,MAAM,CAAC,CAAC,IAAI,MAAM,SAAS;CAChF,IAAI,CAAC,SAAS;EACZ,MAAM,kBACJ;GAAE,SAAS,IAAI;GAAS,OAAO,IAAI;GAAO,aAAa,IAAI;EAAY,GACvE,KAAK,UACP;EACA,OAAO;CACT;CACA,OAAO;EAAE;EAAO;CAAQ;AAC1B"}
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../src/capture/dispatch.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport { BuildModel, type BuildTables } from \"../models/build.ts\";\nimport {\n  CaptureAttemptModel,\n  emitAttemptLog,\n  type AttemptLogRecorder,\n  type CaptureAttemptTables,\n} from \"../models/capture-attempt.ts\";\nimport { CaptureLogModel, type CaptureLogTables } from \"../models/capture-log.ts\";\nimport { CaptureShardModel } from \"../models/capture-shard.ts\";\nimport { ProjectModel, type ProjectTables } from \"../models/project.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { CaptureAttempt } from \"../schema/capture-attempt.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport { redactSecrets } from \"../utils/redact.ts\";\nimport type { BuildStatePublisher } from \"./build-state/types.ts\";\nimport type { JobLease } from \"./job-lease.ts\";\nimport { executeCaptureJob, type CaptureJobOptions, type CaptureSummary } from \"./orchestrator.ts\";\nimport { leaseProgress, type CaptureProgress } from \"./progress.ts\";\nimport { executeCaptureShard } from \"./shards/execute.ts\";\nimport type { FinalSummary } from \"./shards/reduce.ts\";\nimport { hasApprovedBuildForSha } from \"./skip-checks.ts\";\nimport { SignedUrlLifetimeError } from \"./token-chunks.ts\";\n\n/** Build the queue's job runner: post pending, apply skip rules, capture, report. */\nexport function createDispatchJob(\n  deps: DispatchDeps,\n): (job: CaptureDispatchJob, lease?: JobLease) => Promise<void> {\n  return async (job: CaptureDispatchJob, lease?: JobLease): Promise<void> => {\n    await (job.shard\n      ? runShardJob(deps, { ...job, shard: job.shard }, lease)\n      : runBuildJob(deps, job, lease));\n  };\n}\n\n/** The build's own job: post pending, apply skip rules, capture (or plan), report. */\nasync function runBuildJob(\n  deps: DispatchDeps,\n  job: CaptureDispatchJob,\n  lease?: JobLease,\n): Promise<void> {\n  const target = await loadJobTarget(deps, job);\n  if (!target) {\n    return;\n  }\n  await deps.buildState.request(job.buildId);\n  const { attempt, recordLog } = await beginAttempt(\n    deps,\n    target.project,\n    target.build,\n    job.reqId,\n    lease,\n  );\n  const ctx: JobContext = {\n    deps,\n    build: target.build,\n    project: target.project,\n    attempt,\n    recordLog,\n    progress: leaseProgress(lease),\n  };\n  if (await maybeSkipDuplicate(ctx)) {\n    return;\n  }\n  await runAndReport(ctx, job);\n}\n\n/** Table handles required by dispatch. */\nexport type DispatchTables = BuildTables & ProjectTables & CaptureAttemptTables & CaptureLogTables;\n\n/** Dependencies for building the capture queue's job runner. */\nexport interface DispatchDeps {\n  db: DatabaseAdapter;\n  tables: DispatchTables;\n  jobOptions: CaptureJobOptions;\n  /** Shows a build's current state on its git channels; called at every transition. */\n  buildState: BuildStatePublisher;\n  logger: Logger;\n  /** Redeliveries the queue allows a failing job; a shard's last try is its final word. */\n  maxRetries?: number | undefined;\n}\n\n/** A queued capture job. */\nexport interface CaptureDispatchJob {\n  buildId: string;\n  /** A `capture_shards` row to render; absent for the build's own (plan or whole-build) job. */\n  shard?: string | undefined;\n  /** Times the queue has already delivered this job and seen it fail. */\n  attempts?: number | undefined;\n  reqId?: string;\n  /** W3C `traceparent` continuing the enqueueing request's trace. */\n  traceparent?: string;\n}\n\ninterface JobContext {\n  deps: DispatchDeps;\n  build: Build;\n  project: Project;\n  attempt: CaptureAttempt;\n  recordLog: AttemptLogRecorder;\n  progress: CaptureProgress | undefined;\n}\n\n/** Open a new attempt row for this run and return its log recorder. */\nasync function beginAttempt(\n  deps: DispatchDeps,\n  project: Project,\n  build: Build,\n  reqId: string | undefined,\n  lease?: JobLease,\n): Promise<{ attempt: CaptureAttempt; recordLog: AttemptLogRecorder }> {\n  const attempts = new CaptureAttemptModel(deps.db, deps.tables);\n  const logs = new CaptureLogModel(deps.db, deps.tables);\n  const attempt = await attempts.startAttempt(project.id, build.id, reqId);\n  // Every attempt-log line (stages, render progress, runner output) counts as progress.\n  const recordLog: AttemptLogRecorder = async (level, message, fields) => {\n    lease?.touch();\n    await logs.append(project.id, build.id, attempt.id, level, message, fields);\n  };\n  await emitAttemptLog(recordLog, deps.logger, \"info\", \"capture queued\", {\n    buildId: build.id,\n    attemptNo: attempt.attemptNo,\n  });\n  return { attempt, recordLog };\n}\n\n/** Close the attempt row with its terminal status, counts, and error. */\nasync function finishAttempt(\n  ctx: JobContext,\n  status: \"completed\" | \"failed\" | \"cancelled\",\n  error?: string,\n  counts?: { storyCount: number; failedCount: number },\n): Promise<void> {\n  const { deps, attempt } = ctx;\n  await new CaptureAttemptModel(deps.db, deps.tables).markFinished(\n    attempt.id,\n    status,\n    error,\n    counts,\n  );\n  await emitAttemptLog(\n    ctx.recordLog,\n    deps.logger,\n    status === \"failed\" ? \"error\" : \"info\",\n    `capture ${status}`,\n    { attemptNo: attempt.attemptNo },\n  );\n}\n\n/** Full error text for an attempt row (message plus stack when available). */\nfunction errorText(reason: unknown): string {\n  // A runner's error can quote the signed Storybook URL it failed to open.\n  return redactSecrets(reason instanceof Error ? (reason.stack ?? reason.message) : String(reason));\n}\n\nasync function approveWithoutCapture(ctx: JobContext, reason: string): Promise<void> {\n  const { deps, build } = ctx;\n  deps.logger.info({ buildId: build.id, sha: build.gitSha, branch: build.gitBranch }, reason);\n  await emitAttemptLog(ctx.recordLog, deps.logger, \"info\", reason, {\n    sha: build.gitSha,\n    branch: build.gitBranch,\n  });\n  await finishAttempt(ctx, \"completed\");\n  await new BuildModel(deps.db, deps.tables).setStatus(build.id, \"approved\").catch(() => {}); // Intentionally empty — fire-and-forget\n  await deps.buildState.request(build.id);\n}\n\nasync function maybeSkipDuplicate(ctx: JobContext): Promise<boolean> {\n  const { deps, build, project } = ctx;\n  const dup = await hasApprovedBuildForSha(\n    deps.db,\n    deps.tables,\n    project.id,\n    build.gitSha,\n    build.id,\n  );\n  if (dup) {\n    await approveWithoutCapture(ctx, \"skipping capture — duplicate sha already approved\");\n    return true;\n  }\n  return false;\n}\n\n/** A sharded build's attempt stays open: the worker that finishes the last shard closes it. */\nasync function finishUnlessSharded(ctx: JobContext, summary: CaptureSummary): Promise<void> {\n  if (summary.shards) {\n    await emitAttemptLog(ctx.recordLog, ctx.deps.logger, \"info\", \"capture sharded\", {\n      shards: summary.shards,\n    });\n    return;\n  }\n  await finishAttempt(ctx, \"completed\", undefined, summary);\n  await ctx.deps.buildState.request(ctx.build.id);\n}\n\nasync function runAndReport(ctx: JobContext, job: CaptureDispatchJob): Promise<void> {\n  const { deps, build } = ctx;\n  await new CaptureAttemptModel(deps.db, deps.tables).markRunning(ctx.attempt.id);\n  await emitAttemptLog(ctx.recordLog, deps.logger, \"info\", \"capture started\", {\n    buildId: build.id,\n    attemptNo: ctx.attempt.attemptNo,\n  });\n  try {\n    const summary = await executeCaptureJob(\n      {\n        buildId: job.buildId,\n        reqId: job.reqId,\n        traceparent: job.traceparent,\n        attempt: {\n          id: ctx.attempt.id,\n          attemptNo: ctx.attempt.attemptNo,\n          projectId: ctx.project.id,\n        },\n        recordLog: ctx.recordLog,\n        progress: ctx.progress,\n      },\n      deps.jobOptions,\n    );\n    await finishUnlessSharded(ctx, summary);\n  } catch (error: unknown) {\n    await reportFailure(ctx, error);\n  }\n}\n\n/** Record a failed run, then rethrow so the job is redelivered, unless another try cannot help. */\nasync function reportFailure(ctx: JobContext, error: unknown): Promise<void> {\n  const { deps, build } = ctx;\n  await finishAttempt(ctx, \"failed\", errorText(error));\n  await deps.buildState.request(build.id);\n  if (error instanceof SignedUrlLifetimeError) {\n    // A configuration problem: another delivery would fail the same way. The build is failed.\n    deps.logger.error({ buildId: build.id, err: error }, \"capture not retried\");\n    return;\n  }\n  throw error;\n}\n\n/** Load the build + project for a job, running orphan jobs directly. */\nasync function loadJobTarget(\n  deps: DispatchDeps,\n  job: CaptureDispatchJob,\n): Promise<{ build: Build; project: Project } | null> {\n  const build = await new BuildModel(deps.db, deps.tables).get(job.buildId);\n  const project = build ? await new ProjectModel(deps.db, deps.tables).get(build.projectId) : null;\n  if (!build || !project) {\n    await executeCaptureJob(\n      { buildId: job.buildId, reqId: job.reqId, traceparent: job.traceparent },\n      deps.jobOptions,\n    );\n    return null;\n  }\n  return { build, project };\n}\n\n/**\n * Run one render shard. Only the run that finalized the build closes the plan's attempt and posts\n * the terminal status, whether its shard succeeded or failed; every other run leaves them alone.\n */\nasync function runShardJob(\n  deps: DispatchDeps,\n  job: CaptureDispatchJob & { shard: string },\n  lease?: JobLease,\n): Promise<void> {\n  const final = (job.attempts ?? 0) >= (deps.maxRetries ?? 0);\n  await executeCaptureShard(\n    {\n      buildId: job.buildId,\n      shard: job.shard,\n      reqId: job.reqId,\n      final,\n      progress: leaseProgress(lease),\n      onFinalized: async (summary, error) => {\n        await closeShardedBuild(deps, job.buildId, summary, error);\n      },\n    },\n    deps.jobOptions,\n  );\n}\n\n/** End the plan's attempt with the finalizer's counts and report the build's terminal status. */\nasync function closeShardedBuild(\n  deps: DispatchDeps,\n  buildId: string,\n  summary: FinalSummary,\n  error?: unknown,\n): Promise<void> {\n  const loaded = await loadClosing(deps, buildId);\n  if (!loaded) {\n    return;\n  }\n  const failure = error === undefined ? summary.error : errorText(error);\n  const failed = failure !== undefined || summary.buildStatus === \"failed\";\n  const attemptId = summary.attemptId ?? (await planAttemptId(deps, buildId));\n  if (attemptId) {\n    await new CaptureAttemptModel(deps.db, deps.tables)\n      .markFinished(attemptId, failed ? \"failed\" : \"completed\", failure, summary)\n      .catch((closeError: unknown) => {\n        deps.logger.error({ err: closeError }, \"failed to close attempt\");\n      });\n  }\n  await deps.buildState.request(buildId);\n}\n\nasync function planAttemptId(deps: DispatchDeps, buildId: string): Promise<string | null> {\n  const plan = await new CaptureShardModel(deps.db).plan(buildId);\n  return plan?.attemptId ?? null;\n}\n\nasync function loadClosing(\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"],"mappings":"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"}

package/dist/capture/enrich.mjs

@@ -0,0 +1,59 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { filterModes } from "./modes.mjs";
+import { renderBudgetMs } from "./render.mjs";
+import { resolveStoryViewports } from "./storybook.mjs";
+// src/capture/enrich.ts
+/**
+* Merge runtime-resolved parameters (project/component/story levels stacked by
+* Storybook) over the index's, then apply the project's mode allowlist. A
+* runner without `extractParameters`, or one that fails, leaves index
+* parameters untouched — the build still captures plain viewports.
+*/
+async function enrichStories(input) {
+	const extracted = await extractSafely(input);
+	return input.stories.map((story) => {
+		const parameters = {
+			...story.parameters,
+			...extracted[story.id]
+		};
+		const modes = filterModes(parameters.modes, input.allowlist);
+		if (modes) parameters.modes = modes;
+		return Object.keys(parameters).length > 0 ? {
+			...story,
+			parameters
+		} : story;
+	});
+}
+/**
+* Fail the build before any rendering when a story expands beyond the cap
+* (global viewports + default viewport + modes).
+*/
+function assertModeCaps(stories, viewports) {
+	for (const story of stories) {
+		const count = resolveStoryViewports(story, viewports).length;
+		if (count > 8) throw new Error(`Story "${story.id}" expands to ${count} captures (max 8); reduce its modes or the project viewports`);
+	}
+}
+async function extractSafely(input) {
+	const { runner } = input;
+	if (!runner.extractParameters) return {};
+	try {
+		const storybookUrl = await input.storybookUrl?.(input.target, { budgetMs: renderBudgetMs(input.stories.length) });
+		return await runner.extractParameters({
+			buildId: input.buildId,
+			storybookDir: input.storybookDir,
+			stories: input.stories,
+			target: input.target,
+			...storybookUrl === void 0 ? {} : { storybookUrl },
+			...input.logger ? { logger: input.logger } : {}
+		});
+	} catch (error) {
+		input.logger?.warn({ err: error }, "parameter extraction failed; modes from index only");
+		return {};
+	}
+}
+export { assertModeCaps, enrichStories };
+
+//# sourceMappingURL=enrich.mjs.map

package/dist/capture/enrich.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.mjs","names":[],"sources":["../../src/capture/enrich.ts"],"sourcesContent":["/** Orchestrator pre-pass: learn each story's modes before building the capture matrix. */\nimport type { Logger } from \"pino\";\nimport type { CaptureTarget, CaptureRunner } from \"../adapters/capture-runner.ts\";\nimport type { StoryEntry, Viewport } from \"./adapter.ts\";\nimport { filterModes, MAX_MODES_PER_STORY } from \"./modes.ts\";\nimport { renderBudgetMs } from \"./render.ts\";\nimport type { StorybookUrlSource } from \"./storybook-urls.ts\";\nimport { resolveStoryViewports } from \"./storybook.ts\";\n\n/** Inputs for {@link enrichStories}. */\nexport interface EnrichInput {\n  runner: CaptureRunner;\n  buildId: string;\n  storybookDir: string;\n  stories: StoryEntry[];\n  target: CaptureTarget;\n  allowlist: readonly string[] | null;\n  logger: Logger | undefined;\n  /** Mints the signed URL for a `reach: \"url\"` target. */\n  storybookUrl?: StorybookUrlSource | undefined;\n}\n\n/**\n * Merge runtime-resolved parameters (project/component/story levels stacked by\n * Storybook) over the index's, then apply the project's mode allowlist. A\n * runner without `extractParameters`, or one that fails, leaves index\n * parameters untouched — the build still captures plain viewports.\n */\nexport async function enrichStories(input: EnrichInput): Promise<StoryEntry[]> {\n  const extracted = await extractSafely(input);\n  return input.stories.map((story) => {\n    const parameters = { ...story.parameters, ...extracted[story.id] };\n    const modes = filterModes(parameters.modes, input.allowlist);\n    if (modes) parameters.modes = modes;\n    return Object.keys(parameters).length > 0 ? { ...story, parameters } : story;\n  });\n}\n\n/**\n * Fail the build before any rendering when a story expands beyond the cap\n * (global viewports + default viewport + modes).\n */\nexport function assertModeCaps(stories: StoryEntry[], viewports: Viewport[]): void {\n  for (const story of stories) {\n    const count = resolveStoryViewports(story, viewports).length;\n    if (count > MAX_MODES_PER_STORY) {\n      throw new Error(\n        `Story \"${story.id}\" expands to ${count} captures (max ${MAX_MODES_PER_STORY}); reduce its modes or the project viewports`,\n      );\n    }\n  }\n}\n\nasync function extractSafely(\n  input: EnrichInput,\n): ReturnType<NonNullable<CaptureRunner[\"extractParameters\"]>> {\n  const { runner } = input;\n  if (!runner.extractParameters) return {};\n  try {\n    const storybookUrl = await input.storybookUrl?.(input.target, {\n      budgetMs: renderBudgetMs(input.stories.length),\n    });\n    return await runner.extractParameters({\n      buildId: input.buildId,\n      storybookDir: input.storybookDir,\n      stories: input.stories,\n      target: input.target,\n      ...(storybookUrl === undefined ? {} : { storybookUrl }),\n      ...(input.logger ? { logger: input.logger } : {}),\n    });\n  } catch (error) {\n    input.logger?.warn({ err: error }, \"parameter extraction failed; modes from index only\");\n    return {};\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AA4BA,eAAsB,cAAc,OAA2C;CAC7E,MAAM,YAAY,MAAM,cAAc,KAAK;CAC3C,OAAO,MAAM,QAAQ,KAAK,UAAU;EAClC,MAAM,aAAa;GAAE,GAAG,MAAM;GAAY,GAAG,UAAU,MAAM;EAAI;EACjE,MAAM,QAAQ,YAAY,WAAW,OAAO,MAAM,SAAS;EAC3D,IAAI,OAAO,WAAW,QAAQ;EAC9B,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,SAAS,IAAI;GAAE,GAAG;GAAO;EAAW,IAAI;CACzE,CAAC;AACH;;;;;AAMA,SAAgB,eAAe,SAAuB,WAA6B;CACjF,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,QAAQ,sBAAsB,OAAO,SAAS,CAAC,CAAC;EACtD,IAAI,QAAA,GACF,MAAM,IAAI,MACR,UAAU,MAAM,GAAG,eAAe,MAAM,6DAC1C;CAEJ;AACF;AAEA,eAAe,cACb,OAC6D;CAC7D,MAAM,EAAE,WAAW;CACnB,IAAI,CAAC,OAAO,mBAAmB,OAAO,CAAC;CACvC,IAAI;EACF,MAAM,eAAe,MAAM,MAAM,eAAe,MAAM,QAAQ,EAC5D,UAAU,eAAe,MAAM,QAAQ,MAAM,EAC/C,CAAC;EACD,OAAO,MAAM,OAAO,kBAAkB;GACpC,SAAS,MAAM;GACf,cAAc,MAAM;GACpB,SAAS,MAAM;GACf,QAAQ,MAAM;GACd,GAAI,iBAAiB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa;GACrD,GAAI,MAAM,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EACjD,CAAC;CACH,SAAS,OAAO;EACd,MAAM,QAAQ,KAAK,EAAE,KAAK,MAAM,GAAG,oDAAoD;EACvF,OAAO,CAAC;CACV;AACF"}

package/dist/capture/failure-sets.mjs

@@ -0,0 +1,21 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { isFlakyStory } from "./adapter.mjs";
+// src/capture/failure-sets.ts
+/** Classify render failures: `a11y:` errors, then flaky stories, then everything else is blocking. */
+function classifyFailures(stories, failures) {
+	const flakyIds = new Set(stories.filter((story) => isFlakyStory(story)).map((story) => story.id));
+	const sets = {
+		blocking: /* @__PURE__ */ new Set(),
+		flaky: /* @__PURE__ */ new Set(),
+		a11y: /* @__PURE__ */ new Set()
+	};
+	for (const failure of failures) if (failure.error.startsWith("a11y:")) sets.a11y.add(failure.storyId);
+	else if (flakyIds.has(failure.storyId)) sets.flaky.add(failure.storyId);
+	else sets.blocking.add(failure.storyId);
+	return sets;
+}
+export { classifyFailures };
+
+//# sourceMappingURL=failure-sets.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"failure-sets.mjs","names":[],"sources":["../../src/capture/failure-sets.ts"],"sourcesContent":["/** Sorting a render's failures into the three kinds that decide a build's status. */\nimport type { RenderFailure } from \"../adapters/capture-runner.ts\";\nimport { isFlakyStory, type StoryEntry } from \"./adapter.ts\";\n\n/** Story ids by how their failure counts. */\nexport interface FailureSets {\n  /** Fail the build. */\n  blocking: Set<string>;\n  /** Flaky stories: logged, never blocking. */\n  flaky: Set<string>;\n  /** Accessibility violations: logged, never blocking. */\n  a11y: Set<string>;\n}\n\n/** Classify render failures: `a11y:` errors, then flaky stories, then everything else is blocking. */\nexport function classifyFailures(\n  stories: readonly StoryEntry[],\n  failures: readonly RenderFailure[],\n): FailureSets {\n  const flakyIds = new Set(stories.filter((story) => isFlakyStory(story)).map((story) => story.id));\n  const sets: FailureSets = { blocking: new Set(), flaky: new Set(), a11y: new Set() };\n  for (const failure of failures) {\n    if (failure.error.startsWith(\"a11y:\")) {\n      sets.a11y.add(failure.storyId);\n    } else if (flakyIds.has(failure.storyId)) {\n      sets.flaky.add(failure.storyId);\n    } else {\n      sets.blocking.add(failure.storyId);\n    }\n  }\n  return sets;\n}\n"],"mappings":";;;;;;AAeA,SAAgB,iBACd,SACA,UACa;CACb,MAAM,WAAW,IAAI,IAAI,QAAQ,QAAQ,UAAU,aAAa,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,MAAM,EAAE,CAAC;CAChG,MAAM,OAAoB;EAAE,0BAAU,IAAI,IAAI;EAAG,uBAAO,IAAI,IAAI;EAAG,sBAAM,IAAI,IAAI;CAAE;CACnF,KAAK,MAAM,WAAW,UACpB,IAAI,QAAQ,MAAM,WAAW,OAAO,GAClC,KAAK,KAAK,IAAI,QAAQ,OAAO;MACxB,IAAI,SAAS,IAAI,QAAQ,OAAO,GACrC,KAAK,MAAM,IAAI,QAAQ,OAAO;MAE9B,KAAK,SAAS,IAAI,QAAQ,OAAO;CAGrC,OAAO;AACT"}

package/dist/capture/fingerprint.d.mts

@@ -0,0 +1,40 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Viewport } from "./adapter.mjs";
+import { CaptureEnvironment } from "../adapter/capture-runner.mjs";
+import { SIZING_DEFAULTS } from "./sizing.mjs";
+/** The components behind a snapshot's `infraHash`, kept so a mismatch can say what changed. */
+interface Fingerprint {
+  engine: string;
+  browserVersion: string | null;
+  platform: string | null;
+  deviceScaleFactor: number | null;
+  fontsHash: string | null;
+  viewport: {
+    width: number;
+    height: number;
+  };
+  sizing: typeof SIZING_DEFAULTS;
+}
+/** Build the fingerprint of one capture. Missing environment fields stay `null` (runner did not report them). */
+declare function buildFingerprint(engine: string, viewport: Viewport, environment: CaptureEnvironment | undefined): Fingerprint;
+/** Stable hash of a fingerprint: the value stored as `infraHash`. */
+declare function fingerprintHash(fingerprint: Fingerprint): string;
+/**
+ * Names of the environment components that differ; `["unknown"]` when the earlier fingerprint was
+ * not recorded. A component one side did not report (`null`: a runner that does not report it, a
+ * capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed. Viewport is
+ * never a change here: its size comes from story parameters (the PR's own code), so a new size must
+ * be reviewed, and it diffs on its own as a dimension change.
+ */
+declare function changedFields(from: Fingerprint | null, to: Fingerprint): string[];
+/** Parse a stored fingerprint; null for a missing or malformed value. */
+declare function parseFingerprint(raw: string | null | undefined): Fingerprint | null;
+/** What a migrated snapshot records: which components changed, and the before and after. */
+interface EnvironmentChange {
+  changed: string[];
+  from: Fingerprint | null;
+  to: Fingerprint;
+}
+export { EnvironmentChange, Fingerprint, buildFingerprint, changedFields, fingerprintHash, parseFingerprint };
+//# sourceMappingURL=fingerprint.d.mts.map

package/dist/capture/fingerprint.mjs

@@ -0,0 +1,82 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sha256 } from "../utils/hash.mjs";
+import { SIZING_DEFAULTS } from "./sizing.mjs";
+// src/capture/fingerprint.ts
+/** Build the fingerprint of one capture. Missing environment fields stay `null` (runner did not report them). */
+function buildFingerprint(engine, viewport, environment) {
+	return {
+		engine,
+		browserVersion: environment?.browserVersion ?? null,
+		platform: environment?.platform ?? null,
+		deviceScaleFactor: environment?.deviceScaleFactor ?? null,
+		fontsHash: environment?.fontsHash ?? null,
+		viewport: {
+			width: viewport.width,
+			height: viewport.height
+		},
+		sizing: SIZING_DEFAULTS
+	};
+}
+/** Stable hash of a fingerprint: the value stored as `infraHash`. */
+function fingerprintHash(fingerprint) {
+	return sha256(JSON.stringify([
+		fingerprint.engine,
+		fingerprint.browserVersion,
+		fingerprint.platform,
+		fingerprint.deviceScaleFactor,
+		fingerprint.fontsHash,
+		fingerprint.viewport.width,
+		fingerprint.viewport.height,
+		fingerprint.sizing
+	]));
+}
+/** The components whose change is an environment migration. Viewport is not one (see below). */
+const ENVIRONMENT_FIELDS = [
+	"engine",
+	"browserVersion",
+	"platform",
+	"deviceScaleFactor",
+	"fontsHash"
+];
+/**
+* Names of the environment components that differ; `["unknown"]` when the earlier fingerprint was
+* not recorded. A component one side did not report (`null`: a runner that does not report it, a
+* capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed. Viewport is
+* never a change here: its size comes from story parameters (the PR's own code), so a new size must
+* be reviewed, and it diffs on its own as a dimension change.
+*/
+function changedFields(from, to) {
+	if (!from) return ["unknown"];
+	return [...ENVIRONMENT_FIELDS.filter((key) => known(from[key]) && known(to[key]) && from[key] !== to[key]), ...JSON.stringify(from.sizing) === JSON.stringify(to.sizing) ? [] : ["sizing"]];
+}
+function known(value) {
+	return value !== null && value !== void 0;
+}
+/**
+* The fingerprint to store on a baseline: the capture's, with any component it did not report kept
+* from the baseline's earlier fingerprint, so an unknown component never overwrites a known one.
+*/
+function mergeFingerprint(earlier, now) {
+	return {
+		...now,
+		browserVersion: now.browserVersion ?? earlier?.browserVersion ?? null,
+		platform: now.platform ?? earlier?.platform ?? null,
+		deviceScaleFactor: now.deviceScaleFactor ?? earlier?.deviceScaleFactor ?? null,
+		fontsHash: now.fontsHash ?? earlier?.fontsHash ?? null
+	};
+}
+/** Parse a stored fingerprint; null for a missing or malformed value. */
+function parseFingerprint(raw) {
+	if (!raw) return null;
+	try {
+		const value = JSON.parse(raw);
+		return typeof value.engine === "string" && value.viewport ? value : null;
+	} catch {
+		return null;
+	}
+}
+export { buildFingerprint, changedFields, fingerprintHash, mergeFingerprint, parseFingerprint };
+
+//# sourceMappingURL=fingerprint.mjs.map

package/dist/capture/fingerprint.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.mjs","names":[],"sources":["../../src/capture/fingerprint.ts"],"sourcesContent":["/** Capture fingerprint: everything that changes pixels without a code change (ADR 0005 phase 4). */\nimport type { CaptureEnvironment } from \"../adapters/capture-runner.ts\";\nimport { sha256 } from \"../utils/hash.ts\";\nimport type { Viewport } from \"./adapter.ts\";\nimport { SIZING_DEFAULTS } from \"./sizing.ts\";\n\n/** The components behind a snapshot's `infraHash`, kept so a mismatch can say what changed. */\nexport interface Fingerprint {\n  engine: string;\n  browserVersion: string | null;\n  platform: string | null;\n  deviceScaleFactor: number | null;\n  fontsHash: string | null;\n  viewport: { width: number; height: number };\n  sizing: typeof SIZING_DEFAULTS;\n}\n\n/** Build the fingerprint of one capture. Missing environment fields stay `null` (runner did not report them). */\nexport function buildFingerprint(\n  engine: string,\n  viewport: Viewport,\n  environment: CaptureEnvironment | undefined,\n): Fingerprint {\n  return {\n    engine,\n    browserVersion: environment?.browserVersion ?? null,\n    platform: environment?.platform ?? null,\n    deviceScaleFactor: environment?.deviceScaleFactor ?? null,\n    fontsHash: environment?.fontsHash ?? null,\n    viewport: { width: viewport.width, height: viewport.height },\n    sizing: SIZING_DEFAULTS,\n  };\n}\n\n/** Stable hash of a fingerprint: the value stored as `infraHash`. */\nexport function fingerprintHash(fingerprint: Fingerprint): string {\n  return sha256(\n    JSON.stringify([\n      fingerprint.engine,\n      fingerprint.browserVersion,\n      fingerprint.platform,\n      fingerprint.deviceScaleFactor,\n      fingerprint.fontsHash,\n      fingerprint.viewport.width,\n      fingerprint.viewport.height,\n      fingerprint.sizing,\n    ]),\n  );\n}\n\n/** The components whose change is an environment migration. Viewport is not one (see below). */\nconst ENVIRONMENT_FIELDS = [\n  \"engine\",\n  \"browserVersion\",\n  \"platform\",\n  \"deviceScaleFactor\",\n  \"fontsHash\",\n] as const;\n\n/**\n * Names of the environment components that differ; `[\"unknown\"]` when the earlier fingerprint was\n * not recorded. A component one side did not report (`null`: a runner that does not report it, a\n * capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed. Viewport is\n * never a change here: its size comes from story parameters (the PR's own code), so a new size must\n * be reviewed, and it diffs on its own as a dimension change.\n */\nexport function changedFields(from: Fingerprint | null, to: Fingerprint): string[] {\n  if (!from) {\n    return [\"unknown\"];\n  }\n  return [\n    ...ENVIRONMENT_FIELDS.filter(\n      (key) => known(from[key]) && known(to[key]) && from[key] !== to[key],\n    ),\n    ...(JSON.stringify(from.sizing) === JSON.stringify(to.sizing) ? [] : [\"sizing\"]),\n  ];\n}\n\nfunction known(value: unknown): boolean {\n  return value !== null && value !== undefined;\n}\n\n/**\n * The fingerprint to store on a baseline: the capture's, with any component it did not report kept\n * from the baseline's earlier fingerprint, so an unknown component never overwrites a known one.\n */\nexport function mergeFingerprint(earlier: Fingerprint | null, now: Fingerprint): Fingerprint {\n  return {\n    ...now,\n    browserVersion: now.browserVersion ?? earlier?.browserVersion ?? null,\n    platform: now.platform ?? earlier?.platform ?? null,\n    deviceScaleFactor: now.deviceScaleFactor ?? earlier?.deviceScaleFactor ?? null,\n    fontsHash: now.fontsHash ?? earlier?.fontsHash ?? null,\n  };\n}\n\n/** Parse a stored fingerprint; null for a missing or malformed value. */\nexport function parseFingerprint(raw: string | null | undefined): Fingerprint | null {\n  if (!raw) {\n    return null;\n  }\n  try {\n    const value = JSON.parse(raw) as Partial<Fingerprint>;\n    return typeof value.engine === \"string\" && value.viewport ? (value as Fingerprint) : null;\n  } catch {\n    return null;\n  }\n}\n\n/** What a migrated snapshot records: which components changed, and the before and after. */\nexport interface EnvironmentChange {\n  changed: string[];\n  from: Fingerprint | null;\n  to: Fingerprint;\n}\n"],"mappings":";;;;;;;AAkBA,SAAgB,iBACd,QACA,UACA,aACa;CACb,OAAO;EACL;EACA,gBAAgB,aAAa,kBAAkB;EAC/C,UAAU,aAAa,YAAY;EACnC,mBAAmB,aAAa,qBAAqB;EACrD,WAAW,aAAa,aAAa;EACrC,UAAU;GAAE,OAAO,SAAS;GAAO,QAAQ,SAAS;EAAO;EAC3D,QAAQ;CACV;AACF;;AAGA,SAAgB,gBAAgB,aAAkC;CAChE,OAAO,OACL,KAAK,UAAU;EACb,YAAY;EACZ,YAAY;EACZ,YAAY;EACZ,YAAY;EACZ,YAAY;EACZ,YAAY,SAAS;EACrB,YAAY,SAAS;EACrB,YAAY;CACd,CAAC,CACH;AACF;;AAGA,MAAM,qBAAqB;CACzB;CACA;CACA;CACA;CACA;AACF;;;;;;;;AASA,SAAgB,cAAc,MAA0B,IAA2B;CACjF,IAAI,CAAC,MACH,OAAO,CAAC,SAAS;CAEnB,OAAO,CACL,GAAG,mBAAmB,QACnB,QAAQ,MAAM,KAAK,IAAI,KAAK,MAAM,GAAG,IAAI,KAAK,KAAK,SAAS,GAAG,IAClE,GACA,GAAI,KAAK,UAAU,KAAK,MAAM,MAAM,KAAK,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAChF;AACF;AAEA,SAAS,MAAM,OAAyB;CACtC,OAAO,UAAU,QAAQ,UAAU,KAAA;AACrC;;;;;AAMA,SAAgB,iBAAiB,SAA6B,KAA+B;CAC3F,OAAO;EACL,GAAG;EACH,gBAAgB,IAAI,kBAAkB,SAAS,kBAAkB;EACjE,UAAU,IAAI,YAAY,SAAS,YAAY;EAC/C,mBAAmB,IAAI,qBAAqB,SAAS,qBAAqB;EAC1E,WAAW,IAAI,aAAa,SAAS,aAAa;CACpD;AACF;;AAGA,SAAgB,iBAAiB,KAAoD;CACnF,IAAI,CAAC,KACH,OAAO;CAET,IAAI;EACF,MAAM,QAAQ,KAAK,MAAM,GAAG;EAC5B,OAAO,OAAO,MAAM,WAAW,YAAY,MAAM,WAAY,QAAwB;CACvF,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/capture/forked/channel.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ChildMessage, ParentMessage } from "./protocol.mjs";
+/** How the parent sees the capture child (`child_process.fork` adapts to this). */
+interface ChildProcessHandle {
+  send(message: ParentMessage): void;
+  onMessage(listener: (message: unknown) => void): void;
+  /** Fires once when the child ends; `code` is null when it was killed by a signal. */
+  onExit(listener: (info: {
+    code: number | null;
+    signal: string | null;
+  }) => void): void;
+  /** Stop the child: SIGTERM, escalating to SIGKILL; `force` goes straight to SIGKILL (a hung child ignores SIGTERM). */
+  kill(force?: boolean): void;
+}
+/** How the child sees its parent (`process.send` / `process.on("message")` adapt to this). */
+interface ParentPort {
+  send(message: ChildMessage): void;
+  onMessage(listener: (message: unknown) => void): void;
+  onDisconnect(listener: () => void): void;
+}
+export { ChildProcessHandle, ParentPort };
+//# sourceMappingURL=channel.d.mts.map

package/dist/capture/forked/child.d.mts

@@ -0,0 +1,32 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { CaptureHandlerOptions } from "../consumer/capture-handler.mjs";
+import { CaptureConsumerOptions } from "../consumer/types.mjs";
+import { ChildMessage } from "./protocol.mjs";
+/** Handler options minus the shard hand-out, which the child wires to the database queue. */
+type CaptureChildOptions = Omit<CaptureHandlerOptions, "enqueue" | "logger"> & Pick<CaptureConsumerOptions, "images" | "compare"> & {
+  logger?: Logger;
+  /** Retries stamped on shard jobs (default: the parent's `testing.retries`, handed down in the environment). */
+  retries?: number;
+};
+/** The slice of `process` the child uses; injectable so the lifecycle is testable. */
+interface ChildHost {
+  /** Present only in a forked process with an IPC channel. */
+  send?: (message: ChildMessage) => unknown;
+  on(event: "message" | "disconnect" | "SIGTERM" | "SIGINT", listener: (message?: unknown) => void): unknown;
+  env: Record<string, string | undefined>;
+  exit(code: number): void;
+}
+/**
+ * Run pushed jobs until the parent stops the child.
+ *
+ * - `SIGTERM` / `SIGINT`: let the runs in flight finish, then exit 0.
+ * - Parent gone (`disconnect`): nobody can receive results, so exit at once. Whatever was running
+ *   loses its lease with the parent and is redelivered to another consumer.
+ *
+ * @throws When not running as a forked child (no IPC channel), or when the image engine cannot load.
+ */
+declare function runCaptureChild(options: CaptureChildOptions, host?: ChildHost): Promise<void>;
+export { CaptureChildOptions, ChildHost, runCaptureChild };
+//# sourceMappingURL=child.d.mts.map