@sixb/sqlite 0.1.20 → 0.1.22

package/src/auth-storage/auth-storage.ts

@@ -12,6 +12,7 @@ import type {
   InvitationRecord,
   SessionRecord,
   SuspendUserAndRevokeSessionsInput,
+  UpdateAuthUserResult,
   UserIdentityRecord,
   UserRecord,
 } from "@sixb/core/storage"
@@ -32,7 +33,7 @@ import { SqliteAuthUserIdentityStore } from "./identities"
 import { SqliteAuthInvitationStore } from "./invitations"
 import { SqliteAuthMagicLinkStore } from "./magic-links"
 import { SqliteAuthOidcAuthorizationAttemptStore } from "./oidc-attempts"
-import type { SqliteAuthMagicLinkRow, SqliteAuthOidcAttemptRow } from "./rows"
+import type { SqliteAuthMagicLinkRow, SqliteAuthOidcAttemptRow, SqliteAuthUserRow } from "./rows"
 import { rowToIdentityRecord, rowToUserRecord, serializeOptionalRecord } from "./rows"
 import { SqliteAuthServiceAccountGroupMembershipStore } from "./service-account-group-memberships"
 import { SqliteAuthServiceAccountStore } from "./service-accounts"
@@ -216,16 +217,17 @@ export class SqliteAuthStorage implements AuthStorage {
           consumedAt: completedAt,
         })
 
-        const user = existingUserRow
-          ? rowToUserRecord(existingUserRow)
-          : this.insertUser({
-              id: newUserId ?? assertNonEmpty(input.newUserId, "User id"),
-              projectId,
-              email: magicLink.email,
-              displayName: input.newUserDisplayName,
-              avatarUrl: input.newUserAvatarUrl,
-              createdAt: completedAt,
-            })
+        const previousUser = existingUserRow ? rowToUserRecord(existingUserRow) : null
+        const user =
+          previousUser ??
+          this.insertUser({
+            id: newUserId ?? assertNonEmpty(input.newUserId, "User id"),
+            projectId,
+            email: magicLink.email,
+            displayName: input.newUserDisplayName,
+            avatarUrl: input.newUserAvatarUrl,
+            createdAt: completedAt,
+          })
 
         const invitation = this.acceptInvitationAndApplyGroups({
           activeInvitation,
@@ -253,6 +255,7 @@ export class SqliteAuthStorage implements AuthStorage {
           session,
           invitation: invitation.invitation,
           groupMemberships,
+          previousUser,
         }
       }
     )
@@ -297,7 +300,7 @@ export class SqliteAuthStorage implements AuthStorage {
               email,
               now: completedAt,
             })
-        let userRow = identity
+        const userRow = identity
           ? getUserRowById(this.db, { projectId, id: identity.user_id })
           : getUserRowByEmail(this.db, { projectId, email })
         const shouldCreateUser = !identity && !userRow
