pipework 0.252.0 → 0.252.1

package/src/data/migrate/generate.ts

@@ -0,0 +1,201 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { glob } from 'node:fs/promises'
+import type { ResolvedDatabase, ResolvedDoor } from '../../core/config/load.js'
+import { ConfigError } from '../../core/config/errors.js'
+import { postProcessMigration } from './post-process.js'
+import { diffDoors, doorSnapshots } from './door-generate.js'
+import { generateRlsStatements } from './rls-generate.js'
+import { generateAppendOnlyStatements } from './append-only-generate.js'
+import { definitions } from '../domain/index.js'
+import { buildSnapshot } from './snapshot.js'
+import { deltaPath, listMigrations, readFoldedSnapshot, snapshotDelta } from './history.js'
+import { diffSnapshots, diffOpTableName } from './diff.js'
+import { emitSQL } from './sql-emit.js'
+import { PARTITIONED_TRACE_TABLE_NAMES } from '../../trace/partition/tables.js'
+import { AUTH_TABLE_NAMES } from '../../auth/auth/schema.js'
+import { EMAIL_TABLE_NAMES } from '../../infra/email/schema.js'
+import { SCHEDULE_TABLE_NAMES } from '../../async/jobs/schedules-table.js'
+
+// Schema files are import()ed below. They may already be in Node's ESM module
+// cache because `discoverInstance` transitively pulled them in (any surface or
+// handler that imports a defined table loads the schema file along with it).
+// A second evaluation would call pipe.define() again and crash on the registry
+// duplicate-name guard, so we rely on the cache: previously-loaded files
+// resolve to their cached exports (define() has already populated the registry
+// from that first load); files reached only by the glob are evaluated fresh.
+
+export interface GenerateResult {
+  database: string
+  migrationFile: string | null
+  snapshotFile: string | null
+  statements: number
+}
+
+export async function generateForDatabase(
+  dbConfig: ResolvedDatabase,
+  migrationName?: string,
+  internalDefinitions?: () => Promise<Record<string, unknown>>,
+  doors: readonly ResolvedDoor[] | (() => readonly ResolvedDoor[]) = [],
+): Promise<GenerateResult> {
+  if (dbConfig.schema === undefined) {
+    throw new ConfigError(
+      `Database "${dbConfig.name}" has no schema path configured.`,
+      `Add a schema path to your database config:\n\n` +
+      `  databases: {\n` +
+      `    ${dbConfig.name}: {\n` +
+      `      url: '...',\n` +
+      `      schema: './src/db/schema.ts',  // <-- add this\n` +
+      `      migrations: '...',\n` +
+      `    },\n` +
+      `  }\n`,
+    )
+  }
+
+  if (dbConfig.migrations === undefined) {
+    throw new ConfigError(
+      `Database "${dbConfig.name}" has no migrations path configured.`,
+      `Add a migrations path to your database config:\n\n` +
+      `  databases: {\n` +
+      `    ${dbConfig.name}: {\n` +
+      `      url: '...',\n` +
+      `      schema: '...',\n` +
+      `      migrations: './migrations/${dbConfig.name}',  // <-- add this\n` +
+      `    },\n` +
+      `  }\n`,
+    )
+  }
+
+  const schemaFiles = await resolveSchemaFiles(dbConfig.schema, dbConfig.baseDir)
+
+  if (schemaFiles.length === 0) {
+    const patterns = Array.isArray(dbConfig.schema) ? dbConfig.schema.join(', ') : dbConfig.schema
+    throw new ConfigError(
+      `No schema files found for database "${dbConfig.name}".`,
+      `Pattern(s): ${patterns}\n\n  Check the "schema" path in your database config.`,
+    )
+  }
+
+  // ResolvedDatabase.migrations is absolute (resolved against baseDir at
+  // config-load time) — cwd plays no part.
+  const migrationsDir = dbConfig.migrations
+  const metaDir = join(migrationsDir, 'meta')
+
+  mkdirSync(metaDir, { recursive: true })
+
+  const imports: Record<string, unknown> = {}
+  for (const file of schemaFiles) {
+    const url = pathToFileURL(file).href
+    const mod: Record<string, unknown> = await import(url)
+    for (const [key, value] of Object.entries(mod)) {
+      imports[key] = value
+    }
+  }
+
+  // A thunk, invoked only AFTER the schema-file import loop: queue tables
+  // register at createQueue() time, and a queue module reached only by the
+  // schema glob registers during the loop above. Materializing the internal
+  // definitions before the imports (as the CLI once did) silently dropped
+  // those queues from the migration (D2, subseam audit 2026-07-16).
+  if (internalDefinitions !== undefined) {
+    for (const [key, value] of Object.entries(await internalDefinitions())) {
+      imports[key] = value
+    }
+  }
+
+  const prevSnapshot = readFoldedSnapshot(migrationsDir)
+  const currentSnapshot = buildSnapshot(imports, prevSnapshot.id)
+  // Doors are not tables, so the table diff never sees them: their policies are
+  // diffed against the doors the previous snapshot recorded.
+  const currentDoors = doorSnapshots(typeof doors === 'function' ? doors() : doors, dbConfig.rls?.platformRole, definitions())
+  const doorStatements = diffDoors(prevSnapshot.doors, currentDoors)
+  if (Object.keys(currentDoors).length > 0 || prevSnapshot.doors !== undefined) currentSnapshot.doors = currentDoors
+  const ops = diffSnapshots(prevSnapshot, currentSnapshot)
+  // Framework-owned partitioned tables (the trace family) stay in the snapshot
+  // but are never emitted into an application migration: they are PARTITION BY
+  // RANGE, and a bare CREATE TABLE leaves a partitioned table that rejects every
+  // insert with "no partition found". pipework provisions them — parent plus day
+  // partitions — itself. Issue #313.
+  const emittableOps = ops.filter(op => !PARTITIONED_TRACE_TABLE_NAMES.has(diffOpTableName(op)))
+  const statements = emitSQL(emittableOps).map(idempotentAuthTable)
+
+  if (statements.length === 0 && doorStatements.length === 0) {
+    return {
+      database: dbConfig.name,
+      migrationFile: null,
+      snapshotFile: null,
+      statements: 0,
+    }
+  }
+
+  const tag = freeTag(migrationsDir, migrationName)
+
+  const joined = statements.map(s => s + ';').join('\n')
+  const withTenantRls = dbConfig.rls !== undefined
+    ? generateRlsStatements(joined, definitions(), dbConfig.rls.sessionVar, dbConfig.rls.force)
+    : joined
+  // After the tenant policies: a door's policy goes on a table that is row-secured by then.
+  const withRls = doorStatements.length > 0
+    ? `${withTenantRls}${withTenantRls === '' ? '' : '\n\n'}${doorStatements.map(s => s + ';').join('\n')}`
+    : withTenantRls
+  const withAppendOnly = generateAppendOnlyStatements(withRls, definitions())
+  const sqlContent = postProcessMigration(withAppendOnly)
+  const migrationFile = join(migrationsDir, `${tag}.sql`)
+  writeFileSync(migrationFile, sqlContent, 'utf-8')
+
+  const snapshotFile = deltaPath(migrationsDir, tag)
+  writeFileSync(snapshotFile, JSON.stringify(snapshotDelta(prevSnapshot, currentSnapshot), null, 2), 'utf-8')
+
+  return {
+    database: dbConfig.name,
+    migrationFile,
+    snapshotFile,
+    statements: statements.length + doorStatements.length,
+  }
+}
+
+// The session, org, email and schedules tables predate their definitions: apps
+// copied them by hand from SQL files. Their CREATE statements are IF NOT EXISTS so the first
+// generated migration applies over those tables.
+const AUTH_CREATE_RE = /^CREATE\s+(TABLE|(?:UNIQUE\s+)?INDEX)\s+("(?:[^"]|"")+")(\s+ON\s+"([^"]+)")?/
+
+export function idempotentAuthTable(statement: string): string {
+  const m = AUTH_CREATE_RE.exec(statement)
+  if (m === null) return statement
+  const table = m[1] === 'TABLE' ? m[2]!.slice(1, -1) : m[4]
+  if (table === undefined || !(AUTH_TABLE_NAMES.has(table) || EMAIL_TABLE_NAMES.has(table) || SCHEDULE_TABLE_NAMES.has(table))) return statement
+  return statement.replace(AUTH_CREATE_RE, (_all, kind: string, name: string, on: string | undefined) =>
+    `CREATE ${kind} IF NOT EXISTS ${name}${on ?? ''}`)
+}
+
+/** `YYYYMMDDHHMMSS[_slug]` from the UTC clock, moved forward a second at a time until no migration holds that timestamp. */
+function freeTag(migrationsDir: string, name?: string): string {
+  const taken = new Set(listMigrations(migrationsDir).map(m => m.tag.slice(0, 14)))
+  const slug = name === undefined ? '' : name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '')
+  const at = new Date()
+  at.setUTCMilliseconds(0)
+  for (;;) {
+    const stamp = at.toISOString().replace(/\D/g, '').slice(0, 14)
+    if (!taken.has(stamp)) return slug === '' ? stamp : `${stamp}_${slug}`
+    at.setTime(at.getTime() + 1000)
+  }
+}
+
+async function resolveSchemaFiles(schema: string | string[], baseDir: string): Promise<string[]> {
+  const patterns = Array.isArray(schema) ? schema : [schema]
+  const files: string[] = []
+
+  for (const pattern of patterns) {
+    const abs = resolve(baseDir, pattern)
+    if (!pattern.includes('*')) {
+      if (existsSync(abs)) files.push(abs)
+    } else {
+      for await (const match of glob(pattern, { cwd: baseDir })) {
+        files.push(resolve(baseDir, match))
+      }
+    }
+  }
+
+  return [...new Set(files)].sort()
+}

