@storyshelf/core 0.6.1 → 0.7.0

package/dist/retention/screenshot-sweep.mjs

@@ -0,0 +1,128 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { col } from "../models/columns.mjs";
+import { contentDir } from "../paths.mjs";
+import { CLAIMS_DIR } from "../utils/screenshot-store.mjs";
+import { and, eq, gte, inArray, like } from "drizzle-orm";
+//#region src/retention/screenshot-sweep.ts
+/** Mark-and-sweep for a project's content-addressed screenshots. */
+/** Longest an unreferenced screenshot is kept after the sweep first sees it (default 24 h). */
+const SWEEP_GRACE_MS = 864e5;
+/** Marker object remembering when each unreferenced screenshot was first seen. */
+const MARKER = ".sweep.json";
+/**
+* Build statuses during which a capture may have reused an existing object (the "already exists,
+* skip the write" path) without yet writing the snapshot rows that reference it.
+*/
+const ACTIVE_BUILD_STATUSES = [
+	"pending",
+	"capturing",
+	"comparing"
+];
+/**
+* Delete content-addressed screenshots that no snapshot or baseline points at any more.
+*
+* An object is deleted only after it has been unreferenced across two sweeps at least `graceMs`
+* apart (first-seen times live in a marker object, so no schema is needed and the storage
+* adapter needs no modification times). A capture writes its screenshot before the rows that
+* reference it, so a single look is never enough; each candidate is also re-checked against the
+* database immediately before it is deleted.
+*
+* Reusing an object that already exists writes nothing, so the sweep cannot see it by looking at
+* storage. Deletion is therefore deferred (objects stay pending, first-seen times kept) while the
+* project has reuse in flight: a build still capturing, or a reuse claim from a baseline import or
+* approval ({@link withContentClaim}). Both checks are bounded by the grace period, so a build
+* stuck in `capturing` or a claim left by a crash delays reclaiming storage, never forever.
+*/
+async function sweepScreenshotContent(deps, projectId, options = {}) {
+	const dir = `${contentDir(projectId)}/`;
+	const unreferenced = await findUnreferenced(deps, projectId, dir);
+	const firstSeen = await readMarker(deps.storage, dir);
+	const outcome = await deleteDue(deps, projectId, unreferenced, firstSeen, {
+		now: options.now ?? Date.now(),
+		graceMs: options.graceMs ?? 864e5
+	});
+	await writeMarker(deps.storage, dir, outcome.pending, firstSeen);
+	if (outcome.removed > 0) deps.logger?.info({
+		projectId,
+		removed: outcome.removed
+	}, "removed unreferenced screenshots");
+	return {
+		removed: outcome.removed,
+		pending: Object.keys(outcome.pending).length
+	};
+}
+async function findUnreferenced(deps, projectId, dir) {
+	const objects = (await deps.storage.list(dir)).filter((path) => path.startsWith(dir) && path.endsWith(".png"));
+	const referenced = await referencedPaths(deps, projectId);
+	return objects.filter((path) => !referenced.has(path));
+}
+/** Delete what has been unreferenced for the whole grace period; return the rest with first-seen times. */
+async function deleteDue(deps, projectId, unreferenced, firstSeen, clock) {
+	const pending = {};
+	let removed = 0;
+	for (const path of unreferenced) {
+		const seen = firstSeen[path] ?? clock.now;
+		if (clock.now - seen >= clock.graceMs && !await isHeld(deps, projectId, path, clock)) {
+			await deps.storage.delete(path);
+			removed += 1;
+		} else pending[path] = seen;
+	}
+	return {
+		removed,
+		pending
+	};
+}
+async function referencedPaths(deps, projectId) {
+	const rows = await Promise.all([deps.tables.snapshots, deps.tables.baselines].map(async (table) => await deps.db.list(table, { where: and(eq(col(table, "projectId"), projectId), like(col(table, "screenshotPath"), `${contentDir(projectId)}/%`)) })));
+	return new Set(rows.flat().map((row) => row.screenshotPath));
+}
+/** Whether `path` must be kept now: referenced by a row, or reuse may be in flight. */
+async function isHeld(deps, projectId, path, clock) {
+	return await isReferenced(deps, projectId, path) || await hasActiveBuild(deps, projectId, clock) || await hasActiveClaim(deps.storage, projectId, clock);
+}
+/** A build of the project that is still capturing and was updated within the grace period. */
+async function hasActiveBuild(deps, projectId, clock) {
+	const table = deps.tables.builds;
+	return (await deps.db.list(table, {
+		where: and(eq(col(table, "projectId"), projectId), inArray(col(table, "status"), ACTIVE_BUILD_STATUSES), gte(col(table, "updatedAt"), new Date(clock.now - clock.graceMs).toISOString())),
+		limit: 1
+	})).length > 0;
+}
+/** A reuse claim younger than the grace period; older ones (left by a crash) are ignored. */
+async function hasActiveClaim(storage, projectId, clock) {
+	const claims = await storage.list(`${contentDir(projectId)}/${CLAIMS_DIR}/`);
+	return (await Promise.all(claims.map(async (path) => await claimTime(storage, path)))).some((at) => at === null || clock.now - at < clock.graceMs);
+}
+/** When a claim was made; null when it cannot be read (treated as active: fail safe). */
+async function claimTime(storage, path) {
+	try {
+		const parsed = JSON.parse((await storage.read(path)).toString("utf8"));
+		return typeof parsed.at === "number" ? parsed.at : null;
+	} catch {
+		return null;
+	}
+}
+async function isReferenced(deps, projectId, path) {
+	return (await Promise.all([deps.tables.snapshots, deps.tables.baselines].map(async (table) => (await deps.db.list(table, {
+		where: and(eq(col(table, "projectId"), projectId), eq(col(table, "screenshotPath"), path)),
+		limit: 1
+	})).length > 0))).some(Boolean);
+}
+async function readMarker(storage, dir) {
+	try {
+		if (!await storage.exists(`${dir}${MARKER}`)) return {};
+		const parsed = JSON.parse((await storage.read(`${dir}${MARKER}`)).toString("utf8"));
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+async function writeMarker(storage, dir, next, previous) {
+	if (JSON.stringify(next) !== JSON.stringify(previous)) await storage.write(`${dir}${MARKER}`, Buffer.from(JSON.stringify(next)));
+}
+//#endregion
+export { SWEEP_GRACE_MS, sweepScreenshotContent };
+
+//# sourceMappingURL=screenshot-sweep.mjs.map

package/dist/retention/screenshot-sweep.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot-sweep.mjs","names":[],"sources":["../../src/retention/screenshot-sweep.ts"],"sourcesContent":["/** Mark-and-sweep for a project's content-addressed screenshots. */\nimport { and, eq, gte, inArray, like } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { Logger } from \"pino\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { col } from \"../models/columns.ts\";\nimport { contentDir } from \"../utils/paths.ts\";\nimport { CLAIMS_DIR } from \"../utils/screenshot-store.ts\";\n\n/** Longest an unreferenced screenshot is kept after the sweep first sees it (default 24 h). */\nexport const SWEEP_GRACE_MS = 24 * 60 * 60 * 1000;\n\n/** Marker object remembering when each unreferenced screenshot was first seen. */\nconst MARKER = \".sweep.json\";\n\n/**\n * Build statuses during which a capture may have reused an existing object (the \"already exists,\n * skip the write\" path) without yet writing the snapshot rows that reference it.\n */\nconst ACTIVE_BUILD_STATUSES = [\"pending\", \"capturing\", \"comparing\"];\n\n/** Tables the sweep reads references and in-flight builds from. */\nexport interface SweepTables {\n  snapshots: Table;\n  baselines: Table;\n  builds: Table;\n}\n\n/** Inputs for {@link sweepScreenshotContent}. */\nexport interface SweepDeps {\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n  tables: SweepTables;\n  logger?: Logger;\n}\n\n/** What one sweep did. */\nexport interface SweepResult {\n  /** Objects deleted. */\n  removed: number;\n  /** Unreferenced objects still inside their grace period. */\n  pending: number;\n}\n\n/**\n * Delete content-addressed screenshots that no snapshot or baseline points at any more.\n *\n * An object is deleted only after it has been unreferenced across two sweeps at least `graceMs`\n * apart (first-seen times live in a marker object, so no schema is needed and the storage\n * adapter needs no modification times). A capture writes its screenshot before the rows that\n * reference it, so a single look is never enough; each candidate is also re-checked against the\n * database immediately before it is deleted.\n *\n * Reusing an object that already exists writes nothing, so the sweep cannot see it by looking at\n * storage. Deletion is therefore deferred (objects stay pending, first-seen times kept) while the\n * project has reuse in flight: a build still capturing, or a reuse claim from a baseline import or\n * approval ({@link withContentClaim}). Both checks are bounded by the grace period, so a build\n * stuck in `capturing` or a claim left by a crash delays reclaiming storage, never forever.\n */\nexport async function sweepScreenshotContent(\n  deps: SweepDeps,\n  projectId: string,\n  options: { now?: number; graceMs?: number } = {},\n): Promise<SweepResult> {\n  const dir = `${contentDir(projectId)}/`;\n  const unreferenced = await findUnreferenced(deps, projectId, dir);\n  const firstSeen = await readMarker(deps.storage, dir);\n  const outcome = await deleteDue(deps, projectId, unreferenced, firstSeen, {\n    now: options.now ?? Date.now(),\n    graceMs: options.graceMs ?? SWEEP_GRACE_MS,\n  });\n  await writeMarker(deps.storage, dir, outcome.pending, firstSeen);\n  if (outcome.removed > 0) {\n    deps.logger?.info({ projectId, removed: outcome.removed }, \"removed unreferenced screenshots\");\n  }\n  return { removed: outcome.removed, pending: Object.keys(outcome.pending).length };\n}\n\nasync function findUnreferenced(\n  deps: SweepDeps,\n  projectId: string,\n  dir: string,\n): Promise<string[]> {\n  // Only this project's content screenshots: the prefix guards against an adapter listing keys\n  // in another form (such as OS-separated paths), which would otherwise match no reference.\n  const objects = (await deps.storage.list(dir)).filter(\n    (path) => path.startsWith(dir) && path.endsWith(\".png\"),\n  );\n  const referenced = await referencedPaths(deps, projectId);\n  return objects.filter((path) => !referenced.has(path));\n}\n\n/** Delete what has been unreferenced for the whole grace period; return the rest with first-seen times. */\nasync function deleteDue(\n  deps: SweepDeps,\n  projectId: string,\n  unreferenced: string[],\n  firstSeen: Record<string, number>,\n  clock: { now: number; graceMs: number },\n): Promise<{ removed: number; pending: Record<string, number> }> {\n  const pending: Record<string, number> = {};\n  let removed = 0;\n  for (const path of unreferenced) {\n    const seen = firstSeen[path] ?? clock.now;\n    // oxlint-disable-next-line eslint/no-await-in-loop -- re-check and delete one object at a time\n    if (clock.now - seen >= clock.graceMs && !(await isHeld(deps, projectId, path, clock))) {\n      // oxlint-disable-next-line eslint/no-await-in-loop -- see above\n      await deps.storage.delete(path);\n      removed += 1;\n    } else {\n      pending[path] = seen;\n    }\n  }\n  return { removed, pending };\n}\n\nasync function referencedPaths(deps: SweepDeps, projectId: string): Promise<Set<string>> {\n  const rows = await Promise.all(\n    [deps.tables.snapshots, deps.tables.baselines].map(\n      async (table) =>\n        (await deps.db.list(table, {\n          where: and(\n            eq(col(table, \"projectId\"), projectId),\n            like(col(table, \"screenshotPath\"), `${contentDir(projectId)}/%`),\n          ),\n        })) as unknown as { screenshotPath: string }[],\n    ),\n  );\n  return new Set(rows.flat().map((row) => row.screenshotPath));\n}\n\n/** Whether `path` must be kept now: referenced by a row, or reuse may be in flight. */\nasync function isHeld(\n  deps: SweepDeps,\n  projectId: string,\n  path: string,\n  clock: { now: number; graceMs: number },\n): Promise<boolean> {\n  return (\n    (await isReferenced(deps, projectId, path)) ||\n    (await hasActiveBuild(deps, projectId, clock)) ||\n    (await hasActiveClaim(deps.storage, projectId, clock))\n  );\n}\n\n/** A build of the project that is still capturing and was updated within the grace period. */\nasync function hasActiveBuild(\n  deps: SweepDeps,\n  projectId: string,\n  clock: { now: number; graceMs: number },\n): Promise<boolean> {\n  const table = deps.tables.builds;\n  const rows = await deps.db.list(table, {\n    where: and(\n      eq(col(table, \"projectId\"), projectId),\n      inArray(col(table, \"status\"), ACTIVE_BUILD_STATUSES),\n      gte(col(table, \"updatedAt\"), new Date(clock.now - clock.graceMs).toISOString()),\n    ),\n    limit: 1,\n  });\n  return rows.length > 0;\n}\n\n/** A reuse claim younger than the grace period; older ones (left by a crash) are ignored. */\nasync function hasActiveClaim(\n  storage: StorageAdapter,\n  projectId: string,\n  clock: { now: number; graceMs: number },\n): Promise<boolean> {\n  const claims = await storage.list(`${contentDir(projectId)}/${CLAIMS_DIR}/`);\n  const times = await Promise.all(claims.map(async (path) => await claimTime(storage, path)));\n  return times.some((at) => at === null || clock.now - at < clock.graceMs);\n}\n\n/** When a claim was made; null when it cannot be read (treated as active: fail safe). */\nasync function claimTime(storage: StorageAdapter, path: string): Promise<number | null> {\n  try {\n    const parsed = JSON.parse((await storage.read(path)).toString(\"utf8\")) as { at?: unknown };\n    return typeof parsed.at === \"number\" ? parsed.at : null;\n  } catch {\n    return null;\n  }\n}\n\nasync function isReferenced(deps: SweepDeps, projectId: string, path: string): Promise<boolean> {\n  const hits = await Promise.all(\n    [deps.tables.snapshots, deps.tables.baselines].map(\n      async (table) =>\n        (\n          await deps.db.list(table, {\n            where: and(\n              eq(col(table, \"projectId\"), projectId),\n              eq(col(table, \"screenshotPath\"), path),\n            ),\n            limit: 1,\n          })\n        ).length > 0,\n    ),\n  );\n  return hits.some(Boolean);\n}\n\nasync function readMarker(storage: StorageAdapter, dir: string): Promise<Record<string, number>> {\n  try {\n    if (!(await storage.exists(`${dir}${MARKER}`))) {\n      return {};\n    }\n    const parsed = JSON.parse((await storage.read(`${dir}${MARKER}`)).toString(\"utf8\")) as unknown;\n    return parsed && typeof parsed === \"object\" ? (parsed as Record<string, number>) : {};\n  } catch {\n    return {};\n  }\n}\n\nasync function writeMarker(\n  storage: StorageAdapter,\n  dir: string,\n  next: Record<string, number>,\n  previous: Record<string, number>,\n): Promise<void> {\n  if (JSON.stringify(next) !== JSON.stringify(previous)) {\n    await storage.write(`${dir}${MARKER}`, Buffer.from(JSON.stringify(next)));\n  }\n}\n"],"mappings":"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"}