@@ -348,8 +351,10 @@ export class SqliteAuthStorage implements AuthStorage {
 
         this.consumeOidcAttempt(input, completedAt, projectId)
 
+        const previousUser = userRow ? rowToUserRecord(userRow) : null
+        let user: UserRecord
         if (!userRow) {
-          const user = this.insertUser({
+          user = this.insertUser({
             id: newUserId ?? assertNonEmpty(input.newUserId, "User id"),
             projectId,
             email,
@@ -357,19 +362,10 @@ export class SqliteAuthStorage implements AuthStorage {
             avatarUrl: input.avatarUrl,
             createdAt: completedAt,
           })
-          userRow = {
-            project_id: user.projectId,
-            id: user.id,
-            email: user.email,
-            display_name: user.displayName ?? null,
-            avatar_url: user.avatarUrl ?? null,
-            status: user.status,
-            created_at: toIso(user.createdAt),
-            updated_at: toIso(user.updatedAt),
-          }
+        } else {
+          user = this.refreshProviderProfile(userRow, input, completedAt)
         }
 
-        const user = rowToUserRecord(userRow)
         const invitation = this.acceptInvitationAndApplyGroups({
           activeInvitation,
           completedAt,
@@ -412,6 +408,7 @@ export class SqliteAuthStorage implements AuthStorage {
           identity: nextIdentity,
           invitation: invitation.invitation,
           groupMemberships,
+          previousUser,
         }
       }
     )
@@ -425,7 +422,7 @@ export class SqliteAuthStorage implements AuthStorage {
 
   async suspendUserAndRevokeSessions(
     input: SuspendUserAndRevokeSessionsInput
-  ): Promise<UserRecord> {
+  ): Promise<UpdateAuthUserResult> {
     return runImmediateTransaction(this.db, () => {
       const existing = getUserRowById(this.db, {
         projectId: input.projectId,
@@ -456,11 +453,12 @@ export class SqliteAuthStorage implements AuthStorage {
         revokedAt: input.suspendedAt,
       })
 
-      return rowToUserRecord({
+      const user = rowToUserRecord({
         ...existing,
         status: "suspended",
         updated_at: toIso(input.suspendedAt),
       })
+      return { user, previousUser: rowToUserRecord(existing) }
     })
   }
 
@@ -526,6 +524,40 @@ export class SqliteAuthStorage implements AuthStorage {
     }
   }
 
+  // The identity provider owns the name and picture it sends: every sign-in overwrites them, and
+  // one it leaves out keeps the stored value.
+  private refreshProviderProfile(
+    row: SqliteAuthUserRow,
+    input: CompleteOidcSignInInput,
+    updatedAt: Date
+  ): UserRecord {
+    const displayName = input.displayName ?? row.display_name
+    const avatarUrl = input.avatarUrl ?? row.avatar_url
+    if (displayName === row.display_name && avatarUrl === row.avatar_url) {
+      return rowToUserRecord(row)
+    }
+
+    this.db
+      .query(
+        `
+        UPDATE auth_users
+        SET display_name = ?,
+            avatar_url = ?,
+            updated_at = ?
+        WHERE project_id = ?
+          AND id = ?
+      `
+      )
+      .run(displayName, avatarUrl, toIso(updatedAt), row.project_id, row.id)
+
+    return rowToUserRecord({
+      ...row,
+      display_name: displayName,
+      avatar_url: avatarUrl,
+      updated_at: toIso(updatedAt),
+    })
+  }
+
   private insertUser(input: {
     readonly id: string
     readonly projectId: string

package/src/auth-storage/sessions.ts

@@ -2,6 +2,8 @@ import type { Database } from "bun:sqlite"
 import type {
   AuthSessionStore,
   CreateAuthSessionInput,
+  ListAuthSessionsInput,
+  ListAuthSessionsResult,
   RotateSessionRefreshTokenResult,
   SessionRecord,
 } from "@sixb/core/storage"
@@ -60,6 +62,31 @@ export class SqliteAuthSessionStore implements AuthSessionStore {
     return rows.map(rowToSessionRecord)
   }
 
+  async listByUserId(params: ListAuthSessionsInput): Promise<ListAuthSessionsResult> {
+    const rows = this.db
+      .query(
+        `
+        SELECT *
+        FROM auth_sessions
+        WHERE project_id = ? AND user_id = ? AND created_at <= ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ? OFFSET ?
+      `
+      )
+      .all(
+        params.projectId,
+        params.userId,
+        params.before ? toIso(params.before.createdAt) : "9999-12-31T23:59:59.999Z",
+        params.limit + 1,
+        params.before?.skip ?? 0
+      ) as SqliteAuthSessionRow[]
+
+    return {
+      sessions: rows.slice(0, params.limit).map(rowToSessionRecord),
+      hasMore: rows.length > params.limit,
+    }
+  }
+
   async findValidByTokenHash(params: {
     readonly projectId: string
     readonly id: string

package/src/auth-storage/users.ts

@@ -5,10 +5,12 @@ import type {
   ListAuthUsersInput,
   ListAuthUsersResult,
   UpdateAuthUserProfileInput,
+  UpdateAuthUserResult,
   UpdateAuthUserStatusInput,
   UserRecord,
 } from "@sixb/core/storage"
 import { AuthStorageError } from "@sixb/core/storage"
+import { runImmediateTransaction } from "../transactions"
 import type { SqliteAuthUserRow } from "./rows"
 import { rowToUserRecord } from "./rows"
 import {
@@ -103,6 +105,22 @@ export class SqliteAuthUserStore implements AuthUserStore {
     return row ? rowToUserRecord(row) : null
   }
 
+  async getByIds(params: {
+    readonly projectId: string
+    readonly ids: readonly string[]
+  }): Promise<readonly UserRecord[]> {
+    const ids = [...new Set(params.ids)]
+    if (ids.length === 0) return []
+
+    const rows = this.db
+      .query(
+        `SELECT * FROM auth_users WHERE project_id = ? AND id IN (${ids.map(() => "?").join(", ")})`
+      )
+      .all(params.projectId, ...ids) as SqliteAuthUserRow[]
+
+    return rows.map(rowToUserRecord)
+  }
+
   async getByEmail(params: {
     readonly projectId: string
     readonly email: string
@@ -111,77 +129,87 @@ export class SqliteAuthUserStore implements AuthUserStore {
     return row ? rowToUserRecord(row) : null
   }
 
-  async updateProfile(input: UpdateAuthUserProfileInput): Promise<UserRecord> {
-    const existing = getUserRowById(this.db, {
-      projectId: input.projectId,
-      id: input.id,
-    })
+  async updateProfile(input: UpdateAuthUserProfileInput): Promise<UpdateAuthUserResult> {
+    // One transaction, so the user it returns as previous is the one it changed.
+    return runImmediateTransaction(this.db, () => {
+      const existing = getUserRowById(this.db, {
+        projectId: input.projectId,
+        id: input.id,
+      })
 
-    if (!existing) {
-      throw new AuthStorageError(
-        "missing_user",
-        `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
-      )
-    }
+      if (!existing) {
+        throw new AuthStorageError(
+          "missing_user",
+          `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
+        )
+      }
 
-    const updatedAt = dateOrNow(input.updatedAt)
-    this.db
-      .query(
+      const previousUser = rowToUserRecord(existing)
+      if (!changesProfile(previousUser, input)) {
+        return { user: previousUser, previousUser }
+      }
+
+      const updatedAt = dateOrNow(input.updatedAt)
+      const row = this.db
+        .query(
+          `
+          UPDATE auth_users
+          SET display_name = CASE WHEN ? THEN ? ELSE display_name END,
+              avatar_url = CASE WHEN ? THEN ? ELSE avatar_url END,
+              updated_at = ?
+          WHERE project_id = ?
+            AND id = ?
+          RETURNING *
         `
-        UPDATE auth_users
-        SET display_name = ?,
-            avatar_url = ?,
-            updated_at = ?
-        WHERE project_id = ?
-          AND id = ?
-      `
-      )
-      .run(
-        input.displayName ?? null,
-        input.avatarUrl ?? null,
-        toIso(updatedAt),
-        input.projectId,
-        input.id
-      )
+        )
+        .get(
+          input.displayName === undefined ? 0 : 1,
+          input.displayName ?? null,
+          input.avatarUrl === undefined ? 0 : 1,
+          input.avatarUrl ?? null,
+          toIso(updatedAt),
+          input.projectId,
+          input.id
+        ) as SqliteAuthUserRow
 
-    return rowToUserRecord({
-      ...existing,
-      display_name: input.displayName ?? null,
-      avatar_url: input.avatarUrl ?? null,
-      updated_at: toIso(updatedAt),
+      return { user: rowToUserRecord(row), previousUser }
     })
   }
 
-  async updateStatus(input: UpdateAuthUserStatusInput): Promise<UserRecord> {
-    const existing = getUserRowById(this.db, {
-      projectId: input.projectId,
-      id: input.id,
-    })
+  async updateStatus(input: UpdateAuthUserStatusInput): Promise<UpdateAuthUserResult> {
+    // One transaction, so two status changes cannot both report the same previous one.
+    return runImmediateTransaction(this.db, () => {
+      const existing = getUserRowById(this.db, {
+        projectId: input.projectId,
+        id: input.id,
+      })
 
-    if (!existing) {
-      throw new AuthStorageError(
-        "missing_user",
-        `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
-      )
-    }
+      if (!existing) {
+        throw new AuthStorageError(
+          "missing_user",
+          `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
+        )
+      }
 
-    const updatedAt = dateOrNow(input.updatedAt)
-    this.db
-      .query(
+      const updatedAt = dateOrNow(input.updatedAt)
+      this.db
+        .query(
+          `
+          UPDATE auth_users
+          SET status = ?,
+              updated_at = ?
+          WHERE project_id = ?
+            AND id = ?
         `
-        UPDATE auth_users
-        SET status = ?,
-            updated_at = ?
-        WHERE project_id = ?
-          AND id = ?
-      `
-      )
-      .run(input.status, toIso(updatedAt), input.projectId, input.id)
+        )
+        .run(input.status, toIso(updatedAt), input.projectId, input.id)
 
-    return rowToUserRecord({
-      ...existing,
-      status: input.status,
-      updated_at: toIso(updatedAt),
+      const user = rowToUserRecord({
+        ...existing,
+        status: input.status,
+        updated_at: toIso(updatedAt),
+      })
+      return { user, previousUser: rowToUserRecord(existing) }
     })
   }
 
@@ -198,6 +226,15 @@ export class SqliteAuthUserStore implements AuthUserStore {
       args.push(...input.statuses)
     }
 
+    // `instr` matches literally, so `%` and `_` need no escaping. Both sides fold through the same
+    // `lower()`, which ignores case for ASCII letters only: "émilie" does not find "Émilie" here.
+    if (input.search !== undefined) {
+      whereClauses.push(
+        "(instr(lower(coalesce(display_name, '')), lower(?)) > 0 OR instr(lower(email), lower(?)) > 0)"
+      )
+      args.push(input.search, input.search)
+    }
+
     const where = `WHERE ${whereClauses.join(" AND ")}`
     const order = input.order === "asc" ? "ASC" : "DESC"
     const totalRow = this.db
@@ -224,3 +261,12 @@ export class SqliteAuthUserStore implements AuthUserStore {
     }
   }
 }
+
+// Omitted keeps the stored value, and `null` clears it.
+function changesProfile(user: UserRecord, input: UpdateAuthUserProfileInput): boolean {
+  const displayName =
+    input.displayName === undefined ? user.displayName : (input.displayName ?? undefined)
+  const avatarUrl = input.avatarUrl === undefined ? user.avatarUrl : (input.avatarUrl ?? undefined)
+
+  return displayName !== user.displayName || avatarUrl !== user.avatarUrl
+}

package/src/execution-storage.ts

@@ -1,5 +1,6 @@
 import type { Database } from "bun:sqlite"
 import {
+  compareExecutionCreation,
   type ExecutionStorageRow,
   executionRecordFromStorageRow,
   executionRecordToStorageRow,
@@ -7,8 +8,12 @@ import {
 } from "@sixb/core/internal/execution-storage"
 import type {
   CreateExecutionInput,
+  ExecutionDescendant,
   ExecutionRecord,
   ExecutionStorage,
+  ListExecutionDescendantsInput,
+  ListSessionExecutionsInput,
+  SessionExecutions,
   ShareSessionStorage,
 } from "@sixb/core/storage"
 import { ExecutionStorageError } from "@sixb/core/storage"
@@ -115,6 +120,96 @@ export class SqliteExecutionStorage implements ExecutionStorage {
 
     return row ? sqliteExecutionRecord(row) : null
   }
+
+  async listBySession(input: ListSessionExecutionsInput): Promise<SessionExecutions> {
+    const sessionColumn =
+      input.session.type === "user" ? "authority_session_id" : "authority_delegation_session_id"
+
+    // The queue is ordered by depth, so the walk takes roots, then their children level by level,
+    // the earliest first, and the limit stops it: a large tree costs no more than the rows
+    // returned. CROSS JOIN keeps the walk driven by the rows found: statistics taken on a small
+    // ledger choose to scan every child.
+    const rows = this.db
+      .query(
+        `
+        WITH RECURSIVE tree AS (
+          SELECT roots.*, 0 AS depth
+          FROM (
+            SELECT *
+            FROM executions
+            WHERE project_id = ?
+              AND ${sessionColumn} = ?
+              AND parent_execution_id IS NULL
+              AND created_at >= ?
+              AND created_at < ?
+            ORDER BY created_at, id
+            LIMIT ?
+          ) roots
+          UNION ALL
+          SELECT child.*, tree.depth + 1
+          FROM tree
+          CROSS JOIN executions child
+            ON child.project_id = tree.project_id
+            AND child.parent_execution_id = tree.id
+          ORDER BY depth, created_at, id
+          LIMIT ?
+        )
+        SELECT * FROM tree
+      `
+      )
+      .all(
+        input.projectId,
+        input.session.id,
+        input.from.toISOString(),
+        input.to.toISOString(),
+        input.limit + 1,
+        input.limit + 1
+      ) as SqliteExecutionRow[]
+
+    // Rows come out in walk order, so the first `limit` are the ones the contract keeps.
+    const kept = rows.slice(0, input.limit).map(sqliteExecutionRecord)
+    return {
+      executions: kept.sort(compareExecutionCreation),
+      truncated: rows.length > input.limit,
+    }
+  }
+
+  async listDescendants(
+    input: ListExecutionDescendantsInput
+  ): Promise<readonly ExecutionDescendant[]> {
+    if (input.executionIds.length === 0) return []
+    const ids = [...new Set(input.executionIds)]
+
+    // UNION, not UNION ALL: an execution asked about may sit below another one asked about, and
+    // the walk would otherwise reach what it caused twice.
+    const rows = this.db
+      .query(
+        `
+        WITH RECURSIVE tree(id, parent_id) AS (
+          SELECT child.id, child.parent_execution_id
+          FROM executions child
+          WHERE child.project_id = ?
+            AND child.parent_execution_id IN (SELECT value FROM json_each(?))
+          UNION
+          SELECT child.id, child.parent_execution_id
+          FROM tree
+          CROSS JOIN executions child
+            ON child.project_id = ?
+            AND child.parent_execution_id = tree.id
+        )
+        SELECT id, parent_id
+        FROM tree
+        WHERE id NOT IN (SELECT value FROM json_each(?))
+        ORDER BY id
+      `
+      )
+      .all(input.projectId, JSON.stringify(ids), input.projectId, JSON.stringify(ids)) as {
+      id: string
+      parent_id: string
+    }[]
+
+    return rows.map((row) => ({ id: row.id, parentId: row.parent_id }))
+  }
 }
 
 /** An `executions` row as its record, for any store that reads executions alongside its own rows. */

package/src/index.ts

@@ -32,10 +32,12 @@ import {
   StorageTransactionError,
 } from "@sixb/core/storage"
 import { SqliteActionRunStorage } from "./action-run-storage"
+import { SqliteActivityStorage } from "./activity-storage"
 import { SqliteAgentStorage } from "./agents"
 import { SqliteAiCostStorage } from "./ai-cost-storage"
 import { SqliteAiLimitStorage } from "./ai-limit-storage"
 import { SqliteAiUsageStorage } from "./ai-usage-storage"
+import { SqliteArtifactStorage } from "./artifact-storage"
 import { SqliteAuthStorage } from "./auth-storage"
 import { SqliteConnectorConnectionStorage } from "./connector-connection-storage"
 import { SqliteExecutionStorage } from "./execution-storage"
@@ -89,6 +91,7 @@ export class SqliteStorage implements MigrationCapableStorage {
   readonly auth: SqliteAuthStorage
   readonly executions: SqliteExecutionStorage
   readonly agents: SqliteAgentStorage
+  readonly artifacts: SqliteArtifactStorage
   readonly aiUsage: AiUsageStorage
   readonly aiCosts: AiCostStorage
   readonly aiLimits: AiLimitStorage
@@ -106,6 +109,7 @@ export class SqliteStorage implements MigrationCapableStorage {
   readonly connectorConnections: SqliteConnectorConnectionStorage
   readonly fileUploadSessions: SqliteFileUploadSessionStorage
   readonly fileDownloadGrants: SqliteFileDownloadGrantStorage
+  readonly activity: SqliteActivityStorage
   readonly migrators: readonly StorageMigrator[]
 
   private readonly connection: SqliteStoreConnection
@@ -153,6 +157,7 @@ export class SqliteStorage implements MigrationCapableStorage {
     this.auth = createAuthOperationScope(stores.auth, scope)
     this.executions = createOperationScopedFacade(stores.executions, scope)
     this.agents = createAgentOperationScope(stores.agents, scope)
+    this.artifacts = createOperationScopedFacade(stores.artifacts, scope)
     this.aiUsage = createOperationScopedFacade(stores.aiUsage, scope)
     this.aiCosts = createOperationScopedFacade(stores.aiCosts, scope)
     this.aiLimits = createOperationScopedFacade(stores.aiLimits, scope)
@@ -170,6 +175,7 @@ export class SqliteStorage implements MigrationCapableStorage {
     this.connectorConnections = createOperationScopedFacade(stores.connectorConnections, scope)
     this.fileUploadSessions = createOperationScopedFacade(stores.fileUploadSessions, scope)
     this.fileDownloadGrants = createOperationScopedFacade(stores.fileDownloadGrants, scope)
+    this.activity = createOperationScopedFacade(stores.activity, scope)
     this.migrators = options.path ? createSqliteStorageMigrators(options.path) : []
     registerSqliteStorageTestingAdapter(this, {
       advanceConnectorConnectionTime: (durationMs) =>
@@ -317,6 +323,7 @@ function createSqliteStores(
     auth,
     executions,
     agents: new SqliteAgentStorage({ connection, executions }),
+    artifacts: new SqliteArtifactStorage(connection),
     aiUsage: new SqliteAiUsageStorage({ connection }),
     aiCosts: new SqliteAiCostStorage(connection),
     aiLimits: new SqliteAiLimitStorage({ connection }),
@@ -334,6 +341,7 @@ function createSqliteStores(
     connectorConnections: new SqliteConnectorConnectionStorage(connection),
     fileUploadSessions: new SqliteFileUploadSessionStorage(connection),
     fileDownloadGrants: new SqliteFileDownloadGrantStorage(connection),
+    activity: new SqliteActivityStorage(connection),
   }
 }
 
@@ -343,6 +351,7 @@ interface SqliteStoreSet {
   readonly auth: SqliteAuthStorage
   readonly executions: SqliteExecutionStorage
   readonly agents: SqliteAgentStorage
+  readonly artifacts: SqliteArtifactStorage
   readonly aiUsage: SqliteAiUsageStorage
   readonly aiCosts: SqliteAiCostStorage
   readonly aiLimits: SqliteAiLimitStorage
@@ -360,6 +369,7 @@ interface SqliteStoreSet {
   readonly connectorConnections: SqliteConnectorConnectionStorage
   readonly fileUploadSessions: SqliteFileUploadSessionStorage
   readonly fileDownloadGrants: SqliteFileDownloadGrantStorage
+  readonly activity: SqliteActivityStorage
 }
 
 export { migrateSqliteStorage } from "./migrations"

package/src/migrations/062-artifacts.sql

@@ -0,0 +1,71 @@
+-- Artifacts: versioned documents, sheets, decks, and files. An artifact's kind never
+-- changes. Versions take `next_version`, which only grows, so a number is never reused after its
+-- version is deleted. Timestamps are ISO-8601 UTC text and compare lexicographically.
+CREATE TABLE artifacts (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  id TEXT NOT NULL CHECK (length(trim(id)) > 0),
+  kind TEXT NOT NULL CHECK (kind IN ('document', 'sheet', 'slides', 'file')),
+  title TEXT NOT NULL CHECK (length(trim(title)) > 0),
+  owner_principal_type TEXT NOT NULL
+    CHECK (owner_principal_type IN ('user', 'serviceAccount', 'system')),
+  owner_principal_id TEXT NOT NULL CHECK (length(owner_principal_id) > 0),
+  latest_version INTEGER NOT NULL CHECK (latest_version > 0),
+  next_version INTEGER NOT NULL CHECK (next_version > latest_version),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (project_id, id)
+);
+
+CREATE INDEX idx_artifacts_project_updated ON artifacts (project_id, updated_at DESC, id);
+CREATE INDEX idx_artifacts_owner_updated
+  ON artifacts (project_id, owner_principal_type, owner_principal_id, updated_at DESC, id);
+
+-- `refs`, not `references`: that word is reserved in SQL.
+CREATE TABLE artifact_versions (
+  project_id TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version > 0),
+  title TEXT NOT NULL CHECK (length(trim(title)) > 0),
+  entry TEXT NOT NULL CHECK (length(entry) > 0),
+  files TEXT NOT NULL CHECK (json_type(files) = 'array'),
+  outline TEXT NOT NULL CHECK (json_type(outline) = 'object'),
+  refs TEXT NOT NULL CHECK (json_type(refs) = 'array'),
+  author_principal_type TEXT NOT NULL
+    CHECK (author_principal_type IN ('user', 'serviceAccount', 'system')),
+  author_principal_id TEXT NOT NULL CHECK (length(author_principal_id) > 0),
+  origin_thread_id TEXT,
+  origin_run_id TEXT,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (project_id, artifact_id, version),
+  FOREIGN KEY (project_id, artifact_id) REFERENCES artifacts (project_id, id) ON DELETE CASCADE,
+  CHECK ((origin_thread_id IS NULL) = (origin_run_id IS NULL))
+);
+
+CREATE INDEX idx_artifact_versions_origin_run
+  ON artifact_versions (project_id, origin_run_id) WHERE origin_run_id IS NOT NULL;
+CREATE INDEX idx_artifact_versions_origin_thread
+  ON artifact_versions (project_id, origin_thread_id, artifact_id) WHERE origin_thread_id IS NOT NULL;
+
+-- Short-lived links that a sandboxed frame loads a deck's files through. Only the SHA-256 of each
+-- link's token is stored. `targets` is what the frame may show from other artifacts, decided for
+-- its reader when the link was issued: a JSON array of { address, artifactId, version }.
+CREATE TABLE artifact_frame_grants (
+  project_id TEXT NOT NULL,
+  token_hash TEXT NOT NULL CHECK (
+    length(token_hash) = 64
+    AND token_hash = lower(token_hash)
+    AND token_hash NOT GLOB '*[^0-9a-f]*'
+  ),
+  artifact_id TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version > 0),
+  targets TEXT NOT NULL CHECK (json_type(targets) = 'array'),
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  PRIMARY KEY (project_id, token_hash),
+  FOREIGN KEY (project_id, artifact_id) REFERENCES artifacts (project_id, id) ON DELETE CASCADE,
+  CHECK (expires_at > created_at)
+);
+
+CREATE INDEX idx_artifact_frame_grants_expiry ON artifact_frame_grants (project_id, expires_at);
+-- Deleting an artifact cascades here.
+CREATE INDEX idx_artifact_frame_grants_artifact ON artifact_frame_grants (project_id, artifact_id);