@storyshelf/core 0.6.2 → 0.8.0

package/dist/models/design-renders.mjs

@@ -0,0 +1,73 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { designRenderPath } from "../paths.mjs";
+// src/models/design-renders.ts
+/**
+* Renders live at `{projectId}/design/{provider}/{fileKey}/{node}.png` (a member's own
+* connection: `…/{provider}/user-{id}/{fileKey}/…`), one per
+* linked node and overwritten in place when the file version moves, so storage
+* is bounded by the number of distinct linked nodes. A deleted node drops its
+* render; a link removed from settings (or a deleted project) leaves its PNG behind.
+*/
+var DesignRenderStore = class {
+	db;
+	table;
+	storage;
+	logger;
+	constructor(db, table, storage, logger) {
+		this.db = db;
+		this.table = table;
+		this.storage = storage;
+		this.logger = logger;
+	}
+	/** Cached render bytes of a node, or null when it has none (or storage is not wired). */
+	async read(node) {
+		if (!this.storage || !node.renderPath) return null;
+		return await this.storage.read(node.renderPath).catch(() => null);
+	}
+	/** Delete a node's stored render (its row is cleared by the caller's update). */
+	async remove(node) {
+		if (node.renderPath) await this.storage?.delete(node.renderPath).catch(() => {});
+	}
+	/**
+	* Fetch renders (one call per file) for the ok node rows that are missing one
+	* or hold an older file version, keyed by link URL. Failures keep the previous
+	* render and the row unchanged.
+	*/
+	async ensure(projectId, client, fileKey, stored, call) {
+		const needing = [...stored].filter(([, node]) => needsRender(node));
+		if (!this.storage || needing.length === 0) return stored;
+		try {
+			const renders = await client.fetchRenders(fileKey, needing.map(([, node]) => node.nodeId), call);
+			const saved = await Promise.all(needing.map(async ([url, node]) => {
+				const png = renders.get(node.nodeId);
+				return png ? [url, await this.save(projectId, node, png)] : null;
+			}));
+			for (const entry of saved) if (entry) stored.set(entry[0], entry[1]);
+		} catch (error) {
+			this.logger?.warn({
+				err: error,
+				fileKey,
+				nodes: needing.length
+			}, "design render fetch failed");
+		}
+		return stored;
+	}
+	async save(projectId, node, png) {
+		const path = designRenderPath(projectId, node.provider, node.fileKey, node.nodeId, node.viewerId);
+		await this.storage?.write(path, png);
+		return await this.db.update(this.table, node.id, {
+			renderPath: path,
+			renderVersion: node.version,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+};
+/** An ok node row whose render is missing or taken at an older file version. */
+function needsRender(node) {
+	return node.state === "ok" && node.nodeId !== "" && node.version !== null && node.renderVersion !== node.version;
+}
+export { DesignRenderStore };
+
+//# sourceMappingURL=design-renders.mjs.map

package/dist/models/design-renders.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-renders.mjs","names":[],"sources":["../../src/models/design-renders.ts"],"sourcesContent":["/** Persistence of cached design node renders: PNGs in storage, version-tracked on the `design_nodes` row. */\nimport type { Table } from \"drizzle-orm\";\nimport type { Buffer } from \"node:buffer\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { DesignCallOptions, DesignClient } from \"../adapters/design.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport type { DesignNode } from \"../schema/design.ts\";\nimport { designRenderPath } from \"../utils/paths.ts\";\n\n/**\n * Renders live at `{projectId}/design/{provider}/{fileKey}/{node}.png` (a member's own\n * connection: `…/{provider}/user-{id}/{fileKey}/…`), one per\n * linked node and overwritten in place when the file version moves, so storage\n * is bounded by the number of distinct linked nodes. A deleted node drops its\n * render; a link removed from settings (or a deleted project) leaves its PNG behind.\n */\nexport class DesignRenderStore {\n  private readonly db: DatabaseAdapter;\n  private readonly table: Table;\n  private readonly storage: StorageAdapter | undefined;\n  private readonly logger: Logger | undefined;\n\n  constructor(\n    db: DatabaseAdapter,\n    table: Table,\n    storage: StorageAdapter | undefined,\n    logger: Logger | undefined,\n  ) {\n    this.db = db;\n    this.table = table;\n    this.storage = storage;\n    this.logger = logger;\n  }\n\n  /** Cached render bytes of a node, or null when it has none (or storage is not wired). */\n  async read(node: DesignNode): Promise<Buffer | null> {\n    if (!this.storage || !node.renderPath) return null;\n    return await this.storage.read(node.renderPath).catch(() => null);\n  }\n\n  /** Delete a node's stored render (its row is cleared by the caller's update). */\n  async remove(node: DesignNode): Promise<void> {\n    if (node.renderPath) await this.storage?.delete(node.renderPath).catch(() => {});\n  }\n\n  /**\n   * Fetch renders (one call per file) for the ok node rows that are missing one\n   * or hold an older file version, keyed by link URL. Failures keep the previous\n   * render and the row unchanged.\n   */\n  async ensure(\n    projectId: string,\n    client: DesignClient,\n    fileKey: string,\n    stored: Map<string, DesignNode>,\n    call: DesignCallOptions,\n  ): Promise<Map<string, DesignNode>> {\n    const needing = [...stored].filter(([, node]) => needsRender(node));\n    if (!this.storage || needing.length === 0) return stored;\n    try {\n      const renders = await client.fetchRenders(\n        fileKey,\n        needing.map(([, node]) => node.nodeId),\n        call,\n      );\n      const saved = await Promise.all(\n        needing.map(async ([url, node]) => {\n          const png = renders.get(node.nodeId);\n          return png ? ([url, await this.save(projectId, node, png)] as const) : null;\n        }),\n      );\n      for (const entry of saved) {\n        if (entry) stored.set(entry[0], entry[1]);\n      }\n    } catch (error) {\n      this.logger?.warn(\n        { err: error, fileKey, nodes: needing.length },\n        \"design render fetch failed\",\n      );\n    }\n    return stored;\n  }\n\n  private async save(projectId: string, node: DesignNode, png: Buffer): Promise<DesignNode> {\n    const path = designRenderPath(\n      projectId,\n      node.provider,\n      node.fileKey,\n      node.nodeId,\n      node.viewerId,\n    );\n    await this.storage?.write(path, png);\n    return (await this.db.update(this.table, node.id, {\n      renderPath: path,\n      renderVersion: node.version,\n      updatedAt: new Date().toISOString(),\n    })) as unknown as DesignNode;\n  }\n}\n\n/** An ok node row whose render is missing or taken at an older file version. */\nfunction needsRender(node: DesignNode): boolean {\n  return (\n    node.state === \"ok\" &&\n    node.nodeId !== \"\" &&\n    node.version !== null &&\n    node.renderVersion !== node.version\n  );\n}\n"],"mappings":";;;;;;;;;;;;AAiBA,IAAa,oBAAb,MAA+B;CAC7B;CACA;CACA;CACA;CAEA,YACE,IACA,OACA,SACA,QACA;EACA,KAAK,KAAK;EACV,KAAK,QAAQ;EACb,KAAK,UAAU;EACf,KAAK,SAAS;CAChB;;CAGA,MAAM,KAAK,MAA0C;EACnD,IAAI,CAAC,KAAK,WAAW,CAAC,KAAK,YAAY,OAAO;EAC9C,OAAO,MAAM,KAAK,QAAQ,KAAK,KAAK,UAAU,CAAC,CAAC,YAAY,IAAI;CAClE;;CAGA,MAAM,OAAO,MAAiC;EAC5C,IAAI,KAAK,YAAY,MAAM,KAAK,SAAS,OAAO,KAAK,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;CACjF;;;;;;CAOA,MAAM,OACJ,WACA,QACA,SACA,QACA,MACkC;EAClC,MAAM,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC,QAAQ,GAAG,UAAU,YAAY,IAAI,CAAC;EAClE,IAAI,CAAC,KAAK,WAAW,QAAQ,WAAW,GAAG,OAAO;EAClD,IAAI;GACF,MAAM,UAAU,MAAM,OAAO,aAC3B,SACA,QAAQ,KAAK,GAAG,UAAU,KAAK,MAAM,GACrC,IACF;GACA,MAAM,QAAQ,MAAM,QAAQ,IAC1B,QAAQ,IAAI,OAAO,CAAC,KAAK,UAAU;IACjC,MAAM,MAAM,QAAQ,IAAI,KAAK,MAAM;IACnC,OAAO,MAAO,CAAC,KAAK,MAAM,KAAK,KAAK,WAAW,MAAM,GAAG,CAAC,IAAc;GACzE,CAAC,CACH;GACA,KAAK,MAAM,SAAS,OAClB,IAAI,OAAO,OAAO,IAAI,MAAM,IAAI,MAAM,EAAE;EAE5C,SAAS,OAAO;GACd,KAAK,QAAQ,KACX;IAAE,KAAK;IAAO;IAAS,OAAO,QAAQ;GAAO,GAC7C,4BACF;EACF;EACA,OAAO;CACT;CAEA,MAAc,KAAK,WAAmB,MAAkB,KAAkC;EACxF,MAAM,OAAO,iBACX,WACA,KAAK,UACL,KAAK,SACL,KAAK,QACL,KAAK,QACP;EACA,MAAM,KAAK,SAAS,MAAM,MAAM,GAAG;EACnC,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,KAAK,IAAI;GAChD,YAAY;GACZ,eAAe,KAAK;GACpB,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC,CAAC;CACH;AACF;;AAGA,SAAS,YAAY,MAA2B;CAC9C,OACE,KAAK,UAAU,QACf,KAAK,WAAW,MAChB,KAAK,YAAY,QACjB,KAAK,kBAAkB,KAAK;AAEhC"}

package/dist/models/design-resolve.d.mts

@@ -0,0 +1,27 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DesignLink } from "../schema/design.mjs";
+/** Last observed health of a design credential. */
+type DesignCredentialStatus = "unknown" | "ok" | "unauthorized" | "forbidden";
+/** Where a component's resolved design link came from. */
+type DesignSource = "manual" | "story";
+/** The design link(s) a story file resolves to. */
+interface DesignResolution {
+  /** One URL, or the distinct set when states of the file disagree. */
+  urls: string[];
+  source: DesignSource;
+}
+/** Story-file key: path without a leading `./`, so index and manual entries compare equal. */
+declare function normalizeImportPath(path: string): string;
+/**
+ * Resolve design links per component (story file). Precedence: manual mapping
+ * > story parameters (`storyshelf.figma` over `design`, already merged at
+ * capture). States of one file are deduped; if they disagree the distinct set
+ * is returned rather than guessing. Files with no link are absent.
+ */
+declare function resolveDesigns(manual: readonly Pick<DesignLink, "importPath" | "url">[], snapshots: readonly {
+  storyImportPath: string | null;
+  designUrl?: string | null;
+}[]): Map<string, DesignResolution>;
+export { DesignCredentialStatus, DesignResolution, DesignSource, normalizeImportPath, resolveDesigns };
+//# sourceMappingURL=design-resolve.d.mts.map

