@storyshelf/core 0.6.1 → 0.7.0

package/dist/models/webhook.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.mjs","names":[],"sources":["../../src/models/webhook.ts"],"sourcesContent":["/** Webhook subscriptions for project events. */\nimport { eq, getTableColumns } from \"drizzle-orm\";\nimport type { SQLWrapper, Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Webhook } from \"../schema/webhook.ts\";\nimport { decryptCredential, encrypt, type SecretInput } from \"../utils/encrypt.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\n\n/** Tables required by {@link WebhookModel}. */\nexport interface WebhookTables {\n  webhooks: Table;\n}\n\n/** Data operations for webhook subscriptions. */\nexport class WebhookModel {\n  private readonly tables: WebhookTables;\n  private readonly secret?: SecretInput;\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   * @param secret - Server secret for webhook-secret encryption (throws on write/decrypt when unset).\n   */\n  constructor(\n    private readonly db: DatabaseAdapter,\n    tables?: WebhookTables,\n    secret?: SecretInput,\n  ) {\n    this.tables = tables ?? { webhooks: db.tables.webhooks };\n    this.secret = secret;\n  }\n\n  /** List all webhooks for a project. */\n  async list(projectId: string): Promise<Webhook[]> {\n    return (await this.db.list(this.tables.webhooks, {\n      where: eq(\n        getTableColumns(this.tables.webhooks)[\"projectId\"] as unknown as SQLWrapper,\n        projectId,\n      ),\n    })) as unknown as Webhook[];\n  }\n\n  /**\n   * Create a webhook subscription for a project.\n   *\n   * @param projectId - Project ID.\n   * @param input - Webhook creation input.\n   * @returns The created webhook.\n   */\n  async create(projectId: string, input: WebhookCreateInput): Promise<Webhook> {\n    const now = new Date().toISOString();\n    return (await this.db.insert(this.tables.webhooks, {\n      id: ulid(),\n      projectId,\n      url: input.url,\n      secretEncrypted: encrypt(this.secret, input.secret),\n      events: input.events && input.events.length > 0 ? JSON.stringify(input.events) : null,\n      createdAt: now,\n      updatedAt: now,\n    })) as unknown as Webhook;\n  }\n\n  /** Decrypt the secret for a stored row (in memory only, at send time). */\n  decryptSecret(row: Webhook): string {\n    return decryptCredential(this.secret, row.secretEncrypted);\n  }\n\n  /** Fetch a webhook by id scoped to a project, or null if not found. */\n  async get(projectId: string, id: string): Promise<Webhook | null> {\n    const rows = (await this.db.list(this.tables.webhooks, {\n      where: eq(getTableColumns(this.tables.webhooks)[\"id\"] as unknown as SQLWrapper, id),\n      limit: 1,\n    })) as unknown as Webhook[];\n    const found = rows[0] ?? null;\n    return found?.projectId === projectId ? found : null;\n  }\n\n  /** Remove a webhook if it belongs to the given project. */\n  async remove(projectId: string, id: string): Promise<void> {\n    const existing = await this.get(projectId, id);\n    if (existing) {\n      await this.db.remove(this.tables.webhooks, existing.id);\n    }\n  }\n\n  /** Decode the JSON-serialized event list of a webhook. */\n  static eventsOf(webhook: Webhook): string[] {\n    if (!webhook.events) {\n      return [];\n    }\n    try {\n      const parsed: unknown = JSON.parse(webhook.events);\n      return Array.isArray(parsed)\n        ? parsed.filter((event): event is string => typeof event === \"string\")\n        : [];\n    } catch {\n      return [];\n    }\n  }\n}\n\n/** Input for creating a webhook subscription. */\nexport interface WebhookCreateInput {\n  url: string;\n  events?: string[];\n  secret: string;\n}\n"],"mappings":";;;;;;;;;AAcA,IAAa,eAAb,MAA0B;CASL;CARnB;CACA;;;;;;CAMA,YACE,IACA,QACA,QACA;EAHiB,KAAA,KAAA;EAIjB,KAAK,SAAS,UAAU,EAAE,UAAU,GAAG,OAAO,SAAS;EACvD,KAAK,SAAS;CAChB;;CAGA,MAAM,KAAK,WAAuC;EAChD,OAAQ,MAAM,KAAK,GAAG,KAAK,KAAK,OAAO,UAAU,EAC/C,OAAO,GACL,gBAAgB,KAAK,OAAO,QAAQ,CAAC,CAAC,cACtC,SACF,EACF,CAAC;CACH;;;;;;;;CASA,MAAM,OAAO,WAAmB,OAA6C;EAC3E,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,UAAU;GACjD,IAAI,KAAK;GACT;GACA,KAAK,MAAM;GACX,iBAAiB,QAAQ,KAAK,QAAQ,MAAM,MAAM;GAClD,QAAQ,MAAM,UAAU,MAAM,OAAO,SAAS,IAAI,KAAK,UAAU,MAAM,MAAM,IAAI;GACjF,WAAW;GACX,WAAW;EACb,CAAC;CACH;;CAGA,cAAc,KAAsB;EAClC,OAAO,kBAAkB,KAAK,QAAQ,IAAI,eAAe;CAC3D;;CAGA,MAAM,IAAI,WAAmB,IAAqC;EAKhE,MAAM,SAAQ,MAJM,KAAK,GAAG,KAAK,KAAK,OAAO,UAAU;GACrD,OAAO,GAAG,gBAAgB,KAAK,OAAO,QAAQ,CAAC,CAAC,OAAgC,EAAE;GAClF,OAAO;EACT,CAAC,EAAA,CACkB,MAAM;EACzB,OAAO,OAAO,cAAc,YAAY,QAAQ;CAClD;;CAGA,MAAM,OAAO,WAAmB,IAA2B;EACzD,MAAM,WAAW,MAAM,KAAK,IAAI,WAAW,EAAE;EAC7C,IAAI,UACF,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,UAAU,SAAS,EAAE;CAE1D;;CAGA,OAAO,SAAS,SAA4B;EAC1C,IAAI,CAAC,QAAQ,QACX,OAAO,CAAC;EAEV,IAAI;GACF,MAAM,SAAkB,KAAK,MAAM,QAAQ,MAAM;GACjD,OAAO,MAAM,QAAQ,MAAM,IACvB,OAAO,QAAQ,UAA2B,OAAO,UAAU,QAAQ,IACnE,CAAC;EACP,QAAQ;GACN,OAAO,CAAC;EACV;CACF;AACF"}
+{"version":3,"file":"webhook.mjs","names":[],"sources":["../../src/models/webhook.ts"],"sourcesContent":["/** Webhook subscriptions for project events. */\nimport { eq } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Webhook } from \"../schema/webhook.ts\";\nimport { decryptCredential, encrypt, type SecretInput } from \"../utils/encrypt.ts\";\nimport { randomToken } from \"../utils/hash.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { col } from \"./columns.ts\";\n\n/** Tables required by {@link WebhookModel}. */\nexport interface WebhookTables {\n  webhooks: Table;\n}\n\n/** Data operations for webhook subscriptions. */\nexport class WebhookModel {\n  private readonly tables: WebhookTables;\n  private readonly secret?: SecretInput;\n  private readonly db: DatabaseAdapter;\n\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   * @param secret - Server secret for webhook-secret encryption (throws on write/decrypt when unset).\n   */\n  constructor(db: DatabaseAdapter, tables?: WebhookTables, secret?: SecretInput) {\n    this.db = db;\n    this.tables = tables ?? { webhooks: db.tables.webhooks };\n    this.secret = secret;\n  }\n\n  /** List all webhooks for a project. */\n  async list(projectId: string): Promise<Webhook[]> {\n    return (await this.db.list(this.tables.webhooks, {\n      where: eq(col(this.tables.webhooks, \"projectId\"), projectId),\n    })) as unknown as Webhook[];\n  }\n\n  /** Validate a webhook target URL; returns an error message, or null when acceptable. */\n  static urlError(url: string | undefined): string | null {\n    if (!url) {\n      return \"A valid URL is required\";\n    }\n    let protocol: string;\n    try {\n      ({ protocol } = new URL(url));\n    } catch {\n      return \"Enter a valid URL\";\n    }\n    return protocol === \"https:\" || protocol === \"http:\" ? null : \"URL must use http or https\";\n  }\n\n  /**\n   * Create a webhook with a freshly generated `whsec_` signing secret.\n   *\n   * @returns The stored webhook and the plaintext secret (shown to the user once).\n   */\n  async issue(\n    projectId: string,\n    input: { url: string; events?: string[] },\n  ): Promise<{ webhook: Webhook; secret: string }> {\n    const secret = randomToken(\"whsec_\").value;\n    const webhook = await this.create(projectId, { url: input.url, events: input.events, secret });\n    return { webhook, secret };\n  }\n\n  /**\n   * Create a webhook subscription for a project.\n   *\n   * @param projectId - Project ID.\n   * @param input - Webhook creation input.\n   * @returns The created webhook.\n   */\n  async create(projectId: string, input: WebhookCreateInput): Promise<Webhook> {\n    const now = new Date().toISOString();\n    return (await this.db.insert(this.tables.webhooks, {\n      id: ulid(),\n      projectId,\n      url: input.url,\n      secretEncrypted: encrypt(this.secret, input.secret),\n      events: input.events && input.events.length > 0 ? JSON.stringify(input.events) : null,\n      createdAt: now,\n      updatedAt: now,\n    })) as unknown as Webhook;\n  }\n\n  /** Decrypt the secret for a stored row (in memory only, at send time). */\n  decryptSecret(row: Webhook): string {\n    return decryptCredential(this.secret, row.secretEncrypted);\n  }\n\n  /** Fetch a webhook by id scoped to a project, or null if not found. */\n  async get(projectId: string, id: string): Promise<Webhook | null> {\n    const rows = (await this.db.list(this.tables.webhooks, {\n      where: eq(col(this.tables.webhooks, \"id\"), id),\n      limit: 1,\n    })) as unknown as Webhook[];\n    const found = rows[0] ?? null;\n    return found?.projectId === projectId ? found : null;\n  }\n\n  /** Remove a webhook if it belongs to the given project. */\n  async remove(projectId: string, id: string): Promise<void> {\n    const existing = await this.get(projectId, id);\n    if (existing) {\n      await this.db.remove(this.tables.webhooks, existing.id);\n    }\n  }\n\n  /** Decode the JSON-serialized event list of a webhook. */\n  static eventsOf(webhook: Webhook): string[] {\n    if (!webhook.events) {\n      return [];\n    }\n    try {\n      const parsed: unknown = JSON.parse(webhook.events);\n      return Array.isArray(parsed)\n        ? parsed.filter((event): event is string => typeof event === \"string\")\n        : [];\n    } catch {\n      return [];\n    }\n  }\n}\n\n/** Input for creating a webhook subscription. */\nexport interface WebhookCreateInput {\n  url: string;\n  events?: string[];\n  secret: string;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,IAAa,eAAb,MAA0B;CACxB;CACA;CACA;;;;;;CAOA,YAAY,IAAqB,QAAwB,QAAsB;EAC7E,KAAK,KAAK;EACV,KAAK,SAAS,UAAU,EAAE,UAAU,GAAG,OAAO,SAAS;EACvD,KAAK,SAAS;CAChB;;CAGA,MAAM,KAAK,WAAuC;EAChD,OAAQ,MAAM,KAAK,GAAG,KAAK,KAAK,OAAO,UAAU,EAC/C,OAAO,GAAG,IAAI,KAAK,OAAO,UAAU,WAAW,GAAG,SAAS,EAC7D,CAAC;CACH;;CAGA,OAAO,SAAS,KAAwC;EACtD,IAAI,CAAC,KACH,OAAO;EAET,IAAI;EACJ,IAAI;GACF,CAAC,CAAE,YAAa,IAAI,IAAI,GAAG;EAC7B,QAAQ;GACN,OAAO;EACT;EACA,OAAO,aAAa,YAAY,aAAa,UAAU,OAAO;CAChE;;;;;;CAOA,MAAM,MACJ,WACA,OAC+C;EAC/C,MAAM,SAAS,YAAY,QAAQ,CAAC,CAAC;EAErC,OAAO;GAAE,SAAA,MADa,KAAK,OAAO,WAAW;IAAE,KAAK,MAAM;IAAK,QAAQ,MAAM;IAAQ;GAAO,CAAC;GAC3E;EAAO;CAC3B;;;;;;;;CASA,MAAM,OAAO,WAAmB,OAA6C;EAC3E,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,UAAU;GACjD,IAAI,KAAK;GACT;GACA,KAAK,MAAM;GACX,iBAAiB,QAAQ,KAAK,QAAQ,MAAM,MAAM;GAClD,QAAQ,MAAM,UAAU,MAAM,OAAO,SAAS,IAAI,KAAK,UAAU,MAAM,MAAM,IAAI;GACjF,WAAW;GACX,WAAW;EACb,CAAC;CACH;;CAGA,cAAc,KAAsB;EAClC,OAAO,kBAAkB,KAAK,QAAQ,IAAI,eAAe;CAC3D;;CAGA,MAAM,IAAI,WAAmB,IAAqC;EAKhE,MAAM,SAAQ,MAJM,KAAK,GAAG,KAAK,KAAK,OAAO,UAAU;GACrD,OAAO,GAAG,IAAI,KAAK,OAAO,UAAU,IAAI,GAAG,EAAE;GAC7C,OAAO;EACT,CAAC,EAAA,CACkB,MAAM;EACzB,OAAO,OAAO,cAAc,YAAY,QAAQ;CAClD;;CAGA,MAAM,OAAO,WAAmB,IAA2B;EACzD,MAAM,WAAW,MAAM,KAAK,IAAI,WAAW,EAAE;EAC7C,IAAI,UACF,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,UAAU,SAAS,EAAE;CAE1D;;CAGA,OAAO,SAAS,SAA4B;EAC1C,IAAI,CAAC,QAAQ,QACX,OAAO,CAAC;EAEV,IAAI;GACF,MAAM,SAAkB,KAAK,MAAM,QAAQ,MAAM;GACjD,OAAO,MAAM,QAAQ,MAAM,IACvB,OAAO,QAAQ,UAA2B,OAAO,UAAU,QAAQ,IACnE,CAAC;EACP,QAAQ;GACN,OAAO,CAAC;EACV;CACF;AACF"}

package/dist/models.d.mts

@@ -7,16 +7,39 @@ import { CaptureLogModel, CaptureLogTables } from "./models/capture-log.mjs";
 import { ProjectCreateInput, ProjectModel } from "./models/project.mjs";
 import { BaselineModel } from "./models/baseline.mjs";
 import { SnapshotCreateInput, SnapshotModel } from "./models/snapshot.mjs";
-import { StatusConfigCreateInput, StatusConfigModel } from "./models/status-config.mjs";
+import { AttemptClaim, CaptureJobModel, CaptureJobTables, NewCaptureJob, TERMINAL_JOB_STATUSES, attemptRowId, isTerminalJob, parseAttemptRowId } from "./models/capture-job.mjs";
+import { BuildComponentInput, BuildComponentModel, BuildComponentTables } from "./models/build-component.mjs";
+import { ComponentHistoryRow, ComponentPresence, componentHistory, componentPresence, worstStatus } from "./models/component.mjs";
+import { BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_ARCHIVE_VERSION, BaselineArchiveError, BaselineManifest, BaselineManifestEntry } from "./models/baseline-archive.mjs";
+import { BaselineExportOptions } from "./models/baseline-export.mjs";
+import { BaselineImportResult, BaselineTransferModel } from "./models/baseline-transfer.mjs";
 import { BaselineStatus, NO_BASELINE, baselineStatus, isBaselineDrifted } from "./models/baseline-status.mjs";
+import { CaptureShardModel, CaptureShardTables } from "./models/capture-shard.mjs";
+import { AiBudgetAlertModel, AiBudgetAlertTables } from "./models/ai-budget-alert.mjs";
+import { AiUsageInput, AiUsageModel, AiUsageTables } from "./models/ai-usage.mjs";
+import { InsightModel, InsightResultInput, InsightStartInput, InsightStartResult, InsightTables } from "./models/insight.mjs";
+import { InheritedRatio, RECENT_BUILDS_FOR_INHERITED_RATIO, averageInheritedRatio } from "./models/inherited-ratio.mjs";
+import { BuildReviewModel, BuildReviewTables } from "./models/build-review.mjs";
+import { ReviewStatusInput, deriveReviewStatus, latestVerdicts } from "./models/build-review-status.mjs";
+import { BuildChangeset, ChangedComponent, Changeset, ChangesetComponent, changesetOf, computeChangeset, findChangesetBaseline } from "./models/changeset.mjs";
 import { CommentCreateInput, CommentModel } from "./models/comment.mjs";
+import { acceptPendingWithoutWork } from "./models/review-switch-off.mjs";
+import { ConnectionModel, ConnectionTables } from "./models/connections.mjs";
+import { DesignModel, DesignTables } from "./models/design.mjs";
+import { DesignCredentialStatus, DesignResolution, DesignSource, normalizeImportPath, resolveDesigns } from "./models/design-resolve.mjs";
+import { DesignCredentialModel, DesignCredentialTables, PROJECT_SCOPE } from "./models/design-credentials.mjs";
+import { DesignNodeModel, DesignNodeTables, RefreshOptions } from "./models/design-nodes.mjs";
+import { DESIGN_TTL_MS, credentialDaysLeft, isDesignStale } from "./models/design-health.mjs";
 import { LabelModel } from "./models/label.mjs";
+import { PackageUsageInput, PackageUsageModel, PackageUsageTables, UpstreamStory, matchUpstreamStory } from "./models/usage.mjs";
 import { MemberModel } from "./models/member.mjs";
-import { NotificationChannelCreateInput, NotificationChannelModel, NotificationChannelTables } from "./models/notification-channel.mjs";
+import { ChannelValidation, NotificationChannelCreateInput, NotificationChannelModel, NotificationChannelTables } from "./models/notification-channel.mjs";
 import { NotificationSubscriptionInput, NotificationSubscriptionModel, NotificationSubscriptionTables } from "./models/notification-subscription.mjs";
 import { ProjectGroupMappingModel } from "./models/project-group-mapping.mjs";
 import { TokenModel } from "./models/token.mjs";
 import { UserModel } from "./models/user.mjs";
 import { ContentRefModel } from "./models/content-ref.mjs";
 import { CredentialProbe, ReencryptResult, UnreadableCredential, probeCredentials, reencryptCredentials } from "./models/credentials.mjs";
-export { type AttemptLogRecorder, BaselineModel, type BaselineStatus, type BuildCreateInput, type BuildListFilter, BuildModel, CaptureAttemptModel, type CaptureAttemptTables, CaptureLogModel, type CaptureLogTables, type CommentCreateInput, CommentModel, ContentRefModel, type CredentialProbe, LabelModel, MemberModel, NO_BASELINE, type NotificationChannelCreateInput, NotificationChannelModel, type NotificationChannelTables, type NotificationSubscriptionInput, NotificationSubscriptionModel, type NotificationSubscriptionTables, type ProjectCreateInput, ProjectGroupMappingModel, ProjectModel, type ReencryptResult, type SnapshotCreateInput, SnapshotModel, type StatusConfigCreateInput, StatusConfigModel, TokenModel, type UnreadableCredential, UserModel, type WebhookCreateInput, WebhookModel, baselineStatus, emitAttemptLog, isBaselineDrifted, isPublicBuild, probeCredentials, reencryptCredentials };
+import { SiteSettingsModel, SiteSettingsTables } from "./models/site-settings.mjs";
+import { PUBLIC_ORIGIN_KEY, PublicOriginOptions, PublicOriginResolver, PublicOriginSource, ResolvedPublicOrigin, StoredPublicOrigin, createPublicOriginResolver } from "./models/public-origin.mjs";
+export { AiBudgetAlertModel, type AiBudgetAlertTables, type AiUsageInput, AiUsageModel, type AiUsageTables, type AttemptClaim, type AttemptLogRecorder, BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_ARCHIVE_VERSION, BaselineArchiveError, type BaselineExportOptions, type BaselineImportResult, type BaselineManifest, type BaselineManifestEntry, BaselineModel, type BaselineStatus, BaselineTransferModel, type BuildChangeset, type BuildComponentInput, BuildComponentModel, type BuildComponentTables, type BuildCreateInput, type BuildListFilter, BuildModel, BuildReviewModel, type BuildReviewTables, CaptureAttemptModel, type CaptureAttemptTables, CaptureJobModel, type CaptureJobTables, CaptureLogModel, type CaptureLogTables, CaptureShardModel, type CaptureShardTables, type ChangedComponent, type Changeset, type ChangesetComponent, type ChannelValidation, type CommentCreateInput, CommentModel, type ComponentHistoryRow, type ComponentPresence, ConnectionModel, type ConnectionTables, ContentRefModel, type CredentialProbe, DESIGN_TTL_MS, DesignCredentialModel, type DesignCredentialStatus, type DesignCredentialTables, DesignModel, DesignNodeModel, type DesignNodeTables, type DesignResolution, type DesignSource, type DesignTables, type InheritedRatio, InsightModel, type InsightResultInput, type InsightStartInput, type InsightStartResult, type InsightTables, LabelModel, MemberModel, NO_BASELINE, type NewCaptureJob, type NotificationChannelCreateInput, NotificationChannelModel, type NotificationChannelTables, type NotificationSubscriptionInput, NotificationSubscriptionModel, type NotificationSubscriptionTables, PROJECT_SCOPE, PUBLIC_ORIGIN_KEY, type PackageUsageInput, PackageUsageModel, type PackageUsageTables, type ProjectCreateInput, ProjectGroupMappingModel, ProjectModel, type PublicOriginOptions, type PublicOriginResolver, type PublicOriginSource, RECENT_BUILDS_FOR_INHERITED_RATIO, type ReencryptResult, type RefreshOptions, type ResolvedPublicOrigin, type ReviewStatusInput, SiteSettingsModel, type SiteSettingsTables, type SnapshotCreateInput, SnapshotModel, type StoredPublicOrigin, TERMINAL_JOB_STATUSES, TokenModel, type UnreadableCredential, type UpstreamStory, UserModel, type WebhookCreateInput, WebhookModel, acceptPendingWithoutWork, attemptRowId, averageInheritedRatio, baselineStatus, changesetOf, componentHistory, componentPresence, computeChangeset, createPublicOriginResolver, credentialDaysLeft, deriveReviewStatus, emitAttemptLog, findChangesetBaseline, isBaselineDrifted, isDesignStale, isPublicBuild, isTerminalJob, latestVerdicts, matchUpstreamStory, normalizeImportPath, parseAttemptRowId, probeCredentials, reencryptCredentials, resolveDesigns, worstStatus };

package/dist/models.mjs

@@ -2,22 +2,44 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { WebhookModel } from "./models/webhook.mjs";
-import { BuildModel, isPublicBuild } from "./models/build.mjs";
 import { CaptureAttemptModel, emitAttemptLog } from "./models/capture-attempt.mjs";
-import { ProjectModel } from "./models/project.mjs";
+import { BuildModel, isPublicBuild } from "./models/build.mjs";
 import { BaselineModel } from "./models/baseline.mjs";
 import { NO_BASELINE, baselineStatus, isBaselineDrifted } from "./models/baseline-status.mjs";
 import { SnapshotModel } from "./models/snapshot.mjs";
-import { StatusConfigModel } from "./models/status-config.mjs";
+import { CaptureShardModel } from "./models/capture-shard.mjs";
+import { ProjectModel } from "./models/project.mjs";
+import { deriveReviewStatus, latestVerdicts } from "./models/build-review-status.mjs";
+import { BuildReviewModel } from "./models/build-review.mjs";
+import { NotificationChannelModel } from "./models/notification-channel.mjs";
+import { CaptureJobModel, TERMINAL_JOB_STATUSES, attemptRowId, isTerminalJob, parseAttemptRowId } from "./models/capture-job.mjs";
+import { SiteSettingsModel } from "./models/site-settings.mjs";
+import { PUBLIC_ORIGIN_KEY, createPublicOriginResolver } from "./models/public-origin.mjs";
 import { CaptureLogModel } from "./models/capture-log.mjs";
+import { BuildComponentModel } from "./models/build-component.mjs";
+import { normalizeImportPath, resolveDesigns } from "./models/design-resolve.mjs";
+import { BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_ARCHIVE_VERSION, BaselineArchiveError } from "./models/baseline-archive.mjs";
+import { BaselineTransferModel } from "./models/baseline-transfer.mjs";
+import { AiBudgetAlertModel } from "./models/ai-budget-alert.mjs";
+import { AiUsageModel } from "./models/ai-usage.mjs";
+import { InsightModel } from "./models/insight.mjs";
+import { RECENT_BUILDS_FOR_INHERITED_RATIO, averageInheritedRatio } from "./models/inherited-ratio.mjs";
+import { changesetOf, computeChangeset, findChangesetBaseline } from "./models/changeset.mjs";
 import { CommentModel } from "./models/comment.mjs";
+import { acceptPendingWithoutWork } from "./models/review-switch-off.mjs";
+import { componentHistory, componentPresence, worstStatus } from "./models/component.mjs";
+import { ConnectionModel } from "./models/connections.mjs";
+import { DesignModel } from "./models/design.mjs";
+import { DesignCredentialModel, PROJECT_SCOPE } from "./models/design-credentials.mjs";
+import { DESIGN_TTL_MS, credentialDaysLeft, isDesignStale } from "./models/design-health.mjs";
+import { DesignNodeModel } from "./models/design-nodes.mjs";
 import { LabelModel } from "./models/label.mjs";
+import { PackageUsageModel, matchUpstreamStory } from "./models/usage.mjs";
 import { MemberModel } from "./models/member.mjs";
-import { NotificationChannelModel } from "./models/notification-channel.mjs";
 import { NotificationSubscriptionModel } from "./models/notification-subscription.mjs";
 import { ProjectGroupMappingModel } from "./models/project-group-mapping.mjs";
 import { TokenModel } from "./models/token.mjs";
 import { UserModel } from "./models/user.mjs";
 import { ContentRefModel } from "./models/content-ref.mjs";
 import { probeCredentials, reencryptCredentials } from "./models/credentials.mjs";
-export { BaselineModel, BuildModel, CaptureAttemptModel, CaptureLogModel, CommentModel, ContentRefModel, LabelModel, MemberModel, NO_BASELINE, NotificationChannelModel, NotificationSubscriptionModel, ProjectGroupMappingModel, ProjectModel, SnapshotModel, StatusConfigModel, TokenModel, UserModel, WebhookModel, baselineStatus, emitAttemptLog, isBaselineDrifted, isPublicBuild, probeCredentials, reencryptCredentials };
+export { AiBudgetAlertModel, AiUsageModel, BASELINE_ARCHIVE_FORMAT, BASELINE_ARCHIVE_LIMITS, BASELINE_ARCHIVE_VERSION, BaselineArchiveError, BaselineModel, BaselineTransferModel, BuildComponentModel, BuildModel, BuildReviewModel, CaptureAttemptModel, CaptureJobModel, CaptureLogModel, CaptureShardModel, CommentModel, ConnectionModel, ContentRefModel, DESIGN_TTL_MS, DesignCredentialModel, DesignModel, DesignNodeModel, InsightModel, LabelModel, MemberModel, NO_BASELINE, NotificationChannelModel, NotificationSubscriptionModel, PROJECT_SCOPE, PUBLIC_ORIGIN_KEY, PackageUsageModel, ProjectGroupMappingModel, ProjectModel, RECENT_BUILDS_FOR_INHERITED_RATIO, SiteSettingsModel, SnapshotModel, TERMINAL_JOB_STATUSES, TokenModel, UserModel, WebhookModel, acceptPendingWithoutWork, attemptRowId, averageInheritedRatio, baselineStatus, changesetOf, componentHistory, componentPresence, computeChangeset, createPublicOriginResolver, credentialDaysLeft, deriveReviewStatus, emitAttemptLog, findChangesetBaseline, isBaselineDrifted, isDesignStale, isPublicBuild, isTerminalJob, latestVerdicts, matchUpstreamStory, normalizeImportPath, parseAttemptRowId, probeCredentials, reencryptCredentials, resolveDesigns, worstStatus };

package/dist/options.d.mts

@@ -0,0 +1,18 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ShelfOptions } from "./config.mjs";
+//#region src/options.d.ts
+/** Where capture scratch lives when `config.scratchDir` is not set. */
+declare const DEFAULT_SCRATCH_DIR: string;
+/**
+ * Validate and complete the options.
+ *
+ * - `testing.compare.threads` must be a non-negative integer.
+ * - `notifications.config` must match its schema (it used to live in `ShelfConfig`, which validated it).
+ * - `config.scratchDir` defaults to {@link DEFAULT_SCRATCH_DIR}: publishing extracts zips there,
+ *   with or without `testing`.
+ */
+declare function resolveShelfOptions(options: ShelfOptions): ShelfOptions;
+//#endregion
+export { DEFAULT_SCRATCH_DIR, resolveShelfOptions };
+//# sourceMappingURL=options.d.mts.map