package/src/data/migrate/history.ts

@@ -0,0 +1,215 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { EMPTY_SNAPSHOT, type PwSnapshot, type PwTableSnapshot, type PwPartitionSnapshot } from './snapshot.js'
+import type { DoorSnapshot } from './door-generate.js'
+
+export interface MigrationEntry {
+  tag: string
+  when: number
+}
+
+const LEGACY_TAG = /^\d{4}(_|$)/
+const TIMESTAMP_TAG = /^\d{14}(_|$)/
+
+type Sub<K extends keyof PwTableSnapshot> = Record<string, NonNullable<PwTableSnapshot[K]> extends Record<string, infer V> ? V | null : never>
+
+export interface TableDelta {
+  name: string
+  schema: string
+  partitionBy: PwPartitionSnapshot | null
+  columns: Sub<'columns'>
+  indexes: Sub<'indexes'>
+  foreignKeys: Sub<'foreignKeys'>
+  checks: Sub<'checks'>
+  uniqueConstraints: Sub<'uniqueConstraints'>
+  compositePrimaryKeys: Sub<'compositePrimaryKeys'>
+}
+
+export interface SnapshotDelta {
+  version: 'pw1-delta'
+  tables: Record<string, TableDelta | null>
+  doors?: Record<string, DoorSnapshot | null>
+}
+
+const MAP_KEYS = ['columns', 'indexes', 'foreignKeys', 'checks', 'uniqueConstraints', 'compositePrimaryKeys'] as const
+
+function readLegacyJournal(folder: string): { tag: string; when: number }[] | null {
+  const path = join(folder, 'meta', '_journal.json')
+  if (!existsSync(path)) return null
+  const journal = JSON.parse(readFileSync(path, 'utf-8')) as { entries?: { tag: string; when: number }[] }
+  return journal.entries ?? []
+}
+
+/** The folder's migrations in apply order: legacy `NNNN` tags by index, then timestamp tags by time. */
+export function listMigrations(folder: string): MigrationEntry[] {
+  if (!existsSync(folder)) return []
+  const tags = readdirSync(folder, { withFileTypes: true })
+    .filter(e => e.isFile() && e.name.endsWith('.sql'))
+    .map(e => e.name.slice(0, -'.sql'.length))
+
+  const legacy: string[] = []
+  const stamped: string[] = []
+  for (const tag of tags) {
+    if (TIMESTAMP_TAG.test(tag)) stamped.push(tag)
+    else if (LEGACY_TAG.test(tag)) legacy.push(tag)
+    else {
+      throw new Error(
+        `Migration file "${tag}.sql" in ${folder} is not named like a migration. ` +
+          `Expected "NNNN_name.sql" (legacy index) or "YYYYMMDDHHMMSS_name.sql" (UTC timestamp).`,
+      )
+    }
+  }
+  const byText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
+  legacy.sort((a, b) => Number(a.slice(0, 4)) - Number(b.slice(0, 4)) || byText(a, b))
+  stamped.sort((a, b) => byText(a.slice(0, 14), b.slice(0, 14)) || byText(a, b))
+
+  const journal = readLegacyJournal(folder)
+  if (journal !== null) {
+    for (const entry of journal) {
+      const path = `${folder}/${entry.tag}.sql`
+      if (!existsSync(path)) throw new Error(`Missing migration file: ${path}`)
+    }
+  }
+  const journalWhen = new Map((journal ?? []).map(e => [e.tag, e.when]))
+
+  return [
+    ...legacy.map(tag => ({ tag, when: journalWhen.get(tag) ?? Number(tag.slice(0, 4)) })),
+    ...stamped.map(tag => ({ tag, when: timestampMillis(tag) })),
+  ]
+}
+
+export function timestampMillis(tag: string): number {
+  const p = (from: number, to: number): number => Number(tag.slice(from, to))
+  return Date.UTC(p(0, 4), p(4, 6) - 1, p(6, 8), p(8, 10), p(10, 12), p(12, 14))
+}
+
+export function isTimestampTag(tag: string): boolean {
+  return TIMESTAMP_TAG.test(tag)
+}
+
+export function deltaPath(folder: string, tag: string): string {
+  return join(folder, 'meta', `${tag}.delta.json`)
+}
+
+function stable(value: unknown): string {
+  return JSON.stringify(value, (_key, v: unknown) => {
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+    }
+    return v
+  })
+}
+
+function same(a: unknown, b: unknown): boolean {
+  return stable(a) === stable(b)
+}
+
+function diffMap<V>(prev: Record<string, V>, next: Record<string, V>): Record<string, V | null> {
+  const out: Record<string, V | null> = {}
+  for (const [key, value] of Object.entries(next)) {
+    if (!(key in prev) || !same(prev[key], value)) out[key] = value
+  }
+  for (const key of Object.keys(prev)) {
+    if (!(key in next)) out[key] = null
+  }
+  return out
+}
+
+/** The element-level change from one snapshot to the next; only changed tables, elements and doors appear. */
+export function snapshotDelta(prev: PwSnapshot, next: PwSnapshot): SnapshotDelta {
+  const tables: Record<string, TableDelta | null> = {}
+  for (const [key, table] of Object.entries(next.tables)) {
+    const before = prev.tables[key]
+    const empty = before === undefined
+    const delta = {
+      name: table.name,
+      schema: table.schema,
+      partitionBy: table.partitionBy ?? null,
+      columns: diffMap(before?.columns ?? {}, table.columns),
+      indexes: diffMap(before?.indexes ?? {}, table.indexes),
+      foreignKeys: diffMap(before?.foreignKeys ?? {}, table.foreignKeys),
+      checks: diffMap(before?.checks ?? {}, table.checks),
+      uniqueConstraints: diffMap(before?.uniqueConstraints ?? {}, table.uniqueConstraints),
+      compositePrimaryKeys: diffMap(before?.compositePrimaryKeys ?? {}, table.compositePrimaryKeys),
+    } as TableDelta
+    const changed = empty
+      || before.name !== table.name
+      || before.schema !== table.schema
+      || !same(before.partitionBy ?? null, delta.partitionBy)
+      || MAP_KEYS.some(k => Object.keys(delta[k]).length > 0)
+    if (changed) tables[key] = delta
+  }
+  for (const key of Object.keys(prev.tables)) {
+    if (!(key in next.tables)) tables[key] = null
+  }
+
+  const delta: SnapshotDelta = { version: 'pw1-delta', tables }
+  if (next.doors !== undefined || prev.doors !== undefined) {
+    const doors = diffMap<DoorSnapshot>(prev.doors ?? {}, next.doors ?? {})
+    if (Object.keys(doors).length > 0) delta.doors = doors
+  }
+  return delta
+}
+
+function applyMap<V>(base: Record<string, V>, changes: Record<string, V | null>): Record<string, V> {
+  const out: Record<string, V> = { ...base }
+  for (const [key, value] of Object.entries(changes)) {
+    if (value === null) delete out[key]
+    else out[key] = value
+  }
+  return out
+}
+
+/** `snap` with `delta` applied. Pure: the input is not modified. */
+export function applyDelta(snap: PwSnapshot, delta: SnapshotDelta): PwSnapshot {
+  const tables: Record<string, PwTableSnapshot> = { ...snap.tables }
+  for (const [key, change] of Object.entries(delta.tables)) {
+    if (change === null) {
+      delete tables[key]
+      continue
+    }
+    const base = tables[key]
+    tables[key] = {
+      name: change.name,
+      schema: change.schema,
+      columns: applyMap(base?.columns ?? {}, change.columns),
+      indexes: applyMap(base?.indexes ?? {}, change.indexes),
+      foreignKeys: applyMap(base?.foreignKeys ?? {}, change.foreignKeys),
+      checks: applyMap(base?.checks ?? {}, change.checks),
+      uniqueConstraints: applyMap(base?.uniqueConstraints ?? {}, change.uniqueConstraints),
+      compositePrimaryKeys: applyMap(base?.compositePrimaryKeys ?? {}, change.compositePrimaryKeys),
+      partitionBy: change.partitionBy ?? undefined,
+    }
+  }
+  const result: PwSnapshot = { ...snap, tables }
+  if (delta.doors !== undefined) {
+    result.doors = applyMap<DoorSnapshot>(snap.doors ?? {}, delta.doors) as NonNullable<PwSnapshot['doors']>
+  }
+  return result
+}
+
+/** The schema as of every migration in the folder: the legacy snapshot, then each timestamp migration's delta. */
+export function readFoldedSnapshot(folder: string): PwSnapshot {
+  let snap = readLegacySnapshot(folder)
+  for (const { tag } of listMigrations(folder)) {
+    if (!isTimestampTag(tag)) continue
+    const path = deltaPath(folder, tag)
+    if (!existsSync(path)) {
+      throw new Error(`Missing snapshot delta ${path} for migration ${tag}.sql; the delta is written beside the migration by \`pipework generate\` and is committed with it.`)
+    }
+    snap = applyDelta(snap, JSON.parse(readFileSync(path, 'utf-8')) as SnapshotDelta)
+  }
+  return snap
+}
+
+function readLegacySnapshot(folder: string): PwSnapshot {
+  const journal = readLegacyJournal(folder)
+  if (journal === null || journal.length === 0) return EMPTY_SNAPSHOT
+  const last = journal[journal.length - 1] as { idx?: number }
+  const idx = last.idx ?? journal.length - 1
+  const path = join(folder, 'meta', `${String(idx).padStart(4, '0')}_snapshot.json`)
+  if (!existsSync(path)) return EMPTY_SNAPSHOT
+  const raw = JSON.parse(readFileSync(path, 'utf-8')) as { version?: string }
+  if (raw.version === '7') return EMPTY_SNAPSHOT
+  return raw as PwSnapshot
+}

