pipework 0.251.0 → 0.252.1

package/src/data/migrate/pragma.ts

@@ -0,0 +1,73 @@
+/**
+ * Migration pragmas — per-file declarations read from the migration's own
+ * comments.
+ *
+ * Authorization for a hazardous migration lives here rather than on the
+ * `pipework migrate` command line, and the distinction is the whole point.
+ * A CLI flag authorizes an *invocation*: it is written once, into a deploy
+ * workflow, by someone who cannot know what migration 0071 will contain nine
+ * months later. The first destructive migration that has to ship puts
+ * `--allow-destructive` in CI permanently, and from then on the gate is
+ * decorative — every later migration is pre-approved by a decision nobody
+ * revisits, and nothing about it shows up in review.
+ *
+ * A pragma authorizes a *file*. It is written by the person writing the
+ * destructive statement, at the moment they write it; it appears in the diff,
+ * so it is reviewed; it is versioned, so `git log` says who approved which
+ * drop; and it cannot go blanket — a pragma in 0065 says nothing about 0071.
+ * The deploy command stays a bare `pipework migrate` forever, which means
+ * there is no flag to erode.
+ *
+ * The migration tracker records a content hash per applied migration and
+ * refuses edited-but-applied files. Only `expect-*` lines are ignored by that
+ * hash, so annotating history is allowed and nothing else about it is.
+ */
+
+export const PRAGMA_PREFIX = '-- pipework:'
+
+/** Hazard classes that require a per-migration declaration. */
+export type PragmaKind = 'destructive' | 'locking' | 'dynamic'
+
+export const PRAGMA_FOR: Record<PragmaKind, string> = {
+  destructive: 'pipework:expect-destructive',
+  locking: 'pipework:expect-locking',
+  dynamic: 'pipework:expect-dynamic',
+}
+
+/**
+ * True when `sql` declares the given pragma. Pragmas are recognized only on
+ * their own comment line, so prose that happens to mention one does not
+ * authorize anything.
+ */
+export function hasPragma(sql: string, kind: PragmaKind): boolean {
+  const wanted = PRAGMA_FOR[kind]
+  for (const line of sql.split('\n')) {
+    if (pragmaOfLine(line) === wanted) return true
+  }
+  return false
+}
+
+const DECLARED = new Set<string>(Object.values(PRAGMA_FOR))
+
+/** The pragma a single line declares, or undefined when it declares none. */
+function pragmaOfLine(line: string): string | undefined {
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('--')) return undefined
+  return trimmed.slice(2).trim()
+}
+
+/**
+ * `sql` with every `expect-*` pragma line removed, line terminator included.
+ * A pragma declares a hazard; it does not change what the migration does, so
+ * the tracker's immutability check ignores it: an app may annotate an applied
+ * file so a fresh database can replay history through the gate.
+ */
+export function stripPragmaLines(sql: string): string {
+  const lines = sql.match(/[^\n]*\n|[^\n]+$/g) ?? []
+  return lines
+    .filter((line) => {
+      const pragma = pragmaOfLine(line)
+      return pragma === undefined || !DECLARED.has(pragma)
+    })
+    .join('')
+}

package/src/data/migrate/provision-framework.ts

