pipework 0.251.0 → 0.252.1

package/src/core/validation/domain.ts

@@ -0,0 +1,99 @@
+import type { DefinedTable } from '../../data/domain/types.js'
+import { resolveDefinitionRef } from '../../data/domain/types.js'
+import type { ValidationIssue } from './types.js'
+
+function inheritsBrandFromCompositeFK(def: DefinedTable, fieldName: string, brand: string): boolean {
+  for (const fk of def.$options.foreignKeys ?? []) {
+    const i = fk.columns.indexOf(fieldName)
+    if (i === -1) continue
+    const foreignKey = fk.references.columns[i]
+    if (foreignKey === undefined) continue
+    if (resolveDefinitionRef(fk.references.definition).$fields[foreignKey]?._meta.brand === brand) return true
+  }
+  return false
+}
+
+export function validateDomainIntegrity(
+  definitions: ReadonlyMap<string, DefinedTable>,
+  configuredDatabases: readonly string[],
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+
+  const tableNames = new Map<string, string>()
+  const brandNames = new Map<string, string>()
+
+  for (const [name, def] of definitions) {
+    if (def.$options.virtual === true) continue
+
+    if (tableNames.has(name)) {
+      issues.push({
+        phase: 'domain',
+        message: `"${name}" table name conflicts with "${tableNames.get(name)!}"`,
+      })
+    } else {
+      tableNames.set(name, name)
+    }
+
+    if (def.$options.database !== undefined) {
+      if (!configuredDatabases.includes(def.$options.database)) {
+        issues.push({
+          phase: 'domain',
+          message: `${name}.database "${def.$options.database}" is not a configured database`,
+        })
+      }
+    }
+
+    let tenantFieldCount = 0
+
+    for (const [fieldName, descriptor] of Object.entries(def.$fields)) {
+      const meta = descriptor._meta
+
+      if (meta.tenant) tenantFieldCount++
+
+      if (meta.reference !== undefined) {
+        const refDef = resolveDefinitionRef(meta.reference.definition)
+        if (!definitions.has(refDef.$name)) {
+          issues.push({
+            phase: 'domain',
+            message: `${name}.${fieldName} references "${refDef.$name}" — no matching domain definition`,
+          })
+        }
+
+        const refField = refDef.$fields[meta.reference.field]
+        if (refField === undefined) {
+          issues.push({
+            phase: 'domain',
+            message: `${name}.${fieldName} references "${refDef.$name}.${meta.reference.field}" — field does not exist`,
+          })
+        }
+      }
+
+      if (meta.brand !== undefined) {
+        const isInheritedFromFK = (meta.reference !== undefined
+          && resolveDefinitionRef(meta.reference.definition).$fields[meta.reference.field]?._meta.brand === meta.brand)
+          || inheritsBrandFromCompositeFK(def, fieldName, meta.brand)
+
+        if (!isInheritedFromFK) {
+          const existing = brandNames.get(meta.brand)
+          if (existing !== undefined && existing !== `${name}.${fieldName}`) {
+            issues.push({
+              phase: 'domain',
+              message: `brand "${meta.brand}" used by both ${existing} and ${name}.${fieldName}`,
+            })
+          } else {
+            brandNames.set(meta.brand, `${name}.${fieldName}`)
+          }
+        }
+      }
+    }
+
+    if (tenantFieldCount > 1) {
+      issues.push({
+        phase: 'domain',
+        message: `${name} has ${String(tenantFieldCount)} tenant fields — exactly one expected`,
+      })
+    }
+  }
+
+  return issues
+}

package/src/core/validation/index.ts

@@ -0,0 +1,5 @@
+export { validateStartup, type ValidationContext } from './startup.js'
+export { validateDomainIntegrity } from './domain.js'
+export { collectSurfaceIssues } from './surfaces.js'
+export { validateConnectivity } from './connectivity.js'
+export { StartupValidationError, type ValidationIssue, type ValidationPhase } from './types.js'

package/src/core/validation/queue-tables.ts