package/dist/models/design-resolve.mjs

@@ -0,0 +1,40 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/models/design-resolve.ts
+/** Story-file key: path without a leading `./`, so index and manual entries compare equal. */
+function normalizeImportPath(path) {
+	return path.trim().replace(/^(?:\.\/)+/u, "");
+}
+/**
+* Resolve design links per component (story file). Precedence: manual mapping
+* > story parameters (`storyshelf.figma` over `design`, already merged at
+* capture). States of one file are deduped; if they disagree the distinct set
+* is returned rather than guessing. Files with no link are absent.
+*/
+function resolveDesigns(manual, snapshots) {
+	const resolved = storyDesigns(snapshots);
+	for (const link of manual) if (link.importPath) resolved.set(normalizeImportPath(link.importPath), {
+		urls: [link.url],
+		source: "manual"
+	});
+	return resolved;
+}
+/** Distinct story-declared URLs per file. */
+function storyDesigns(snapshots) {
+	const resolved = /* @__PURE__ */ new Map();
+	for (const snapshot of snapshots) {
+		const key = snapshot.storyImportPath ? normalizeImportPath(snapshot.storyImportPath) : "";
+		if (!key || !snapshot.designUrl) continue;
+		const urls = resolved.get(key)?.urls ?? [];
+		if (!urls.includes(snapshot.designUrl)) urls.push(snapshot.designUrl);
+		resolved.set(key, {
+			urls,
+			source: "story"
+		});
+	}
+	return resolved;
+}
+export { normalizeImportPath, resolveDesigns };
+
+//# sourceMappingURL=design-resolve.mjs.map

