@sixb/pg 0.1.20 → 0.1.22

package/src/auth-storage/users.ts

@@ -4,11 +4,12 @@ import type {
   ListAuthUsersInput,
   ListAuthUsersResult,
   UpdateAuthUserProfileInput,
+  UpdateAuthUserResult,
   UpdateAuthUserStatusInput,
   UserRecord,
 } from "@sixb/core/storage"
 import { AuthStorageError } from "@sixb/core/storage"
-import type { PgStoreClient } from "../transactions"
+import { type PgStoreClient, runPgTransaction } from "../transactions"
 import type { PgAuthUserRow } from "./rows"
 import { rowToUserRecord } from "./rows"
 import {
@@ -90,6 +91,23 @@ export class PgAuthUserStore 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 = await this.sql<PgAuthUserRow[]>`
+      SELECT *
+      FROM auth_users
+      WHERE project_id = ${params.projectId}
+        AND id IN ${this.sql(ids)}
+    `
+
+    return rows.map(rowToUserRecord)
+  }
+
   async getByEmail(params: {
     readonly projectId: string
     readonly email: string
@@ -98,57 +116,83 @@ export class PgAuthUserStore implements AuthUserStore {
     return row ? rowToUserRecord(row) : null
   }
 
-  async updateProfile(input: UpdateAuthUserProfileInput): Promise<UserRecord> {
-    const existing = await getUserRowById(this.sql, {
-      projectId: input.projectId,
-      id: input.id,
-    })
-
-    if (!existing) {
-      throw new AuthStorageError(
-        "missing_user",
-        `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
+  async updateProfile(input: UpdateAuthUserProfileInput): Promise<UpdateAuthUserResult> {
+    // The row stays locked until the update, so the user it returns as previous is the one it
+    // changed, and an omitted field keeps whatever a concurrent update wrote to it.
+    return runPgTransaction(this.sql, async (tx) => {
+      const existing = await getUserRowById(
+        tx,
+        {
+          projectId: input.projectId,
+          id: input.id,
+        },
+        { forUpdate: true }
       )
-    }
 
-    const updatedAt = dateOrNow(input.updatedAt)
-    const [row] = await this.sql<PgAuthUserRow[]>`
-      UPDATE auth_users
-      SET display_name = ${input.displayName ?? null},
-          avatar_url = ${input.avatarUrl ?? null},
-          updated_at = ${updatedAt}
-      WHERE project_id = ${input.projectId}
-        AND id = ${input.id}
-      RETURNING *
-    `
+      if (!existing) {
+        throw new AuthStorageError(
+          "missing_user",
+          `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
+        )
+      }
 
-    return rowToUserRecord(row)
-  }
+      const previousUser = rowToUserRecord(existing)
+      if (!changesProfile(previousUser, input)) {
+        return { user: previousUser, previousUser }
+      }
+
+      const updatedAt = dateOrNow(input.updatedAt)
+      const [row] = await tx<PgAuthUserRow[]>`
+        UPDATE auth_users
+        SET display_name = CASE
+              WHEN ${input.displayName !== undefined}::boolean THEN ${input.displayName ?? null}::text
+              ELSE display_name
+            END,
+            avatar_url = CASE
+              WHEN ${input.avatarUrl !== undefined}::boolean THEN ${input.avatarUrl ?? null}::text
+              ELSE avatar_url
+            END,
+            updated_at = ${updatedAt}
+        WHERE project_id = ${input.projectId}
+          AND id = ${input.id}
+        RETURNING *
+      `
 
-  async updateStatus(input: UpdateAuthUserStatusInput): Promise<UserRecord> {
-    const existing = await getUserRowById(this.sql, {
-      projectId: input.projectId,
-      id: input.id,
+      return { user: rowToUserRecord(row), previousUser }
     })
+  }
 
-    if (!existing) {
-      throw new AuthStorageError(
-        "missing_user",
-        `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
+  async updateStatus(input: UpdateAuthUserStatusInput): Promise<UpdateAuthUserResult> {
+    // Locked like a profile update, so two status changes cannot both report the same previous one.
+    return runPgTransaction(this.sql, async (tx) => {
+      const existing = await getUserRowById(
+        tx,
+        {
+          projectId: input.projectId,
+          id: input.id,
+        },
+        { forUpdate: true }
       )
-    }
 
-    const updatedAt = dateOrNow(input.updatedAt)
-    const [row] = await this.sql<PgAuthUserRow[]>`
-      UPDATE auth_users
-      SET status = ${input.status},
-          updated_at = ${updatedAt}
-      WHERE project_id = ${input.projectId}
-        AND id = ${input.id}
-      RETURNING *
-    `
+      if (!existing) {
+        throw new AuthStorageError(
+          "missing_user",
+          `[Sixb] User '${input.id}' not found for project '${input.projectId}'.`
+        )
+      }
+
+      const updatedAt = dateOrNow(input.updatedAt)
+      const [row] = await tx<PgAuthUserRow[]>`
+        UPDATE auth_users
+        SET status = ${input.status},
+            updated_at = ${updatedAt}
+        WHERE project_id = ${input.projectId}
+          AND id = ${input.id}
+        RETURNING *
+      `
 
-    return rowToUserRecord(row)
+      return { user: rowToUserRecord(row), previousUser: rowToUserRecord(existing) }
+    })
   }
 
   async list(input: ListAuthUsersInput): Promise<ListAuthUsersResult> {
@@ -165,6 +209,15 @@ export class PgAuthUserStore implements AuthUserStore {
       params.push(...input.statuses)
     }
 
+    // `strpos` matches literally, so `%` and `_` need no escaping. Both sides fold through `lower()`.
+    if (input.search !== undefined) {
+      const index = nextIndex++
+      whereClauses.push(
+        `(strpos(lower(coalesce(display_name, '')), lower($${index})) > 0 OR strpos(lower(email), lower($${index})) > 0)`
+      )
+      params.push(input.search)
+    }
+
     const where = `WHERE ${whereClauses.join(" AND ")}`
     const order = input.order === "asc" ? "ASC" : "DESC"
     const [totalRow] = await this.sql.unsafe<{ readonly count: string | number }[]>(
@@ -194,3 +247,12 @@ export class PgAuthUserStore 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/index.ts

@@ -49,9 +49,11 @@ export type { PgObjectTextCountIndex } from "./objects/text-count-index"
 
 import { PgOntologyStorage, type PgOntologyTransactionContext } from "./ontology-storage"
 import { PgActionRunStorage } from "./pg-action-run-storage"
+import { PgActivityStorage } from "./pg-activity-storage"
 import { PgAiCostStorage } from "./pg-ai-cost-storage"
 import { PgAiLimitStorage } from "./pg-ai-limit-storage"
 import { PgAiUsageStorage } from "./pg-ai-usage-storage"
+import { PgArtifactStorage } from "./pg-artifact-storage"
 import { createPgClient, type SQL, type SQLClient } from "./pg-client"
 import { PgExecutionStorage } from "./pg-execution-storage"
 import { PgFileDownloadGrantStorage } from "./pg-file-download-grant-storage"
@@ -166,6 +168,7 @@ export class PostgresStorage implements MigrationCapableStorage, QueryPreparatio
   readonly auth: PgAuthStorage
   readonly executions: PgExecutionStorage
   readonly agents: PgAgentStorage
+  readonly artifacts: PgArtifactStorage
   readonly aiUsage: AiUsageStorage
   readonly aiCosts: AiCostStorage
   readonly aiLimits: AiLimitStorage
@@ -183,6 +186,7 @@ export class PostgresStorage implements MigrationCapableStorage, QueryPreparatio
   readonly shareSessions: PgShareSessionStorage
   readonly fileUploadSessions: PgFileUploadSessionStorage
   readonly fileDownloadGrants: PgFileDownloadGrantStorage
+  readonly activity: PgActivityStorage
   readonly migrators: readonly StorageMigrator[]
 
   private readonly sql: SQL
@@ -252,6 +256,7 @@ export class PostgresStorage implements MigrationCapableStorage, QueryPreparatio
     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)
@@ -269,6 +274,7 @@ export class PostgresStorage implements MigrationCapableStorage, QueryPreparatio
     this.shareSessions = createOperationScopedFacade(stores.shareSessions, scope)
     this.fileUploadSessions = createOperationScopedFacade(stores.fileUploadSessions, scope)
     this.fileDownloadGrants = createOperationScopedFacade(stores.fileDownloadGrants, scope)
+    this.activity = createOperationScopedFacade(stores.activity, scope)
     registerPostgresStorageTestingAdapter(this, (durationMs) =>
       stores.connectorConnections.advanceTimeForTesting(durationMs)
     )
@@ -414,6 +420,7 @@ function createPostgresStores(
     auth,
     executions,
     agents: new PgAgentStorage({ sql, executions }),
+    artifacts: new PgArtifactStorage(sql),
     aiUsage: new PgAiUsageStorage(sql),
     aiCosts: new PgAiCostStorage(sql),
     aiLimits: new PgAiLimitStorage(sql),
@@ -431,6 +438,7 @@ function createPostgresStores(
     shareSessions,
     fileUploadSessions: new PgFileUploadSessionStorage(sql),
     fileDownloadGrants: new PgFileDownloadGrantStorage(sql),
+    activity: new PgActivityStorage(sql),
   }
 }
 
@@ -440,6 +448,7 @@ interface PostgresStoreSet {
   readonly auth: PgAuthStorage
   readonly executions: PgExecutionStorage
   readonly agents: PgAgentStorage
+  readonly artifacts: PgArtifactStorage
   readonly aiUsage: PgAiUsageStorage
   readonly aiCosts: PgAiCostStorage
   readonly aiLimits: PgAiLimitStorage
@@ -457,6 +466,7 @@ interface PostgresStoreSet {
   readonly shareSessions: PgShareSessionStorage
   readonly fileUploadSessions: PgFileUploadSessionStorage
   readonly fileDownloadGrants: PgFileDownloadGrantStorage
+  readonly activity: PgActivityStorage
 }
 
 function resolveTimeoutMillis(value: number | undefined, label: string): number | undefined {

package/src/migrations/063-artifacts.sql

@@ -0,0 +1,67 @@
+-- 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.
+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 TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ 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 JSONB NOT NULL CHECK (jsonb_typeof(files) = 'array'),
+  outline JSONB NOT NULL CHECK (jsonb_typeof(outline) = 'object'),
+  refs JSONB NOT NULL CHECK (jsonb_typeof(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 TIMESTAMPTZ 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 (token_hash ~ '^[0-9a-f]{64}$'),
+  artifact_id TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK (version > 0),
+  targets JSONB NOT NULL CHECK (jsonb_typeof(targets) = 'array'),
+  created_at TIMESTAMPTZ NOT NULL,
+  expires_at TIMESTAMPTZ 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, and Postgres does not index a foreign key by itself.
+CREATE INDEX idx_artifact_frame_grants_artifact ON artifact_frame_grants (project_id, artifact_id);

package/src/migrations/064-drop-output-diagnostics.sql

@@ -0,0 +1,14 @@
+-- The Agent delivers files by publishing artifacts, so a run no longer collects an output
+-- directory or reports on it. Stored `output_*` diagnostics go; a run left with none stores none.
+UPDATE agent_runs
+SET diagnostics = (
+  SELECT jsonb_agg(item.value ORDER BY item.position)
+  FROM jsonb_array_elements(agent_runs.diagnostics) WITH ORDINALITY AS item(value, position)
+  WHERE item.value->>'code' NOT LIKE 'output\_%'
+)
+WHERE jsonb_typeof(diagnostics) = 'array'
+  AND EXISTS (
+    SELECT 1
+    FROM jsonb_array_elements(agent_runs.diagnostics) AS item(value)
+    WHERE item.value->>'code' LIKE 'output\_%'
+  );

package/src/migrations/065-plan-work-payload-statistics.sql

@@ -0,0 +1,5 @@
+-- A plan's work is analyzed whenever a stream has staged enough of it, and most of that ANALYZE
+-- went into the statistics of `payload`, which no query reads: the plan queries filter on the
+-- typed columns and only extract values from `payload`, and an extracted value has no statistics.
+-- A query that filters `payload` itself (`@>`, `?`) would need them back.
+ALTER TABLE ontology_replacement_plan_work ALTER COLUMN payload SET STATISTICS 0;

package/src/migrations/066-activity.sql

@@ -0,0 +1,61 @@
+-- App activity: one source per verified session, the visits it opened, and their page views.
+-- Foreground activity moves a visit's `last_seen_at` and stores no row, unless it opens a visit.
+-- A session id names an `auth_sessions` row for a user and a `share_sessions` row for a share; it
+-- is not a secret, and no foreign key holds it, so history outlives its sessions. Ids compare
+-- byte by byte, as the other providers sort them.
+CREATE TABLE activity_sources (
+  project_id TEXT NOT NULL,
+  actor_type TEXT NOT NULL CHECK (actor_type IN ('user', 'share')),
+  session_id TEXT NOT NULL CHECK (length(session_id) > 0),
+  visit_id TEXT NOT NULL,
+  last_seen_at TIMESTAMPTZ NOT NULL,
+  sequence INTEGER NOT NULL CHECK (sequence >= 0),
+  window_start TIMESTAMPTZ NOT NULL,
+  window_count INTEGER NOT NULL CHECK (window_count >= 0),
+  PRIMARY KEY (project_id, actor_type, session_id)
+);
+
+CREATE TABLE activity_visits (
+  project_id TEXT NOT NULL,
+  id TEXT COLLATE "C" NOT NULL,
+  actor_type TEXT NOT NULL CHECK (actor_type IN ('user', 'share')),
+  user_id TEXT COLLATE "C",
+  grant_id TEXT,
+  session_id TEXT NOT NULL CHECK (length(session_id) > 0),
+  started_at TIMESTAMPTZ NOT NULL,
+  last_seen_at TIMESTAMPTZ NOT NULL CHECK (last_seen_at >= started_at),
+  page_views INTEGER NOT NULL CHECK (page_views >= 0),
+  attribution JSONB CHECK (attribution IS NULL OR jsonb_typeof(attribution) = 'object'),
+  PRIMARY KEY (project_id, id),
+  CHECK (
+    (actor_type = 'user' AND user_id IS NOT NULL AND grant_id IS NULL)
+    OR (actor_type = 'share' AND user_id IS NULL AND grant_id IS NOT NULL)
+  )
+);
+
+-- A period reads the visits it overlaps. A visit lasts less than a day, so they started in
+-- `[from - 1 day, to)`: both period indexes bound `started_at` on both sides. `last_seen_at` is
+-- left out of every index, so the update each batch makes touches none of them. The user index
+-- also serves deleting one user's history.
+CREATE INDEX idx_activity_visits_started
+  ON activity_visits (project_id, started_at, id);
+CREATE INDEX idx_activity_visits_user
+  ON activity_visits (project_id, user_id, started_at, id);
+-- A session's visits, to join them with the session and the executions it authorized.
+CREATE INDEX idx_activity_visits_session
+  ON activity_visits (project_id, actor_type, session_id);
+
+CREATE TABLE activity_page_views (
+  project_id TEXT NOT NULL,
+  visit_id TEXT COLLATE "C" NOT NULL,
+  sequence INTEGER NOT NULL CHECK (sequence > 0),
+  id TEXT NOT NULL,
+  route TEXT NOT NULL,
+  received_at TIMESTAMPTZ NOT NULL,
+  attribution JSONB CHECK (attribution IS NULL OR jsonb_typeof(attribution) = 'object'),
+  PRIMARY KEY (project_id, visit_id, sequence),
+  FOREIGN KEY (project_id, visit_id) REFERENCES activity_visits (project_id, id) ON DELETE CASCADE
+);
+
+-- Finds a retried page view by the id its browser chose.
+CREATE INDEX idx_activity_page_views_id ON activity_page_views (project_id, id);

package/src/migrations/067-activity-timeline.sql

@@ -0,0 +1,15 @@
+-- A visit's timeline reads what its session started: the roots it authorized in a window, then
+-- everything they caused. A signed-in session is the credential of its roots, a shared link's
+-- session their delegation; a child names its parent. Agent executions copy their parent's
+-- session: the root indexes hold only executions without a parent, so they never see those, and
+-- end with `id` so the root read's order needs no sort. A user's connection history reads
+-- `idx_auth_sessions_user_created`, which already exists.
+CREATE INDEX idx_executions_session_roots
+  ON executions (project_id, authority_session_id, created_at, id)
+  WHERE authority_session_id IS NOT NULL AND parent_execution_id IS NULL;
+CREATE INDEX idx_executions_delegation_roots
+  ON executions (project_id, authority_delegation_session_id, created_at, id)
+  WHERE authority_delegation_session_id IS NOT NULL AND parent_execution_id IS NULL;
+CREATE INDEX idx_executions_parent
+  ON executions (project_id, parent_execution_id)
+  WHERE parent_execution_id IS NOT NULL;

package/src/migrations/068-activity-interactions.sql

@@ -0,0 +1,20 @@
+-- Interactions an app marks, such as a button: their name and route, never a value. They share
+-- the visit's sequence with its page views, so a visit reads both in the order they happened, and
+-- cascade with the visit, which counts them as it counts its page views.
+ALTER TABLE activity_visits
+  ADD COLUMN interactions INTEGER NOT NULL DEFAULT 0 CHECK (interactions >= 0);
+
+CREATE TABLE activity_interactions (
+  project_id TEXT NOT NULL,
+  visit_id TEXT COLLATE "C" NOT NULL,
+  sequence INTEGER NOT NULL CHECK (sequence > 0),
+  id TEXT NOT NULL,
+  name TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 100),
+  route TEXT NOT NULL,
+  received_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, visit_id, sequence),
+  FOREIGN KEY (project_id, visit_id) REFERENCES activity_visits (project_id, id) ON DELETE CASCADE
+);
+
+-- Finds a retried interaction by the id its browser chose.
+CREATE INDEX idx_activity_interactions_id ON activity_interactions (project_id, id);

package/src/migrations/069-artifact-kinds.sql

@@ -0,0 +1,4 @@
+-- Artifacts take two more kinds: pages, and the canvases that lay pages out.
+ALTER TABLE artifacts DROP CONSTRAINT artifacts_kind_check;
+ALTER TABLE artifacts ADD CONSTRAINT artifacts_kind_check
+  CHECK (kind IN ('document', 'sheet', 'slides', 'page', 'canvas', 'file'));

package/src/migrations/070-artifact-state.sql

@@ -0,0 +1,16 @@
+-- What a page keeps for each of its readers with `sixb.state`: JSON text by key, for one artifact
+-- and one principal, across the artifact's versions. The value stays text, as written, so its
+-- size is the one the reader's limits count; `size_bytes` is its UTF-8 length. Deleting the
+-- artifact cascades here.
+CREATE TABLE artifact_state (
+  project_id TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  principal_type TEXT NOT NULL CHECK (principal_type IN ('user', 'serviceAccount', 'system')),
+  principal_id TEXT NOT NULL CHECK (length(principal_id) > 0),
+  key TEXT NOT NULL CHECK (length(key) > 0),
+  value TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL CHECK (size_bytes >= 0),
+  updated_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, artifact_id, principal_type, principal_id, key),
+  FOREIGN KEY (project_id, artifact_id) REFERENCES artifacts (project_id, id) ON DELETE CASCADE
+);

package/src/migrations/071-agent-thread-participants.sql

@@ -0,0 +1,16 @@
+-- The users a thread's owner added to the conversation. Only users take part: only a signed-in
+-- user talks to the Agent. Listing the threads shared with someone reads the principal index.
+CREATE TABLE agent_thread_participants (
+  project_id TEXT NOT NULL,
+  thread_id TEXT NOT NULL,
+  principal_type TEXT NOT NULL CHECK (principal_type = 'user'),
+  principal_id TEXT NOT NULL CHECK (length(principal_id) > 0),
+  added_at TIMESTAMPTZ NOT NULL,
+  added_by_type TEXT NOT NULL CHECK (added_by_type IN ('user', 'serviceAccount', 'system')),
+  added_by_id TEXT NOT NULL CHECK (length(added_by_id) > 0),
+  PRIMARY KEY (project_id, thread_id, principal_type, principal_id),
+  FOREIGN KEY (project_id, thread_id) REFERENCES agent_threads (project_id, id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_agent_thread_participants_principal
+  ON agent_thread_participants (project_id, principal_type, principal_id, thread_id);

package/src/migrations/072-forked-context-checkpoints.sql

@@ -0,0 +1,23 @@
+-- A forked thread copies the checkpoint its history needs, and the copy keeps the run that wrote
+-- the summary. A run's checkpoint is therefore unique within a thread, not within the project.
+-- The project-wide constraint was unnamed: drop the one unique on exactly those two columns, and
+-- stop if it is not there rather than leave the old rule in place.
+DO $$
+DECLARE run_constraint TEXT;
+BEGIN
+  SELECT conname INTO run_constraint
+  FROM pg_constraint
+  WHERE conrelid = 'agent_context_checkpoints'::regclass
+    AND contype = 'u'
+    AND pg_get_constraintdef(oid) = 'UNIQUE (project_id, created_by_run_id)';
+
+  IF run_constraint IS NULL THEN
+    RAISE EXCEPTION 'agent_context_checkpoints has no UNIQUE (project_id, created_by_run_id) to drop';
+  END IF;
+
+  EXECUTE format('ALTER TABLE agent_context_checkpoints DROP CONSTRAINT %I', run_constraint);
+END $$;
+
+ALTER TABLE agent_context_checkpoints
+  ADD CONSTRAINT uq_agent_context_checkpoints_thread_run
+  UNIQUE (project_id, thread_id, created_by_run_id);

package/src/migrations/073-unique-values.sql

@@ -0,0 +1,25 @@
+-- The values of unique properties, one row per value an object holds. Every object write keeps
+-- them current, so a write that would give a value to a second object of the type is refused.
+-- Values are keyed by their SHA-256: a long string stays under the btree key limit, and a lookup
+-- still compares `value_key` itself.
+CREATE TABLE object_unique_values (
+  project_id TEXT NOT NULL,
+  object_type_id TEXT NOT NULL,
+  property_id TEXT NOT NULL,
+  value_hash BYTEA NOT NULL,
+  value_key TEXT NOT NULL,
+  primary_id TEXT NOT NULL,
+  PRIMARY KEY (project_id, object_type_id, property_id, value_hash)
+);
+
+-- The unique properties whose values were built from the objects already stored, and how their
+-- keys were computed. A claim made with other keys is refused until they are built again.
+CREATE TABLE object_unique_properties (
+  project_id TEXT NOT NULL,
+  object_type_id TEXT NOT NULL,
+  property_id TEXT NOT NULL,
+  key_kind TEXT NOT NULL,
+  key_version INTEGER NOT NULL,
+  prepared_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, object_type_id, property_id)
+);

package/src/migrations/074-generated-media-usage.sql

@@ -0,0 +1,21 @@
+ALTER TABLE ai_model_call_usage
+  ADD COLUMN image_output_tokens BIGINT
+  CHECK (image_output_tokens IS NULL OR image_output_tokens >= 0),
+  ADD COLUMN audio_output_tokens BIGINT
+  CHECK (audio_output_tokens IS NULL OR audio_output_tokens >= 0),
+  ADD COLUMN output_images BIGINT
+  CHECK (output_images IS NULL OR output_images >= 0),
+  ADD COLUMN input_characters BIGINT
+  CHECK (input_characters IS NULL OR input_characters >= 0);
+
+ALTER TABLE ai_model_call_usage
+  DROP CONSTRAINT ai_model_call_usage_model_kind_check;
+
+ALTER TABLE ai_model_call_usage
+  ADD CONSTRAINT ai_model_call_usage_model_kind_check
+  CHECK (
+    model_kind IS NULL
+    OR model_kind IN (
+      'language', 'image', 'video', 'embedding', 'decision', 'transcription', 'speech', 'reranking'
+    )
+  );

package/src/migrations/075-model-call-files.sql

@@ -0,0 +1,11 @@
+-- The files a model call produced. The execution that made the call decides who may read them.
+CREATE TABLE ai_model_call_files (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  call_id TEXT NOT NULL CHECK (length(trim(call_id)) > 0),
+  execution_id TEXT NOT NULL CHECK (length(trim(execution_id)) > 0),
+  files JSONB NOT NULL CHECK (jsonb_typeof(files) = 'array' AND jsonb_array_length(files) > 0),
+  recorded_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, call_id),
+  FOREIGN KEY (project_id, execution_id)
+    REFERENCES executions(project_id, id)
+);

package/src/migrations/076-agent-memory.sql

@@ -0,0 +1,33 @@
+-- Agent memory: each repo, 'user:<userId>' or 'project', is a log of revisions. A save inserts one
+-- revision and the file versions it wrote, and never updates a row. A file's current contents are
+-- its highest-revision version; NULL contents mean that revision deleted it.
+CREATE TABLE agent_memory_revisions (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  repo_id TEXT NOT NULL CHECK (length(trim(repo_id)) > 0),
+  revision INTEGER NOT NULL CHECK (revision > 0),
+  message TEXT NOT NULL CHECK (length(trim(message)) > 0),
+  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),
+  source TEXT,
+  created_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, repo_id, revision)
+);
+
+-- A save also removes versions older than 90 days that are not their path's latest, so a
+-- revision's rows here can be fewer than the files it wrote. Paths compare by code unit, as they
+-- do in SQLite.
+CREATE TABLE agent_memory_files (
+  project_id TEXT NOT NULL,
+  repo_id TEXT NOT NULL,
+  path TEXT COLLATE "C" NOT NULL CHECK (length(path) > 0),
+  revision INTEGER NOT NULL,
+  contents TEXT,
+  PRIMARY KEY (project_id, repo_id, path, revision),
+  FOREIGN KEY (project_id, repo_id, revision)
+    REFERENCES agent_memory_revisions (project_id, repo_id, revision) ON DELETE CASCADE
+);
+
+-- Deleting a repo cascades here, and Postgres does not index a foreign key by itself.
+CREATE INDEX idx_agent_memory_files_revision
+  ON agent_memory_files (project_id, repo_id, revision);

package/src/migrations/077-artifact-threads.sql

@@ -0,0 +1,21 @@
+-- The threads an artifact is shared in: everyone who reads one of them reads the artifact. An
+-- Agent turn publishing a version links its thread, for as long as a version from it remains; a
+-- forked thread links its copies, `copied`, for as long as they last. Existing versions published
+-- from a thread link it here.
+CREATE TABLE artifact_threads (
+  project_id TEXT NOT NULL,
+  artifact_id TEXT NOT NULL,
+  thread_id TEXT NOT NULL CHECK (length(thread_id) > 0),
+  shared_at TIMESTAMPTZ NOT NULL,
+  copied BOOLEAN NOT NULL DEFAULT FALSE,
+  PRIMARY KEY (project_id, artifact_id, thread_id),
+  FOREIGN KEY (project_id, artifact_id) REFERENCES artifacts (project_id, id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_artifact_threads_thread ON artifact_threads (project_id, thread_id, artifact_id);
+
+INSERT INTO artifact_threads (project_id, artifact_id, thread_id, shared_at)
+SELECT project_id, artifact_id, origin_thread_id, MIN(created_at)
+FROM artifact_versions
+WHERE origin_thread_id IS NOT NULL
+GROUP BY project_id, artifact_id, origin_thread_id;