@sixb/pg 0.1.20 → 0.1.22

package/src/pg-ai-usage-storage.ts

@@ -1,14 +1,23 @@
-import { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "@sixb/core/internal/storage"
+import type { FileRef } from "@sixb/core/blob-storage/server"
+import {
+  assertAiUsageExecutionId,
+  assertSameCallExecution,
+  normalizeAiModelCallFilesRecord,
+  normalizeAiModelCallRecord,
+} from "@sixb/core/internal/storage"
 import { isModelReasoning, normalizeModelProviderIds } from "@sixb/core/models"
 import type { ReadonlyJsonObject } from "@sixb/core/storage"
 import {
+  type AiModelCallFilesRecord,
   type AiModelCallUsageInput,
   type AiModelCallUsageRecord,
   type AiUsageExecutionSummary,
   type AiUsageStorage,
   AiUsageStorageError,
   aggregateAiModelCallUsage,
+  type GetAiModelCallFilesInput,
   type GetLatestAiModelCallForExecutionInput,
+  type RecordAiModelCallFilesInput,
   type RecordAiModelCallInput,
   type RecordAiModelCallResult,
   type SummarizeAiUsageExecutionInput,
@@ -51,6 +60,10 @@ export class PgAiUsageStorage implements AiUsageStorage {
           text_output_tokens,
           reasoning_output_tokens,
           audio_duration_ms,
+          image_output_tokens,
+          audio_output_tokens,
+          output_images,
+          input_characters,
           reporting_status,
           raw_usage,
           occurred_at,
@@ -81,6 +94,10 @@ export class PgAiUsageStorage implements AiUsageStorage {
           ${record.usage.textOutputTokens ?? null},
           ${record.usage.reasoningOutputTokens ?? null},
           ${record.usage.audioDurationMs ?? null},
+          ${record.usage.imageOutputTokens ?? null},
+          ${record.usage.audioOutputTokens ?? null},
+          ${record.usage.outputImages ?? null},
+          ${record.usage.inputCharacters ?? null},
           ${record.usage.reportingStatus},
           ${record.rawUsage === undefined ? null : JSON.stringify(record.rawUsage)}::text::jsonb,
           ${record.occurredAt},
@@ -235,6 +252,48 @@ export class PgAiUsageStorage implements AiUsageStorage {
     `
   }
 
+  async recordModelCallFiles(input: RecordAiModelCallFilesInput): Promise<AiModelCallFilesRecord> {
+    const record = normalizeAiModelCallFilesRecord(input)
+    return runPgTransaction(this.sql, async (tx) => {
+      const existing = await this.findCallFiles(tx, record.projectId, record.callId)
+      if (existing) return assertSameCallExecution(existing, record)
+      await this.assertExecutionExists(tx, record.projectId, record.executionId)
+      const inserted = await tx<CallFilesRow[]>`
+        INSERT INTO ai_model_call_files (project_id, call_id, execution_id, files, recorded_at)
+        VALUES (
+          ${record.projectId},
+          ${record.callId},
+          ${record.executionId},
+          ${JSON.stringify(record.files)}::text::jsonb,
+          ${record.recordedAt}
+        )
+        ON CONFLICT (project_id, call_id) DO NOTHING
+        RETURNING *
+      `
+      if (inserted[0]) return callFilesFromRow(inserted[0])
+      // Another writer recorded this call between the read and the insert.
+      const concurrent = await this.findCallFiles(tx, record.projectId, record.callId)
+      if (!concurrent) throw new Error("[SixbPg] AI model-call files disappeared after a conflict.")
+      return assertSameCallExecution(concurrent, record)
+    })
+  }
+
+  async getModelCallFiles(input: GetAiModelCallFilesInput): Promise<AiModelCallFilesRecord | null> {
+    assertNonBlankProjectId(input.projectId)
+    return this.findCallFiles(this.sql, input.projectId, input.callId)
+  }
+
+  private async findCallFiles(
+    sql: PgStoreClient,
+    projectId: string,
+    callId: string
+  ): Promise<AiModelCallFilesRecord | null> {
+    const [row] = await sql<CallFilesRow[]>`
+      SELECT * FROM ai_model_call_files WHERE project_id = ${projectId} AND call_id = ${callId}
+    `
+    return row ? callFilesFromRow(row) : null
+  }
+
   private async assertExecutionExists(
     sql: PgStoreClient,
     projectId: string,
@@ -253,6 +312,24 @@ export class PgAiUsageStorage implements AiUsageStorage {
   }
 }
 
+interface CallFilesRow {
+  readonly project_id: string
+  readonly call_id: string
+  readonly execution_id: string
+  readonly files: FileRef[] | string
+  readonly recorded_at: Date | string
+}
+
+function callFilesFromRow(row: CallFilesRow): AiModelCallFilesRecord {
+  return {
+    projectId: row.project_id,
+    executionId: row.execution_id,
+    callId: row.call_id,
+    files: typeof row.files === "string" ? (JSON.parse(row.files) as FileRef[]) : row.files,
+    recordedAt: new Date(row.recorded_at),
+  }
+}
+
 interface AiUsageRow {
   readonly project_id: string
   readonly id: string
@@ -275,6 +352,10 @@ interface AiUsageRow {
   readonly text_output_tokens: number | string | null
   readonly reasoning_output_tokens: number | string | null
   readonly audio_duration_ms: number | string | null
+  readonly image_output_tokens: number | string | null
+  readonly audio_output_tokens: number | string | null
+  readonly output_images: number | string | null
+  readonly input_characters: number | string | null
   readonly reporting_status: AiModelCallUsageRecord["usage"]["reportingStatus"]
   readonly raw_usage: ReadonlyJsonObject | string | null
   readonly occurred_at: Date | string
@@ -319,6 +400,14 @@ function usageFromRow(row: AiUsageRow): AiModelCallUsageInput {
       ? {}
       : { reasoningOutputTokens: Number(row.reasoning_output_tokens) }),
     ...(row.audio_duration_ms === null ? {} : { audioDurationMs: Number(row.audio_duration_ms) }),
+    ...(row.image_output_tokens === null
+      ? {}
+      : { imageOutputTokens: Number(row.image_output_tokens) }),
+    ...(row.audio_output_tokens === null
+      ? {}
+      : { audioOutputTokens: Number(row.audio_output_tokens) }),
+    ...(row.output_images === null ? {} : { outputImages: Number(row.output_images) }),
+    ...(row.input_characters === null ? {} : { inputCharacters: Number(row.input_characters) }),
   }
 }
 

package/src/pg-artifact-storage.ts

@@ -0,0 +1,521 @@
+import {
+  artifactStateBytes,
+  artifactStorageErrors,
+  checkArtifactStateWrite,
+  parseArtifactFrameGrantRow,
+  parseArtifactRow,
+  parseArtifactStateRow,
+  parseArtifactVersionRow,
+} from "@sixb/core/internal/storage"
+import type {
+  ArtifactFrameGrantRecord,
+  ArtifactRecord,
+  ArtifactStateEntry,
+  ArtifactStateKeyInput,
+  ArtifactStateScope,
+  ArtifactStorage,
+  ArtifactVersionInput,
+  ArtifactVersionRecord,
+  CopyArtifactInput,
+  CreateArtifactInput,
+  DeleteArtifactInput,
+  DeleteArtifactVersionsByOriginInput,
+  DeleteExpiredArtifactFrameGrantsInput,
+  FindArtifactFrameGrantInput,
+  GetArtifactInput,
+  GetArtifactVersionInput,
+  ListArtifactsInput,
+  ListArtifactsResult,
+  ListArtifactVersionsInput,
+  ListArtifactVersionsResult,
+  ListReferencingVersionsInput,
+  PublishArtifactVersionInput,
+  PublishedArtifactVersion,
+  SetArtifactStateInput,
+} from "@sixb/core/storage"
+import type { SQLClient, SqlParameter } from "./pg-client"
+import { type PgStoreClient, runPgTransaction } from "./transactions"
+
+interface PgRow {
+  readonly [column: string]: unknown
+}
+
+// Quoted aliases give the shared row parsers their camelCase keys; an unquoted alias would fold to
+// lower case.
+const ARTIFACT_COLUMNS = `
+  project_id AS "projectId", id, kind, title,
+  owner_principal_type AS "ownerPrincipalType", owner_principal_id AS "ownerPrincipalId",
+  latest_version AS "latestVersion", created_at AS "createdAt", updated_at AS "updatedAt"
+`
+
+const VERSION_COLUMNS = `
+  project_id AS "projectId", artifact_id AS "artifactId", version, title, entry, files, outline,
+  refs, author_principal_type AS "authorPrincipalType", author_principal_id AS "authorPrincipalId",
+  origin_thread_id AS "originThreadId", origin_run_id AS "originRunId", created_at AS "createdAt"
+`
+
+const FRAME_GRANT_COLUMNS = `
+  project_id AS "projectId", token_hash AS "tokenHash", artifact_id AS "artifactId", version,
+  targets, created_at AS "createdAt", expires_at AS "expiresAt"
+`
+
+const STATE_COLUMNS = `key, value, size_bytes AS "sizeBytes", updated_at AS "updatedAt"`
+
+export class PgArtifactStorage implements ArtifactStorage {
+  constructor(private readonly sql: PgStoreClient) {}
+
+  async create(input: CreateArtifactInput): Promise<PublishedArtifactVersion> {
+    return runPgTransaction(this.sql, async (tx) => {
+      const [artifact] = await tx<PgRow[]>`
+        INSERT INTO artifacts (
+          project_id, id, kind, title, owner_principal_type, owner_principal_id,
+          latest_version, next_version, created_at, updated_at
+        ) VALUES (
+          ${input.projectId}, ${input.id}, ${input.kind}, ${input.version.title},
+          ${input.owner.type}, ${input.owner.id}, 1, 2,
+          ${input.version.createdAt}, ${input.version.createdAt}
+        )
+        ON CONFLICT (project_id, id) DO NOTHING
+        RETURNING ${tx.unsafe(ARTIFACT_COLUMNS)}
+      `
+      if (!artifact) throw artifactStorageErrors.exists(input.id)
+      return {
+        artifact: parseArtifactRow(artifact),
+        version: await insertVersion(tx, input.projectId, input.id, 1, input.version),
+      }
+    })
+  }
+
+  async publish(input: PublishArtifactVersionInput): Promise<PublishedArtifactVersion> {
+    return runPgTransaction(this.sql, async (tx) => {
+      // The row lock serializes concurrent publishes of one artifact.
+      const [current] = await tx<PgRow[]>`
+        SELECT kind, next_version, latest_version FROM artifacts
+        WHERE project_id = ${input.projectId} AND id = ${input.artifactId}
+        FOR UPDATE
+      `
+      if (!current) throw artifactStorageErrors.notFound(input.artifactId)
+      const kind = current.kind as ArtifactRecord["kind"]
+      if (kind !== input.kind) {
+        throw artifactStorageErrors.kindMismatch(input.artifactId, kind, input.kind)
+      }
+      // Under the row lock: a publish from the same base after this one finds it moved.
+      const latestVersion = Number(current.latest_version)
+      if (input.baseVersion !== undefined && latestVersion !== input.baseVersion) {
+        const [row] = await tx<PgRow[]>`
+          SELECT ${tx.unsafe(VERSION_COLUMNS)} FROM artifact_versions
+          WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+            AND version = ${latestVersion}
+        `
+        const latest = parseArtifactVersionRow(row as PgRow)
+        throw artifactStorageErrors.moved(input.artifactId, input.baseVersion, {
+          version: latest.version,
+          author: latest.author,
+        })
+      }
+      const version = await insertVersion(
+        tx,
+        input.projectId,
+        input.artifactId,
+        Number(current.next_version),
+        input.version
+      )
+      const [artifact] = await tx<PgRow[]>`
+        UPDATE artifacts
+        SET title = ${input.version.title}, latest_version = ${version.version},
+            next_version = ${version.version + 1}, updated_at = ${input.version.createdAt}
+        WHERE project_id = ${input.projectId} AND id = ${input.artifactId}
+        RETURNING ${tx.unsafe(ARTIFACT_COLUMNS)}
+      `
+      return { artifact: parseArtifactRow(artifact), version }
+    })
+  }
+
+  async get(input: GetArtifactInput): Promise<ArtifactRecord | null> {
+    const [row] = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(ARTIFACT_COLUMNS)} FROM artifacts
+      WHERE project_id = ${input.projectId} AND id = ${input.id}
+    `
+    return row ? parseArtifactRow(row) : null
+  }
+
+  async list(input: ListArtifactsInput): Promise<ListArtifactsResult> {
+    const where = ["a.project_id = $1"]
+    const params: SqlParameter[] = [input.projectId]
+    if (input.owner) {
+      where.push(`a.owner_principal_type = $${params.length + 1}`)
+      params.push(input.owner.type)
+      where.push(`a.owner_principal_id = $${params.length + 1}`)
+      params.push(input.owner.id)
+    }
+    if (input.threadId !== undefined) {
+      where.push(
+        `EXISTS (
+          SELECT 1 FROM artifact_threads t
+          WHERE t.project_id = a.project_id AND t.artifact_id = a.id
+            AND t.thread_id = $${params.length + 1}
+        )`
+      )
+      params.push(input.threadId)
+    }
+    if (input.kind !== undefined) {
+      where.push(`a.kind = $${params.length + 1}`)
+      params.push(input.kind)
+    }
+    const clause = where.join(" AND ")
+    const [counted] = await this.sql.unsafe<{ total: number }[]>(
+      `SELECT COUNT(*)::int AS total FROM artifacts a WHERE ${clause}`,
+      params
+    )
+    const offset = input.offset ?? 0
+    const rows = await this.sql.unsafe<PgRow[]>(
+      `SELECT ${ARTIFACT_COLUMNS} FROM artifacts a WHERE ${clause}
+       ORDER BY a.updated_at DESC, a.id ASC
+       LIMIT $${params.length + 1} OFFSET $${params.length + 2}`,
+      [...params, input.limit ?? null, offset]
+    )
+    const total = counted?.total ?? 0
+    return { artifacts: rows.map(parseArtifactRow), hasMore: offset + rows.length < total, total }
+  }
+
+  async getVersion(input: GetArtifactVersionInput): Promise<ArtifactVersionRecord | null> {
+    const [row] = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(VERSION_COLUMNS)} FROM artifact_versions
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+        AND version = ${input.version}
+    `
+    return row ? parseArtifactVersionRow(row) : null
+  }
+
+  async listThreadIds(input: GetArtifactInput): Promise<string[]> {
+    const rows = await this.sql<{ thread_id: string }[]>`
+      SELECT thread_id FROM artifact_threads
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.id}
+      ORDER BY thread_id COLLATE "C"
+    `
+    return rows.map((row) => row.thread_id)
+  }
+
+  async copy(input: CopyArtifactInput): Promise<ArtifactRecord> {
+    return runPgTransaction(this.sql, async (tx) => {
+      // The share lock keeps the source from being deleted or published to while it is copied, so
+      // the copy holds every version it has.
+      const [source] = await tx<PgRow[]>`
+        SELECT id FROM artifacts WHERE project_id = ${input.projectId} AND id = ${input.sourceId}
+        FOR SHARE
+      `
+      if (!source) throw artifactStorageErrors.notFound(input.sourceId)
+
+      const [artifact] = await tx<PgRow[]>`
+        INSERT INTO artifacts (
+          project_id, id, kind, title, owner_principal_type, owner_principal_id,
+          latest_version, next_version, created_at, updated_at
+        )
+        SELECT project_id, ${input.id}, kind, title, ${input.owner.type}, ${input.owner.id},
+               latest_version, next_version, created_at, updated_at
+        FROM artifacts WHERE project_id = ${input.projectId} AND id = ${input.sourceId}
+        ON CONFLICT (project_id, id) DO NOTHING
+        RETURNING ${tx.unsafe(ARTIFACT_COLUMNS)}
+      `
+      if (!artifact) throw artifactStorageErrors.exists(input.id)
+
+      await tx`
+        INSERT INTO artifact_versions (
+          project_id, artifact_id, version, title, entry, files, outline, refs,
+          author_principal_type, author_principal_id, created_at
+        )
+        SELECT project_id, ${input.id}, version, title, entry, files, outline, refs,
+               author_principal_type, author_principal_id, created_at
+        FROM artifact_versions
+        WHERE project_id = ${input.projectId} AND artifact_id = ${input.sourceId}
+      `
+      await tx`
+        INSERT INTO artifact_threads (project_id, artifact_id, thread_id, shared_at, copied)
+        VALUES (
+          ${input.projectId}, ${input.id}, ${input.threadId}, ${input.copiedAt ?? new Date()}, TRUE
+        )
+      `
+      return parseArtifactRow(artifact)
+    })
+  }
+
+  async listVersions(input: ListArtifactVersionsInput): Promise<ListArtifactVersionsResult> {
+    const [counted] = await this.sql<{ total: number }[]>`
+      SELECT COUNT(*)::int AS total FROM artifact_versions
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+    `
+    const offset = input.offset ?? 0
+    const rows = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(VERSION_COLUMNS)} FROM artifact_versions
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+      ORDER BY version DESC
+      LIMIT ${input.limit ?? null} OFFSET ${offset}
+    `
+    const total = counted?.total ?? 0
+    return {
+      versions: rows.map(parseArtifactVersionRow),
+      hasMore: offset + rows.length < total,
+      total,
+    }
+  }
+
+  async listReferencingVersions(
+    input: ListReferencingVersionsInput
+  ): Promise<ArtifactVersionRecord[]> {
+    // An address names the artifact when the id is followed by nothing, a version, a file, or a
+    // part.
+    const prefix = `artifact:${input.artifactId}`
+    const rows = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(VERSION_COLUMNS)} FROM artifact_versions v
+      WHERE project_id = ${input.projectId} AND (artifact_id, version) IN (
+        SELECT id, latest_version FROM artifacts WHERE project_id = ${input.projectId}
+      ) AND EXISTS (
+        SELECT 1 FROM jsonb_array_elements(v.refs) r
+        WHERE left(r ->> 'address', ${prefix.length}::int) = ${prefix}
+          AND substr(r ->> 'address', ${prefix.length + 1}::int, 1) IN ('', '@', '/', '#')
+      )
+      ORDER BY artifact_id
+    `
+    return rows.map(parseArtifactVersionRow)
+  }
+
+  async createFrameGrant(record: ArtifactFrameGrantRecord): Promise<void> {
+    const rows = await this.sql`
+      INSERT INTO artifact_frame_grants
+        (project_id, token_hash, artifact_id, version, targets, created_at, expires_at)
+      SELECT ${record.projectId}, ${record.tokenHash}, ${record.artifactId}, ${record.version},
+             ${JSON.stringify(record.targets)}::text::jsonb, ${record.createdAt},
+             ${record.expiresAt}
+      WHERE EXISTS (
+        SELECT 1 FROM artifacts WHERE project_id = ${record.projectId} AND id = ${record.artifactId}
+      )
+      RETURNING token_hash
+    `
+    if (rows.length === 0) throw artifactStorageErrors.notFound(record.artifactId)
+  }
+
+  async findFrameGrant(
+    input: FindArtifactFrameGrantInput
+  ): Promise<ArtifactFrameGrantRecord | null> {
+    const [row] = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(FRAME_GRANT_COLUMNS)} FROM artifact_frame_grants
+      WHERE project_id = ${input.projectId} AND token_hash = ${input.tokenHash}
+    `
+    return row ? parseArtifactFrameGrantRow(row) : null
+  }
+
+  async deleteExpiredFrameGrants(input: DeleteExpiredArtifactFrameGrantsInput): Promise<number> {
+    const rows = await this.sql`
+      DELETE FROM artifact_frame_grants
+      WHERE (project_id, token_hash) IN (
+        SELECT project_id, token_hash FROM artifact_frame_grants
+        WHERE project_id = ${input.projectId} AND expires_at < ${input.expiredBefore}
+        ORDER BY expires_at LIMIT ${input.limit}
+      )
+      RETURNING token_hash
+    `
+    return rows.length
+  }
+
+  async getState(input: ArtifactStateKeyInput): Promise<ArtifactStateEntry | null> {
+    const [row] = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(STATE_COLUMNS)} FROM artifact_state
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+        AND principal_type = ${input.principal.type} AND principal_id = ${input.principal.id}
+        AND key = ${input.key}
+    `
+    return row ? parseArtifactStateRow(row) : null
+  }
+
+  async setState(input: SetArtifactStateInput): Promise<void> {
+    await runPgTransaction(this.sql, async (tx) => {
+      // The key share lock keeps the artifact from being deleted under the write, without
+      // waiting on a publish.
+      const [artifact] = await tx<PgRow[]>`
+        SELECT 1 FROM artifacts WHERE project_id = ${input.projectId} AND id = ${input.artifactId}
+        FOR KEY SHARE
+      `
+      if (!artifact) throw artifactStorageErrors.notFound(input.artifactId)
+      // One reader's writes to one artifact take turns, so two at once cannot both fit under the
+      // limits; other readers' writes do not wait.
+      await tx`
+        SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([
+          "artifact_state",
+          input.projectId,
+          input.artifactId,
+          input.principal.type,
+          input.principal.id,
+        ])}, 0))
+      `
+      const [others] = await tx<PgRow[]>`
+        SELECT count(*) AS keys, coalesce(sum(size_bytes), 0) AS bytes FROM artifact_state
+        WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+          AND principal_type = ${input.principal.type} AND principal_id = ${input.principal.id}
+          AND key <> ${input.key}
+      `
+      const sizeBytes = artifactStateBytes(input.value)
+      checkArtifactStateWrite({
+        key: input.key,
+        valueBytes: sizeBytes,
+        others: { keys: Number(others?.keys ?? 0), bytes: Number(others?.bytes ?? 0) },
+      })
+      await tx`
+        INSERT INTO artifact_state (
+          project_id, artifact_id, principal_type, principal_id, key, value, size_bytes,
+          updated_at
+        ) VALUES (
+          ${input.projectId}, ${input.artifactId}, ${input.principal.type},
+          ${input.principal.id}, ${input.key}, ${input.value}, ${sizeBytes}, ${input.updatedAt}
+        )
+        ON CONFLICT (project_id, artifact_id, principal_type, principal_id, key) DO UPDATE SET
+          value = excluded.value, size_bytes = excluded.size_bytes,
+          updated_at = excluded.updated_at
+      `
+    })
+  }
+
+  async deleteState(input: ArtifactStateKeyInput): Promise<boolean> {
+    const rows = await this.sql`
+      DELETE FROM artifact_state
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+        AND principal_type = ${input.principal.type} AND principal_id = ${input.principal.id}
+        AND key = ${input.key}
+      RETURNING key
+    `
+    return rows.length > 0
+  }
+
+  async listState(input: ArtifactStateScope): Promise<ArtifactStateEntry[]> {
+    // COLLATE "C": code-unit order, as SQLite and the in-memory store compare keys.
+    const rows = await this.sql<PgRow[]>`
+      SELECT ${this.sql.unsafe(STATE_COLUMNS)} FROM artifact_state
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+        AND principal_type = ${input.principal.type} AND principal_id = ${input.principal.id}
+      ORDER BY key COLLATE "C"
+    `
+    return rows.map(parseArtifactStateRow)
+  }
+
+  async clearState(input: ArtifactStateScope): Promise<number> {
+    const rows = await this.sql`
+      DELETE FROM artifact_state
+      WHERE project_id = ${input.projectId} AND artifact_id = ${input.artifactId}
+        AND principal_type = ${input.principal.type} AND principal_id = ${input.principal.id}
+      RETURNING key
+    `
+    return rows.length
+  }
+
+  async delete(input: DeleteArtifactInput): Promise<boolean> {
+    // Versions, frame grants, and state go with the artifact through ON DELETE CASCADE.
+    const rows = await this.sql`
+      DELETE FROM artifacts WHERE project_id = ${input.projectId} AND id = ${input.id}
+      RETURNING id
+    `
+    return rows.length > 0
+  }
+
+  async deleteVersionsByOrigin(input: DeleteArtifactVersionsByOriginInput): Promise<number> {
+    return runPgTransaction(this.sql, async (tx) => {
+      // Lock the run's artifacts first, in id order so two of these never deadlock. `publish`
+      // holds the same lock while it adds a version, and under READ COMMITTED each statement
+      // below then reads a snapshot taken after any publish that held it committed. Without the
+      // lock they would wait on a publish's row lock and then apply what they read before it: the
+      // UPDATE would point `latest_version` back past the new version, and the DELETE would drop
+      // an artifact whose versions were all the run's, cascading the new version with it.
+      const locked = await tx<{ id: string }[]>`
+        SELECT id FROM artifacts
+        WHERE project_id = ${input.projectId} AND id IN (
+          SELECT artifact_id FROM artifact_versions
+          WHERE project_id = ${input.projectId} AND origin_run_id = ${input.runId}
+        )
+        ORDER BY id
+        FOR UPDATE
+      `
+      const affected = locked.map((row) => row.id)
+      if (affected.length === 0) return 0
+      const deleted = await tx<{ origin_thread_id: string }[]>`
+        DELETE FROM artifact_versions
+        WHERE project_id = ${input.projectId} AND origin_run_id = ${input.runId}
+          AND artifact_id IN ${tx(affected)}
+        RETURNING origin_thread_id
+      `
+      // A run publishes from one thread: its artifacts stay shared there only while a version
+      // from it remains, or when they were copied for it.
+      const threadId = deleted[0]?.origin_thread_id
+      await tx`
+        DELETE FROM artifact_threads t
+        WHERE t.project_id = ${input.projectId} AND t.artifact_id IN ${tx(affected)}
+          AND t.thread_id = ${threadId ?? null} AND NOT t.copied
+          AND NOT EXISTS (
+            SELECT 1 FROM artifact_versions v
+            WHERE v.project_id = t.project_id AND v.artifact_id = t.artifact_id
+              AND v.origin_thread_id = t.thread_id
+          )
+      `
+      // An artifact left without versions goes; the rest point at their newest remaining one.
+      await tx`
+        DELETE FROM artifacts a
+        WHERE a.project_id = ${input.projectId} AND a.id IN ${tx(affected)}
+          AND NOT EXISTS (
+            SELECT 1 FROM artifact_versions v
+            WHERE v.project_id = a.project_id AND v.artifact_id = a.id
+          )
+      `
+      await tx`
+        UPDATE artifacts a
+        SET latest_version = latest.version, title = latest.title, updated_at = latest.created_at
+        FROM (
+          SELECT DISTINCT ON (artifact_id) artifact_id, version, title, created_at
+          FROM artifact_versions
+          WHERE project_id = ${input.projectId} AND artifact_id IN ${tx(affected)}
+          ORDER BY artifact_id, version DESC
+        ) latest
+        WHERE a.project_id = ${input.projectId} AND a.id = latest.artifact_id
+      `
+      return deleted.length
+    })
+  }
+}
+
+async function insertVersion(
+  sql: SQLClient,
+  projectId: string,
+  artifactId: string,
+  version: number,
+  input: ArtifactVersionInput
+): Promise<ArtifactVersionRecord> {
+  const [row] = await sql<PgRow[]>`
+    INSERT INTO artifact_versions (
+      project_id, artifact_id, version, title, entry, files, outline, refs,
+      author_principal_type, author_principal_id, origin_thread_id, origin_run_id, created_at
+    ) VALUES (
+      ${projectId}, ${artifactId}, ${version}, ${input.title}, ${input.entry},
+      ${JSON.stringify(input.files)}::text::jsonb,
+      ${JSON.stringify(input.outline)}::text::jsonb,
+      ${JSON.stringify(input.references)}::text::jsonb,
+      ${input.author.type}, ${input.author.id},
+      ${input.origin?.threadId ?? null}, ${input.origin?.runId ?? null}, ${input.createdAt}
+    )
+    RETURNING ${sql.unsafe(VERSION_COLUMNS)}
+  `
+  if (input.origin) {
+    await linkThread(sql, projectId, artifactId, input.origin.threadId, input.createdAt)
+  }
+  return parseArtifactVersionRow(row)
+}
+
+/** Shares an artifact in a thread, keeping when it was first shared there. */
+async function linkThread(
+  sql: SQLClient,
+  projectId: string,
+  artifactId: string,
+  threadId: string,
+  sharedAt: Date
+): Promise<void> {
+  await sql`
+    INSERT INTO artifact_threads (project_id, artifact_id, thread_id, shared_at)
+    VALUES (${projectId}, ${artifactId}, ${threadId}, ${sharedAt})
+    ON CONFLICT (project_id, artifact_id, thread_id) DO NOTHING
+  `
+}