@storyshelf/core 0.7.0 → 0.9.0-next-d2cc082

package/dist/models/baseline-approval.d.mts

@@ -0,0 +1,18 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import "../adapter/database.mjs";
+import { Snapshot } from "../schema/snapshot.mjs";
+import { BaselineWriteConflict } from "./baseline-conflict.mjs";
+import { BaselineStatus } from "./baseline-status.mjs";
+interface AtomicBaselineApproval {
+  snapshot: Snapshot;
+  reviewedBy: string | null;
+  force: boolean;
+  branch: string;
+}
+declare class BaselineApprovalConflict extends BaselineWriteConflict {
+  readonly driftStatus?: BaselineStatus;
+  constructor(message: string, driftStatus?: BaselineStatus);
+}
+export { AtomicBaselineApproval, BaselineApprovalConflict };
+//# sourceMappingURL=baseline-approval.d.mts.map

package/dist/models/baseline-approval.mjs

@@ -0,0 +1,41 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { col } from "./columns.mjs";
+import { BaselineWriteConflict } from "./baseline-conflict.mjs";
+import { baselineStatus, isBaselineDrifted } from "./baseline-status.mjs";
+import { and, eq } from "drizzle-orm";
+// src/models/baseline-approval.ts
+/** Review checks and decision persisted inside the baseline/reference transaction. */
+var BaselineApprovalConflict = class extends BaselineWriteConflict {
+	driftStatus;
+	constructor(message, driftStatus) {
+		super(message);
+		this.driftStatus = driftStatus;
+	}
+};
+async function approveInTransaction(tx, tables, input) {
+	const snapshot = await tx.get(tables.snapshots, input.snapshot.id);
+	if (!snapshot || snapshot.projectId !== input.snapshot.projectId || snapshot.buildId !== input.snapshot.buildId || snapshot.status !== input.snapshot.status || snapshot.updatedAt !== input.snapshot.updatedAt || snapshot.screenshotPath !== input.snapshot.screenshotPath || snapshot.baselineId !== input.snapshot.baselineId || snapshot.baselineVersion !== input.snapshot.baselineVersion) throw new BaselineApprovalConflict("Snapshot changed during approval; reload and retry");
+	const build = await tx.get(tables.builds, snapshot.buildId);
+	const project = await tx.get(tables.projects, snapshot.projectId);
+	if (!build || !project || build.projectId !== project.id || build.status === "cancelled" || build.gitBranch !== input.branch) throw new BaselineApprovalConflict("Build is unavailable for approval");
+	const current = await baselineFor(tx, tables, snapshot, build.gitBranch) ?? (build.gitBranch === project.gitDefaultBranch ? null : await baselineFor(tx, tables, snapshot, project.gitDefaultBranch));
+	const status = baselineStatus(snapshot, current);
+	if ((snapshot.status === "new" || snapshot.status === "changed") && isBaselineDrifted(status) && !input.force) throw new BaselineApprovalConflict("Baseline changed after this diff was computed", status);
+	await tx.update(tables.snapshots, snapshot.id, {
+		status: "approved",
+		reviewedBy: input.reviewedBy,
+		reviewedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+async function baselineFor(tx, tables, snapshot, branch) {
+	return (await tx.list(tables.baselines, {
+		where: and(eq(col(tables.baselines, "projectId"), snapshot.projectId), eq(col(tables.baselines, "storyId"), snapshot.storyId), eq(col(tables.baselines, "viewportName"), snapshot.viewportName), eq(col(tables.baselines, "browser"), snapshot.browser ?? "chromium"), eq(col(tables.baselines, "branch"), branch)),
+		limit: 1
+	}))[0] ?? null;
+}
+export { BaselineApprovalConflict, approveInTransaction };
+
+//# sourceMappingURL=baseline-approval.mjs.map

package/dist/models/baseline-approval.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-approval.mjs","names":[],"sources":["../../src/models/baseline-approval.ts"],"sourcesContent":["/** Review checks and decision persisted inside the baseline/reference transaction. */\nimport { and, eq } from \"drizzle-orm\";\nimport type { Tables, TxStore } from \"../adapters/database.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { Snapshot } from \"../schema/snapshot.ts\";\nimport { BaselineWriteConflict } from \"./baseline-conflict.ts\";\nimport { baselineStatus, isBaselineDrifted, type BaselineStatus } from \"./baseline-status.ts\";\nimport { col } from \"./columns.ts\";\n\nexport interface AtomicBaselineApproval {\n  snapshot: Snapshot;\n  reviewedBy: string | null;\n  force: boolean;\n  branch: string;\n}\nexport class BaselineApprovalConflict extends BaselineWriteConflict {\n  readonly driftStatus?: BaselineStatus;\n  constructor(message: string, driftStatus?: BaselineStatus) {\n    super(message);\n    this.driftStatus = driftStatus;\n  }\n}\n\nexport async function approveInTransaction(\n  tx: TxStore,\n  tables: Tables,\n  input: AtomicBaselineApproval,\n): Promise<void> {\n  const snapshot = (await tx.get(\n    tables.snapshots,\n    input.snapshot.id,\n  )) as unknown as Snapshot | null;\n  if (\n    !snapshot ||\n    snapshot.projectId !== input.snapshot.projectId ||\n    snapshot.buildId !== input.snapshot.buildId ||\n    snapshot.status !== input.snapshot.status ||\n    snapshot.updatedAt !== input.snapshot.updatedAt ||\n    snapshot.screenshotPath !== input.snapshot.screenshotPath ||\n    snapshot.baselineId !== input.snapshot.baselineId ||\n    snapshot.baselineVersion !== input.snapshot.baselineVersion\n  )\n    throw new BaselineApprovalConflict(\"Snapshot changed during approval; reload and retry\");\n  const build = (await tx.get(tables.builds, snapshot.buildId)) as unknown as Build | null;\n  const project = (await tx.get(tables.projects, snapshot.projectId)) as unknown as Project | null;\n  if (\n    !build ||\n    !project ||\n    build.projectId !== project.id ||\n    build.status === \"cancelled\" ||\n    build.gitBranch !== input.branch\n  )\n    throw new BaselineApprovalConflict(\"Build is unavailable for approval\");\n  const own = await baselineFor(tx, tables, snapshot, build.gitBranch);\n  const current =\n    own ??\n    (build.gitBranch === project.gitDefaultBranch\n      ? null\n      : await baselineFor(tx, tables, snapshot, project.gitDefaultBranch));\n  const status = baselineStatus(snapshot, current);\n  if (\n    (snapshot.status === \"new\" || snapshot.status === \"changed\") &&\n    isBaselineDrifted(status) &&\n    !input.force\n  )\n    throw new BaselineApprovalConflict(\"Baseline changed after this diff was computed\", status);\n  await tx.update(tables.snapshots, snapshot.id, {\n    status: \"approved\",\n    reviewedBy: input.reviewedBy,\n    reviewedAt: new Date().toISOString(),\n    updatedAt: new Date().toISOString(),\n  });\n}\n\nasync function baselineFor(\n  tx: TxStore,\n  tables: Tables,\n  snapshot: Snapshot,\n  branch: string,\n): Promise<Baseline | null> {\n  const rows = await tx.list(tables.baselines, {\n    where: and(\n      eq(col(tables.baselines, \"projectId\"), snapshot.projectId),\n      eq(col(tables.baselines, \"storyId\"), snapshot.storyId),\n      eq(col(tables.baselines, \"viewportName\"), snapshot.viewportName),\n      eq(col(tables.baselines, \"browser\"), snapshot.browser ?? \"chromium\"),\n      eq(col(tables.baselines, \"branch\"), branch),\n    ),\n    limit: 1,\n  });\n  return (rows[0] as unknown as Baseline | undefined) ?? null;\n}\n"],"mappings":";;;;;;;;;AAiBA,IAAa,2BAAb,cAA8C,sBAAsB;CAClE;CACA,YAAY,SAAiB,aAA8B;EACzD,MAAM,OAAO;EACb,KAAK,cAAc;CACrB;AACF;AAEA,eAAsB,qBACpB,IACA,QACA,OACe;CACf,MAAM,WAAY,MAAM,GAAG,IACzB,OAAO,WACP,MAAM,SAAS,EACjB;CACA,IACE,CAAC,YACD,SAAS,cAAc,MAAM,SAAS,aACtC,SAAS,YAAY,MAAM,SAAS,WACpC,SAAS,WAAW,MAAM,SAAS,UACnC,SAAS,cAAc,MAAM,SAAS,aACtC,SAAS,mBAAmB,MAAM,SAAS,kBAC3C,SAAS,eAAe,MAAM,SAAS,cACvC,SAAS,oBAAoB,MAAM,SAAS,iBAE5C,MAAM,IAAI,yBAAyB,oDAAoD;CACzF,MAAM,QAAS,MAAM,GAAG,IAAI,OAAO,QAAQ,SAAS,OAAO;CAC3D,MAAM,UAAW,MAAM,GAAG,IAAI,OAAO,UAAU,SAAS,SAAS;CACjE,IACE,CAAC,SACD,CAAC,WACD,MAAM,cAAc,QAAQ,MAC5B,MAAM,WAAW,eACjB,MAAM,cAAc,MAAM,QAE1B,MAAM,IAAI,yBAAyB,mCAAmC;CAExE,MAAM,UACJ,MAFgB,YAAY,IAAI,QAAQ,UAAU,MAAM,SAAS,MAGhE,MAAM,cAAc,QAAQ,mBACzB,OACA,MAAM,YAAY,IAAI,QAAQ,UAAU,QAAQ,gBAAgB;CACtE,MAAM,SAAS,eAAe,UAAU,OAAO;CAC/C,KACG,SAAS,WAAW,SAAS,SAAS,WAAW,cAClD,kBAAkB,MAAM,KACxB,CAAC,MAAM,OAEP,MAAM,IAAI,yBAAyB,iDAAiD,MAAM;CAC5F,MAAM,GAAG,OAAO,OAAO,WAAW,SAAS,IAAI;EAC7C,QAAQ;EACR,YAAY,MAAM;EAClB,6BAAY,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;CACpC,CAAC;AACH;AAEA,eAAe,YACb,IACA,QACA,UACA,QAC0B;CAW1B,QAAQ,MAVW,GAAG,KAAK,OAAO,WAAW;EAC3C,OAAO,IACL,GAAG,IAAI,OAAO,WAAW,WAAW,GAAG,SAAS,SAAS,GACzD,GAAG,IAAI,OAAO,WAAW,SAAS,GAAG,SAAS,OAAO,GACrD,GAAG,IAAI,OAAO,WAAW,cAAc,GAAG,SAAS,YAAY,GAC/D,GAAG,IAAI,OAAO,WAAW,SAAS,GAAG,SAAS,WAAW,UAAU,GACnE,GAAG,IAAI,OAAO,WAAW,QAAQ,GAAG,MAAM,CAC5C;EACA,OAAO;CACT,CAAC,EAAA,CACY,MAA0C;AACzD"}

package/dist/models/baseline-archive.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { z } from "zod";
-//#region src/models/baseline-archive.d.ts
 /** Identifies a StoryShelf baseline archive. */
 declare const BASELINE_ARCHIVE_FORMAT = "storyshelf-baselines";
 /** Current archive format version. */
@@ -79,6 +78,5 @@ type BaselineSkipped = z.infer<typeof baselineSkippedSchema>;
 declare class BaselineArchiveError extends Error {
   readonly name = "BaselineArchiveError";
 }
-//#endregion
 export { BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_ARCHIVE_VERSION, BaselineArchiveError, BaselineManifest, BaselineManifestEntry, BaselineSkipped, baselineManifestEntrySchema, baselineManifestSchema, baselineSkippedSchema };
 //# sourceMappingURL=baseline-archive.d.mts.map

package/dist/models/baseline-archive.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { modeSegment } from "../paths.mjs";
 import { z } from "zod";
-//#region src/models/baseline-archive.ts
+// src/models/baseline-archive.ts
 /**
 * Baseline archive format (v1): a zip holding `manifest.json` plus one PNG per
 * baseline at `baselines/<branch>/<storyId>/<mode>.png` — the storage layout
@@ -100,7 +100,6 @@ const PNG_SIGNATURE = Buffer.from([
 function isPng(data) {
 	return data.length >= PNG_SIGNATURE.length && data.subarray(0, 8).equals(PNG_SIGNATURE);
 }
-//#endregion
 export { BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_ARCHIVE_VERSION, BASELINE_MANIFEST_NAME, BaselineArchiveError, archiveFileName, baselineIdentity, baselineManifestEntrySchema, baselineManifestSchema, baselineSkippedSchema, isPng };
 
 //# sourceMappingURL=baseline-archive.mjs.map

package/dist/models/baseline-atomic.mjs

@@ -0,0 +1,66 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../adapters/capture-target.mjs";
+import { col } from "./columns.mjs";
+import { BaselineWriteConflict } from "./baseline-conflict.mjs";
+import { and, eq } from "drizzle-orm";
+// src/models/baseline-atomic.ts
+/** Transactional baseline mutation for adapters with explicit reference lifecycle support. */
+/** Atomically change the baseline row and its complete build-reference set. */
+async function upsertAtomicBaseline(lifecycle, tables, input) {
+	const owner = {
+		projectId: input.projectId,
+		type: "baseline",
+		id: input.id
+	};
+	const generation = await lifecycle.referenceGeneration(owner);
+	return (await lifecycle.replaceFencedReferences(owner, generation, input.sourceBuildId ? [input.sourceBuildId] : [], async (tx) => {
+		await input.beforeWrite?.(tx);
+		return await writeBaseline(tx, tables, input);
+	})).result;
+}
+async function writeBaseline(tx, tables, input) {
+	const existing = (await tx.list(tables.baselines, {
+		where: and(eq(col(tables.baselines, "projectId"), input.projectId), eq(col(tables.baselines, "storyId"), input.storyId), eq(col(tables.baselines, "viewportName"), input.viewport), eq(col(tables.baselines, "branch"), input.branch), eq(col(tables.baselines, "browser"), input.browser)),
+		limit: 1
+	}))[0] ?? null;
+	assertBaselineUnchanged(existing, input);
+	if (input.sourceBuildId) await assertSource(tx, tables.snapshots, input);
+	const now = nextBaselineVersion(existing?.updatedAt ?? null, /* @__PURE__ */ new Date());
+	const fields = {
+		snapshotId: input.snapshotId,
+		sourceBuildId: input.sourceBuildId,
+		screenshotPath: input.screenshotPath,
+		infraHash: input.infraHash ?? existing?.infraHash ?? null,
+		fingerprint: input.fingerprint ?? existing?.fingerprint ?? null,
+		mode: input.mode ?? existing?.mode ?? null,
+		updatedAt: now
+	};
+	return existing ? await tx.update(tables.baselines, existing.id, fields) : await tx.insert(tables.baselines, {
+		...fields,
+		id: input.id,
+		projectId: input.projectId,
+		storyId: input.storyId,
+		viewportName: input.viewport,
+		branch: input.branch,
+		browser: input.browser,
+		createdAt: now
+	});
+}
+function assertBaselineUnchanged(existing, input) {
+	if ((existing?.id ?? null) !== input.existingId || (existing?.updatedAt ?? null) !== input.existingVersion) throw new BaselineWriteConflict("Baseline changed during promotion; retry");
+}
+/** Keep the version advancing even when updates share a millisecond or clocks move backwards. */
+function nextBaselineVersion(previous, now) {
+	const last = previous === null ? NaN : Date.parse(previous);
+	return new Date(Number.isFinite(last) ? Math.max(now.getTime(), last + 1) : now.getTime()).toISOString();
+}
+async function assertSource(tx, table, input) {
+	const row = await tx.get(table, input.snapshotId);
+	const origin = row?.inherited ? row.sourceBuildId : row?.buildId;
+	if (!row || row.projectId !== input.projectId || row.storyId !== input.storyId || row.viewportName !== input.viewport || (row.browser ?? "chromium") !== input.browser || row.screenshotPath !== input.originalPath || origin !== input.sourceBuildId) throw new BaselineWriteConflict("Source snapshot changed during promotion; retry");
+}
+export { nextBaselineVersion, upsertAtomicBaseline };
+
+//# sourceMappingURL=baseline-atomic.mjs.map

package/dist/models/baseline-atomic.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-atomic.mjs","names":[],"sources":["../../src/models/baseline-atomic.ts"],"sourcesContent":["/** Transactional baseline mutation for adapters with explicit reference lifecycle support. */\nimport { and, eq } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { BuildReferenceLifecycle, TxStore } from \"../adapters/database.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport type { Snapshot } from \"../schema/snapshot.ts\";\nimport { BaselineWriteConflict } from \"./baseline-conflict.ts\";\nimport { col } from \"./columns.ts\";\n\nexport interface AtomicBaselineInput {\n  id: string;\n  existingId: string | null;\n  existingVersion: string | null;\n  projectId: string;\n  storyId: string;\n  viewport: string;\n  branch: string;\n  browser: string;\n  snapshotId: string;\n  sourceBuildId: string | null;\n  originalPath: string;\n  screenshotPath: string;\n  infraHash: string | null | undefined;\n  fingerprint: string | null | undefined;\n  mode: string | null | undefined;\n  beforeWrite?: (tx: TxStore) => Promise<void>;\n}\n\n/** Atomically change the baseline row and its complete build-reference set. */\nexport async function upsertAtomicBaseline(\n  lifecycle: BuildReferenceLifecycle,\n  tables: { baselines: Table; snapshots: Table },\n  input: AtomicBaselineInput,\n): Promise<Baseline> {\n  const owner = { projectId: input.projectId, type: \"baseline\" as const, id: input.id };\n  const generation = await lifecycle.referenceGeneration(owner);\n  const updated = await lifecycle.replaceFencedReferences(\n    owner,\n    generation,\n    input.sourceBuildId ? [input.sourceBuildId] : [],\n    async (tx) => {\n      await input.beforeWrite?.(tx);\n      return await writeBaseline(tx, tables, input);\n    },\n  );\n  return updated.result;\n}\n\nasync function writeBaseline(\n  tx: TxStore,\n  tables: { baselines: Table; snapshots: Table },\n  input: AtomicBaselineInput,\n): Promise<Baseline> {\n  const rows = (await tx.list(tables.baselines, {\n    where: and(\n      eq(col(tables.baselines, \"projectId\"), input.projectId),\n      eq(col(tables.baselines, \"storyId\"), input.storyId),\n      eq(col(tables.baselines, \"viewportName\"), input.viewport),\n      eq(col(tables.baselines, \"branch\"), input.branch),\n      eq(col(tables.baselines, \"browser\"), input.browser),\n    ),\n    limit: 1,\n  })) as unknown as Baseline[];\n  const existing = rows[0] ?? null;\n  assertBaselineUnchanged(existing, input);\n  if (input.sourceBuildId) await assertSource(tx, tables.snapshots, input);\n  const now = nextBaselineVersion(existing?.updatedAt ?? null, new Date());\n  const fields = {\n    snapshotId: input.snapshotId,\n    sourceBuildId: input.sourceBuildId,\n    screenshotPath: input.screenshotPath,\n    infraHash: input.infraHash ?? existing?.infraHash ?? null,\n    fingerprint: input.fingerprint ?? existing?.fingerprint ?? null,\n    mode: input.mode ?? existing?.mode ?? null,\n    updatedAt: now,\n  };\n  return (existing\n    ? await tx.update(tables.baselines, existing.id, fields)\n    : await tx.insert(tables.baselines, {\n        ...fields,\n        id: input.id,\n        projectId: input.projectId,\n        storyId: input.storyId,\n        viewportName: input.viewport,\n        branch: input.branch,\n        browser: input.browser,\n        createdAt: now,\n      })) as unknown as Baseline;\n}\n\nfunction assertBaselineUnchanged(existing: Baseline | null, input: AtomicBaselineInput): void {\n  if (\n    (existing?.id ?? null) !== input.existingId ||\n    (existing?.updatedAt ?? null) !== input.existingVersion\n  )\n    throw new BaselineWriteConflict(\"Baseline changed during promotion; retry\");\n}\n\n/** Keep the version advancing even when updates share a millisecond or clocks move backwards. */\nexport function nextBaselineVersion(previous: string | null, now: Date): string {\n  const last = previous === null ? Number.NaN : Date.parse(previous);\n  return new Date(\n    Number.isFinite(last) ? Math.max(now.getTime(), last + 1) : now.getTime(),\n  ).toISOString();\n}\n\nasync function assertSource(tx: TxStore, table: Table, input: AtomicBaselineInput): Promise<void> {\n  const row = (await tx.get(table, input.snapshotId)) as unknown as Snapshot | null;\n  const origin = row?.inherited ? row.sourceBuildId : row?.buildId;\n  if (\n    !row ||\n    row.projectId !== input.projectId ||\n    row.storyId !== input.storyId ||\n    row.viewportName !== input.viewport ||\n    (row.browser ?? DEFAULT_BROWSER) !== input.browser ||\n    row.screenshotPath !== input.originalPath ||\n    origin !== input.sourceBuildId\n  ) {\n    throw new BaselineWriteConflict(\"Source snapshot changed during promotion; retry\");\n  }\n}\n"],"mappings":";;;;;;;;;;AA8BA,eAAsB,qBACpB,WACA,QACA,OACmB;CACnB,MAAM,QAAQ;EAAE,WAAW,MAAM;EAAW,MAAM;EAAqB,IAAI,MAAM;CAAG;CACpF,MAAM,aAAa,MAAM,UAAU,oBAAoB,KAAK;CAU5D,QAAO,MATe,UAAU,wBAC9B,OACA,YACA,MAAM,gBAAgB,CAAC,MAAM,aAAa,IAAI,CAAC,GAC/C,OAAO,OAAO;EACZ,MAAM,MAAM,cAAc,EAAE;EAC5B,OAAO,MAAM,cAAc,IAAI,QAAQ,KAAK;CAC9C,CACF,EAAA,CACe;AACjB;AAEA,eAAe,cACb,IACA,QACA,OACmB;CAWnB,MAAM,YAAW,MAVG,GAAG,KAAK,OAAO,WAAW;EAC5C,OAAO,IACL,GAAG,IAAI,OAAO,WAAW,WAAW,GAAG,MAAM,SAAS,GACtD,GAAG,IAAI,OAAO,WAAW,SAAS,GAAG,MAAM,OAAO,GAClD,GAAG,IAAI,OAAO,WAAW,cAAc,GAAG,MAAM,QAAQ,GACxD,GAAG,IAAI,OAAO,WAAW,QAAQ,GAAG,MAAM,MAAM,GAChD,GAAG,IAAI,OAAO,WAAW,SAAS,GAAG,MAAM,OAAO,CACpD;EACA,OAAO;CACT,CAAC,EAAA,CACqB,MAAM;CAC5B,wBAAwB,UAAU,KAAK;CACvC,IAAI,MAAM,eAAe,MAAM,aAAa,IAAI,OAAO,WAAW,KAAK;CACvE,MAAM,MAAM,oBAAoB,UAAU,aAAa,sBAAM,IAAI,KAAK,CAAC;CACvE,MAAM,SAAS;EACb,YAAY,MAAM;EAClB,eAAe,MAAM;EACrB,gBAAgB,MAAM;EACtB,WAAW,MAAM,aAAa,UAAU,aAAa;EACrD,aAAa,MAAM,eAAe,UAAU,eAAe;EAC3D,MAAM,MAAM,QAAQ,UAAU,QAAQ;EACtC,WAAW;CACb;CACA,OAAQ,WACJ,MAAM,GAAG,OAAO,OAAO,WAAW,SAAS,IAAI,MAAM,IACrD,MAAM,GAAG,OAAO,OAAO,WAAW;EAChC,GAAG;EACH,IAAI,MAAM;EACV,WAAW,MAAM;EACjB,SAAS,MAAM;EACf,cAAc,MAAM;EACpB,QAAQ,MAAM;EACd,SAAS,MAAM;EACf,WAAW;CACb,CAAC;AACP;AAEA,SAAS,wBAAwB,UAA2B,OAAkC;CAC5F,KACG,UAAU,MAAM,UAAU,MAAM,eAChC,UAAU,aAAa,UAAU,MAAM,iBAExC,MAAM,IAAI,sBAAsB,0CAA0C;AAC9E;;AAGA,SAAgB,oBAAoB,UAAyB,KAAmB;CAC9E,MAAM,OAAO,aAAa,OAAO,MAAa,KAAK,MAAM,QAAQ;CACjE,OAAO,IAAI,KACT,OAAO,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,CAC1E,CAAC,CAAC,YAAY;AAChB;AAEA,eAAe,aAAa,IAAa,OAAc,OAA2C;CAChG,MAAM,MAAO,MAAM,GAAG,IAAI,OAAO,MAAM,UAAU;CACjD,MAAM,SAAS,KAAK,YAAY,IAAI,gBAAgB,KAAK;CACzD,IACE,CAAC,OACD,IAAI,cAAc,MAAM,aACxB,IAAI,YAAY,MAAM,WACtB,IAAI,iBAAiB,MAAM,aAC1B,IAAI,WAAA,gBAAgC,MAAM,WAC3C,IAAI,mBAAmB,MAAM,gBAC7B,WAAW,MAAM,eAEjB,MAAM,IAAI,sBAAsB,iDAAiD;AAErF"}