@@ -0,0 +1,147 @@
+// Provisions pipework's framework-owned partitioned tables — the trace family.
+// `generate` deliberately keeps them out of application migrations (#313): a
+// bare CREATE TABLE of a PARTITION BY RANGE table accepts no rows. pipework
+// creates them itself — the parent tables, then their day partitions —
+// wherever a database is provisioned: the test harness (src/test/setup.ts) and
+// `migrate` (src/data/migrate/run.ts).
+
+import { sql } from '../db/sql.js'
+import { quoteIdentifier } from '../db/identifiers.js'
+import type { DB } from '../db/index.js'
+import type { Blueprint } from '../../core/config/schema.js'
+import { syncTracePartitions, type TracePartitionConfig } from '../../trace/partition/index.js'
+import { PARTITIONED_TRACE_TABLE_NAMES } from '../../trace/partition/tables.js'
+import { AUDIT_ENTITY_INDEX_SQL } from '../../audit/schema/audit-record.js'
+import { installAuditChain } from '../../audit/chain/install.js'
+import { loadInternalDefinitions } from './internal-definitions.js'
+import { buildSnapshot, EMPTY_SNAPSHOT } from './snapshot.js'
+import type { DiffOp } from './diff.js'
+import { emitSQL } from './sql-emit.js'
+import { makeTablesUnlogged } from './apply.js'
+import { installFrameworkPolicies, type FrameworkRls } from './framework-rls.js'
+
+export interface FrameworkTablesResult {
+  /** Parent tables that did not exist and were created. */
+  created: string[]
+  /** `table.column` for every column added to a table that already existed. */
+  columnsAdded: string[]
+  /** Day partitions created. */
+  partitionsCreated: string[]
+}
+
+export function frameworkTablesChanged(r: FrameworkTablesResult): boolean {
+  return r.created.length + r.columnsAdded.length + r.partitionsCreated.length > 0
+}
+
+export class FrameworkTableColumnError extends Error {
+  override readonly name = 'FrameworkTableColumnError'
+}
+
+/**
+ * Create the framework-owned partitioned tables and their day partitions.
+ *
+ * Trace and audit storage rides the default database only, and only when the
+ * blueprint enables `trace` or `audit`. `valve_crossing` is framework-owned but
+ * not partitioned — it ships in the application migration like any ordinary
+ * table — so it is not provisioned here. Issue #313.
+ *
+ * Missing tables are created. A table that exists gains any column its
+ * definition has and it lacks; nothing is dropped, renamed or altered. A
+ * missing NOT NULL column with no default cannot be added to a table that has
+ * rows and fails naming the table and column. `unlogged` is for test databases;
+ * a real database gets logged tables. When the database configures `rls`, each
+ * table also gets the tenant policies of `framework-rls.ts`, replaced on every
+ * run so an existing database picks them up. Idempotent.
+ */
+export async function provisionFrameworkTables(
+  db: DB,
+  blueprint: Blueprint,
+  traceConfig: TracePartitionConfig,
+  isDefaultDatabase: boolean,
+  options: {
+    unlogged: boolean
+    rls?: FrameworkRls | undefined
+    /** Told as each step starts; a partition reports `step` 'partition' with `i/n name` as detail. */
+    onProgress?: ((step: string, detail?: string) => void) | undefined
+  } = { unlogged: true },
+): Promise<FrameworkTablesResult> {
+  const result: FrameworkTablesResult = { created: [], columnsAdded: [], partitionsCreated: [] }
+  const progress = options.onProgress ?? (() => {})
+  if (!isDefaultDatabase) return result
+  if (blueprint.trace === undefined && blueprint.audit === undefined) return result
+
+  const definitions = await loadInternalDefinitions(blueprint, { isDefaultDatabase })
+  const snapshot = buildSnapshot(definitions, EMPTY_SNAPSHOT.id)
+  const tables = Object.values(snapshot.tables).filter(t => PARTITIONED_TRACE_TABLE_NAMES.has(t.name))
+
+  const live = await readLiveColumns(db, tables.map(t => t.name))
+  const createOps: DiffOp[] = []
+  const alterStatements: string[] = []
+
+  for (const table of tables) {
+    const liveColumns = live.get(table.name)
+    if (liveColumns === undefined) {
+      createOps.push({ type: 'create_table', table })
+      result.created.push(table.name)
+      continue
+    }
+    for (const column of Object.values(table.columns)) {
+      if (liveColumns.has(column.name)) continue
+      if (column.notNull && column.default === undefined && column.identity === undefined && column.generated === undefined) {
+        const rows = await db.execute(sql.raw(`SELECT 1 FROM ${quoteIdentifier(table.name, 'table')} LIMIT 1`))
+        if (rows.length > 0) {
+          throw new FrameworkTableColumnError(
+            `Cannot add column "${column.name}" to framework table "${table.name}": it is NOT NULL with no default ` +
+            `and the table has rows. Backfill is a decision for the application — add the column by hand ` +
+            `(nullable, backfill, then SET NOT NULL) and run migrate again.`,
+          )
+        }
+      }
+      const [statement] = emitSQL([{ type: 'add_column', tableName: table.name, tableSchema: table.schema, column }])
+      alterStatements.push(statement!.replace('ADD COLUMN', 'ADD COLUMN IF NOT EXISTS'))
+      result.columnsAdded.push(`${table.name}.${column.name}`)
+    }
+  }
+
+  progress('tables')
+  const createStatements = emitSQL(createOps)
+  for (const [i, statement] of createStatements.entries()) {
+    await db.execute(sql.raw(options.unlogged ? makeTablesUnlogged(statement) : statement))
+    progress('tables', `create ${i + 1}/${createStatements.length}`)
+  }
+  for (const [i, statement] of alterStatements.entries()) {
+    await db.execute(sql.raw(statement))
+    progress('tables', `alter ${i + 1}/${alterStatements.length}`)
+  }
+  if (tables.some(t => t.name === 'audit_record')) await db.execute(sql.raw(AUDIT_ENTITY_INDEX_SQL))
+
+  if (blueprint.audit?.chain === true) {
+    progress('audit-chain')
+    await installAuditChain(db)
+  }
+  if (options.rls !== undefined) {
+    progress('policies')
+    await installFrameworkPolicies(db, tables.map(t => t.name), options.rls)
+  }
+
+  const synced = await syncTracePartitions(db, traceConfig, undefined, {
+    onPartition: (name, index, total) => progress('partition', `${index}/${total} ${name}`),
+  })
+  result.partitionsCreated.push(...synced.created)
+  return result
+}
+
+/** Column names of each named public table that exists; absent tables are not in the map. */
+async function readLiveColumns(db: DB, names: string[]): Promise<Map<string, Set<string>>> {
+  const out = new Map<string, Set<string>>()
+  for (const name of names) {
+    const rows = await db.execute(sql`
+      SELECT a.attname AS name
+      FROM pg_attribute a
+      WHERE a.attrelid = to_regclass(${quoteIdentifier(name, 'table')})
+        AND a.attnum > 0 AND NOT a.attisdropped
+    `)
+    if (rows.length > 0) out.set(name, new Set(rows.map(r => String(r['name']))))
+  }
+  return out
+}

