@preventive/triage 1.0.0-alpha.2 → 1.0.0-alpha.20

package/server-managed/db-neon.ts

@@ -0,0 +1,171 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { WebSocket } from 'ws'
+import { type ManagedDb, type ManagedDbOptions, createManagedMethods } from './db-methods.ts'
+import { MANAGED_SCHEMA } from './db-schema.ts'
+import { GITHUB_METADATA_SCHEMA, GITHUB_STATE_REASON_COLUMN } from './github-metadata.ts'
+import { COMMENT_SCHEMA } from './comments.ts'
+import { ACTIVITY_SCHEMA } from './activity.ts'
+import { type ManagedSqlDriver, scopeManagedMethods } from './sql.ts'
+import { postgresSchema, postgresSql } from './sql-postgres.ts'
+import { managedTableRenames } from './db-table-names.ts'
+import { WORKSPACE_SHARE_SCHEMA } from './workspace-shares.ts'
+import { allocateMissingSlugs } from './slugs.ts'
+
+export interface PgConnection {
+  query(sql: string, params?: unknown[]): Promise<{
+    rows: Record<string, unknown>[]; rowCount?: number | null
+    fields?: { name: string; dataTypeID: number }[]
+  }>
+  release(): Promise<void>
+}
+export type PgConnect = () => Promise<PgConnection>
+// All managed writers cooperate on this transaction-scoped lock. Reads use a
+// consistent snapshot without taking it. Also protects concurrent cold starts.
+const LOCK = 'SELECT pg_advisory_xact_lock(1937006964, 1835101793)'
+
+async function initialize(db: PgConnection): Promise<void> {
+  await db.query('BEGIN')
+  try {
+    await db.query(LOCK)
+    await db.query('CREATE TABLE IF NOT EXISTS managed_schema_version (version INTEGER PRIMARY KEY)')
+    const initialized = (await db.query('SELECT version FROM managed_schema_version WHERE version = 1')).rows.length > 0
+    const prefixed = (await db.query('SELECT version FROM managed_schema_version WHERE version = 3')).rows.length > 0
+    if (initialized && !prefixed) {
+      const { rows } = await db.query("SELECT relname AS name FROM pg_class WHERE relkind IN ('r', 'p') AND pg_table_is_visible(oid)")
+      for (const [from, to] of managedTableRenames(new Set(rows.map(row => String(row['name']))))) {
+        await db.query(`ALTER TABLE ${from} RENAME TO ${to}`)
+      }
+      // PL/pgSQL function bodies retain literal table names after ALTER TABLE.
+      for (const type of ['report', 'bundle']) await createUploadTrigger(db, type, false)
+    }
+    if (!initialized) {
+      await db.query(postgresSchema(MANAGED_SCHEMA + COMMENT_SCHEMA + ACTIVITY_SCHEMA))
+      await db.query(`ALTER TABLE managed_finding_triage_event ADD COLUMN report_id TEXT, ADD COLUMN report TEXT, ADD COLUMN repo TEXT;
+        CREATE UNIQUE INDEX managed_team_slug_idx ON managed_team(slug);
+        CREATE UNIQUE INDEX managed_report_slug_idx ON managed_report(slug);
+        CREATE INDEX managed_activity_actor_at_idx ON managed_activity(actor_id, at);`)
+      for (const type of ['report', 'bundle']) await createUploadTrigger(db, type)
+      await db.query('INSERT INTO managed_schema_version VALUES (1)')
+    }
+    if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 2')).rows.length === 0) {
+      await db.query('CREATE INDEX IF NOT EXISTS managed_report_bundle_hash_idx ON managed_report(bundle_id, sha256)')
+      await db.query('INSERT INTO managed_schema_version VALUES (2)')
+    }
+    if (!prefixed) await db.query('INSERT INTO managed_schema_version VALUES (3)')
+    if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 4')).rows.length === 0) {
+      await db.query(postgresSchema(WORKSPACE_SHARE_SCHEMA))
+      await db.query('INSERT INTO managed_schema_version VALUES (4)')
+    }
+    await db.query(postgresSchema(GITHUB_METADATA_SCHEMA))
+    await db.query(`ALTER TABLE managed_github_metadata ADD COLUMN IF NOT EXISTS state_reason ${GITHUB_STATE_REASON_COLUMN}`)
+    await db.query('ALTER TABLE managed_github_metadata ADD COLUMN IF NOT EXISTS attempted_at BIGINT')
+    if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 5')).rows.length === 0) {
+      await db.query(`ALTER TABLE managed_workspace_share ADD COLUMN IF NOT EXISTS dependencies INTEGER NOT NULL DEFAULT 0,
+        ADD COLUMN IF NOT EXISTS security INTEGER NOT NULL DEFAULT 0`)
+      await db.query('INSERT INTO managed_schema_version VALUES (5)')
+    }
+    if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 6')).rows.length === 0) {
+      await db.query('ALTER TABLE managed_bundle ADD COLUMN IF NOT EXISTS slug TEXT')
+      const { rows } = await db.query('SELECT id, slug FROM managed_bundle ORDER BY id')
+      for (const row of allocateMissingSlugs(rows as { id: string; slug: string | null }[])) {
+        await db.query('UPDATE managed_bundle SET slug = $1 WHERE id = $2', [row.slug, row.id])
+      }
+      await db.query(`ALTER TABLE managed_bundle ALTER COLUMN slug SET NOT NULL;
+        CREATE UNIQUE INDEX IF NOT EXISTS managed_bundle_slug_idx ON managed_bundle(slug);
+        INSERT INTO managed_schema_version VALUES (6)`)
+    }
+    if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 7')).rows.length === 0) {
+      await db.query("ALTER TABLE managed_bundle ADD COLUMN IF NOT EXISTS repo_directory TEXT NOT NULL DEFAULT ''")
+      await db.query('INSERT INTO managed_schema_version VALUES (7)')
+    }
+    await db.query('COMMIT')
+  } catch (err) {
+    await db.query('ROLLBACK')
+    throw err
+  }
+}
+
+async function createUploadTrigger(db: PgConnection, type: string, createTrigger = true): Promise<void> {
+  await db.query(`CREATE OR REPLACE FUNCTION managed_${type}_activity_insert() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      INSERT INTO managed_activity (id, kind, actor, action, repo, report_id, report, at, bundle_id, actor_id)
+      VALUES ('${type}-upload:' || NEW.id, 'upload',
+        COALESCE(NEW.uploaded_by_login, (SELECT login FROM managed_user WHERE id = NEW.uploaded_by)),
+        'uploaded a ${type}', (SELECT full_name FROM managed_selected_repo WHERE repo_id = NEW.repo_id),
+        ${type === 'report' ? 'NEW.id' : 'NULL'}, NEW.filename, NEW.uploaded_at,
+        ${type === 'bundle' ? 'NEW.id' : 'NULL'}, NEW.uploaded_by);
+      RETURN NEW;
+    END $$;`)
+  if (createTrigger) {
+    await db.query(`CREATE TRIGGER managed_${type}_activity AFTER INSERT ON managed_${type}
+      FOR EACH ROW EXECUTE FUNCTION managed_${type}_activity_insert();`)
+  }
+}
+
+// Exposed for parity tests against real PostgreSQL semantics via PGlite.
+export async function openPostgresManagedDb(connect: PgConnect, options: ManagedDbOptions = {}): Promise<ManagedDb> {
+  const initial = await connect()
+  try { await initialize(initial) } finally { await initial.release() }
+  const context = new AsyncLocalStorage<PgConnection>()
+  let closed = false
+  const driver: ManagedSqlDriver = {
+    prepare(source) {
+      const { sql, names } = postgresSql(source)
+      async function query(args: unknown[]) {
+        const db = context.getStore()
+        if (!db) throw new Error('Managed query outside transaction')
+        const values = names.length > 0 ? names.map(name => (args[0] as Record<string, unknown>)[name])
+          : args.length === 1 && typeof args[0] === 'object' && args[0] !== null ? [] : args
+        const result = await db.query(sql, values)
+        // Postgres int8 is returned as text by node-postgres/Neon. All store
+        // numbers are JS safe integers (timestamps, IDs, sizes and sequences).
+        for (const field of result.fields ?? []) {
+          if (field.dataTypeID !== 20) continue
+          for (const row of result.rows) {
+            if (row[field.name] == null) continue
+            const value = Number(row[field.name])
+            if (!Number.isSafeInteger(value)) throw new Error('Managed integer exceeds safe range')
+            row[field.name] = value
+          }
+        }
+        return result
+      }
+      return {
+        get: async (...args) => (await query(args)).rows[0],
+        all: async (...args) => (await query(args)).rows,
+        run: async (...args) => ({ changes: (await query(args)).rowCount ?? 0 }),
+      }
+    },
+    async scope(write, work) {
+      if (closed) throw new Error('Managed database is closed')
+      const db = await connect()
+      try {
+        await db.query(write ? 'BEGIN' : 'BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY')
+        if (write) await db.query(LOCK)
+        const result = await context.run(db, work)
+        await db.query('COMMIT')
+        return result
+      } catch (err) {
+        await db.query('ROLLBACK').catch(() => {})
+        throw err
+      } finally { await db.release() }
+    },
+    close() { closed = true },
+  }
+  return scopeManagedMethods(createManagedMethods(driver, options), driver)
+}
+
+export async function openNeonManagedDb(url: string, options: ManagedDbOptions = {}): Promise<ManagedDb> {
+  // Reuse the e2e optional-driver boundary. Each operation closes its socket
+  // before returning; no open connection has to survive a frozen invocation.
+  const { Client, neonConfig } = await import('../server-e2e/neon-driver.ts') as unknown as {
+    Client: new (url: string) => { connect(): Promise<void>; end(): Promise<void>; query: PgConnection['query'] }
+    neonConfig: { webSocketConstructor: typeof WebSocket }
+  }
+  neonConfig.webSocketConstructor = WebSocket
+  return openPostgresManagedDb(async () => {
+    const client = new Client(url)
+    try { await client.connect() } catch (err) { await client.end().catch(() => {}); throw err }
+    return { query: (sql, params) => client.query(sql, params), release: () => client.end() }
+  }, options)
+}