package/dist/options.mjs

@@ -0,0 +1,90 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { notificationsConfigSchema } from "./config.mjs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+//#region src/options.ts
+/** Resolves `ShelfOptions` once at boot: validates `testing.compare` and fills the scratch default. */
+/** Where capture scratch lives when `config.scratchDir` is not set. */
+const DEFAULT_SCRATCH_DIR = join(tmpdir(), "storyshelf");
+/**
+* Validate and complete the options.
+*
+* - `testing.compare.threads` must be a non-negative integer.
+* - `notifications.config` must match its schema (it used to live in `ShelfConfig`, which validated it).
+* - `config.scratchDir` defaults to {@link DEFAULT_SCRATCH_DIR}: publishing extracts zips there,
+*   with or without `testing`.
+*/
+function resolveShelfOptions(options) {
+	assertThreads(options.testing?.compare?.threads);
+	assertTestingProcess(options.testing);
+	assertTestingBackable(options);
+	assertNotificationsConfig(options.notifications?.config);
+	if (options.config?.scratchDir !== void 0) return options;
+	return {
+		...options,
+		config: {
+			...options.config,
+			scratchDir: DEFAULT_SCRATCH_DIR
+		}
+	};
+}
+/**
+* A `testing` instance renders here, so it needs a database a long-running server can keep.
+*/
+function assertTestingBackable(options) {
+	if (options.testing === void 0) return;
+	if (options.database.metadata.supportsTesting === false) throw new Error(`The ${options.database.metadata.name} database cannot back testing: it is reachable only from a platform that ends the process after each request, so nothing would run capture jobs. Remove the testing option to host Storybooks only, or use a network database (Turso, Postgres, MySQL, SQLite on a volume).`);
+}
+function assertTestingProcess(testing) {
+	if (testing !== void 0 && testing.runner === void 0) throw new Error("testing requires testing.runner");
+	if (testing?.workerEntry !== void 0 && testing.runner === void 0) throw new Error("testing.workerEntry requires testing.runner (it is the in-process fallback)");
+	if (testing?.mode === "fork" && testing.workerEntry === void 0) throw new Error("testing.mode \"fork\" requires testing.workerEntry");
+	assertShardSize(testing);
+	assertTestingNumbers(testing);
+}
+/** Numeric `testing` options: concurrency, retries and the Storybook URL rate limit. */
+function assertTestingNumbers(testing) {
+	assertConcurrency(testing?.concurrency);
+	assertRetries(testing?.retries);
+	assertLeaseSeconds(testing?.leaseSeconds);
+	assertStorybookUrlRateLimit(testing?.storybookUrlRateLimit);
+}
+/** A whole number of requests per minute; `0` would refuse every render. */
+function assertStorybookUrlRateLimit(limit) {
+	if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1)) throw new Error(`testing.storybookUrlRateLimit must be a positive whole number of requests per minute, got ${String(limit)}`);
+}
+/** Retries are counted after the first attempt: `0` runs a job once. */
+function assertRetries(retries) {
+	if (retries !== void 0 && (!Number.isInteger(retries) || retries < 0)) throw new Error(`testing.retries must be a non-negative integer, got ${String(retries)}`);
+}
+/** A lease must be a positive length: `0` would expire every job at once. */
+function assertLeaseSeconds(seconds) {
+	if (seconds !== void 0 && (!Number.isFinite(seconds) || seconds <= 0)) throw new Error(`testing.leaseSeconds must be a positive number of seconds, got ${String(seconds)}`);
+}
+/** `0` would deadlock the consumer. */
+function assertConcurrency(concurrency) {
+	if (concurrency !== void 0 && (!Number.isInteger(concurrency) || concurrency < 1)) throw new Error(`testing.concurrency must be a positive integer, got ${String(concurrency)}`);
+}
+function assertShardSize(testing) {
+	const size = testing?.shardSize;
+	if (size === void 0) return;
+	if (!Number.isInteger(size) || size < 1) throw new Error(`testing.shardSize must be a positive integer, got ${String(size)}`);
+	if (testing?.runner === void 0) throw new Error("testing.shardSize requires testing.runner (workers set their own shardSize)");
+}
+function assertThreads(threads) {
+	if (threads !== void 0 && (!Number.isInteger(threads) || threads < 0)) throw new Error(`testing.compare.threads must be a non-negative integer, got ${String(threads)}`);
+}
+function assertNotificationsConfig(config) {
+	if (config === void 0) return;
+	const result = notificationsConfigSchema.safeParse(config);
+	if (!result.success) {
+		const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+		throw new Error(`Invalid notifications.config: ${issues}`);
+	}
+}
+//#endregion
+export { DEFAULT_SCRATCH_DIR, resolveShelfOptions };
+
+//# sourceMappingURL=options.mjs.map

