merge: wave 2 executor (01-02) into main

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

paperclip-reference/packages/db/src/backup-lib.ts

@@ -0,0 +1,558 @@
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import postgres from "postgres";
+
+export type RunDatabaseBackupOptions = {
+  connectionString: string;
+  backupDir: string;
+  retentionDays: number;
+  filenamePrefix?: string;
+  connectTimeoutSeconds?: number;
+  includeMigrationJournal?: boolean;
+  excludeTables?: string[];
+  nullifyColumns?: Record<string, string[]>;
+};
+
+export type RunDatabaseBackupResult = {
+  backupFile: string;
+  sizeBytes: number;
+  prunedCount: number;
+};
+
+export type RunDatabaseRestoreOptions = {
+  connectionString: string;
+  backupFile: string;
+  connectTimeoutSeconds?: number;
+};
+
+type SequenceDefinition = {
+  sequence_schema: string;
+  sequence_name: string;
+  data_type: string;
+  start_value: string;
+  minimum_value: string;
+  maximum_value: string;
+  increment: string;
+  cycle_option: "YES" | "NO";
+  owner_schema: string | null;
+  owner_table: string | null;
+  owner_column: string | null;
+};
+
+type TableDefinition = {
+  schema_name: string;
+  tablename: string;
+};
+
+const DRIZZLE_SCHEMA = "drizzle";
+const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
+
+const STATEMENT_BREAKPOINT = "-- paperclip statement breakpoint 69f6f3f1-42fd-46a6-bf17-d1d85f8f3900";
+
+function sanitizeRestoreErrorMessage(error: unknown): string {
+  if (error && typeof error === "object") {
+    const record = error as Record<string, unknown>;
+    const firstLine = typeof record.message === "string"
+      ? record.message.split(/\r?\n/, 1)[0]?.trim()
+      : "";
+    const detail = typeof record.detail === "string" ? record.detail.trim() : "";
+    const severity = typeof record.severity === "string" ? record.severity.trim() : "";
+    const message = firstLine || detail || (error instanceof Error ? error.message : String(error));
+    return severity ? `${severity}: ${message}` : message;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function timestamp(date: Date = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function pruneOldBackups(backupDir: string, retentionDays: number, filenamePrefix: string): number {
+  if (!existsSync(backupDir)) return 0;
+  const safeRetention = Math.max(1, Math.trunc(retentionDays));
+  const cutoff = Date.now() - safeRetention * 24 * 60 * 60 * 1000;
+  let pruned = 0;
+
+  for (const name of readdirSync(backupDir)) {
+    if (!name.startsWith(`${filenamePrefix}-`) || !name.endsWith(".sql")) continue;
+    const fullPath = resolve(backupDir, name);
+    const stat = statSync(fullPath);
+    if (stat.mtimeMs < cutoff) {
+      unlinkSync(fullPath);
+      pruned++;
+    }
+  }
+
+  return pruned;
+}
+
+function formatBackupSize(sizeBytes: number): string {
+  if (sizeBytes < 1024) return `${sizeBytes}B`;
+  if (sizeBytes < 1024 * 1024) return `${(sizeBytes / 1024).toFixed(1)}K`;
+  return `${(sizeBytes / (1024 * 1024)).toFixed(1)}M`;
+}
+
+function formatSqlLiteral(value: string): string {
+  const sanitized = value.replace(/\u0000/g, "");
+  let tag = "$paperclip$";
+  while (sanitized.includes(tag)) {
+    tag = `$paperclip_${Math.random().toString(36).slice(2, 8)}$`;
+  }
+  return `${tag}${sanitized}${tag}`;
+}
+
+function normalizeTableNameSet(values: string[] | undefined): Set<string> {
+  return new Set(
+    (values ?? [])
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0),
+  );
+}
+
+function normalizeNullifyColumnMap(values: Record<string, string[]> | undefined): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  if (!values) return out;
+  for (const [tableName, columns] of Object.entries(values)) {
+    const normalizedTable = tableName.trim();
+    if (normalizedTable.length === 0) continue;
+    const normalizedColumns = new Set(
+      columns
+        .map((column) => column.trim())
+        .filter((column) => column.length > 0),
+    );
+    if (normalizedColumns.size > 0) {
+      out.set(normalizedTable, normalizedColumns);
+    }
+  }
+  return out;
+}
+
+function quoteIdentifier(value: string): string {
+  return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+
+function quoteQualifiedName(schemaName: string, objectName: string): string {
+  return `${quoteIdentifier(schemaName)}.${quoteIdentifier(objectName)}`;
+}
+
+function tableKey(schemaName: string, tableName: string): string {
+  return `${schemaName}.${tableName}`;
+}
+
+export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise<RunDatabaseBackupResult> {
+  const filenamePrefix = opts.filenamePrefix ?? "paperclip";
+  const retentionDays = Math.max(1, Math.trunc(opts.retentionDays));
+  const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
+  const includeMigrationJournal = opts.includeMigrationJournal === true;
+  const excludedTableNames = normalizeTableNameSet(opts.excludeTables);
+  const nullifiedColumnsByTable = normalizeNullifyColumnMap(opts.nullifyColumns);
+  const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
+
+  try {
+    await sql`SELECT 1`;
+
+    const lines: string[] = [];
+    const emit = (line: string) => lines.push(line);
+    const emitStatement = (statement: string) => {
+      emit(statement);
+      emit(STATEMENT_BREAKPOINT);
+    };
+    const emitStatementBoundary = () => {
+      emit(STATEMENT_BREAKPOINT);
+    };
+
+    emit("-- Paperclip database backup");
+    emit(`-- Created: ${new Date().toISOString()}`);
+    emit("");
+    emitStatement("BEGIN;");
+    emitStatement("SET LOCAL session_replication_role = replica;");
+    emitStatement("SET LOCAL client_min_messages = warning;");
+    emit("");
+
+    const allTables = await sql<TableDefinition[]>`
+      SELECT table_schema AS schema_name, table_name AS tablename
+      FROM information_schema.tables
+      WHERE table_type = 'BASE TABLE'
+        AND (
+          table_schema = 'public'
+          OR (${includeMigrationJournal}::boolean AND table_schema = ${DRIZZLE_SCHEMA} AND table_name = ${DRIZZLE_MIGRATIONS_TABLE})
+        )
+      ORDER BY table_schema, table_name
+    `;
+    const tables = allTables;
+    const includedTableNames = new Set(tables.map(({ schema_name, tablename }) => tableKey(schema_name, tablename)));
+
+    // Get all enums
+    const enums = await sql<{ typname: string; labels: string[] }[]>`
+      SELECT t.typname, array_agg(e.enumlabel ORDER BY e.enumsortorder) AS labels
+      FROM pg_type t
+      JOIN pg_enum e ON t.oid = e.enumtypid
+      JOIN pg_namespace n ON t.typnamespace = n.oid
+      WHERE n.nspname = 'public'
+      GROUP BY t.typname
+      ORDER BY t.typname
+    `;
+
+    for (const e of enums) {
+      const labels = e.labels.map((l) => `'${l.replace(/'/g, "''")}'`).join(", ");
+      emitStatement(`CREATE TYPE "public"."${e.typname}" AS ENUM (${labels});`);
+    }
+    if (enums.length > 0) emit("");
+
+    const allSequences = await sql<SequenceDefinition[]>`
+      SELECT
+        s.sequence_schema,
+        s.sequence_name,
+        s.data_type,
+        s.start_value,
+        s.minimum_value,
+        s.maximum_value,
+        s.increment,
+        s.cycle_option,
+        tblns.nspname AS owner_schema,
+        tbl.relname AS owner_table,
+        attr.attname AS owner_column
+      FROM information_schema.sequences s
+      JOIN pg_class seq ON seq.relname = s.sequence_name
+      JOIN pg_namespace n ON n.oid = seq.relnamespace AND n.nspname = s.sequence_schema
+      LEFT JOIN pg_depend dep ON dep.objid = seq.oid AND dep.deptype = 'a'
+      LEFT JOIN pg_class tbl ON tbl.oid = dep.refobjid
+      LEFT JOIN pg_namespace tblns ON tblns.oid = tbl.relnamespace
+      LEFT JOIN pg_attribute attr ON attr.attrelid = tbl.oid AND attr.attnum = dep.refobjsubid
+      WHERE s.sequence_schema = 'public'
+         OR (${includeMigrationJournal}::boolean AND s.sequence_schema = ${DRIZZLE_SCHEMA})
+      ORDER BY s.sequence_schema, s.sequence_name
+    `;
+    const sequences = allSequences.filter(
+      (seq) => !seq.owner_table || includedTableNames.has(tableKey(seq.owner_schema ?? "public", seq.owner_table)),
+    );
+
+    const schemas = new Set<string>();
+    for (const table of tables) schemas.add(table.schema_name);
+    for (const seq of sequences) schemas.add(seq.sequence_schema);
+    const extraSchemas = [...schemas].filter((schemaName) => schemaName !== "public");
+    if (extraSchemas.length > 0) {
+      emit("-- Schemas");
+      for (const schemaName of extraSchemas) {
+        emitStatement(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schemaName)};`);
+      }
+      emit("");
+    }
+
+    if (sequences.length > 0) {
+      emit("-- Sequences");
+      for (const seq of sequences) {
+        const qualifiedSequenceName = quoteQualifiedName(seq.sequence_schema, seq.sequence_name);
+        emitStatement(`DROP SEQUENCE IF EXISTS ${qualifiedSequenceName} CASCADE;`);
+        emitStatement(
+          `CREATE SEQUENCE ${qualifiedSequenceName} AS ${seq.data_type} INCREMENT BY ${seq.increment} MINVALUE ${seq.minimum_value} MAXVALUE ${seq.maximum_value} START WITH ${seq.start_value}${seq.cycle_option === "YES" ? " CYCLE" : " NO CYCLE"};`,
+        );
+      }
+      emit("");
+    }
+
+    // Get full CREATE TABLE DDL via column info
+    for (const { schema_name, tablename } of tables) {
+      const qualifiedTableName = quoteQualifiedName(schema_name, tablename);
+      const columns = await sql<{
+        column_name: string;
+        data_type: string;
+        udt_name: string;
+        is_nullable: string;
+        column_default: string | null;
+        character_maximum_length: number | null;
+        numeric_precision: number | null;
+        numeric_scale: number | null;
+      }[]>`
+        SELECT column_name, data_type, udt_name, is_nullable, column_default,
+               character_maximum_length, numeric_precision, numeric_scale
+        FROM information_schema.columns
+        WHERE table_schema = ${schema_name} AND table_name = ${tablename}
+        ORDER BY ordinal_position
+      `;
+
+      emit(`-- Table: ${schema_name}.${tablename}`);
+      emitStatement(`DROP TABLE IF EXISTS ${qualifiedTableName} CASCADE;`);
+
+      const colDefs: string[] = [];
+      for (const col of columns) {
+        let typeStr: string;
+        if (col.data_type === "USER-DEFINED") {
+          typeStr = `"${col.udt_name}"`;
+        } else if (col.data_type === "ARRAY") {
+          typeStr = `${col.udt_name.replace(/^_/, "")}[]`;
+        } else if (col.data_type === "character varying") {
+          typeStr = col.character_maximum_length
+            ? `varchar(${col.character_maximum_length})`
+            : "varchar";
+        } else if (col.data_type === "numeric" && col.numeric_precision != null) {
+          typeStr =
+            col.numeric_scale != null
+              ? `numeric(${col.numeric_precision}, ${col.numeric_scale})`
+              : `numeric(${col.numeric_precision})`;
+        } else {
+          typeStr = col.data_type;
+        }
+
+        let def = `  "${col.column_name}" ${typeStr}`;
+        if (col.column_default != null) def += ` DEFAULT ${col.column_default}`;
+        if (col.is_nullable === "NO") def += " NOT NULL";
+        colDefs.push(def);
+      }
+
+      // Primary key
+      const pk = await sql<{ constraint_name: string; column_names: string[] }[]>`
+        SELECT c.conname AS constraint_name,
+               array_agg(a.attname ORDER BY array_position(c.conkey, a.attnum)) AS column_names
+        FROM pg_constraint c
+        JOIN pg_class t ON t.oid = c.conrelid
+        JOIN pg_namespace n ON n.oid = t.relnamespace
+        JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(c.conkey)
+        WHERE n.nspname = ${schema_name} AND t.relname = ${tablename} AND c.contype = 'p'
+        GROUP BY c.conname
+      `;
+      for (const p of pk) {
+        const cols = p.column_names.map((c) => `"${c}"`).join(", ");
+        colDefs.push(`  CONSTRAINT "${p.constraint_name}" PRIMARY KEY (${cols})`);
+      }
+
+      emit(`CREATE TABLE ${qualifiedTableName} (`);
+      emit(colDefs.join(",\n"));
+      emit(");");
+      emitStatementBoundary();
+      emit("");
+    }
+
+    const ownedSequences = sequences.filter((seq) => seq.owner_table && seq.owner_column);
+    if (ownedSequences.length > 0) {
+      emit("-- Sequence ownership");
+      for (const seq of ownedSequences) {
+        emitStatement(
+          `ALTER SEQUENCE ${quoteQualifiedName(seq.sequence_schema, seq.sequence_name)} OWNED BY ${quoteQualifiedName(seq.owner_schema ?? "public", seq.owner_table!)}.${quoteIdentifier(seq.owner_column!)};`,
+        );
+      }
+      emit("");
+    }
+
+    // Foreign keys (after all tables created)
+    const allForeignKeys = await sql<{
+      constraint_name: string;
+      source_schema: string;
+      source_table: string;
+      source_columns: string[];
+      target_schema: string;
+      target_table: string;
+      target_columns: string[];
+      update_rule: string;
+      delete_rule: string;
+    }[]>`
+      SELECT
+        c.conname AS constraint_name,
+        srcn.nspname AS source_schema,
+        src.relname AS source_table,
+        array_agg(sa.attname ORDER BY array_position(c.conkey, sa.attnum)) AS source_columns,
+        tgtn.nspname AS target_schema,
+        tgt.relname AS target_table,
+        array_agg(ta.attname ORDER BY array_position(c.confkey, ta.attnum)) AS target_columns,
+        CASE c.confupdtype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS update_rule,
+        CASE c.confdeltype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS delete_rule
+      FROM pg_constraint c
+      JOIN pg_class src ON src.oid = c.conrelid
+      JOIN pg_namespace srcn ON srcn.oid = src.relnamespace
+      JOIN pg_class tgt ON tgt.oid = c.confrelid
+      JOIN pg_namespace tgtn ON tgtn.oid = tgt.relnamespace
+      JOIN pg_attribute sa ON sa.attrelid = src.oid AND sa.attnum = ANY(c.conkey)
+      JOIN pg_attribute ta ON ta.attrelid = tgt.oid AND ta.attnum = ANY(c.confkey)
+      WHERE c.contype = 'f' AND (
+        srcn.nspname = 'public'
+        OR (${includeMigrationJournal}::boolean AND srcn.nspname = ${DRIZZLE_SCHEMA})
+      )
+      GROUP BY c.conname, srcn.nspname, src.relname, tgtn.nspname, tgt.relname, c.confupdtype, c.confdeltype
+      ORDER BY srcn.nspname, src.relname, c.conname
+    `;
+    const fks = allForeignKeys.filter(
+      (fk) => includedTableNames.has(tableKey(fk.source_schema, fk.source_table))
+        && includedTableNames.has(tableKey(fk.target_schema, fk.target_table)),
+    );
+
+    if (fks.length > 0) {
+      emit("-- Foreign keys");
+      for (const fk of fks) {
+        const srcCols = fk.source_columns.map((c) => `"${c}"`).join(", ");
+        const tgtCols = fk.target_columns.map((c) => `"${c}"`).join(", ");
+        emitStatement(
+          `ALTER TABLE ${quoteQualifiedName(fk.source_schema, fk.source_table)} ADD CONSTRAINT "${fk.constraint_name}" FOREIGN KEY (${srcCols}) REFERENCES ${quoteQualifiedName(fk.target_schema, fk.target_table)} (${tgtCols}) ON UPDATE ${fk.update_rule} ON DELETE ${fk.delete_rule};`,
+        );
+      }
+      emit("");
+    }
+
+    // Unique constraints
+    const allUniqueConstraints = await sql<{
+      constraint_name: string;
+      schema_name: string;
+      tablename: string;
+      column_names: string[];
+    }[]>`
+      SELECT c.conname AS constraint_name,
+             n.nspname AS schema_name,
+             t.relname AS tablename,
+             array_agg(a.attname ORDER BY array_position(c.conkey, a.attnum)) AS column_names
+      FROM pg_constraint c
+      JOIN pg_class t ON t.oid = c.conrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(c.conkey)
+      WHERE c.contype = 'u' AND (
+        n.nspname = 'public'
+        OR (${includeMigrationJournal}::boolean AND n.nspname = ${DRIZZLE_SCHEMA})
+      )
+      GROUP BY c.conname, n.nspname, t.relname
+      ORDER BY n.nspname, t.relname, c.conname
+    `;
+    const uniques = allUniqueConstraints.filter((entry) => includedTableNames.has(tableKey(entry.schema_name, entry.tablename)));
+
+    if (uniques.length > 0) {
+      emit("-- Unique constraints");
+      for (const u of uniques) {
+        const cols = u.column_names.map((c) => `"${c}"`).join(", ");
+        emitStatement(`ALTER TABLE ${quoteQualifiedName(u.schema_name, u.tablename)} ADD CONSTRAINT "${u.constraint_name}" UNIQUE (${cols});`);
+      }
+      emit("");
+    }
+
+    // Indexes (non-primary, non-unique-constraint)
+    const allIndexes = await sql<{ schema_name: string; tablename: string; indexdef: string }[]>`
+      SELECT schemaname AS schema_name, tablename, indexdef
+      FROM pg_indexes
+      WHERE (
+          schemaname = 'public'
+          OR (${includeMigrationJournal}::boolean AND schemaname = ${DRIZZLE_SCHEMA})
+        )
+        AND indexname NOT IN (
+          SELECT conname FROM pg_constraint c
+          JOIN pg_namespace n ON n.oid = c.connamespace
+          WHERE n.nspname = pg_indexes.schemaname
+        )
+      ORDER BY schemaname, tablename, indexname
+    `;
+    const indexes = allIndexes.filter((entry) => includedTableNames.has(tableKey(entry.schema_name, entry.tablename)));
+
+    if (indexes.length > 0) {
+      emit("-- Indexes");
+      for (const idx of indexes) {
+        emitStatement(`${idx.indexdef};`);
+      }
+      emit("");
+    }
+
+    // Dump data for each table
+    for (const { schema_name, tablename } of tables) {
+      const qualifiedTableName = quoteQualifiedName(schema_name, tablename);
+      const count = await sql.unsafe<{ n: number }[]>(`SELECT count(*)::int AS n FROM ${qualifiedTableName}`);
+      if (excludedTableNames.has(tablename) || (count[0]?.n ?? 0) === 0) continue;
+
+      // Get column info for this table
+      const cols = await sql<{ column_name: string; data_type: string }[]>`
+        SELECT column_name, data_type
+        FROM information_schema.columns
+        WHERE table_schema = ${schema_name} AND table_name = ${tablename}
+        ORDER BY ordinal_position
+      `;
+      const colNames = cols.map((c) => `"${c.column_name}"`).join(", ");
+
+      emit(`-- Data for: ${schema_name}.${tablename} (${count[0]!.n} rows)`);
+
+      const rows = await sql.unsafe(`SELECT * FROM ${qualifiedTableName}`).values();
+      const nullifiedColumns = nullifiedColumnsByTable.get(tablename) ?? new Set<string>();
+      for (const row of rows) {
+        const values = row.map((rawValue: unknown, index) => {
+          const columnName = cols[index]?.column_name;
+          const val = columnName && nullifiedColumns.has(columnName) ? null : rawValue;
+          if (val === null || val === undefined) return "NULL";
+          if (typeof val === "boolean") return val ? "true" : "false";
+          if (typeof val === "number") return String(val);
+          if (val instanceof Date) return formatSqlLiteral(val.toISOString());
+          if (typeof val === "object") return formatSqlLiteral(JSON.stringify(val));
+          return formatSqlLiteral(String(val));
+        });
+        emitStatement(`INSERT INTO ${qualifiedTableName} (${colNames}) VALUES (${values.join(", ")});`);
+      }
+      emit("");
+    }
+
+    // Sequence values
+    if (sequences.length > 0) {
+      emit("-- Sequence values");
+      for (const seq of sequences) {
+        const qualifiedSequenceName = quoteQualifiedName(seq.sequence_schema, seq.sequence_name);
+        const val = await sql.unsafe<{ last_value: string; is_called: boolean }[]>(
+          `SELECT last_value::text, is_called FROM ${qualifiedSequenceName}`,
+        );
+        const skipSequenceValue =
+          seq.owner_table !== null
+            && excludedTableNames.has(seq.owner_table);
+        if (val[0] && !skipSequenceValue) {
+          emitStatement(`SELECT setval('${qualifiedSequenceName.replaceAll("'", "''")}', ${val[0].last_value}, ${val[0].is_called ? "true" : "false"});`);
+        }
+      }
+      emit("");
+    }
+
+    emitStatement("COMMIT;");
+    emit("");
+
+    // Write the backup file
+    mkdirSync(opts.backupDir, { recursive: true });
+    const backupFile = resolve(opts.backupDir, `${filenamePrefix}-${timestamp()}.sql`);
+    await writeFile(backupFile, lines.join("\n"), "utf8");
+
+    const sizeBytes = statSync(backupFile).size;
+    const prunedCount = pruneOldBackups(opts.backupDir, retentionDays, filenamePrefix);
+
+    return {
+      backupFile,
+      sizeBytes,
+      prunedCount,
+    };
+  } finally {
+    await sql.end();
+  }
+}
+
+export async function runDatabaseRestore(opts: RunDatabaseRestoreOptions): Promise<void> {
+  const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
+  const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
+
+  try {
+    await sql`SELECT 1`;
+    const contents = await readFile(opts.backupFile, "utf8");
+    const statements = contents
+      .split(STATEMENT_BREAKPOINT)
+      .map((statement) => statement.trim())
+      .filter((statement) => statement.length > 0);
+
+    for (const statement of statements) {
+      await sql.unsafe(statement).execute();
+    }
+  } catch (error) {
+    const statementPreview = typeof error === "object" && error !== null && typeof (error as Record<string, unknown>).query === "string"
+      ? String((error as Record<string, unknown>).query)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0 && !line.startsWith("--"))
+      : null;
+    throw new Error(
+      `Failed to restore ${basename(opts.backupFile)}: ${sanitizeRestoreErrorMessage(error)}${statementPreview ? ` [statement: ${statementPreview.slice(0, 120)}]` : ""}`,
+    );
+  } finally {
+    await sql.end();
+  }
+}
+
+export function formatDatabaseBackupResult(result: RunDatabaseBackupResult): string {
+  const size = formatBackupSize(result.sizeBytes);
+  const pruned = result.prunedCount > 0 ? `; pruned ${result.prunedCount} old backup(s)` : "";
+  return `${result.backupFile} (${size}${pruned})`;
+}

paperclip-reference/packages/db/src/backup.ts

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { formatDatabaseBackupResult, runDatabaseBackup } from "./backup-lib.js";
+
+type PartialConfig = {
+  database?: {
+    mode?: "embedded-postgres" | "postgres";
+    connectionString?: string;
+    embeddedPostgresPort?: number;
+    backup?: {
+      dir?: string;
+      retentionDays?: number;
+    };
+  };
+};
+
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolvePaperclipHomeDir(): string {
+  const envHome = process.env.PAPERCLIP_HOME?.trim();
+  if (envHome) return path.resolve(expandHomePrefix(envHome));
+  return path.resolve(os.homedir(), ".paperclip");
+}
+
+function resolvePaperclipInstanceId(): string {
+  const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
+  if (!/^[a-zA-Z0-9_-]+$/.test(raw)) {
+    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
+  }
+  return raw;
+}
+
+function resolveDefaultConfigPath(): string {
+  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "config.json");
+}
+
+function readConfig(configPath: string): PartialConfig | null {
+  if (!existsSync(configPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    return typeof parsed === "object" && parsed ? (parsed as PartialConfig) : null;
+  } catch {
+    return null;
+  }
+}
+
+function asPositiveInt(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const rounded = Math.trunc(value);
+  return rounded > 0 ? rounded : null;
+}
+
+function resolveEmbeddedPort(config: PartialConfig | null): number {
+  return asPositiveInt(config?.database?.embeddedPostgresPort) ?? 54329;
+}
+
+function resolveConnectionString(config: PartialConfig | null): string {
+  const envUrl = process.env.DATABASE_URL?.trim();
+  if (envUrl) return envUrl;
+
+  if (config?.database?.mode === "postgres" && typeof config.database.connectionString === "string") {
+    const trimmed = config.database.connectionString.trim();
+    if (trimmed) return trimmed;
+  }
+
+  const port = resolveEmbeddedPort(config);
+  return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
+}
+
+function resolveDefaultBackupDir(): string {
+  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "data", "backups");
+}
+
+function resolveBackupDir(config: PartialConfig | null): string {
+  const raw = config?.database?.backup?.dir;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return path.resolve(expandHomePrefix(raw.trim()));
+  }
+  return resolveDefaultBackupDir();
+}
+
+function resolveRetentionDays(config: PartialConfig | null): number {
+  return asPositiveInt(config?.database?.backup?.retentionDays) ?? 30;
+}
+
+async function main() {
+  const configPath = resolveDefaultConfigPath();
+  const config = readConfig(configPath);
+  const connectionString = resolveConnectionString(config);
+  const backupDir = resolveBackupDir(config);
+  const retentionDays = resolveRetentionDays(config);
+
+  console.log(`Config path: ${configPath}`);
+  console.log(`Backing up database to: ${backupDir}`);
+  console.log(`Retention window: ${retentionDays} day(s)`);
+
+  try {
+    const result = await runDatabaseBackup({
+      connectionString,
+      backupDir,
+      retentionDays,
+      filenamePrefix: "paperclip",
+    });
+
+    console.log(`Backup saved: ${formatDatabaseBackupResult(result)}`);
+  } catch (err) {
+    console.error("Backup failed.");
+    if (err instanceof Error) {
+      console.error(err.message);
+    } else {
+      console.error(String(err));
+    }
+    process.exit(1);
+  }
+}
+
+await main();