@@ -0,0 +1,312 @@
+import type { ValidationIssue } from './types.js'
+import type { ResolvedDatabase } from '../config/load.js'
+import { probeConnectTimeout } from './connectivity.js'
+import { queueDefinitions, queueProgressColumns } from '../../async/jobs/table.js'
+import { getTableColumns } from '../../data/query/index.js'
+
+// D2 residual risk (subseam audit 2026-07-16): a queue whose module is in no
+// schema glob and no import chain reaches the registry at runtime (createQueue
+// runs when the worker imports it) but never reached a migration — so the
+// first enqueue in production failed on a missing relation. This check makes
+// that state loud at startup and at test bootstrap instead.
+//
+// The same story one level down: a table that exists but predates the current
+// queue definition (0.26.0 added claim_token) fails at the first claim() with
+// a raw 42703. So the shape is compared too. Extra columns are ignored on
+// purpose — a consumer may add their own columns to a queue table; only
+// columns the definition requires and the table lacks are reported.
+//
+// One level down again: a column can be present under the right name and
+// still be the wrong column. `ALTER COLUMN ... SET DATA TYPE` / `DROP NOT
+// NULL` are migration steps a consumer can skip exactly as they can skip an
+// ADD COLUMN, and the result is quieter: claim_token as text compares wrong
+// against a uuid rather than erroring, so a fence built on it silently never
+// matches. See columnDrift() for what counts as compatible.
+
+/** A required column whose type or nullability in the database contradicts the definition. */
+export interface QueueColumnDrift {
+  readonly column: string
+  /** Present when the type differs; the definition's spelling and the database's. */
+  readonly requiredType?: string
+  readonly foundType?: string
+  /** True when the definition requires NOT NULL and the column is nullable. */
+  readonly nullableButRequired?: boolean
+}
+
+/** A registered queue table that is absent, or present with columns missing or drifted. */
+export interface QueueTableProblem {
+  readonly table: string
+  /** Empty when the table itself is absent. */
+  readonly missingColumns: readonly string[]
+  /** Omitted entirely when no present column has drifted. */
+  readonly driftedColumns?: readonly QueueColumnDrift[]
+  /** The configured `progressColumn` when the table lacks it. */
+  readonly missingProgressColumn?: string
+}
+
+export function queueProgressColumnMessage(table: string, database: string, column: string): string {
+  return (
+    `queue table "${table}" in database "${database}" is missing column "${column}", which ` +
+    `createQueue({ progressColumn: '${column}' }) records as each claim's progressMark. ` +
+    `It is a column of your own: add it with a migration of your schema, then run \`pipework migrate\`.`
+  )
+}
+
+export function queueTableMessage(table: string, database: string): string {
+  return (
+    `queue table "${table}" is registered (createQueue) but does not exist in database "${database}". ` +
+    `The module calling createQueue({ table: '${table}' }) must be reachable from the database's ` +
+    `schema glob (or imported by a schema file) so \`pipework generate\` emits its migration. ` +
+    `Add it to the schema patterns, run \`pipework generate\`, then \`pipework migrate\`.`
+  )
+}
+
+export function queueColumnsMessage(table: string, database: string, missing: readonly string[]): string {
+  const columns = missing.map(c => `"${c}"`).join(', ')
+  const plural = missing.length === 1 ? 'column' : 'columns'
+  return (
+    `queue table "${table}" in database "${database}" is missing ${plural} ${columns}, which the queue ` +
+    `definition requires. The table predates the current definition — its migration has not been ` +
+    `regenerated or applied. Run \`pipework generate\`, then \`pipework migrate\`. ` +
+    `(Extra columns of your own are fine; only missing ones are reported.)`
+  )
+}
+
+function driftClause(drift: QueueColumnDrift): string {
+  const parts: string[] = []
+  if (drift.requiredType !== undefined && drift.foundType !== undefined) {
+    parts.push(`requires ${drift.requiredType} but the database has ${drift.foundType}`)
+  }
+  if (drift.nullableButRequired === true) {
+    parts.push('requires NOT NULL but the database allows nulls')
+  }
+  return `"${drift.column}" ${parts.join(', and ')}`
+}
+
+export function queueColumnDriftMessage(
+  table: string,
+  database: string,
+  drifted: readonly QueueColumnDrift[],
+): string {
+  const plural = drifted.length === 1 ? 'column' : 'columns'
+  return (
+    `queue table "${table}" in database "${database}" has ${plural} the queue definition disagrees with: ` +
+    `${drifted.map(driftClause).join('; ')}. The table predates the current definition — the migration ` +
+    `that alters ${drifted.length === 1 ? 'it' : 'them'} has not been regenerated or applied. ` +
+    `Run \`pipework generate\`, then \`pipework migrate\`. ` +
+    `(Length and precision are not compared, and a column stricter than the definition asks is fine.)`
+  )
+}
+
+/** The message for one problem, whichever kinds it carries. */
+export function queueTableProblemMessage(problem: QueueTableProblem, database: string): string {
+  if (problem.missingColumns.length === 0 && (problem.driftedColumns ?? []).length === 0 && problem.missingProgressColumn === undefined) {
+    return queueTableMessage(problem.table, database)
+  }
+  const parts: string[] = []
+  if (problem.missingColumns.length > 0) {
+    parts.push(queueColumnsMessage(problem.table, database, problem.missingColumns))
+  }
+  if (problem.driftedColumns !== undefined && problem.driftedColumns.length > 0) {
+    parts.push(queueColumnDriftMessage(problem.table, database, problem.driftedColumns))
+  }
+  if (problem.missingProgressColumn !== undefined) {
+    parts.push(queueProgressColumnMessage(problem.table, database, problem.missingProgressColumn))
+  }
+  return parts.join(' ')
+}
+
+interface RequiredColumn {
+  readonly name: string
+  /** The definition's own spelling, e.g. "timestamp with time zone"; resolved to an OID by Postgres. */
+  readonly sqlType: string
+  readonly notNull: boolean
+}
+
+/** Columns the definition requires — read off the table it builds, never a second list. */
+function requiredColumns(): Map<string, readonly RequiredColumn[]> {
+  const required = new Map<string, readonly RequiredColumn[]>()
+  for (const [table, definition] of queueDefinitions()) {
+    const columns = Object.values(getTableColumns(definition.table())).map(c => ({
+      name: c.name,
+      sqlType: c.getSQLType(),
+      notNull: c.notNull,
+    }))
+    required.set(table, columns)
+  }
+  return required
+}
+
+interface ActualColumn {
+  readonly typeOid: number
+  /** format_type without a typmod: the found type spelled as the definition spells it. */
+  readonly typeName: string
+  readonly notNull: boolean
+}
+
+/**
+ * What counts as compatible, and why:
+ *
+ * - Type is compared as canonical type identity, not spelling: the
+ *   definition's declared type is resolved through Postgres's own
+ *   `to_regtype` and the resulting OID compared against the column's
+ *   `atttypid`. `timestamptz` and `timestamp with time zone` are then the
+ *   same thing without a hand-maintained alias table that can rot. A type
+ *   Postgres cannot resolve (to_regtype returns NULL — an enum or domain the
+ *   database has not got) is not reported as drift: the missing type would
+ *   have shown up as a missing table or column, and guessing here would
+ *   report false drift. Note the arm swallows a pseudo-type too: `serial` is
+ *   not a type Postgres resolves, so a column ever declared that way would be
+ *   skipped silently, with no missing column to reveal it.
+ * - Type modifiers (length, precision) are ignored. varchar(64) vs
+ *   varchar(128) is not reported: comparing typmod invites false drift on
+ *   healthy tables, and a check that cries wolf gets switched off, which
+ *   leaves things worse than not checking at all.
+ * - Nullability is reported in one direction only. A column the definition
+ *   requires NOT NULL that is nullable in the database breaks a promise the
+ *   definition makes, so it is reported. Stricter in the database than the
+ *   definition asks cannot violate anything the definition promises, and a
+ *   consumer may have tightened it deliberately, so it is not.
+ * - Defaults are not compared at all (out of scope for 0.28.0).
+ */
+function columnDrift(
+  required: RequiredColumn,
+  actual: ActualColumn,
+  expectedOid: number | undefined,
+): QueueColumnDrift | undefined {
+  const typeDiffers = expectedOid !== undefined && expectedOid !== actual.typeOid
+  const nullableButRequired = required.notNull && !actual.notNull
+  if (!typeDiffers && !nullableButRequired) return undefined
+  return {
+    column: required.name,
+    ...(typeDiffers ? { requiredType: required.sqlType, foundType: actual.typeName } : {}),
+    ...(nullableButRequired ? { nullableButRequired: true } : {}),
+  }
+}
+
+/**
+ * Registered queue tables that are absent from the database at `url`, or
+ * present without every column their definition requires, or present with a
+ * required column whose type or nullability contradicts the definition.
+ * Opens a short-lived probe connection, mirroring validateConnectivity. Two
+ * queries total, whatever the number of queues. `timeoutMs: null` leaves the
+ * connect timeout to the driver (PGCONNECT_TIMEOUT, else 30 s).
+ */
+export async function queueTableProblems(url: string, timeoutMs: number | null = 5000): Promise<QueueTableProblem[]> {
+  const required = requiredColumns()
+  const tables = [...required.keys()]
+  if (tables.length === 0) return []
+
+  const { default: postgres } = await import('postgres')
+  const sql = postgres(url, {
+    max: 1,
+    idle_timeout: 1,
+    ...probeConnectTimeout(timeoutMs),
+    onnotice: () => {},
+  })
+
+  try {
+    const presence = await sql<{ name: string; present: boolean }[]>`
+      SELECT t.name, to_regclass('public.' || quote_ident(t.name)) IS NOT NULL AS present
+      FROM unnest(${tables}::text[]) AS t(name)
+    `
+    const present = new Set(presence.filter(r => r.present).map(r => r.name))
+
+    const actual = new Map<string, Map<string, ActualColumn>>()
+    const expectedOids = new Map<string, number>()
+    const typeNames = [...new Set(
+      [...present].flatMap(t => (required.get(t) ?? []).map(c => c.sqlType)),
+    )]
+    if (present.size > 0) {
+      // pg_attribute, not information_schema.columns: that view is filtered to
+      // columns the current role holds a privilege on, so a role with CONNECT
+      // and USAGE but no table grants would read zero columns and be told to
+      // migrate when the cure is a GRANT. attnum > 0 AND NOT attisdropped
+      // excludes system and dropped columns. The definition's declared types
+      // are canonicalised by the same round trip (to_regtype), so this stays
+      // two queries whatever the number of queues; format_type without a
+      // typmod prints the found type the way the definition spells it.
+      const [row] = await sql<{
+        columns: { table_name: string; column_name: string; type_oid: number; not_null: boolean; type_name: string }[]
+        types: { name: string; oid: number | null }[]
+      }[]>`
+        SELECT
+          (
+            SELECT coalesce(json_agg(json_build_object(
+              'table_name', c.relname, 'column_name', a.attname,
+              'type_oid', a.atttypid::int, 'not_null', a.attnotnull,
+              'type_name', format_type(a.atttypid, NULL)
+            )), '[]'::json)
+            FROM pg_attribute a
+            JOIN pg_class c ON c.oid = a.attrelid
+            JOIN pg_namespace n ON n.oid = c.relnamespace
+            WHERE n.nspname = 'public' AND c.relname = ANY(${[...present]}::text[])
+              AND a.attnum > 0 AND NOT a.attisdropped
+          ) AS columns,
+          (
+            SELECT coalesce(json_agg(json_build_object('name', t, 'oid', to_regtype(t)::oid::int)), '[]'::json)
+            FROM unnest(${typeNames}::text[]) AS t
+          ) AS types
+      `
+      for (const column of row?.columns ?? []) {
+        let columns = actual.get(column.table_name)
+        if (columns === undefined) { columns = new Map(); actual.set(column.table_name, columns) }
+        columns.set(column.column_name, {
+          typeOid: column.type_oid,
+          typeName: column.type_name,
+          notNull: column.not_null,
+        })
+      }
+      for (const type of row?.types ?? []) {
+        if (type.oid !== null && type.oid !== 0) expectedOids.set(type.name, type.oid)
+      }
+    }
+
+    const problems: QueueTableProblem[] = []
+    for (const table of tables) {
+      if (!present.has(table)) {
+        problems.push({ table, missingColumns: [] })
+        continue
+      }
+      const have = actual.get(table) ?? new Map<string, ActualColumn>()
+      const missing: string[] = []
+      const drifted: QueueColumnDrift[] = []
+      for (const column of required.get(table) ?? []) {
+        const found = have.get(column.name)
+        if (found === undefined) { missing.push(column.name); continue }
+        // The unprivileged-role case: pg_attribute is readable by anyone, so a
+        // present column always carries its real type here.
+        const drift = columnDrift(column, found, expectedOids.get(column.sqlType))
+        if (drift !== undefined) drifted.push(drift)
+      }
+      const progress = queueProgressColumns().get(table)
+      const missingProgress = progress !== undefined && !have.has(progress) ? { missingProgressColumn: progress } : {}
+      if (missing.length > 0 || drifted.length > 0 || progress !== undefined && !have.has(progress)) {
+        problems.push({
+          table, missingColumns: missing, ...(drifted.length > 0 ? { driftedColumns: drifted } : {}), ...missingProgress,
+        })
+      }
+    }
+    return problems
+  } finally {
+    await sql.end({ timeout: 1 })
+  }
+}
+
+/** Startup-validation leg: every registered queue's table must exist, in shape, in the default database (where queue migrations are emitted). */
+export async function validateQueueTables(
+  defaultDb: ResolvedDatabase,
+  timeoutMs = 5000,
+): Promise<ValidationIssue[]> {
+  try {
+    const problems = await queueTableProblems(defaultDb.url, timeoutMs)
+    return problems.map(problem => ({
+      phase: 'database' as const,
+      message: queueTableProblemMessage(problem, defaultDb.name),
+    }))
+  } catch {
+    // An unreachable database is validateConnectivity's finding — reporting it
+    // here too would double up the same root cause.
+    return []
+  }
+}