package/src/data/migrate/rls-generate.ts

@@ -0,0 +1,61 @@
+import type { DefinedTable, FieldKind } from '../domain/types.js'
+import { camelToSnake } from '../domain/naming.js'
+import { tenantIsolationPolicy, type TenantKeyType } from '../../auth/tenant/rls.js'
+
+// A fresh matcher per call. A `g` regex carries lastIndex; sharing one instance
+// corrupts the next call when a previous run exits mid-iteration (e.g.
+// tenantKeyTypeForKind throws), making exec() resume mid-string and silently
+// skip tables — dropping their RLS. Each call gets its own.
+const createTableMatcher = (): RegExp => /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|([a-z_][a-z0-9_]*))/gi
+
+export function generateRlsStatements(
+  migrationSql: string,
+  definitions: ReadonlyMap<string, DefinedTable>,
+  sessionVar: string,
+  force: boolean = true,
+): string {
+    const rlsBlocks: string[] = []
+    let match: RegExpExecArray | null
+
+    const createTableRe = createTableMatcher()
+    while ((match = createTableRe.exec(migrationSql)) !== null) {
+      const tableName = match[1] ?? match[2]
+      if (tableName === undefined) continue
+
+      const definition = definitions.get(tableName)
+      if (definition === undefined) continue
+
+      const tenantFieldKey = Object.keys(definition.$fields).find(
+        (key) => definition.$fields[key]!._meta.tenant === true,
+      )
+      if (tenantFieldKey === undefined) continue
+
+      const tenantField = definition.$fields[tenantFieldKey]!
+      const columnName = camelToSnake(tenantFieldKey)
+      const keyType = tenantKeyTypeForKind(tenantField._meta.kind, tableName, tenantFieldKey)
+
+      if (migrationSql.includes(`"${tableName}" ENABLE ROW LEVEL SECURITY`) ||
+          migrationSql.includes(`${tableName} ENABLE ROW LEVEL SECURITY`)) {
+        continue
+      }
+
+      rlsBlocks.push(tenantIsolationPolicy(tableName, columnName, keyType, sessionVar, force))
+    }
+
+    if (rlsBlocks.length === 0) return migrationSql
+
+    return migrationSql + '\n\n' + rlsBlocks.join(';\n\n') + ';'
+}
+
+const TENANT_KEY_KINDS: ReadonlySet<string> = new Set(['uuid', 'text', 'integer', 'bigint'])
+
+function tenantKeyTypeForKind(kind: FieldKind, table: string, field: string): TenantKeyType {
+  if (TENANT_KEY_KINDS.has(kind)) return kind as TenantKeyType
+  throw new Error(
+    `[pipework] Field "${field}" on table "${table}" is marked .tenant() but its kind is '${kind}'.\n\n` +
+    `  A tenant discriminator must be uuid, text, integer, or bigint — the generated RLS\n` +
+    `  policy casts current_setting() to that type. Mark the uuid/text tenant key with\n` +
+    `  .tenant(), not a '${kind}' column.`,
+  )
+}
+