paperclip-reference/packages/db/src/client.test.ts

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import postgres from "postgres";
+import {
+  applyPendingMigrations,
+  ensurePostgresDatabase,
+  inspectMigrations,
+} from "./client.js";
+
+type EmbeddedPostgresInstance = {
+  initialise(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+};
+
+type EmbeddedPostgresCtor = new (opts: {
+  databaseDir: string;
+  user: string;
+  password: string;
+  port: number;
+  persistent: boolean;
+  initdbFlags?: string[];
+  onLog?: (message: unknown) => void;
+  onError?: (message: unknown) => void;
+}) => EmbeddedPostgresInstance;
+
+const tempPaths: string[] = [];
+const runningInstances: EmbeddedPostgresInstance[] = [];
+
+async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
+  const mod = await import("embedded-postgres");
+  return mod.default as EmbeddedPostgresCtor;
+}
+
+async function getAvailablePort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to allocate test port")));
+        return;
+      }
+      const { port } = address;
+      server.close((error) => {
+        if (error) reject(error);
+        else resolve(port);
+      });
+    });
+  });
+}
+
+async function createTempDatabase(): Promise<string> {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-client-"));
+  tempPaths.push(dataDir);
+  const port = await getAvailablePort();
+  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
+  const instance = new EmbeddedPostgres({
+    databaseDir: dataDir,
+    user: "paperclip",
+    password: "paperclip",
+    port,
+    persistent: true,
+    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+    onLog: () => {},
+    onError: () => {},
+  });
+  await instance.initialise();
+  await instance.start();
+  runningInstances.push(instance);
+
+  const adminUrl = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
+  await ensurePostgresDatabase(adminUrl, "paperclip");
+  return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
+}
+
+async function migrationHash(migrationFile: string): Promise<string> {
+  const content = await fs.promises.readFile(
+    new URL(`./migrations/${migrationFile}`, import.meta.url),
+    "utf8",
+  );
+  return createHash("sha256").update(content).digest("hex");
+}
+
+afterEach(async () => {
+  while (runningInstances.length > 0) {
+    const instance = runningInstances.pop();
+    if (!instance) continue;
+    await instance.stop();
+  }
+  while (tempPaths.length > 0) {
+    const tempPath = tempPaths.pop();
+    if (!tempPath) continue;
+    fs.rmSync(tempPath, { recursive: true, force: true });
+  }
+});
+
+describe("applyPendingMigrations", () => {
+  it(
+    "applies an inserted earlier migration without replaying later legacy migrations",
+    async () => {
+      const connectionString = await createTempDatabase();
+
+      await applyPendingMigrations(connectionString);
+
+      const sql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        const richMagnetoHash = await migrationHash("0030_rich_magneto.sql");
+
+        await sql.unsafe(
+          `DELETE FROM "drizzle"."__drizzle_migrations" WHERE hash = '${richMagnetoHash}'`,
+        );
+        await sql.unsafe(`DROP TABLE "company_logos"`);
+      } finally {
+        await sql.end();
+      }
+
+      const pendingState = await inspectMigrations(connectionString);
+      expect(pendingState).toMatchObject({
+        status: "needsMigrations",
+        pendingMigrations: ["0030_rich_magneto.sql"],
+        reason: "pending-migrations",
+      });
+
+      await applyPendingMigrations(connectionString);
+
+      const finalState = await inspectMigrations(connectionString);
+      expect(finalState.status).toBe("upToDate");
+
+      const verifySql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        const rows = await verifySql.unsafe<{ table_name: string }[]>(
+          `
+            SELECT table_name
+            FROM information_schema.tables
+            WHERE table_schema = 'public'
+              AND table_name IN ('company_logos', 'execution_workspaces')
+            ORDER BY table_name
+          `,
+        );
+        expect(rows.map((row) => row.table_name)).toEqual([
+          "company_logos",
+          "execution_workspaces",
+        ]);
+      } finally {
+        await verifySql.end();
+      }
+    },
+    20_000,
+  );
+
+  it(
+    "replays migration 0044 safely when its schema changes already exist",
+    async () => {
+      const connectionString = await createTempDatabase();
+
+      await applyPendingMigrations(connectionString);
+
+      const sql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        const illegalToadHash = await migrationHash("0044_illegal_toad.sql");
+
+        await sql.unsafe(
+          `DELETE FROM "drizzle"."__drizzle_migrations" WHERE hash = '${illegalToadHash}'`,
+        );
+
+        const columns = await sql.unsafe<{ column_name: string }[]>(
+          `
+            SELECT column_name
+            FROM information_schema.columns
+            WHERE table_schema = 'public'
+              AND table_name = 'instance_settings'
+              AND column_name = 'general'
+          `,
+        );
+        expect(columns).toHaveLength(1);
+      } finally {
+        await sql.end();
+      }
+
+      const pendingState = await inspectMigrations(connectionString);
+      expect(pendingState).toMatchObject({
+        status: "needsMigrations",
+        pendingMigrations: ["0044_illegal_toad.sql"],
+        reason: "pending-migrations",
+      });
+
+      await applyPendingMigrations(connectionString);
+
+      const finalState = await inspectMigrations(connectionString);
+      expect(finalState.status).toBe("upToDate");
+    },
+    20_000,
+  );
+
+  it(
+    "enforces a unique board_api_keys.key_hash after migration 0044",
+    async () => {
+      const connectionString = await createTempDatabase();
+
+      await applyPendingMigrations(connectionString);
+
+      const sql = postgres(connectionString, { max: 1, onnotice: () => {} });
+      try {
+        await sql.unsafe(`
+          INSERT INTO "user" ("id", "name", "email", "email_verified", "created_at", "updated_at")
+          VALUES ('user-1', 'User One', 'user@example.com', true, now(), now())
+        `);
+        await sql.unsafe(`
+          INSERT INTO "board_api_keys" ("id", "user_id", "name", "key_hash", "created_at")
+          VALUES ('00000000-0000-0000-0000-000000000001', 'user-1', 'Key One', 'dup-hash', now())
+        `);
+        await expect(
+          sql.unsafe(`
+            INSERT INTO "board_api_keys" ("id", "user_id", "name", "key_hash", "created_at")
+            VALUES ('00000000-0000-0000-0000-000000000002', 'user-1', 'Key Two', 'dup-hash', now())
+          `),
+        ).rejects.toThrow();
+      } finally {
+        await sql.end();
+      }
+    },
+    20_000,
+  );
+});

paperclip-reference/packages/db/src/client.ts