package/dist/models/design-resolve.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-resolve.mjs","names":[],"sources":["../../src/models/design-resolve.ts"],"sourcesContent":["/** Per-component design link resolution: manual mappings over story-declared URLs. */\nimport type { DesignLink } from \"../schema/design.ts\";\n\n/** Last observed health of a design credential. */\nexport type DesignCredentialStatus = \"unknown\" | \"ok\" | \"unauthorized\" | \"forbidden\";\n\n/** Where a component's resolved design link came from. */\nexport type DesignSource = \"manual\" | \"story\";\n\n/** The design link(s) a story file resolves to. */\nexport interface DesignResolution {\n  /** One URL, or the distinct set when states of the file disagree. */\n  urls: string[];\n  source: DesignSource;\n}\n\n/** Story-file key: path without a leading `./`, so index and manual entries compare equal. */\nexport function normalizeImportPath(path: string): string {\n  return path.trim().replace(/^(?:\\.\\/)+/u, \"\");\n}\n\n/**\n * Resolve design links per component (story file). Precedence: manual mapping\n * > story parameters (`storyshelf.figma` over `design`, already merged at\n * capture). States of one file are deduped; if they disagree the distinct set\n * is returned rather than guessing. Files with no link are absent.\n */\nexport function resolveDesigns(\n  manual: readonly Pick<DesignLink, \"importPath\" | \"url\">[],\n  snapshots: readonly { storyImportPath: string | null; designUrl?: string | null }[],\n): Map<string, DesignResolution> {\n  const resolved = storyDesigns(snapshots);\n  for (const link of manual) {\n    if (link.importPath) {\n      resolved.set(normalizeImportPath(link.importPath), { urls: [link.url], source: \"manual\" });\n    }\n  }\n  return resolved;\n}\n\n/** Distinct story-declared URLs per file. */\nfunction storyDesigns(\n  snapshots: readonly { storyImportPath: string | null; designUrl?: string | null }[],\n): Map<string, DesignResolution> {\n  const resolved = new Map<string, DesignResolution>();\n  for (const snapshot of snapshots) {\n    const key = snapshot.storyImportPath ? normalizeImportPath(snapshot.storyImportPath) : \"\";\n    if (!key || !snapshot.designUrl) continue;\n    const urls = resolved.get(key)?.urls ?? [];\n    if (!urls.includes(snapshot.designUrl)) urls.push(snapshot.designUrl);\n    resolved.set(key, { urls, source: \"story\" });\n  }\n  return resolved;\n}\n"],"mappings":";;;;;AAiBA,SAAgB,oBAAoB,MAAsB;CACxD,OAAO,KAAK,KAAK,CAAC,CAAC,QAAQ,eAAe,EAAE;AAC9C;;;;;;;AAQA,SAAgB,eACd,QACA,WAC+B;CAC/B,MAAM,WAAW,aAAa,SAAS;CACvC,KAAK,MAAM,QAAQ,QACjB,IAAI,KAAK,YACP,SAAS,IAAI,oBAAoB,KAAK,UAAU,GAAG;EAAE,MAAM,CAAC,KAAK,GAAG;EAAG,QAAQ;CAAS,CAAC;CAG7F,OAAO;AACT;;AAGA,SAAS,aACP,WAC+B;CAC/B,MAAM,2BAAW,IAAI,IAA8B;CACnD,KAAK,MAAM,YAAY,WAAW;EAChC,MAAM,MAAM,SAAS,kBAAkB,oBAAoB,SAAS,eAAe,IAAI;EACvF,IAAI,CAAC,OAAO,CAAC,SAAS,WAAW;EACjC,MAAM,OAAO,SAAS,IAAI,GAAG,CAAC,EAAE,QAAQ,CAAC;EACzC,IAAI,CAAC,KAAK,SAAS,SAAS,SAAS,GAAG,KAAK,KAAK,SAAS,SAAS;EACpE,SAAS,IAAI,KAAK;GAAE;GAAM,QAAQ;EAAQ,CAAC;CAC7C;CACA,OAAO;AACT"}

package/dist/models/design.d.mts

@@ -0,0 +1,37 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { DesignProvider } from "../adapter/design.mjs";
+import { DesignLink } from "../schema/design.mjs";
+import { Table } from "drizzle-orm";
+/** Tables required by {@link DesignModel}. */
+interface DesignTables {
+  designLinks: Table;
+}
+/** Data operations for design links; URLs are validated by the configured providers. */
+declare class DesignModel {
+  private readonly tables;
+  private readonly db;
+  private readonly providers;
+  constructor(db: DatabaseAdapter, providers: readonly DesignProvider[], tables?: DesignTables);
+  /** Project-level design file links, oldest first. */
+  projectLinks(projectId: string): Promise<DesignLink[]>;
+  /** Component mapping overrides (`import_path → URL`), by path. */
+  componentLinks(projectId: string): Promise<DesignLink[]>;
+  /** Add a project-level design file link. Throws {@link InvalidDesignUrlError}. */
+  addProjectLink(projectId: string, input: {
+    label: string;
+    url: string;
+  }): Promise<void>;
+  /** Map a story file to a design URL (replaces any existing mapping). Throws {@link InvalidDesignUrlError}. */
+  setComponentLink(projectId: string, importPath: string, rawUrl: string): Promise<void>;
+  /** Remove a link scoped to the project. */
+  removeLink(projectId: string, id: string): Promise<void>;
+  private validUrl;
+  /** Update the mapping of `key` when one exists; false when there is none. */
+  private updateComponentLink;
+  private links;
+  private insertLink;
+}
+export { DesignModel, DesignTables };
+//# sourceMappingURL=design.d.mts.map

package/dist/models/design.mjs