package/src/core/validation/rls-role.ts

@@ -0,0 +1,138 @@
+import type { ValidationIssue } from './types.js'
+import type { ResolvedDatabase } from '../config/load.js'
+import { probeConnectTimeout } from './connectivity.js'
+import type { IsolationStrategy } from '../config/schema.js'
+import { appPoolCreated } from '../config/app-pool.js'
+
+// D4b (subseam audit 2026-07-16, finding F3): a database can carry a full RLS
+// policy set while its runtime role is superuser or BYPASSRLS — every policy
+// inert, with zero signal from the framework. Probed at startup and at test
+// bootstrap; refusal is an error, not a warning.
+
+export interface RlsRoleProbe {
+  readonly role: string
+  readonly superuser: boolean
+  readonly bypassRls: boolean
+}
+
+export function rlsRoleMessage(database: string, probe: RlsRoleProbe): string {
+  const flag = probe.superuser ? 'SUPERUSER' : 'BYPASSRLS'
+  return (
+    `database "${database}" has rls configured, but its runtime role "${probe.role}" is ${flag} — ` +
+    `row-level security policies never apply to it, so tenant isolation is inert. ` +
+    `Provision a non-BYPASSRLS, non-superuser application role and point the runtime connection at it ` +
+    `(appUrl/appTestUrl, or the url/testUrl var this connection resolved from).`
+  )
+}
+
+/** The connection whose role actually executes queries under the harness: transaction isolation collapses every role onto the resolved `url` connection; database/container isolation resolves roles normally (`appUrl ?? url`). */
+export function rlsProbeTarget(db: ResolvedDatabase, strategy: IsolationStrategy): string {
+  return appPoolCreated(strategy) ? (db.appUrl ?? db.url) : db.url
+}
+
+/**
+ * Role flags for `current_user` at `url`. Short-lived probe connection, mirroring
+ * validateConnectivity. `timeoutMs: null` leaves the connect timeout to the
+ * driver (PGCONNECT_TIMEOUT, else 30 s).
+ */
+export async function probeRlsRole(url: string, timeoutMs: number | null = 5000): Promise<RlsRoleProbe> {
+  const { default: postgres } = await import('postgres')
+  const sql = postgres(url, {
+    max: 1,
+    idle_timeout: 1,
+    ...probeConnectTimeout(timeoutMs),
+    onnotice: () => {},
+  })
+
+  try {
+    const rows = await sql`SELECT current_user AS role, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`
+    const row = rows[0] as { role: string; rolsuper: boolean; rolbypassrls: boolean } | undefined
+    if (row === undefined) {
+      throw new Error('current_user not found in pg_roles')
+    }
+    return { role: row.role, superuser: row.rolsuper, bypassRls: row.rolbypassrls }
+  } finally {
+    await sql.end({ timeout: 1 })
+  }
+}
+
+/** Startup-validation leg: for each database with `rls` configured, the runtime connection's role (`appUrl ?? url`) must not bypass RLS. */
+export async function validateRlsRoles(
+  databases: ReadonlyMap<string, ResolvedDatabase>,
+  timeoutMs = 5000,
+): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = []
+
+  const checks = [...databases.entries()]
+    .filter(([, db]) => db.rls !== undefined)
+    .map(async ([name, db]) => {
+      let probe: RlsRoleProbe
+      try {
+        probe = await probeRlsRole(db.appUrl ?? db.url, timeoutMs)
+      } catch {
+        // An unreachable database is validateConnectivity's finding.
+        return
+      }
+      if (probe.superuser || probe.bypassRls) {
+        issues.push({ phase: 'database', message: rlsRoleMessage(name, probe) })
+      }
+    })
+
+  await Promise.all(checks)
+  return issues
+}
+
+export function systemRoleMessage(database: string, platformRole: string, probe: RlsRoleProbe): string[] {
+  const out: string[] = []
+  if (probe.superuser || probe.bypassRls) {
+    const flag = probe.superuser ? 'SUPERUSER' : 'BYPASSRLS'
+    out.push(
+      `database "${database}": the systemUrl role "${probe.role}" is ${flag} — row-level security never applies to it, ` +
+      `so the system channel reaches every tenant row and no door means anything. ` +
+      `Point systemUrl/systemTestUrl at a role with neither flag, named rls.platformRole.`,
+    )
+  }
+  if (probe.role !== platformRole) {
+    out.push(
+      `database "${database}": the systemUrl connection authenticates as "${probe.role}", but rls.platformRole is "${platformRole}" — ` +
+      `door policies are granted to "${platformRole}" only. Point systemUrl/systemTestUrl at a connection as "${platformRole}", ` +
+      `or change rls.platformRole.`,
+    )
+  }
+  return out
+}
+
+/** Startup-validation leg: for each database in platform mode, the `systemUrl` role must be the named platform role and must not bypass RLS. */
+export async function validateSystemRoles(
+  databases: ReadonlyMap<string, ResolvedDatabase>,
+  timeoutMs = 5000,
+): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = []
+
+  const checks = [...databases.entries()]
+    .filter(([, db]) => db.rls?.platformRole !== undefined && db.systemUrl !== undefined)
+    .map(async ([name, db]) => {
+      let probe: RlsRoleProbe
+      try {
+        probe = await probeRlsRole(db.systemUrl!, timeoutMs)
+      } catch {
+        // An unreachable database is validateConnectivity's finding.
+        return
+      }
+      for (const message of systemRoleMessage(name, db.rls!.platformRole!, probe)) {
+        issues.push({ phase: 'database', message })
+      }
+    })
+
+  await Promise.all(checks)
+  return issues
+}
+
+/** Databases with `rls` and no platform role: their system channel runs on the owner role, which bypasses RLS. */
+export function ownerSystemChannelWarnings(databases: ReadonlyMap<string, ResolvedDatabase>): string[] {
+  return [...databases.entries()]
+    .filter(([, db]) => db.rls !== undefined && db.rls.platformRole === undefined)
+    .map(([name]) =>
+      `database "${name}" has rls configured and no platform role: pipe.system() runs on the owner role, which bypasses RLS. ` +
+      `Set systemUrl and rls.platformRole to run it on a role with no BYPASSRLS and read tenant tables through declared doors.`)
+}