package/dist/options.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.mjs","names":[],"sources":["../src/options.ts"],"sourcesContent":["/** Resolves `ShelfOptions` once at boot: validates `testing.compare` and fills the scratch default. */\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { notificationsConfigSchema, type ShelfOptions } from \"./config.ts\";\n\n/** Where capture scratch lives when `config.scratchDir` is not set. */\nexport const DEFAULT_SCRATCH_DIR: string = join(tmpdir(), \"storyshelf\");\n\n/**\n * Validate and complete the options.\n *\n * - `testing.compare.threads` must be a non-negative integer.\n * - `notifications.config` must match its schema (it used to live in `ShelfConfig`, which validated it).\n * - `config.scratchDir` defaults to {@link DEFAULT_SCRATCH_DIR}: publishing extracts zips there,\n *   with or without `testing`.\n */\nexport function resolveShelfOptions(options: ShelfOptions): ShelfOptions {\n  assertThreads(options.testing?.compare?.threads);\n  assertTestingProcess(options.testing);\n  assertTestingBackable(options);\n  assertNotificationsConfig(options.notifications?.config);\n  if (options.config?.scratchDir !== undefined) {\n    return options;\n  }\n  return { ...options, config: { ...options.config, scratchDir: DEFAULT_SCRATCH_DIR } };\n}\n\n/**\n * A `testing` instance renders here, so it needs a database a long-running server can keep.\n */\nfunction assertTestingBackable(options: ShelfOptions): void {\n  if (options.testing === undefined) {\n    return;\n  }\n  if (options.database.metadata.supportsTesting === false) {\n    throw new Error(\n      `The ${options.database.metadata.name} database cannot back testing: it is reachable only ` +\n        `from a platform that ends the process after each request, so nothing would run capture ` +\n        `jobs. Remove the testing option to host Storybooks only, or use a network database ` +\n        `(Turso, Postgres, MySQL, SQLite on a volume).`,\n    );\n  }\n}\n\nfunction assertTestingProcess(testing: ShelfOptions[\"testing\"]): void {\n  if (testing !== undefined && testing.runner === undefined) {\n    throw new Error(\"testing requires testing.runner\");\n  }\n  if (testing?.workerEntry !== undefined && testing.runner === undefined) {\n    throw new Error(\"testing.workerEntry requires testing.runner (it is the in-process fallback)\");\n  }\n  if (testing?.mode === \"fork\" && testing.workerEntry === undefined) {\n    throw new Error('testing.mode \"fork\" requires testing.workerEntry');\n  }\n  assertShardSize(testing);\n  assertTestingNumbers(testing);\n}\n\n/** Numeric `testing` options: concurrency, retries and the Storybook URL rate limit. */\nfunction assertTestingNumbers(testing: ShelfOptions[\"testing\"]): void {\n  assertConcurrency(testing?.concurrency);\n  assertRetries(testing?.retries);\n  assertLeaseSeconds(testing?.leaseSeconds);\n  assertStorybookUrlRateLimit(testing?.storybookUrlRateLimit);\n}\n\n/** A whole number of requests per minute; `0` would refuse every render. */\nfunction assertStorybookUrlRateLimit(limit: number | undefined): void {\n  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {\n    throw new Error(\n      `testing.storybookUrlRateLimit must be a positive whole number of requests per minute, got ${String(limit)}`,\n    );\n  }\n}\n\n/** Retries are counted after the first attempt: `0` runs a job once. */\nfunction assertRetries(retries: number | undefined): void {\n  if (retries !== undefined && (!Number.isInteger(retries) || retries < 0)) {\n    throw new Error(`testing.retries must be a non-negative integer, got ${String(retries)}`);\n  }\n}\n\n/** A lease must be a positive length: `0` would expire every job at once. */\nfunction assertLeaseSeconds(seconds: number | undefined): void {\n  if (seconds !== undefined && (!Number.isFinite(seconds) || seconds <= 0)) {\n    throw new Error(\n      `testing.leaseSeconds must be a positive number of seconds, got ${String(seconds)}`,\n    );\n  }\n}\n\n/** `0` would deadlock the consumer. */\nfunction assertConcurrency(concurrency: number | undefined): void {\n  if (concurrency !== undefined && (!Number.isInteger(concurrency) || concurrency < 1)) {\n    throw new Error(`testing.concurrency must be a positive integer, got ${String(concurrency)}`);\n  }\n}\n\nfunction assertShardSize(testing: ShelfOptions[\"testing\"]): void {\n  const size = testing?.shardSize;\n  if (size === undefined) {\n    return;\n  }\n  if (!Number.isInteger(size) || size < 1) {\n    throw new Error(`testing.shardSize must be a positive integer, got ${String(size)}`);\n  }\n  if (testing?.runner === undefined) {\n    throw new Error(\"testing.shardSize requires testing.runner (workers set their own shardSize)\");\n  }\n}\n\nfunction assertThreads(threads: number | undefined): void {\n  if (threads !== undefined && (!Number.isInteger(threads) || threads < 0)) {\n    throw new Error(\n      `testing.compare.threads must be a non-negative integer, got ${String(threads)}`,\n    );\n  }\n}\n\nfunction assertNotificationsConfig(config: unknown): void {\n  if (config === undefined) {\n    return;\n  }\n  const result = notificationsConfigSchema.safeParse(config);\n  if (!result.success) {\n    const issues = result.error.issues.map((i) => `${i.path.join(\".\")}: ${i.message}`).join(\"; \");\n    throw new Error(`Invalid notifications.config: ${issues}`);\n  }\n}\n"],"mappings":";;;;;;;;;AAMA,MAAa,sBAA8B,KAAK,OAAO,GAAG,YAAY;;;;;;;;;AAUtE,SAAgB,oBAAoB,SAAqC;CACvE,cAAc,QAAQ,SAAS,SAAS,OAAO;CAC/C,qBAAqB,QAAQ,OAAO;CACpC,sBAAsB,OAAO;CAC7B,0BAA0B,QAAQ,eAAe,MAAM;CACvD,IAAI,QAAQ,QAAQ,eAAe,KAAA,GACjC,OAAO;CAET,OAAO;EAAE,GAAG;EAAS,QAAQ;GAAE,GAAG,QAAQ;GAAQ,YAAY;EAAoB;CAAE;AACtF;;;;AAKA,SAAS,sBAAsB,SAA6B;CAC1D,IAAI,QAAQ,YAAY,KAAA,GACtB;CAEF,IAAI,QAAQ,SAAS,SAAS,oBAAoB,OAChD,MAAM,IAAI,MACR,OAAO,QAAQ,SAAS,SAAS,KAAK,4QAIxC;AAEJ;AAEA,SAAS,qBAAqB,SAAwC;CACpE,IAAI,YAAY,KAAA,KAAa,QAAQ,WAAW,KAAA,GAC9C,MAAM,IAAI,MAAM,iCAAiC;CAEnD,IAAI,SAAS,gBAAgB,KAAA,KAAa,QAAQ,WAAW,KAAA,GAC3D,MAAM,IAAI,MAAM,6EAA6E;CAE/F,IAAI,SAAS,SAAS,UAAU,QAAQ,gBAAgB,KAAA,GACtD,MAAM,IAAI,MAAM,oDAAkD;CAEpE,gBAAgB,OAAO;CACvB,qBAAqB,OAAO;AAC9B;;AAGA,SAAS,qBAAqB,SAAwC;CACpE,kBAAkB,SAAS,WAAW;CACtC,cAAc,SAAS,OAAO;CAC9B,mBAAmB,SAAS,YAAY;CACxC,4BAA4B,SAAS,qBAAqB;AAC5D;;AAGA,SAAS,4BAA4B,OAAiC;CACpE,IAAI,UAAU,KAAA,MAAc,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,IAC9D,MAAM,IAAI,MACR,6FAA6F,OAAO,KAAK,GAC3G;AAEJ;;AAGA,SAAS,cAAc,SAAmC;CACxD,IAAI,YAAY,KAAA,MAAc,CAAC,OAAO,UAAU,OAAO,KAAK,UAAU,IACpE,MAAM,IAAI,MAAM,uDAAuD,OAAO,OAAO,GAAG;AAE5F;;AAGA,SAAS,mBAAmB,SAAmC;CAC7D,IAAI,YAAY,KAAA,MAAc,CAAC,OAAO,SAAS,OAAO,KAAK,WAAW,IACpE,MAAM,IAAI,MACR,kEAAkE,OAAO,OAAO,GAClF;AAEJ;;AAGA,SAAS,kBAAkB,aAAuC;CAChE,IAAI,gBAAgB,KAAA,MAAc,CAAC,OAAO,UAAU,WAAW,KAAK,cAAc,IAChF,MAAM,IAAI,MAAM,uDAAuD,OAAO,WAAW,GAAG;AAEhG;AAEA,SAAS,gBAAgB,SAAwC;CAC/D,MAAM,OAAO,SAAS;CACtB,IAAI,SAAS,KAAA,GACX;CAEF,IAAI,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,GACpC,MAAM,IAAI,MAAM,qDAAqD,OAAO,IAAI,GAAG;CAErF,IAAI,SAAS,WAAW,KAAA,GACtB,MAAM,IAAI,MAAM,6EAA6E;AAEjG;AAEA,SAAS,cAAc,SAAmC;CACxD,IAAI,YAAY,KAAA,MAAc,CAAC,OAAO,UAAU,OAAO,KAAK,UAAU,IACpE,MAAM,IAAI,MACR,+DAA+D,OAAO,OAAO,GAC/E;AAEJ;AAEA,SAAS,0BAA0B,QAAuB;CACxD,IAAI,WAAW,KAAA,GACb;CAEF,MAAM,SAAS,0BAA0B,UAAU,MAAM;CACzD,IAAI,CAAC,OAAO,SAAS;EACnB,MAAM,SAAS,OAAO,MAAM,OAAO,KAAK,MAAM,GAAG,EAAE,KAAK,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,IAAI;EAC5F,MAAM,IAAI,MAAM,iCAAiC,QAAQ;CAC3D;AACF"}

