@sixb/sqlite 0.1.20 → 0.1.22

package/src/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,
@@ -110,10 +119,54 @@ export class SqliteAiUsageStorage implements AiUsageStorage {
     return aggregateExecutionRows(input.executionIds, rows)
   }
 
+  async recordModelCallFiles(input: RecordAiModelCallFilesInput): Promise<AiModelCallFilesRecord> {
+    const record = normalizeAiModelCallFilesRecord(input)
+    return runImmediateTransaction(this.connection.db, () => {
+      const existing = this.findCallFiles(record.projectId, record.callId)
+      if (existing) return assertSameCallExecution(existing, record)
+      this.assertExecutionExists(record.projectId, record.executionId)
+      this.connection.db
+        .query(
+          `
+            INSERT INTO ai_model_call_files (project_id, call_id, execution_id, files, recorded_at)
+            VALUES (?, ?, ?, ?, ?)
+          `
+        )
+        .run(
+          record.projectId,
+          record.callId,
+          record.executionId,
+          JSON.stringify(record.files),
+          record.recordedAt.toISOString()
+        )
+      return record
+    })
+  }
+
+  async getModelCallFiles(input: GetAiModelCallFilesInput): Promise<AiModelCallFilesRecord | null> {
+    assertNonBlankProjectId(input.projectId)
+    return this.findCallFiles(input.projectId, input.callId)
+  }
+
   close(): void {
     closeSqliteStoreConnection(this.connection)
   }
 