@@ -0,0 +1,89 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { InvalidDesignUrlError, parseDesignUrl } from "../adapter/design.mjs";
+import { ulid } from "../utils/ulid.mjs";
+import { col } from "./columns.mjs";
+import { normalizeImportPath } from "./design-resolve.mjs";
+import { eq } from "drizzle-orm";
+// src/models/design.ts
+/** Design-source links: project-level design files and per-component (story file) mappings. */
+/** Data operations for design links; URLs are validated by the configured providers. */
+var DesignModel = class {
+	tables;
+	db;
+	providers;
+	constructor(db, providers, tables) {
+		this.db = db;
+		this.providers = providers;
+		this.tables = tables ?? { designLinks: db.tables.designLinks };
+	}
+	/** Project-level design file links, oldest first. */
+	async projectLinks(projectId) {
+		return (await this.links(projectId)).filter((link) => link.importPath === null);
+	}
+	/** Component mapping overrides (`import_path → URL`), by path. */
+	async componentLinks(projectId) {
+		return (await this.links(projectId)).filter((link) => link.importPath !== null).toSorted((a, b) => (a.importPath ?? "").localeCompare(b.importPath ?? ""));
+	}
+	/** Add a project-level design file link. Throws {@link InvalidDesignUrlError}. */
+	async addProjectLink(projectId, input) {
+		const url = this.validUrl(input.url);
+		await this.insertLink(projectId, {
+			importPath: null,
+			label: input.label.trim() || null,
+			url
+		});
+	}
+	/** Map a story file to a design URL (replaces any existing mapping). Throws {@link InvalidDesignUrlError}. */
+	async setComponentLink(projectId, importPath, rawUrl) {
+		const url = this.validUrl(rawUrl);
+		const key = normalizeImportPath(importPath);
+		if (await this.updateComponentLink(projectId, key, url)) return;
+		try {
+			await this.insertLink(projectId, {
+				importPath: key,
+				label: null,
+				url
+			});
+		} catch (error) {
+			if (!await this.updateComponentLink(projectId, key, url)) throw error;
+		}
+	}
+	/** Remove a link scoped to the project. */
+	async removeLink(projectId, id) {
+		if ((await this.links(projectId)).find((link) => link.id === id)) await this.db.remove(this.tables.designLinks, id);
+	}
+	validUrl(raw) {
+		const parsed = parseDesignUrl(this.providers, raw);
+		if (!parsed) throw new InvalidDesignUrlError(raw, this.providers.map((p) => p.metadata.urlHint).join(" or "));
+		return parsed.ref.url;
+	}
+	/** Update the mapping of `key` when one exists; false when there is none. */
+	async updateComponentLink(projectId, key, url) {
+		const existing = (await this.componentLinks(projectId)).find((link) => normalizeImportPath(link.importPath ?? "") === key);
+		if (!existing) return false;
+		await this.db.update(this.tables.designLinks, existing.id, {
+			url,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return true;
+	}
+	async links(projectId) {
+		const column = col(this.tables.designLinks, "projectId");
+		return (await this.db.list(this.tables.designLinks, { where: eq(column, projectId) })).toSorted((a, b) => a.createdAt.localeCompare(b.createdAt));
+	}
+	async insertLink(projectId, input) {
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		await this.db.insert(this.tables.designLinks, {
+			id: ulid(),
+			projectId,
+			...input,
+			createdAt: now,
+			updatedAt: now
+		});
+	}
+};
+export { DesignModel };
+
+//# sourceMappingURL=design.mjs.map

package/dist/models/design.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.mjs","names":[],"sources":["../../src/models/design.ts"],"sourcesContent":["/** Design-source links: project-level design files and per-component (story file) mappings. */\nimport { eq } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport { InvalidDesignUrlError, parseDesignUrl, type DesignProvider } from \"../adapters/design.ts\";\nimport type { DesignLink } from \"../schema/design.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { col } from \"./columns.ts\";\nimport { normalizeImportPath } from \"./design-resolve.ts\";\n\n/** Tables required by {@link DesignModel}. */\nexport interface DesignTables {\n  designLinks: Table;\n}\n\n/** Data operations for design links; URLs are validated by the configured providers. */\nexport class DesignModel {\n  private readonly tables: DesignTables;\n  private readonly db: DatabaseAdapter;\n  private readonly providers: readonly DesignProvider[];\n\n  constructor(db: DatabaseAdapter, providers: readonly DesignProvider[], tables?: DesignTables) {\n    this.db = db;\n    this.providers = providers;\n    this.tables = tables ?? { designLinks: db.tables.designLinks };\n  }\n\n  /** Project-level design file links, oldest first. */\n  async projectLinks(projectId: string): Promise<DesignLink[]> {\n    return (await this.links(projectId)).filter((link) => link.importPath === null);\n  }\n\n  /** Component mapping overrides (`import_path → URL`), by path. */\n  async componentLinks(projectId: string): Promise<DesignLink[]> {\n    return (await this.links(projectId))\n      .filter((link) => link.importPath !== null)\n      .toSorted((a, b) => (a.importPath ?? \"\").localeCompare(b.importPath ?? \"\"));\n  }\n\n  /** Add a project-level design file link. Throws {@link InvalidDesignUrlError}. */\n  async addProjectLink(projectId: string, input: { label: string; url: string }): Promise<void> {\n    const url = this.validUrl(input.url);\n    await this.insertLink(projectId, { importPath: null, label: input.label.trim() || null, url });\n  }\n\n  /** Map a story file to a design URL (replaces any existing mapping). Throws {@link InvalidDesignUrlError}. */\n  async setComponentLink(projectId: string, importPath: string, rawUrl: string): Promise<void> {\n    const url = this.validUrl(rawUrl);\n    const key = normalizeImportPath(importPath);\n    if (await this.updateComponentLink(projectId, key, url)) return;\n    try {\n      await this.insertLink(projectId, { importPath: key, label: null, url });\n    } catch (error) {\n      // A concurrent writer won the (project_id, import_path) unique index: converge on an update.\n      if (!(await this.updateComponentLink(projectId, key, url))) throw error;\n    }\n  }\n\n  /** Remove a link scoped to the project. */\n  async removeLink(projectId: string, id: string): Promise<void> {\n    const found = (await this.links(projectId)).find((link) => link.id === id);\n    if (found) await this.db.remove(this.tables.designLinks, id);\n  }\n\n  private validUrl(raw: string): string {\n    const parsed = parseDesignUrl(this.providers, raw);\n    if (!parsed) {\n      throw new InvalidDesignUrlError(\n        raw,\n        this.providers.map((p) => p.metadata.urlHint).join(\" or \"),\n      );\n    }\n    return parsed.ref.url;\n  }\n\n  /** Update the mapping of `key` when one exists; false when there is none. */\n  private async updateComponentLink(projectId: string, key: string, url: string): Promise<boolean> {\n    const existing = (await this.componentLinks(projectId)).find(\n      (link) => normalizeImportPath(link.importPath ?? \"\") === key,\n    );\n    if (!existing) return false;\n    await this.db.update(this.tables.designLinks, existing.id, {\n      url,\n      updatedAt: new Date().toISOString(),\n    });\n    return true;\n  }\n\n  private async links(projectId: string): Promise<DesignLink[]> {\n    const column = col(this.tables.designLinks, \"projectId\");\n    const rows = (await this.db.list(this.tables.designLinks, {\n      where: eq(column, projectId),\n    })) as unknown as DesignLink[];\n    return rows.toSorted((a, b) => a.createdAt.localeCompare(b.createdAt));\n  }\n\n  private async insertLink(\n    projectId: string,\n    input: { importPath: string | null; label: string | null; url: string },\n  ): Promise<void> {\n    const now = new Date().toISOString();\n    await this.db.insert(this.tables.designLinks, {\n      id: ulid(),\n      projectId,\n      ...input,\n      createdAt: now,\n      updatedAt: now,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;AAgBA,IAAa,cAAb,MAAyB;CACvB;CACA;CACA;CAEA,YAAY,IAAqB,WAAsC,QAAuB;EAC5F,KAAK,KAAK;EACV,KAAK,YAAY;EACjB,KAAK,SAAS,UAAU,EAAE,aAAa,GAAG,OAAO,YAAY;CAC/D;;CAGA,MAAM,aAAa,WAA0C;EAC3D,QAAQ,MAAM,KAAK,MAAM,SAAS,EAAA,CAAG,QAAQ,SAAS,KAAK,eAAe,IAAI;CAChF;;CAGA,MAAM,eAAe,WAA0C;EAC7D,QAAQ,MAAM,KAAK,MAAM,SAAS,EAAA,CAC/B,QAAQ,SAAS,KAAK,eAAe,IAAI,CAAC,CAC1C,UAAU,GAAG,OAAO,EAAE,cAAc,GAAA,CAAI,cAAc,EAAE,cAAc,EAAE,CAAC;CAC9E;;CAGA,MAAM,eAAe,WAAmB,OAAsD;EAC5F,MAAM,MAAM,KAAK,SAAS,MAAM,GAAG;EACnC,MAAM,KAAK,WAAW,WAAW;GAAE,YAAY;GAAM,OAAO,MAAM,MAAM,KAAK,KAAK;GAAM;EAAI,CAAC;CAC/F;;CAGA,MAAM,iBAAiB,WAAmB,YAAoB,QAA+B;EAC3F,MAAM,MAAM,KAAK,SAAS,MAAM;EAChC,MAAM,MAAM,oBAAoB,UAAU;EAC1C,IAAI,MAAM,KAAK,oBAAoB,WAAW,KAAK,GAAG,GAAG;EACzD,IAAI;GACF,MAAM,KAAK,WAAW,WAAW;IAAE,YAAY;IAAK,OAAO;IAAM;GAAI,CAAC;EACxE,SAAS,OAAO;GAEd,IAAI,CAAE,MAAM,KAAK,oBAAoB,WAAW,KAAK,GAAG,GAAI,MAAM;EACpE;CACF;;CAGA,MAAM,WAAW,WAAmB,IAA2B;EAE7D,KADe,MAAM,KAAK,MAAM,SAAS,EAAA,CAAG,MAAM,SAAS,KAAK,OAAO,EAC/D,GAAG,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,aAAa,EAAE;CAC7D;CAEA,SAAiB,KAAqB;EACpC,MAAM,SAAS,eAAe,KAAK,WAAW,GAAG;EACjD,IAAI,CAAC,QACH,MAAM,IAAI,sBACR,KACA,KAAK,UAAU,KAAK,MAAM,EAAE,SAAS,OAAO,CAAC,CAAC,KAAK,MAAM,CAC3D;EAEF,OAAO,OAAO,IAAI;CACpB;;CAGA,MAAc,oBAAoB,WAAmB,KAAa,KAA+B;EAC/F,MAAM,YAAY,MAAM,KAAK,eAAe,SAAS,EAAA,CAAG,MACrD,SAAS,oBAAoB,KAAK,cAAc,EAAE,MAAM,GAC3D;EACA,IAAI,CAAC,UAAU,OAAO;EACtB,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,aAAa,SAAS,IAAI;GACzD;GACA,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC,CAAC;EACD,OAAO;CACT;CAEA,MAAc,MAAM,WAA0C;EAC5D,MAAM,SAAS,IAAI,KAAK,OAAO,aAAa,WAAW;EAIvD,QAAO,MAHa,KAAK,GAAG,KAAK,KAAK,OAAO,aAAa,EACxD,OAAO,GAAG,QAAQ,SAAS,EAC7B,CAAC,EAAA,CACW,UAAU,GAAG,MAAM,EAAE,UAAU,cAAc,EAAE,SAAS,CAAC;CACvE;CAEA,MAAc,WACZ,WACA,OACe;EACf,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,aAAa;GAC5C,IAAI,KAAK;GACT;GACA,GAAG;GACH,WAAW;GACX,WAAW;EACb,CAAC;CACH;AACF"}

package/dist/models/inherited-ratio.d.mts

@@ -0,0 +1,19 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Build } from "../schema/build.mjs";
+/** Builds the average looks at by default (newest first). */
+declare const RECENT_BUILDS_FOR_INHERITED_RATIO = 20;
+/** The average inherited ratio of a project's recent builds. */
+interface InheritedRatio {
+  /** Mean of each build's `inheritedCount / snapshotCount`, from 0 to 1. */
+  ratio: number;
+  /** Builds that went into the mean. */
+  builds: number;
+}
+/**
+ * The mean inherited ratio over the newest `limit` builds that hold snapshots, or `null` when none
+ * does (no data is not a 0 % skip rate). A build with no snapshots has no ratio and is skipped.
+ */
+declare function averageInheritedRatio(builds: readonly Pick<Build, "createdAt" | "snapshotCount" | "inheritedCount">[], limit?: number): InheritedRatio | null;
+export { InheritedRatio, RECENT_BUILDS_FOR_INHERITED_RATIO, averageInheritedRatio };
+//# sourceMappingURL=inherited-ratio.d.mts.map