package/dist/retention.d.mts

@@ -3,6 +3,8 @@ import __tsdown_shims_url from 'node:url';
 import { DatabaseAdapter } from "./adapter/database.mjs";
 import { StorageAdapter } from "./adapter/storage.mjs";
 import { Project } from "./schema/project.mjs";
+import { SWEEP_GRACE_MS, SweepDeps, SweepResult, SweepTables, sweepScreenshotContent } from "./retention/screenshot-sweep.mjs";
+import { AiPurgeResult, STALE_RUN_MS, purgeAiData } from "./retention/ai.mjs";
 import { Logger } from "pino";
 import { Table } from "drizzle-orm";
 //#region src/retention/purge.d.ts
@@ -18,8 +20,20 @@ declare class Retention {
   private readonly storage;
   private readonly tables;
   private readonly logger?;
-  constructor(db: DatabaseAdapter, storage: StorageAdapter, tables: RetentionTables, logger?: Logger | undefined);
+  constructor(db: DatabaseAdapter, storage: StorageAdapter, tables: RetentionTables, logger?: Logger);
   purge(project: Project, options: PurgeOptions): Promise<PurgeResult>;
+  /**
+   * The builds a purge removes: terminal builds past the window (minus the latest per branch when
+   * asked), and pending builds idle past it (ADR 0013, decision 9). Persistent builds stay.
+   */
+  private selectBuilds;
+  /** Reclaim screenshots no snapshot or baseline references any more; never blocks the purge. */
+  private sweepScreenshots;
+  /**
+   * Drop finished queue jobs older than the build cutoff (they have no foreign key to a build, and
+   * a finished job is only history); never blocks the purge. Queued and running jobs are kept.
+   */
+  private purgeFinishedJobs;
   private removeBuild;
   private latestPerBranch;
   private deleteBuildFiles;
@@ -41,5 +55,5 @@ interface BranchGcResult {
   removedBaselines: number;
 }
 //#endregion
-export { BranchGcResult, PurgeOptions, PurgeResult, Retention, RetentionTables };
+export { type AiPurgeResult, BranchGcResult, PurgeOptions, PurgeResult, Retention, RetentionTables, STALE_RUN_MS, SWEEP_GRACE_MS, type SweepDeps, type SweepResult, type SweepTables, purgeAiData, sweepScreenshotContent };
 //# sourceMappingURL=retention.d.mts.map

package/dist/retention.mjs

@@ -2,10 +2,18 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { TERMINAL_BUILD_STATUSES } from "./types.mjs";
+import { col } from "./models/columns.mjs";
 import { BuildModel } from "./models/build.mjs";
 import { BaselineModel } from "./models/baseline.mjs";
+import { CaptureJobModel } from "./models/capture-job.mjs";
+import { BuildComponentModel } from "./models/build-component.mjs";
+import { InsightModel } from "./models/insight.mjs";
 import { LabelModel } from "./models/label.mjs";
-import { and, desc, eq, getTableColumns, inArray, lt } from "drizzle-orm";
+import { PackageUsageModel } from "./models/usage.mjs";
+import { pendingCandidates } from "./retention/pending.mjs";
+import { SWEEP_GRACE_MS, sweepScreenshotContent } from "./retention/screenshot-sweep.mjs";
+import { STALE_RUN_MS, purgeAiData } from "./retention/ai.mjs";
+import { and, desc, eq, inArray, lt } from "drizzle-orm";
 //#region src/retention/purge.ts
 /** Removes expired transient builds while keeping baselines and persistent builds. */
 var Retention = class {
@@ -21,38 +29,86 @@ var Retention = class {
 	}
 	async purge(project, options) {
 		const cutoff = (/* @__PURE__ */ new Date(Date.now() - options.ttlDays * 864e5)).toISOString();
-		const candidates = await this.db.list(this.tables.builds, { where: and(eq(getTableColumns(this.tables.builds)["projectId"], project.id), inArray(getTableColumns(this.tables.builds)["status"], [...TERMINAL_BUILD_STATUSES]), lt(getTableColumns(this.tables.builds)["updatedAt"], cutoff)) });
-		const keep = options.keepLatestPerBranch ? await this.latestPerBranch(project.id) : /* @__PURE__ */ new Set();
-		const labelModel = new LabelModel(this.db, this.tables);
-		const buildIds = (await Promise.all(candidates.map(async (build) => {
-			const buildId = build.id;
-			if (keep.has(buildId) || await labelModel.hasPersistent(project.id, buildId)) return null;
-			return buildId;
-		}))).filter((id) => id !== null);
+		const { buildIds, pending } = await this.selectBuilds(project, options, cutoff);
 		const results = await Promise.all(buildIds.map(async (buildId) => ({
 			files: await this.deleteBuildFiles(project.id, buildId),
 			removed: await this.removeBuild(buildId)
 		})));
 		const removedBuilds = results.filter((r) => r.removed).length;
 		const removedFiles = results.reduce((sum, r) => sum + r.files, 0);
+		await this.sweepScreenshots(project);
+		const removedJobs = await this.purgeFinishedJobs(cutoff);
 		this.logger?.info({
 			projectId: project.id,
 			removedBuilds,
-			removedFiles
+			removedFiles,
+			removedJobs,
+			removedPending: pending
 		}, "build retention purge complete");
 		return {
 			removedBuilds,
 			removedFiles
 		};
 	}
+	/**
+	* The builds a purge removes: terminal builds past the window (minus the latest per branch when
+	* asked), and pending builds idle past it (ADR 0013, decision 9). Persistent builds stay.
+	*/
+	async selectBuilds(project, options, cutoff) {
+		const candidates = await this.db.list(this.tables.builds, { where: and(eq(col(this.tables.builds, "projectId"), project.id), inArray(col(this.tables.builds, "status"), [...TERMINAL_BUILD_STATUSES]), lt(col(this.tables.builds, "updatedAt"), cutoff)) });
+		const keep = options.keepLatestPerBranch ? await this.latestPerBranch(project.id) : /* @__PURE__ */ new Set();
+		const persistent = await new LabelModel(this.db, this.tables).persistentBuildIds(project.id);
+		const terminal = candidates.map((build) => build.id).filter((buildId) => !keep.has(buildId));
+		const pending = (await pendingCandidates(this.db, project.id, cutoff)).map((candidate) => candidate.buildId);
+		return {
+			buildIds: [...terminal, ...pending].filter((buildId) => !persistent.has(buildId)),
+			pending: pending.length
+		};
+	}
+	/** Reclaim screenshots no snapshot or baseline references any more; never blocks the purge. */
+	async sweepScreenshots(project) {
+		try {
+			await sweepScreenshotContent({
+				db: this.db,
+				storage: this.storage,
+				tables: {
+					snapshots: this.db.tables.snapshots,
+					baselines: this.tables.baselines,
+					builds: this.tables.builds
+				},
+				logger: this.logger
+			}, project.id);
+		} catch (error) {
+			this.logger?.warn({
+				err: error,
+				projectId: project.id
+			}, "screenshot sweep failed");
+		}
+	}
+	/**
+	* Drop finished queue jobs older than the build cutoff (they have no foreign key to a build, and
+	* a finished job is only history); never blocks the purge. Queued and running jobs are kept.
+	*/
+	async purgeFinishedJobs(cutoff) {
+		try {
+			return await new CaptureJobModel(this.db).purgeFinished(cutoff);
+		} catch (error) {
+			this.logger?.warn({ err: error }, "capture job purge failed");
+			return 0;
+		}
+	}
 	async removeBuild(buildId) {
+		await new InsightModel(this.db).removeForBuild(buildId);
+		await new CaptureJobModel(this.db).removeForBuild(buildId);
+		await new BuildComponentModel(this.db).removeForBuild(buildId);
+		await new PackageUsageModel(this.db).removeForBuild(buildId);
 		await new BuildModel(this.db, this.tables).remove(buildId);
 		return true;
 	}
 	async latestPerBranch(projectId) {
 		const rows = await this.db.list(this.tables.builds, {
-			where: eq(getTableColumns(this.tables.builds)["projectId"], projectId),
-			orderBy: desc(getTableColumns(this.tables.builds)["updatedAt"])
+			where: eq(col(this.tables.builds, "projectId"), projectId),
+			orderBy: desc(col(this.tables.builds, "updatedAt"))
 		});
 		const latest = /* @__PURE__ */ new Map();
 		for (const row of rows) {
@@ -108,12 +164,13 @@ var Retention = class {
 			removedBaselines: 0
 		};
 		const cutoff = (/* @__PURE__ */ new Date(Date.now() - ttlDays * 864e5)).toISOString();
-		const stale = collectStaleBranches(await this.db.list(this.tables.builds, { where: eq(getTableColumns(this.tables.builds)["projectId"], project.id) }), project.gitDefaultBranch, cutoff);
+		const stale = collectStaleBranches(await this.db.list(this.tables.builds, { where: eq(col(this.tables.builds, "projectId"), project.id) }), project.gitDefaultBranch, cutoff);
 		if (stale.size === 0) return {
 			removedBranches: 0,
 			removedBaselines: 0
 		};
 		const removedBaselines = await new BaselineModel(this.db, this.tables, this.storage).removeStaleBranches(project.id, stale);
+		await this.sweepScreenshots(project);
 		this.logger?.info({
 			projectId: project.id,
 			removedBranches: stale.size,
@@ -140,6 +197,6 @@ function branchLatestAt(rows) {
 	return latestAt;
 }
 //#endregion
-export { Retention };
+export { Retention, STALE_RUN_MS, SWEEP_GRACE_MS, purgeAiData, sweepScreenshotContent };
 
 //# sourceMappingURL=retention.mjs.map

package/dist/retention.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"retention.mjs","names":[],"sources":["../src/retention/purge.ts"],"sourcesContent":["import { and, desc, eq, getTableColumns, inArray, lt } from \"drizzle-orm\";\nimport type { SQLWrapper, Table } from \"drizzle-orm\";\nimport type { Logger } from \"pino\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { BaselineModel } from \"../models/baseline.ts\";\nimport { BuildModel, type BuildTables } from \"../models/build.ts\";\nimport { LabelModel, type LabelTables } from \"../models/label.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport { TERMINAL_BUILD_STATUSES } from \"../types.ts\";\n\n/** Table handles for retention queries. */\nexport interface RetentionTables {\n  builds: Table;\n  buildLabels: Table;\n  baselines: Table;\n}\n\n/** Removes expired transient builds while keeping baselines and persistent builds. */\nexport class Retention {\n  constructor(\n    private readonly db: DatabaseAdapter,\n    private readonly storage: StorageAdapter,\n    private readonly tables: RetentionTables,\n    private readonly logger?: Logger,\n  ) {}\n\n  async purge(project: Project, options: PurgeOptions): Promise<PurgeResult> {\n    const cutoff = new Date(Date.now() - options.ttlDays * 86_400_000).toISOString();\n    const candidates = await this.db.list(this.tables.builds, {\n      where: and(\n        eq(getTableColumns(this.tables.builds)[\"projectId\"] as unknown as SQLWrapper, project.id),\n        inArray(getTableColumns(this.tables.builds)[\"status\"] as unknown as SQLWrapper, [\n          ...TERMINAL_BUILD_STATUSES,\n        ]),\n        lt(getTableColumns(this.tables.builds)[\"updatedAt\"] as unknown as SQLWrapper, cutoff),\n      ),\n    });\n\n    const keep = options.keepLatestPerBranch\n      ? await this.latestPerBranch(project.id)\n      : new Set<string>();\n    const labelModel = new LabelModel(this.db, this.tables as unknown as LabelTables);\n    const target = await Promise.all(\n      candidates.map(async (build) => {\n        const buildId = (build as { id: string }).id;\n        if (keep.has(buildId) || (await labelModel.hasPersistent(project.id, buildId))) {\n          return null;\n        }\n        return buildId;\n      }),\n    );\n\n    const buildIds = target.filter((id): id is string => id !== null);\n    const results = await Promise.all(\n      buildIds.map(async (buildId) => ({\n        files: await this.deleteBuildFiles(project.id, buildId),\n        removed: await this.removeBuild(buildId),\n      })),\n    );\n    const removedBuilds = results.filter((r: { removed: boolean }) => r.removed).length;\n    const removedFiles = results.reduce((sum: number, r: { files: number }) => sum + r.files, 0);\n    this.logger?.info(\n      { projectId: project.id, removedBuilds, removedFiles },\n      \"build retention purge complete\",\n    );\n    return { removedBuilds, removedFiles };\n  }\n\n  private async removeBuild(buildId: string): Promise<boolean> {\n    await new BuildModel(this.db, this.tables as unknown as BuildTables).remove(buildId);\n    return true;\n  }\n\n  private async latestPerBranch(projectId: string): Promise<Set<string>> {\n    const rows = (await this.db.list(this.tables.builds, {\n      where: eq(\n        getTableColumns(this.tables.builds)[\"projectId\"] as unknown as SQLWrapper,\n        projectId,\n      ),\n      orderBy: desc(getTableColumns(this.tables.builds)[\"updatedAt\"] as unknown as SQLWrapper),\n    })) as unknown as { gitBranch: string; id: string }[];\n    const latest = new Map<string, string>();\n    for (const row of rows) {\n      const branch = row.gitBranch;\n      const current = latest.get(branch);\n      if (!current) {\n        latest.set(branch, row.id);\n      }\n    }\n    return new Set(latest.values());\n  }\n\n  private async deleteBuildFiles(projectId: string, buildId: string): Promise<number> {\n    const prefix = `${projectId}/builds/${buildId}/`;\n    const manifestPath = `${prefix}storybook/manifest.json`;\n    let manifestFiles: string[] = [];\n    try {\n      if (await this.storage.exists(manifestPath)) {\n        const raw = await this.storage.read(manifestPath);\n        const manifest = JSON.parse(raw.toString(\"utf8\")) as Record<string, string>;\n        manifestFiles = Object.values(manifest);\n      }\n    } catch {\n      // ignore — manifest may not exist for old builds\n    }\n    const files = await this.storage.list(prefix);\n    await Promise.all(\n      files.map(async (file) => {\n        await this.storage.delete(file);\n      }),\n    );\n    // Decrement content refs for this build's manifest\n    for (const hash of manifestFiles) {\n      try {\n        const contentRefs = this.db.tables.contentRefs;\n        const existing = (await this.db.get(contentRefs, hash)) as unknown as {\n          refCount: number;\n        } | null;\n        // oxlint-disable-next-line unicorn/prefer-ternary -- refCount check is clearer as if/else\n        if (existing) {\n          const refCount = existing.refCount;\n          // oxlint-disable-next-line unicorn/prefer-ternary -- grace logic is clearer as if/else\n          if (refCount <= 1) {\n            // Keep for 7-day grace: set refCount 0 and update lastSeenAt, don't delete yet\n            await this.db.update(contentRefs, hash, {\n              refCount: 0,\n              lastSeenAt: new Date().toISOString(),\n            });\n          } else {\n            await this.db.update(contentRefs, hash, {\n              refCount: refCount - 1,\n              lastSeenAt: new Date().toISOString(),\n            });\n          }\n        }\n      } catch {\n        // ignore — content_refs may not exist\n      }\n    }\n    // GC stale content_refs with 7-day grace\n    try {\n      const contentRefs = this.db.tables.contentRefs;\n      const cutoff = new Date(Date.now() - 7 * 86_400_000).toISOString();\n      const all = (await this.db.list(contentRefs)) as unknown as {\n        hash: string;\n        refCount: number;\n        lastSeenAt: string;\n      }[];\n      for (const row of all) {\n        if (row.refCount === 0 && row.lastSeenAt < cutoff) {\n          await this.storage.delete(`content/${row.hash}`).catch(() => {\n            // ignore storage delete failure\n          });\n          await this.db.remove(contentRefs, row.hash);\n        }\n      }\n    } catch {\n      // ignore — content_refs may not exist\n    }\n    return files.length;\n  }\n\n  async purgeStaleBranches(project: Project, ttlDays: number): Promise<BranchGcResult> {\n    if (ttlDays <= 0) {\n      return { removedBranches: 0, removedBaselines: 0 };\n    }\n    const cutoff = new Date(Date.now() - ttlDays * 86_400_000).toISOString();\n    const rows = (await this.db.list(this.tables.builds, {\n      where: eq(\n        getTableColumns(this.tables.builds)[\"projectId\"] as unknown as SQLWrapper,\n        project.id,\n      ),\n    })) as unknown as { gitBranch: string; updatedAt: string }[];\n    const stale = collectStaleBranches(rows, project.gitDefaultBranch, cutoff);\n    if (stale.size === 0) {\n      return { removedBranches: 0, removedBaselines: 0 };\n    }\n    const baselines = new BaselineModel(this.db, this.tables, this.storage);\n    const removedBaselines = await baselines.removeStaleBranches(project.id, stale);\n    this.logger?.info(\n      { projectId: project.id, removedBranches: stale.size, removedBaselines },\n      \"branch GC complete\",\n    );\n    return { removedBranches: stale.size, removedBaselines };\n  }\n}\n\n/** Options controlling which builds a retention purge removes. */\nexport interface PurgeOptions {\n  ttlDays: number;\n  keepLatestPerBranch: boolean;\n}\n\n/** Counts of builds and files removed by a retention purge. */\nexport interface PurgeResult {\n  removedBuilds: number;\n  removedFiles: number;\n}\n\n/** Counts of stale branches and baselines removed. */\nexport interface BranchGcResult {\n  removedBranches: number;\n  removedBaselines: number;\n}\n\nfunction collectStaleBranches(\n  rows: { gitBranch: string; updatedAt: string }[],\n  defaultBranch: string,\n  cutoff: string,\n): Set<string> {\n  const latestAt = branchLatestAt(rows);\n  const stale = new Set<string>();\n  for (const [branch, updatedAt] of latestAt) {\n    if (branch !== defaultBranch && updatedAt < cutoff) {\n      stale.add(branch);\n    }\n  }\n  return stale;\n}\n\nfunction branchLatestAt(rows: { gitBranch: string; updatedAt: string }[]): Map<string, string> {\n  const latestAt = new Map<string, string>();\n  for (const row of rows) {\n    const current = latestAt.get(row.gitBranch);\n    if (!current || row.updatedAt > current) {\n      latestAt.set(row.gitBranch, row.updatedAt);\n    }\n  }\n  return latestAt;\n}\n"],"mappings":"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"}
+{"version":3,"file":"retention.mjs","names":[],"sources":["../src/retention/purge.ts"],"sourcesContent":["import { and, desc, eq, inArray, lt } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { Logger } from \"pino\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport { BaselineModel } from \"../models/baseline.ts\";\nimport { BuildComponentModel } from \"../models/build-component.ts\";\nimport { BuildModel, type BuildTables } from \"../models/build.ts\";\nimport { CaptureJobModel } from \"../models/capture-job.ts\";\nimport { InsightModel } from \"../models/insight.ts\";\nimport { LabelModel, type LabelTables } from \"../models/label.ts\";\nimport { PackageUsageModel } from \"../models/usage.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport { TERMINAL_BUILD_STATUSES } from \"../types.ts\";\nimport { pendingCandidates } from \"./pending.ts\";\nimport { sweepScreenshotContent } from \"./screenshot-sweep.ts\";\n\nexport {\n  sweepScreenshotContent,\n  SWEEP_GRACE_MS,\n  type SweepDeps,\n  type SweepResult,\n  type SweepTables,\n} from \"./screenshot-sweep.ts\";\nimport { col } from \"../models/columns.ts\";\nexport { purgeAiData, STALE_RUN_MS, type AiPurgeResult } from \"./ai.ts\";\n\n/** Table handles for retention queries. */\nexport interface RetentionTables {\n  builds: Table;\n  buildLabels: Table;\n  baselines: Table;\n}\n\n/** Removes expired transient builds while keeping baselines and persistent builds. */\nexport class Retention {\n  private readonly db: DatabaseAdapter;\n  private readonly storage: StorageAdapter;\n  private readonly tables: RetentionTables;\n  private readonly logger?: Logger;\n\n  constructor(\n    db: DatabaseAdapter,\n    storage: StorageAdapter,\n    tables: RetentionTables,\n    logger?: Logger,\n  ) {\n    this.db = db;\n    this.storage = storage;\n    this.tables = tables;\n    this.logger = logger;\n  }\n\n  async purge(project: Project, options: PurgeOptions): Promise<PurgeResult> {\n    const cutoff = new Date(Date.now() - options.ttlDays * 86_400_000).toISOString();\n    const { buildIds, pending } = await this.selectBuilds(project, options, cutoff);\n    const results = await Promise.all(\n      buildIds.map(async (buildId) => ({\n        files: await this.deleteBuildFiles(project.id, buildId),\n        removed: await this.removeBuild(buildId),\n      })),\n    );\n    const removedBuilds = results.filter((r: { removed: boolean }) => r.removed).length;\n    const removedFiles = results.reduce((sum: number, r: { files: number }) => sum + r.files, 0);\n    await this.sweepScreenshots(project);\n    const removedJobs = await this.purgeFinishedJobs(cutoff);\n    this.logger?.info(\n      { projectId: project.id, removedBuilds, removedFiles, removedJobs, removedPending: pending },\n      \"build retention purge complete\",\n    );\n    return { removedBuilds, removedFiles };\n  }\n\n  /**\n   * The builds a purge removes: terminal builds past the window (minus the latest per branch when\n   * asked), and pending builds idle past it (ADR 0013, decision 9). Persistent builds stay.\n   */\n  private async selectBuilds(\n    project: Project,\n    options: PurgeOptions,\n    cutoff: string,\n  ): Promise<{ buildIds: string[]; pending: number }> {\n    const candidates = await this.db.list(this.tables.builds, {\n      where: and(\n        eq(col(this.tables.builds, \"projectId\"), project.id),\n        inArray(col(this.tables.builds, \"status\"), [...TERMINAL_BUILD_STATUSES]),\n        lt(col(this.tables.builds, \"updatedAt\"), cutoff),\n      ),\n    });\n    const keep = options.keepLatestPerBranch\n      ? await this.latestPerBranch(project.id)\n      : new Set<string>();\n    const persistent = await new LabelModel(\n      this.db,\n      this.tables as unknown as LabelTables,\n    ).persistentBuildIds(project.id);\n    const terminal = candidates\n      .map((build) => (build as { id: string }).id)\n      .filter((buildId) => !keep.has(buildId));\n    // Pending builds leave on their own clock; \"the latest on a branch\" does not shield them.\n    const pending = (await pendingCandidates(this.db, project.id, cutoff)).map(\n      (candidate) => candidate.buildId,\n    );\n    return {\n      buildIds: [...terminal, ...pending].filter((buildId) => !persistent.has(buildId)),\n      pending: pending.length,\n    };\n  }\n\n  /** Reclaim screenshots no snapshot or baseline references any more; never blocks the purge. */\n  private async sweepScreenshots(project: Project): Promise<void> {\n    try {\n      await sweepScreenshotContent(\n        {\n          db: this.db,\n          storage: this.storage,\n          tables: {\n            snapshots: this.db.tables.snapshots,\n            baselines: this.tables.baselines,\n            builds: this.tables.builds,\n          },\n          logger: this.logger,\n        },\n        project.id,\n      );\n    } catch (error) {\n      this.logger?.warn({ err: error, projectId: project.id }, \"screenshot sweep failed\");\n    }\n  }\n\n  /**\n   * Drop finished queue jobs older than the build cutoff (they have no foreign key to a build, and\n   * a finished job is only history); never blocks the purge. Queued and running jobs are kept.\n   */\n  private async purgeFinishedJobs(cutoff: string): Promise<number> {\n    try {\n      return await new CaptureJobModel(this.db).purgeFinished(cutoff);\n    } catch (error) {\n      this.logger?.warn({ err: error }, \"capture job purge failed\");\n      return 0;\n    }\n  }\n\n  private async removeBuild(buildId: string): Promise<boolean> {\n    await new InsightModel(this.db).removeForBuild(buildId);\n    await new CaptureJobModel(this.db).removeForBuild(buildId);\n    await new BuildComponentModel(this.db).removeForBuild(buildId);\n    await new PackageUsageModel(this.db).removeForBuild(buildId);\n    await new BuildModel(this.db, this.tables as unknown as BuildTables).remove(buildId);\n    return true;\n  }\n\n  private async latestPerBranch(projectId: string): Promise<Set<string>> {\n    const rows = (await this.db.list(this.tables.builds, {\n      where: eq(col(this.tables.builds, \"projectId\"), projectId),\n      orderBy: desc(col(this.tables.builds, \"updatedAt\")),\n    })) as unknown as { gitBranch: string; id: string }[];\n    const latest = new Map<string, string>();\n    for (const row of rows) {\n      const branch = row.gitBranch;\n      const current = latest.get(branch);\n      if (!current) {\n        latest.set(branch, row.id);\n      }\n    }\n    return new Set(latest.values());\n  }\n\n  private async deleteBuildFiles(projectId: string, buildId: string): Promise<number> {\n    const prefix = `${projectId}/builds/${buildId}/`;\n    const manifestPath = `${prefix}storybook/manifest.json`;\n    let manifestFiles: string[] = [];\n    try {\n      if (await this.storage.exists(manifestPath)) {\n        const raw = await this.storage.read(manifestPath);\n        const manifest = JSON.parse(raw.toString(\"utf8\")) as Record<string, string>;\n        manifestFiles = Object.values(manifest);\n      }\n    } catch {\n      // ignore — manifest may not exist for old builds\n    }\n    const files = await this.storage.list(prefix);\n    await Promise.all(\n      files.map(async (file) => {\n        await this.storage.delete(file);\n      }),\n    );\n    // Decrement content refs for this build's manifest\n    for (const hash of manifestFiles) {\n      try {\n        const contentRefs = this.db.tables.contentRefs;\n        const existing = (await this.db.get(contentRefs, hash)) as unknown as {\n          refCount: number;\n        } | null;\n        // oxlint-disable-next-line unicorn/prefer-ternary -- refCount check is clearer as if/else\n        if (existing) {\n          const refCount = existing.refCount;\n          // oxlint-disable-next-line unicorn/prefer-ternary -- grace logic is clearer as if/else\n          if (refCount <= 1) {\n            // Keep for 7-day grace: set refCount 0 and update lastSeenAt, don't delete yet\n            await this.db.update(contentRefs, hash, {\n              refCount: 0,\n              lastSeenAt: new Date().toISOString(),\n            });\n          } else {\n            await this.db.update(contentRefs, hash, {\n              refCount: refCount - 1,\n              lastSeenAt: new Date().toISOString(),\n            });\n          }\n        }\n      } catch {\n        // ignore — content_refs may not exist\n      }\n    }\n    // GC stale content_refs with 7-day grace\n    try {\n      const contentRefs = this.db.tables.contentRefs;\n      const cutoff = new Date(Date.now() - 7 * 86_400_000).toISOString();\n      const all = (await this.db.list(contentRefs)) as unknown as {\n        hash: string;\n        refCount: number;\n        lastSeenAt: string;\n      }[];\n      for (const row of all) {\n        if (row.refCount === 0 && row.lastSeenAt < cutoff) {\n          await this.storage.delete(`content/${row.hash}`).catch(() => {\n            // ignore storage delete failure\n          });\n          await this.db.remove(contentRefs, row.hash);\n        }\n      }\n    } catch {\n      // ignore — content_refs may not exist\n    }\n    return files.length;\n  }\n\n  async purgeStaleBranches(project: Project, ttlDays: number): Promise<BranchGcResult> {\n    if (ttlDays <= 0) {\n      return { removedBranches: 0, removedBaselines: 0 };\n    }\n    const cutoff = new Date(Date.now() - ttlDays * 86_400_000).toISOString();\n    const rows = (await this.db.list(this.tables.builds, {\n      where: eq(col(this.tables.builds, \"projectId\"), project.id),\n    })) as unknown as { gitBranch: string; updatedAt: string }[];\n    const stale = collectStaleBranches(rows, project.gitDefaultBranch, cutoff);\n    if (stale.size === 0) {\n      return { removedBranches: 0, removedBaselines: 0 };\n    }\n    const baselines = new BaselineModel(this.db, this.tables, this.storage);\n    const removedBaselines = await baselines.removeStaleBranches(project.id, stale);\n    await this.sweepScreenshots(project);\n    this.logger?.info(\n      { projectId: project.id, removedBranches: stale.size, removedBaselines },\n      \"branch GC complete\",\n    );\n    return { removedBranches: stale.size, removedBaselines };\n  }\n}\n\n/** Options controlling which builds a retention purge removes. */\nexport interface PurgeOptions {\n  ttlDays: number;\n  keepLatestPerBranch: boolean;\n}\n\n/** Counts of builds and files removed by a retention purge. */\nexport interface PurgeResult {\n  removedBuilds: number;\n  removedFiles: number;\n}\n\n/** Counts of stale branches and baselines removed. */\nexport interface BranchGcResult {\n  removedBranches: number;\n  removedBaselines: number;\n}\n\nfunction collectStaleBranches(\n  rows: { gitBranch: string; updatedAt: string }[],\n  defaultBranch: string,\n  cutoff: string,\n): Set<string> {\n  const latestAt = branchLatestAt(rows);\n  const stale = new Set<string>();\n  for (const [branch, updatedAt] of latestAt) {\n    if (branch !== defaultBranch && updatedAt < cutoff) {\n      stale.add(branch);\n    }\n  }\n  return stale;\n}\n\nfunction branchLatestAt(rows: { gitBranch: string; updatedAt: string }[]): Map<string, string> {\n  const latestAt = new Map<string, string>();\n  for (const row of rows) {\n    const current = latestAt.get(row.gitBranch);\n    if (!current || row.updatedAt > current) {\n      latestAt.set(row.gitBranch, row.updatedAt);\n    }\n  }\n  return latestAt;\n}\n"],"mappings":"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"}

package/dist/schema/baseline.d.mts

@@ -11,6 +11,12 @@ interface Baseline {
   snapshotId: string | null;
   screenshotPath: string;
   infraHash: string | null;
+  /** JSON `Fingerprint` behind `infraHash`; null on baselines recorded before fingerprints. */
+  fingerprint: string | null;
+  /** Resolved mode definition (JSON) — display/capture only; identity is `viewportName`. */
+  mode?: string | null;
+  /** Engine the image was captured with. */
+  browser?: string;
   createdAt: string;
   updatedAt: string;
 }

package/dist/schema/build-component.d.mts

@@ -0,0 +1,25 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/schema/build-component.d.ts
+/**
+ * Row type of `build_components` (ADR 0006, decision 9): one row per component of a published
+ * build, written from the build's Storybook index when publishing ends. A component is the
+ * stories and docs entries that share a story file (`importPath`).
+ */
+/** One component of one build, as persisted from the Storybook index. */
+interface BuildComponent {
+  id: string;
+  projectId: string;
+  buildId: string;
+  /** Story file the component's entries come from, without a leading `./`; empty when the index has none. */
+  importPath: string;
+  title: string;
+  /** Story entries (docs entries are not counted). */
+  storyCount: number;
+  /** SHA-256 of the component's entries (id, name, type), so two builds compare with one string. */
+  hash: string;
+  createdAt: string;
+}
+//#endregion
+export { BuildComponent };
+//# sourceMappingURL=build-component.d.mts.map

package/dist/schema/build-review.d.mts

@@ -0,0 +1,17 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ReviewVerdict } from "../types.mjs";
+//#region src/schema/build-review.d.ts
+/** One verdict on one build. */
+interface BuildReview {
+  id: string;
+  buildId: string;
+  /** The reviewer; null when auth is off or an admin token wrote it. */
+  userId: string | null;
+  verdict: ReviewVerdict;
+  body: string | null;
+  createdAt: string;
+}
+//#endregion
+export { BuildReview };
+//# sourceMappingURL=build-review.d.mts.map

package/dist/schema/build.d.mts

@@ -18,6 +18,8 @@ interface Build {
   changedCount: number;
   approvedCount: number;
   rejectedCount: number;
+  /** Snapshots inherited from the baseline without rendering (affected capture); a subset of `snapshotCount`. */
+  inheritedCount: number;
   /** Affected capture enabled for this build (default true). */
   affectedOnly: boolean;
   /** Ancestor commit the affected set was computed against, if any. */
@@ -26,6 +28,11 @@ interface Build {
   changedFiles: string | null;
   /** JSON array of affected story import paths; null means full capture. */
   affectedImportPaths: string | null;
+  /**
+   * JSON array of the results of the build's Storybook `.test()` entries (`TestResult`); null when
+   * the project does not run tests or the Storybook has none.
+   */
+  testResults?: string | null;
   createdAt: string;
   updatedAt: string;
 }

package/dist/schema/capture-job.d.mts

@@ -0,0 +1,60 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/schema/capture-job.d.ts
+/**
+ * Row types of `capture_jobs`, the database queue (ADR 0006, decision 4).
+ *
+ * One table holds two kinds of row, told apart by `entry`:
+ *
+ * - a **job** row (`id` = job id, `jobId` = its own id) carries delivery state: `status` is
+ *   `queued | running | done | failed | cancelled`, `attempt` counts the attempts started so far,
+ *   and `visibleAt` is when a queued job may next be claimed;
+ * - an **attempt** row (`id` = `<jobId>:<attempt>`) is one claim of a job, created by a unique-key
+ *   insert. It holds the `owner`, the lease expiry (in `visibleAt`) and, once over, its outcome:
+ *   `status` is `running | done | failed | expired`.
+ *
+ * `visibleAt` is non-null only while a row is a poll candidate (a queued job row, a running attempt
+ * row), so the poll is one indexed range query that reads at most one row.
+ */
+/** Which of the two row kinds of `capture_jobs` a row is. */
+type CaptureJobEntry = "job" | "attempt";
+/** What a job does: render a build or shard, publish a zip, or deliver a notification. */
+type CaptureJobKind = "capture" | "publish" | "notify";
+/** Lifecycle of a job row. */
+type CaptureJobStatus = "queued" | "running" | "done" | "failed" | "cancelled";
+/** Lifecycle of an attempt row; `expired` is a lease another instance took over. */
+type CaptureAttemptStatus = "running" | "done" | "failed" | "expired";
+/** One row of `capture_jobs`: a job, or one attempt at it. */
+interface CaptureJobRow {
+  id: string;
+  entry: CaptureJobEntry;
+  /** The job this row belongs to (a job row's own id). */
+  jobId: string;
+  kind: CaptureJobKind;
+  /** Build the job works on; notify jobs may have none. */
+  buildId: string | null;
+  /** `capture_shards` row a shard job renders; null for the build's own job. */
+  shardId: string | null;
+  /** Job row: attempts started so far. Attempt row: its number, from 1. */
+  attempt: number;
+  /** Attempts allowed in total (`testing.retries` + 1); copied onto attempt rows. */
+  maxAttempts: number;
+  status: CaptureJobStatus | CaptureAttemptStatus;
+  /** Queued job: when it may be claimed. Running attempt: its lease expiry. Otherwise null. */
+  visibleAt: string | null;
+  /** Instance holding an attempt; null on job rows. */
+  owner: string | null;
+  /** JSON: request id, traceparent and kind-specific fields. */
+  payload: string | null;
+  /** Set once cancel was asked for; the holder turns it into `runner.cancel`. */
+  cancelRequestedAt: string | null;
+  /** Job row: the last attempt's error. Attempt row: its own. */
+  error: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+//#endregion
+export { CaptureAttemptStatus, CaptureJobEntry, CaptureJobKind, CaptureJobRow, CaptureJobStatus };
+//# sourceMappingURL=capture-job.d.mts.map

package/dist/schema/capture-shard.d.mts

@@ -0,0 +1,35 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/schema/capture-shard.d.ts
+/** What a row of `capture_shards` is: a stage of a sharded capture, or the claim that finalizes it. */
+type CaptureShardKind = "plan" | "render" | "finalize";
+/** Lifecycle of one shard row. */
+type CaptureShardStatus = "pending" | "running" | "done" | "failed";
+/**
+ * One row per stage of a sharded capture: the `plan` (ordinal 0) records the build-level plan, each
+ * `render` shard (ordinal 1..n) is a slice of stories, and a `finalize` row (ordinal 0) is the
+ * claim that makes exactly one worker finish the build. `(buildId, kind, ordinal)` is unique, so
+ * inserting a row is an atomic claim on every database.
+ */
+interface CaptureShard {
+  id: string;
+  projectId: string;
+  buildId: string;
+  kind: CaptureShardKind;
+  ordinal: number;
+  status: CaptureShardStatus;
+  /** Attempt row the build's log history and result belong to (plan row only). */
+  attemptId: string | null;
+  /** JSON: the stories and engines of a render shard, or the plan's settings. */
+  payload: string | null;
+  /** JSON outcome once the stage ended (failed, flaky and a11y story ids, counts, duration). */
+  result: string | null;
+  error: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+//#endregion
+export { CaptureShard, CaptureShardKind, CaptureShardStatus };
+//# sourceMappingURL=capture-shard.d.mts.map

package/dist/schema/comment.d.mts

@@ -7,6 +7,8 @@ interface Comment {
   projectId: string;
   buildId: string;
   snapshotId: string | null;
+  /** Storybook story id of a story-anchored comment (ADR 0013, decision 2); null otherwise. */
+  storyId: string | null;
   userId: string | null;
   body: string;
   parentId: string | null;

package/dist/schema/connection.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/schema/connection.d.ts
+/**
+ * A user's own OAuth connection to an external service (`design` providers today,
+ * issue trackers later). One per user and service; tokens are encrypted at rest.
+ */
+interface UserConnection {
+  id: string;
+  userId: string;
+  /** Service `metadata.kind`, e.g. `figma`. */
+  service: string;
+  tokenEncrypted: string;
+  refreshTokenEncrypted: string | null;
+  /** When the access token expires; null when it never does. */
+  expiresAt: string | null;
+  /** `ok`, or `expired` once a refresh failed and the user must reconnect. */
+  status: string;
+  createdAt: string;
+  updatedAt: string;
+}
+//#endregion
+export { UserConnection };
+//# sourceMappingURL=connection.d.mts.map