package/src/core/validation/startup.ts

@@ -0,0 +1,51 @@
+import type { ValidationIssue } from './types.js'
+import { StartupValidationError } from './types.js'
+import { validateDomainIntegrity } from './domain.js'
+import { collectSurfaceIssues } from './surfaces.js'
+import { validateConnectivity } from './connectivity.js'
+import { validateQueueTables } from './queue-tables.js'
+import { validateRlsRoles, validateSystemRoles } from './rls-role.js'
+import { definitions } from '../../data/domain/define.js'
+import type { SurfaceMap } from '../surface/types.js'
+import type { ResolvedDatabase } from '../config/load.js'
+
+export interface ValidationContext {
+  readonly configuredDatabases: readonly string[]
+  readonly environment: string
+  readonly surfaces?: SurfaceMap | undefined
+  readonly defaultDbAvailable?: boolean | undefined
+  readonly databases?: ReadonlyMap<string, ResolvedDatabase> | undefined
+  /** The database queue migrations are emitted into — queue-table existence is checked there. Undefined skips the check (genuinely ambiguous multi-DB configs fail earlier, at generate). */
+  readonly defaultDatabase?: ResolvedDatabase | undefined
+  readonly connectivityCheck?: boolean | undefined
+}
+
+export async function validateStartup(ctx: ValidationContext): Promise<void> {
+  const issues: ValidationIssue[] = []
+
+  issues.push(...validateDomainIntegrity(definitions(), ctx.configuredDatabases))
+
+  if (ctx.surfaces !== undefined) {
+    issues.push(
+      ...collectSurfaceIssues(
+        ctx.surfaces,
+        ctx.configuredDatabases,
+        ctx.defaultDbAvailable ?? ctx.configuredDatabases.length === 1,
+      ),
+    )
+  }
+
+  if (ctx.connectivityCheck !== false && ctx.databases !== undefined) {
+    issues.push(...await validateConnectivity(ctx.databases))
+    issues.push(...await validateRlsRoles(ctx.databases))
+    issues.push(...await validateSystemRoles(ctx.databases))
+  }
+
+  if (ctx.connectivityCheck !== false && ctx.defaultDatabase !== undefined) {
+    issues.push(...await validateQueueTables(ctx.defaultDatabase))
+  }
+
+  if (issues.length > 0) {
+    throw new StartupValidationError(issues)
+  }
+}