package/dist/models/inherited-ratio.mjs

@@ -0,0 +1,21 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/models/inherited-ratio.ts
+/** Builds the average looks at by default (newest first). */
+const RECENT_BUILDS_FOR_INHERITED_RATIO = 20;
+/**
+* The mean inherited ratio over the newest `limit` builds that hold snapshots, or `null` when none
+* does (no data is not a 0 % skip rate). A build with no snapshots has no ratio and is skipped.
+*/
+function averageInheritedRatio(builds, limit = 20) {
+	const recent = builds.filter((build) => build.snapshotCount > 0).toSorted((a, b) => b.createdAt.localeCompare(a.createdAt)).slice(0, limit);
+	if (recent.length === 0) return null;
+	return {
+		ratio: recent.reduce((total, build) => total + Math.min(1, build.inheritedCount / build.snapshotCount), 0) / recent.length,
+		builds: recent.length
+	};
+}
+export { RECENT_BUILDS_FOR_INHERITED_RATIO, averageInheritedRatio };
+
+//# sourceMappingURL=inherited-ratio.mjs.map

package/dist/models/inherited-ratio.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inherited-ratio.mjs","names":[],"sources":["../../src/models/inherited-ratio.ts"],"sourcesContent":["/**\n * Affected-capture efficiency of a project (#140): how much of its recent builds was inherited from\n * the baseline instead of rendered. Pure and computed from the counts stored on the builds\n * (`snapshotCount`, `inheritedCount`), so a page needs no per-snapshot query.\n */\nimport type { Build } from \"../schema/build.ts\";\n\n/** Builds the average looks at by default (newest first). */\nexport const RECENT_BUILDS_FOR_INHERITED_RATIO = 20;\n\n/** The average inherited ratio of a project's recent builds. */\nexport interface InheritedRatio {\n  /** Mean of each build's `inheritedCount / snapshotCount`, from 0 to 1. */\n  ratio: number;\n  /** Builds that went into the mean. */\n  builds: number;\n}\n\n/**\n * The mean inherited ratio over the newest `limit` builds that hold snapshots, or `null` when none\n * does (no data is not a 0 % skip rate). A build with no snapshots has no ratio and is skipped.\n */\nexport function averageInheritedRatio(\n  builds: readonly Pick<Build, \"createdAt\" | \"snapshotCount\" | \"inheritedCount\">[],\n  limit: number = RECENT_BUILDS_FOR_INHERITED_RATIO,\n): InheritedRatio | null {\n  const recent = builds\n    .filter((build) => build.snapshotCount > 0)\n    .toSorted((a, b) => b.createdAt.localeCompare(a.createdAt))\n    .slice(0, limit);\n  if (recent.length === 0) {\n    return null;\n  }\n  const sum = recent.reduce(\n    (total, build) => total + Math.min(1, build.inheritedCount / build.snapshotCount),\n    0,\n  );\n  return { ratio: sum / recent.length, builds: recent.length };\n}\n"],"mappings":";;;;;AAQA,MAAa,oCAAoC;;;;;AAcjD,SAAgB,sBACd,QACA,QAAA,IACuB;CACvB,MAAM,SAAS,OACZ,QAAQ,UAAU,MAAM,gBAAgB,CAAC,CAAC,CAC1C,UAAU,GAAG,MAAM,EAAE,UAAU,cAAc,EAAE,SAAS,CAAC,CAAC,CAC1D,MAAM,GAAG,KAAK;CACjB,IAAI,OAAO,WAAW,GACpB,OAAO;CAMT,OAAO;EAAE,OAJG,OAAO,QAChB,OAAO,UAAU,QAAQ,KAAK,IAAI,GAAG,MAAM,iBAAiB,MAAM,aAAa,GAChF,CAEgB,IAAI,OAAO;EAAQ,QAAQ,OAAO;CAAO;AAC7D"}