@@ -0,0 +1,779 @@
+import { createHash } from "node:crypto";
+import { drizzle as drizzlePg } from "drizzle-orm/postgres-js";
+import { migrate as migratePg } from "drizzle-orm/postgres-js/migrator";
+import { readFile, readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import postgres from "postgres";
+import * as schema from "./schema/index.js";
+
+const MIGRATIONS_FOLDER = fileURLToPath(new URL("./migrations", import.meta.url));
+const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
+const MIGRATIONS_JOURNAL_JSON = fileURLToPath(new URL("./migrations/meta/_journal.json", import.meta.url));
+
+function createUtilitySql(url: string) {
+  return postgres(url, { max: 1, onnotice: () => {} });
+}
+
+function isSafeIdentifier(value: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+
+function quoteIdentifier(value: string): string {
+  if (!isSafeIdentifier(value)) throw new Error(`Unsafe SQL identifier: ${value}`);
+  return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+
+function quoteLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function splitMigrationStatements(content: string): string[] {
+  return content
+    .split("--> statement-breakpoint")
+    .map((statement) => statement.trim())
+    .filter((statement) => statement.length > 0);
+}
+
+export type MigrationState =
+  | { status: "upToDate"; tableCount: number; availableMigrations: string[]; appliedMigrations: string[] }
+  | {
+      status: "needsMigrations";
+      tableCount: number;
+      availableMigrations: string[];
+      appliedMigrations: string[];
+      pendingMigrations: string[];
+      reason: "no-migration-journal-empty-db" | "no-migration-journal-non-empty-db" | "pending-migrations";
+    };
+
+export function createDb(url: string) {
+  const sql = postgres(url);
+  return drizzlePg(sql, { schema });
+}
+
+export async function getPostgresDataDirectory(url: string): Promise<string | null> {
+  const sql = createUtilitySql(url);
+  try {
+    const rows = await sql<{ data_directory: string | null }[]>`
+      SELECT current_setting('data_directory', true) AS data_directory
+    `;
+    const actual = rows[0]?.data_directory;
+    return typeof actual === "string" && actual.length > 0 ? actual : null;
+  } catch {
+    return null;
+  } finally {
+    await sql.end();
+  }
+}
+
+async function listMigrationFiles(): Promise<string[]> {
+  const entries = await readdir(MIGRATIONS_FOLDER, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".sql"))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+type MigrationJournalFile = {
+  entries?: Array<{ idx?: number; tag?: string; when?: number }>;
+};
+
+type JournalMigrationEntry = {
+  fileName: string;
+  folderMillis: number;
+  order: number;
+};
+
+async function listJournalMigrationEntries(): Promise<JournalMigrationEntry[]> {
+  try {
+    const raw = await readFile(MIGRATIONS_JOURNAL_JSON, "utf8");
+    const parsed = JSON.parse(raw) as MigrationJournalFile;
+    if (!Array.isArray(parsed.entries)) return [];
+    return parsed.entries
+      .map((entry, entryIndex) => {
+        if (typeof entry?.tag !== "string") return null;
+        if (typeof entry?.when !== "number" || !Number.isFinite(entry.when)) return null;
+        const order = Number.isInteger(entry.idx) ? Number(entry.idx) : entryIndex;
+        return { fileName: `${entry.tag}.sql`, folderMillis: entry.when, order };
+      })
+      .filter((entry): entry is JournalMigrationEntry => entry !== null);
+  } catch {
+    return [];
+  }
+}
+
+async function listJournalMigrationFiles(): Promise<string[]> {
+  const entries = await listJournalMigrationEntries();
+  return entries.map((entry) => entry.fileName);
+}
+
+async function readMigrationFileContent(migrationFile: string): Promise<string> {
+  return readFile(new URL(`./migrations/${migrationFile}`, import.meta.url), "utf8");
+}
+
+async function orderMigrationsByJournal(migrationFiles: string[]): Promise<string[]> {
+  const journalEntries = await listJournalMigrationEntries();
+  const orderByFileName = new Map(journalEntries.map((entry) => [entry.fileName, entry.order]));
+  return [...migrationFiles].sort((left, right) => {
+    const leftOrder = orderByFileName.get(left);
+    const rightOrder = orderByFileName.get(right);
+    if (leftOrder === undefined && rightOrder === undefined) return left.localeCompare(right);
+    if (leftOrder === undefined) return 1;
+    if (rightOrder === undefined) return -1;
+    if (leftOrder === rightOrder) return left.localeCompare(right);
+    return leftOrder - rightOrder;
+  });
+}
+
+type SqlExecutor = Pick<ReturnType<typeof postgres>, "unsafe">;
+
+async function runInTransaction(sql: SqlExecutor, action: () => Promise<void>): Promise<void> {
+  await sql.unsafe("BEGIN");
+  try {
+    await action();
+    await sql.unsafe("COMMIT");
+  } catch (error) {
+    try {
+      await sql.unsafe("ROLLBACK");
+    } catch {
+      // Ignore rollback failures and surface the original error.
+    }
+    throw error;
+  }
+}
+
+async function latestMigrationCreatedAt(
+  sql: SqlExecutor,
+  qualifiedTable: string,
+): Promise<number | null> {
+  const rows = await sql.unsafe<{ created_at: string | number | null }[]>(
+    `SELECT created_at FROM ${qualifiedTable} ORDER BY created_at DESC NULLS LAST LIMIT 1`,
+  );
+  const value = Number(rows[0]?.created_at ?? Number.NaN);
+  return Number.isFinite(value) ? value : null;
+}
+
+function normalizeFolderMillis(value: number | null | undefined): number {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.trunc(value);
+  }
+  return Date.now();
+}
+
+async function ensureMigrationJournalTable(
+  sql: ReturnType<typeof postgres>,
+): Promise<{ migrationTableSchema: string; columnNames: Set<string> }> {
+  let migrationTableSchema = await discoverMigrationTableSchema(sql);
+  if (!migrationTableSchema) {
+    const drizzleSchema = quoteIdentifier("drizzle");
+    const migrationTable = quoteIdentifier(DRIZZLE_MIGRATIONS_TABLE);
+    await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS ${drizzleSchema}`);
+    await sql.unsafe(
+      `CREATE TABLE IF NOT EXISTS ${drizzleSchema}.${migrationTable} (id SERIAL PRIMARY KEY, hash text NOT NULL, created_at bigint)`,
+    );
+    migrationTableSchema = (await discoverMigrationTableSchema(sql)) ?? "drizzle";
+  }
+
+  const columnNames = await getMigrationTableColumnNames(sql, migrationTableSchema);
+  return { migrationTableSchema, columnNames };
+}
+
+async function migrationHistoryEntryExists(
+  sql: SqlExecutor,
+  qualifiedTable: string,
+  columnNames: Set<string>,
+  migrationFile: string,
+  hash: string,
+): Promise<boolean> {
+  const predicates: string[] = [];
+  if (columnNames.has("hash")) predicates.push(`hash = ${quoteLiteral(hash)}`);
+  if (columnNames.has("name")) predicates.push(`name = ${quoteLiteral(migrationFile)}`);
+  if (predicates.length === 0) return false;
+
+  const rows = await sql.unsafe<{ one: number }[]>(
+    `SELECT 1 AS one FROM ${qualifiedTable} WHERE ${predicates.join(" OR ")} LIMIT 1`,
+  );
+  return rows.length > 0;
+}
+
+async function recordMigrationHistoryEntry(
+  sql: SqlExecutor,
+  qualifiedTable: string,
+  columnNames: Set<string>,
+  migrationFile: string,
+  hash: string,
+  folderMillis: number,
+): Promise<void> {
+  const insertColumns: string[] = [];
+  const insertValues: string[] = [];
+
+  if (columnNames.has("hash")) {
+    insertColumns.push(quoteIdentifier("hash"));
+    insertValues.push(quoteLiteral(hash));
+  }
+  if (columnNames.has("name")) {
+    insertColumns.push(quoteIdentifier("name"));
+    insertValues.push(quoteLiteral(migrationFile));
+  }
+  if (columnNames.has("created_at")) {
+    const latestCreatedAt = await latestMigrationCreatedAt(sql, qualifiedTable);
+    const createdAt = latestCreatedAt === null
+      ? normalizeFolderMillis(folderMillis)
+      : Math.max(latestCreatedAt + 1, normalizeFolderMillis(folderMillis));
+    insertColumns.push(quoteIdentifier("created_at"));
+    insertValues.push(quoteLiteral(String(createdAt)));
+  }
+
+  if (insertColumns.length === 0) return;
+
+  await sql.unsafe(
+    `INSERT INTO ${qualifiedTable} (${insertColumns.join(", ")}) VALUES (${insertValues.join(", ")})`,
+  );
+}
+
+async function applyPendingMigrationsManually(
+  url: string,
+  pendingMigrations: string[],
+): Promise<void> {
+  if (pendingMigrations.length === 0) return;
+
+  const orderedPendingMigrations = await orderMigrationsByJournal(pendingMigrations);
+  const journalEntries = await listJournalMigrationEntries();
+  const folderMillisByFileName = new Map(
+    journalEntries.map((entry) => [entry.fileName, normalizeFolderMillis(entry.folderMillis)]),
+  );
+
+  const sql = createUtilitySql(url);
+  try {
+    const { migrationTableSchema, columnNames } = await ensureMigrationJournalTable(sql);
+    const qualifiedTable = `${quoteIdentifier(migrationTableSchema)}.${quoteIdentifier(DRIZZLE_MIGRATIONS_TABLE)}`;
+
+    for (const migrationFile of orderedPendingMigrations) {
+      const migrationContent = await readMigrationFileContent(migrationFile);
+      const hash = createHash("sha256").update(migrationContent).digest("hex");
+      const existingEntry = await migrationHistoryEntryExists(
+        sql,
+        qualifiedTable,
+        columnNames,
+        migrationFile,
+        hash,
+      );
+      if (existingEntry) continue;
+
+      await runInTransaction(sql, async () => {
+        for (const statement of splitMigrationStatements(migrationContent)) {
+          await sql.unsafe(statement);
+        }
+
+        await recordMigrationHistoryEntry(
+          sql,
+          qualifiedTable,
+          columnNames,
+          migrationFile,
+          hash,
+          folderMillisByFileName.get(migrationFile) ?? Date.now(),
+        );
+      });
+    }
+  } finally {
+    await sql.end();
+  }
+}
+
+async function mapHashesToMigrationFiles(migrationFiles: string[]): Promise<Map<string, string>> {
+  const mapped = new Map<string, string>();
+
+  await Promise.all(
+    migrationFiles.map(async (migrationFile) => {
+      const content = await readMigrationFileContent(migrationFile);
+      const hash = createHash("sha256").update(content).digest("hex");
+      mapped.set(hash, migrationFile);
+    }),
+  );
+
+  return mapped;
+}
+
+async function getMigrationTableColumnNames(
+  sql: ReturnType<typeof postgres>,
+  migrationTableSchema: string,
+): Promise<Set<string>> {
+  const columns = await sql.unsafe<{ column_name: string }[]>(
+    `
+      SELECT column_name
+      FROM information_schema.columns
+      WHERE table_schema = ${quoteLiteral(migrationTableSchema)}
+        AND table_name = ${quoteLiteral(DRIZZLE_MIGRATIONS_TABLE)}
+    `,
+  );
+  return new Set(columns.map((column) => column.column_name));
+}
+
+async function tableExists(
+  sql: ReturnType<typeof postgres>,
+  tableName: string,
+): Promise<boolean> {
+  const rows = await sql<{ exists: boolean }[]>`
+    SELECT EXISTS (
+      SELECT 1
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+        AND table_name = ${tableName}
+    ) AS exists
+  `;
+  return rows[0]?.exists ?? false;
+}
+
+async function columnExists(
+  sql: ReturnType<typeof postgres>,
+  tableName: string,
+  columnName: string,
+): Promise<boolean> {
+  const rows = await sql<{ exists: boolean }[]>`
+    SELECT EXISTS (
+      SELECT 1
+      FROM information_schema.columns
+      WHERE table_schema = 'public'
+        AND table_name = ${tableName}
+        AND column_name = ${columnName}
+    ) AS exists
+  `;
+  return rows[0]?.exists ?? false;
+}
+
+async function indexExists(
+  sql: ReturnType<typeof postgres>,
+  indexName: string,
+): Promise<boolean> {
+  const rows = await sql<{ exists: boolean }[]>`
+    SELECT EXISTS (
+      SELECT 1
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public'
+        AND c.relkind = 'i'
+        AND c.relname = ${indexName}
+    ) AS exists
+  `;
+  return rows[0]?.exists ?? false;
+}
+
+async function constraintExists(
+  sql: ReturnType<typeof postgres>,
+  constraintName: string,
+): Promise<boolean> {
+  const rows = await sql<{ exists: boolean }[]>`
+    SELECT EXISTS (
+      SELECT 1
+      FROM pg_constraint c
+      JOIN pg_namespace n ON n.oid = c.connamespace
+      WHERE n.nspname = 'public'
+        AND c.conname = ${constraintName}
+    ) AS exists
+  `;
+  return rows[0]?.exists ?? false;
+}
+
+async function migrationStatementAlreadyApplied(
+  sql: ReturnType<typeof postgres>,
+  statement: string,
+): Promise<boolean> {
+  const normalized = statement.replace(/\s+/g, " ").trim();
+
+  const createTableMatch = normalized.match(/^CREATE TABLE(?: IF NOT EXISTS)? "([^"]+)"/i);
+  if (createTableMatch) {
+    return tableExists(sql, createTableMatch[1]);
+  }
+
+  const addColumnMatch = normalized.match(
+    /^ALTER TABLE "([^"]+)" ADD COLUMN(?: IF NOT EXISTS)? "([^"]+)"/i,
+  );
+  if (addColumnMatch) {
+    return columnExists(sql, addColumnMatch[1], addColumnMatch[2]);
+  }
+
+  const createIndexMatch = normalized.match(/^CREATE (?:UNIQUE )?INDEX(?: IF NOT EXISTS)? "([^"]+)"/i);
+  if (createIndexMatch) {
+    return indexExists(sql, createIndexMatch[1]);
+  }
+
+  const addConstraintMatch = normalized.match(/^ALTER TABLE "([^"]+)" ADD CONSTRAINT "([^"]+)"/i);
+  if (addConstraintMatch) {
+    return constraintExists(sql, addConstraintMatch[2]);
+  }
+
+  // If we cannot reason about a statement safely, require manual migration.
+  return false;
+}
+
+async function migrationContentAlreadyApplied(
+  sql: ReturnType<typeof postgres>,
+  migrationContent: string,
+): Promise<boolean> {
+  const statements = splitMigrationStatements(migrationContent);
+  if (statements.length === 0) return false;
+
+  for (const statement of statements) {
+    const applied = await migrationStatementAlreadyApplied(sql, statement);
+    if (!applied) return false;
+  }
+
+  return true;
+}
+
+async function loadAppliedMigrations(
+  sql: ReturnType<typeof postgres>,
+  migrationTableSchema: string,
+  availableMigrations: string[],
+): Promise<string[]> {
+  const quotedSchema = quoteIdentifier(migrationTableSchema);
+  const qualifiedTable = `${quotedSchema}.${quoteIdentifier(DRIZZLE_MIGRATIONS_TABLE)}`;
+  const columnNames = await getMigrationTableColumnNames(sql, migrationTableSchema);
+
+  if (columnNames.has("name")) {
+    const rows = await sql.unsafe<{ name: string }[]>(`SELECT name FROM ${qualifiedTable} ORDER BY id`);
+    return rows.map((row) => row.name).filter((name): name is string => Boolean(name));
+  }
+
+  if (columnNames.has("hash")) {
+    const rows = await sql.unsafe<{ hash: string }[]>(`SELECT hash FROM ${qualifiedTable} ORDER BY id`);
+    const hashesToMigrationFiles = await mapHashesToMigrationFiles(availableMigrations);
+    const appliedFromHashes = rows
+      .map((row) => hashesToMigrationFiles.get(row.hash))
+      .filter((name): name is string => Boolean(name));
+
+    if (appliedFromHashes.length > 0) {
+      // Best-effort: when all hashes resolve, this is authoritative.
+      if (appliedFromHashes.length === rows.length) return appliedFromHashes;
+
+      // Partial hash resolution can happen when files have changed; return what we can trust.
+      return appliedFromHashes;
+    }
+
+    // Fallback only when hashes are unavailable/unresolved.
+    if (columnNames.has("created_at")) {
+      const journalEntries = await listJournalMigrationEntries();
+      if (journalEntries.length > 0) {
+        const lastDbRows = await sql.unsafe<{ created_at: string | number | null }[]>(
+          `SELECT created_at FROM ${qualifiedTable} ORDER BY created_at DESC LIMIT 1`,
+        );
+        const lastCreatedAt = Number(lastDbRows[0]?.created_at ?? -1);
+        if (Number.isFinite(lastCreatedAt) && lastCreatedAt >= 0) {
+          return journalEntries
+            .filter((entry) => availableMigrations.includes(entry.fileName))
+            .filter((entry) => entry.folderMillis <= lastCreatedAt)
+            .map((entry) => entry.fileName)
+            .slice(0, rows.length);
+        }
+      }
+    }
+  }
+
+  const rows = await sql.unsafe<{ id: number }[]>(`SELECT id FROM ${qualifiedTable} ORDER BY id`);
+  const journalMigrationFiles = await listJournalMigrationFiles();
+  const appliedFromIds = rows
+    .map((row) => journalMigrationFiles[row.id - 1])
+    .filter((name): name is string => Boolean(name));
+  if (appliedFromIds.length > 0) return appliedFromIds;
+
+  return availableMigrations.slice(0, Math.max(0, rows.length));
+}
+
+export type MigrationHistoryReconcileResult = {
+  repairedMigrations: string[];
+  remainingMigrations: string[];
+};
+
+export async function reconcilePendingMigrationHistory(
+  url: string,
+): Promise<MigrationHistoryReconcileResult> {
+  const state = await inspectMigrations(url);
+  if (state.status !== "needsMigrations" || state.reason !== "pending-migrations") {
+    return { repairedMigrations: [], remainingMigrations: [] };
+  }
+
+  const sql = createUtilitySql(url);
+  const repairedMigrations: string[] = [];
+
+  try {
+    const journalEntries = await listJournalMigrationEntries();
+    const folderMillisByFile = new Map(journalEntries.map((entry) => [entry.fileName, entry.folderMillis]));
+    const migrationTableSchema = await discoverMigrationTableSchema(sql);
+    if (!migrationTableSchema) {
+      return { repairedMigrations, remainingMigrations: state.pendingMigrations };
+    }
+
+    const columnNames = await getMigrationTableColumnNames(sql, migrationTableSchema);
+    const qualifiedTable = `${quoteIdentifier(migrationTableSchema)}.${quoteIdentifier(DRIZZLE_MIGRATIONS_TABLE)}`;
+
+    for (const migrationFile of state.pendingMigrations) {
+      const migrationContent = await readMigrationFileContent(migrationFile);
+      const alreadyApplied = await migrationContentAlreadyApplied(sql, migrationContent);
+      if (!alreadyApplied) break;
+
+      const hash = createHash("sha256").update(migrationContent).digest("hex");
+      const folderMillis = folderMillisByFile.get(migrationFile) ?? Date.now();
+      const existingByHash = columnNames.has("hash")
+        ? await sql.unsafe<{ created_at: string | number | null }[]>(
+            `SELECT created_at FROM ${qualifiedTable} WHERE hash = ${quoteLiteral(hash)} ORDER BY created_at DESC LIMIT 1`,
+          )
+        : [];
+      const existingByName = columnNames.has("name")
+        ? await sql.unsafe<{ created_at: string | number | null }[]>(
+            `SELECT created_at FROM ${qualifiedTable} WHERE name = ${quoteLiteral(migrationFile)} ORDER BY created_at DESC LIMIT 1`,
+          )
+        : [];
+      if (existingByHash.length > 0 || existingByName.length > 0) {
+        if (columnNames.has("created_at")) {
+          const existingHashCreatedAt = Number(existingByHash[0]?.created_at ?? -1);
+          if (existingByHash.length > 0 && Number.isFinite(existingHashCreatedAt) && existingHashCreatedAt < folderMillis) {
+            await sql.unsafe(
+              `UPDATE ${qualifiedTable} SET created_at = ${quoteLiteral(String(folderMillis))} WHERE hash = ${quoteLiteral(hash)} AND created_at < ${quoteLiteral(String(folderMillis))}`,
+            );
+          }
+
+          const existingNameCreatedAt = Number(existingByName[0]?.created_at ?? -1);
+          if (existingByName.length > 0 && Number.isFinite(existingNameCreatedAt) && existingNameCreatedAt < folderMillis) {
+            await sql.unsafe(
+              `UPDATE ${qualifiedTable} SET created_at = ${quoteLiteral(String(folderMillis))} WHERE name = ${quoteLiteral(migrationFile)} AND created_at < ${quoteLiteral(String(folderMillis))}`,
+            );
+          }
+        }
+
+        repairedMigrations.push(migrationFile);
+        continue;
+      }
+
+      const insertColumns: string[] = [];
+      const insertValues: string[] = [];
+
+      if (columnNames.has("hash")) {
+        insertColumns.push(quoteIdentifier("hash"));
+        insertValues.push(quoteLiteral(hash));
+      }
+      if (columnNames.has("name")) {
+        insertColumns.push(quoteIdentifier("name"));
+        insertValues.push(quoteLiteral(migrationFile));
+      }
+      if (columnNames.has("created_at")) {
+        insertColumns.push(quoteIdentifier("created_at"));
+        insertValues.push(quoteLiteral(String(folderMillis)));
+      }
+
+      if (insertColumns.length === 0) break;
+
+      await sql.unsafe(
+        `INSERT INTO ${qualifiedTable} (${insertColumns.join(", ")}) VALUES (${insertValues.join(", ")})`,
+      );
+      repairedMigrations.push(migrationFile);
+    }
+  } finally {
+    await sql.end();
+  }
+
+  const refreshed = await inspectMigrations(url);
+  return {
+    repairedMigrations,
+    remainingMigrations:
+      refreshed.status === "needsMigrations" ? refreshed.pendingMigrations : [],
+  };
+}
+
+async function discoverMigrationTableSchema(sql: ReturnType<typeof postgres>): Promise<string | null> {
+  const rows = await sql<{ schemaName: string }[]>`
+    SELECT n.nspname AS "schemaName"
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relname = ${DRIZZLE_MIGRATIONS_TABLE} AND c.relkind = 'r'
+  `;
+
+  if (rows.length === 0) return null;
+
+  const drizzleSchema = rows.find(({ schemaName }) => schemaName === "drizzle");
+  if (drizzleSchema) return drizzleSchema.schemaName;
+
+  const publicSchema = rows.find(({ schemaName }) => schemaName === "public");
+  if (publicSchema) return publicSchema.schemaName;
+
+  return rows[0]?.schemaName ?? null;
+}
+
+export async function inspectMigrations(url: string): Promise<MigrationState> {
+  const sql = createUtilitySql(url);
+
+  try {
+    const availableMigrations = await listMigrationFiles();
+    const tableCountResult = await sql<{ count: number }[]>`
+      select count(*)::int as count
+      from information_schema.tables
+      where table_schema = 'public'
+        and table_type = 'BASE TABLE'
+    `;
+    const tableCount = tableCountResult[0]?.count ?? 0;
+
+    const migrationTableSchema = await discoverMigrationTableSchema(sql);
+    if (!migrationTableSchema) {
+      if (tableCount > 0) {
+        return {
+          status: "needsMigrations",
+          tableCount,
+          availableMigrations,
+          appliedMigrations: [],
+          pendingMigrations: availableMigrations,
+          reason: "no-migration-journal-non-empty-db",
+        };
+      }
+
+      return {
+        status: "needsMigrations",
+        tableCount,
+        availableMigrations,
+        appliedMigrations: [],
+        pendingMigrations: availableMigrations,
+        reason: "no-migration-journal-empty-db",
+      };
+    }
+
+    const appliedMigrations = await loadAppliedMigrations(sql, migrationTableSchema, availableMigrations);
+    const pendingMigrations = availableMigrations.filter((name) => !appliedMigrations.includes(name));
+    if (pendingMigrations.length === 0) {
+      return {
+        status: "upToDate",
+        tableCount,
+        availableMigrations,
+        appliedMigrations,
+      };
+    }
+
+    return {
+      status: "needsMigrations",
+      tableCount,
+      availableMigrations,
+      appliedMigrations,
+      pendingMigrations,
+      reason: "pending-migrations",
+    };
+  } finally {
+    await sql.end();
+  }
+}
+
+export async function applyPendingMigrations(url: string): Promise<void> {
+  const initialState = await inspectMigrations(url);
+  if (initialState.status === "upToDate") return;
+
+  if (initialState.reason === "no-migration-journal-empty-db") {
+    const sql = createUtilitySql(url);
+    try {
+      const db = drizzlePg(sql);
+      await migratePg(db, { migrationsFolder: MIGRATIONS_FOLDER });
+    } finally {
+      await sql.end();
+    }
+
+    let bootstrappedState = await inspectMigrations(url);
+    if (bootstrappedState.status === "upToDate") return;
+    if (bootstrappedState.reason === "pending-migrations") {
+      const repair = await reconcilePendingMigrationHistory(url);
+      if (repair.repairedMigrations.length > 0) {
+        bootstrappedState = await inspectMigrations(url);
+      }
+      if (bootstrappedState.status === "needsMigrations" && bootstrappedState.reason === "pending-migrations") {
+        await applyPendingMigrationsManually(url, bootstrappedState.pendingMigrations);
+        bootstrappedState = await inspectMigrations(url);
+      }
+    }
+    if (bootstrappedState.status === "upToDate") return;
+    throw new Error(
+      `Failed to bootstrap migrations: ${bootstrappedState.pendingMigrations.join(", ")}`,
+    );
+  }
+
+  if (initialState.reason === "no-migration-journal-non-empty-db") {
+    throw new Error(
+      "Database has tables but no migration journal; automatic migration is unsafe. Initialize migration history manually.",
+    );
+  }
+
+  let state = await inspectMigrations(url);
+  if (state.status === "upToDate") return;
+
+  const repair = await reconcilePendingMigrationHistory(url);
+  if (repair.repairedMigrations.length > 0) {
+    state = await inspectMigrations(url);
+    if (state.status === "upToDate") return;
+  }
+
+  if (state.status !== "needsMigrations" || state.reason !== "pending-migrations") {
+    throw new Error("Migrations are still pending after migration-history reconciliation; run inspectMigrations for details.");
+  }
+
+  await applyPendingMigrationsManually(url, state.pendingMigrations);
+
+  const finalState = await inspectMigrations(url);
+  if (finalState.status !== "upToDate") {
+    throw new Error(
+      `Failed to apply pending migrations: ${finalState.pendingMigrations.join(", ")}`,
+    );
+  }
+}
+
+export type MigrationBootstrapResult =
+  | { migrated: true; reason: "migrated-empty-db"; tableCount: 0 }
+  | { migrated: false; reason: "already-migrated"; tableCount: number }
+  | { migrated: false; reason: "not-empty-no-migration-journal"; tableCount: number };
+
+export async function migratePostgresIfEmpty(url: string): Promise<MigrationBootstrapResult> {
+  const sql = createUtilitySql(url);
+
+  try {
+    const migrationTableSchema = await discoverMigrationTableSchema(sql);
+
+    const tableCountResult = await sql<{ count: number }[]>`
+      select count(*)::int as count
+      from information_schema.tables
+      where table_schema = 'public'
+        and table_type = 'BASE TABLE'
+    `;
+
+    const tableCount = tableCountResult[0]?.count ?? 0;
+
+    if (migrationTableSchema) {
+      return { migrated: false, reason: "already-migrated", tableCount };
+    }
+
+    if (tableCount > 0) {
+      return { migrated: false, reason: "not-empty-no-migration-journal", tableCount };
+    }
+
+    const db = drizzlePg(sql);
+    await migratePg(db, { migrationsFolder: MIGRATIONS_FOLDER });
+
+    return { migrated: true, reason: "migrated-empty-db", tableCount: 0 };
+  } finally {
+    await sql.end();
+  }
+}
+
+export async function ensurePostgresDatabase(
+  url: string,
+  databaseName: string,
+): Promise<"created" | "exists"> {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(databaseName)) {
+    throw new Error(`Unsafe database name: ${databaseName}`);
+  }
+
+  const sql = createUtilitySql(url);
+  try {
+    const existing = await sql<{ one: number }[]>`
+      select 1 as one from pg_database where datname = ${databaseName} limit 1
+    `;
+    if (existing.length > 0) return "exists";
+
+    await sql.unsafe(`create database "${databaseName}" encoding 'UTF8' lc_collate 'C' lc_ctype 'C' template template0`);
+    return "created";
+  } finally {
+    await sql.end();
+  }
+}
+
+export type Db = ReturnType<typeof createDb>;

paperclip-reference/packages/db/src/index.ts

@@ -0,0 +1,22 @@
+export {
+  createDb,
+  getPostgresDataDirectory,
+  ensurePostgresDatabase,
+  inspectMigrations,
+  applyPendingMigrations,
+  reconcilePendingMigrationHistory,
+  type MigrationState,
+  type MigrationHistoryReconcileResult,
+  migratePostgresIfEmpty,
+  type MigrationBootstrapResult,
+  type Db,
+} from "./client.js";
+export {
+  runDatabaseBackup,
+  runDatabaseRestore,
+  formatDatabaseBackupResult,
+  type RunDatabaseBackupOptions,
+  type RunDatabaseBackupResult,
+  type RunDatabaseRestoreOptions,
+} from "./backup-lib.js";
+export * from "./schema/index.js";

paperclip-reference/packages/db/src/migrate.ts

@@ -0,0 +1,29 @@
+import { applyPendingMigrations, inspectMigrations } from "./client.js";
+import { resolveMigrationConnection } from "./migration-runtime.js";
+
+async function main(): Promise<void> {
+  const resolved = await resolveMigrationConnection();
+
+  console.log(`Migrating database via ${resolved.source}`);
+
+  try {
+    const before = await inspectMigrations(resolved.connectionString);
+    if (before.status === "upToDate") {
+      console.log("No pending migrations");
+      return;
+    }
+
+    console.log(`Applying ${before.pendingMigrations.length} pending migration(s)...`);
+    await applyPendingMigrations(resolved.connectionString);
+
+    const after = await inspectMigrations(resolved.connectionString);
+    if (after.status !== "upToDate") {
+      throw new Error(`Migrations incomplete: ${after.pendingMigrations.join(", ")}`);
+    }
+    console.log("Migrations complete");
+  } finally {
+    await resolved.stop();
+  }
+}
+
+await main();

paperclip-reference/packages/db/src/migration-runtime.ts

@@ -0,0 +1,200 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import path from "node:path";
+import { ensurePostgresDatabase, getPostgresDataDirectory } from "./client.js";
+import { resolveDatabaseTarget } from "./runtime-config.js";
+
+type EmbeddedPostgresInstance = {
+  initialise(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+};
+
+type EmbeddedPostgresCtor = new (opts: {
+  databaseDir: string;
+  user: string;
+  password: string;
+  port: number;
+  persistent: boolean;
+  initdbFlags?: string[];
+  onLog?: (message: unknown) => void;
+  onError?: (message: unknown) => void;
+}) => EmbeddedPostgresInstance;
+
+export type MigrationConnection = {
+  connectionString: string;
+  source: string;
+  stop: () => Promise<void>;
+};
+
+function toError(error: unknown, fallbackMessage: string): Error {
+  if (error instanceof Error) return error;
+  if (error === undefined) return new Error(fallbackMessage);
+  if (typeof error === "string") return new Error(`${fallbackMessage}: ${error}`);
+
+  try {
+    return new Error(`${fallbackMessage}: ${JSON.stringify(error)}`);
+  } catch {
+    return new Error(`${fallbackMessage}: ${String(error)}`);
+  }
+}
+
+function readRunningPostmasterPid(postmasterPidFile: string): number | null {
+  if (!existsSync(postmasterPidFile)) return null;
+  try {
+    const pid = Number(readFileSync(postmasterPidFile, "utf8").split("\n")[0]?.trim());
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+function readPidFilePort(postmasterPidFile: string): number | null {
+  if (!existsSync(postmasterPidFile)) return null;
+  try {
+    const lines = readFileSync(postmasterPidFile, "utf8").split("\n");
+    const port = Number(lines[3]?.trim());
+    return Number.isInteger(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+async function isPortInUse(port: number): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", (error: NodeJS.ErrnoException) => {
+      resolve(error.code === "EADDRINUSE");
+    });
+    server.listen(port, "127.0.0.1", () => {
+      server.close();
+      resolve(false);
+    });
+  });
+}
+
+async function findAvailablePort(startPort: number): Promise<number> {
+  const maxLookahead = 20;
+  let port = startPort;
+  for (let i = 0; i < maxLookahead; i += 1, port += 1) {
+    if (!(await isPortInUse(port))) return port;
+  }
+  throw new Error(
+    `Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}`,
+  );
+}
+
+async function loadEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
+  try {
+    const mod = await import("embedded-postgres");
+    return mod.default as EmbeddedPostgresCtor;
+  } catch {
+    throw new Error(
+      "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
+    );
+  }
+}
+
+async function ensureEmbeddedPostgresConnection(
+  dataDir: string,
+  preferredPort: number,
+): Promise<MigrationConnection> {
+  const EmbeddedPostgres = await loadEmbeddedPostgresCtor();
+  const selectedPort = await findAvailablePort(preferredPort);
+  const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
+  const pgVersionFile = path.resolve(dataDir, "PG_VERSION");
+  const runningPid = readRunningPostmasterPid(postmasterPidFile);
+  const runningPort = readPidFilePort(postmasterPidFile);
+  const preferredAdminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/postgres`;
+
+  if (!runningPid && existsSync(pgVersionFile)) {
+    try {
+      const actualDataDir = await getPostgresDataDirectory(preferredAdminConnectionString);
+      const matchesDataDir =
+        typeof actualDataDir === "string" &&
+        path.resolve(actualDataDir) === path.resolve(dataDir);
+      if (!matchesDataDir) {
+        throw new Error("reachable postgres does not use the expected embedded data directory");
+      }
+      await ensurePostgresDatabase(preferredAdminConnectionString, "paperclip");
+      process.emitWarning(
+        `Adopting an existing PostgreSQL instance on port ${preferredPort} for embedded data dir ${dataDir} because postmaster.pid is missing.`,
+      );
+      return {
+        connectionString: `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/paperclip`,
+        source: `embedded-postgres@${preferredPort}`,
+        stop: async () => {},
+      };
+    } catch {
+      // Fall through and attempt to start the configured embedded cluster.
+    }
+  }
+
+  if (runningPid) {
+    const port = runningPort ?? preferredPort;
+    const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
+    await ensurePostgresDatabase(adminConnectionString, "paperclip");
+    return {
+      connectionString: `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`,
+      source: `embedded-postgres@${port}`,
+      stop: async () => {},
+    };
+  }
+
+  const instance = new EmbeddedPostgres({
+    databaseDir: dataDir,
+    user: "paperclip",
+    password: "paperclip",
+    port: selectedPort,
+    persistent: true,
+    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+    onLog: () => {},
+    onError: () => {},
+  });
+
+  if (!existsSync(path.resolve(dataDir, "PG_VERSION"))) {
+    try {
+      await instance.initialise();
+    } catch (error) {
+      throw toError(
+        error,
+        `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${selectedPort}`,
+      );
+    }
+  }
+  if (existsSync(postmasterPidFile)) {
+    rmSync(postmasterPidFile, { force: true });
+  }
+  try {
+    await instance.start();
+  } catch (error) {
+    throw toError(error, `Failed to start embedded PostgreSQL on port ${selectedPort}`);
+  }
+
+  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${selectedPort}/postgres`;
+  await ensurePostgresDatabase(adminConnectionString, "paperclip");
+
+  return {
+    connectionString: `postgres://paperclip:paperclip@127.0.0.1:${selectedPort}/paperclip`,
+    source: `embedded-postgres@${selectedPort}`,
+    stop: async () => {
+      await instance.stop();
+    },
+  };
+}
+
+export async function resolveMigrationConnection(): Promise<MigrationConnection> {
+  const target = resolveDatabaseTarget();
+  if (target.mode === "postgres") {
+    return {
+      connectionString: target.connectionString,
+      source: target.source,
+      stop: async () => {},
+    };
+  }
+
+  return ensureEmbeddedPostgresConnection(target.dataDir, target.port);
+}

paperclip-reference/packages/db/src/migration-status.ts

@@ -0,0 +1,61 @@
+import { inspectMigrations } from "./client.js";
+import { resolveMigrationConnection } from "./migration-runtime.js";
+
+const jsonMode = process.argv.includes("--json");
+
+function toError(error: unknown, context = "Migration status check failed"): Error {
+  if (error instanceof Error) return error;
+  if (error === undefined) return new Error(context);
+  if (typeof error === "string") return new Error(`${context}: ${error}`);
+
+  try {
+    return new Error(`${context}: ${JSON.stringify(error)}`);
+  } catch {
+    return new Error(`${context}: ${String(error)}`);
+  }
+}
+
+async function main(): Promise<void> {
+  const connection = await resolveMigrationConnection();
+
+  try {
+    const state = await inspectMigrations(connection.connectionString);
+    const payload =
+      state.status === "upToDate"
+        ? {
+            source: connection.source,
+            status: "upToDate" as const,
+            tableCount: state.tableCount,
+            pendingMigrations: [] as string[],
+          }
+        : {
+            source: connection.source,
+            status: "needsMigrations" as const,
+            tableCount: state.tableCount,
+            pendingMigrations: state.pendingMigrations,
+            reason: state.reason,
+          };
+
+    if (jsonMode) {
+      console.log(JSON.stringify(payload));
+      return;
+    }
+
+    if (payload.status === "upToDate") {
+      console.log(`Database is up to date via ${payload.source}`);
+      return;
+    }
+
+    console.log(
+      `Pending migrations via ${payload.source}: ${payload.pendingMigrations.join(", ")}`,
+    );
+  } finally {
+    await connection.stop();
+  }
+}
+
+main().catch((error) => {
+  const err = toError(error, "Migration status check failed");
+  process.stderr.write(`${err.stack ?? err.message}\n`);
+  process.exit(1);
+});

paperclip-reference/packages/db/src/migrations/0000_mature_masked_marvel.sql

@@ -0,0 +1,208 @@
+CREATE TABLE "activity_log" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"actor_type" text DEFAULT 'system' NOT NULL,
+	"actor_id" text NOT NULL,
+	"action" text NOT NULL,
+	"entity_type" text NOT NULL,
+	"entity_id" text NOT NULL,
+	"agent_id" uuid,
+	"details" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "agent_api_keys" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"company_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"key_hash" text NOT NULL,
+	"last_used_at" timestamp with time zone,
+	"revoked_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "agents" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"role" text DEFAULT 'general' NOT NULL,
+	"title" text,
+	"status" text DEFAULT 'idle' NOT NULL,
+	"reports_to" uuid,
+	"capabilities" text,
+	"adapter_type" text DEFAULT 'process' NOT NULL,
+	"adapter_config" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"context_mode" text DEFAULT 'thin' NOT NULL,
+	"budget_monthly_cents" integer DEFAULT 0 NOT NULL,
+	"spent_monthly_cents" integer DEFAULT 0 NOT NULL,
+	"last_heartbeat_at" timestamp with time zone,
+	"metadata" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "approvals" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"type" text NOT NULL,
+	"requested_by_agent_id" uuid,
+	"requested_by_user_id" text,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"payload" jsonb NOT NULL,
+	"decision_note" text,
+	"decided_by_user_id" text,
+	"decided_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "companies" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"status" text DEFAULT 'active' NOT NULL,
+	"budget_monthly_cents" integer DEFAULT 0 NOT NULL,
+	"spent_monthly_cents" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "cost_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"issue_id" uuid,
+	"project_id" uuid,
+	"goal_id" uuid,
+	"billing_code" text,
+	"provider" text NOT NULL,
+	"model" text NOT NULL,
+	"input_tokens" integer DEFAULT 0 NOT NULL,
+	"output_tokens" integer DEFAULT 0 NOT NULL,
+	"cost_cents" integer NOT NULL,
+	"occurred_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "goals" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"title" text NOT NULL,
+	"description" text,
+	"level" text DEFAULT 'task' NOT NULL,
+	"status" text DEFAULT 'planned' NOT NULL,
+	"parent_id" uuid,
+	"owner_agent_id" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "heartbeat_runs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"invocation_source" text DEFAULT 'manual' NOT NULL,
+	"status" text DEFAULT 'queued' NOT NULL,
+	"started_at" timestamp with time zone,
+	"finished_at" timestamp with time zone,
+	"error" text,
+	"external_run_id" text,
+	"context_snapshot" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "issue_comments" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"author_agent_id" uuid,
+	"author_user_id" text,
+	"body" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "issues" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid,
+	"goal_id" uuid,
+	"parent_id" uuid,
+	"title" text NOT NULL,
+	"description" text,
+	"status" text DEFAULT 'backlog' NOT NULL,
+	"priority" text DEFAULT 'medium' NOT NULL,
+	"assignee_agent_id" uuid,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"request_depth" integer DEFAULT 0 NOT NULL,
+	"billing_code" text,
+	"started_at" timestamp with time zone,
+	"completed_at" timestamp with time zone,
+	"cancelled_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "projects" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"goal_id" uuid,
+	"name" text NOT NULL,
+	"description" text,
+	"status" text DEFAULT 'backlog' NOT NULL,
+	"lead_agent_id" uuid,
+	"target_date" date,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "activity_log" ADD CONSTRAINT "activity_log_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "activity_log" ADD CONSTRAINT "activity_log_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_api_keys" ADD CONSTRAINT "agent_api_keys_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_api_keys" ADD CONSTRAINT "agent_api_keys_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agents" ADD CONSTRAINT "agents_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agents" ADD CONSTRAINT "agents_reports_to_agents_id_fk" FOREIGN KEY ("reports_to") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "approvals" ADD CONSTRAINT "approvals_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "approvals" ADD CONSTRAINT "approvals_requested_by_agent_id_agents_id_fk" FOREIGN KEY ("requested_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD CONSTRAINT "cost_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD CONSTRAINT "cost_events_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD CONSTRAINT "cost_events_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD CONSTRAINT "cost_events_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD CONSTRAINT "cost_events_goal_id_goals_id_fk" FOREIGN KEY ("goal_id") REFERENCES "public"."goals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "goals" ADD CONSTRAINT "goals_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "goals" ADD CONSTRAINT "goals_parent_id_goals_id_fk" FOREIGN KEY ("parent_id") REFERENCES "public"."goals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "goals" ADD CONSTRAINT "goals_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD CONSTRAINT "heartbeat_runs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD CONSTRAINT "heartbeat_runs_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_comments" ADD CONSTRAINT "issue_comments_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_comments" ADD CONSTRAINT "issue_comments_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_comments" ADD CONSTRAINT "issue_comments_author_agent_id_agents_id_fk" FOREIGN KEY ("author_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_goal_id_goals_id_fk" FOREIGN KEY ("goal_id") REFERENCES "public"."goals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_parent_id_issues_id_fk" FOREIGN KEY ("parent_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_assignee_agent_id_agents_id_fk" FOREIGN KEY ("assignee_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "projects" ADD CONSTRAINT "projects_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "projects" ADD CONSTRAINT "projects_goal_id_goals_id_fk" FOREIGN KEY ("goal_id") REFERENCES "public"."goals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "projects" ADD CONSTRAINT "projects_lead_agent_id_agents_id_fk" FOREIGN KEY ("lead_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "activity_log_company_created_idx" ON "activity_log" USING btree ("company_id","created_at");--> statement-breakpoint
+CREATE INDEX "agent_api_keys_key_hash_idx" ON "agent_api_keys" USING btree ("key_hash");--> statement-breakpoint
+CREATE INDEX "agent_api_keys_company_agent_idx" ON "agent_api_keys" USING btree ("company_id","agent_id");--> statement-breakpoint
+CREATE INDEX "agents_company_status_idx" ON "agents" USING btree ("company_id","status");--> statement-breakpoint
+CREATE INDEX "agents_company_reports_to_idx" ON "agents" USING btree ("company_id","reports_to");--> statement-breakpoint
+CREATE INDEX "approvals_company_status_type_idx" ON "approvals" USING btree ("company_id","status","type");--> statement-breakpoint
+CREATE INDEX "cost_events_company_occurred_idx" ON "cost_events" USING btree ("company_id","occurred_at");--> statement-breakpoint
+CREATE INDEX "cost_events_company_agent_occurred_idx" ON "cost_events" USING btree ("company_id","agent_id","occurred_at");--> statement-breakpoint
+CREATE INDEX "goals_company_idx" ON "goals" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "heartbeat_runs_company_agent_started_idx" ON "heartbeat_runs" USING btree ("company_id","agent_id","started_at");--> statement-breakpoint
+CREATE INDEX "issue_comments_issue_idx" ON "issue_comments" USING btree ("issue_id");--> statement-breakpoint
+CREATE INDEX "issue_comments_company_idx" ON "issue_comments" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "issues_company_status_idx" ON "issues" USING btree ("company_id","status");--> statement-breakpoint
+CREATE INDEX "issues_company_assignee_status_idx" ON "issues" USING btree ("company_id","assignee_agent_id","status");--> statement-breakpoint
+CREATE INDEX "issues_company_parent_idx" ON "issues" USING btree ("company_id","parent_id");--> statement-breakpoint
+CREATE INDEX "issues_company_project_idx" ON "issues" USING btree ("company_id","project_id");--> statement-breakpoint
+CREATE INDEX "projects_company_idx" ON "projects" USING btree ("company_id");

paperclip-reference/packages/db/src/migrations/0001_fast_northstar.sql

@@ -0,0 +1,87 @@
+CREATE TABLE "agent_runtime_state" (
+	"agent_id" uuid PRIMARY KEY NOT NULL,
+	"company_id" uuid NOT NULL,
+	"adapter_type" text NOT NULL,
+	"session_id" text,
+	"state_json" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"last_run_id" uuid,
+	"last_run_status" text,
+	"total_input_tokens" bigint DEFAULT 0 NOT NULL,
+	"total_output_tokens" bigint DEFAULT 0 NOT NULL,
+	"total_cached_input_tokens" bigint DEFAULT 0 NOT NULL,
+	"total_cost_cents" bigint DEFAULT 0 NOT NULL,
+	"last_error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "agent_wakeup_requests" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"source" text NOT NULL,
+	"trigger_detail" text,
+	"reason" text,
+	"payload" jsonb,
+	"status" text DEFAULT 'queued' NOT NULL,
+	"coalesced_count" integer DEFAULT 0 NOT NULL,
+	"requested_by_actor_type" text,
+	"requested_by_actor_id" text,
+	"idempotency_key" text,
+	"run_id" uuid,
+	"requested_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"claimed_at" timestamp with time zone,
+	"finished_at" timestamp with time zone,
+	"error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "heartbeat_run_events" (
+	"id" bigserial PRIMARY KEY NOT NULL,
+	"company_id" uuid NOT NULL,
+	"run_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"seq" integer NOT NULL,
+	"event_type" text NOT NULL,
+	"stream" text,
+	"level" text,
+	"color" text,
+	"message" text,
+	"payload" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ALTER COLUMN "invocation_source" SET DEFAULT 'on_demand';--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "runtime_config" jsonb DEFAULT '{}'::jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "trigger_detail" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "wakeup_request_id" uuid;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "exit_code" integer;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "signal" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "usage_json" jsonb;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "result_json" jsonb;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "session_id_before" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "session_id_after" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "log_store" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "log_ref" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "log_bytes" bigint;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "log_sha256" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "log_compressed" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "stdout_excerpt" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "stderr_excerpt" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "error_code" text;--> statement-breakpoint
+ALTER TABLE "agent_runtime_state" ADD CONSTRAINT "agent_runtime_state_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_runtime_state" ADD CONSTRAINT "agent_runtime_state_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_wakeup_requests" ADD CONSTRAINT "agent_wakeup_requests_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_wakeup_requests" ADD CONSTRAINT "agent_wakeup_requests_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "heartbeat_run_events" ADD CONSTRAINT "heartbeat_run_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "heartbeat_run_events" ADD CONSTRAINT "heartbeat_run_events_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "heartbeat_run_events" ADD CONSTRAINT "heartbeat_run_events_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "agent_runtime_state_company_agent_idx" ON "agent_runtime_state" USING btree ("company_id","agent_id");--> statement-breakpoint
+CREATE INDEX "agent_runtime_state_company_updated_idx" ON "agent_runtime_state" USING btree ("company_id","updated_at");--> statement-breakpoint
+CREATE INDEX "agent_wakeup_requests_company_agent_status_idx" ON "agent_wakeup_requests" USING btree ("company_id","agent_id","status");--> statement-breakpoint
+CREATE INDEX "agent_wakeup_requests_company_requested_idx" ON "agent_wakeup_requests" USING btree ("company_id","requested_at");--> statement-breakpoint
+CREATE INDEX "agent_wakeup_requests_agent_requested_idx" ON "agent_wakeup_requests" USING btree ("agent_id","requested_at");--> statement-breakpoint
+CREATE INDEX "heartbeat_run_events_run_seq_idx" ON "heartbeat_run_events" USING btree ("run_id","seq");--> statement-breakpoint
+CREATE INDEX "heartbeat_run_events_company_run_idx" ON "heartbeat_run_events" USING btree ("company_id","run_id");--> statement-breakpoint
+CREATE INDEX "heartbeat_run_events_company_created_idx" ON "heartbeat_run_events" USING btree ("company_id","created_at");

paperclip-reference/packages/db/src/migrations/0002_big_zaladane.sql

@@ -0,0 +1 @@
+ALTER TABLE "heartbeat_runs" ADD CONSTRAINT "heartbeat_runs_wakeup_request_id_agent_wakeup_requests_id_fk" FOREIGN KEY ("wakeup_request_id") REFERENCES "public"."agent_wakeup_requests"("id") ON DELETE no action ON UPDATE no action;

paperclip-reference/packages/db/src/migrations/0003_shallow_quentin_quire.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "activity_log" ADD COLUMN "run_id" uuid;--> statement-breakpoint
+ALTER TABLE "activity_log" ADD CONSTRAINT "activity_log_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "activity_log_run_id_idx" ON "activity_log" USING btree ("run_id");--> statement-breakpoint
+CREATE INDEX "activity_log_entity_type_id_idx" ON "activity_log" USING btree ("entity_type","entity_id");--> statement-breakpoint
+ALTER TABLE "agents" DROP COLUMN "context_mode";

paperclip-reference/packages/db/src/migrations/0004_issue_identifiers.sql

@@ -0,0 +1,28 @@
+-- Add issue identifier columns to companies
+ALTER TABLE "companies" ADD COLUMN "issue_prefix" text NOT NULL DEFAULT 'PAP';--> statement-breakpoint
+ALTER TABLE "companies" ADD COLUMN "issue_counter" integer NOT NULL DEFAULT 0;--> statement-breakpoint
+
+-- Add issue identifier columns to issues
+ALTER TABLE "issues" ADD COLUMN "issue_number" integer;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "identifier" text;--> statement-breakpoint
+
+-- Backfill existing issues: assign sequential issue_number per company ordered by created_at
+WITH numbered AS (
+  SELECT id, company_id, ROW_NUMBER() OVER (PARTITION BY company_id ORDER BY created_at ASC) AS rn
+  FROM issues
+)
+UPDATE issues
+SET issue_number = numbered.rn,
+    identifier = (SELECT issue_prefix FROM companies WHERE companies.id = issues.company_id) || '-' || numbered.rn
+FROM numbered
+WHERE issues.id = numbered.id;--> statement-breakpoint
+
+-- Sync each company's issue_counter to the max assigned number
+UPDATE companies
+SET issue_counter = COALESCE(
+  (SELECT MAX(issue_number) FROM issues WHERE issues.company_id = companies.id),
+  0
+);--> statement-breakpoint
+
+-- Create unique index on (company_id, identifier)
+CREATE UNIQUE INDEX "issues_company_identifier_idx" ON "issues" USING btree ("company_id","identifier");

paperclip-reference/packages/db/src/migrations/0005_chief_luke_cage.sql

@@ -0,0 +1,19 @@
+CREATE TABLE "approval_comments" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"approval_id" uuid NOT NULL,
+	"author_agent_id" uuid,
+	"author_user_id" text,
+	"body" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "permissions" jsonb DEFAULT '{}'::jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "companies" ADD COLUMN "require_board_approval_for_new_agents" boolean DEFAULT true NOT NULL;--> statement-breakpoint
+ALTER TABLE "approval_comments" ADD CONSTRAINT "approval_comments_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "approval_comments" ADD CONSTRAINT "approval_comments_approval_id_approvals_id_fk" FOREIGN KEY ("approval_id") REFERENCES "public"."approvals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "approval_comments" ADD CONSTRAINT "approval_comments_author_agent_id_agents_id_fk" FOREIGN KEY ("author_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "approval_comments_company_idx" ON "approval_comments" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "approval_comments_approval_idx" ON "approval_comments" USING btree ("approval_id");--> statement-breakpoint
+CREATE INDEX "approval_comments_approval_created_idx" ON "approval_comments" USING btree ("approval_id","created_at");--> statement-breakpoint

paperclip-reference/packages/db/src/migrations/0006_overjoyed_mister_sinister.sql

@@ -0,0 +1,36 @@
+CREATE TABLE "agent_config_revisions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"source" text DEFAULT 'patch' NOT NULL,
+	"rolled_back_from_revision_id" uuid,
+	"changed_keys" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"before_config" jsonb NOT NULL,
+	"after_config" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "issue_approvals" (
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"approval_id" uuid NOT NULL,
+	"linked_by_agent_id" uuid,
+	"linked_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "issue_approvals_pk" PRIMARY KEY("issue_id","approval_id")
+);
+--> statement-breakpoint
+ALTER TABLE "agent_config_revisions" ADD CONSTRAINT "agent_config_revisions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_config_revisions" ADD CONSTRAINT "agent_config_revisions_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_config_revisions" ADD CONSTRAINT "agent_config_revisions_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_approvals" ADD CONSTRAINT "issue_approvals_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_approvals" ADD CONSTRAINT "issue_approvals_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_approvals" ADD CONSTRAINT "issue_approvals_approval_id_approvals_id_fk" FOREIGN KEY ("approval_id") REFERENCES "public"."approvals"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_approvals" ADD CONSTRAINT "issue_approvals_linked_by_agent_id_agents_id_fk" FOREIGN KEY ("linked_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "agent_config_revisions_company_agent_created_idx" ON "agent_config_revisions" USING btree ("company_id","agent_id","created_at");--> statement-breakpoint
+CREATE INDEX "agent_config_revisions_agent_created_idx" ON "agent_config_revisions" USING btree ("agent_id","created_at");--> statement-breakpoint
+CREATE INDEX "issue_approvals_issue_idx" ON "issue_approvals" USING btree ("issue_id");--> statement-breakpoint
+CREATE INDEX "issue_approvals_approval_idx" ON "issue_approvals" USING btree ("approval_id");--> statement-breakpoint
+CREATE INDEX "issue_approvals_company_idx" ON "issue_approvals" USING btree ("company_id");

paperclip-reference/packages/db/src/migrations/0007_new_quentin_quire.sql

@@ -0,0 +1,20 @@
+CREATE TABLE "agent_task_sessions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"adapter_type" text NOT NULL,
+	"task_key" text NOT NULL,
+	"session_params_json" jsonb,
+	"session_display_id" text,
+	"last_run_id" uuid,
+	"last_error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "agent_task_sessions" ADD CONSTRAINT "agent_task_sessions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_task_sessions" ADD CONSTRAINT "agent_task_sessions_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_task_sessions" ADD CONSTRAINT "agent_task_sessions_last_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("last_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "agent_task_sessions_company_agent_adapter_task_uniq" ON "agent_task_sessions" USING btree ("company_id","agent_id","adapter_type","task_key");--> statement-breakpoint
+CREATE INDEX "agent_task_sessions_company_agent_updated_idx" ON "agent_task_sessions" USING btree ("company_id","agent_id","updated_at");--> statement-breakpoint
+CREATE INDEX "agent_task_sessions_company_task_updated_idx" ON "agent_task_sessions" USING btree ("company_id","task_key","updated_at");

paperclip-reference/packages/db/src/migrations/0008_amused_zzzax.sql

@@ -0,0 +1 @@
+ALTER TABLE "issues" ADD COLUMN "hidden_at" timestamp with time zone;

paperclip-reference/packages/db/src/migrations/0009_fast_jackal.sql

@@ -0,0 +1,36 @@
+CREATE TABLE "company_secret_versions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"secret_id" uuid NOT NULL,
+	"version" integer NOT NULL,
+	"material" jsonb NOT NULL,
+	"value_sha256" text NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"revoked_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE "company_secrets" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"provider" text DEFAULT 'local_encrypted' NOT NULL,
+	"external_ref" text,
+	"latest_version" integer DEFAULT 1 NOT NULL,
+	"description" text,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "company_secret_versions" ADD CONSTRAINT "company_secret_versions_secret_id_company_secrets_id_fk" FOREIGN KEY ("secret_id") REFERENCES "public"."company_secrets"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "company_secret_versions" ADD CONSTRAINT "company_secret_versions_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "company_secrets" ADD CONSTRAINT "company_secrets_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "company_secrets" ADD CONSTRAINT "company_secrets_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "company_secret_versions_secret_idx" ON "company_secret_versions" USING btree ("secret_id","created_at");--> statement-breakpoint
+CREATE INDEX "company_secret_versions_value_sha256_idx" ON "company_secret_versions" USING btree ("value_sha256");--> statement-breakpoint
+CREATE UNIQUE INDEX "company_secret_versions_secret_version_uq" ON "company_secret_versions" USING btree ("secret_id","version");--> statement-breakpoint
+CREATE INDEX "company_secrets_company_idx" ON "company_secrets" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "company_secrets_company_provider_idx" ON "company_secrets" USING btree ("company_id","provider");--> statement-breakpoint
+CREATE UNIQUE INDEX "company_secrets_company_name_uq" ON "company_secrets" USING btree ("company_id","name");

paperclip-reference/packages/db/src/migrations/0010_stale_justin_hammer.sql

@@ -0,0 +1,37 @@
+CREATE TABLE "assets" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"provider" text NOT NULL,
+	"object_key" text NOT NULL,
+	"content_type" text NOT NULL,
+	"byte_size" integer NOT NULL,
+	"sha256" text NOT NULL,
+	"original_filename" text,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "issue_attachments" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"asset_id" uuid NOT NULL,
+	"issue_comment_id" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "assets" ADD CONSTRAINT "assets_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "assets" ADD CONSTRAINT "assets_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_attachments" ADD CONSTRAINT "issue_attachments_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_attachments" ADD CONSTRAINT "issue_attachments_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_attachments" ADD CONSTRAINT "issue_attachments_asset_id_assets_id_fk" FOREIGN KEY ("asset_id") REFERENCES "public"."assets"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_attachments" ADD CONSTRAINT "issue_attachments_issue_comment_id_issue_comments_id_fk" FOREIGN KEY ("issue_comment_id") REFERENCES "public"."issue_comments"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "assets_company_created_idx" ON "assets" USING btree ("company_id","created_at");--> statement-breakpoint
+CREATE INDEX "assets_company_provider_idx" ON "assets" USING btree ("company_id","provider");--> statement-breakpoint
+CREATE UNIQUE INDEX "assets_company_object_key_uq" ON "assets" USING btree ("company_id","object_key");--> statement-breakpoint
+CREATE INDEX "issue_attachments_company_issue_idx" ON "issue_attachments" USING btree ("company_id","issue_id");--> statement-breakpoint
+CREATE INDEX "issue_attachments_issue_comment_idx" ON "issue_attachments" USING btree ("issue_comment_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_attachments_asset_uq" ON "issue_attachments" USING btree ("asset_id");

paperclip-reference/packages/db/src/migrations/0011_windy_corsair.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "project_goals" (
+	"project_id" uuid NOT NULL,
+	"goal_id" uuid NOT NULL,
+	"company_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "project_goals_project_id_goal_id_pk" PRIMARY KEY("project_id","goal_id")
+);
+--> statement-breakpoint
+ALTER TABLE "project_goals" ADD CONSTRAINT "project_goals_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "project_goals" ADD CONSTRAINT "project_goals_goal_id_goals_id_fk" FOREIGN KEY ("goal_id") REFERENCES "public"."goals"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "project_goals" ADD CONSTRAINT "project_goals_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "project_goals_project_idx" ON "project_goals" USING btree ("project_id");--> statement-breakpoint
+CREATE INDEX "project_goals_goal_idx" ON "project_goals" USING btree ("goal_id");--> statement-breakpoint
+CREATE INDEX "project_goals_company_idx" ON "project_goals" USING btree ("company_id");--> statement-breakpoint
+INSERT INTO "project_goals" ("project_id", "goal_id", "company_id")
+SELECT "id", "goal_id", "company_id" FROM "projects" WHERE "goal_id" IS NOT NULL
+ON CONFLICT DO NOTHING;

paperclip-reference/packages/db/src/migrations/0012_perpetual_ser_duncan.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "issues" ADD COLUMN "checkout_run_id" uuid;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_checkout_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("checkout_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;

paperclip-reference/packages/db/src/migrations/0013_dashing_wasp.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "issues" ADD COLUMN "execution_run_id" uuid;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "execution_agent_name_key" text;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "execution_locked_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_execution_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("execution_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;

paperclip-reference/packages/db/src/migrations/0014_many_mikhail_rasputin.sql

@@ -0,0 +1,135 @@
+CREATE TABLE "account" (
+	"id" text PRIMARY KEY NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"id_token" text,
+	"access_token_expires_at" timestamp with time zone,
+	"refresh_token_expires_at" timestamp with time zone,
+	"scope" text,
+	"password" text,
+	"created_at" timestamp with time zone NOT NULL,
+	"updated_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "session" (
+	"id" text PRIMARY KEY NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"token" text NOT NULL,
+	"created_at" timestamp with time zone NOT NULL,
+	"updated_at" timestamp with time zone NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"user_id" text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "user" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean DEFAULT false NOT NULL,
+	"image" text,
+	"created_at" timestamp with time zone NOT NULL,
+	"updated_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "verification" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone,
+	"updated_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE "company_memberships" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"principal_type" text NOT NULL,
+	"principal_id" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"membership_role" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "instance_user_roles" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"role" text DEFAULT 'instance_admin' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "invites" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid,
+	"invite_type" text DEFAULT 'company_join' NOT NULL,
+	"token_hash" text NOT NULL,
+	"allowed_join_types" text DEFAULT 'both' NOT NULL,
+	"defaults_payload" jsonb,
+	"expires_at" timestamp with time zone NOT NULL,
+	"invited_by_user_id" text,
+	"revoked_at" timestamp with time zone,
+	"accepted_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "join_requests" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"invite_id" uuid NOT NULL,
+	"company_id" uuid NOT NULL,
+	"request_type" text NOT NULL,
+	"status" text DEFAULT 'pending_approval' NOT NULL,
+	"request_ip" text NOT NULL,
+	"requesting_user_id" text,
+	"request_email_snapshot" text,
+	"agent_name" text,
+	"adapter_type" text,
+	"capabilities" text,
+	"agent_defaults_payload" jsonb,
+	"created_agent_id" uuid,
+	"approved_by_user_id" text,
+	"approved_at" timestamp with time zone,
+	"rejected_by_user_id" text,
+	"rejected_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "principal_permission_grants" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"principal_type" text NOT NULL,
+	"principal_id" text NOT NULL,
+	"permission_key" text NOT NULL,
+	"scope" jsonb,
+	"granted_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "assignee_user_id" text;--> statement-breakpoint
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "company_memberships" ADD CONSTRAINT "company_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invites" ADD CONSTRAINT "invites_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "join_requests" ADD CONSTRAINT "join_requests_invite_id_invites_id_fk" FOREIGN KEY ("invite_id") REFERENCES "public"."invites"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "join_requests" ADD CONSTRAINT "join_requests_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "join_requests" ADD CONSTRAINT "join_requests_created_agent_id_agents_id_fk" FOREIGN KEY ("created_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "principal_permission_grants" ADD CONSTRAINT "principal_permission_grants_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "company_memberships_company_principal_unique_idx" ON "company_memberships" USING btree ("company_id","principal_type","principal_id");--> statement-breakpoint
+CREATE INDEX "company_memberships_principal_status_idx" ON "company_memberships" USING btree ("principal_type","principal_id","status");--> statement-breakpoint
+CREATE INDEX "company_memberships_company_status_idx" ON "company_memberships" USING btree ("company_id","status");--> statement-breakpoint
+CREATE UNIQUE INDEX "instance_user_roles_user_role_unique_idx" ON "instance_user_roles" USING btree ("user_id","role");--> statement-breakpoint
+CREATE INDEX "instance_user_roles_role_idx" ON "instance_user_roles" USING btree ("role");--> statement-breakpoint
+CREATE UNIQUE INDEX "invites_token_hash_unique_idx" ON "invites" USING btree ("token_hash");--> statement-breakpoint
+CREATE INDEX "invites_company_invite_state_idx" ON "invites" USING btree ("company_id","invite_type","revoked_at","expires_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "join_requests_invite_unique_idx" ON "join_requests" USING btree ("invite_id");--> statement-breakpoint
+CREATE INDEX "join_requests_company_status_type_created_idx" ON "join_requests" USING btree ("company_id","status","request_type","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "principal_permission_grants_unique_idx" ON "principal_permission_grants" USING btree ("company_id","principal_type","principal_id","permission_key");--> statement-breakpoint
+CREATE INDEX "principal_permission_grants_company_permission_idx" ON "principal_permission_grants" USING btree ("company_id","permission_key");--> statement-breakpoint
+CREATE INDEX "issues_company_assignee_user_status_idx" ON "issues" USING btree ("company_id","assignee_user_id","status");

paperclip-reference/packages/db/src/migrations/0015_project_color_archived.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "projects" ADD COLUMN "color" text;
+ALTER TABLE "projects" ADD COLUMN "archived_at" timestamp with time zone;

paperclip-reference/packages/db/src/migrations/0016_agent_icon.sql

@@ -0,0 +1 @@
+ALTER TABLE "agents" ADD COLUMN "icon" text;

paperclip-reference/packages/db/src/migrations/0017_tiresome_gabe_jones.sql

@@ -0,0 +1,51 @@
+DROP INDEX "issues_company_identifier_idx";--> statement-breakpoint
+
+-- Rebuild issue prefixes to be company-specific and globally unique.
+-- Base prefix is first 3 letters of company name (A-Z only), fallback "CMP".
+-- Duplicate bases receive deterministic letter suffixes: PAP, PAPA, PAPAA, ...
+WITH ranked_companies AS (
+  SELECT
+    c.id,
+    COALESCE(NULLIF(SUBSTRING(REGEXP_REPLACE(UPPER(c.name), '[^A-Z]', '', 'g') FROM 1 FOR 3), ''), 'CMP') AS base_prefix,
+    ROW_NUMBER() OVER (
+      PARTITION BY COALESCE(NULLIF(SUBSTRING(REGEXP_REPLACE(UPPER(c.name), '[^A-Z]', '', 'g') FROM 1 FOR 3), ''), 'CMP')
+      ORDER BY c.created_at, c.id
+    ) AS prefix_rank
+  FROM companies c
+)
+UPDATE companies c
+SET issue_prefix = CASE
+  WHEN ranked_companies.prefix_rank = 1 THEN ranked_companies.base_prefix
+  ELSE ranked_companies.base_prefix || REPEAT('A', (ranked_companies.prefix_rank - 1)::integer)
+END
+FROM ranked_companies
+WHERE c.id = ranked_companies.id;--> statement-breakpoint
+
+-- Reassign issue numbers sequentially per company to guarantee uniqueness.
+WITH numbered_issues AS (
+  SELECT
+    i.id,
+    ROW_NUMBER() OVER (PARTITION BY i.company_id ORDER BY i.created_at, i.id) AS issue_number
+  FROM issues i
+)
+UPDATE issues i
+SET issue_number = numbered_issues.issue_number
+FROM numbered_issues
+WHERE i.id = numbered_issues.id;--> statement-breakpoint
+
+-- Rebuild identifiers from normalized prefix + issue number.
+UPDATE issues i
+SET identifier = c.issue_prefix || '-' || i.issue_number
+FROM companies c
+WHERE c.id = i.company_id;--> statement-breakpoint
+
+-- Sync counters to the largest issue number currently assigned per company.
+UPDATE companies c
+SET issue_counter = COALESCE((
+  SELECT MAX(i.issue_number)
+  FROM issues i
+  WHERE i.company_id = c.id
+), 0);--> statement-breakpoint
+
+CREATE UNIQUE INDEX "companies_issue_prefix_idx" ON "companies" USING btree ("issue_prefix");--> statement-breakpoint
+CREATE UNIQUE INDEX "issues_identifier_idx" ON "issues" USING btree ("identifier");

paperclip-reference/packages/db/src/migrations/0018_flat_sleepwalker.sql

@@ -0,0 +1,26 @@
+CREATE TABLE "issue_labels" (
+	"issue_id" uuid NOT NULL,
+	"label_id" uuid NOT NULL,
+	"company_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "issue_labels_pk" PRIMARY KEY("issue_id","label_id")
+);
+--> statement-breakpoint
+CREATE TABLE "labels" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"color" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issue_labels" ADD CONSTRAINT "issue_labels_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_labels" ADD CONSTRAINT "issue_labels_label_id_labels_id_fk" FOREIGN KEY ("label_id") REFERENCES "public"."labels"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_labels" ADD CONSTRAINT "issue_labels_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "labels" ADD CONSTRAINT "labels_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issue_labels_issue_idx" ON "issue_labels" USING btree ("issue_id");--> statement-breakpoint
+CREATE INDEX "issue_labels_label_idx" ON "issue_labels" USING btree ("label_id");--> statement-breakpoint
+CREATE INDEX "issue_labels_company_idx" ON "issue_labels" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "labels_company_idx" ON "labels" USING btree ("company_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "labels_company_name_idx" ON "labels" USING btree ("company_id","name");

paperclip-reference/packages/db/src/migrations/0019_public_victor_mancha.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "project_workspaces" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"cwd" text NOT NULL,
+	"repo_url" text,
+	"repo_ref" text,
+	"metadata" jsonb,
+	"is_primary" boolean DEFAULT false NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD CONSTRAINT "project_workspaces_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD CONSTRAINT "project_workspaces_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "project_workspaces_company_project_idx" ON "project_workspaces" USING btree ("company_id","project_id");--> statement-breakpoint
+CREATE INDEX "project_workspaces_project_primary_idx" ON "project_workspaces" USING btree ("project_id","is_primary");

paperclip-reference/packages/db/src/migrations/0020_white_anita_blake.sql

@@ -0,0 +1 @@
+ALTER TABLE "project_workspaces" ALTER COLUMN "cwd" DROP NOT NULL;

paperclip-reference/packages/db/src/migrations/0021_chief_vindicator.sql

@@ -0,0 +1 @@
+ALTER TABLE "issues" ADD COLUMN "assignee_adapter_overrides" jsonb;

paperclip-reference/packages/db/src/migrations/0022_company_brand_color.sql

@@ -0,0 +1 @@
+ALTER TABLE "companies" ADD COLUMN "brand_color" text;

paperclip-reference/packages/db/src/migrations/0023_fair_lethal_legion.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "join_requests" ADD COLUMN "claim_secret_hash" text;--> statement-breakpoint
+ALTER TABLE "join_requests" ADD COLUMN "claim_secret_expires_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "join_requests" ADD COLUMN "claim_secret_consumed_at" timestamp with time zone;

paperclip-reference/packages/db/src/migrations/0024_far_beast.sql

@@ -0,0 +1,2 @@
+CREATE INDEX "issue_comments_company_issue_created_at_idx" ON "issue_comments" USING btree ("company_id","issue_id","created_at");--> statement-breakpoint
+CREATE INDEX "issue_comments_company_author_issue_created_at_idx" ON "issue_comments" USING btree ("company_id","author_user_id","issue_id","created_at");

paperclip-reference/packages/db/src/migrations/0025_nasty_salo.sql

@@ -0,0 +1,15 @@
+CREATE TABLE "issue_read_states" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"last_read_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issue_read_states" ADD CONSTRAINT "issue_read_states_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_read_states" ADD CONSTRAINT "issue_read_states_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issue_read_states_company_issue_idx" ON "issue_read_states" USING btree ("company_id","issue_id");--> statement-breakpoint
+CREATE INDEX "issue_read_states_company_user_idx" ON "issue_read_states" USING btree ("company_id","user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_read_states_company_issue_user_idx" ON "issue_read_states" USING btree ("company_id","issue_id","user_id");

paperclip-reference/packages/db/src/migrations/0026_lying_pete_wisdom.sql

@@ -0,0 +1,39 @@
+CREATE TABLE "workspace_runtime_services" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid,
+	"project_workspace_id" uuid,
+	"issue_id" uuid,
+	"scope_type" text NOT NULL,
+	"scope_id" text,
+	"service_name" text NOT NULL,
+	"status" text NOT NULL,
+	"lifecycle" text NOT NULL,
+	"reuse_key" text,
+	"command" text,
+	"cwd" text,
+	"port" integer,
+	"url" text,
+	"provider" text NOT NULL,
+	"provider_ref" text,
+	"owner_agent_id" uuid,
+	"started_by_run_id" uuid,
+	"last_used_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"started_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"stopped_at" timestamp with time zone,
+	"stop_policy" jsonb,
+	"health_status" text DEFAULT 'unknown' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_project_workspace_id_project_workspaces_id_fk" FOREIGN KEY ("project_workspace_id") REFERENCES "public"."project_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_started_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("started_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_workspace_status_idx" ON "workspace_runtime_services" USING btree ("company_id","project_workspace_id","status");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_project_status_idx" ON "workspace_runtime_services" USING btree ("company_id","project_id","status");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_run_idx" ON "workspace_runtime_services" USING btree ("started_by_run_id");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_updated_idx" ON "workspace_runtime_services" USING btree ("company_id","updated_at");

paperclip-reference/packages/db/src/migrations/0027_tranquil_tenebrous.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "issues" ADD COLUMN "execution_workspace_settings" jsonb;--> statement-breakpoint
+ALTER TABLE "projects" ADD COLUMN "execution_workspace_policy" jsonb;

paperclip-reference/packages/db/src/migrations/0028_harsh_goliath.sql

@@ -0,0 +1,54 @@
+CREATE TABLE "document_revisions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"document_id" uuid NOT NULL,
+	"revision_number" integer NOT NULL,
+	"body" text NOT NULL,
+	"change_summary" text,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "documents" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"title" text,
+	"format" text DEFAULT 'markdown' NOT NULL,
+	"latest_body" text NOT NULL,
+	"latest_revision_id" uuid,
+	"latest_revision_number" integer DEFAULT 1 NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"updated_by_agent_id" uuid,
+	"updated_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "issue_documents" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"document_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "document_revisions" ADD CONSTRAINT "document_revisions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_revisions" ADD CONSTRAINT "document_revisions_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_revisions" ADD CONSTRAINT "document_revisions_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "documents" ADD CONSTRAINT "documents_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "documents" ADD CONSTRAINT "documents_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "documents" ADD CONSTRAINT "documents_updated_by_agent_id_agents_id_fk" FOREIGN KEY ("updated_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_documents" ADD CONSTRAINT "issue_documents_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_documents" ADD CONSTRAINT "issue_documents_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_documents" ADD CONSTRAINT "issue_documents_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "document_revisions_document_revision_uq" ON "document_revisions" USING btree ("document_id","revision_number");--> statement-breakpoint
+CREATE INDEX "document_revisions_company_document_created_idx" ON "document_revisions" USING btree ("company_id","document_id","created_at");--> statement-breakpoint
+CREATE INDEX "documents_company_updated_idx" ON "documents" USING btree ("company_id","updated_at");--> statement-breakpoint
+CREATE INDEX "documents_company_created_idx" ON "documents" USING btree ("company_id","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_documents_company_issue_key_uq" ON "issue_documents" USING btree ("company_id","issue_id","key");--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_documents_document_uq" ON "issue_documents" USING btree ("document_id");--> statement-breakpoint
+CREATE INDEX "issue_documents_company_issue_updated_idx" ON "issue_documents" USING btree ("company_id","issue_id","updated_at");

paperclip-reference/packages/db/src/migrations/0029_plugin_tables.sql

@@ -0,0 +1,177 @@
+-- Rollback:
+--   DROP INDEX IF EXISTS "plugin_logs_level_idx";
+--   DROP INDEX IF EXISTS "plugin_logs_plugin_time_idx";
+--   DROP INDEX IF EXISTS "plugin_company_settings_company_plugin_uq";
+--   DROP INDEX IF EXISTS "plugin_company_settings_plugin_idx";
+--   DROP INDEX IF EXISTS "plugin_company_settings_company_idx";
+--   DROP INDEX IF EXISTS "plugin_webhook_deliveries_key_idx";
+--   DROP INDEX IF EXISTS "plugin_webhook_deliveries_status_idx";
+--   DROP INDEX IF EXISTS "plugin_webhook_deliveries_plugin_idx";
+--   DROP INDEX IF EXISTS "plugin_job_runs_status_idx";
+--   DROP INDEX IF EXISTS "plugin_job_runs_plugin_idx";
+--   DROP INDEX IF EXISTS "plugin_job_runs_job_idx";
+--   DROP INDEX IF EXISTS "plugin_jobs_unique_idx";
+--   DROP INDEX IF EXISTS "plugin_jobs_next_run_idx";
+--   DROP INDEX IF EXISTS "plugin_jobs_plugin_idx";
+--   DROP INDEX IF EXISTS "plugin_entities_external_idx";
+--   DROP INDEX IF EXISTS "plugin_entities_scope_idx";
+--   DROP INDEX IF EXISTS "plugin_entities_type_idx";
+--   DROP INDEX IF EXISTS "plugin_entities_plugin_idx";
+--   DROP INDEX IF EXISTS "plugin_state_plugin_scope_idx";
+--   DROP INDEX IF EXISTS "plugin_config_plugin_id_idx";
+--   DROP INDEX IF EXISTS "plugins_status_idx";
+--   DROP INDEX IF EXISTS "plugins_plugin_key_idx";
+--   DROP TABLE IF EXISTS "plugin_logs";
+--   DROP TABLE IF EXISTS "plugin_company_settings";
+--   DROP TABLE IF EXISTS "plugin_webhook_deliveries";
+--   DROP TABLE IF EXISTS "plugin_job_runs";
+--   DROP TABLE IF EXISTS "plugin_jobs";
+--   DROP TABLE IF EXISTS "plugin_entities";
+--   DROP TABLE IF EXISTS "plugin_state";
+--   DROP TABLE IF EXISTS "plugin_config";
+--   DROP TABLE IF EXISTS "plugins";
+
+CREATE TABLE "plugins" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plugin_key" text NOT NULL,
+	"package_name" text NOT NULL,
+	"package_path" text,
+	"version" text NOT NULL,
+	"api_version" integer DEFAULT 1 NOT NULL,
+	"categories" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"manifest_json" jsonb NOT NULL,
+	"status" text DEFAULT 'installed' NOT NULL,
+	"install_order" integer,
+	"last_error" text,
+	"installed_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_config" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"config_json" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"last_error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_state" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"scope_kind" text NOT NULL,
+	"scope_id" text,
+	"namespace" text DEFAULT 'default' NOT NULL,
+	"state_key" text NOT NULL,
+	"value_json" jsonb NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "plugin_state_unique_entry_idx" UNIQUE NULLS NOT DISTINCT("plugin_id","scope_kind","scope_id","namespace","state_key")
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_entities" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"entity_type" text NOT NULL,
+	"scope_kind" text NOT NULL,
+	"scope_id" text,
+	"external_id" text,
+	"title" text,
+	"status" text,
+	"data" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_jobs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"job_key" text NOT NULL,
+	"schedule" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"last_run_at" timestamp with time zone,
+	"next_run_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_job_runs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"job_id" uuid NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"trigger" text NOT NULL,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"duration_ms" integer,
+	"error" text,
+	"logs" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"started_at" timestamp with time zone,
+	"finished_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_webhook_deliveries" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"webhook_key" text NOT NULL,
+	"external_id" text,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"duration_ms" integer,
+	"error" text,
+	"payload" jsonb NOT NULL,
+	"headers" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"started_at" timestamp with time zone,
+	"finished_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_company_settings" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"plugin_id" uuid NOT NULL,
+	"settings_json" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"last_error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_logs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+	"plugin_id" uuid NOT NULL,
+	"level" text NOT NULL DEFAULT 'info',
+	"message" text NOT NULL,
+	"meta" jsonb,
+	"created_at" timestamp with time zone NOT NULL DEFAULT now()
+);
+--> statement-breakpoint
+ALTER TABLE "plugin_config" ADD CONSTRAINT "plugin_config_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_state" ADD CONSTRAINT "plugin_state_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_entities" ADD CONSTRAINT "plugin_entities_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_jobs" ADD CONSTRAINT "plugin_jobs_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_job_runs" ADD CONSTRAINT "plugin_job_runs_job_id_plugin_jobs_id_fk" FOREIGN KEY ("job_id") REFERENCES "public"."plugin_jobs"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_job_runs" ADD CONSTRAINT "plugin_job_runs_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_webhook_deliveries" ADD CONSTRAINT "plugin_webhook_deliveries_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_company_settings" ADD CONSTRAINT "plugin_company_settings_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_company_settings" ADD CONSTRAINT "plugin_company_settings_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_logs" ADD CONSTRAINT "plugin_logs_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "plugins_plugin_key_idx" ON "plugins" USING btree ("plugin_key");--> statement-breakpoint
+CREATE INDEX "plugins_status_idx" ON "plugins" USING btree ("status");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_config_plugin_id_idx" ON "plugin_config" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_state_plugin_scope_idx" ON "plugin_state" USING btree ("plugin_id","scope_kind");--> statement-breakpoint
+CREATE INDEX "plugin_entities_plugin_idx" ON "plugin_entities" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_entities_type_idx" ON "plugin_entities" USING btree ("entity_type");--> statement-breakpoint
+CREATE INDEX "plugin_entities_scope_idx" ON "plugin_entities" USING btree ("scope_kind","scope_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_entities_external_idx" ON "plugin_entities" USING btree ("plugin_id","entity_type","external_id");--> statement-breakpoint
+CREATE INDEX "plugin_jobs_plugin_idx" ON "plugin_jobs" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_jobs_next_run_idx" ON "plugin_jobs" USING btree ("next_run_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_jobs_unique_idx" ON "plugin_jobs" USING btree ("plugin_id","job_key");--> statement-breakpoint
+CREATE INDEX "plugin_job_runs_job_idx" ON "plugin_job_runs" USING btree ("job_id");--> statement-breakpoint
+CREATE INDEX "plugin_job_runs_plugin_idx" ON "plugin_job_runs" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_job_runs_status_idx" ON "plugin_job_runs" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "plugin_webhook_deliveries_plugin_idx" ON "plugin_webhook_deliveries" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_webhook_deliveries_status_idx" ON "plugin_webhook_deliveries" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "plugin_webhook_deliveries_key_idx" ON "plugin_webhook_deliveries" USING btree ("webhook_key");--> statement-breakpoint
+CREATE INDEX "plugin_company_settings_company_idx" ON "plugin_company_settings" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "plugin_company_settings_plugin_idx" ON "plugin_company_settings" USING btree ("plugin_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_company_settings_company_plugin_uq" ON "plugin_company_settings" USING btree ("company_id","plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_logs_plugin_time_idx" ON "plugin_logs" USING btree ("plugin_id","created_at");--> statement-breakpoint
+CREATE INDEX "plugin_logs_level_idx" ON "plugin_logs" USING btree ("level");

paperclip-reference/packages/db/src/migrations/0030_rich_magneto.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "company_logos" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"asset_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "company_logos" ADD CONSTRAINT "company_logos_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "company_logos" ADD CONSTRAINT "company_logos_asset_id_assets_id_fk" FOREIGN KEY ("asset_id") REFERENCES "public"."assets"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "company_logos_company_uq" ON "company_logos" USING btree ("company_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "company_logos_asset_uq" ON "company_logos" USING btree ("asset_id");

paperclip-reference/packages/db/src/migrations/0031_zippy_magma.sql

@@ -0,0 +1,51 @@
+CREATE TABLE "finance_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid,
+	"issue_id" uuid,
+	"project_id" uuid,
+	"goal_id" uuid,
+	"heartbeat_run_id" uuid,
+	"cost_event_id" uuid,
+	"billing_code" text,
+	"description" text,
+	"event_kind" text NOT NULL,
+	"direction" text DEFAULT 'debit' NOT NULL,
+	"biller" text NOT NULL,
+	"provider" text,
+	"execution_adapter_type" text,
+	"pricing_tier" text,
+	"region" text,
+	"model" text,
+	"quantity" integer,
+	"unit" text,
+	"amount_cents" integer NOT NULL,
+	"currency" text DEFAULT 'USD' NOT NULL,
+	"estimated" boolean DEFAULT false NOT NULL,
+	"external_invoice_id" text,
+	"metadata_json" jsonb,
+	"occurred_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "cost_events" ADD COLUMN "heartbeat_run_id" uuid;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD COLUMN "biller" text DEFAULT 'unknown' NOT NULL;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD COLUMN "billing_type" text DEFAULT 'unknown' NOT NULL;--> statement-breakpoint
+ALTER TABLE "cost_events" ADD COLUMN "cached_input_tokens" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_goal_id_goals_id_fk" FOREIGN KEY ("goal_id") REFERENCES "public"."goals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_heartbeat_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("heartbeat_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "finance_events" ADD CONSTRAINT "finance_events_cost_event_id_cost_events_id_fk" FOREIGN KEY ("cost_event_id") REFERENCES "public"."cost_events"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "finance_events_company_occurred_idx" ON "finance_events" USING btree ("company_id","occurred_at");--> statement-breakpoint
+CREATE INDEX "finance_events_company_biller_occurred_idx" ON "finance_events" USING btree ("company_id","biller","occurred_at");--> statement-breakpoint
+CREATE INDEX "finance_events_company_kind_occurred_idx" ON "finance_events" USING btree ("company_id","event_kind","occurred_at");--> statement-breakpoint
+CREATE INDEX "finance_events_company_direction_occurred_idx" ON "finance_events" USING btree ("company_id","direction","occurred_at");--> statement-breakpoint
+CREATE INDEX "finance_events_company_heartbeat_run_idx" ON "finance_events" USING btree ("company_id","heartbeat_run_id");--> statement-breakpoint
+CREATE INDEX "finance_events_company_cost_event_idx" ON "finance_events" USING btree ("company_id","cost_event_id");--> statement-breakpoint
+ALTER TABLE "cost_events" ADD CONSTRAINT "cost_events_heartbeat_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("heartbeat_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "cost_events_company_provider_occurred_idx" ON "cost_events" USING btree ("company_id","provider","occurred_at");--> statement-breakpoint
+CREATE INDEX "cost_events_company_biller_occurred_idx" ON "cost_events" USING btree ("company_id","biller","occurred_at");--> statement-breakpoint
+CREATE INDEX "cost_events_company_heartbeat_run_idx" ON "cost_events" USING btree ("company_id","heartbeat_run_id");

paperclip-reference/packages/db/src/migrations/0032_pretty_doctor_octopus.sql

@@ -0,0 +1,102 @@
+CREATE TABLE "budget_incidents" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"policy_id" uuid NOT NULL,
+	"scope_type" text NOT NULL,
+	"scope_id" uuid NOT NULL,
+	"metric" text NOT NULL,
+	"window_kind" text NOT NULL,
+	"window_start" timestamp with time zone NOT NULL,
+	"window_end" timestamp with time zone NOT NULL,
+	"threshold_type" text NOT NULL,
+	"amount_limit" integer NOT NULL,
+	"amount_observed" integer NOT NULL,
+	"status" text DEFAULT 'open' NOT NULL,
+	"approval_id" uuid,
+	"resolved_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "budget_policies" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"scope_type" text NOT NULL,
+	"scope_id" uuid NOT NULL,
+	"metric" text DEFAULT 'billed_cents' NOT NULL,
+	"window_kind" text NOT NULL,
+	"amount" integer DEFAULT 0 NOT NULL,
+	"warn_percent" integer DEFAULT 80 NOT NULL,
+	"hard_stop_enabled" boolean DEFAULT true NOT NULL,
+	"notify_enabled" boolean DEFAULT true NOT NULL,
+	"is_active" boolean DEFAULT true NOT NULL,
+	"created_by_user_id" text,
+	"updated_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "pause_reason" text;--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "paused_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "projects" ADD COLUMN "pause_reason" text;--> statement-breakpoint
+ALTER TABLE "projects" ADD COLUMN "paused_at" timestamp with time zone;--> statement-breakpoint
+INSERT INTO "budget_policies" (
+	"company_id",
+	"scope_type",
+	"scope_id",
+	"metric",
+	"window_kind",
+	"amount",
+	"warn_percent",
+	"hard_stop_enabled",
+	"notify_enabled",
+	"is_active"
+)
+SELECT
+	"id",
+	'company',
+	"id",
+	'billed_cents',
+	'calendar_month_utc',
+	"budget_monthly_cents",
+	80,
+	true,
+	true,
+	true
+FROM "companies"
+WHERE "budget_monthly_cents" > 0;--> statement-breakpoint
+INSERT INTO "budget_policies" (
+	"company_id",
+	"scope_type",
+	"scope_id",
+	"metric",
+	"window_kind",
+	"amount",
+	"warn_percent",
+	"hard_stop_enabled",
+	"notify_enabled",
+	"is_active"
+)
+SELECT
+	"company_id",
+	'agent',
+	"id",
+	'billed_cents',
+	'calendar_month_utc',
+	"budget_monthly_cents",
+	80,
+	true,
+	true,
+	true
+FROM "agents"
+WHERE "budget_monthly_cents" > 0;--> statement-breakpoint
+ALTER TABLE "budget_incidents" ADD CONSTRAINT "budget_incidents_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "budget_incidents" ADD CONSTRAINT "budget_incidents_policy_id_budget_policies_id_fk" FOREIGN KEY ("policy_id") REFERENCES "public"."budget_policies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "budget_incidents" ADD CONSTRAINT "budget_incidents_approval_id_approvals_id_fk" FOREIGN KEY ("approval_id") REFERENCES "public"."approvals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "budget_policies" ADD CONSTRAINT "budget_policies_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "budget_incidents_company_status_idx" ON "budget_incidents" USING btree ("company_id","status");--> statement-breakpoint
+CREATE INDEX "budget_incidents_company_scope_idx" ON "budget_incidents" USING btree ("company_id","scope_type","scope_id","status");--> statement-breakpoint
+CREATE UNIQUE INDEX "budget_incidents_policy_window_threshold_idx" ON "budget_incidents" USING btree ("policy_id","window_start","threshold_type");--> statement-breakpoint
+CREATE INDEX "budget_policies_company_scope_active_idx" ON "budget_policies" USING btree ("company_id","scope_type","scope_id","is_active");--> statement-breakpoint
+CREATE INDEX "budget_policies_company_window_idx" ON "budget_policies" USING btree ("company_id","window_kind","metric");--> statement-breakpoint
+CREATE UNIQUE INDEX "budget_policies_company_scope_metric_unique_idx" ON "budget_policies" USING btree ("company_id","scope_type","scope_id","metric","window_kind");

paperclip-reference/packages/db/src/migrations/0033_shiny_black_tarantula.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "companies" ADD COLUMN "pause_reason" text;--> statement-breakpoint
+ALTER TABLE "companies" ADD COLUMN "paused_at" timestamp with time zone;

paperclip-reference/packages/db/src/migrations/0034_fat_dormammu.sql

@@ -0,0 +1,2 @@
+DROP INDEX "budget_incidents_policy_window_threshold_idx";--> statement-breakpoint
+CREATE UNIQUE INDEX "budget_incidents_policy_window_threshold_idx" ON "budget_incidents" USING btree ("policy_id","window_start","threshold_type") WHERE "budget_incidents"."status" <> 'dismissed';

paperclip-reference/packages/db/src/migrations/0035_marvelous_satana.sql

@@ -0,0 +1,91 @@
+CREATE TABLE "execution_workspaces" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"project_workspace_id" uuid,
+	"source_issue_id" uuid,
+	"mode" text NOT NULL,
+	"strategy_type" text NOT NULL,
+	"name" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"cwd" text,
+	"repo_url" text,
+	"base_ref" text,
+	"branch_name" text,
+	"provider_type" text DEFAULT 'local_fs' NOT NULL,
+	"provider_ref" text,
+	"derived_from_execution_workspace_id" uuid,
+	"last_used_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"opened_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"closed_at" timestamp with time zone,
+	"cleanup_eligible_at" timestamp with time zone,
+	"cleanup_reason" text,
+	"metadata" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "issue_work_products" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid,
+	"issue_id" uuid NOT NULL,
+	"execution_workspace_id" uuid,
+	"runtime_service_id" uuid,
+	"type" text NOT NULL,
+	"provider" text NOT NULL,
+	"external_id" text,
+	"title" text NOT NULL,
+	"url" text,
+	"status" text NOT NULL,
+	"review_state" text DEFAULT 'none' NOT NULL,
+	"is_primary" boolean DEFAULT false NOT NULL,
+	"health_status" text DEFAULT 'unknown' NOT NULL,
+	"summary" text,
+	"metadata" jsonb,
+	"created_by_run_id" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "project_workspace_id" uuid;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "execution_workspace_id" uuid;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN "execution_workspace_preference" text;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "source_type" text DEFAULT 'local_path' NOT NULL;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "default_ref" text;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "visibility" text DEFAULT 'default' NOT NULL;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "setup_command" text;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "cleanup_command" text;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "remote_provider" text;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "remote_workspace_ref" text;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD COLUMN "shared_workspace_key" text;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD COLUMN "execution_workspace_id" uuid;--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_project_workspace_id_project_workspaces_id_fk" FOREIGN KEY ("project_workspace_id") REFERENCES "public"."project_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_derived_from_execution_workspace_id_execution_workspaces_id_fk" FOREIGN KEY ("derived_from_execution_workspace_id") REFERENCES "public"."execution_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_work_products" ADD CONSTRAINT "issue_work_products_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_work_products" ADD CONSTRAINT "issue_work_products_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_work_products" ADD CONSTRAINT "issue_work_products_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_work_products" ADD CONSTRAINT "issue_work_products_execution_workspace_id_execution_workspaces_id_fk" FOREIGN KEY ("execution_workspace_id") REFERENCES "public"."execution_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_work_products" ADD CONSTRAINT "issue_work_products_runtime_service_id_workspace_runtime_services_id_fk" FOREIGN KEY ("runtime_service_id") REFERENCES "public"."workspace_runtime_services"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_work_products" ADD CONSTRAINT "issue_work_products_created_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("created_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "execution_workspaces_company_project_status_idx" ON "execution_workspaces" USING btree ("company_id","project_id","status");--> statement-breakpoint
+CREATE INDEX "execution_workspaces_company_project_workspace_status_idx" ON "execution_workspaces" USING btree ("company_id","project_workspace_id","status");--> statement-breakpoint
+CREATE INDEX "execution_workspaces_company_source_issue_idx" ON "execution_workspaces" USING btree ("company_id","source_issue_id");--> statement-breakpoint
+CREATE INDEX "execution_workspaces_company_last_used_idx" ON "execution_workspaces" USING btree ("company_id","last_used_at");--> statement-breakpoint
+CREATE INDEX "execution_workspaces_company_branch_idx" ON "execution_workspaces" USING btree ("company_id","branch_name");--> statement-breakpoint
+CREATE INDEX "issue_work_products_company_issue_type_idx" ON "issue_work_products" USING btree ("company_id","issue_id","type");--> statement-breakpoint
+CREATE INDEX "issue_work_products_company_execution_workspace_type_idx" ON "issue_work_products" USING btree ("company_id","execution_workspace_id","type");--> statement-breakpoint
+CREATE INDEX "issue_work_products_company_provider_external_id_idx" ON "issue_work_products" USING btree ("company_id","provider","external_id");--> statement-breakpoint
+CREATE INDEX "issue_work_products_company_updated_idx" ON "issue_work_products" USING btree ("company_id","updated_at");--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_project_workspace_id_project_workspaces_id_fk" FOREIGN KEY ("project_workspace_id") REFERENCES "public"."project_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issues" ADD CONSTRAINT "issues_execution_workspace_id_execution_workspaces_id_fk" FOREIGN KEY ("execution_workspace_id") REFERENCES "public"."execution_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_execution_workspace_id_execution_workspaces_id_fk" FOREIGN KEY ("execution_workspace_id") REFERENCES "public"."execution_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issues_company_project_workspace_idx" ON "issues" USING btree ("company_id","project_workspace_id");--> statement-breakpoint
+CREATE INDEX "issues_company_execution_workspace_idx" ON "issues" USING btree ("company_id","execution_workspace_id");--> statement-breakpoint
+CREATE INDEX "project_workspaces_project_source_type_idx" ON "project_workspaces" USING btree ("project_id","source_type");--> statement-breakpoint
+CREATE INDEX "project_workspaces_company_shared_key_idx" ON "project_workspaces" USING btree ("company_id","shared_workspace_key");--> statement-breakpoint
+CREATE UNIQUE INDEX "project_workspaces_project_remote_ref_idx" ON "project_workspaces" USING btree ("project_id","remote_provider","remote_workspace_ref");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_execution_workspace_status_idx" ON "workspace_runtime_services" USING btree ("company_id","execution_workspace_id","status");

paperclip-reference/packages/db/src/migrations/0036_cheerful_nitro.sql

@@ -0,0 +1,9 @@
+CREATE TABLE "instance_settings" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"singleton_key" text DEFAULT 'default' NOT NULL,
+	"experimental" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "instance_settings_singleton_key_idx" ON "instance_settings" USING btree ("singleton_key");

paperclip-reference/packages/db/src/migrations/0037_friendly_eddie_brock.sql

@@ -0,0 +1,29 @@
+CREATE TABLE "workspace_operations" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"execution_workspace_id" uuid,
+	"heartbeat_run_id" uuid,
+	"phase" text NOT NULL,
+	"command" text,
+	"cwd" text,
+	"status" text DEFAULT 'running' NOT NULL,
+	"exit_code" integer,
+	"log_store" text,
+	"log_ref" text,
+	"log_bytes" bigint,
+	"log_sha256" text,
+	"log_compressed" boolean DEFAULT false NOT NULL,
+	"stdout_excerpt" text,
+	"stderr_excerpt" text,
+	"metadata" jsonb,
+	"started_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"finished_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "workspace_operations" ADD CONSTRAINT "workspace_operations_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_operations" ADD CONSTRAINT "workspace_operations_execution_workspace_id_execution_workspaces_id_fk" FOREIGN KEY ("execution_workspace_id") REFERENCES "public"."execution_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_operations" ADD CONSTRAINT "workspace_operations_heartbeat_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("heartbeat_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "workspace_operations_company_run_started_idx" ON "workspace_operations" USING btree ("company_id","heartbeat_run_id","started_at");--> statement-breakpoint
+CREATE INDEX "workspace_operations_company_workspace_started_idx" ON "workspace_operations" USING btree ("company_id","execution_workspace_id","started_at");

paperclip-reference/packages/db/src/migrations/0038_careless_iron_monger.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "heartbeat_runs" ADD COLUMN "process_pid" integer;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "process_started_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "retry_of_run_id" uuid;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN "process_loss_retry_count" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD CONSTRAINT "heartbeat_runs_retry_of_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("retry_of_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;

paperclip-reference/packages/db/src/migrations/0039_fat_magneto.sql

@@ -0,0 +1,161 @@
+CREATE TABLE IF NOT EXISTS "routine_runs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"routine_id" uuid NOT NULL,
+	"trigger_id" uuid,
+	"source" text NOT NULL,
+	"status" text DEFAULT 'received' NOT NULL,
+	"triggered_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"idempotency_key" text,
+	"trigger_payload" jsonb,
+	"linked_issue_id" uuid,
+	"coalesced_into_run_id" uuid,
+	"failure_reason" text,
+	"completed_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "routine_triggers" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"routine_id" uuid NOT NULL,
+	"kind" text NOT NULL,
+	"label" text,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"cron_expression" text,
+	"timezone" text,
+	"next_run_at" timestamp with time zone,
+	"last_fired_at" timestamp with time zone,
+	"public_id" text,
+	"secret_id" uuid,
+	"signing_mode" text,
+	"replay_window_sec" integer,
+	"last_rotated_at" timestamp with time zone,
+	"last_result" text,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"updated_by_agent_id" uuid,
+	"updated_by_user_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "routines" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"goal_id" uuid,
+	"parent_issue_id" uuid,
+	"title" text NOT NULL,
+	"description" text,
+	"assignee_agent_id" uuid NOT NULL,
+	"priority" text DEFAULT 'medium' NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"concurrency_policy" text DEFAULT 'coalesce_if_active' NOT NULL,
+	"catch_up_policy" text DEFAULT 'skip_missed' NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"updated_by_agent_id" uuid,
+	"updated_by_user_id" text,
+	"last_triggered_at" timestamp with time zone,
+	"last_enqueued_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN IF NOT EXISTS "origin_kind" text DEFAULT 'manual' NOT NULL;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN IF NOT EXISTS "origin_id" text;--> statement-breakpoint
+ALTER TABLE "issues" ADD COLUMN IF NOT EXISTS "origin_run_id" text;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_runs_company_id_companies_id_fk') THEN
+  ALTER TABLE "routine_runs" ADD CONSTRAINT "routine_runs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_runs_routine_id_routines_id_fk') THEN
+  ALTER TABLE "routine_runs" ADD CONSTRAINT "routine_runs_routine_id_routines_id_fk" FOREIGN KEY ("routine_id") REFERENCES "public"."routines"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_runs_trigger_id_routine_triggers_id_fk') THEN
+  ALTER TABLE "routine_runs" ADD CONSTRAINT "routine_runs_trigger_id_routine_triggers_id_fk" FOREIGN KEY ("trigger_id") REFERENCES "public"."routine_triggers"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_runs_linked_issue_id_issues_id_fk') THEN
+  ALTER TABLE "routine_runs" ADD CONSTRAINT "routine_runs_linked_issue_id_issues_id_fk" FOREIGN KEY ("linked_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_triggers_company_id_companies_id_fk') THEN
+  ALTER TABLE "routine_triggers" ADD CONSTRAINT "routine_triggers_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_triggers_routine_id_routines_id_fk') THEN
+  ALTER TABLE "routine_triggers" ADD CONSTRAINT "routine_triggers_routine_id_routines_id_fk" FOREIGN KEY ("routine_id") REFERENCES "public"."routines"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_triggers_secret_id_company_secrets_id_fk') THEN
+  ALTER TABLE "routine_triggers" ADD CONSTRAINT "routine_triggers_secret_id_company_secrets_id_fk" FOREIGN KEY ("secret_id") REFERENCES "public"."company_secrets"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_triggers_created_by_agent_id_agents_id_fk') THEN
+  ALTER TABLE "routine_triggers" ADD CONSTRAINT "routine_triggers_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_triggers_updated_by_agent_id_agents_id_fk') THEN
+  ALTER TABLE "routine_triggers" ADD CONSTRAINT "routine_triggers_updated_by_agent_id_agents_id_fk" FOREIGN KEY ("updated_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_company_id_companies_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_project_id_projects_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_goal_id_goals_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_goal_id_goals_id_fk" FOREIGN KEY ("goal_id") REFERENCES "public"."goals"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_parent_issue_id_issues_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_parent_issue_id_issues_id_fk" FOREIGN KEY ("parent_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_assignee_agent_id_agents_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_assignee_agent_id_agents_id_fk" FOREIGN KEY ("assignee_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_created_by_agent_id_agents_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routines_updated_by_agent_id_agents_id_fk') THEN
+  ALTER TABLE "routines" ADD CONSTRAINT "routines_updated_by_agent_id_agents_id_fk" FOREIGN KEY ("updated_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_runs_company_routine_idx" ON "routine_runs" USING btree ("company_id","routine_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_runs_trigger_idx" ON "routine_runs" USING btree ("trigger_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_runs_linked_issue_idx" ON "routine_runs" USING btree ("linked_issue_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_runs_trigger_idempotency_idx" ON "routine_runs" USING btree ("trigger_id","idempotency_key");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_triggers_company_routine_idx" ON "routine_triggers" USING btree ("company_id","routine_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_triggers_company_kind_idx" ON "routine_triggers" USING btree ("company_id","kind");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_triggers_next_run_idx" ON "routine_triggers" USING btree ("next_run_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_triggers_public_id_idx" ON "routine_triggers" USING btree ("public_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routines_company_status_idx" ON "routines" USING btree ("company_id","status");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routines_company_assignee_idx" ON "routines" USING btree ("company_id","assignee_agent_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routines_company_project_idx" ON "routines" USING btree ("company_id","project_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issues_company_origin_idx" ON "issues" USING btree ("company_id","origin_kind","origin_id");

paperclip-reference/packages/db/src/migrations/0040_eager_shotgun.sql

@@ -0,0 +1,5 @@
+CREATE UNIQUE INDEX IF NOT EXISTS "issues_open_routine_execution_uq" ON "issues" USING btree ("company_id","origin_kind","origin_id") WHERE "issues"."origin_kind" = 'routine_execution'
+          and "issues"."origin_id" is not null
+          and "issues"."hidden_at" is null
+          and "issues"."status" in ('backlog', 'todo', 'in_progress', 'in_review', 'blocked');--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "routine_triggers_public_id_uq" ON "routine_triggers" USING btree ("public_id");

paperclip-reference/packages/db/src/migrations/0041_curly_maria_hill.sql

@@ -0,0 +1 @@
+ALTER TABLE "instance_settings" ADD COLUMN IF NOT EXISTS "general" jsonb DEFAULT '{}'::jsonb NOT NULL;

paperclip-reference/packages/db/src/migrations/0042_spotty_the_renegades.sql

@@ -0,0 +1,26 @@
+CREATE TABLE IF NOT EXISTS "company_skills" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"slug" text NOT NULL,
+	"name" text NOT NULL,
+	"description" text,
+	"markdown" text NOT NULL,
+	"source_type" text DEFAULT 'local_path' NOT NULL,
+	"source_locator" text,
+	"source_ref" text,
+	"trust_level" text DEFAULT 'markdown_only' NOT NULL,
+	"compatibility" text DEFAULT 'compatible' NOT NULL,
+	"file_inventory" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"metadata" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'company_skills_company_id_companies_id_fk') THEN
+  ALTER TABLE "company_skills" ADD CONSTRAINT "company_skills_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "company_skills_company_key_idx" ON "company_skills" USING btree ("company_id","key");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "company_skills_company_name_idx" ON "company_skills" USING btree ("company_id","name");

paperclip-reference/packages/db/src/migrations/0043_reflective_captain_universe.sql

@@ -0,0 +1,6 @@
+DROP INDEX IF EXISTS "issues_open_routine_execution_uq";--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "issues_open_routine_execution_uq" ON "issues" USING btree ("company_id","origin_kind","origin_id") WHERE "issues"."origin_kind" = 'routine_execution'
+          and "issues"."origin_id" is not null
+          and "issues"."hidden_at" is null
+          and "issues"."execution_run_id" is not null
+          and "issues"."status" in ('backlog', 'todo', 'in_progress', 'in_review', 'blocked');

paperclip-reference/packages/db/src/migrations/0044_illegal_toad.sql

@@ -0,0 +1,56 @@
+CREATE TABLE IF NOT EXISTS "board_api_keys" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"name" text NOT NULL,
+	"key_hash" text NOT NULL,
+	"last_used_at" timestamp with time zone,
+	"revoked_at" timestamp with time zone,
+	"expires_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "cli_auth_challenges" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"secret_hash" text NOT NULL,
+	"command" text NOT NULL,
+	"client_name" text,
+	"requested_access" text DEFAULT 'board' NOT NULL,
+	"requested_company_id" uuid,
+	"pending_key_hash" text NOT NULL,
+	"pending_key_name" text NOT NULL,
+	"approved_by_user_id" text,
+	"board_api_key_id" uuid,
+	"approved_at" timestamp with time zone,
+	"cancelled_at" timestamp with time zone,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "instance_settings" ADD COLUMN IF NOT EXISTS "general" jsonb DEFAULT '{}'::jsonb NOT NULL;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'board_api_keys_user_id_user_id_fk') THEN
+  ALTER TABLE "board_api_keys" ADD CONSTRAINT "board_api_keys_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'cli_auth_challenges_requested_company_id_companies_id_fk') THEN
+  ALTER TABLE "cli_auth_challenges" ADD CONSTRAINT "cli_auth_challenges_requested_company_id_companies_id_fk" FOREIGN KEY ("requested_company_id") REFERENCES "public"."companies"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'cli_auth_challenges_approved_by_user_id_user_id_fk') THEN
+  ALTER TABLE "cli_auth_challenges" ADD CONSTRAINT "cli_auth_challenges_approved_by_user_id_user_id_fk" FOREIGN KEY ("approved_by_user_id") REFERENCES "public"."user"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'cli_auth_challenges_board_api_key_id_board_api_keys_id_fk') THEN
+  ALTER TABLE "cli_auth_challenges" ADD CONSTRAINT "cli_auth_challenges_board_api_key_id_board_api_keys_id_fk" FOREIGN KEY ("board_api_key_id") REFERENCES "public"."board_api_keys"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DROP INDEX IF EXISTS "board_api_keys_key_hash_idx";--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "board_api_keys_key_hash_idx" ON "board_api_keys" USING btree ("key_hash");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "board_api_keys_user_idx" ON "board_api_keys" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "cli_auth_challenges_secret_hash_idx" ON "cli_auth_challenges" USING btree ("secret_hash");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "cli_auth_challenges_approved_by_idx" ON "cli_auth_challenges" USING btree ("approved_by_user_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "cli_auth_challenges_requested_company_idx" ON "cli_auth_challenges" USING btree ("requested_company_id");

paperclip-reference/packages/db/src/migrations/meta/_journal.json

@@ -0,0 +1,321 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1771300567463,
+      "tag": "0000_mature_masked_marvel",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1771349039633,
+      "tag": "0001_fast_northstar",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1771349403162,
+      "tag": "0002_big_zaladane",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1771456737635,
+      "tag": "0003_shallow_quentin_quire",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1771545600000,
+      "tag": "0004_issue_identifiers",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1771545601000,
+      "tag": "0005_chief_luke_cage",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1771545602000,
+      "tag": "0006_overjoyed_mister_sinister",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1771545603000,
+      "tag": "0007_new_quentin_quire",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1771534160426,
+      "tag": "0008_amused_zzzax",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1771534211029,
+      "tag": "0009_fast_jackal",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1771605173513,
+      "tag": "0010_stale_justin_hammer",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1771616419708,
+      "tag": "0011_windy_corsair",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1771619674673,
+      "tag": "0012_perpetual_ser_duncan",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1771623691139,
+      "tag": "0013_dashing_wasp",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1771691806349,
+      "tag": "0014_many_mikhail_rasputin",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1771865100000,
+      "tag": "0015_project_color_archived",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1771955900000,
+      "tag": "0016_agent_icon",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1771883888199,
+      "tag": "0017_tiresome_gabe_jones",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1771897769629,
+      "tag": "0018_flat_sleepwalker",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1772029333401,
+      "tag": "0019_public_victor_mancha",
+      "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1772032176413,
+      "tag": "0020_white_anita_blake",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1772122471656,
+      "tag": "0021_chief_vindicator",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1772186400000,
+      "tag": "0022_company_brand_color",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1772139727599,
+      "tag": "0023_fair_lethal_legion",
+      "breakpoints": true
+    },
+    {
+      "idx": 24,
+      "version": "7",
+      "when": 1772806603601,
+      "tag": "0024_far_beast",
+      "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1772807461603,
+      "tag": "0025_nasty_salo",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1773089625430,
+      "tag": "0026_lying_pete_wisdom",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1773150731736,
+      "tag": "0027_tranquil_tenebrous",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1773432085646,
+      "tag": "0028_harsh_goliath",
+      "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "7",
+      "when": 1773417600000,
+      "tag": "0029_plugin_tables",
+      "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1773670925214,
+      "tag": "0030_rich_magneto",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1773511922713,
+      "tag": "0031_zippy_magma",
+      "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "7",
+      "when": 1773542934499,
+      "tag": "0032_pretty_doctor_octopus",
+      "breakpoints": true
+    },
+    {
+      "idx": 33,
+      "version": "7",
+      "when": 1773664961967,
+      "tag": "0033_shiny_black_tarantula",
+      "breakpoints": true
+    },
+    {
+      "idx": 34,
+      "version": "7",
+      "when": 1773697572188,
+      "tag": "0034_fat_dormammu",
+      "breakpoints": true
+    },
+    {
+      "idx": 35,
+      "version": "7",
+      "when": 1773698696169,
+      "tag": "0035_marvelous_satana",
+      "breakpoints": true
+    },
+    {
+      "idx": 36,
+      "version": "7",
+      "when": 1773756213455,
+      "tag": "0036_cheerful_nitro",
+      "breakpoints": true
+    },
+    {
+      "idx": 37,
+      "version": "7",
+      "when": 1773756922363,
+      "tag": "0037_friendly_eddie_brock",
+      "breakpoints": true
+    },
+    {
+      "idx": 38,
+      "version": "7",
+      "when": 1773931592563,
+      "tag": "0038_careless_iron_monger",
+      "breakpoints": true
+    },
+    {
+      "idx": 39,
+      "version": "7",
+      "when": 1773926116580,
+      "tag": "0039_fat_magneto",
+      "breakpoints": true
+    },
+    {
+      "idx": 40,
+      "version": "7",
+      "when": 1773927102783,
+      "tag": "0040_eager_shotgun",
+      "breakpoints": true
+    },
+    {
+      "idx": 41,
+      "version": "7",
+      "when": 1774011294562,
+      "tag": "0041_curly_maria_hill",
+      "breakpoints": true
+    },
+    {
+      "idx": 42,
+      "version": "7",
+      "when": 1774031825634,
+      "tag": "0042_spotty_the_renegades",
+      "breakpoints": true
+    },
+    {
+      "idx": 43,
+      "version": "7",
+      "when": 1774008910991,
+      "tag": "0043_reflective_captain_universe",
+      "breakpoints": true
+    },
+    {
+      "idx": 44,
+      "version": "7",
+      "when": 1774269579794,
+      "tag": "0044_illegal_toad",
+      "breakpoints": true
+    }
+  ]
+}

paperclip-reference/packages/db/src/runtime-config.test.ts

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveDatabaseTarget } from "./runtime-config.js";
+
+const ORIGINAL_CWD = process.cwd();
+const ORIGINAL_ENV = { ...process.env };
+
+function writeJson(filePath: string, value: unknown) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function writeText(filePath: string, value: string) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, value);
+}
+
+afterEach(() => {
+  process.chdir(ORIGINAL_CWD);
+  for (const key of Object.keys(process.env)) {
+    if (!(key in ORIGINAL_ENV)) delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+describe("resolveDatabaseTarget", () => {
+  it("uses DATABASE_URL from process env first", () => {
+    process.env.DATABASE_URL = "postgres://env-user:env-pass@db.example.com:5432/paperclip";
+
+    const target = resolveDatabaseTarget();
+
+    expect(target).toMatchObject({
+      mode: "postgres",
+      connectionString: "postgres://env-user:env-pass@db.example.com:5432/paperclip",
+      source: "DATABASE_URL",
+    });
+  });
+
+  it("uses DATABASE_URL from repo-local .paperclip/.env", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-runtime-"));
+    const projectDir = path.join(tempDir, "repo");
+    fs.mkdirSync(projectDir, { recursive: true });
+    process.chdir(projectDir);
+    delete process.env.PAPERCLIP_CONFIG;
+    writeJson(path.join(projectDir, ".paperclip", "config.json"), {
+      database: { mode: "embedded-postgres", embeddedPostgresPort: 54329 },
+    });
+    writeText(
+      path.join(projectDir, ".paperclip", ".env"),
+      'DATABASE_URL="postgres://file-user:file-pass@db.example.com:6543/paperclip"\n',
+    );
+
+    const target = resolveDatabaseTarget();
+
+    expect(target).toMatchObject({
+      mode: "postgres",
+      connectionString: "postgres://file-user:file-pass@db.example.com:6543/paperclip",
+      source: "paperclip-env",
+    });
+  });
+
+  it("uses config postgres connection string when configured", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-runtime-"));
+    const configPath = path.join(tempDir, "instance", "config.json");
+    process.env.PAPERCLIP_CONFIG = configPath;
+    writeJson(configPath, {
+      database: {
+        mode: "postgres",
+        connectionString: "postgres://cfg-user:cfg-pass@db.example.com:5432/paperclip",
+      },
+    });
+
+    const target = resolveDatabaseTarget();
+
+    expect(target).toMatchObject({
+      mode: "postgres",
+      connectionString: "postgres://cfg-user:cfg-pass@db.example.com:5432/paperclip",
+      source: "config.database.connectionString",
+    });
+  });
+
+  it("falls back to embedded postgres settings from config", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-runtime-"));
+    const configPath = path.join(tempDir, "instance", "config.json");
+    process.env.PAPERCLIP_CONFIG = configPath;
+    writeJson(configPath, {
+      database: {
+        mode: "embedded-postgres",
+        embeddedPostgresDataDir: "~/paperclip-test-db",
+        embeddedPostgresPort: 55444,
+      },
+    });
+
+    const target = resolveDatabaseTarget();
+
+    expect(target).toMatchObject({
+      mode: "embedded-postgres",
+      dataDir: path.resolve(os.homedir(), "paperclip-test-db"),
+      port: 55444,
+      source: "embedded-postgres@55444",
+    });
+  });
+});

paperclip-reference/packages/db/src/runtime-config.ts

@@ -0,0 +1,267 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DEFAULT_INSTANCE_ID = "default";
+const CONFIG_BASENAME = "config.json";
+const ENV_BASENAME = ".env";
+const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+type PartialConfig = {
+  database?: {
+    mode?: "embedded-postgres" | "postgres";
+    connectionString?: string;
+    embeddedPostgresDataDir?: string;
+    embeddedPostgresPort?: number;
+    pgliteDataDir?: string;
+    pglitePort?: number;
+  };
+};
+
+export type ResolvedDatabaseTarget =
+  | {
+      mode: "postgres";
+      connectionString: string;
+      source: "DATABASE_URL" | "paperclip-env" | "config.database.connectionString";
+      configPath: string;
+      envPath: string;
+    }
+  | {
+      mode: "embedded-postgres";
+      dataDir: string;
+      port: number;
+      source: `embedded-postgres@${number}`;
+      configPath: string;
+      envPath: string;
+    };
+
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolvePaperclipHomeDir(): string {
+  const envHome = process.env.PAPERCLIP_HOME?.trim();
+  if (envHome) return path.resolve(expandHomePrefix(envHome));
+  return path.resolve(os.homedir(), ".paperclip");
+}
+
+function resolvePaperclipInstanceId(): string {
+  const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
+  if (!INSTANCE_ID_RE.test(raw)) {
+    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
+  }
+  return raw;
+}
+
+function resolveDefaultConfigPath(): string {
+  return path.resolve(
+    resolvePaperclipHomeDir(),
+    "instances",
+    resolvePaperclipInstanceId(),
+    CONFIG_BASENAME,
+  );
+}
+
+function resolveDefaultEmbeddedPostgresDir(): string {
+  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "db");
+}
+
+function resolveHomeAwarePath(value: string): string {
+  return path.resolve(expandHomePrefix(value));
+}
+
+function findConfigFileFromAncestors(startDir: string): string | null {
+  let currentDir = path.resolve(startDir);
+
+  while (true) {
+    const candidate = path.resolve(currentDir, ".paperclip", CONFIG_BASENAME);
+    if (existsSync(candidate)) return candidate;
+
+    const nextDir = path.resolve(currentDir, "..");
+    if (nextDir === currentDir) return null;
+    currentDir = nextDir;
+  }
+}
+
+function resolvePaperclipConfigPath(): string {
+  if (process.env.PAPERCLIP_CONFIG?.trim()) {
+    return path.resolve(process.env.PAPERCLIP_CONFIG.trim());
+  }
+  return findConfigFileFromAncestors(process.cwd()) ?? resolveDefaultConfigPath();
+}
+
+function resolvePaperclipEnvPath(configPath: string): string {
+  return path.resolve(path.dirname(configPath), ENV_BASENAME);
+}
+
+function parseEnvFile(contents: string): Record<string, string> {
+  const entries: Record<string, string> = {};
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+    if (!value) {
+      entries[key] = "";
+      continue;
+    }
+
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      entries[key] = value.slice(1, -1);
+      continue;
+    }
+
+    entries[key] = value.replace(/\s+#.*$/, "").trim();
+  }
+
+  return entries;
+}
+
+function readEnvEntries(envPath: string): Record<string, string> {
+  if (!existsSync(envPath)) return {};
+  return parseEnvFile(readFileSync(envPath, "utf8"));
+}
+
+function migrateLegacyConfig(raw: unknown): PartialConfig | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+
+  const config = { ...(raw as Record<string, unknown>) };
+  const databaseRaw = config.database;
+  if (typeof databaseRaw !== "object" || databaseRaw === null || Array.isArray(databaseRaw)) {
+    return config;
+  }
+
+  const database = { ...(databaseRaw as Record<string, unknown>) };
+  if (database.mode === "pglite") {
+    database.mode = "embedded-postgres";
+
+    if (
+      typeof database.embeddedPostgresDataDir !== "string" &&
+      typeof database.pgliteDataDir === "string"
+    ) {
+      database.embeddedPostgresDataDir = database.pgliteDataDir;
+    }
+    if (
+      typeof database.embeddedPostgresPort !== "number" &&
+      typeof database.pglitePort === "number" &&
+      Number.isFinite(database.pglitePort)
+    ) {
+      database.embeddedPostgresPort = database.pglitePort;
+    }
+  }
+
+  config.database = database;
+  return config as PartialConfig;
+}
+
+function asPositiveInt(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const rounded = Math.trunc(value);
+  return rounded > 0 ? rounded : null;
+}
+
+function readConfig(configPath: string): PartialConfig | null {
+  if (!existsSync(configPath)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Failed to parse config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const migrated = migrateLegacyConfig(parsed);
+  if (migrated === null || typeof migrated !== "object" || Array.isArray(migrated)) {
+    throw new Error(`Invalid config at ${configPath}: expected a JSON object`);
+  }
+
+  const database =
+    typeof migrated.database === "object" &&
+    migrated.database !== null &&
+    !Array.isArray(migrated.database)
+      ? migrated.database
+      : undefined;
+
+  return {
+    database: database
+      ? {
+          mode: database.mode === "postgres" ? "postgres" : "embedded-postgres",
+          connectionString:
+            typeof database.connectionString === "string" ? database.connectionString : undefined,
+          embeddedPostgresDataDir:
+            typeof database.embeddedPostgresDataDir === "string"
+              ? database.embeddedPostgresDataDir
+              : undefined,
+          embeddedPostgresPort: asPositiveInt(database.embeddedPostgresPort) ?? undefined,
+          pgliteDataDir: typeof database.pgliteDataDir === "string" ? database.pgliteDataDir : undefined,
+          pglitePort: asPositiveInt(database.pglitePort) ?? undefined,
+        }
+      : undefined,
+  };
+}
+
+export function resolveDatabaseTarget(): ResolvedDatabaseTarget {
+  const configPath = resolvePaperclipConfigPath();
+  const envPath = resolvePaperclipEnvPath(configPath);
+  const envEntries = readEnvEntries(envPath);
+
+  const envUrl = process.env.DATABASE_URL?.trim();
+  if (envUrl) {
+    return {
+      mode: "postgres",
+      connectionString: envUrl,
+      source: "DATABASE_URL",
+      configPath,
+      envPath,
+    };
+  }
+
+  const fileEnvUrl = envEntries.DATABASE_URL?.trim();
+  if (fileEnvUrl) {
+    return {
+      mode: "postgres",
+      connectionString: fileEnvUrl,
+      source: "paperclip-env",
+      configPath,
+      envPath,
+    };
+  }
+
+  const config = readConfig(configPath);
+  const connectionString = config?.database?.connectionString?.trim();
+  if (config?.database?.mode === "postgres" && connectionString) {
+    return {
+      mode: "postgres",
+      connectionString,
+      source: "config.database.connectionString",
+      configPath,
+      envPath,
+    };
+  }
+
+  const port = config?.database?.embeddedPostgresPort ?? 54329;
+  const dataDir = resolveHomeAwarePath(
+    config?.database?.embeddedPostgresDataDir ?? resolveDefaultEmbeddedPostgresDir(),
+  );
+
+  return {
+    mode: "embedded-postgres",
+    dataDir,
+    port,
+    source: `embedded-postgres@${port}`,
+    configPath,
+    envPath,
+  };
+}

paperclip-reference/packages/db/src/schema/activity_log.ts

@@ -0,0 +1,26 @@
+import { pgTable, uuid, text, timestamp, jsonb, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { agents } from "./agents.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+
+export const activityLog = pgTable(
+  "activity_log",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    actorType: text("actor_type").notNull().default("system"),
+    actorId: text("actor_id").notNull(),
+    action: text("action").notNull(),
+    entityType: text("entity_type").notNull(),
+    entityId: text("entity_id").notNull(),
+    agentId: uuid("agent_id").references(() => agents.id),
+    runId: uuid("run_id").references(() => heartbeatRuns.id),
+    details: jsonb("details").$type<Record<string, unknown>>(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyCreatedIdx: index("activity_log_company_created_idx").on(table.companyId, table.createdAt),
+    runIdIdx: index("activity_log_run_id_idx").on(table.runId),
+    entityIdx: index("activity_log_entity_type_id_idx").on(table.entityType, table.entityId),
+  }),
+);

paperclip-reference/packages/db/src/schema/agent_api_keys.ts

@@ -0,0 +1,21 @@
+import { pgTable, uuid, text, timestamp, index } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+
+export const agentApiKeys = pgTable(
+  "agent_api_keys",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    agentId: uuid("agent_id").notNull().references(() => agents.id),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    name: text("name").notNull(),
+    keyHash: text("key_hash").notNull(),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    keyHashIdx: index("agent_api_keys_key_hash_idx").on(table.keyHash),
+    companyAgentIdx: index("agent_api_keys_company_agent_idx").on(table.companyId, table.agentId),
+  }),
+);

paperclip-reference/packages/db/src/schema/agent_config_revisions.ts

@@ -0,0 +1,28 @@
+import { pgTable, uuid, text, timestamp, jsonb, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { agents } from "./agents.js";
+
+export const agentConfigRevisions = pgTable(
+  "agent_config_revisions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    agentId: uuid("agent_id").notNull().references(() => agents.id, { onDelete: "cascade" }),
+    createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    createdByUserId: text("created_by_user_id"),
+    source: text("source").notNull().default("patch"),
+    rolledBackFromRevisionId: uuid("rolled_back_from_revision_id"),
+    changedKeys: jsonb("changed_keys").$type<string[]>().notNull().default([]),
+    beforeConfig: jsonb("before_config").$type<Record<string, unknown>>().notNull(),
+    afterConfig: jsonb("after_config").$type<Record<string, unknown>>().notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyAgentCreatedIdx: index("agent_config_revisions_company_agent_created_idx").on(
+      table.companyId,
+      table.agentId,
+      table.createdAt,
+    ),
+    agentCreatedIdx: index("agent_config_revisions_agent_created_idx").on(table.agentId, table.createdAt),
+  }),
+);

paperclip-reference/packages/db/src/schema/agent_runtime_state.ts

@@ -0,0 +1,28 @@
+import { pgTable, uuid, text, timestamp, jsonb, bigint, index } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+
+export const agentRuntimeState = pgTable(
+  "agent_runtime_state",
+  {
+    agentId: uuid("agent_id").primaryKey().references(() => agents.id),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    adapterType: text("adapter_type").notNull(),
+    sessionId: text("session_id"),
+    stateJson: jsonb("state_json").$type<Record<string, unknown>>().notNull().default({}),
+    lastRunId: uuid("last_run_id"),
+    lastRunStatus: text("last_run_status"),
+    totalInputTokens: bigint("total_input_tokens", { mode: "number" }).notNull().default(0),
+    totalOutputTokens: bigint("total_output_tokens", { mode: "number" }).notNull().default(0),
+    totalCachedInputTokens: bigint("total_cached_input_tokens", { mode: "number" }).notNull().default(0),
+    totalCostCents: bigint("total_cost_cents", { mode: "number" }).notNull().default(0),
+    lastError: text("last_error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyAgentIdx: index("agent_runtime_state_company_agent_idx").on(table.companyId, table.agentId),
+    companyUpdatedIdx: index("agent_runtime_state_company_updated_idx").on(table.companyId, table.updatedAt),
+  }),
+);
+

paperclip-reference/packages/db/src/schema/agent_task_sessions.ts

@@ -0,0 +1,39 @@
+import { pgTable, uuid, text, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { agents } from "./agents.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+
+export const agentTaskSessions = pgTable(
+  "agent_task_sessions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    agentId: uuid("agent_id").notNull().references(() => agents.id),
+    adapterType: text("adapter_type").notNull(),
+    taskKey: text("task_key").notNull(),
+    sessionParamsJson: jsonb("session_params_json").$type<Record<string, unknown>>(),
+    sessionDisplayId: text("session_display_id"),
+    lastRunId: uuid("last_run_id").references(() => heartbeatRuns.id),
+    lastError: text("last_error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyAgentTaskUniqueIdx: uniqueIndex("agent_task_sessions_company_agent_adapter_task_uniq").on(
+      table.companyId,
+      table.agentId,
+      table.adapterType,
+      table.taskKey,
+    ),
+    companyAgentUpdatedIdx: index("agent_task_sessions_company_agent_updated_idx").on(
+      table.companyId,
+      table.agentId,
+      table.updatedAt,
+    ),
+    companyTaskUpdatedIdx: index("agent_task_sessions_company_task_updated_idx").on(
+      table.companyId,
+      table.taskKey,
+      table.updatedAt,
+    ),
+  }),
+);

paperclip-reference/packages/db/src/schema/agent_wakeup_requests.ts

@@ -0,0 +1,40 @@
+import { pgTable, uuid, text, timestamp, jsonb, integer, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { agents } from "./agents.js";
+
+export const agentWakeupRequests = pgTable(
+  "agent_wakeup_requests",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    agentId: uuid("agent_id").notNull().references(() => agents.id),
+    source: text("source").notNull(),
+    triggerDetail: text("trigger_detail"),
+    reason: text("reason"),
+    payload: jsonb("payload").$type<Record<string, unknown>>(),
+    status: text("status").notNull().default("queued"),
+    coalescedCount: integer("coalesced_count").notNull().default(0),
+    requestedByActorType: text("requested_by_actor_type"),
+    requestedByActorId: text("requested_by_actor_id"),
+    idempotencyKey: text("idempotency_key"),
+    runId: uuid("run_id"),
+    requestedAt: timestamp("requested_at", { withTimezone: true }).notNull().defaultNow(),
+    claimedAt: timestamp("claimed_at", { withTimezone: true }),
+    finishedAt: timestamp("finished_at", { withTimezone: true }),
+    error: text("error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyAgentStatusIdx: index("agent_wakeup_requests_company_agent_status_idx").on(
+      table.companyId,
+      table.agentId,
+      table.status,
+    ),
+    companyRequestedIdx: index("agent_wakeup_requests_company_requested_idx").on(
+      table.companyId,
+      table.requestedAt,
+    ),
+    agentRequestedIdx: index("agent_wakeup_requests_agent_requested_idx").on(table.agentId, table.requestedAt),
+  }),
+);