+  private findCallFiles(projectId: string, callId: string): AiModelCallFilesRecord | null {
+    const row = this.connection.db
+      .query("SELECT * FROM ai_model_call_files WHERE project_id = ? AND call_id = ?")
+      .get(projectId, callId) as CallFilesRow | null
+    return row
+      ? {
+          projectId: row.project_id,
+          executionId: row.execution_id,
+          callId: row.call_id,
+          files: JSON.parse(row.files) as FileRef[],
+          recordedAt: new Date(row.recorded_at),
+        }
+      : null
+  }
+
   private insertRecord(record: AiModelCallUsageRecord): void {
     this.connection.db
       .query(
@@ -140,12 +193,16 @@ export class SqliteAiUsageStorage 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,
             recorded_at
           ) VALUES (
-            ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+            ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
           )
         `
       )
@@ -171,6 +228,10 @@ export class SqliteAiUsageStorage 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),
         record.occurredAt.toISOString(),
@@ -285,6 +346,14 @@ export class SqliteAiUsageStorage implements AiUsageStorage {
   }
 }
 
+interface CallFilesRow {
+  readonly project_id: string
+  readonly call_id: string
+  readonly execution_id: string
+  readonly files: string
+  readonly recorded_at: string
+}
+
 interface AiUsageRow {
   readonly project_id: string
   readonly id: string
@@ -307,6 +376,10 @@ interface AiUsageRow {
   readonly text_output_tokens: number | null
   readonly reasoning_output_tokens: number | null
   readonly audio_duration_ms: number | null
+  readonly image_output_tokens: number | null
+  readonly audio_output_tokens: number | null
+  readonly output_images: number | null
+  readonly input_characters: number | null
   readonly reporting_status: AiModelCallUsageRecord["usage"]["reportingStatus"]
   readonly raw_usage: string | null
   readonly occurred_at: string
@@ -349,6 +422,10 @@ function usageFromRow(row: AiUsageRow): AiModelCallUsageInput {
       ? {}
       : { reasoningOutputTokens: row.reasoning_output_tokens }),
     ...(row.audio_duration_ms === null ? {} : { audioDurationMs: row.audio_duration_ms }),
+    ...(row.image_output_tokens === null ? {} : { imageOutputTokens: row.image_output_tokens }),
+    ...(row.audio_output_tokens === null ? {} : { audioOutputTokens: row.audio_output_tokens }),
+    ...(row.output_images === null ? {} : { outputImages: row.output_images }),
+    ...(row.input_characters === null ? {} : { inputCharacters: row.input_characters }),
   }
 }
 

package/src/artifact-storage.ts

@@ -0,0 +1,553 @@
+import type { Database, SQLQueryBindings } from "bun:sqlite"
+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 { runImmediateTransaction, type SqliteStoreConnection } from "./transactions"
+
+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"
+
+/** One reader of one artifact: the bindings that follow `STATE_SCOPE`. */
+const STATE_SCOPE = "project_id = ? AND artifact_id = ? AND principal_type = ? AND principal_id = ?"
+
+function stateScope(input: ArtifactStateScope): SQLQueryBindings[] {
+  return [input.projectId, input.artifactId, input.principal.type, input.principal.id]
+}
+
+type Row = Record<string, unknown>
+
+export class SqliteArtifactStorage implements ArtifactStorage {
+  private readonly db: Database
+
+  constructor(connection: SqliteStoreConnection) {
+    this.db = connection.db
+  }
+
+  async create(input: CreateArtifactInput): Promise<PublishedArtifactVersion> {
+    return runImmediateTransaction(this.db, () => {
+      const createdAt = input.version.createdAt.toISOString()
+      const artifact = this.db
+        .query(
+          `INSERT INTO artifacts (
+            project_id, id, kind, title, owner_principal_type, owner_principal_id,
+            latest_version, next_version, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, 1, 2, ?, ?)
+          ON CONFLICT (project_id, id) DO NOTHING
+          RETURNING ${ARTIFACT_COLUMNS}`
+        )
+        .get(
+          input.projectId,
+          input.id,
+          input.kind,
+          input.version.title,
+          input.owner.type,
+          input.owner.id,
+          createdAt,
+          createdAt
+        ) as Row | null
+      if (!artifact) throw artifactStorageErrors.exists(input.id)
+      return {
+        artifact: parseArtifactRow(artifact),
+        version: this.insertVersion(input.projectId, input.id, 1, input.version),
+      }
+    })
+  }
+
+  async publish(input: PublishArtifactVersionInput): Promise<PublishedArtifactVersion> {
+    return runImmediateTransaction(this.db, () => {
+      const current = this.db
+        .query(
+          `SELECT kind, next_version AS nextVersion, latest_version AS latestVersion
+           FROM artifacts WHERE project_id = ? AND id = ?`
+        )
+        .get(input.projectId, input.artifactId) as {
+        readonly kind: ArtifactRecord["kind"]
+        readonly nextVersion: number
+        readonly latestVersion: number
+      } | null
+      if (!current) throw artifactStorageErrors.notFound(input.artifactId)
+      if (current.kind !== input.kind) {
+        throw artifactStorageErrors.kindMismatch(input.artifactId, current.kind, input.kind)
+      }
+      // Inside the write transaction: a publish from the same base after this one finds it moved.
+      if (input.baseVersion !== undefined && current.latestVersion !== input.baseVersion) {
+        const latest = parseArtifactVersionRow(
+          this.db
+            .query(
+              `SELECT ${VERSION_COLUMNS} FROM artifact_versions
+               WHERE project_id = ? AND artifact_id = ? AND version = ?`
+            )
+            .get(input.projectId, input.artifactId, current.latestVersion) as Row
+        )
+        throw artifactStorageErrors.moved(input.artifactId, input.baseVersion, {
+          version: latest.version,
+          author: latest.author,
+        })
+      }
+      const version = this.insertVersion(
+        input.projectId,
+        input.artifactId,
+        current.nextVersion,
+        input.version
+      )
+      const artifact = this.db
+        .query(
+          `UPDATE artifacts
+           SET title = ?, latest_version = ?, next_version = ?, updated_at = ?
+           WHERE project_id = ? AND id = ?
+           RETURNING ${ARTIFACT_COLUMNS}`
+        )
+        .get(
+          input.version.title,
+          version.version,
+          version.version + 1,
+          input.version.createdAt.toISOString(),
+          input.projectId,
+          input.artifactId
+        ) as Row
+      return { artifact: parseArtifactRow(artifact), version }
+    })
+  }
+
+  async get(input: GetArtifactInput): Promise<ArtifactRecord | null> {
+    const row = this.db
+      .query(`SELECT ${ARTIFACT_COLUMNS} FROM artifacts WHERE project_id = ? AND id = ?`)
+      .get(input.projectId, input.id) as Row | null
+    return row ? parseArtifactRow(row) : null
+  }
+
+  async list(input: ListArtifactsInput): Promise<ListArtifactsResult> {
+    const where = ["a.project_id = ?"]
+    const params: SQLQueryBindings[] = [input.projectId]
+    if (input.owner) {
+      where.push("a.owner_principal_type = ? AND a.owner_principal_id = ?")
+      params.push(input.owner.type, 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.push(input.threadId)
+    }
+    if (input.kind !== undefined) {
+      where.push("a.kind = ?")
+      params.push(input.kind)
+    }
+    const clause = where.join(" AND ")
+    const { total } = this.db
+      .query(`SELECT COUNT(*) AS total FROM artifacts a WHERE ${clause}`)
+      .get(...params) as { readonly total: number }
+    const offset = input.offset ?? 0
+    const rows = this.db
+      .query(
+        `SELECT ${ARTIFACT_COLUMNS} FROM artifacts a WHERE ${clause}
+         ORDER BY a.updated_at DESC, a.id ASC LIMIT ? OFFSET ?`
+      )
+      .all(...params, input.limit ?? -1, offset) as Row[]
+    return {
+      artifacts: rows.map(parseArtifactRow),
+      hasMore: offset + rows.length < total,
+      total,
+    }
+  }
+
+  async getVersion(input: GetArtifactVersionInput): Promise<ArtifactVersionRecord | null> {
+    const row = this.db
+      .query(
+        `SELECT ${VERSION_COLUMNS} FROM artifact_versions
+         WHERE project_id = ? AND artifact_id = ? AND version = ?`
+      )
+      .get(input.projectId, input.artifactId, input.version) as Row | null
+    return row ? parseArtifactVersionRow(row) : null
+  }
+
+  async listVersions(input: ListArtifactVersionsInput): Promise<ListArtifactVersionsResult> {
+    const { total } = this.db
+      .query(
+        "SELECT COUNT(*) AS total FROM artifact_versions WHERE project_id = ? AND artifact_id = ?"
+      )
+      .get(input.projectId, input.artifactId) as { readonly total: number }
+    const offset = input.offset ?? 0
+    const rows = this.db
+      .query(
+        `SELECT ${VERSION_COLUMNS} FROM artifact_versions
+         WHERE project_id = ? AND artifact_id = ?
+         ORDER BY version DESC LIMIT ? OFFSET ?`
+      )
+      .all(input.projectId, input.artifactId, input.limit ?? -1, offset) as Row[]
+    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 = this.db
+      .query(
+        `SELECT ${VERSION_COLUMNS} FROM artifact_versions v
+         WHERE (project_id, artifact_id, version) IN (
+           SELECT project_id, id, latest_version FROM artifacts WHERE project_id = ?
+         ) AND EXISTS (
+           SELECT 1 FROM json_each(v.refs) r
+           WHERE substr(json_extract(r.value, '$.address'), 1, ?) = ?
+             AND substr(json_extract(r.value, '$.address'), ? + 1, 1) IN ('', '@', '/', '#')
+         )
+         ORDER BY artifact_id`
+      )
+      .all(input.projectId, prefix.length, prefix, prefix.length) as Row[]
+    return rows.map(parseArtifactVersionRow)
+  }
+
+  async listThreadIds(input: GetArtifactInput): Promise<string[]> {
+    const rows = this.db
+      .query(
+        `SELECT thread_id AS threadId FROM artifact_threads
+         WHERE project_id = ? AND artifact_id = ? ORDER BY thread_id`
+      )
+      .all(input.projectId, input.id) as { readonly threadId: string }[]
+    return rows.map((row) => row.threadId)
+  }
+
+  async copy(input: CopyArtifactInput): Promise<ArtifactRecord> {
+    return runImmediateTransaction(this.db, () => {
+      const source = this.db
+        .query("SELECT id FROM artifacts WHERE project_id = ? AND id = ?")
+        .get(input.projectId, input.sourceId)
+      if (!source) throw artifactStorageErrors.notFound(input.sourceId)
+
+      const artifact = this.db
+        .query(
+          `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, ?, kind, title, ?, ?, latest_version, next_version, created_at,
+                 updated_at
+          FROM artifacts WHERE project_id = ? AND id = ?
+          ON CONFLICT (project_id, id) DO NOTHING
+          RETURNING ${ARTIFACT_COLUMNS}`
+        )
+        .get(
+          input.id,
+          input.owner.type,
+          input.owner.id,
+          input.projectId,
+          input.sourceId
+        ) as Row | null
+      if (!artifact) throw artifactStorageErrors.exists(input.id)
+
+      this.db
+        .query(
+          `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, ?, version, title, entry, files, outline, refs,
+                 author_principal_type, author_principal_id, created_at
+          FROM artifact_versions WHERE project_id = ? AND artifact_id = ?`
+        )
+        .run(input.id, input.projectId, input.sourceId)
+      this.db
+        .query(
+          `INSERT INTO artifact_threads (project_id, artifact_id, thread_id, shared_at, copied)
+           VALUES (?, ?, ?, ?, 1)`
+        )
+        .run(
+          input.projectId,
+          input.id,
+          input.threadId,
+          (input.copiedAt ?? new Date()).toISOString()
+        )
+      return parseArtifactRow(artifact)
+    })
+  }
+
+  async createFrameGrant(record: ArtifactFrameGrantRecord): Promise<void> {
+    runImmediateTransaction(this.db, () => {
+      const exists = this.db
+        .query("SELECT 1 FROM artifacts WHERE project_id = ? AND id = ?")
+        .get(record.projectId, record.artifactId)
+      if (!exists) throw artifactStorageErrors.notFound(record.artifactId)
+      this.db
+        .query(
+          `INSERT INTO artifact_frame_grants
+             (project_id, token_hash, artifact_id, version, targets, created_at, expires_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`
+        )
+        .run(
+          record.projectId,
+          record.tokenHash,
+          record.artifactId,
+          record.version,
+          JSON.stringify(record.targets),
+          record.createdAt.toISOString(),
+          record.expiresAt.toISOString()
+        )
+    })
+  }
+
+  async findFrameGrant(
+    input: FindArtifactFrameGrantInput
+  ): Promise<ArtifactFrameGrantRecord | null> {
+    const row = this.db
+      .query(
+        `SELECT ${FRAME_GRANT_COLUMNS} FROM artifact_frame_grants
+         WHERE project_id = ? AND token_hash = ?`
+      )
+      .get(input.projectId, input.tokenHash) as Row | null
+    return row ? parseArtifactFrameGrantRow(row) : null
+  }
+
+  async deleteExpiredFrameGrants(input: DeleteExpiredArtifactFrameGrantsInput): Promise<number> {
+    return this.db
+      .query(
+        `DELETE FROM artifact_frame_grants WHERE rowid IN (
+           SELECT rowid FROM artifact_frame_grants
+           WHERE project_id = ? AND expires_at < ?
+           ORDER BY expires_at LIMIT ?
+         )`
+      )
+      .run(input.projectId, input.expiredBefore.toISOString(), input.limit).changes
+  }
+
+  async getState(input: ArtifactStateKeyInput): Promise<ArtifactStateEntry | null> {
+    const row = this.db
+      .query(`SELECT ${STATE_COLUMNS} FROM artifact_state WHERE ${STATE_SCOPE} AND key = ?`)
+      .get(...stateScope(input), input.key) as Row | null
+    return row ? parseArtifactStateRow(row) : null
+  }
+
+  async setState(input: SetArtifactStateInput): Promise<void> {
+    runImmediateTransaction(this.db, () => {
+      const artifact = this.db
+        .query("SELECT 1 FROM artifacts WHERE project_id = ? AND id = ?")
+        .get(input.projectId, input.artifactId)
+      if (!artifact) throw artifactStorageErrors.notFound(input.artifactId)
+      // In the write transaction: two writes at once cannot both fit under the limits.
+      const others = this.db
+        .query(
+          `SELECT count(*) AS keys, coalesce(sum(size_bytes), 0) AS bytes FROM artifact_state
+           WHERE ${STATE_SCOPE} AND key <> ?`
+        )
+        .get(...stateScope(input), input.key) as { readonly keys: number; readonly bytes: number }
+      const sizeBytes = artifactStateBytes(input.value)
+      checkArtifactStateWrite({ key: input.key, valueBytes: sizeBytes, others })
+      this.db
+        .query(
+          `INSERT INTO artifact_state (
+            project_id, artifact_id, principal_type, principal_id, key, value, size_bytes,
+            updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          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`
+        )
+        .run(...stateScope(input), input.key, input.value, sizeBytes, input.updatedAt.toISOString())
+    })
+  }
+
+  async deleteState(input: ArtifactStateKeyInput): Promise<boolean> {
+    return (
+      this.db
+        .query(`DELETE FROM artifact_state WHERE ${STATE_SCOPE} AND key = ?`)
+        .run(...stateScope(input), input.key).changes > 0
+    )
+  }
+
+  async listState(input: ArtifactStateScope): Promise<ArtifactStateEntry[]> {
+    const rows = this.db
+      .query(`SELECT ${STATE_COLUMNS} FROM artifact_state WHERE ${STATE_SCOPE} ORDER BY key`)
+      .all(...stateScope(input)) as Row[]
+    return rows.map(parseArtifactStateRow)
+  }
+
+  async clearState(input: ArtifactStateScope): Promise<number> {
+    return this.db
+      .query(`DELETE FROM artifact_state WHERE ${STATE_SCOPE}`)
+      .run(...stateScope(input)).changes
+  }
+
+  async delete(input: DeleteArtifactInput): Promise<boolean> {
+    // Versions, frame grants, and state go with the artifact through ON DELETE CASCADE.
+    return (
+      this.db
+        .query("DELETE FROM artifacts WHERE project_id = ? AND id = ?")
+        .run(input.projectId, input.id).changes > 0
+    )
+  }
+
+  async deleteVersionsByOrigin(input: DeleteArtifactVersionsByOriginInput): Promise<number> {
+    return runImmediateTransaction(this.db, () => {
+      const affected = this.db
+        .query(
+          `SELECT DISTINCT artifact_id AS artifactId FROM artifact_versions
+           WHERE project_id = ? AND origin_run_id = ?`
+        )
+        .all(input.projectId, input.runId) as { readonly artifactId: string }[]
+      const deleted = this.db
+        .query(
+          `DELETE FROM artifact_versions WHERE project_id = ? AND origin_run_id = ?
+           RETURNING origin_thread_id AS threadId`
+        )
+        .all(input.projectId, input.runId) as { readonly threadId: string }[]
+      // 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]?.threadId
+      for (const { artifactId } of affected) {
+        this.db
+          .query(
+            `DELETE FROM artifact_threads
+             WHERE project_id = ? AND artifact_id = ? AND thread_id = ? AND copied = 0
+               AND NOT EXISTS (
+                 SELECT 1 FROM artifact_versions
+                 WHERE project_id = ? AND artifact_id = ? AND origin_thread_id = ?
+               )`
+          )
+          .run(
+            input.projectId,
+            artifactId,
+            threadId ?? null,
+            input.projectId,
+            artifactId,
+            threadId ?? null
+          )
+        this.repointLatest(input.projectId, artifactId)
+      }
+      return deleted.length
+    })
+  }
+
+  /** Point an artifact at its newest remaining version, or delete it when none remains. */
+  private repointLatest(projectId: string, artifactId: string): void {
+    const latest = this.db
+      .query(
+        `SELECT version, title, created_at AS createdAt FROM artifact_versions
+         WHERE project_id = ? AND artifact_id = ? ORDER BY version DESC LIMIT 1`
+      )
+      .get(projectId, artifactId) as {
+      readonly version: number
+      readonly title: string
+      readonly createdAt: string
+    } | null
+    if (!latest) {
+      this.db
+        .query("DELETE FROM artifacts WHERE project_id = ? AND id = ?")
+        .run(projectId, artifactId)
+      return
+    }
+    this.db
+      .query(
+        `UPDATE artifacts SET title = ?, latest_version = ?, updated_at = ?
+         WHERE project_id = ? AND id = ?`
+      )
+      .run(latest.title, latest.version, latest.createdAt, projectId, artifactId)
+  }
+
+  private insertVersion(
+    projectId: string,
+    artifactId: string,
+    version: number,
+    input: ArtifactVersionInput
+  ): ArtifactVersionRecord {
+    const row = this.db
+      .query(
+        `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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        RETURNING ${VERSION_COLUMNS}`
+      )
+      .get(
+        projectId,
+        artifactId,
+        version,
+        input.title,
+        input.entry,
+        JSON.stringify(input.files),
+        JSON.stringify(input.outline),
+        JSON.stringify(input.references),
+        input.author.type,
+        input.author.id,
+        input.origin?.threadId ?? null,
+        input.origin?.runId ?? null,
+        input.createdAt.toISOString()
+      ) as Row
+    if (input.origin) {
+      this.linkThread(projectId, artifactId, input.origin.threadId, input.createdAt)
+    }
+    return parseArtifactVersionRow(row)
+  }
+
+  /** Shares an artifact in a thread, keeping when it was first shared there. */
+  private linkThread(
+    projectId: string,
+    artifactId: string,
+    threadId: string,
+    sharedAt: Date
+  ): void {
+    this.db
+      .query(
+        `INSERT INTO artifact_threads (project_id, artifact_id, thread_id, shared_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT (project_id, artifact_id, thread_id) DO NOTHING`
+      )
+      .run(projectId, artifactId, threadId, sharedAt.toISOString())
+  }
+}