package/dist/models/insight.d.mts

@@ -0,0 +1,68 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { InsightKind, InsightRow } from "../schema/insight.mjs";
+import { Table } from "drizzle-orm";
+/** Tables required by {@link InsightModel}. */
+interface InsightTables {
+  insights: Table;
+}
+/** Identity and metadata of a run to start. */
+interface InsightStartInput {
+  projectId: string;
+  buildId: string | null;
+  kind: InsightKind;
+  windowKey: string | null;
+  inputHash: string;
+  profile: string;
+  model: string;
+  promptVersion: string;
+  /** Re-run even when a finished row with the same hash exists. */
+  force?: boolean;
+}
+/** Outcome of {@link InsightModel.start}: the row and whether work must run. */
+interface InsightStartResult {
+  row: InsightRow;
+  /** True when the caller should run inference for this row. */
+  run: boolean;
+}
+/** Result payload stored on success. */
+interface InsightResultInput {
+  verdict: string;
+  summary: string;
+  result: string;
+}
+/** Data operations for insights. */
+declare class InsightModel {
+  private readonly tables;
+  private readonly db;
+  constructor(db: DatabaseAdapter, tables?: InsightTables);
+  /**
+   * Insert a `pending` row, or return the existing one for the same unique key
+   * (the dedupe: concurrent identical requests share one row). Failed rows,
+   * replaced health rows, and `force` restart the existing row in place.
+   */
+  start(input: InsightStartInput): Promise<InsightStartResult>;
+  /** The existing row for a run's unique key, without creating one. */
+  peek(input: InsightStartInput): Promise<InsightRow | null>;
+  get(id: string): Promise<InsightRow | null>;
+  /** Newest triage rows for a build (any status), newest first. */
+  listForBuild(buildId: string, limit?: number): Promise<InsightRow[]>;
+  /** The health row for a project window, if any. */
+  getHealth(projectId: string, windowKey: string): Promise<InsightRow | null>;
+  markRunning(id: string): Promise<void>;
+  markDone(id: string, result: InsightResultInput): Promise<void>;
+  markFailed(id: string, errorCode: string): Promise<void>;
+  /** Explicitly remove all rows of a build (no reliance on FK cascade). */
+  removeForBuild(buildId: string): Promise<number>;
+  /** Remove health rows created before `cutoffIso`. */
+  purgeHealthBefore(cutoffIso: string): Promise<number>;
+  /** Mark pending/running rows older than `cutoffIso` as interrupted. */
+  sweepStale(cutoffIso: string): Promise<number>;
+  private removeWhere;
+  private findByKey;
+  private restartIfNeeded;
+  private col;
+}
+export { InsightModel, InsightResultInput, InsightStartInput, InsightStartResult, InsightTables };
+//# sourceMappingURL=insight.d.mts.map

package/dist/models/insight.mjs