package/dist/models/baseline-conflict.d.mts

@@ -0,0 +1,6 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** A baseline write lost a concurrency check and should be retried. */
+declare class BaselineWriteConflict extends Error {}
+export { BaselineWriteConflict };
+//# sourceMappingURL=baseline-conflict.d.mts.map

package/dist/models/baseline-conflict.mjs

@@ -0,0 +1,9 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/models/baseline-conflict.ts
+/** A baseline write lost a concurrency check and should be retried. */
+var BaselineWriteConflict = class extends Error {};
+export { BaselineWriteConflict };
+
+//# sourceMappingURL=baseline-conflict.mjs.map

package/dist/models/baseline-conflict.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-conflict.mjs","names":[],"sources":["../../src/models/baseline-conflict.ts"],"sourcesContent":["/** A baseline write lost a concurrency check and should be retried. */\nexport class BaselineWriteConflict extends Error {}\n"],"mappings":";;;;;AACA,IAAa,wBAAb,cAA2C,MAAM,CAAC"}

package/dist/models/baseline-export.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import "../adapter/storage.mjs";
 import { BaselineSkipped } from "./baseline-archive.mjs";
-//#region src/models/baseline-export.d.ts
 /** Options for {@link exportBaselineArchive}. */
 interface BaselineExportOptions {
   /** Export only this branch; omit (or null) for every branch. */
@@ -14,6 +13,5 @@ interface BaselineExportOptions {
   /** Clock override for `exportedAt` (tests). */
   now?: () => Date;
 }
-//#endregion
 export { BaselineExportOptions };
 //# sourceMappingURL=baseline-export.d.mts.map

package/dist/models/baseline-export.mjs

@@ -5,7 +5,7 @@ import "../adapters/capture-target.mjs";
 import { BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_MANIFEST_NAME, BaselineArchiveError, archiveFileName } from "./baseline-archive.mjs";
 import { zipStream } from "../utils/zip-write.mjs";
 import { createHash } from "node:crypto";
-//#region src/models/baseline-export.ts
+// src/models/baseline-export.ts
 /** Stream a project's baselines as a portable zip archive (format v1). */
 /**
 * Prepare a baseline archive for `rows`. Validation (the entry limit) runs
@@ -130,7 +130,6 @@ function uniqueName(name, names) {
 	names.add(candidate);
 	return candidate;
 }
-//#endregion
 export { exportBaselineArchive };
 
 //# sourceMappingURL=baseline-export.mjs.map

package/dist/models/baseline-import.mjs

@@ -6,7 +6,7 @@ import { BASELINE_ARCHIVE_LIMITS, BASELINE_MANIFEST_NAME, BaselineArchiveError,
 import { ZipFormatError, readZip } from "../utils/zip-read.mjs";
 import { createHash } from "node:crypto";
 import { setImmediate } from "node:timers/promises";
-//#region src/models/baseline-import.ts
+// src/models/baseline-import.ts
 /**
 * Validate and apply a baseline archive (format v1).
 *
@@ -112,7 +112,6 @@ function readEntry(zipEntry) {
 		throw error;
 	}
 }
-//#endregion
 export { planBaselineImport, writePlannedImage };
 
 //# sourceMappingURL=baseline-import.mjs.map

package/dist/models/baseline-origin.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Build } from "../schema/build.mjs";
+import { Baseline } from "../schema/baseline.mjs";
+import { Snapshot } from "../schema/snapshot.mjs";
+import "../schema.mjs";
+/** The records needed to prove which build rendered a baseline image. */
+interface BaselineOriginReader {
+  baseline(id: string): Promise<Baseline | null>;
+  snapshot(id: string): Promise<Snapshot | null>;
+  build(id: string): Promise<Build | null>;
+}
+/** A proven source, or null when the recorded history is incomplete or has changed. */
+declare function resolveBaselineOrigin(baseline: Baseline, reader: BaselineOriginReader): Promise<Build | null>;
+export { BaselineOriginReader, resolveBaselineOrigin };
+//# sourceMappingURL=baseline-origin.d.mts.map

package/dist/models/baseline-origin.mjs

@@ -0,0 +1,35 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../adapters/capture-target.mjs";
+// src/models/baseline-origin.ts
+/** A proven source, or null when the recorded history is incomplete or has changed. */
+async function resolveBaselineOrigin(baseline, reader) {
+	return await traceOrigin(baseline, baseline.projectId, reader, /* @__PURE__ */ new Set());
+}
+async function traceOrigin(current, projectId, reader, seen) {
+	if (current.sourceBuildId) return await verifiedBuild(current.sourceBuildId, projectId, reader);
+	if (seen.size >= 32 || seen.has(current.id) || !current.snapshotId) return null;
+	seen.add(current.id);
+	const snapshot = await reader.snapshot(current.snapshotId);
+	if (!snapshot || !matchesImage(current, snapshot)) return null;
+	if (!snapshot.inherited) return await verifiedBuild(snapshot.buildId, projectId, reader);
+	return await traceInherited(snapshot, projectId, reader, seen);
+}
+async function traceInherited(snapshot, projectId, reader, seen) {
+	if (snapshot.sourceBuildId) return await verifiedBuild(snapshot.sourceBuildId, projectId, reader);
+	if (!snapshot.baselineId || !snapshot.baselineVersion) return null;
+	const parent = await reader.baseline(snapshot.baselineId);
+	if (!parent || parent.updatedAt !== snapshot.baselineVersion || !matchesImage(parent, snapshot)) return null;
+	return await traceOrigin(parent, projectId, reader, seen);
+}
+function matchesImage(baseline, snapshot) {
+	return baseline.projectId === snapshot.projectId && baseline.storyId === snapshot.storyId && baseline.viewportName === snapshot.viewportName && (baseline.browser ?? "chromium") === (snapshot.browser ?? "chromium") && baseline.screenshotPath === snapshot.screenshotPath;
+}
+async function verifiedBuild(buildId, projectId, reader) {
+	const build = await reader.build(buildId);
+	return build?.projectId === projectId ? build : null;
+}
+export { resolveBaselineOrigin };
+
+//# sourceMappingURL=baseline-origin.mjs.map

package/dist/models/baseline-origin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-origin.mjs","names":[],"sources":["../../src/models/baseline-origin.ts"],"sourcesContent":["import { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { Baseline, Build, Snapshot } from \"../schema/index.ts\";\n\n/** The records needed to prove which build rendered a baseline image. */\nexport interface BaselineOriginReader {\n  baseline(id: string): Promise<Baseline | null>;\n  snapshot(id: string): Promise<Snapshot | null>;\n  build(id: string): Promise<Build | null>;\n}\n\n/** A proven source, or null when the recorded history is incomplete or has changed. */\nexport async function resolveBaselineOrigin(\n  baseline: Baseline,\n  reader: BaselineOriginReader,\n): Promise<Build | null> {\n  return await traceOrigin(baseline, baseline.projectId, reader, new Set());\n}\n\nasync function traceOrigin(\n  current: Baseline,\n  projectId: string,\n  reader: BaselineOriginReader,\n  seen: Set<string>,\n): Promise<Build | null> {\n  if (current.sourceBuildId) return await verifiedBuild(current.sourceBuildId, projectId, reader);\n  if (seen.size >= 32 || seen.has(current.id) || !current.snapshotId) return null;\n  seen.add(current.id);\n  const snapshot = await reader.snapshot(current.snapshotId);\n  if (!snapshot || !matchesImage(current, snapshot)) return null;\n  if (!snapshot.inherited) return await verifiedBuild(snapshot.buildId, projectId, reader);\n  return await traceInherited(snapshot, projectId, reader, seen);\n}\n\nasync function traceInherited(\n  snapshot: Snapshot,\n  projectId: string,\n  reader: BaselineOriginReader,\n  seen: Set<string>,\n): Promise<Build | null> {\n  if (snapshot.sourceBuildId) return await verifiedBuild(snapshot.sourceBuildId, projectId, reader);\n  if (!snapshot.baselineId || !snapshot.baselineVersion) return null;\n  const parent = await reader.baseline(snapshot.baselineId);\n  if (!parent || parent.updatedAt !== snapshot.baselineVersion || !matchesImage(parent, snapshot))\n    return null;\n  return await traceOrigin(parent, projectId, reader, seen);\n}\n\nfunction matchesImage(baseline: Baseline, snapshot: Snapshot): boolean {\n  return (\n    baseline.projectId === snapshot.projectId &&\n    baseline.storyId === snapshot.storyId &&\n    baseline.viewportName === snapshot.viewportName &&\n    (baseline.browser ?? DEFAULT_BROWSER) === (snapshot.browser ?? DEFAULT_BROWSER) &&\n    baseline.screenshotPath === snapshot.screenshotPath\n  );\n}\n\nasync function verifiedBuild(\n  buildId: string,\n  projectId: string,\n  reader: BaselineOriginReader,\n): Promise<Build | null> {\n  const build = await reader.build(buildId);\n  return build?.projectId === projectId ? build : null;\n}\n"],"mappings":";;;;;;AAWA,eAAsB,sBACpB,UACA,QACuB;CACvB,OAAO,MAAM,YAAY,UAAU,SAAS,WAAW,wBAAQ,IAAI,IAAI,CAAC;AAC1E;AAEA,eAAe,YACb,SACA,WACA,QACA,MACuB;CACvB,IAAI,QAAQ,eAAe,OAAO,MAAM,cAAc,QAAQ,eAAe,WAAW,MAAM;CAC9F,IAAI,KAAK,QAAQ,MAAM,KAAK,IAAI,QAAQ,EAAE,KAAK,CAAC,QAAQ,YAAY,OAAO;CAC3E,KAAK,IAAI,QAAQ,EAAE;CACnB,MAAM,WAAW,MAAM,OAAO,SAAS,QAAQ,UAAU;CACzD,IAAI,CAAC,YAAY,CAAC,aAAa,SAAS,QAAQ,GAAG,OAAO;CAC1D,IAAI,CAAC,SAAS,WAAW,OAAO,MAAM,cAAc,SAAS,SAAS,WAAW,MAAM;CACvF,OAAO,MAAM,eAAe,UAAU,WAAW,QAAQ,IAAI;AAC/D;AAEA,eAAe,eACb,UACA,WACA,QACA,MACuB;CACvB,IAAI,SAAS,eAAe,OAAO,MAAM,cAAc,SAAS,eAAe,WAAW,MAAM;CAChG,IAAI,CAAC,SAAS,cAAc,CAAC,SAAS,iBAAiB,OAAO;CAC9D,MAAM,SAAS,MAAM,OAAO,SAAS,SAAS,UAAU;CACxD,IAAI,CAAC,UAAU,OAAO,cAAc,SAAS,mBAAmB,CAAC,aAAa,QAAQ,QAAQ,GAC5F,OAAO;CACT,OAAO,MAAM,YAAY,QAAQ,WAAW,QAAQ,IAAI;AAC1D;AAEA,SAAS,aAAa,UAAoB,UAA6B;CACrE,OACE,SAAS,cAAc,SAAS,aAChC,SAAS,YAAY,SAAS,WAC9B,SAAS,iBAAiB,SAAS,iBAClC,SAAS,WAAA,iBAAiC,SAAS,WAAA,eACpD,SAAS,mBAAmB,SAAS;AAEzC;AAEA,eAAe,cACb,SACA,WACA,QACuB;CACvB,MAAM,QAAQ,MAAM,OAAO,MAAM,OAAO;CACxC,OAAO,OAAO,cAAc,YAAY,QAAQ;AAClD"}