package/src/data/migrate/index.ts

@@ -0,0 +1,9 @@
+export { migrateAll, migrateOne, UnsafeMigrationError, type MigrateResult, type MigrateOptions } from './run.js'
+export { checkMigrations, formatCheckResult, type MigrationCheckResult, type FileHazards, type MigrationHazard, type Severity } from './check.js'
+export { hasPragma, PRAGMA_FOR, type PragmaKind } from './pragma.js'
+export { readAppliedState, type AppliedState } from './applied.js'
+export { analyzeSQL } from './safety.js'
+export { generateForDatabase, type GenerateResult } from './generate.js'
+export { postProcessMigration } from './post-process.js'
+export { generateRlsStatements } from './rls-generate.js'
+export { generateAppendOnlyStatements } from './append-only-generate.js'

package/src/data/migrate/internal-definitions.ts

@@ -0,0 +1,175 @@
+// Pipework ships table DEFINITIONS for its own substrate — `trace`,
+// `trace_step`, `trace_retained`, `trace_step_retained`, `audit_record` — but
+// the migration generator only sees the consumer's `schema.ts` exports. Without
+// this loader, enabling `trace: {}` or `audit: {}` in a blueprint produces a
+// runtime crash on the first traced operation because the tables never reached
+// the consumer's database. Loading is gated by the blueprint flags and by
+// `isDefaultDatabase` because trace/audit always write to the default db.
+
+import type { Blueprint } from '../../core/config/schema.js'
+
+export async function loadInternalDefinitions(
+  blueprint: Blueprint,
+  options: { isDefaultDatabase: boolean },
+): Promise<Record<string, unknown>> {
+  if (!options.isDefaultDatabase) return {}
+
+  const result: Record<string, unknown> = {}
+
+  if (blueprint.trace !== undefined) {
+    const { trace } = await import('../../trace/schema/trace.js')
+    const { traceStep } = await import('../../trace/schema/trace-step.js')
+    const { traceRetained } = await import('../../trace/schema/trace-retained.js')
+    const { traceStepRetained } = await import('../../trace/schema/trace-step-retained.js')
+    result['__pipework_trace'] = trace
+    result['__pipework_trace_step'] = traceStep
+    result['__pipework_trace_retained'] = traceRetained
+    result['__pipework_trace_step_retained'] = traceStepRetained
+  }
+
+  if (blueprint.audit !== undefined) {
+    const { auditRecord } = await import('../../audit/schema/audit-record.js')
+    result['__pipework_audit_record'] = auditRecord
+  }
+
+  if (blueprint.valve !== undefined) {
+    const { valveCrossing } = await import('../valve/schema/valve-crossing.js')
+    result['__pipework_valve_crossing'] = valveCrossing
+  }
+
+  if (blueprint.accessLinks !== undefined) {
+    const { accessLinkCode, accessLink, accessLinkUse, accessLinkCheckSpent, accessLinkMiss } = await import('../../infra/access-links/schema.js')
+    result['__pipework_access_link_code'] = accessLinkCode
+    result['__pipework_access_link'] = accessLink
+    result['__pipework_access_link_use'] = accessLinkUse
+    result['__pipework_access_link_check_spent'] = accessLinkCheckSpent
+    result['__pipework_access_link_miss'] = accessLinkMiss
+  }
+
+  if (blueprint.joinRequests !== undefined) {
+    const { joinRequest } = await import('../../infra/join-requests/schema.js')
+    result['__pipework_join_request'] = joinRequest
+  }
+
+  if (blueprint.credits !== undefined) {
+    const { creditGrant, creditReservation, creditDraw, creditLedger, creditAccount } = await import('../../infra/credits/schema.js')
+    result['__pipework_credit_grant'] = creditGrant
+    result['__pipework_credit_reservation'] = creditReservation
+    result['__pipework_credit_draw'] = creditDraw
+    result['__pipework_credit_ledger'] = creditLedger
+    result['__pipework_credit_account'] = creditAccount
+  }
+
+  if (blueprint.creditLine !== undefined) {
+    const {
+      creditLine, creditLineReservation, creditLineEntry, creditLinePayment, creditLinePaymentApplication, creditLineAuthorization,
+    } = await import('../../infra/credit-line/schema.js')
+    result['__pipework_credit_line'] = creditLine
+    result['__pipework_credit_line_reservation'] = creditLineReservation
+    result['__pipework_credit_line_entry'] = creditLineEntry
+    result['__pipework_credit_line_payment'] = creditLinePayment
+    result['__pipework_credit_line_payment_application'] = creditLinePaymentApplication
+    result['__pipework_credit_line_authorization'] = creditLineAuthorization
+  }
+
+  if (blueprint.quota !== undefined) {
+    const { outboundQuota } = await import('../../infra/quota/schema.js')
+    result['__pipework_outbound_quota'] = outboundQuota
+  }
+
+  if (blueprint.storage !== undefined) {
+    const { storageFile } = await import('../../infra/storage/schema.js')
+    result['__pipework_storage_file'] = storageFile
+  }
+
+  if (blueprint.crawl !== undefined) {
+    const { crawls, crawlUrls, crawlHosts, crawlResources } = await import('../../infra/crawl/schema.js')
+    result['__pipework_crawl'] = crawls
+    result['__pipework_crawl_url'] = crawlUrls
+    result['__pipework_crawl_host'] = crawlHosts
+    result['__pipework_crawl_resource'] = crawlResources
+  }
+
+  if (blueprint.alerts !== undefined) {
+    const { alerts, alertOccurrences, alertDeliveries, alertSourceState, unitFaults, loopBeats, faults } = await import('../../infra/alerts/schema.js')
+    result['__pipework_alerts'] = alerts
+    result['__pipework_alert_occurrences'] = alertOccurrences
+    result['__pipework_alert_deliveries'] = alertDeliveries
+    result['__pipework_alert_source_state'] = alertSourceState
+    result['__pipework_unit_faults'] = unitFaults
+    result['__pipework_loop_beats'] = loopBeats
+    result['__pipework_faults'] = faults
+  }
+
+  if (blueprint.support !== undefined) {
+    const { supportTicket, supportMessage, supportLink, supportEventDelivery } = await import('../../infra/support/schema.js')
+    result['__pipework_support_ticket'] = supportTicket
+    result['__pipework_support_message'] = supportMessage
+    result['__pipework_support_link'] = supportLink
+    result['__pipework_support_event_delivery'] = supportEventDelivery
+  }
+
+  if (blueprint.sessions !== undefined) {
+    const { refreshTokens, authVersions } = await import('../../auth/auth/schema.js')
+    result['__pipework_refresh_tokens'] = refreshTokens
+    result['__pipework_auth_versions'] = authVersions
+  }
+
+  if (blueprint.orgs !== undefined) {
+    const { userOrgs } = await import('../../auth/auth/schema.js')
+    result['__pipework_user_orgs'] = userOrgs
+  }
+
+  if (blueprint.passwords !== undefined) {
+    const { signinAttempts } = await import('../../auth/auth/schema.js')
+    result['__pipework_signin_attempts'] = signinAttempts
+  }
+
+  if (blueprint.guards !== undefined) {
+    const { guardAttempts } = await import('../../auth/auth/schema.js')
+    result['__pipework_guard_attempts'] = guardAttempts
+  }
+
+  if (blueprint.emailLinks !== undefined) {
+    const { emailLinks, emailLinkRequests } = await import('../../auth/auth/schema.js')
+    result['__pipework_email_links'] = emailLinks
+    result['__pipework_email_link_requests'] = emailLinkRequests
+  }
+
+  if (blueprint.rateLimits !== undefined) {
+    const { rateLimitCounts } = await import('../../request/http/rate-limit-classes.js')
+    result['__pipework_rate_limit_counts'] = rateLimitCounts
+  }
+
+  if (blueprint.email !== undefined) {
+    const { emailMessages, emailSuppressions, emailInbound, emailUnsubscribes } = await import('../../infra/email/schema.js')
+    result['__pipework_email_messages'] = emailMessages
+    result['__pipework_email_suppressions'] = emailSuppressions
+    result['__pipework_email_inbound'] = emailInbound
+    result['__pipework_email_unsubscribes'] = emailUnsubscribes
+  }
+
+  // Queue tables register at createQueue() time (worker surfaces create their
+  // queue at construction, so config discovery populates the registry before
+  // generate snapshots). No blueprint flag — presence in the registry means a
+  // queue is in use. Like trace/audit, queue tables are only emitted into the
+  // default database's migrations.
+  const { queueDefinitions } = await import('../../async/jobs/table.js')
+  for (const [name, definition] of queueDefinitions()) {
+    result[`__pipework_queue_${name}`] = definition
+  }
+
+  // Registered when a step graph is defined.
+  const { stepDefinitions } = await import('../../async/steps/table.js')
+  for (const [name, definition] of stepDefinitions()) {
+    result[`__pipework_${name}`] = definition
+  }
+
+  // Registered when a worker surface declaring schedules is constructed.
+  const { schedulesDefinitions } = await import('../../async/jobs/schedules-table.js')
+  for (const [name, definition] of schedulesDefinitions()) {
+    result[`__pipework_${name}`] = definition
+  }
+
+  return result
+}