package/dist/paths.d.mts

@@ -1,16 +1,31 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 //#region src/utils/paths.d.ts
+/**
+ * Path segment for a mode on a given engine. Chromium keeps the bare mode key
+ * so pre-multi-browser objects stay addressable; other engines get `~browser`.
+ */
+declare function modeSegment(viewport: string, browser?: string): string;
 /** Storage path for a captured snapshot screenshot. */
-declare function screenshotPath(projectId: string, buildId: string, storyId: string, viewport: string): string;
+declare function screenshotPath(projectId: string, buildId: string, storyId: string, viewport: string, browser?: string): string;
+/** Storage prefix of a project's content-addressed screenshots. */
+declare function contentDir(projectId: string): string;
+/** Storage path of a screenshot stored by the SHA-256 of its bytes (shared by builds and baselines). */
+declare function contentPath(projectId: string, hash: string): string;
+/** Whether `path` is one of `projectId`'s content-addressed screenshots. */
+declare function isContentPath(projectId: string, path: string): boolean;
 /** Storage path for a snapshot diff overlay image. */
-declare function diffPath(projectId: string, buildId: string, storyId: string, viewport: string): string;
+declare function diffPath(projectId: string, buildId: string, storyId: string, viewport: string, browser?: string): string;
+/** Storage path for a cached design node render (overwritten in place when the file version moves). */
+declare function designRenderPath(projectId: string, provider: string, fileKey: string, nodeId: string, viewerId?: string): string;
 /** Storage path for a branch baseline screenshot. */