@@ -0,0 +1,161 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { ulid } from "../utils/ulid.mjs";
+import { col } from "./columns.mjs";
+import { and, asc, desc, eq, inArray, isNull, lt } from "drizzle-orm";
+// src/models/insight.ts
+/** Insight rows: pending/running/done/failed runs with dedupe by unique key. */
+/** Data operations for insights. */
+var InsightModel = class {
+	tables;
+	db;
+	constructor(db, tables) {
+		this.db = db;
+		this.tables = tables ?? { insights: db.tables.insights };
+	}
+	/**
+	* Insert a `pending` row, or return the existing one for the same unique key
+	* (the dedupe: concurrent identical requests share one row). Failed rows,
+	* replaced health rows, and `force` restart the existing row in place.
+	*/
+	async start(input) {
+		const existing = await this.findByKey(input);
+		if (existing) return await this.restartIfNeeded(existing, input);
+		try {
+			return {
+				row: await this.db.insert(this.tables.insights, {
+					id: ulid(),
+					...pick(input),
+					status: "pending",
+					createdAt: (/* @__PURE__ */ new Date()).toISOString()
+				}),
+				run: true
+			};
+		} catch (error) {
+			const raced = await this.findByKey(input);
+			if (raced) return {
+				row: raced,
+				run: false
+			};
+			throw error;
+		}
+	}
+	/** The existing row for a run's unique key, without creating one. */
+	async peek(input) {
+		return await this.findByKey(input);
+	}
+	async get(id) {
+		return await this.db.get(this.tables.insights, id);
+	}
+	/** Newest triage rows for a build (any status), newest first. */
+	async listForBuild(buildId, limit = 20) {
+		return await this.db.list(this.tables.insights, {
+			where: and(eq(this.col("buildId"), buildId), eq(this.col("kind"), "triage")),
+			orderBy: desc(this.col("createdAt")),
+			limit
+		});
+	}
+	/** The health row for a project window, if any. */
+	async getHealth(projectId, windowKey) {
+		return (await this.db.list(this.tables.insights, {
+			where: and(eq(this.col("projectId"), projectId), eq(this.col("kind"), "health"), eq(this.col("windowKey"), windowKey)),
+			limit: 1
+		}))[0] ?? null;
+	}
+	async markRunning(id) {
+		await this.db.update(this.tables.insights, id, {
+			status: "running",
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	async markDone(id, result) {
+		await this.db.update(this.tables.insights, id, {
+			status: "done",
+			...result,
+			errorCode: null,
+			finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	async markFailed(id, errorCode) {
+		await this.db.update(this.tables.insights, id, {
+			status: "failed",
+			errorCode,
+			finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	/** Explicitly remove all rows of a build (no reliance on FK cascade). */
+	async removeForBuild(buildId) {
+		return await this.removeWhere(eq(this.col("buildId"), buildId));
+	}
+	/** Remove health rows created before `cutoffIso`. */
+	async purgeHealthBefore(cutoffIso) {
+		const where = and(eq(this.col("kind"), "health"), lt(this.col("createdAt"), cutoffIso));
+		return where ? await this.removeWhere(where) : 0;
+	}
+	/** Mark pending/running rows older than `cutoffIso` as interrupted. */
+	async sweepStale(cutoffIso) {
+		const stale = await this.db.list(this.tables.insights, { where: and(inArray(this.col("status"), ["pending", "running"]), lt(this.col("createdAt"), cutoffIso)) });
+		await Promise.all(stale.map(async (row) => {
+			await this.markFailed(row.id, "interrupted");
+		}));
+		return stale.length;
+	}
+	async removeWhere(where) {
+		const rows = await this.db.list(this.tables.insights, {
+			where,
+			orderBy: asc(this.col("id"))
+		});
+		await Promise.all(rows.map(async (row) => {
+			await this.db.remove(this.tables.insights, row.id);
+		}));
+		return rows.length;
+	}
+	async findByKey(input) {
+		const where = input.kind === "health" ? and(eq(this.col("projectId"), input.projectId), eq(this.col("kind"), "health"), input.windowKey === null ? isNull(this.col("windowKey")) : eq(this.col("windowKey"), input.windowKey)) : and(eq(this.col("projectId"), input.projectId), input.buildId === null ? isNull(this.col("buildId")) : eq(this.col("buildId"), input.buildId), eq(this.col("kind"), input.kind), eq(this.col("inputHash"), input.inputHash));
+		return (await this.db.list(this.tables.insights, {
+			where,
+			limit: 1
+		}))[0] ?? null;
+	}
+	async restartIfNeeded(existing, input) {
+		const inFlight = existing.status === "pending" || existing.status === "running";
+		const sameHash = existing.inputHash === input.inputHash;
+		if (inFlight || existing.status === "done" && sameHash && !input.force) return {
+			row: existing,
+			run: false
+		};
+		return {
+			row: await this.db.update(this.tables.insights, existing.id, {
+				...pick(input),
+				status: "pending",
+				verdict: null,
+				summary: null,
+				result: null,
+				errorCode: null,
+				startedAt: null,
+				finishedAt: null,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			}),
+			run: true
+		};
+	}
+	col(name) {
+		return col(this.tables.insights, name);
+	}
+};
+function pick(input) {
+	return {
+		projectId: input.projectId,
+		buildId: input.buildId,
+		kind: input.kind,
+		windowKey: input.windowKey,
+		inputHash: input.inputHash,
+		profile: input.profile,
+		model: input.model,
+		promptVersion: input.promptVersion
+	};
+}
+export { InsightModel };
+
+//# sourceMappingURL=insight.mjs.map

package/dist/models/insight.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight.mjs","names":[],"sources":["../../src/models/insight.ts"],"sourcesContent":["/** Insight rows: pending/running/done/failed runs with dedupe by unique key. */\nimport { and, asc, desc, eq, inArray, isNull, lt } from \"drizzle-orm\";\nimport type { SQL, SQLWrapper, Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { InsightKind, InsightRow } from \"../schema/insight.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { col } from \"./columns.ts\";\n\n/** Tables required by {@link InsightModel}. */\nexport interface InsightTables {\n  insights: Table;\n}\n\n/** Identity and metadata of a run to start. */\nexport interface InsightStartInput {\n  projectId: string;\n  buildId: string | null;\n  kind: InsightKind;\n  windowKey: string | null;\n  inputHash: string;\n  profile: string;\n  model: string;\n  promptVersion: string;\n  /** Re-run even when a finished row with the same hash exists. */\n  force?: boolean;\n}\n\n/** Outcome of {@link InsightModel.start}: the row and whether work must run. */\nexport interface InsightStartResult {\n  row: InsightRow;\n  /** True when the caller should run inference for this row. */\n  run: boolean;\n}\n\n/** Result payload stored on success. */\nexport interface InsightResultInput {\n  verdict: string;\n  summary: string;\n  result: string;\n}\n\n/** Data operations for insights. */\nexport class InsightModel {\n  private readonly tables: InsightTables;\n  private readonly db: DatabaseAdapter;\n\n  constructor(db: DatabaseAdapter, tables?: InsightTables) {\n    this.db = db;\n    this.tables = tables ?? { insights: db.tables.insights };\n  }\n\n  /**\n   * Insert a `pending` row, or return the existing one for the same unique key\n   * (the dedupe: concurrent identical requests share one row). Failed rows,\n   * replaced health rows, and `force` restart the existing row in place.\n   */\n  async start(input: InsightStartInput): Promise<InsightStartResult> {\n    const existing = await this.findByKey(input);\n    if (existing) {\n      return await this.restartIfNeeded(existing, input);\n    }\n    try {\n      const row = (await this.db.insert(this.tables.insights, {\n        id: ulid(),\n        ...pick(input),\n        status: \"pending\",\n        createdAt: new Date().toISOString(),\n      })) as unknown as InsightRow;\n      return { row, run: true };\n    } catch (error) {\n      const raced = await this.findByKey(input);\n      if (raced) {\n        return { row: raced, run: false };\n      }\n      throw error;\n    }\n  }\n\n  /** The existing row for a run's unique key, without creating one. */\n  async peek(input: InsightStartInput): Promise<InsightRow | null> {\n    return await this.findByKey(input);\n  }\n\n  async get(id: string): Promise<InsightRow | null> {\n    return (await this.db.get(this.tables.insights, id)) as unknown as InsightRow | null;\n  }\n\n  /** Newest triage rows for a build (any status), newest first. */\n  async listForBuild(buildId: string, limit = 20): Promise<InsightRow[]> {\n    return (await this.db.list(this.tables.insights, {\n      where: and(eq(this.col(\"buildId\"), buildId), eq(this.col(\"kind\"), \"triage\")),\n      orderBy: desc(this.col(\"createdAt\")),\n      limit,\n    })) as unknown as InsightRow[];\n  }\n\n  /** The health row for a project window, if any. */\n  async getHealth(projectId: string, windowKey: string): Promise<InsightRow | null> {\n    const rows = (await this.db.list(this.tables.insights, {\n      where: and(\n        eq(this.col(\"projectId\"), projectId),\n        eq(this.col(\"kind\"), \"health\"),\n        eq(this.col(\"windowKey\"), windowKey),\n      ),\n      limit: 1,\n    })) as unknown as InsightRow[];\n    return rows[0] ?? null;\n  }\n\n  async markRunning(id: string): Promise<void> {\n    await this.db.update(this.tables.insights, id, {\n      status: \"running\",\n      startedAt: new Date().toISOString(),\n    });\n  }\n\n  async markDone(id: string, result: InsightResultInput): Promise<void> {\n    await this.db.update(this.tables.insights, id, {\n      status: \"done\",\n      ...result,\n      errorCode: null,\n      finishedAt: new Date().toISOString(),\n    });\n  }\n\n  async markFailed(id: string, errorCode: string): Promise<void> {\n    await this.db.update(this.tables.insights, id, {\n      status: \"failed\",\n      errorCode,\n      finishedAt: new Date().toISOString(),\n    });\n  }\n\n  /** Explicitly remove all rows of a build (no reliance on FK cascade). */\n  async removeForBuild(buildId: string): Promise<number> {\n    return await this.removeWhere(eq(this.col(\"buildId\"), buildId));\n  }\n\n  /** Remove health rows created before `cutoffIso`. */\n  async purgeHealthBefore(cutoffIso: string): Promise<number> {\n    const where = and(eq(this.col(\"kind\"), \"health\"), lt(this.col(\"createdAt\"), cutoffIso));\n    return where ? await this.removeWhere(where) : 0;\n  }\n\n  /** Mark pending/running rows older than `cutoffIso` as interrupted. */\n  async sweepStale(cutoffIso: string): Promise<number> {\n    const stale = (await this.db.list(this.tables.insights, {\n      where: and(\n        inArray(this.col(\"status\"), [\"pending\", \"running\"]),\n        lt(this.col(\"createdAt\"), cutoffIso),\n      ),\n    })) as unknown as InsightRow[];\n    await Promise.all(\n      stale.map(async (row) => {\n        await this.markFailed(row.id, \"interrupted\");\n      }),\n    );\n    return stale.length;\n  }\n\n  private async removeWhere(where: SQL): Promise<number> {\n    const rows = (await this.db.list(this.tables.insights, {\n      where,\n      orderBy: asc(this.col(\"id\")),\n    })) as unknown as InsightRow[];\n    await Promise.all(\n      rows.map(async (row) => {\n        await this.db.remove(this.tables.insights, row.id);\n      }),\n    );\n    return rows.length;\n  }\n\n  private async findByKey(input: InsightStartInput): Promise<InsightRow | null> {\n    const where =\n      input.kind === \"health\"\n        ? and(\n            eq(this.col(\"projectId\"), input.projectId),\n            eq(this.col(\"kind\"), \"health\"),\n            input.windowKey === null\n              ? isNull(this.col(\"windowKey\"))\n              : eq(this.col(\"windowKey\"), input.windowKey),\n          )\n        : and(\n            eq(this.col(\"projectId\"), input.projectId),\n            input.buildId === null\n              ? isNull(this.col(\"buildId\"))\n              : eq(this.col(\"buildId\"), input.buildId),\n            eq(this.col(\"kind\"), input.kind),\n            eq(this.col(\"inputHash\"), input.inputHash),\n          );\n    const rows = (await this.db.list(this.tables.insights, {\n      where,\n      limit: 1,\n    })) as unknown as InsightRow[];\n    return rows[0] ?? null;\n  }\n\n  private async restartIfNeeded(\n    existing: InsightRow,\n    input: InsightStartInput,\n  ): Promise<InsightStartResult> {\n    const inFlight = existing.status === \"pending\" || existing.status === \"running\";\n    const sameHash = existing.inputHash === input.inputHash;\n    if (inFlight || (existing.status === \"done\" && sameHash && !input.force)) {\n      return { row: existing, run: false };\n    }\n    const row = (await this.db.update(this.tables.insights, existing.id, {\n      ...pick(input),\n      status: \"pending\",\n      verdict: null,\n      summary: null,\n      result: null,\n      errorCode: null,\n      startedAt: null,\n      finishedAt: null,\n      createdAt: new Date().toISOString(),\n    })) as unknown as InsightRow;\n    return { row, run: true };\n  }\n\n  private col(name: string): SQLWrapper {\n    return col(this.tables.insights, name);\n  }\n}\n\nfunction pick(input: InsightStartInput): Record<string, unknown> {\n  return {\n    projectId: input.projectId,\n    buildId: input.buildId,\n    kind: input.kind,\n    windowKey: input.windowKey,\n    inputHash: input.inputHash,\n    profile: input.profile,\n    model: input.model,\n    promptVersion: input.promptVersion,\n  };\n}\n"],"mappings":"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"}

package/dist/models/label.d.mts

@@ -3,7 +3,6 @@ import __tsdown_shims_url from 'node:url';
 import { DatabaseAdapter } from "../adapter/database.mjs";
 import { BuildLabel, LabelType } from "../schema/label.mjs";
 import { Table } from "drizzle-orm";
-//#region src/models/label.d.ts
 /** Tables required by {@link LabelModel}. */
 interface LabelTables {
   builds: Table;
@@ -12,8 +11,8 @@ interface LabelTables {
 }
 /** Data operations for label types and build labels. */
 declare class LabelModel {
-  private readonly db;
   private readonly tables;
+  private readonly db;
   /**
    * @param db - Database adapter.
    * @param tables - Table handles.
@@ -50,9 +49,10 @@ declare class LabelModel {
   listForBuild(buildId: string): Promise<BuildLabel[]>;
   /** Return the id of the latest build carrying a given label value, if any. */
   latestBuildId(projectId: string, typeKey: string, value: string): Promise<string | null>;
-  /** Return whether a build is marked as persistent. */
+  /** Whether a build is marked as persistent. */
   hasPersistent(projectId: string, buildId: string): Promise<boolean>;
+  /** Ids of the project's builds marked persistent (exempt from retention). */
+  persistentBuildIds(projectId: string): Promise<Set<string>>;
 }
-//#endregion
 export { LabelModel, LabelTables };
 //# sourceMappingURL=label.d.mts.map