package/src/data/migrate/post-process.ts

@@ -0,0 +1,73 @@
+import { stripComments, codeStartOffset } from './statements.js'
+
+const CREATE_INDEX_RE = /\bCREATE\s+(UNIQUE\s+)?INDEX\b(?!\s+CONCURRENTLY)/i
+const CONCURRENTLY_RE = /\bCONCURRENTLY\b/i
+
+const NO_TRANSACTION_PRAGMA = '-- pipework:no-transaction'
+
+/**
+ * Transform unsafe migration SQL emitted by the diff/sql-emit pipeline into
+ * safe SQL.
+ *
+ * `CREATE INDEX` → `CREATE INDEX CONCURRENTLY`, and the
+ * `-- pipework:no-transaction` pragma is prepended so the runner applies the
+ * migration outside a transaction (CONCURRENTLY cannot run inside one).
+ *
+ * Foreign-key safety (`NOT VALID` + `VALIDATE CONSTRAINT`) is decided upstream
+ * in `emitSQL`: Postgres rejects `NOT VALID` foreign keys on partitioned
+ * tables, and only the op metadata knows which tables are partitioned. A
+ * text-level pass here cannot tell, so it must not touch foreign keys. Issue #312.
+ */
+export function postProcessMigration(sql: string): string {
+  const parts = sql.split(';')
+  const trailing = parts[parts.length - 1]
+  const rawStatements = parts.slice(0, -1)
+
+  const outputStatements: string[] = []
+  let hasConcurrently = false
+
+  for (const raw of rawStatements) {
+    // Match against the SQL with comments removed, not against the raw
+    // fragment. A statement and the comment above it share a `;`-fragment, so
+    // skipping fragments that *start with* `--` skipped the statement too and
+    // a commented CREATE INDEX silently kept its exclusive lock (#334).
+    // Comment text is equally unable to fake a match it should not have.
+    const code = stripComments(raw)
+    if (code.trim().length === 0) {
+      outputStatements.push(raw)
+      continue
+    }
+
+    if (CREATE_INDEX_RE.test(code)) {
+      // Rewrite only from where the SQL actually starts, so a leading comment
+      // that happens to say "CREATE INDEX" is not the thing rewritten.
+      const offset = codeStartOffset(raw)
+      const rewritten =
+        raw.slice(0, offset) +
+        raw.slice(offset).replace(/\b(CREATE\s+(?:UNIQUE\s+)?)(INDEX)\b/i, '$1$2 CONCURRENTLY')
+      outputStatements.push(rewritten)
+      hasConcurrently = true
+      continue
+    }
+
+    if (CONCURRENTLY_RE.test(code)) {
+      hasConcurrently = true
+    }
+
+    outputStatements.push(raw)
+  }
+
+  let result = outputStatements.join(';') + ';'
+
+  if (trailing !== undefined && trailing.trim().length > 0) {
+    result += trailing
+  }
+
+  if (hasConcurrently) {
+    result = result.startsWith(NO_TRANSACTION_PRAGMA)
+      ? result
+      : `${NO_TRANSACTION_PRAGMA}\n${result}`
+  }
+
+  return result
+}