-declare function baselinePath(projectId: string, branch: string, storyId: string, viewport: string): string;
+declare function baselinePath(projectId: string, branch: string, storyId: string, viewport: string, browser?: string): string;
 /** Storage prefix for an extracted published Storybook. */
 declare function storybookDir(projectId: string, buildId: string): string;
 /** Storage path for an uploaded Storybook zip. */
 declare function storybookZipPath(projectId: string, buildId: string): string;
+/** Storage path of a build's persisted catalog (ADR 0006, decision 9), next to its `storybook/` statics. */
+declare function catalogPath(projectId: string, buildId: string): string;
 //#endregion
-export { baselinePath, diffPath, screenshotPath, storybookDir, storybookZipPath };
+export { baselinePath, catalogPath, contentDir, contentPath, designRenderPath, diffPath, isContentPath, modeSegment, screenshotPath, storybookDir, storybookZipPath };
 //# sourceMappingURL=paths.d.mts.map

package/dist/paths.mjs

@@ -11,35 +11,71 @@ function assertSegments(segments) {
 	const bad = segments.filter((segment) => !isSafeSegment(segment) || segment.length === 0);
 	if (bad.length > 0) throw new Error(`Unsafe storage path segment: ${bad.join(",")}`);
 }
+/**
+* Path segment for a mode on a given engine. Chromium keeps the bare mode key
+* so pre-multi-browser objects stay addressable; other engines get `~browser`.
+*/
+function modeSegment(viewport, browser) {
+	return browser && browser !== "chromium" ? `${viewport}~${browser}` : viewport;
+}
 /** Storage path for a captured snapshot screenshot. */
