@storyshelf/core 0.7.0 → 0.9.0-next-d2cc082

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

@@ -1,12 +1,11 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/db-queue/types.ts
+// 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

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

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

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { REAL_TIMERS } from "./timers.mjs";
-//#region src/capture/db-queue/wake.ts
+// 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) {
@@ -42,7 +42,6 @@ async function waitFor(timers, waiters, ms) {
 	waiters.add(settle);
 	return await promise;
 }
-//#endregion
 export { createWakeSignal };
 
 //# sourceMappingURL=wake.mjs.map

package/dist/capture/design.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/design.ts
+// 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).
@@ -33,7 +33,6 @@ function logInvalidDesigns(logger, stories) {
 		design: story.designInvalid
 	}, "ignored invalid design url");
 }
-//#endregion
 export { extractDesignUrl, logInvalidDesigns };
 
 //# sourceMappingURL=design.mjs.map

package/dist/capture/diff-record.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { DEFAULT_DIFF_OPTIONS, diffImagesAsync } from "@storyshelf/image";
-//#region src/capture/diff-record.ts
+// src/capture/diff-record.ts
 /** Diff a stored screenshot against a baseline and persist the overlay; shared by capture and re-diff. */
 /** Per-story `diffThreshold` when it is a finite number in 0..1; otherwise the project threshold. */
 function resolvePixelThreshold(projectThreshold, override) {
@@ -44,7 +44,6 @@ async function writeDiffOverlay(storage, path, result, passed) {
 	await storage.write(path, result.diffImage);
 	return path;
 }
-//#endregion
 export { diffStoredScreenshots, resolvePixelThreshold, writeDiffOverlay };
 
 //# sourceMappingURL=diff-record.mjs.map

package/dist/capture/dispatch.d.mts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { DatabaseAdapter } from "../adapter/database.mjs";
 import { Logger } from "../logger.mjs";
+import { DatabaseAdapter } from "../adapter/database.mjs";
 import { BuildTables } from "../models/build.mjs";
 import { CaptureAttemptTables } from "../models/capture-attempt.mjs";
 import { CaptureLogTables } from "../models/capture-log.mjs";
@@ -9,7 +9,6 @@ import { ProjectTables } from "../models/project.mjs";
 import { JobLease } from "./job-lease.mjs";
 import { CaptureJobOptions } from "./orchestrator.mjs";
 import { BuildStatePublisher } from "./build-state/types.mjs";
-//#region src/capture/dispatch.d.ts
 /** Build the queue's job runner: post pending, apply skip rules, capture, report. */
 declare function createDispatchJob(deps: DispatchDeps): (job: CaptureDispatchJob, lease?: JobLease) => Promise<void>;
 /** Table handles required by dispatch. */
@@ -36,6 +35,5 @@ interface CaptureDispatchJob {
   /** W3C `traceparent` continuing the enqueueing request's trace. */
   traceparent?: string;
 }
-//#endregion
 export { CaptureDispatchJob, DispatchDeps, DispatchTables, createDispatchJob };
 //# sourceMappingURL=dispatch.d.mts.map

package/dist/capture/dispatch.mjs

@@ -4,6 +4,7 @@ import.meta.url;
 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";
@@ -11,7 +12,7 @@ import { CaptureLogModel } from "../models/capture-log.mjs";
 import { leaseProgress } from "./progress.mjs";
 import { executeCaptureShard } from "./shards/execute.mjs";
 import { hasApprovedBuildForSha } from "./skip-checks.mjs";
-//#region src/capture/dispatch.ts
+// src/capture/dispatch.ts
 /** Build the queue's job runner: post pending, apply skip rules, capture, report. */
 function createDispatchJob(deps) {
 	return async (job, lease) => {
@@ -119,11 +120,23 @@ async function runAndReport(ctx, job) {
 			progress: ctx.progress
 		}, deps.jobOptions));
 	} catch (error) {
-		await finishAttempt(ctx, "failed", errorText(error));
-		await deps.buildState.request(build.id);
-		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);
@@ -180,7 +193,6 @@ async function loadClosing(deps, buildId) {
 		project
 	} : null;
 }