package/src/data/migrate/run.ts

@@ -0,0 +1,124 @@
+import { sql } from '../query/index.js'
+import type { Manifold } from '../../core/pipework.js'
+import type { ResolvedDatabase } from '../../core/config/index.js'
+import { quoteIdentifier } from '../db/identifiers.js'
+import { OWNER_LABEL_MIGRATE } from '../db/owner-labels.js'
+import { checkMigrations, type MigrationCheckResult } from './check.js'
+import { readAppliedState } from './applied.js'
+import { applyMigrations } from './apply.js'
+import { provisionFrameworkTables, type FrameworkTablesResult } from './provision-framework.js'
+
+// Deliberately empty of hazard switches. Authorization for a hazardous
+// migration is declared in that migration's own file (see pragma.ts) — an
+// option here would be an invocation-level approval, which is exactly the
+// thing that gets written into a deploy workflow once and never revisited.
+export interface MigrateOptions {}
+
+export interface MigrateResult {
+  database: string
+  migrationsRun: number
+  extensions: string[]
+  safetyCheck: MigrationCheckResult
+  /** No-transaction files picked up half applied and finished. Issue #378. */
+  resumed: ResumedMigration[]
+  /** Trace/audit tables, columns and day partitions this run provisioned. */
+  frameworkTables: FrameworkTablesResult
+}
+
+export interface ResumedMigration {
+  tag: string
+  /** 1-based statement the rerun started from. */
+  fromStatement: number
+  totalStatements: number
+}
+
+export class UnsafeMigrationError extends Error {
+  override readonly name = 'UnsafeMigrationError'
+  constructor(
+    public readonly check: MigrationCheckResult,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+export async function migrateAll(instance: Manifold, options: MigrateOptions = {}): Promise<MigrateResult[]> {
+  const results: MigrateResult[] = []
+
+  for (const [, dbConfig] of instance.config.databases()) {
+    if (dbConfig.migrations === undefined) continue
+    const result = await migrateOne(instance, dbConfig, options)
+    results.push(result)
+  }
+
+  return results
+}
+
+export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase, _options: MigrateOptions = {}): Promise<MigrateResult> {
+  const conn = instance.pool.getOrCreate(dbConfig, 'owner', OWNER_LABEL_MIGRATE)
+
+  // Scope the safety gate to pending migrations only — hazards in already-applied
+  // migrations are history, not a decision the operator still gets to make.
+  // Without this, a fully-current database with a destructive op anywhere in its
+  // history can never run a clean no-op `migrate`.
+  const safetyCheck = dbConfig.migrations !== undefined
+    ? checkMigrations(dbConfig.migrations, await readAppliedState(conn.drizzle, dbConfig.migrationTable))
+    : { safe: true, hasDestructive: false, hasLocking: false, hasDynamic: false, declared: true, fileHazards: [] } as MigrationCheckResult
+
+  if (!safetyCheck.declared) {
+    const files = safetyCheck.fileHazards.filter(f => f.undeclared.length > 0)
+    const detail = files
+      .map(f => `${f.file} (${f.undeclared.join(', ')})`)
+      .join(', ')
+    throw new UnsafeMigrationError(
+      safetyCheck,
+      `Migration for "${dbConfig.name}" raises hazards that its own file does not declare: ${detail}. ` +
+      `Add the matching \`-- pipework:expect-*\` pragma to each migration and commit it.`,
+    )
+  }
+
+  let extensionsCreated: string[] = []
+
+  if (dbConfig.extensions.length > 0) {
+    for (const ext of dbConfig.extensions) {
+      await conn.drizzle.execute(sql.raw(`CREATE EXTENSION IF NOT EXISTS ${quoteIdentifier(ext, 'extension')}`))
+    }
+    extensionsCreated = [...dbConfig.extensions]
+  }
+
+  const resumed: ResumedMigration[] = []
+  const migrationsRun = await applyMigrations({
+    migrationsFolder: dbConfig.migrations!,
+    migrationsTable: dbConfig.migrationTable,
+    connectionUrl: dbConfig.url,
+    onResume: (tag, fromStatement, totalStatements) => resumed.push({ tag, fromStatement, totalStatements }),
+  })
+
+  // Trace and audit storage rides the default database; their partitioned
+  // tables are kept out of generated migrations (#313), so migrate provisions them.
+  const frameworkTables = await provisionFrameworkTables(
+    conn.drizzle,
+    instance.config.raw,
+    {
+      hotRetentionDays: instance.config.trace.hotRetentionDays,
+      errorRetentionDays: instance.config.trace.errorRetentionDays,
+      auditRetentionDays: instance.config.audit.retentionDays === 'keep' ? null : instance.config.audit.retentionDays,
+      partitionLeadDays: instance.config.trace.partitionLeadDays,
+    },
+    wantsFrameworkTables(instance) && dbConfig.name === instance.config.defaultDatabaseName(),
+    { unlogged: false, rls: dbConfig.rls },
+  )
+
+  return {
+    database: dbConfig.name,
+    migrationsRun,
+    extensions: extensionsCreated,
+    safetyCheck,
+    resumed,
+    frameworkTables,
+  }
+}
+
+function wantsFrameworkTables(instance: Manifold): boolean {
+  return instance.config.raw.trace !== undefined || instance.config.raw.audit !== undefined
+}

package/src/data/migrate/safety.ts

@@ -0,0 +1,167 @@
+import { scanStatements, blankLiterals } from './statements.js'
+
+export type Severity = 'destructive' | 'locking' | 'dynamic' | 'safe'
+
+export interface MigrationHazard {
+  severity: Severity
+  operation: string
+  statement: string
+  suggestion: string
+}
+
+interface Rule {
+  pattern: RegExp
+  severity: Severity
+  operation: string
+  suggestion: string
+  except?: RegExp
+}
+
+const RULES: Rule[] = [
+  // ── Destructive (data loss / backward-incompatible) ───────────────────
+  {
+    pattern: /\bDROP\s+TABLE\b/i,
+    severity: 'destructive',
+    operation: 'DROP TABLE',
+    suggestion: 'Rename the table first, deploy, verify no access, then drop in a follow-up migration.',
+  },
+  {
+    pattern: /\bDROP\s+COLUMN\b/i,
+    severity: 'destructive',
+    operation: 'DROP COLUMN',
+    suggestion: 'Stop reading the column in application code first, then drop in a follow-up migration.',
+  },
+  {
+    pattern: /\bALTER\s+COLUMN\b[^;]*\bSET\s+NOT\s+NULL\b/i,
+    severity: 'destructive',
+    operation: 'SET NOT NULL',
+    suggestion: 'Add a CHECK constraint with NOT VALID, validate it separately, then convert to NOT NULL.',
+  },
+  {
+    pattern: /\bALTER\s+COLUMN\b[^;]*\bTYPE\b/i,
+    severity: 'destructive',
+    operation: 'ALTER COLUMN TYPE',
+    suggestion: 'Add a new column with the target type, backfill, swap reads, then drop the old column.',
+  },
+  {
+    pattern: /\bTRUNCATE\b/i,
+    severity: 'destructive',
+    operation: 'TRUNCATE',
+    suggestion: 'Use DELETE with a WHERE clause if you need to remove rows in a migration.',
+  },
+
+  // ── Locking (acquires heavy locks, risks downtime under load) ─────────
+  {
+    pattern: /\bCREATE\s+(?:UNIQUE\s+)?INDEX\b(?!\s+CONCURRENTLY)/i,
+    severity: 'locking',
+    operation: 'CREATE INDEX (non-concurrent)',
+    suggestion: 'Use CREATE INDEX CONCURRENTLY to avoid blocking writes.',
+    except: /\bCONCURRENTLY\b/i,
+  },
+  {
+    pattern: /\bRENAME\s+COLUMN\b/i,
+    severity: 'locking',
+    operation: 'RENAME COLUMN',
+    suggestion: 'Add a new column, backfill, migrate reads, then drop the old column.',
+  },
+  {
+    pattern: /\bRENAME\s+TABLE\b/i,
+    severity: 'locking',
+    operation: 'RENAME TABLE',
+    suggestion: 'Create a new table, migrate data, swap reads, then drop the old table.',
+  },
+  {
+    pattern: /\bRENAME\s+TO\b/i,
+    severity: 'locking',
+    operation: 'RENAME TO',
+    suggestion: 'Renames acquire AccessExclusive locks. Consider a multi-step migration instead.',
+    except: /\bRENAME\s+COLUMN\b|\bRENAME\s+TABLE\b|\bALTER\s+INDEX\b/i,
+  },
+  {
+    pattern: /\bADD\s+CONSTRAINT\b[^;]*\bFOREIGN\s+KEY\b(?![^;]*\bNOT\s+VALID\b)/i,
+    severity: 'locking',
+    operation: 'ADD FOREIGN KEY (without NOT VALID)',
+    suggestion: 'Add the constraint with NOT VALID, then VALIDATE CONSTRAINT in a separate statement.',
+  },
+  {
+    // Locking rather than destructive: on a non-empty table this fails loudly
+    // instead of losing data, so it aborts the deploy rather than silently
+    // damaging it. It is still a gate-worthy hazard, hence the rule (#334).
+    pattern: /\bADD\s+COLUMN\b[^;]*\bNOT\s+NULL\b/i,
+    severity: 'locking',
+    operation: 'ADD COLUMN NOT NULL (without DEFAULT)',
+    suggestion:
+      'Add the column nullable, backfill, then SET NOT NULL — or give it a DEFAULT so existing rows can be filled.',
+    except: /\bDEFAULT\b/i,
+  },
+
+  // ── Dynamic (SQL assembled at runtime — unanalyzable) ────────────────
+  {
+    // The gate reads text; `EXECUTE` runs text that does not exist yet. Rather
+    // than pretend to see through it, name it. This is also what lets string
+    // literals be treated as the inert data they almost always are: a literal
+    // is dangerous exactly when something EXECUTEs it, and that is structural
+    // rather than a guess about its contents (#334). `EXECUTE FUNCTION|PROCEDURE`
+    // (triggers) and `EXECUTE ON` (GRANT/REVOKE) name an existing function or
+    // privilege and build no SQL, so they are not this (#480).
+    pattern: /\bEXECUTE\b(?!\s+(?:FUNCTION|PROCEDURE|ON)\b)/i,
+    severity: 'dynamic',
+    operation: 'dynamic SQL (EXECUTE)',
+    suggestion:
+      'The gate cannot analyze SQL built at runtime. Prefer static DDL; if runtime assembly is required, declare it in the migration.',
+  },
+]
+
+export function analyzeSQL(sql: string): MigrationHazard[] {
+  const statements = scanStatements(sql)
+  const hazards: MigrationHazard[] = []
+
+  for (const stmt of statements) {
+    // Rules match against the statement with string-literal contents blanked:
+    // literals are data, and DDL keywords sitting in seed data execute
+    // nothing. Dollar-quoted bodies stay intact — those are code.
+    const subject = blankLiterals(stmt)
+
+    for (const rule of RULES) {
+      if (!rule.pattern.test(subject)) continue
+      if (rule.except !== undefined && rule.except.test(subject)) continue
+
+      hazards.push({
+        severity: rule.severity,
+        operation: rule.operation,
+        statement: stmt.trim().slice(0, 200),
+        suggestion: rule.suggestion,
+      })
+    }
+  }
+
+  return hazards
+}
+
+export function formatHazards(hazards: MigrationHazard[], file: string): string {
+  const lines: string[] = []
+
+  lines.push(`  ${file}:`)
+
+  const label: Record<string, string> = {
+    destructive: '✗ DESTRUCTIVE',
+    locking: '⚠ LOCKING',
+    dynamic: '? DYNAMIC',
+  }
+
+  for (const severity of ['destructive', 'locking', 'dynamic'] as const) {
+    for (const h of hazards.filter(x => x.severity === severity)) {
+      lines.push(`    ${label[severity]}: ${h.operation}`)
+      lines.push(`      ${truncate(h.statement, 120)}`)
+      lines.push(`      → ${h.suggestion}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function truncate(s: string, max: number): string {
+  const oneLine = s.replace(/\s+/g, ' ')
+  if (oneLine.length <= max) return oneLine
+  return oneLine.slice(0, max - 3) + '...'
+}