-function screenshotPath(projectId, buildId, storyId, viewport) {
+function screenshotPath(projectId, buildId, storyId, viewport, browser) {
+	const segment = modeSegment(viewport, browser);
 	assertSegments([
 		projectId,
 		buildId,
 		storyId,
-		viewport
+		segment
 	]);
-	return `${projectId}/builds/${buildId}/screenshots/${storyId}/${viewport}.png`;
+	return `${projectId}/builds/${buildId}/screenshots/${storyId}/${segment}.png`;
+}
+/** Storage prefix of a project's content-addressed screenshots. */
+function contentDir(projectId) {
+	assertSegments([projectId]);
+	return `${projectId}/content`;
+}
+/** Storage path of a screenshot stored by the SHA-256 of its bytes (shared by builds and baselines). */
+function contentPath(projectId, hash) {
+	assertSegments([projectId, hash]);
+	return `${contentDir(projectId)}/${hash}.png`;
+}
+/** Whether `path` is one of `projectId`'s content-addressed screenshots. */
+function isContentPath(projectId, path) {
+	return path.startsWith(`${contentDir(projectId)}/`) && path.endsWith(".png");
 }
 /** Storage path for a snapshot diff overlay image. */
-function diffPath(projectId, buildId, storyId, viewport) {
+function diffPath(projectId, buildId, storyId, viewport, browser) {
+	const segment = modeSegment(viewport, browser);
 	assertSegments([
 		projectId,
 		buildId,
 		storyId,
-		viewport
+		segment
+	]);
+	return `${projectId}/builds/${buildId}/diffs/${storyId}/${segment}.png`;
+}
+/** Storage path for a cached design node render (overwritten in place when the file version moves). */
+function designRenderPath(projectId, provider, fileKey, nodeId, viewerId = "") {
+	const node = nodeId.replaceAll(":", "-");
+	assertSegments([
+		projectId,
+		provider,
+		fileKey,
+		node,
+		...viewerId ? [viewerId] : []
 	]);
-	return `${projectId}/builds/${buildId}/diffs/${storyId}/${viewport}.png`;
+	return `${projectId}/design/${provider}/${viewerId ? `user-${viewerId}/` : ""}${fileKey}/${node}.png`;
 }
 /** Storage path for a branch baseline screenshot. */
-function baselinePath(projectId, branch, storyId, viewport) {
+function baselinePath(projectId, branch, storyId, viewport, browser) {
+	const segment = modeSegment(viewport, browser);
 	assertSegments([
 		projectId,
 		branch,
 		storyId,
-		viewport
+		segment
 	]);
-	return `${projectId}/baselines/${branch}/${storyId}/${viewport}.png`;
+	return `${projectId}/baselines/${branch}/${storyId}/${segment}.png`;
 }
 /** Storage prefix for an extracted published Storybook. */
 function storybookDir(projectId, buildId) {
@@ -51,7 +87,12 @@ function storybookZipPath(projectId, buildId) {
 	assertSegments([projectId, buildId]);
 	return `${projectId}/builds/${buildId}/storybook.zip`;
 }
+/** Storage path of a build's persisted catalog (ADR 0006, decision 9), next to its `storybook/` statics. */
+function catalogPath(projectId, buildId) {
+	assertSegments([projectId, buildId]);
+	return `${projectId}/builds/${buildId}/catalog.json`;
+}
 //#endregion
-export { baselinePath, diffPath, screenshotPath, storybookDir, storybookZipPath };
+export { baselinePath, catalogPath, contentDir, contentPath, designRenderPath, diffPath, isContentPath, modeSegment, screenshotPath, storybookDir, storybookZipPath };
 
 //# sourceMappingURL=paths.mjs.map

package/dist/paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","names":[],"sources":["../src/utils/paths.ts"],"sourcesContent":["/** Storage path builders. Every segment is validated — a third-party\n * capture runner echoing `story.id = \"../../x\"` must fail here, not in an\n * adapter with its own key-jailing quirks. */\nimport { isSafeSegment } from \"./path-security.ts\";\n\n/** Throw when any key segment could escape its storage prefix. */\nfunction assertSegments(segments: string[]): void {\n  const bad = segments.filter((segment) => !isSafeSegment(segment) || segment.length === 0);\n  if (bad.length > 0) {\n    throw new Error(`Unsafe storage path segment: ${bad.join(\",\")}`);\n  }\n}\n/** Storage path for a captured snapshot screenshot. */\nexport function screenshotPath(\n  projectId: string,\n  buildId: string,\n  storyId: string,\n  viewport: string,\n): string {\n  assertSegments([projectId, buildId, storyId, viewport]);\n  return `${projectId}/builds/${buildId}/screenshots/${storyId}/${viewport}.png`;\n}\n\n/** Storage path for a snapshot diff overlay image. */\nexport function diffPath(\n  projectId: string,\n  buildId: string,\n  storyId: string,\n  viewport: string,\n): string {\n  assertSegments([projectId, buildId, storyId, viewport]);\n  return `${projectId}/builds/${buildId}/diffs/${storyId}/${viewport}.png`;\n}\n\n/** Storage path for a branch baseline screenshot. */\nexport function baselinePath(\n  projectId: string,\n  branch: string,\n  storyId: string,\n  viewport: string,\n): string {\n  assertSegments([projectId, branch, storyId, viewport]);\n  return `${projectId}/baselines/${branch}/${storyId}/${viewport}.png`;\n}\n\n/** Storage prefix for an extracted published Storybook. */\nexport function storybookDir(projectId: string, buildId: string): string {\n  assertSegments([projectId, buildId]);\n  return `${projectId}/builds/${buildId}/storybook`;\n}\n\n/** Storage path for an uploaded Storybook zip. */\nexport function storybookZipPath(projectId: string, buildId: string): string {\n  assertSegments([projectId, buildId]);\n  return `${projectId}/builds/${buildId}/storybook.zip`;\n}\n"],"mappings":";;;;;;;;;AAMA,SAAS,eAAe,UAA0B;CAChD,MAAM,MAAM,SAAS,QAAQ,YAAY,CAAC,cAAc,OAAO,KAAK,QAAQ,WAAW,CAAC;CACxF,IAAI,IAAI,SAAS,GACf,MAAM,IAAI,MAAM,gCAAgC,IAAI,KAAK,GAAG,GAAG;AAEnE;;AAEA,SAAgB,eACd,WACA,SACA,SACA,UACQ;CACR,eAAe;EAAC;EAAW;EAAS;EAAS;CAAQ,CAAC;CACtD,OAAO,GAAG,UAAU,UAAU,QAAQ,eAAe,QAAQ,GAAG,SAAS;AAC3E;;AAGA,SAAgB,SACd,WACA,SACA,SACA,UACQ;CACR,eAAe;EAAC;EAAW;EAAS;EAAS;CAAQ,CAAC;CACtD,OAAO,GAAG,UAAU,UAAU,QAAQ,SAAS,QAAQ,GAAG,SAAS;AACrE;;AAGA,SAAgB,aACd,WACA,QACA,SACA,UACQ;CACR,eAAe;EAAC;EAAW;EAAQ;EAAS;CAAQ,CAAC;CACrD,OAAO,GAAG,UAAU,aAAa,OAAO,GAAG,QAAQ,GAAG,SAAS;AACjE;;AAGA,SAAgB,aAAa,WAAmB,SAAyB;CACvE,eAAe,CAAC,WAAW,OAAO,CAAC;CACnC,OAAO,GAAG,UAAU,UAAU,QAAQ;AACxC;;AAGA,SAAgB,iBAAiB,WAAmB,SAAyB;CAC3E,eAAe,CAAC,WAAW,OAAO,CAAC;CACnC,OAAO,GAAG,UAAU,UAAU,QAAQ;AACxC"}
+{"version":3,"file":"paths.mjs","names":[],"sources":["../src/utils/paths.ts"],"sourcesContent":["/** Storage path builders. Every segment is validated — a third-party\n * capture runner echoing `story.id = \"../../x\"` must fail here, not in an\n * adapter with its own key-jailing quirks. */\nimport { isSafeSegment } from \"./path-security.ts\";\n\n/** Throw when any key segment could escape its storage prefix. */\nfunction assertSegments(segments: string[]): void {\n  const bad = segments.filter((segment) => !isSafeSegment(segment) || segment.length === 0);\n  if (bad.length > 0) {\n    throw new Error(`Unsafe storage path segment: ${bad.join(\",\")}`);\n  }\n}\n/**\n * Path segment for a mode on a given engine. Chromium keeps the bare mode key\n * so pre-multi-browser objects stay addressable; other engines get `~browser`.\n */\nexport function modeSegment(viewport: string, browser?: string): string {\n  return browser && browser !== \"chromium\" ? `${viewport}~${browser}` : viewport;\n}\n\n/** Storage path for a captured snapshot screenshot. */\nexport function screenshotPath(\n  projectId: string,\n  buildId: string,\n  storyId: string,\n  viewport: string,\n  browser?: string,\n): string {\n  const segment = modeSegment(viewport, browser);\n  assertSegments([projectId, buildId, storyId, segment]);\n  return `${projectId}/builds/${buildId}/screenshots/${storyId}/${segment}.png`;\n}\n\n/** Storage prefix of a project's content-addressed screenshots. */\nexport function contentDir(projectId: string): string {\n  assertSegments([projectId]);\n  return `${projectId}/content`;\n}\n\n/** Storage path of a screenshot stored by the SHA-256 of its bytes (shared by builds and baselines). */\nexport function contentPath(projectId: string, hash: string): string {\n  assertSegments([projectId, hash]);\n  return `${contentDir(projectId)}/${hash}.png`;\n}\n\n/** Whether `path` is one of `projectId`'s content-addressed screenshots. */\nexport function isContentPath(projectId: string, path: string): boolean {\n  return path.startsWith(`${contentDir(projectId)}/`) && path.endsWith(\".png\");\n}\n\n/** Storage path for a snapshot diff overlay image. */\nexport function diffPath(\n  projectId: string,\n  buildId: string,\n  storyId: string,\n  viewport: string,\n  browser?: string,\n): string {\n  const segment = modeSegment(viewport, browser);\n  assertSegments([projectId, buildId, storyId, segment]);\n  return `${projectId}/builds/${buildId}/diffs/${storyId}/${segment}.png`;\n}\n\n/** Storage path for a cached design node render (overwritten in place when the file version moves). */\nexport function designRenderPath(\n  projectId: string,\n  provider: string,\n  fileKey: string,\n  nodeId: string,\n  viewerId = \"\",\n): string {\n  const node = nodeId.replaceAll(\":\", \"-\");\n  assertSegments([projectId, provider, fileKey, node, ...(viewerId ? [viewerId] : [])]);\n  const owner = viewerId ? `user-${viewerId}/` : \"\";\n  return `${projectId}/design/${provider}/${owner}${fileKey}/${node}.png`;\n}\n\n/** Storage path for a branch baseline screenshot. */\nexport function baselinePath(\n  projectId: string,\n  branch: string,\n  storyId: string,\n  viewport: string,\n  browser?: string,\n): string {\n  const segment = modeSegment(viewport, browser);\n  assertSegments([projectId, branch, storyId, segment]);\n  return `${projectId}/baselines/${branch}/${storyId}/${segment}.png`;\n}\n\n/** Storage prefix for an extracted published Storybook. */\nexport function storybookDir(projectId: string, buildId: string): string {\n  assertSegments([projectId, buildId]);\n  return `${projectId}/builds/${buildId}/storybook`;\n}\n\n/** Storage path for an uploaded Storybook zip. */\nexport function storybookZipPath(projectId: string, buildId: string): string {\n  assertSegments([projectId, buildId]);\n  return `${projectId}/builds/${buildId}/storybook.zip`;\n}\n\n/** Storage path of a build's persisted catalog (ADR 0006, decision 9), next to its `storybook/` statics. */\nexport function catalogPath(projectId: string, buildId: string): string {\n  assertSegments([projectId, buildId]);\n  return `${projectId}/builds/${buildId}/catalog.json`;\n}\n"],"mappings":";;;;;;;;;AAMA,SAAS,eAAe,UAA0B;CAChD,MAAM,MAAM,SAAS,QAAQ,YAAY,CAAC,cAAc,OAAO,KAAK,QAAQ,WAAW,CAAC;CACxF,IAAI,IAAI,SAAS,GACf,MAAM,IAAI,MAAM,gCAAgC,IAAI,KAAK,GAAG,GAAG;AAEnE;;;;;AAKA,SAAgB,YAAY,UAAkB,SAA0B;CACtE,OAAO,WAAW,YAAY,aAAa,GAAG,SAAS,GAAG,YAAY;AACxE;;AAGA,SAAgB,eACd,WACA,SACA,SACA,UACA,SACQ;CACR,MAAM,UAAU,YAAY,UAAU,OAAO;CAC7C,eAAe;EAAC;EAAW;EAAS;EAAS;CAAO,CAAC;CACrD,OAAO,GAAG,UAAU,UAAU,QAAQ,eAAe,QAAQ,GAAG,QAAQ;AAC1E;;AAGA,SAAgB,WAAW,WAA2B;CACpD,eAAe,CAAC,SAAS,CAAC;CAC1B,OAAO,GAAG,UAAU;AACtB;;AAGA,SAAgB,YAAY,WAAmB,MAAsB;CACnE,eAAe,CAAC,WAAW,IAAI,CAAC;CAChC,OAAO,GAAG,WAAW,SAAS,EAAE,GAAG,KAAK;AAC1C;;AAGA,SAAgB,cAAc,WAAmB,MAAuB;CACtE,OAAO,KAAK,WAAW,GAAG,WAAW,SAAS,EAAE,EAAE,KAAK,KAAK,SAAS,MAAM;AAC7E;;AAGA,SAAgB,SACd,WACA,SACA,SACA,UACA,SACQ;CACR,MAAM,UAAU,YAAY,UAAU,OAAO;CAC7C,eAAe;EAAC;EAAW;EAAS;EAAS;CAAO,CAAC;CACrD,OAAO,GAAG,UAAU,UAAU,QAAQ,SAAS,QAAQ,GAAG,QAAQ;AACpE;;AAGA,SAAgB,iBACd,WACA,UACA,SACA,QACA,WAAW,IACH;CACR,MAAM,OAAO,OAAO,WAAW,KAAK,GAAG;CACvC,eAAe;EAAC;EAAW;EAAU;EAAS;EAAM,GAAI,WAAW,CAAC,QAAQ,IAAI,CAAC;CAAE,CAAC;CAEpF,OAAO,GAAG,UAAU,UAAU,SAAS,GADzB,WAAW,QAAQ,SAAS,KAAK,KACG,QAAQ,GAAG,KAAK;AACpE;;AAGA,SAAgB,aACd,WACA,QACA,SACA,UACA,SACQ;CACR,MAAM,UAAU,YAAY,UAAU,OAAO;CAC7C,eAAe;EAAC;EAAW;EAAQ;EAAS;CAAO,CAAC;CACpD,OAAO,GAAG,UAAU,aAAa,OAAO,GAAG,QAAQ,GAAG,QAAQ;AAChE;;AAGA,SAAgB,aAAa,WAAmB,SAAyB;CACvE,eAAe,CAAC,WAAW,OAAO,CAAC;CACnC,OAAO,GAAG,UAAU,UAAU,QAAQ;AACxC;;AAGA,SAAgB,iBAAiB,WAAmB,SAAyB;CAC3E,eAAe,CAAC,WAAW,OAAO,CAAC;CACnC,OAAO,GAAG,UAAU,UAAU,QAAQ;AACxC;;AAGA,SAAgB,YAAY,WAAmB,SAAyB;CACtE,eAAe,CAAC,WAAW,OAAO,CAAC;CACnC,OAAO,GAAG,UAAU,UAAU,QAAQ;AACxC"}

package/dist/retention/ai.d.mts

@@ -0,0 +1,18 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { Logger } from "../logger.mjs";
+//#region src/retention/ai.d.ts
+/** Pending/running rows older than this are marked `interrupted`. */
+declare const STALE_RUN_MS: number;
+/** What one AI retention pass removed. */
+interface AiPurgeResult {
+  health: number;
+  usage: number;
+  interrupted: number;
+}
+/** Run one AI retention pass (safe to call from any instance, any time). */
+declare function purgeAiData(db: DatabaseAdapter, now?: Date, logger?: Logger): Promise<AiPurgeResult>;
+//#endregion
+export { AiPurgeResult, STALE_RUN_MS, purgeAiData };
+//# sourceMappingURL=ai.d.mts.map

package/dist/retention/ai.mjs

@@ -0,0 +1,23 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { AiUsageModel } from "../models/ai-usage.mjs";
+import { InsightModel } from "../models/insight.mjs";
+/** Pending/running rows older than this are marked `interrupted`. */
+const STALE_RUN_MS = 18e5;
+/** Run one AI retention pass (safe to call from any instance, any time). */
+async function purgeAiData(db, now = /* @__PURE__ */ new Date(), logger) {
+	const insights = new InsightModel(db);
+	const day = 864e5;
+	const result = {
+		health: await insights.purgeHealthBefore((/* @__PURE__ */ new Date(now.getTime() - 90 * day)).toISOString()),
+		usage: await new AiUsageModel(db).purgeBefore((/* @__PURE__ */ new Date(now.getTime() - 90 * day)).toISOString()),
+		interrupted: await insights.sweepStale((/* @__PURE__ */ new Date(now.getTime() - STALE_RUN_MS)).toISOString())
+	};
+	if (result.health > 0 || result.usage > 0 || result.interrupted > 0) logger?.info(result, "ai data retention pass complete");
+	return result;
+}
+//#endregion
+export { STALE_RUN_MS, purgeAiData };
+
+//# sourceMappingURL=ai.mjs.map

package/dist/retention/ai.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.mjs","names":[],"sources":["../../src/retention/ai.ts"],"sourcesContent":["/** Retention for AI data: old health digests, old usage rows and interrupted runs. */\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport { AiUsageModel } from \"../models/ai-usage.ts\";\nimport { InsightModel } from \"../models/insight.ts\";\n\n/** Health digests older than this are deleted (ADR 0016 §5). */\nexport const HEALTH_RETENTION_DAYS = 90;\n\n/** Usage rows older than this are deleted (budgets only look at days/hours). */\nexport const USAGE_RETENTION_DAYS = 90;\n\n/** Pending/running rows older than this are marked `interrupted`. */\nexport const STALE_RUN_MS = 30 * 60_000;\n\n/** What one AI retention pass removed. */\nexport interface AiPurgeResult {\n  health: number;\n  usage: number;\n  interrupted: number;\n}\n\n/** Run one AI retention pass (safe to call from any instance, any time). */\nexport async function purgeAiData(\n  db: DatabaseAdapter,\n  now: Date = new Date(),\n  logger?: Logger,\n): Promise<AiPurgeResult> {\n  const insights = new InsightModel(db);\n  const day = 86_400_000;\n  const result: AiPurgeResult = {\n    health: await insights.purgeHealthBefore(\n      new Date(now.getTime() - HEALTH_RETENTION_DAYS * day).toISOString(),\n    ),\n    usage: await new AiUsageModel(db).purgeBefore(\n      new Date(now.getTime() - USAGE_RETENTION_DAYS * day).toISOString(),\n    ),\n    interrupted: await insights.sweepStale(new Date(now.getTime() - STALE_RUN_MS).toISOString()),\n  };\n  if (result.health > 0 || result.usage > 0 || result.interrupted > 0) {\n    logger?.info(result, \"ai data retention pass complete\");\n  }\n  return result;\n}\n"],"mappings":";;;;;;AAaA,MAAa,eAAe;;AAU5B,eAAsB,YACpB,IACA,sBAAY,IAAI,KAAK,GACrB,QACwB;CACxB,MAAM,WAAW,IAAI,aAAa,EAAE;CACpC,MAAM,MAAM;CACZ,MAAM,SAAwB;EAC5B,QAAQ,MAAM,SAAS,mCACrB,IAAI,KAAK,IAAI,QAAQ,IAAA,KAA4B,GAAG,EAAA,CAAE,YAAY,CACpE;EACA,OAAO,MAAM,IAAI,aAAa,EAAE,CAAC,CAAC,6BAChC,IAAI,KAAK,IAAI,QAAQ,IAAA,KAA2B,GAAG,EAAA,CAAE,YAAY,CACnE;EACA,aAAa,MAAM,SAAS,4BAAW,IAAI,KAAK,IAAI,QAAQ,IAAI,YAAY,EAAA,CAAE,YAAY,CAAC;CAC7F;CACA,IAAI,OAAO,SAAS,KAAK,OAAO,QAAQ,KAAK,OAAO,cAAc,GAChE,QAAQ,KAAK,QAAQ,iCAAiC;CAExD,OAAO;AACT"}