package/server-managed/db-schema.ts

@@ -0,0 +1,203 @@
+import { WORKSPACE_SHARE_SCHEMA } from './workspace-shares.ts'
+
+export const MANAGED_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_user (
+  id             TEXT PRIMARY KEY,
+  github_user_id INTEGER NOT NULL UNIQUE,
+  login          TEXT NOT NULL,
+  name           TEXT,
+  avatar_url     TEXT,
+  role           TEXT NOT NULL DEFAULT 'none',
+  -- GitHub user-to-server token, persisted so the repositories page can list
+  -- the user's repos (GET /user/repos) on demand. Refresh token + expiry are
+  -- null for non-expiring tokens (GitHub App with expiring tokens disabled).
+  gh_access_token      TEXT,
+  gh_refresh_token     TEXT,
+  gh_token_expires_at  INTEGER,
+  created_at     INTEGER NOT NULL,
+  updated_at     INTEGER NOT NULL,
+  -- Presence is independent of admin edits and background token refreshes.
+  -- NULL for legacy accounts until a known session authenticates them.
+  last_seen_at   INTEGER
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS managed_session (
+  id         TEXT PRIMARY KEY,
+  user_id    TEXT NOT NULL REFERENCES managed_user(id) ON DELETE CASCADE,
+  csrf_token TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS managed_session_user_idx ON managed_session(user_id);
+CREATE INDEX IF NOT EXISTS managed_session_expires_idx ON managed_session(expires_at);
+
+-- Repositories selected to operate on. Keyed by GitHub's numeric repo id
+-- (stable across renames). The row carries everything needed to read the repo's
+-- contents server-side later: installation_id mints an App installation token
+-- (Contents: Read) for PRIVATE repos — NULL means a PUBLIC repo readable without
+-- the App — and full_name + default_branch locate the contents. added_by is the
+-- selector, nulled (not cascaded) if that user is removed so the selection
+-- survives.
+CREATE TABLE IF NOT EXISTS managed_selected_repo (
+  repo_id         INTEGER PRIMARY KEY,
+  full_name       TEXT NOT NULL,
+  is_private      INTEGER NOT NULL,
+  installation_id INTEGER,
+  default_branch  TEXT NOT NULL,
+  html_url        TEXT NOT NULL,
+  added_by        TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  added_at        INTEGER NOT NULL,
+  updated_at      INTEGER NOT NULL,
+  active          INTEGER NOT NULL DEFAULT 1
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS selected_repo_full_name_idx ON managed_selected_repo(full_name);
+
+-- Bundles uploaded to the server (the "Manage bundles" page). Like reports, the
+-- bytes are stored in the clear (blob-store, keyed by this opaque uuid id) for
+-- the server to operate on. integrity is the content hash (sha512-<base64>,
+-- byte-identical to the client's) so re-uploading the same bytes dedupes (UNIQUE);
+-- it is also the key a report's bundleHashes match to auto-link.
+-- uploaded_by / repo_id are the (nullable) user + repo links, both nulled (not
+-- cascaded) when the referenced user / selected repo goes away.
+CREATE TABLE IF NOT EXISTS managed_bundle (
+  id           TEXT PRIMARY KEY,
+  slug         TEXT NOT NULL,
+  integrity    TEXT NOT NULL UNIQUE,
+  filename     TEXT NOT NULL,
+  kind         TEXT,
+  byte_size    INTEGER NOT NULL,
+  uploaded_by  TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  -- Durable snapshot of the uploader's login at upload time, so "who uploaded
+  -- this" survives the uploader being removed (when uploaded_by nulls out).
+  uploaded_by_login TEXT,
+  repo_id      INTEGER REFERENCES managed_selected_repo(repo_id) ON DELETE SET NULL,
+  repo_directory  TEXT NOT NULL DEFAULT '',
+  uploaded_at  INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS managed_bundle_uploaded_at_idx ON managed_bundle(uploaded_at);
+
+-- Reports uploaded to the server (the "Manage reports" page). A managed server
+-- is TRUSTED, so the bytes are stored in the clear (blob-store, keyed by this
+-- opaque uuid id) for the server to operate on later; this row carries the
+-- metadata + attribution. uploaded_by / repo_id are the (nullable) user + repo
+-- links, nulled (not cascaded) when the user / selected repo goes away. bundle_id
+-- is the (nullable) auto-resolved link to a stored bundle; bundle_integrity is
+-- the report's declared primary bundle (from its bundleHashes), kept so a later
+-- bundle upload of that integrity can re-link.
+CREATE TABLE IF NOT EXISTS managed_report (
+  id               TEXT PRIMARY KEY,
+  slug             TEXT NOT NULL,
+  filename         TEXT NOT NULL,
+  content_type     TEXT NOT NULL,
+  byte_size        INTEGER NOT NULL,
+  sha256           TEXT NOT NULL,
+  uploaded_by      TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  -- Durable snapshot of the uploader's login (see managed_bundle).
+  uploaded_by_login TEXT,
+  repo_id          INTEGER REFERENCES managed_selected_repo(repo_id) ON DELETE SET NULL,
+  repo_directory   TEXT NOT NULL DEFAULT '',
+  repo_embedded    INTEGER NOT NULL DEFAULT 0,
+  analyzer         TEXT,
+  visible          INTEGER NOT NULL DEFAULT 0,
+  bundle_id        TEXT REFERENCES managed_bundle(id) ON DELETE SET NULL,
+  bundle_integrity TEXT,
+  uploaded_at      INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS managed_report_uploaded_at_idx ON managed_report(uploaded_at);
+CREATE INDEX IF NOT EXISTS managed_report_bundle_integrity_idx ON managed_report(bundle_integrity);
+CREATE INDEX IF NOT EXISTS managed_report_bundle_hash_idx ON managed_report(bundle_id, sha256);
+
+-- Per-finding triage annotations — the managed (trusted-plaintext) counterpart
+-- of the client's localStorage triage map, keyed the same way: by finding id
+-- alone, not by report. Reports mostly repeat one another (a re-scan of the
+-- same code carries the same finding ids) and a finding's triage is shared by
+-- every report that carries it; which ids a viewer may read or write is
+-- decided per report at the endpoint, not here. The wire shape lives in
+-- common/managed/triage.ts. Whole-entry replace, NULL columns are unset;
+-- flagged is tri-state: NULL unset / 1 flagged / 0 an explicit un-flag
+-- tombstone. A cleared entry keeps its row with every field NULL — a
+-- tombstone a reader adopts as "cleared", where a missing row means "never
+-- annotated" (so a stale client copy can't resurrect a teammate's clear).
+-- updated_by is the last writer (nulled when that user is removed);
+-- updated_by_login is the durable login snapshot (see managed_bundle).
+CREATE TABLE IF NOT EXISTS managed_finding_triage (
+  finding_id       TEXT PRIMARY KEY,
+  color            TEXT,
+  triage           TEXT,
+  comment          TEXT,
+  fix              TEXT,
+  flagged          INTEGER,
+  updated_by       TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  updated_by_login TEXT,
+  updated_at       INTEGER NOT NULL
+) STRICT;
+
+-- The trail behind managed_finding_triage: one row per write that CHANGED an entry,
+-- holding the entry as written (every field NULL = a clear), who wrote it and
+-- when. managed_finding_triage stays the current-state projection reads hit; this is
+-- walked only for a finding's history. The wire is whole-entry replace, so a
+-- snapshot per write is exactly what arrived and "what changed" is the diff
+-- against the previous row for the same id, computed on read. batch_id groups
+-- the rows of one request. seq is the rowid: a total order that breaks ties
+-- on at. actor_id / actor_login follow the uploaded_by / uploaded_by_login
+-- convention (live account, durable login snapshot). Everything is kept by
+-- default — the trail is the record; an operator may bound it per finding
+-- (TRIAGE_HISTORY_LIMIT), in which case a finding's older events are trimmed
+-- as new ones land. An id no report carries any more is the tombstone GC's
+-- concern.
+CREATE TABLE IF NOT EXISTS managed_finding_triage_event (
+  seq          INTEGER PRIMARY KEY,
+  finding_id   TEXT NOT NULL,
+  batch_id     TEXT NOT NULL,
+  color        TEXT,
+  triage       TEXT,
+  comment      TEXT,
+  fix          TEXT,
+  flagged      INTEGER,
+  actor_id     TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  actor_login  TEXT,
+  at           INTEGER NOT NULL
+) STRICT;
+CREATE INDEX IF NOT EXISTS finding_triage_event_finding_idx ON managed_finding_triage_event(finding_id, seq);
+CREATE INDEX IF NOT EXISTS finding_triage_event_actor_at_idx ON managed_finding_triage_event(actor_id, at);
+
+-- Teams group users + repos for access scoping. A team has just a name here;
+-- the two link tables below carry the many-many relations.
+CREATE TABLE IF NOT EXISTS managed_team (
+  id          TEXT PRIMARY KEY,
+  slug        TEXT NOT NULL,
+  name        TEXT NOT NULL UNIQUE,
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL
+) STRICT;
+
+-- Team <-> repo, many-many, with an OPTIONAL path (a subpath of the repo the
+-- team is scoped to; empty path = the whole repo). Distinct paths can coexist;
+-- adding the whole repo replaces them. CASCADE removes links with either side. repo_id
+-- references the selected (operate-on) repos.
+CREATE TABLE IF NOT EXISTS managed_team_repo (
+  team_id  TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+  repo_id  INTEGER NOT NULL REFERENCES managed_selected_repo(repo_id) ON DELETE CASCADE,
+  path     TEXT NOT NULL DEFAULT '',
+  PRIMARY KEY (team_id, repo_id, path)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS team_repo_repo_idx ON managed_team_repo(repo_id);
+
+-- Team <-> user, many-many, with per-membership visibility permissions (see
+-- common/managed/permissions.ts) — view_dependencies / view_security, both
+-- default 0 (off). CASCADE so the membership dies with either side.
+CREATE TABLE IF NOT EXISTS managed_team_user (
+  team_id           TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+  user_id           TEXT NOT NULL REFERENCES managed_user(id) ON DELETE CASCADE,
+  view_dependencies INTEGER NOT NULL DEFAULT 0,
+  view_security     INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (team_id, user_id)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS team_user_user_idx ON managed_team_user(user_id);
+` + WORKSPACE_SHARE_SCHEMA

package/server-managed/db-table-names.ts

@@ -0,0 +1,22 @@
+// Table identifiers are code constants. Renames retain rows and foreign keys;
+// an ambiguous old/new pair must be resolved before the server can start.
+export const MANAGED_TABLE_RENAMES = [
+  ['selected_repo', 'managed_selected_repo'],
+  ['team_repo', 'managed_team_repo'],
+  ['team_user', 'managed_team_user'],
+  ['finding_triage', 'managed_finding_triage'],
+  ['finding_triage_event', 'managed_finding_triage_event'],
+  ['finding_comment', 'managed_finding_comment'],
+  ['finding_comment_event', 'managed_finding_comment_event'],
+] as const
+
+export function managedTableRenames(tables: Set<string>) {
+  // A fresh installation must not claim similarly named unrelated tables in
+  // a shared database. managed_user anchors an existing managed installation.
+  if (!tables.has('managed_user')) return []
+  const renames = MANAGED_TABLE_RENAMES.filter(([from]) => tables.has(from))
+  for (const [from, to] of renames) {
+    if (tables.has(to)) throw new Error(`Cannot migrate managed tables: both ${from} and ${to} exist`)
+  }
+  return renames
+}

package/server-managed/db.ts

@@ -0,0 +1,109 @@
+// SQLite bootstrap and legacy upgrades. Runtime methods are shared with Neon.
+import { mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { migrateSlugs } from './slugs.ts'
+import { migrateReportLocations } from './report-migration.ts'
+import { initCommentMethods } from './comments.ts'
+import { initActivityMethods } from './activity.ts'
+import { MANAGED_SCHEMA } from './db-schema.ts'
+import { GITHUB_METADATA_SCHEMA, GITHUB_STATE_REASON_COLUMN } from './github-metadata.ts'
+import { managedTableRenames } from './db-table-names.ts'
+import { type ManagedDb, type ManagedDbOptions, createManagedMethods } from './db-methods.ts'
+import { createSqliteDriver, scopeManagedMethods } from './sql.ts'
+export type * from './db-methods.ts'
+
+function migrateManagedTableNames(db: DatabaseSync): void {
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec('CREATE TABLE IF NOT EXISTS managed_schema_version (version INTEGER PRIMARY KEY) STRICT;')
+    if (!db.prepare('SELECT version FROM managed_schema_version WHERE version = 3').get()) {
+      const rows = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all() as { name: string }[]
+      for (const [from, to] of managedTableRenames(new Set(rows.map(row => row.name)))) {
+        db.exec(`ALTER TABLE ${from} RENAME TO ${to}`)
+      }
+      db.exec('INSERT INTO managed_schema_version VALUES (3)')
+    }
+    db.exec('COMMIT')
+  } catch (err) { db.exec('ROLLBACK'); throw err }
+}
+
+// Preserve the legacy single-path links while adding path to their identity.
+function migrateTeamRepoPaths(db: DatabaseSync): void {
+  const columns = db.prepare('PRAGMA table_info(managed_team_repo)').all() as { name: string; pk: number }[]
+  if (columns.some(column => column.name === 'path' && column.pk === 3)) return
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec(`CREATE TABLE managed_team_repo_paths (
+      team_id TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+      repo_id INTEGER NOT NULL REFERENCES managed_selected_repo(repo_id) ON DELETE CASCADE,
+      path TEXT NOT NULL DEFAULT '', PRIMARY KEY (team_id, repo_id, path)
+    ) STRICT;
+    INSERT INTO managed_team_repo_paths SELECT team_id, repo_id, COALESCE(path, '') FROM managed_team_repo;
+    DROP TABLE managed_team_repo;
+    ALTER TABLE managed_team_repo_paths RENAME TO managed_team_repo;
+    CREATE INDEX team_repo_repo_idx ON managed_team_repo(repo_id);`)
+    db.exec('COMMIT')
+  } catch (err) { db.exec('ROLLBACK'); throw err }
+}
+
+// Add `column` to `table` if it's missing (a lightweight migration for DBs that
+// predate the column; `table`/`column` are code constants, never user input).
+function ensureColumn(db: DatabaseSync, table: string, column: string, type: string): boolean {
+  const cols = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+  if (cols.some((c) => c.name === column)) return false
+  db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`)
+  return true
+}
+
+export function openSqliteManagedDb(path: string, options: ManagedDbOptions = {}): ManagedDb {
+  mkdirSync(dirname(path), { recursive: true })
+  const db = new DatabaseSync(path)
+  try {
+    db.exec('PRAGMA journal_mode = WAL;')
+    db.exec('PRAGMA synchronous = FULL;')
+    db.exec('PRAGMA foreign_keys = ON;')
+    migrateManagedTableNames(db)
+    db.exec(MANAGED_SCHEMA + GITHUB_METADATA_SCHEMA)
+    ensureColumn(db, 'managed_github_metadata', 'state_reason', GITHUB_STATE_REASON_COLUMN)
+    ensureColumn(db, 'managed_github_metadata', 'attempted_at', 'INTEGER')
+    // Existing public links must opt in too; never preserve an implicit grant.
+    ensureColumn(db, 'managed_workspace_share', 'dependencies', 'INTEGER NOT NULL DEFAULT 0')
+    ensureColumn(db, 'managed_workspace_share', 'security', 'INTEGER NOT NULL DEFAULT 0')
+    migrateTeamRepoPaths(db)
+    migrateSlugs(db)
+    // Migrate DBs created before a column existed (CREATE TABLE IF NOT EXISTS
+    // never alters an already-present table). Idempotent — skipped on fresh DBs.
+    const addedLastSeen = ensureColumn(db, 'managed_user', 'last_seen_at', 'INTEGER')
+    if (addedLastSeen) {
+      // Session creation is known authentication activity. updated_at is not:
+      // role changes and token refreshes also wrote it. Keep unknowns NULL.
+      db.exec(`UPDATE managed_user SET last_seen_at = (
+        SELECT MAX(s.created_at) FROM managed_session s WHERE s.user_id = managed_user.id
+      )`)
+    }
+    ensureColumn(db, 'managed_report', 'uploaded_by_login', 'TEXT')
+    ensureColumn(db, 'managed_report', 'repo_embedded', 'INTEGER NOT NULL DEFAULT 0')
+    migrateReportLocations(db, join(dirname(path), 'reports'))
+    ensureColumn(db, 'managed_report', 'analyzer', 'TEXT')
+    // Existing rows predate publication controls and were already visible.
+    // Backfill only when adding the column; newly inserted rows still use the
+    // hidden default and must be explicitly published.
+    const addedVisible = ensureColumn(db, 'managed_report', 'visible', 'INTEGER NOT NULL DEFAULT 0')
+    if (addedVisible) db.prepare('UPDATE managed_report SET visible = 1 WHERE visible = 0').run()
+    ensureColumn(db, 'managed_bundle', 'uploaded_by_login', 'TEXT')
+    ensureColumn(db, 'managed_bundle', 'repo_directory', "TEXT NOT NULL DEFAULT ''")
+    ensureColumn(db, 'managed_selected_repo', 'active', 'INTEGER NOT NULL DEFAULT 1')
+    ensureColumn(db, 'managed_finding_triage_event', 'report_id', 'TEXT')
+    ensureColumn(db, 'managed_finding_triage_event', 'report', 'TEXT')
+    ensureColumn(db, 'managed_finding_triage_event', 'repo', 'TEXT')
+    initCommentMethods(db)
+    initActivityMethods(db)
+  } catch (err) {
+    try { db.close() } catch {}
+    throw err
+  }
+
+  const driver = createSqliteDriver(db)
+  return scopeManagedMethods(createManagedMethods(driver, options), driver)
+}