@tangen/db 0.0.0-stage → 0.1.55

package/src/content-ddl.ts

@@ -0,0 +1,70 @@
+/**
+ * File Name: content-ddl.ts
+ * Purpose: The DDL of a content type's table and its `_i18n` side table, and
+ *          the in-place upgrades an existing database gets: the primary key is
+ *          `id` (and `(object_id, locale)` on the side table). One registry per
+ *          database, one table per type, rows scoped by workspace_id.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: `pkeyColumnsQuery` lets a caller detect an older
+ *          composite key by name before running the upgrade DDL.
+ */
+
+/** CREATE TABLE for a per-type content table. `fieldColsSql` is the caller's
+ *  pre-rendered field column list (possibly empty). */
+export function contentTableDdl(tableName: string, fieldColsSql: string): string {
+  return `
+        CREATE TABLE IF NOT EXISTS "${tableName}" (
+          id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          title TEXT,
+          slug TEXT,
+          status TEXT NOT NULL DEFAULT 'draft',
+          published_at TIMESTAMPTZ,
+          published_by TEXT,
+          published_values JSONB,
+          scheduled_at TIMESTAMPTZ,
+          scheduled_by TEXT,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          created_by TEXT,
+          updated_by TEXT,
+          created_by_kind TEXT,
+          updated_by_kind TEXT,
+          published_by_kind TEXT${fieldColsSql ? ',\n    ' + fieldColsSql : ''},
+          PRIMARY KEY (id)
+        )
+      `
+}
+
+/** CREATE TABLE for a per-type i18n side table (localized columns are added
+ *  by the caller with ALTER ... ADD COLUMN IF NOT EXISTS, as before). */
+export function i18nTableDdl(tableName: string): string {
+  return `
+      CREATE TABLE IF NOT EXISTS "${tableName}" (
+        object_id TEXT NOT NULL,
+        locale TEXT NOT NULL,
+        "__title" TEXT,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        PRIMARY KEY (object_id, locale)
+      )
+    `
+}
+
+/**
+ * Detection query: the table's PRIMARY KEY column list, as text like
+ * "id" or "object_id, locale". Callers compare against the target shape to
+ * decide whether the upgrade statements need to run (idempotence).
+ */
+export function pkeyColumnsQuery(tableName: string): string {
+  return `
+    SELECT c.conname AS pkey_name,
+           string_agg(a.attname, ', ' ORDER BY array_position(c.conkey, a.attnum)) AS cols
+    FROM pg_constraint c
+    JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+    WHERE c.contype = 'p' AND c.conrelid = '"${tableName}"'::regclass
+    GROUP BY c.conname
+  `
+}

package/src/content-tables.ts