package/src/core/validation/surfaces.ts

@@ -0,0 +1,65 @@
+import type { SurfaceMap } from '../surface/types.js'
+import { DEFAULT_DB } from '../../request/di/types.js'
+import type { ValidationIssue } from './types.js'
+
+export function collectSurfaceIssues(
+  surfaces: SurfaceMap,
+  configuredDatabases: readonly string[],
+  defaultDbAvailable: boolean,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  const dbSet = new Set(configuredDatabases)
+
+  for (const [name, surface] of Object.entries(surfaces)) {
+    for (const db of surface.manifest.databases) {
+      if (db === DEFAULT_DB) {
+        if (!defaultDbAvailable) {
+          issues.push({
+            phase: 'surface',
+            message: `"${name}" uses the default database, but multiple databases are configured: ${configuredDatabases.join(', ')}`,
+          })
+        }
+      } else if (!dbSet.has(db)) {
+        issues.push({
+          phase: 'surface',
+          message: `"${name}" requires database "${db}" which is not configured (available: ${configuredDatabases.join(', ')})`,
+        })
+      }
+    }
+
+    if (surface.kind === 'worker' && surface.manifest.jobTypes.length === 0) {
+      issues.push({
+        phase: 'surface',
+        message: `"${name}" is a worker with no job handlers`,
+      })
+    }
+
+    const seen = new Set<string>()
+    for (const jobType of surface.manifest.jobTypes) {
+      if (seen.has(jobType)) {
+        issues.push({
+          phase: 'surface',
+          message: `"${name}" has duplicate job type "${jobType}"`,
+        })
+      }
+      seen.add(jobType)
+    }
+  }
+
+  const jobOwners = new Map<string, string>()
+  for (const [name, surface] of Object.entries(surfaces)) {
+    for (const jobType of surface.manifest.jobTypes) {
+      const existing = jobOwners.get(jobType)
+      if (existing !== undefined) {
+        issues.push({
+          phase: 'surface',
+          message: `job type "${jobType}" handled by both "${existing}" and "${name}"`,
+        })
+      } else {
+        jobOwners.set(jobType, name)
+      }
+    }
+  }
+
+  return issues
+}