-//#endregion
 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 { 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\";\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 finishAttempt(ctx, \"failed\", errorText(error));\n    await deps.buildState.request(build.id);\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 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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"}
+{"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

@@ -4,7 +4,7 @@ import.meta.url;
 import { filterModes } from "./modes.mjs";
 import { renderBudgetMs } from "./render.mjs";
 import { resolveStoryViewports } from "./storybook.mjs";
-//#region src/capture/enrich.ts
+// 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
@@ -54,7 +54,6 @@ async function extractSafely(input) {
 		return {};
 	}
 }
-//#endregion
 export { assertModeCaps, enrichStories };
 
 //# sourceMappingURL=enrich.mjs.map

package/dist/capture/failure-sets.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { isFlakyStory } from "./adapter.mjs";
-//#region src/capture/failure-sets.ts
+// 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));
@@ -16,7 +16,6 @@ function classifyFailures(stories, failures) {
 	else sets.blocking.add(failure.storyId);
 	return sets;
 }
-//#endregion
 export { classifyFailures };
 
 //# sourceMappingURL=failure-sets.mjs.map

package/dist/capture/fingerprint.d.mts

@@ -3,9 +3,18 @@ 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";
-//#region src/capture/fingerprint.d.ts
+/** The components a comparison reads: the environment fields and the screenshot sizing. */
+type MeasuredField = "engine" | "browserVersion" | "platform" | "deviceScaleFactor" | "fontsHash" | "sizing";
+/** Components whose measurement changed, by the version that changed it. Tests pass their own. */
+type MeasurementHistory = Readonly<Record<number, readonly MeasuredField[]>>;
 /** The components behind a snapshot's `infraHash`, kept so a mismatch can say what changed. */
 interface Fingerprint {
+  /**
+   * How the environment components were measured (see {@link MEASUREMENT_VERSION}). Absent means
+   * version 1. It is not part of `infraHash`: the baseline's identity must not change when only
+   * the measurement does.
+   */
+  measurementVersion?: number | undefined;
   engine: string;
   browserVersion: string | null;
   platform: string | null;
@@ -19,24 +28,26 @@ interface Fingerprint {
 }
 /** 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`. */
+/** Stable hash of a fingerprint: the value stored as `infraHash`. `measurementVersion` is left out on purpose. */
 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.
+ * capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed, and so is a
+ * component measured differently in the two measurement versions. 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[];
+declare function changedFields(from: Fingerprint | null, to: Fingerprint, history?: MeasurementHistory): 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[];
+  /** Components not compared because their measurement changed between versions (absent: none). */
+  unknown?: string[] | undefined;
   from: Fingerprint | null;
   to: Fingerprint;
 }
-//#endregion
-export { EnvironmentChange, Fingerprint, buildFingerprint, changedFields, fingerprintHash, parseFingerprint };
+export { EnvironmentChange, Fingerprint, MeasuredField, MeasurementHistory, buildFingerprint, changedFields, fingerprintHash, parseFingerprint };
 //# sourceMappingURL=fingerprint.d.mts.map

package/dist/capture/fingerprint.mjs

@@ -3,10 +3,16 @@ import "node:url";
 import.meta.url;
 import { sha256 } from "../utils/hash.mjs";
 import { SIZING_DEFAULTS } from "./sizing.mjs";