@@ -0,0 +1,110 @@
+/**
+ * File Name: content-tables.ts
+ * Purpose: The RUNTIME registry of content tables: one Drizzle table object
+ *          per content type the process serves, built from the schema
+ *          registry rows of those environments - never from a generated file.
+ *          A process serving several environments on one database gets the
+ *          physical UNION of their tables, so which environment ran
+ *          `tangen push` last can never decide what the process can read.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: `contentTables` and `contentI18nTables` are MUTABLE
+ *          maps with a stable identity - every consumer imports them once and
+ *          reads `contentTables[type]` per request; `setContentTables`
+ *          replaces their entries in place at boot and on every schema
+ *          change. The generated `app/generated/content-tables.ts` remains
+ *          codegen and type support (tangen-types.d.ts) and is not loaded here.
+ */
+import { pgTable, text, numeric, boolean, timestamp, jsonb, primaryKey } from 'drizzle-orm/pg-core'
+import type { ColumnKind, ContentTableSpec, ContentI18nTableSpec } from '@tangen/types'
+
+export type ContentTableMap = Record<string, unknown>
+
+/** The content tables this process serves, by type name. Filled by setContentTables. */
+export const contentTables: ContentTableMap = {}
+/** The localized side tables (`<type>_i18n`), by type name. */
+export const contentI18nTables: ContentTableMap = {}
+
+/** The Drizzle column for one column kind - the same rule codegen writes down. */
+export function drizzleColumnFor(name: string, kind: ColumnKind) {
+  switch (kind) {
+    case 'NUMERIC': return numeric(name)
+    case 'BOOLEAN': return boolean(name)
+    case 'TIMESTAMPTZ': return timestamp(name, { withTimezone: true })
+    case 'JSONB': return jsonb(name)
+    case 'TEXT[]': return text(name).array()
+    // NUMRANGE is read and written as its string literal ("[1,10]"); PG casts on write.
+    case 'NUMRANGE':
+    case 'TEXT':
+    default: return text(name)
+  }
+}
+
+function systemCols() {
+  return {
+    // Identity is COMPOSITE - (id) - declared per table below.
+    id: text('id').notNull(),
+    workspaceId: text('workspace_id').notNull(),
+    title: text('title'),
+    slug: text('slug'),
+    status: text('status').notNull().default('draft'),
+    publishedAt: timestamp('published_at', { withTimezone: true }),
+    publishedBy: text('published_by'),
+    publishedValues: jsonb('published_values'),
+    scheduledAt: timestamp('scheduled_at', { withTimezone: true }),
+    /** Who scheduled the publish (a member or key id): the actor the scheduler publishes AS (kernel K4). */
+    scheduledBy: text('scheduled_by'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+    createdBy: text('created_by'),
+    updatedBy: text('updated_by'),
+    /** The actor KIND behind each attribution id (kernel K5): member | api_key | system | site_user. A system actor has no id, but it has a kind. */
+    createdByKind: text('created_by_kind'),
+    updatedByKind: text('updated_by_kind'),
+    publishedByKind: text('published_by_kind'),
+  }
+}
+
+/** One content table object from its spec: the system columns plus the field columns. */
+export function buildContentTable(spec: ContentTableSpec) {
+  const cols: Record<string, any> = { ...systemCols() }
+  for (const c of spec.columns) cols[c.name] = drizzleColumnFor(c.name, c.kind)
+  return pgTable(spec.name, cols, (t: any) => ({ pk: primaryKey({ columns: [t.id] }) }))
+}
+
+/** One localized side table object from its spec. */
+export function buildContentI18nTable(spec: ContentI18nTableSpec) {
+  const cols: Record<string, any> = {
+    objectId: text('object_id').notNull(),
+    locale: text('locale').notNull(),
+    __title: text('__title'),
+  }
+  for (const c of spec.columns) cols[c.name] = drizzleColumnFor(c.name, c.kind)
+  cols.updatedAt = timestamp('updated_at', { withTimezone: true }).notNull().defaultNow()
+  return pgTable(`${spec.type}_i18n`, cols, (t: any) => ({ pk: primaryKey({ columns: [t.objectId, t.locale] }) }))
+}
+
+export interface BuiltContentTables { contentTables: ContentTableMap; contentI18nTables: ContentTableMap }
+
+/** Every table object for a set of specs (the union a process serves). */
+export function buildContentTables(tables: ContentTableSpec[], i18n: ContentI18nTableSpec[] = []): BuiltContentTables {
+  const out: BuiltContentTables = { contentTables: {}, contentI18nTables: {} }
+  for (const spec of tables) out.contentTables[spec.name] = buildContentTable(spec)
+  for (const spec of i18n) out.contentI18nTables[spec.type] = buildContentI18nTable(spec)
+  return out
+}
+
+/** Replaces the registry's entries in place; the exported maps keep their identity. */
+export function setContentTables(built: BuiltContentTables): void {
+  for (const k of Object.keys(contentTables)) delete contentTables[k]
+  for (const k of Object.keys(contentI18nTables)) delete contentI18nTables[k]
+  Object.assign(contentTables, built.contentTables)
+  Object.assign(contentI18nTables, built.contentI18nTables)
+}
+
+/** Tests only: an empty registry. */
+export function resetContentTables(): void {
+  setContentTables({ contentTables: {}, contentI18nTables: {} })
+}

package/src/custom-tables-loader.ts

@@ -0,0 +1,65 @@
+/**
+ * File Name: custom-tables-loader.ts
+ * Purpose: The `@tangen/db/custom-tables` entry — resolves the GENERATED
+ *          custom-tables Drizzle registry project-first, mirroring the
+ *          content-tables loader. A consumer project's
+ *          `app/generated/custom-tables.ts` (written by `tangen push`,
+ *          committed to git) wins; otherwise the package's bundled
+ *          `generated/custom-tables.ts` (monorepo / tests) is used; otherwise
+ *          an empty registry. The API additionally falls back to building the
+ *          pgTable from the boot-loaded CustomTableDefinition (schema-kit's
+ *          customTablePg), so a missing/partial file never breaks queries.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Project-first: the project's generated file, then the bundled one —
+ *          the generated schema lives in the PROJECT, not node_modules (which
+ *          `npm i` wipes). Top-level await makes this an async module.
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+type TableMap = Record<string, unknown>
+interface GeneratedModule { customTables?: TableMap }
+
+/**
+ * Resolve the generated custom-tables MODULE (project-first, then bundled
+ * fallback, then empty).
+ */
+async function resolveGenerated(
+  workspaceRoot: string | undefined,
+  bundled: () => Promise<GeneratedModule>,
+): Promise<GeneratedModule> {
+  if (workspaceRoot) {
+    const projectFile = join(workspaceRoot, 'app', 'generated', 'custom-tables.ts')
+    if (existsSync(projectFile)) {
+      try {
+        return await import(projectFile)
+      } catch {
+        // Fall through to the bundled fallback on a bad/partial project file.
+      }
+    }
+  }
+  try {
+    return await bundled()
+  } catch {
+    return {}
+  }
+}
+
+/** Resolve just the custom-tables registry (project-first). Exposed for tests. */
+export async function loadCustomTables(
+  workspaceRoot: string | undefined,
+  bundled: () => Promise<GeneratedModule>,
+): Promise<TableMap> {
+  return (await resolveGenerated(workspaceRoot, bundled)).customTables ?? {}
+}
+
+const _generated: GeneratedModule = await resolveGenerated(
+  process.env.TANGEN_WORKSPACE_DIR,
+  () => import('./generated/custom-tables'),
+)
+
+/** Drizzle pgTable per custom table, keyed by table name. */
+export const customTables: TableMap = _generated.customTables ?? {}

package/src/ensure-system-schema.ts

@@ -0,0 +1,195 @@
+/**
+ * File Name: ensure-system-schema.ts
+ * Purpose: The idempotent system-schema floor, DERIVED from the canonical
+ *          migrations (closure plan, Phase 1 Unit 5). Tangen has one
+ *          authoritative definition and evolution path for its system
+ *          schema: the drizzle migrations under `drizzle/`. This module
+ *          declares nothing of its own. It extracts, mechanically and in
+ *          journal order, the statements those migrations already wrote in
+ *          an idempotent form (CREATE TABLE / CREATE INDEX / ADD COLUMN ...
+ *          IF NOT EXISTS) so a database the migrator could not bring up to
+ *          date (no DATABASE_URL, TANGEN_SKIP_MIGRATE=1, a drifted ledger)
+ *          still gets the tables and columns the current code reads, as a
+ *          best-effort fallback that can never fail a working database.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Runs only when the migrator did not (API boot) or
+ *          could not (push): when `runMigrations` succeeded the schema is
+ *          current by definition and the floor has nothing to add. Reads the
+ *          .sql files the package ships (the same files the migrator runs).
+ *          Statements inside DO blocks are not extracted: they are the
+ *          conditional path with its own entrypoint (knowledge-schema.ts).
+ *          A migration written without IF NOT EXISTS is not derivable and is
+ *          therefore only reachable through the migrator - the test lists
+ *          what the floor covers so a gap is a visible decision, not a
+ *          surprise.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const migrationsFolder = join(import.meta.dir, '..', 'drizzle')
+
+/** Splits SQL text into statements, honouring quotes, dollar-quoted blocks and `--` comments. */
+export function splitSqlStatements(text: string): string[] {
+  const out: string[] = []
+  let cur = ''
+  let i = 0
+  let inSingle = false
+  let inDouble = false
+  let dollarTag: string | null = null
+  while (i < text.length) {
+    const ch = text[i]!
+    if (dollarTag) {
+      if (text.startsWith(dollarTag, i)) { cur += dollarTag; i += dollarTag.length; dollarTag = null; continue }
+      cur += ch; i++; continue
+    }
+    if (inSingle) {
+      cur += ch
+      if (ch === "'") { if (text[i + 1] === "'") { cur += "'"; i += 2; continue } inSingle = false }
+      i++; continue
+    }
+    if (inDouble) { cur += ch; if (ch === '"') inDouble = false; i++; continue }
+    if (ch === '-' && text[i + 1] === '-') { const nl = text.indexOf('\n', i); i = nl === -1 ? text.length : nl; continue }
+    if (ch === '$') {
+      const m = /^\$[A-Za-z_]*\$/.exec(text.slice(i, i + 64))
+      if (m) { dollarTag = m[0]; cur += m[0]; i += m[0].length; continue }
+    }
+    if (ch === "'") { inSingle = true; cur += ch; i++; continue }
+    if (ch === '"') { inDouble = true; cur += ch; i++; continue }
+    if (ch === ';') { const s = cur.trim(); if (s) out.push(s); cur = ''; i++; continue }
+    cur += ch; i++
+  }
+  const tail = cur.trim()
+  if (tail) out.push(tail)
+  return out
+}
+
+/** The statement forms that are idempotent by construction, and so safe to run on any database. */
+const IDEMPOTENT = /^(CREATE TABLE IF NOT EXISTS|CREATE (UNIQUE )?INDEX (CONCURRENTLY )?IF NOT EXISTS|ALTER TABLE\s+(?:"[^"]+"|\w+)\s+ADD COLUMN IF NOT EXISTS)\b/i
+
+/** Tables migration 0051 drops: the Environment model. Never part of the floor. */
+const DROPPED_TABLES = new Set(['environments', 'member_env_membership', 'member_env_roles', 'promotion_log'])
+
+/**
+ * Migration 0051 removes the Environment column from every table
+ * (tasks/remove-environments-programme.md). It runs as one plpgsql block, so
+ * the floor cannot extract it - instead every earlier statement is rewritten
+ * the way 0051 leaves the table: no env column, the keys, uniques and
+ * indexes re-keyed without it (renamed the way 0051 renames them), and the
+ * dropped tables absent. Null when the statement has nothing left to say.
+ */
+export function withoutEnvironmentColumns(stmt: string): string | null {
+  const table = /^CREATE TABLE IF NOT EXISTS "?([A-Za-z_][A-Za-z0-9_]*)"?/i.exec(stmt)?.[1]
+  if (table && DROPPED_TABLES.has(table)) return null
+  const indexOn = /^CREATE (?:UNIQUE )?INDEX (?:CONCURRENTLY )?IF NOT EXISTS "?[A-Za-z0-9_]+"?\s+ON\s+"?([A-Za-z_][A-Za-z0-9_]*)"?/i.exec(stmt)?.[1]
+  if (indexOn && DROPPED_TABLES.has(indexOn)) return null
+  const alterOf = /^ALTER TABLE\s+"?([A-Za-z_][A-Za-z0-9_]*)"?\s+ADD COLUMN IF NOT EXISTS "?([A-Za-z_][A-Za-z0-9_]*)"?/i.exec(stmt)
+  if (alterOf && (DROPPED_TABLES.has(alterOf[1]!) || ENV_COLUMNS.has(alterOf[2]!))) return null
+  if (!/env_id/i.test(stmt)) return stmt
+  const renameIndex = (name: string) => name.replace(/_env_id(?=_|$)/g, '').replace(/_workspace_env_/g, '_workspace_').replace(/_ws_env_/g, '_ws_').replace(/_env_/g, '_')
+  if (table) {
+    const open = stmt.indexOf('(')
+    const close = stmt.lastIndexOf(')')
+    const body = stmt.slice(open + 1, close)
+    const parts = splitTopLevel(body).map((p) => p.trim()).filter(Boolean)
+    const kept: string[] = []
+    for (const part of parts) {
+      const col = /^"?([A-Za-z_][A-Za-z0-9_]*)"?\s/.exec(part)?.[1]
+      if (col && ENV_COLUMNS.has(col) && !/^(CONSTRAINT|PRIMARY|UNIQUE|FOREIGN|CHECK)\b/i.test(part)) continue
+      const constraint = /^(CONSTRAINT\s+"?([A-Za-z0-9_]+)"?\s+)?(PRIMARY KEY|UNIQUE)\s*\(([^)]*)\)/i.exec(part)
+      if (constraint) {
+        const cols = constraint[4]!.split(',').map((c) => c.trim()).filter((c) => !ENV_COLUMNS.has(c.replace(/"/g, '')))
+        if (cols.length === 0) continue
+        const name = constraint[2] ? `CONSTRAINT "${renameIndex(constraint[2])}" ` : ''
+        kept.push(`${name}${constraint[3]}(${cols.join(',')})`)
+        continue
+      }
+      kept.push(part)
+    }
+    return `${stmt.slice(0, open + 1)}\n\t${kept.join(',\n\t')}\n${stmt.slice(close)}`
+  }
+  if (indexOn) {
+    const m = /^(CREATE (?:UNIQUE )?INDEX (?:CONCURRENTLY )?IF NOT EXISTS )"?([A-Za-z0-9_]+)"?(\s+ON\s+"?[A-Za-z_][A-Za-z0-9_]*"?\s*(?:USING\s+\w+\s*)?)\(([\s\S]*)\)([\s\S]*)$/i.exec(stmt)
+    if (!m) return null
+    const cols = splitTopLevel(m[4]!).map((c) => c.trim()).filter((c) => !ENV_COLUMNS.has(c.replace(/"/g, '')))
+    if (cols.length === 0) return null
+    return `${m[1]}"${renameIndex(m[2]!)}"${m[3]}(${cols.join(', ')})${m[5] ?? ''}`
+  }
+  return stmt
+}
+
+const ENV_COLUMNS = new Set(['env_id', 'source_env_id', 'target_env_id', 'from_env_id', 'to_env_id'])
+
+/** Splits `a, b(c, d), e` on the commas outside parentheses. */
+function splitTopLevel(text: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let cur = ''
+  for (const ch of text) {
+    if (ch === '(') depth++
+    if (ch === ')') depth--
+    if (ch === ',' && depth === 0) { out.push(cur); cur = ''; continue }
+    cur += ch
+  }
+  out.push(cur)
+  return out
+}
+
+/** The floor: every idempotent statement the migrations carry, in journal order, each once, as 0051 leaves it. */
+export function deriveSystemSchemaFloor(migrationSql: readonly string[]): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const file of migrationSql) {
+    for (const raw of splitSqlStatements(file)) {
+      if (!IDEMPOTENT.test(raw.replace(/\s+/g, ' '))) continue
+      const stmt = withoutEnvironmentColumns(raw)
+      if (!stmt) continue
+      const key = stmt.replace(/\s+/g, ' ')
+      if (seen.has(key)) continue
+      seen.add(key)
+      out.push(stmt)
+    }
+  }
+  return out
+}
+
+/** The migration files in journal order, as the migrator reads them. */
+export function readMigrationSql(folder = migrationsFolder): string[] {
+  const journal = JSON.parse(readFileSync(join(folder, 'meta', '_journal.json'), 'utf8')) as { entries: Array<{ tag: string }> }
+  return journal.entries.map((e) => readFileSync(join(folder, `${e.tag}.sql`), 'utf8'))
+}
+
+let derived: readonly string[] | null = null
+
+/** The floor for the migrations this package ships (computed once). */
+export function systemSchemaFloor(): readonly string[] {
+  return (derived ??= deriveSystemSchemaFloor(readMigrationSql()))
+}
+
+/** @deprecated The floor is derived; kept as a name for the callers and tests that read it. */
+export const SYSTEM_COLUMN_GUARDS: readonly string[] = new Proxy([] as string[], {
+  get(_, prop) {
+    const list = systemSchemaFloor() as string[]
+    const v = (list as unknown as Record<PropertyKey, unknown>)[prop]
+    return typeof v === 'function' ? (v as (...a: unknown[]) => unknown).bind(list) : v
+  },
+  has(_, prop) { return prop in (systemSchemaFloor() as string[]) },
+  ownKeys() { return Reflect.ownKeys(systemSchemaFloor() as string[]) },
+  getOwnPropertyDescriptor(_, prop) { return Reflect.getOwnPropertyDescriptor(systemSchemaFloor() as string[], prop) },
+})
+
+/**
+ * Runs the derived floor. Best-effort per statement - a failure on one (a
+ * base table absent, an extension the server lacks) never blocks the others
+ * or the caller; the migrator is the path that reports errors.
+ * @param exec - Runs a raw SQL string against the database.
+ */
+export async function ensureSystemColumns(
+  exec: (sql: string) => Promise<unknown>,
+): Promise<void> {
+  for (const stmt of systemSchemaFloor()) {
+    try { await exec(stmt) } catch { /* base table absent / extension missing / transient - the migrator reconciles */ }
+  }
+}

package/src/extension-install-state.ts

@@ -0,0 +1,220 @@
+/**
+ * File Name: extension-install-state.ts
+ * Purpose: The installation state of an extension in a workspace - installed,
+ *          enabled, version, options, uninstalled - as the one table
+ *          `workspace_installed_apps` holds it. Installed, enabled and
+ *          active are distinct: a row exists once installed, `enabled`
+ *          switches it, and active means installed AND enabled.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Scope is the WORKSPACE (tasks/remove-environments-programme.md):
+ *          an extension is installed in a deployment's database for a
+ *          workspace, and every request in that workspace sees the same
+ *          installation. `InstallExec` is a raw statement runner so the CLI,
+ *          the API and PGlite tests share one implementation.
+ */
+import { and, eq } from 'drizzle-orm'
+import { workspaceInstalledApps } from './schema/workspace-installed-apps'
+
+export type InstallExec = (text: string, params?: unknown[]) => Promise<Array<Record<string, unknown>>>
+
+export function installExecFromDb(db: unknown): InstallExec {
+  const d = db as { $rawClient?: { unsafe: (t: string, p: unknown[]) => Promise<unknown[]> }; session?: { client?: { unsafe: (t: string, p: unknown[]) => Promise<unknown[]> } }; $client?: { query: (t: string, p: unknown[]) => Promise<{ rows: unknown[] }> } }
+  const raw = d.$rawClient ?? d.session?.client
+  if (raw && typeof raw.unsafe === 'function') return async (text, params) => (await raw.unsafe(text, params ?? [])) as Array<Record<string, unknown>>
+  const pg = d.$client ?? (d.session?.client as unknown as { query?: (t: string, p: unknown[]) => Promise<{ rows: unknown[] }> } | undefined)
+  if (pg && typeof pg.query === 'function') { const q = pg.query.bind(pg); return async (text, params) => (await q(text, params ?? [])).rows as Array<Record<string, unknown>> }
+  throw new Error('installExecFromDb: not a drizzle client this platform knows')
+}
+
+export type ExtensionInstallState = 'installed' | 'uninstalled'
+
+export interface ExtensionInstallRow {
+  id: string
+  workspaceId: string
+  extensionId: string
+  state: ExtensionInstallState
+  enabled: boolean
+  version: string | null
+  options: Record<string, unknown>
+  installedAt: Date | string
+  installedBy: string | null
+  upgradedAt: Date | string | null
+  uninstalledAt: Date | string | null
+  /** K5.2a: the grants an operator approved; null = not reviewed; undefined = the table has no such column yet. */
+  grantedGrants?: string[] | null
+}
+
+export interface InstallScope { workspaceId: string; extensionId: string }
+
+const COLS = `id, workspace_id, app_id, options, state, enabled, version, installed_at, installed_by, upgraded_at, uninstalled_at`
+
+function rowOf(r: Record<string, unknown>): ExtensionInstallRow {
+  return {
+    id: String(r.id), workspaceId: String(r.workspace_id), extensionId: String(r.app_id),
+    state: (r.state as ExtensionInstallState) ?? 'installed', enabled: r.enabled === true || r.enabled === 't',
+    version: (r.version as string | null) ?? null,
+    options: (typeof r.options === 'string' ? JSON.parse(r.options) : r.options ?? {}) as Record<string, unknown>,
+    installedAt: r.installed_at as Date | string, installedBy: (r.installed_by as string | null) ?? null,
+    upgradedAt: (r.upgraded_at as Date | string | null) ?? null, uninstalledAt: (r.uninstalled_at as Date | string | null) ?? null,
+    ...('granted_grants' in r ? { grantedGrants: parseGrants(r.granted_grants) } : {}),
+  }
+}
+
+function parseGrants(v: unknown): string[] | null {
+  const parsed = typeof v === 'string' ? JSON.parse(v) : v
+  return Array.isArray(parsed) ? parsed.filter((g): g is string => typeof g === 'string') : null
+}
+
+export async function readInstall(exec: InstallExec, scope: InstallScope): Promise<ExtensionInstallRow | null> {
+  const rows = await exec(`SELECT ${COLS} FROM workspace_installed_apps WHERE workspace_id = $1 AND app_id = $2 LIMIT 1`, [scope.workspaceId, scope.extensionId])
+  if (!rows[0]) return null
+  const row = rowOf(rows[0])
+  const grants = await listGrantedGrants(exec, scope)
+  return scope.extensionId in grants ? { ...row, grantedGrants: grants[scope.extensionId] ?? null } : row
+}
+
+/**
+ * K5.2a: the approval record per installed extension of a scope. Read in
+ * its own statement so a database whose migration has not run (or a test's
+ * hand-built table) answers "nothing recorded" instead of failing every
+ * install read.
+ */
+export async function listGrantedGrants(exec: InstallExec, scope: { workspaceId: string; extensionId?: string }): Promise<Record<string, string[] | null>> {
+  try {
+    const rows = scope.extensionId
+      ? await exec(`SELECT app_id, granted_grants FROM workspace_installed_apps WHERE workspace_id = $1 AND app_id = $2 AND state = 'installed'`, [scope.workspaceId, scope.extensionId])
+      : await exec(`SELECT app_id, granted_grants FROM workspace_installed_apps WHERE workspace_id = $1 AND state = 'installed'`, [scope.workspaceId])
+    const out: Record<string, string[] | null> = {}
+    for (const r of rows) out[String(r.app_id)] = parseGrants(r.granted_grants)
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/** K5.2a: record (or clear, with null) the grants an operator approved for an installation. */
+export async function recordGrantedGrants(exec: InstallExec, scope: InstallScope, grants: readonly string[] | null): Promise<void> {
+  await exec(
+    `UPDATE workspace_installed_apps SET granted_grants = $3::jsonb WHERE workspace_id = $1 AND app_id = $2`,
+    [scope.workspaceId, scope.extensionId, grants ? JSON.stringify([...grants]) : null],
+  )
+}
+
+export async function listInstalls(exec: InstallExec, scope: { workspaceId: string }): Promise<ExtensionInstallRow[]> {
+  const rows = await exec(`SELECT ${COLS} FROM workspace_installed_apps WHERE workspace_id = $1 ORDER BY app_id`, [scope.workspaceId])
+  return rows.map(rowOf)
+}
+
+export async function isExtensionActive(exec: InstallExec, scope: InstallScope): Promise<boolean> {
+  const rows = await exec(`SELECT 1 AS one FROM workspace_installed_apps WHERE workspace_id = $1 AND app_id = $2 AND state = 'installed' AND enabled = true LIMIT 1`, [scope.workspaceId, scope.extensionId])
+  return rows.length > 0
+}
+
+export async function activeExtensionIdsDb(db: unknown, scope: { workspaceId: string }): Promise<string[]> {
+  const d = db as { select: (cols: Record<string, unknown>) => { from: (t: unknown) => { where: (w: unknown) => Promise<Array<{ appId: string }>> } } }
+  const rows = await d
+    .select({ appId: workspaceInstalledApps.appId })
+    .from(workspaceInstalledApps)
+    .where(and(
+      eq(workspaceInstalledApps.workspaceId, scope.workspaceId),
+      eq(workspaceInstalledApps.state, 'installed'),
+      eq(workspaceInstalledApps.enabled, true),
+    ))
+  return rows.map((r) => r.appId)
+}
+
+export async function activeExtensionIds(exec: InstallExec, scope: { workspaceId: string }): Promise<string[]> {
+  const rows = await exec(`SELECT app_id FROM workspace_installed_apps WHERE workspace_id = $1 AND state = 'installed' AND enabled = true ORDER BY app_id`, [scope.workspaceId])
+  return rows.map((r) => String(r.app_id))
+}
+
+export interface InstallInput {
+  workspaceId: string
+  extensionId: string
+  version: string | null
+  options?: Record<string, unknown>
+  installedBy?: string | null
+  enabled?: boolean
+  /** K5.2a: the grants the operator approved at this install; omit to leave the installation unreviewed. */
+  grants?: readonly string[] | null
+}
+
+export async function installExtension(exec: InstallExec, input: InstallInput): Promise<{ row: ExtensionInstallRow; outcome: 'installed' | 'adopted' | 'already-installed' }> {
+  const existing = await readInstall(exec, input)
+  const options = JSON.stringify(input.options ?? {})
+  if (existing?.state === 'installed') return { row: existing, outcome: 'already-installed' }
+  if (existing) {
+    await exec(
+      `UPDATE workspace_installed_apps SET state = 'installed', enabled = $3, version = $4, options = $5::jsonb, installed_at = now(), installed_by = $6, uninstalled_at = NULL
+        WHERE workspace_id = $1 AND app_id = $2`,
+      [input.workspaceId, input.extensionId, input.enabled ?? true, input.version, options, input.installedBy ?? null],
+    )
+    if (input.grants !== undefined) await recordGrantedGrants(exec, input, input.grants)
+    return { row: (await readInstall(exec, input))!, outcome: 'adopted' }
+  }
+  const id = `wext_${Math.random().toString(16).slice(2, 10)}`
+  await exec(
+    `INSERT INTO workspace_installed_apps (id, workspace_id, app_id, options, state, enabled, version, installed_by)
+      VALUES ($1, $2, $3, $4::jsonb, 'installed', $5, $6, $7)`,
+    [id, input.workspaceId, input.extensionId, options, input.enabled ?? true, input.version, input.installedBy ?? null],
+  )
+  if (input.grants !== undefined) await recordGrantedGrants(exec, input, input.grants)
+  return { row: (await readInstall(exec, input))!, outcome: 'installed' }
+}
+
+export async function setExtensionEnabled(exec: InstallExec, scope: InstallScope, enabled: boolean): Promise<boolean> {
+  const rows = await exec(
+    `UPDATE workspace_installed_apps SET enabled = $3 WHERE workspace_id = $1 AND app_id = $2 AND state = 'installed' RETURNING id`,
+    [scope.workspaceId, scope.extensionId, enabled],
+  )
+  return rows.length > 0
+}
+
+export async function recordInstalledVersion(exec: InstallExec, scope: InstallScope, version: string, upgraded: boolean): Promise<void> {
+  await exec(
+    `UPDATE workspace_installed_apps SET version = $3${upgraded ? ', upgraded_at = now()' : ''} WHERE workspace_id = $1 AND app_id = $2`,
+    [scope.workspaceId, scope.extensionId, version],
+  )
+}
+
+export async function discardInstall(exec: InstallExec, scope: InstallScope, outcome: 'installed' | 'adopted'): Promise<void> {
+  if (outcome === 'adopted') { await uninstallExtension(exec, scope); return }
+  await exec(`DELETE FROM workspace_installed_apps WHERE workspace_id = $1 AND app_id = $2`, [scope.workspaceId, scope.extensionId])
+}
+
+export async function uninstallExtension(exec: InstallExec, scope: InstallScope): Promise<boolean> {
+  const rows = await exec(
+    `UPDATE workspace_installed_apps SET state = 'uninstalled', enabled = false, uninstalled_at = now() WHERE workspace_id = $1 AND app_id = $2 AND state = 'installed' RETURNING id`,
+    [scope.workspaceId, scope.extensionId],
+  )
+  return rows.length > 0
+}
+
+/**
+ * A declaration in app/config/extensions.ts makes an extension AVAILABLE and
+ * nothing more: installing and enabling are explicit acts, per deployment
+ * (`tangen extension install`). Boot used to adopt every declared extension
+ * as installed and enabled, which put SEO and Flows in every new project's
+ * sidebar before anyone asked (2026-09-07). What boot still does is learn
+ * the declared version for an installed row that predates versions.
+ * @returns how many rows learned a version.
+ */
+export async function syncDeclaredExtensionVersions(
+  exec: InstallExec,
+  workspaces: Array<{ workspaceId: string; extensions: Array<{ id: string; version: string }> }>,
+): Promise<number> {
+  let learned = 0
+  for (const ws of workspaces) {
+    for (const ext of ws.extensions) {
+      const rows = await exec(
+        `UPDATE workspace_installed_apps SET version = $3 WHERE workspace_id = $1 AND app_id = $2 AND version IS NULL RETURNING id`,
+        [ws.workspaceId, ext.id, ext.version],
+      )
+      learned += rows.length
+    }
+  }
+  return learned
+}