package/dist/retention/pending.mjs

@@ -0,0 +1,47 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { BuildModel } from "../models/build.mjs";
+import { BuildReviewModel } from "../models/build-review.mjs";
+import { CommentModel } from "../models/comment.mjs";
+//#region src/retention/pending.ts
+/**
+* The project's pending builds whose last activity (upload, comment or verdict) is before
+* `cutoff`. `capture_attempts` need no check: a build capture worked on leaves `pending`.
+*/
+async function pendingCandidates(db, projectId, cutoff) {
+	const builds = new BuildModel(db);
+	const pending = await builds.list(projectId, { status: "pending" });
+	if (pending.length === 0) return [];
+	const all = await builds.list(projectId);
+	return (await Promise.all(pending.map(async (build) => {
+		const activity = await activityOf(db, build);
+		if (activity.last >= cutoff) return null;
+		const superseded = !activity.touched && hasNewerOnBranch(all, build);
+		return {
+			buildId: build.id,
+			reason: superseded ? "superseded" : "idle"
+		};
+	}))).filter((candidate) => candidate !== null);
+}
+async function activityOf(db, build) {
+	const [comments, reviews] = await Promise.all([new CommentModel(db).listByBuild(build.id), new BuildReviewModel(db).listByBuild(build.id)]);
+	return {
+		last: [
+			build.updatedAt,
+			...comments.map((item) => stampOf(item)),
+			...reviews.map((item) => stampOf(item))
+		].toSorted().at(-1) ?? build.updatedAt,
+		touched: comments.length > 0 || reviews.length > 0
+	};
+}
+function stampOf(item) {
+	return item.createdAt;
+}
+function hasNewerOnBranch(all, build) {
+	return all.some((other) => other.id !== build.id && other.gitBranch === build.gitBranch && other.createdAt > build.createdAt);
+}
+//#endregion
+export { pendingCandidates };
+
+//# sourceMappingURL=pending.mjs.map