package/dist/models/baseline-status.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Baseline } from "../schema/baseline.mjs";
 import { Snapshot } from "../schema/snapshot.mjs";
-//#region src/models/baseline-status.d.ts
 /** `baselineVersion` recorded when a story had no baseline at diff time. */
 declare const NO_BASELINE = "none";
 /**
@@ -24,6 +23,5 @@ type TrackedSnapshot = Pick<Snapshot, "baselineId" | "baselineVersion">;
 declare function baselineStatus(snapshot: TrackedSnapshot, current: Baseline | null): BaselineStatus;
 /** True when approving should be refused until the diff is recomputed (or forced). */
 declare function isBaselineDrifted(status: BaselineStatus): boolean;
-//#endregion
 export { BaselineStatus, NO_BASELINE, baselineStatus, isBaselineDrifted };
 //# sourceMappingURL=baseline-status.d.mts.map

package/dist/models/baseline-status.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/models/baseline-status.ts
+// src/models/baseline-status.ts
 /** `baselineVersion` recorded when a story had no baseline at diff time. */
 const NO_BASELINE = "none";
 /**
@@ -20,7 +20,6 @@ function baselineStatus(snapshot, current) {
 function isBaselineDrifted(status) {
 	return status === "stale" || status === "removed";
 }
-//#endregion
 export { NO_BASELINE, baselineStatus, isBaselineDrifted };
 
 //# sourceMappingURL=baseline-status.mjs.map

package/dist/models/baseline-transfer.d.mts

@@ -4,7 +4,6 @@ import { DatabaseAdapter } from "../adapter/database.mjs";
 import { StorageAdapter } from "../adapter/storage.mjs";
 import { BaselineTables } from "./baseline.mjs";
 import { BaselineExportOptions } from "./baseline-export.mjs";
-//#region src/models/baseline-transfer.d.ts
 /** Outcome of {@link BaselineTransferModel.import}. */
 interface BaselineImportResult {
   /** Baselines in the archive (all applied). */
@@ -41,9 +40,9 @@ declare class BaselineTransferModel {
   private existingByIdentity;
   /** Apply every row, in a transaction when available; returns how many were created. */
   private applyRows;
+  private assertUnchangedIdentities;
   /** Write one planned row; resolves true when it was created. */
   private applyRow;
 }
-//#endregion
 export { BaselineImportResult, BaselineTransferModel };
 //# sourceMappingURL=baseline-transfer.d.mts.map

package/dist/models/baseline-transfer.mjs

@@ -4,11 +4,12 @@ import.meta.url;
 import "../adapters/capture-target.mjs";
 import { ulid } from "../utils/ulid.mjs";
 import { withContentClaim } from "../utils/screenshot-store.mjs";
+import { BaselineWriteConflict } from "./baseline-conflict.mjs";
 import { BaselineModel } from "./baseline.mjs";
 import { baselineIdentity } from "./baseline-archive.mjs";
 import { exportBaselineArchive } from "./baseline-export.mjs";
 import { planBaselineImport, writePlannedImage } from "./baseline-import.mjs";
-//#region src/models/baseline-transfer.ts
+// src/models/baseline-transfer.ts
 /**
 * Baseline portability: export a project's baselines as a zip archive and
 * import (upsert) them from the same format. Format and limits live in
@@ -73,13 +74,41 @@ var BaselineTransferModel = class {
 			for (const planned of plan) created += await this.applyRow(store, projectId, planned, existing) ? 1 : 0;
 			return created;
 		};
+		const lifecycle = this.db.buildReferenceLifecycle;
+		if (lifecycle) {
+			const touched = plan.map((planned) => existing.get(baselineIdentity(planned.entry))).filter((row) => row !== void 0);
+			const changes = await Promise.all(touched.map(async (row) => {
+				const owner = {
+					type: "baseline",
+					id: row.id,
+					projectId
+				};
+				return {
+					owner,
+					expectedGeneration: await lifecycle.referenceGeneration(owner),
+					buildIds: []
+				};
+			}));
+			return (await lifecycle.replaceManyFencedReferences(changes, async (store) => {
+				await this.assertUnchangedIdentities(store, touched);
+				return await run(store);
+			})).result;
+		}
 		return this.db.transact ? await this.db.transact(run) : await run(this.db);
 	}
+	async assertUnchangedIdentities(store, rows) {
+		const current = await Promise.all(rows.map(async (row) => await store.get(this.tables.baselines, row.id)));
+		for (const [index, row] of rows.entries()) {
+			const found = current[index];
+			if (!found || found.projectId !== row.projectId || found.storyId !== row.storyId || found.viewportName !== row.viewportName || found.branch !== row.branch || found.updatedAt !== row.updatedAt || found.snapshotId !== row.snapshotId || found.sourceBuildId !== row.sourceBuildId || found.screenshotPath !== row.screenshotPath || (found.browser ?? "chromium") !== (row.browser ?? "chromium")) throw new BaselineWriteConflict("Baseline changed during import; retry");
+		}
+	}
 	/** Write one planned row; resolves true when it was created. */
 	async applyRow(store, projectId, planned, existing) {
 		const { entry, storagePath } = planned;
 		const fields = {
 			snapshotId: null,
+			sourceBuildId: null,
 			screenshotPath: storagePath,
 			infraHash: entry.infraHash,
 			fingerprint: entry.fingerprint ?? null,
@@ -115,7 +144,6 @@ async function serialized(key, task) {
 		if (importQueues.get(key) === run) importQueues.delete(key);
 	}
 }
-//#endregion
 export { BaselineTransferModel };
 
 //# sourceMappingURL=baseline-transfer.mjs.map

package/dist/models/baseline-transfer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"baseline-transfer.mjs","names":[],"sources":["../../src/models/baseline-transfer.ts"],"sourcesContent":["/**\n * Baseline portability: export a project's baselines as a zip archive and\n * import (upsert) them from the same format. Format and limits live in\n * `baseline-archive.ts`; see the portability guide in the docs site.\n */\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { DatabaseAdapter, TxStore } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport { withContentClaim } from \"../utils/screenshot-store.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { baselineIdentity } from \"./baseline-archive.ts\";\nimport { exportBaselineArchive, type BaselineExportOptions } from \"./baseline-export.ts\";\nimport { planBaselineImport, writePlannedImage, type PlannedBaseline } from \"./baseline-import.ts\";\nimport { BaselineModel, type BaselineTables } from \"./baseline.ts\";\n\n/** Outcome of {@link BaselineTransferModel.import}. */\nexport interface BaselineImportResult {\n  /** Baselines in the archive (all applied). */\n  imported: number;\n  /** Baselines that did not exist before. */\n  created: number;\n  /** Existing baselines that were overwritten. */\n  updated: number;\n}\n\n/** Export/import of baselines between StoryShelf instances (or for backup). */\nexport class BaselineTransferModel {\n  private readonly tables: BaselineTables;\n  private readonly baselines: BaselineModel;\n  private readonly db: DatabaseAdapter;\n  private readonly storage: StorageAdapter;\n\n  constructor(db: DatabaseAdapter, storage: StorageAdapter, tables?: BaselineTables) {\n    this.db = db;\n    this.storage = storage;\n    this.tables = tables ?? { baselines: db.tables.baselines };\n    this.baselines = new BaselineModel(db, this.tables, storage);\n  }\n\n  /**\n   * Stream the project's baselines (optionally one branch) as a zip archive.\n   *\n   * @throws {BaselineArchiveError} Before streaming, when over the archive entry limit.\n   */\n  async export(\n    projectId: string,\n    options: BaselineExportOptions = {},\n  ): Promise<AsyncIterable<Buffer>> {\n    return exportBaselineArchive(this.storage, await this.baselines.list(projectId), options);\n  }\n\n  /**\n   * Upsert every baseline in `archive` into the project. The whole archive is\n   * validated before anything is written; images are then stored (idempotent,\n   * safe to retry) and all rows are applied in one transaction when the driver\n   * supports it, so a failure leaves the rows untouched. Imports into the same\n   * project run one at a time. Imported rows keep their original timestamps;\n   * `snapshotId` is cleared because snapshots are not portable.\n   *\n   * @throws {BaselineArchiveError} On a malformed, unsafe, or inconsistent archive.\n   */\n  async import(projectId: string, archive: Buffer): Promise<BaselineImportResult> {\n    const plan = await planBaselineImport(archive, projectId);\n    // Images that already exist are reused, not written: claim the project's content so the\n    // screenshot sweep cannot delete one before the rows pointing at it are committed.\n    return await serialized(\n      projectId,\n      async () =>\n        await withContentClaim(this.storage, projectId, async () => {\n          for (const planned of plan) {\n            // oxlint-disable-next-line eslint/no-await-in-loop -- sequential writes bound storage load\n            await writePlannedImage(this.storage, planned);\n          }\n          const existing = await this.existingByIdentity(projectId);\n          const created = await this.applyRows(projectId, plan, existing);\n          return { imported: plan.length, created, updated: plan.length - created };\n        }),\n    );\n  }\n\n  private async existingByIdentity(projectId: string): Promise<Map<string, Baseline>> {\n    const rows = await this.baselines.list(projectId);\n    return new Map(\n      rows.map((row) => [\n        baselineIdentity({\n          storyId: row.storyId,\n          viewport: row.viewportName,\n          browser: row.browser ?? DEFAULT_BROWSER,\n          branch: row.branch,\n        }),\n        row,\n      ]),\n    );\n  }\n\n  /** Apply every row, in a transaction when available; returns how many were created. */\n  private async applyRows(\n    projectId: string,\n    plan: PlannedBaseline[],\n    existing: Map<string, Baseline>,\n  ): Promise<number> {\n    const run = async (store: TxStore): Promise<number> => {\n      let created = 0;\n      for (const planned of plan) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- rows are applied in order within one transaction\n        created += (await this.applyRow(store, projectId, planned, existing)) ? 1 : 0;\n      }\n      return created;\n    };\n    return this.db.transact ? await this.db.transact(run) : await run(this.db);\n  }\n\n  /** Write one planned row; resolves true when it was created. */\n  private async applyRow(\n    store: TxStore,\n    projectId: string,\n    planned: PlannedBaseline,\n    existing: Map<string, Baseline>,\n  ): Promise<boolean> {\n    const { entry, storagePath } = planned;\n    const fields = {\n      snapshotId: null,\n      screenshotPath: storagePath,\n      infraHash: entry.infraHash,\n      fingerprint: entry.fingerprint ?? null,\n      mode: entry.mode,\n      createdAt: entry.createdAt,\n      updatedAt: entry.updatedAt,\n    } satisfies Partial<Baseline>;\n    const current = existing.get(baselineIdentity(entry));\n    if (current) {\n      await store.update(this.tables.baselines, current.id, fields);\n      return false;\n    }\n    await store.insert(this.tables.baselines, {\n      ...fields,\n      id: ulid(),\n      projectId,\n      storyId: entry.storyId,\n      viewportName: entry.viewport,\n      branch: entry.branch,\n      browser: entry.browser,\n    });\n    return true;\n  }\n}\n\nconst importQueues = new Map<string, Promise<unknown>>();\n\n/** Run `task` after earlier work for the same key settles (in-process serialization). */\nasync function serialized<T>(key: string, task: () => Promise<T>): Promise<T> {\n  const run = (importQueues.get(key) ?? Promise.resolve()).then(task, task);\n  importQueues.set(key, run);\n  try {\n    return await run;\n  } finally {\n    if (importQueues.get(key) === run) {\n      importQueues.delete(key);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA2BA,IAAa,wBAAb,MAAmC;CACjC;CACA;CACA;CACA;CAEA,YAAY,IAAqB,SAAyB,QAAyB;EACjF,KAAK,KAAK;EACV,KAAK,UAAU;EACf,KAAK,SAAS,UAAU,EAAE,WAAW,GAAG,OAAO,UAAU;EACzD,KAAK,YAAY,IAAI,cAAc,IAAI,KAAK,QAAQ,OAAO;CAC7D;;;;;;CAOA,MAAM,OACJ,WACA,UAAiC,CAAC,GACF;EAChC,OAAO,sBAAsB,KAAK,SAAS,MAAM,KAAK,UAAU,KAAK,SAAS,GAAG,OAAO;CAC1F;;;;;;;;;;;CAYA,MAAM,OAAO,WAAmB,SAAgD;EAC9E,MAAM,OAAO,MAAM,mBAAmB,SAAS,SAAS;EAGxD,OAAO,MAAM,WACX,WACA,YACE,MAAM,iBAAiB,KAAK,SAAS,WAAW,YAAY;GAC1D,KAAK,MAAM,WAAW,MAEpB,MAAM,kBAAkB,KAAK,SAAS,OAAO;GAE/C,MAAM,WAAW,MAAM,KAAK,mBAAmB,SAAS;GACxD,MAAM,UAAU,MAAM,KAAK,UAAU,WAAW,MAAM,QAAQ;GAC9D,OAAO;IAAE,UAAU,KAAK;IAAQ;IAAS,SAAS,KAAK,SAAS;GAAQ;EAC1E,CAAC,CACL;CACF;CAEA,MAAc,mBAAmB,WAAmD;EAClF,MAAM,OAAO,MAAM,KAAK,UAAU,KAAK,SAAS;EAChD,OAAO,IAAI,IACT,KAAK,KAAK,QAAQ,CAChB,iBAAiB;GACf,SAAS,IAAI;GACb,UAAU,IAAI;GACd,SAAS,IAAI,WAAA;GACb,QAAQ,IAAI;EACd,CAAC,GACD,GACF,CAAC,CACH;CACF;;CAGA,MAAc,UACZ,WACA,MACA,UACiB;EACjB,MAAM,MAAM,OAAO,UAAoC;GACrD,IAAI,UAAU;GACd,KAAK,MAAM,WAAW,MAEpB,WAAY,MAAM,KAAK,SAAS,OAAO,WAAW,SAAS,QAAQ,IAAK,IAAI;GAE9E,OAAO;EACT;EACA,OAAO,KAAK,GAAG,WAAW,MAAM,KAAK,GAAG,SAAS,GAAG,IAAI,MAAM,IAAI,KAAK,EAAE;CAC3E;;CAGA,MAAc,SACZ,OACA,WACA,SACA,UACkB;EAClB,MAAM,EAAE,OAAO,gBAAgB;EAC/B,MAAM,SAAS;GACb,YAAY;GACZ,gBAAgB;GAChB,WAAW,MAAM;GACjB,aAAa,MAAM,eAAe;GAClC,MAAM,MAAM;GACZ,WAAW,MAAM;GACjB,WAAW,MAAM;EACnB;EACA,MAAM,UAAU,SAAS,IAAI,iBAAiB,KAAK,CAAC;EACpD,IAAI,SAAS;GACX,MAAM,MAAM,OAAO,KAAK,OAAO,WAAW,QAAQ,IAAI,MAAM;GAC5D,OAAO;EACT;EACA,MAAM,MAAM,OAAO,KAAK,OAAO,WAAW;GACxC,GAAG;GACH,IAAI,KAAK;GACT;GACA,SAAS,MAAM;GACf,cAAc,MAAM;GACpB,QAAQ,MAAM;GACd,SAAS,MAAM;EACjB,CAAC;EACD,OAAO;CACT;AACF;AAEA,MAAM,+BAAe,IAAI,IAA8B;;AAGvD,eAAe,WAAc,KAAa,MAAoC;CAC5E,MAAM,OAAO,aAAa,IAAI,GAAG,KAAK,QAAQ,QAAQ,EAAA,CAAG,KAAK,MAAM,IAAI;CACxE,aAAa,IAAI,KAAK,GAAG;CACzB,IAAI;EACF,OAAO,MAAM;CACf,UAAU;EACR,IAAI,aAAa,IAAI,GAAG,MAAM,KAC5B,aAAa,OAAO,GAAG;CAE3B;AACF"}
+{"version":3,"file":"baseline-transfer.mjs","names":[],"sources":["../../src/models/baseline-transfer.ts"],"sourcesContent":["/**\n * Baseline portability: export a project's baselines as a zip archive and\n * import (upsert) them from the same format. Format and limits live in\n * `baseline-archive.ts`; see the portability guide in the docs site.\n */\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { DatabaseAdapter, TxStore } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport { withContentClaim } from \"../utils/screenshot-store.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { baselineIdentity } from \"./baseline-archive.ts\";\nimport { BaselineWriteConflict } from \"./baseline-conflict.ts\";\nimport { exportBaselineArchive, type BaselineExportOptions } from \"./baseline-export.ts\";\nimport { planBaselineImport, writePlannedImage, type PlannedBaseline } from \"./baseline-import.ts\";\nimport { BaselineModel, type BaselineTables } from \"./baseline.ts\";\n\n/** Outcome of {@link BaselineTransferModel.import}. */\nexport interface BaselineImportResult {\n  /** Baselines in the archive (all applied). */\n  imported: number;\n  /** Baselines that did not exist before. */\n  created: number;\n  /** Existing baselines that were overwritten. */\n  updated: number;\n}\n\n/** Export/import of baselines between StoryShelf instances (or for backup). */\nexport class BaselineTransferModel {\n  private readonly tables: BaselineTables;\n  private readonly baselines: BaselineModel;\n  private readonly db: DatabaseAdapter;\n  private readonly storage: StorageAdapter;\n\n  constructor(db: DatabaseAdapter, storage: StorageAdapter, tables?: BaselineTables) {\n    this.db = db;\n    this.storage = storage;\n    this.tables = tables ?? { baselines: db.tables.baselines };\n    this.baselines = new BaselineModel(db, this.tables, storage);\n  }\n\n  /**\n   * Stream the project's baselines (optionally one branch) as a zip archive.\n   *\n   * @throws {BaselineArchiveError} Before streaming, when over the archive entry limit.\n   */\n  async export(\n    projectId: string,\n    options: BaselineExportOptions = {},\n  ): Promise<AsyncIterable<Buffer>> {\n    return exportBaselineArchive(this.storage, await this.baselines.list(projectId), options);\n  }\n\n  /**\n   * Upsert every baseline in `archive` into the project. The whole archive is\n   * validated before anything is written; images are then stored (idempotent,\n   * safe to retry) and all rows are applied in one transaction when the driver\n   * supports it, so a failure leaves the rows untouched. Imports into the same\n   * project run one at a time. Imported rows keep their original timestamps;\n   * `snapshotId` is cleared because snapshots are not portable.\n   *\n   * @throws {BaselineArchiveError} On a malformed, unsafe, or inconsistent archive.\n   */\n  async import(projectId: string, archive: Buffer): Promise<BaselineImportResult> {\n    const plan = await planBaselineImport(archive, projectId);\n    // Images that already exist are reused, not written: claim the project's content so the\n    // screenshot sweep cannot delete one before the rows pointing at it are committed.\n    return await serialized(\n      projectId,\n      async () =>\n        await withContentClaim(this.storage, projectId, async () => {\n          for (const planned of plan) {\n            // oxlint-disable-next-line eslint/no-await-in-loop -- sequential writes bound storage load\n            await writePlannedImage(this.storage, planned);\n          }\n          const existing = await this.existingByIdentity(projectId);\n          const created = await this.applyRows(projectId, plan, existing);\n          return { imported: plan.length, created, updated: plan.length - created };\n        }),\n    );\n  }\n\n  private async existingByIdentity(projectId: string): Promise<Map<string, Baseline>> {\n    const rows = await this.baselines.list(projectId);\n    return new Map(\n      rows.map((row) => [\n        baselineIdentity({\n          storyId: row.storyId,\n          viewport: row.viewportName,\n          browser: row.browser ?? DEFAULT_BROWSER,\n          branch: row.branch,\n        }),\n        row,\n      ]),\n    );\n  }\n\n  /** Apply every row, in a transaction when available; returns how many were created. */\n  private async applyRows(\n    projectId: string,\n    plan: PlannedBaseline[],\n    existing: Map<string, Baseline>,\n  ): Promise<number> {\n    const run = async (store: TxStore): Promise<number> => {\n      let created = 0;\n      for (const planned of plan) {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- rows are applied in order within one transaction\n        created += (await this.applyRow(store, projectId, planned, existing)) ? 1 : 0;\n      }\n      return created;\n    };\n    const lifecycle = this.db.buildReferenceLifecycle;\n    if (lifecycle) {\n      const touched = plan\n        .map((planned) => existing.get(baselineIdentity(planned.entry)))\n        .filter((row): row is Baseline => row !== undefined);\n      const changes = await Promise.all(\n        touched.map(async (row) => {\n          const owner = { type: \"baseline\" as const, id: row.id, projectId };\n          return {\n            owner,\n            expectedGeneration: await lifecycle.referenceGeneration(owner),\n            buildIds: [],\n          };\n        }),\n      );\n      const updated = await lifecycle.replaceManyFencedReferences(changes, async (store) => {\n        await this.assertUnchangedIdentities(store, touched);\n        return await run(store);\n      });\n      return updated.result;\n    }\n    return this.db.transact ? await this.db.transact(run) : await run(this.db);\n  }\n\n  private async assertUnchangedIdentities(store: TxStore, rows: Baseline[]): Promise<void> {\n    const current = await Promise.all(\n      rows.map(\n        async (row) =>\n          (await store.get(this.tables.baselines, row.id)) as unknown as Baseline | null,\n      ),\n    );\n    for (const [index, row] of rows.entries()) {\n      const found = current[index];\n      if (\n        !found ||\n        found.projectId !== row.projectId ||\n        found.storyId !== row.storyId ||\n        found.viewportName !== row.viewportName ||\n        found.branch !== row.branch ||\n        found.updatedAt !== row.updatedAt ||\n        found.snapshotId !== row.snapshotId ||\n        found.sourceBuildId !== row.sourceBuildId ||\n        found.screenshotPath !== row.screenshotPath ||\n        (found.browser ?? DEFAULT_BROWSER) !== (row.browser ?? DEFAULT_BROWSER)\n      ) {\n        throw new BaselineWriteConflict(\"Baseline changed during import; retry\");\n      }\n    }\n  }\n\n  /** Write one planned row; resolves true when it was created. */\n  private async applyRow(\n    store: TxStore,\n    projectId: string,\n    planned: PlannedBaseline,\n    existing: Map<string, Baseline>,\n  ): Promise<boolean> {\n    const { entry, storagePath } = planned;\n    const fields = {\n      snapshotId: null,\n      sourceBuildId: null,\n      screenshotPath: storagePath,\n      infraHash: entry.infraHash,\n      fingerprint: entry.fingerprint ?? null,\n      mode: entry.mode,\n      createdAt: entry.createdAt,\n      updatedAt: entry.updatedAt,\n    } satisfies Partial<Baseline>;\n    const current = existing.get(baselineIdentity(entry));\n    if (current) {\n      await store.update(this.tables.baselines, current.id, fields);\n      return false;\n    }\n    await store.insert(this.tables.baselines, {\n      ...fields,\n      id: ulid(),\n      projectId,\n      storyId: entry.storyId,\n      viewportName: entry.viewport,\n      branch: entry.branch,\n      browser: entry.browser,\n    });\n    return true;\n  }\n}\n\nconst importQueues = new Map<string, Promise<unknown>>();\n\n/** Run `task` after earlier work for the same key settles (in-process serialization). */\nasync function serialized<T>(key: string, task: () => Promise<T>): Promise<T> {\n  const run = (importQueues.get(key) ?? Promise.resolve()).then(task, task);\n  importQueues.set(key, run);\n  try {\n    return await run;\n  } finally {\n    if (importQueues.get(key) === run) {\n      importQueues.delete(key);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA4BA,IAAa,wBAAb,MAAmC;CACjC;CACA;CACA;CACA;CAEA,YAAY,IAAqB,SAAyB,QAAyB;EACjF,KAAK,KAAK;EACV,KAAK,UAAU;EACf,KAAK,SAAS,UAAU,EAAE,WAAW,GAAG,OAAO,UAAU;EACzD,KAAK,YAAY,IAAI,cAAc,IAAI,KAAK,QAAQ,OAAO;CAC7D;;;;;;CAOA,MAAM,OACJ,WACA,UAAiC,CAAC,GACF;EAChC,OAAO,sBAAsB,KAAK,SAAS,MAAM,KAAK,UAAU,KAAK,SAAS,GAAG,OAAO;CAC1F;;;;;;;;;;;CAYA,MAAM,OAAO,WAAmB,SAAgD;EAC9E,MAAM,OAAO,MAAM,mBAAmB,SAAS,SAAS;EAGxD,OAAO,MAAM,WACX,WACA,YACE,MAAM,iBAAiB,KAAK,SAAS,WAAW,YAAY;GAC1D,KAAK,MAAM,WAAW,MAEpB,MAAM,kBAAkB,KAAK,SAAS,OAAO;GAE/C,MAAM,WAAW,MAAM,KAAK,mBAAmB,SAAS;GACxD,MAAM,UAAU,MAAM,KAAK,UAAU,WAAW,MAAM,QAAQ;GAC9D,OAAO;IAAE,UAAU,KAAK;IAAQ;IAAS,SAAS,KAAK,SAAS;GAAQ;EAC1E,CAAC,CACL;CACF;CAEA,MAAc,mBAAmB,WAAmD;EAClF,MAAM,OAAO,MAAM,KAAK,UAAU,KAAK,SAAS;EAChD,OAAO,IAAI,IACT,KAAK,KAAK,QAAQ,CAChB,iBAAiB;GACf,SAAS,IAAI;GACb,UAAU,IAAI;GACd,SAAS,IAAI,WAAA;GACb,QAAQ,IAAI;EACd,CAAC,GACD,GACF,CAAC,CACH;CACF;;CAGA,MAAc,UACZ,WACA,MACA,UACiB;EACjB,MAAM,MAAM,OAAO,UAAoC;GACrD,IAAI,UAAU;GACd,KAAK,MAAM,WAAW,MAEpB,WAAY,MAAM,KAAK,SAAS,OAAO,WAAW,SAAS,QAAQ,IAAK,IAAI;GAE9E,OAAO;EACT;EACA,MAAM,YAAY,KAAK,GAAG;EAC1B,IAAI,WAAW;GACb,MAAM,UAAU,KACb,KAAK,YAAY,SAAS,IAAI,iBAAiB,QAAQ,KAAK,CAAC,CAAC,CAAC,CAC/D,QAAQ,QAAyB,QAAQ,KAAA,CAAS;GACrD,MAAM,UAAU,MAAM,QAAQ,IAC5B,QAAQ,IAAI,OAAO,QAAQ;IACzB,MAAM,QAAQ;KAAE,MAAM;KAAqB,IAAI,IAAI;KAAI;IAAU;IACjE,OAAO;KACL;KACA,oBAAoB,MAAM,UAAU,oBAAoB,KAAK;KAC7D,UAAU,CAAC;IACb;GACF,CAAC,CACH;GAKA,QAAO,MAJe,UAAU,4BAA4B,SAAS,OAAO,UAAU;IACpF,MAAM,KAAK,0BAA0B,OAAO,OAAO;IACnD,OAAO,MAAM,IAAI,KAAK;GACxB,CAAC,EAAA,CACc;EACjB;EACA,OAAO,KAAK,GAAG,WAAW,MAAM,KAAK,GAAG,SAAS,GAAG,IAAI,MAAM,IAAI,KAAK,EAAE;CAC3E;CAEA,MAAc,0BAA0B,OAAgB,MAAiC;EACvF,MAAM,UAAU,MAAM,QAAQ,IAC5B,KAAK,IACH,OAAO,QACJ,MAAM,MAAM,IAAI,KAAK,OAAO,WAAW,IAAI,EAAE,CAClD,CACF;EACA,KAAK,MAAM,CAAC,OAAO,QAAQ,KAAK,QAAQ,GAAG;GACzC,MAAM,QAAQ,QAAQ;GACtB,IACE,CAAC,SACD,MAAM,cAAc,IAAI,aACxB,MAAM,YAAY,IAAI,WACtB,MAAM,iBAAiB,IAAI,gBAC3B,MAAM,WAAW,IAAI,UACrB,MAAM,cAAc,IAAI,aACxB,MAAM,eAAe,IAAI,cACzB,MAAM,kBAAkB,IAAI,iBAC5B,MAAM,mBAAmB,IAAI,mBAC5B,MAAM,WAAA,iBAAiC,IAAI,WAAA,aAE5C,MAAM,IAAI,sBAAsB,uCAAuC;EAE3E;CACF;;CAGA,MAAc,SACZ,OACA,WACA,SACA,UACkB;EAClB,MAAM,EAAE,OAAO,gBAAgB;EAC/B,MAAM,SAAS;GACb,YAAY;GACZ,eAAe;GACf,gBAAgB;GAChB,WAAW,MAAM;GACjB,aAAa,MAAM,eAAe;GAClC,MAAM,MAAM;GACZ,WAAW,MAAM;GACjB,WAAW,MAAM;EACnB;EACA,MAAM,UAAU,SAAS,IAAI,iBAAiB,KAAK,CAAC;EACpD,IAAI,SAAS;GACX,MAAM,MAAM,OAAO,KAAK,OAAO,WAAW,QAAQ,IAAI,MAAM;GAC5D,OAAO;EACT;EACA,MAAM,MAAM,OAAO,KAAK,OAAO,WAAW;GACxC,GAAG;GACH,IAAI,KAAK;GACT;GACA,SAAS,MAAM;GACf,cAAc,MAAM;GACpB,QAAQ,MAAM;GACd,SAAS,MAAM;EACjB,CAAC;EACD,OAAO;CACT;AACF;AAEA,MAAM,+BAAe,IAAI,IAA8B;;AAGvD,eAAe,WAAc,KAAa,MAAoC;CAC5E,MAAM,OAAO,aAAa,IAAI,GAAG,KAAK,QAAQ,QAAQ,EAAA,CAAG,KAAK,MAAM,IAAI;CACxE,aAAa,IAAI,KAAK,GAAG;CACzB,IAAI;EACF,OAAO,MAAM;CACf,UAAU;EACR,IAAI,aAAa,IAAI,GAAG,MAAM,KAC5B,aAAa,OAAO,GAAG;CAE3B;AACF"}

package/dist/models/baseline.d.mts

@@ -5,10 +5,11 @@ import { StorageAdapter } from "../adapter/storage.mjs";
 import { SecretInput } from "../utils/encrypt.mjs";
 import { WebhookTables } from "./webhook.mjs";
 import { Baseline } from "../schema/baseline.mjs";
+import { AtomicBaselineApproval } from "./baseline-approval.mjs";
 import { Table } from "drizzle-orm";
-//#region src/models/baseline.d.ts
 /** Extra identity/metadata for {@link BaselineModel.upsert}. */
 interface BaselineUpsertOptions {
+  approval?: AtomicBaselineApproval;
   /** Engine the baseline belongs to (default chromium). */
   browser?: string;
   /** Resolved mode definition as JSON (display only). */
@@ -45,16 +46,18 @@ declare class BaselineModel {
   private contentFor;
   read(baseline: Baseline): Promise<Buffer>;
   upsert(projectId: string, storyId: string, viewport: string, branch: string, snapshotId: string, sourcePath: string, infraHash?: string | null, options?: BaselineUpsertOptions): Promise<Baseline>;
+  private sourceBuildId;
   list(projectId: string): Promise<Baseline[]>;
   /**
    * Delete a baseline's own file. A content-addressed screenshot is shared with snapshots and other
    * baselines, so it is left for the retention sweep instead.
    */
   private discardFile;
+  /** Drop the reference and row together when the adapter supports lifecycle protection. */
+  private removeRecord;
   removeOrphans(projectId: string, validStoryIds: Set<string>): Promise<number>;
   removeForBranch(projectId: string, branch: string): Promise<number>;
   removeStaleBranches(projectId: string, staleBranches: ReadonlySet<string>): Promise<number>;
 }
-//#endregion
 export { BaselineModel, BaselineTables, BaselineUpsertOptions };
 //# sourceMappingURL=baseline.d.mts.map