-//#region src/capture/fingerprint.ts
+/**
+* Components whose measurement changed when a version was introduced, by that version. Version 1
+* is the baseline of the scheme, so nothing is listed yet. Between two versions, a listed
+* component is compared as unknown, never as a mismatch (it must not cause an environment migration).
+*/
+const REMEASURED_IN = {};
 /** Build the fingerprint of one capture. Missing environment fields stay `null` (runner did not report them). */
 function buildFingerprint(engine, viewport, environment) {
 	return {
+		measurementVersion: 1,
 		engine,
 		browserVersion: environment?.browserVersion ?? null,
 		platform: environment?.platform ?? null,
@@ -19,7 +25,7 @@ function buildFingerprint(engine, viewport, environment) {
 		sizing: SIZING_DEFAULTS
 	};
 }
-/** Stable hash of a fingerprint: the value stored as `infraHash`. */
+/** Stable hash of a fingerprint: the value stored as `infraHash`. `measurementVersion` is left out on purpose. */
 function fingerprintHash(fingerprint) {
 	return sha256(JSON.stringify([
 		fingerprint.engine,
@@ -40,16 +46,38 @@ const ENVIRONMENT_FIELDS = [
 	"deviceScaleFactor",
 	"fontsHash"
 ];
+/** The version a fingerprint was measured with; one stored before versions existed is version 1. */
+function measurementVersionOf(fingerprint) {
+	return fingerprint.measurementVersion ?? 1;
+}
+/**
+* Components measured differently in the two fingerprints: those listed for any version between
+* theirs. Empty when the versions match (nothing about a same-version comparison changes).
+*/
+function remeasuredFields(from, to, history = REMEASURED_IN) {
+	const [low, high] = [measurementVersionOf(from), measurementVersionOf(to)].toSorted((left, right) => left - right);
+	const fields = Object.entries(history).filter(([version]) => Number(version) > (low ?? 1) && Number(version) <= (high ?? 1)).flatMap(([, listed]) => listed);
+	return [...new Set(fields)];
+}
 /**
 * 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.
+* capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed, and so is a
+* component measured differently in the two measurement versions. 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) {
+function changedFields(from, to, history = REMEASURED_IN) {
 	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"]];
+	const remeasured = new Set(remeasuredFields(from, to, history));
+	return [...ENVIRONMENT_FIELDS.filter((key) => !remeasured.has(key) && known(from[key]) && known(to[key]) && from[key] !== to[key]), ...remeasured.has("sizing") || JSON.stringify(from.sizing) === JSON.stringify(to.sizing) ? [] : ["sizing"]];
+}
+/**
+* Components that could not be compared because their measurement changed between the two
+* fingerprints' versions. The review says the environment is partly unknown; nothing migrates.
+*/
+function unknownFields(from, to, history = REMEASURED_IN) {
+	return from ? remeasuredFields(from, to, history) : [];
 }
 function known(value) {
 	return value !== null && value !== void 0;
@@ -58,13 +86,15 @@ function known(value) {
 * 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) {
+function mergeFingerprint(earlier, now, history = REMEASURED_IN) {
+	const stale = new Set(earlier ? remeasuredFields(earlier, now, history) : []);
+	const kept = (key) => now[key] ?? (stale.has(key) ? null : earlier?.[key] ?? null);
 	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
+		browserVersion: kept("browserVersion"),
+		platform: kept("platform"),
+		deviceScaleFactor: kept("deviceScaleFactor"),
+		fontsHash: kept("fontsHash")
 	};
 }
 /** Parse a stored fingerprint; null for a missing or malformed value. */
@@ -77,7 +107,6 @@ function parseFingerprint(raw) {
 		return null;
 	}
 }
-//#endregion
-export { buildFingerprint, changedFields, fingerprintHash, mergeFingerprint, parseFingerprint };
+export { REMEASURED_IN, buildFingerprint, changedFields, fingerprintHash, measurementVersionOf, mergeFingerprint, parseFingerprint, remeasuredFields, unknownFields };
 
 //# sourceMappingURL=fingerprint.mjs.map

package/dist/capture/fingerprint.mjs.map

@@ -1 +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"}
+{"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/**\n * What this build of StoryShelf measures the environment with (the browser probe). Bump it only\n * together with a probe change, and list in {@link REMEASURED_IN} the components whose measurement\n * changed. A fingerprint stored without it is version 1.\n */\nexport const MEASUREMENT_VERSION = 1;\n\n/** The components a comparison reads: the environment fields and the screenshot sizing. */\nexport type MeasuredField =\n  | \"engine\"\n  | \"browserVersion\"\n  | \"platform\"\n  | \"deviceScaleFactor\"\n  | \"fontsHash\"\n  | \"sizing\";\n\n/**\n * Components whose measurement changed when a version was introduced, by that version. Version 1\n * is the baseline of the scheme, so nothing is listed yet. Between two versions, a listed\n * component is compared as unknown, never as a mismatch (it must not cause an environment migration).\n */\n// A test that needs a re-measured component adds a version here and deletes it again.\nexport const REMEASURED_IN: Record<number, readonly MeasuredField[]> = {};\n\n/** Components whose measurement changed, by the version that changed it. Tests pass their own. */\nexport type MeasurementHistory = Readonly<Record<number, readonly MeasuredField[]>>;\n\n/** The components behind a snapshot's `infraHash`, kept so a mismatch can say what changed. */\nexport interface Fingerprint {\n  /**\n   * How the environment components were measured (see {@link MEASUREMENT_VERSION}). Absent means\n   * version 1. It is not part of `infraHash`: the baseline's identity must not change when only\n   * the measurement does.\n   */\n  measurementVersion?: number | undefined;\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    measurementVersion: MEASUREMENT_VERSION,\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`. `measurementVersion` is left out on purpose. */\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/** The version a fingerprint was measured with; one stored before versions existed is version 1. */\nexport function measurementVersionOf(fingerprint: Fingerprint): number {\n  return fingerprint.measurementVersion ?? 1;\n}\n\n/**\n * Components measured differently in the two fingerprints: those listed for any version between\n * theirs. Empty when the versions match (nothing about a same-version comparison changes).\n */\nexport function remeasuredFields(\n  from: Fingerprint,\n  to: Fingerprint,\n  history: MeasurementHistory = REMEASURED_IN,\n): MeasuredField[] {\n  const [low, high] = [measurementVersionOf(from), measurementVersionOf(to)].toSorted(\n    (left, right) => left - right,\n  );\n  const fields = Object.entries(history)\n    .filter(([version]) => Number(version) > (low ?? 1) && Number(version) <= (high ?? 1))\n    .flatMap(([, listed]) => listed);\n  return [...new Set(fields)];\n}\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, and so is a\n * component measured differently in the two measurement versions. Viewport is never a change\n * here: its size comes from story parameters (the PR's own code), so a new size must be reviewed,\n * and it diffs on its own as a dimension change.\n */\nexport function changedFields(\n  from: Fingerprint | null,\n  to: Fingerprint,\n  history: MeasurementHistory = REMEASURED_IN,\n): string[] {\n  if (!from) {\n    return [\"unknown\"];\n  }\n  const remeasured = new Set<string>(remeasuredFields(from, to, history));\n  return [\n    ...ENVIRONMENT_FIELDS.filter(\n      (key) => !remeasured.has(key) && known(from[key]) && known(to[key]) && from[key] !== to[key],\n    ),\n    ...(remeasured.has(\"sizing\") || JSON.stringify(from.sizing) === JSON.stringify(to.sizing)\n      ? []\n      : [\"sizing\"]),\n  ];\n}\n\n/**\n * Components that could not be compared because their measurement changed between the two\n * fingerprints' versions. The review says the environment is partly unknown; nothing migrates.\n */\nexport function unknownFields(\n  from: Fingerprint | null,\n  to: Fingerprint,\n  history: MeasurementHistory = REMEASURED_IN,\n): string[] {\n  return from ? remeasuredFields(from, to, history) : [];\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(\n  earlier: Fingerprint | null,\n  now: Fingerprint,\n  history: MeasurementHistory = REMEASURED_IN,\n): Fingerprint {\n  // A value measured under another version is not carried over a changed measurement.\n  const stale = new Set<string>(earlier ? remeasuredFields(earlier, now, history) : []);\n  const kept = <Key extends \"browserVersion\" | \"platform\" | \"deviceScaleFactor\" | \"fontsHash\">(\n    key: Key,\n  ): Fingerprint[Key] => now[key] ?? (stale.has(key) ? null : (earlier?.[key] ?? null));\n  return {\n    ...now,\n    browserVersion: kept(\"browserVersion\"),\n    platform: kept(\"platform\"),\n    deviceScaleFactor: kept(\"deviceScaleFactor\"),\n    fontsHash: kept(\"fontsHash\"),\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  /** Components not compared because their measurement changed between versions (absent: none). */\n  unknown?: string[] | undefined;\n  from: Fingerprint | null;\n  to: Fingerprint;\n}\n"],"mappings":";;;;;;;;;;AA4BA,MAAa,gBAA0D,CAAC;;AAuBxE,SAAgB,iBACd,QACA,UACA,aACa;CACb,OAAO;EACL,oBAAA;EACA;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;;AAGA,SAAgB,qBAAqB,aAAkC;CACrE,OAAO,YAAY,sBAAsB;AAC3C;;;;;AAMA,SAAgB,iBACd,MACA,IACA,UAA8B,eACb;CACjB,MAAM,CAAC,KAAK,QAAQ,CAAC,qBAAqB,IAAI,GAAG,qBAAqB,EAAE,CAAC,CAAC,CAAC,UACxE,MAAM,UAAU,OAAO,KAC1B;CACA,MAAM,SAAS,OAAO,QAAQ,OAAO,CAAC,CACnC,QAAQ,CAAC,aAAa,OAAO,OAAO,KAAK,OAAO,MAAM,OAAO,OAAO,MAAM,QAAQ,EAAE,CAAC,CACrF,SAAS,GAAG,YAAY,MAAM;CACjC,OAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAC5B;;;;;;;;;AAUA,SAAgB,cACd,MACA,IACA,UAA8B,eACpB;CACV,IAAI,CAAC,MACH,OAAO,CAAC,SAAS;CAEnB,MAAM,aAAa,IAAI,IAAY,iBAAiB,MAAM,IAAI,OAAO,CAAC;CACtE,OAAO,CACL,GAAG,mBAAmB,QACnB,QAAQ,CAAC,WAAW,IAAI,GAAG,KAAK,MAAM,KAAK,IAAI,KAAK,MAAM,GAAG,IAAI,KAAK,KAAK,SAAS,GAAG,IAC1F,GACA,GAAI,WAAW,IAAI,QAAQ,KAAK,KAAK,UAAU,KAAK,MAAM,MAAM,KAAK,UAAU,GAAG,MAAM,IACpF,CAAC,IACD,CAAC,QAAQ,CACf;AACF;;;;;AAMA,SAAgB,cACd,MACA,IACA,UAA8B,eACpB;CACV,OAAO,OAAO,iBAAiB,MAAM,IAAI,OAAO,IAAI,CAAC;AACvD;AAEA,SAAS,MAAM,OAAyB;CACtC,OAAO,UAAU,QAAQ,UAAU,KAAA;AACrC;;;;;AAMA,SAAgB,iBACd,SACA,KACA,UAA8B,eACjB;CAEb,MAAM,QAAQ,IAAI,IAAY,UAAU,iBAAiB,SAAS,KAAK,OAAO,IAAI,CAAC,CAAC;CACpF,MAAM,QACJ,QACqB,IAAI,SAAS,MAAM,IAAI,GAAG,IAAI,OAAQ,UAAU,QAAQ;CAC/E,OAAO;EACL,GAAG;EACH,gBAAgB,KAAK,gBAAgB;EACrC,UAAU,KAAK,UAAU;EACzB,mBAAmB,KAAK,mBAAmB;EAC3C,WAAW,KAAK,WAAW;CAC7B;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

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { ChildMessage, ParentMessage } from "./protocol.mjs";
-//#region src/capture/forked/channel.d.ts
 /** How the parent sees the capture child (`child_process.fork` adapts to this). */
 interface ChildProcessHandle {
   send(message: ParentMessage): void;
@@ -20,6 +19,5 @@ interface ParentPort {
   onMessage(listener: (message: unknown) => void): void;
   onDisconnect(listener: () => void): void;
 }
-//#endregion
 export { ChildProcessHandle, ParentPort };
 //# sourceMappingURL=channel.d.mts.map

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

@@ -4,7 +4,6 @@ import { Logger } from "../../logger.mjs";
 import { CaptureHandlerOptions } from "../consumer/capture-handler.mjs";
 import { CaptureConsumerOptions } from "../consumer/types.mjs";
 import { ChildMessage } from "./protocol.mjs";
-//#region src/capture/forked/child.d.ts
 /** 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;
@@ -29,6 +28,5 @@ interface ChildHost {
  * @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>;
-//#endregion
 export { CaptureChildOptions, ChildHost, runCaptureChild };
 //# sourceMappingURL=child.d.mts.map

package/dist/capture/forked/child.mjs

@@ -10,7 +10,7 @@ import { createCaptureHandler, originOf } from "../consumer/capture-handler.mjs"
 import { applyImageSettings, ensureImageEngine } from "../consumer/startup.mjs";
 import "./fork.mjs";
 import { isParentMessage } from "./protocol.mjs";
-//#region src/capture/forked/child.ts
+// src/capture/forked/child.ts
 /**
 * Entry helper for a forked capture child (`testing.workerEntry`). The app is the consumer: it
 * polls the database queue, holds the slots and the lease, and pushes each leased job here over
@@ -196,7 +196,6 @@ function processHost() {
 		exit: (code) => process.exit(code)
 	};
 }
-//#endregion
 export { runCaptureChild };
 
 //# sourceMappingURL=child.mjs.map

package/dist/capture/forked/crash-tracker.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/forked/crash-tracker.ts
+// src/capture/forked/crash-tracker.ts
 /** Counts child crashes inside a sliding window, to tell a flaky child from a crash loop. */
 var CrashTracker = class {
 	#limit;
@@ -17,7 +17,6 @@ var CrashTracker = class {
 		return this.#times.length >= this.#limit;
 	}
 };
-//#endregion
 export { CrashTracker };
 
 //# sourceMappingURL=crash-tracker.mjs.map

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

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/capture/forked/decision.d.ts
 /** Whether a capture child is worth forking on this host (ADR 0005 phase 3 fallback rules). */
 /** What the decision looks at. */
 interface ForkHost {
@@ -21,6 +20,5 @@ declare const FORK_MIN_CPUS = 2;
 declare const FORK_MIN_MEMORY_BYTES: number;
 /** Pick the capture process model for a host. */
 declare function decideCaptureProcess(host: ForkHost): ForkDecision;
-//#endregion
 export { FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, ForkDecision, ForkHost, decideCaptureProcess };
 //# sourceMappingURL=decision.d.mts.map

package/dist/capture/forked/decision.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/forked/decision.ts
+// src/capture/forked/decision.ts
 /** Smallest host that still gains from a second process: below this the child only costs memory. */
 const FORK_MIN_CPUS = 2;
 const FORK_MIN_MEMORY_BYTES = 2 * 1024 ** 3;
@@ -21,7 +21,6 @@ function decideCaptureProcess(host) {
 	};
 	return { mode: "fork" };
 }
-//#endregion
 export { FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, decideCaptureProcess };
 
 //# sourceMappingURL=decision.mjs.map

package/dist/capture/forked/exit.mjs

@@ -1,12 +1,11 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/capture/forked/exit.ts
+// src/capture/forked/exit.ts
 /** `signal SIGKILL` or `code 1`. */
 function describeExit(info) {
 	return info.signal ? `signal ${info.signal}` : `code ${info.code}`;
 }
-//#endregion
 export { describeExit };
 
 //# sourceMappingURL=exit.mjs.map

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

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { ChildProcessHandle } from "./channel.mjs";
-//#region src/capture/forked/fork.d.ts
 /** Environment variable the forked child sees; set to this value so a module can tell it is the child. */
 declare const CAPTURE_WORKER_ROLE = "capture-worker";
 /** Environment variable carrying the parent's `testing.retries` to the child, which stamps it on the shard jobs it queues. */
@@ -26,6 +25,5 @@ interface ForkOptions {
  * @throws When the runtime cannot fork, or the fork itself throws.
  */
 declare function forkCaptureChild(options: ForkOptions): ChildProcessHandle;
-//#endregion
 export { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, ForkOptions, canForkCaptureChild, forkCaptureChild };
 //# sourceMappingURL=fork.d.mts.map