package/dist/retention/pending.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.mjs","names":[],"sources":["../../src/retention/pending.ts"],"sourcesContent":["/**\n * Pending builds nobody finishes (ADR 0013, decision 9; ADR 0009, decision 4). A `pending` build\n * waits for a review verdict, so the terminal-status rule never reaches it; this rule gives it an\n * exit. A pending build is purgeable once its last activity is older than the retention window:\n * the later of its own last update (upload) and its newest comment or verdict. A build superseded\n * by a newer one on its branch, with no attempts, verdicts or comments, has no activity beyond\n * its upload, so it leaves at the same window; the build under review is never cut short.\n */\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport { BuildReviewModel } from \"../models/build-review.ts\";\nimport { BuildModel } from \"../models/build.ts\";\nimport { CommentModel } from \"../models/comment.ts\";\nimport type { Build } from \"../schema/build.ts\";\n\n/** Why a pending build is purgeable. */\nexport type PendingReason = \"superseded\" | \"idle\";\n\n/** A pending build the retention pass may remove. */\nexport interface PendingCandidate {\n  buildId: string;\n  reason: PendingReason;\n}\n\n/**\n * The project's pending builds whose last activity (upload, comment or verdict) is before\n * `cutoff`. `capture_attempts` need no check: a build capture worked on leaves `pending`.\n */\nexport async function pendingCandidates(\n  db: DatabaseAdapter,\n  projectId: string,\n  cutoff: string,\n): Promise<PendingCandidate[]> {\n  const builds = new BuildModel(db);\n  const pending = await builds.list(projectId, { status: \"pending\" });\n  if (pending.length === 0) {\n    return [];\n  }\n  const all = await builds.list(projectId);\n  const found = await Promise.all(\n    pending.map(async (build): Promise<PendingCandidate | null> => {\n      const activity = await activityOf(db, build);\n      if (activity.last >= cutoff) {\n        return null;\n      }\n      const superseded = !activity.touched && hasNewerOnBranch(all, build);\n      return { buildId: build.id, reason: superseded ? \"superseded\" : \"idle\" };\n    }),\n  );\n  return found.filter((candidate) => candidate !== null);\n}\n\ninterface Activity {\n  /** Newest of the build's own update, its comments and its verdicts. */\n  last: string;\n  /** A person commented on or gave a verdict to the build. */\n  touched: boolean;\n}\n\nasync function activityOf(db: DatabaseAdapter, build: Build): Promise<Activity> {\n  const [comments, reviews] = await Promise.all([\n    new CommentModel(db).listByBuild(build.id),\n    new BuildReviewModel(db).listByBuild(build.id),\n  ]);\n  const stamps = [\n    build.updatedAt,\n    ...comments.map((item) => stampOf(item)),\n    ...reviews.map((item) => stampOf(item)),\n  ];\n  return {\n    last: stamps.toSorted().at(-1) ?? build.updatedAt,\n    touched: comments.length > 0 || reviews.length > 0,\n  };\n}\n\nfunction stampOf(item: { createdAt: string }): string {\n  return item.createdAt;\n}\n\nfunction hasNewerOnBranch(all: readonly Build[], build: Build): boolean {\n  return all.some(\n    (other) =>\n      other.id !== build.id &&\n      other.gitBranch === build.gitBranch &&\n      other.createdAt > build.createdAt,\n  );\n}\n"],"mappings":";;;;;;;;;;;AA2BA,eAAsB,kBACpB,IACA,WACA,QAC6B;CAC7B,MAAM,SAAS,IAAI,WAAW,EAAE;CAChC,MAAM,UAAU,MAAM,OAAO,KAAK,WAAW,EAAE,QAAQ,UAAU,CAAC;CAClE,IAAI,QAAQ,WAAW,GACrB,OAAO,CAAC;CAEV,MAAM,MAAM,MAAM,OAAO,KAAK,SAAS;CAWvC,QAAO,MAVa,QAAQ,IAC1B,QAAQ,IAAI,OAAO,UAA4C;EAC7D,MAAM,WAAW,MAAM,WAAW,IAAI,KAAK;EAC3C,IAAI,SAAS,QAAQ,QACnB,OAAO;EAET,MAAM,aAAa,CAAC,SAAS,WAAW,iBAAiB,KAAK,KAAK;EACnE,OAAO;GAAE,SAAS,MAAM;GAAI,QAAQ,aAAa,eAAe;EAAO;CACzE,CAAC,CACH,EAAA,CACa,QAAQ,cAAc,cAAc,IAAI;AACvD;AASA,eAAe,WAAW,IAAqB,OAAiC;CAC9E,MAAM,CAAC,UAAU,WAAW,MAAM,QAAQ,IAAI,CAC5C,IAAI,aAAa,EAAE,CAAC,CAAC,YAAY,MAAM,EAAE,GACzC,IAAI,iBAAiB,EAAE,CAAC,CAAC,YAAY,MAAM,EAAE,CAC/C,CAAC;CAMD,OAAO;EACL,MAAM;GALN,MAAM;GACN,GAAG,SAAS,KAAK,SAAS,QAAQ,IAAI,CAAC;GACvC,GAAG,QAAQ,KAAK,SAAS,QAAQ,IAAI,CAAC;EAG3B,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,KAAK,MAAM;EACxC,SAAS,SAAS,SAAS,KAAK,QAAQ,SAAS;CACnD;AACF;AAEA,SAAS,QAAQ,MAAqC;CACpD,OAAO,KAAK;AACd;AAEA,SAAS,iBAAiB,KAAuB,OAAuB;CACtE,OAAO,IAAI,MACR,UACC,MAAM,OAAO,MAAM,MACnB,MAAM,cAAc,MAAM,aAC1B,MAAM,YAAY,MAAM,SAC5B;AACF"}

package/dist/retention/screenshot-sweep.d.mts

@@ -0,0 +1,51 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { StorageAdapter } from "../adapter/storage.mjs";
+import { Logger } from "pino";
+import { Table } from "drizzle-orm";
+//#region src/retention/screenshot-sweep.d.ts
+/** Longest an unreferenced screenshot is kept after the sweep first sees it (default 24 h). */
+declare const SWEEP_GRACE_MS: number;
+/** Tables the sweep reads references and in-flight builds from. */
+interface SweepTables {
+  snapshots: Table;
+  baselines: Table;
+  builds: Table;
+}
+/** Inputs for {@link sweepScreenshotContent}. */
+interface SweepDeps {
+  db: DatabaseAdapter;
+  storage: StorageAdapter;
+  tables: SweepTables;
+  logger?: Logger;
+}
+/** What one sweep did. */
+interface SweepResult {
+  /** Objects deleted. */
+  removed: number;
+  /** Unreferenced objects still inside their grace period. */
+  pending: number;
+}
+/**
+ * Delete content-addressed screenshots that no snapshot or baseline points at any more.
+ *
+ * An object is deleted only after it has been unreferenced across two sweeps at least `graceMs`
+ * apart (first-seen times live in a marker object, so no schema is needed and the storage
+ * adapter needs no modification times). A capture writes its screenshot before the rows that
+ * reference it, so a single look is never enough; each candidate is also re-checked against the
+ * database immediately before it is deleted.
+ *
+ * Reusing an object that already exists writes nothing, so the sweep cannot see it by looking at
+ * storage. Deletion is therefore deferred (objects stay pending, first-seen times kept) while the
+ * project has reuse in flight: a build still capturing, or a reuse claim from a baseline import or
+ * approval ({@link withContentClaim}). Both checks are bounded by the grace period, so a build
+ * stuck in `capturing` or a claim left by a crash delays reclaiming storage, never forever.
+ */
+declare function sweepScreenshotContent(deps: SweepDeps, projectId: string, options?: {
+  now?: number;
+  graceMs?: number;
+}): Promise<SweepResult>;
+//#endregion
+export { SWEEP_GRACE_MS, SweepDeps, SweepResult, SweepTables, sweepScreenshotContent };
+//# sourceMappingURL=screenshot-sweep.d.mts.map