pipework 0.252.0 → 0.253.0

package/src/core/config/load.ts

@@ -0,0 +1,417 @@
+import { resolve } from 'node:path'
+import { trunkConfigSchema, type Blueprint, type Environment, type DatabaseConfig, type IsolationStrategy } from './schema.js'
+import { resolveEnvironment, resolveEnvironmentStrict, resolveDbUrl, resolveTestOwnerUrl } from './resolve.js'
+import { ConfigError } from './errors.js'
+import { resolveEnvVars } from './env-resolve.js'
+import { consumeConfigBaseDir } from './base-dir.js'
+import type { StatementObserver } from './statement-observer.js'
+
+export interface ResolvedObservability {
+  readonly slowQueryMs: number
+  /** Interval at which a still-running statement is reported; undefined = off. */
+  readonly inFlightQueryMs?: number | undefined
+  readonly logAllQueries: boolean
+  readonly poolMetricsInterval: number
+  /** Caller-supplied per-statement observer; undefined when not configured. */
+  readonly onStatement: StatementObserver | undefined
+}
+
+export interface ResolvedTrace {
+  readonly hotRetentionDays: number
+  readonly errorRetentionDays: number
+  readonly partitionLeadDays: number
+  readonly safetyFactor: number
+  /** Unset → the runtime step cap is open (truncation never fires). Set → cap is `structuralMax × safetyFactor`. */
+  readonly structuralMax: number | undefined
+  readonly captureInputs: boolean
+  /** Per-trace limit on steps recorded from outside the Node process via `trace.record`; not part of the structural cap. */
+  readonly maxExternalSteps: number
+  /**
+   * Consumer-extension I/O registry (Q9). Keys are lexical call patterns —
+   * either a bare identifier (`"fetch"`) or a single member access
+   * (`"cache.get"`) — and values declare whether the call is a read or a
+   * write. The Tier-2 coverage check unions this with the stock pipework
+   * registry (`pipe.*` writes, `pipe(...)`-chain reads).
+   */
+  readonly io: Readonly<Record<string, 'read' | 'write'>>
+  /**
+   * Maximum audit rows emitted per write+audit CTE statement (Q8 / Phase 6c).
+   * Bulk inserts whose `values.length × touches.length` would exceed this are
+   * split into chunks executed sequentially inside a transaction (or savepoint
+   * when already nested). Engineering knob: defaults to 5000, never zero.
+   */
+  readonly auditChunkSize: number
+}
+
+export interface ResolvedAudit {
+  readonly retentionDays: number | 'keep'
+}
+
+export interface ResolvedConfig {
+  readonly raw: Blueprint
+  /** The environment this process runs as: Blueprint `environment`, else `PIPEWORK_ENV`, else `NODE_ENV` (test/production), else development. Read it here rather than from `process.env`. */
+  readonly environment: Environment
+  /** The release read from `release.env`; null when not configured, unset or empty. */
+  readonly release: string | null
+  readonly observability: ResolvedObservability
+  readonly trace: ResolvedTrace
+  readonly audit: ResolvedAudit
+  readonly env: Readonly<Record<string, unknown>>
+  /** Declared cross-tenant read doors, by name, each with its database resolved. */
+  readonly doors: Readonly<Record<string, ResolvedDoor>>
+  /** Doors pipework declares for its own substrates, only where the default database has `rls.platformRole`. */
+  readonly frameworkDoors: Readonly<Record<string, ResolvedDoor>>
+  database(name?: string): ResolvedDatabase
+  databases(): ReadonlyMap<string, ResolvedDatabase>
+  databaseNames(): readonly string[]
+  defaultDatabaseName(): string
+  isolationStrategy(dbName: string): IsolationStrategy
+}
+
+export interface ResolvedDoor {
+  readonly name: string
+  /** SQL table name. */
+  readonly table: string
+  /** The database the table lives in — the default database when the door names none. */
+  readonly database: string
+  readonly reason: string
+  /** A door pipework declares for its own work (named `pipework.*`); not in config. */
+  readonly framework?: true
+  /** Operations a framework door opens; an app door is SELECT-only. */
+  readonly ops?: readonly ('select' | 'update' | 'delete')[]
+}
+
+export interface ResolvedDatabase {
+  readonly name: string
+  readonly url: string
+  readonly appUrl?: string
+  /** Platform mode only: the connection `pipe.system()` and `pipe.door()` run on, as `rls.platformRole`. */
+  readonly systemUrl?: string
+  /** Test mode only: the connection whose role migrates the template. See `testOwnerUrl` in the config schema. */
+  readonly testOwnerUrl?: string
+  /** Directory relative `migrations`/`schema` paths resolve against — the config file's directory (process.cwd() for directly-constructed configs). */
+  readonly baseDir: string
+  /** Glob patterns stay as authored; consumers glob them with `cwd: baseDir`. */
+  readonly schema: string | string[] | undefined
+  /** Absolute — resolved against baseDir at load time, so cwd never matters (D1). */
+  readonly migrations: string | undefined
+  readonly extensions: readonly string[]
+  readonly migrationTable: string
+  readonly pool: { max: number; idleTimeout: number; readonly publishReservation?: boolean; readonly settings?: Readonly<Record<string, string>> }
+  readonly rls?: { readonly sessionVar: string; readonly force: boolean; readonly platformRole?: string }
+}
+
+export function loadConfig(raw: unknown): ResolvedConfig {
+  // Consume before validation so a parse failure cannot leave the slot set for
+  // an unrelated later load.
+  const baseDir = consumeConfigBaseDir() ?? process.cwd()
+  const parsed = trunkConfigSchema.safeParse(raw)
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map(i => `  - ${i.path.join('.')}: ${i.message}`).join('\n')
+    throw new ConfigError(
+      `Invalid pipework.config.ts:\n${issues}`,
+      'Check your pipework.config.ts against the expected schema.',
+    )
+  }
+
+  const config = parsed.data
+  const environment = config.environment
+    ?? (config.requireEnvironment === true ? resolveEnvironmentStrict() : resolveEnvironment())
+  return buildResolved(config, environment, baseDir)
+}
+
+function stringifySettings(settings: Readonly<Record<string, string | number | boolean>>): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(settings)) out[k] = typeof v === 'boolean' ? (v ? 'on' : 'off') : String(v)
+  return out
+}
+
+function resolveRelease(def: Blueprint['release'], environment: Environment): string | null {
+  if (def === undefined) return null
+  const value = process.env[def.env]
+  if (value !== undefined && value !== '') return value
+  if (def.requiredIn?.includes(environment) === true) {
+    throw new ConfigError(
+      `Environment variable ${def.env} is not set, but the release is required in environment "${environment}".`,
+      `Set ${def.env} to this deploy's release (for example ${def.env}=2026.10.3), or remove "${environment}" from release.requiredIn.`,
+    )
+  }
+  return null
+}
+
+function buildResolved(config: Blueprint, environment: Environment, baseDir: string): ResolvedConfig {
+  const dbMap = new Map<string, ResolvedDatabase>()
+
+  // Defined here, not inline in the accessor, so the app-pair carve-out below
+  // and `isolationStrategy()` cannot answer the same question differently.
+  const isolationStrategyFor = (dbName: string): IsolationStrategy =>
+    config.test?.databases?.[dbName]?.isolation ?? config.test?.isolation ?? 'transaction'
+
+  // URL resolution is attempted for EVERY database here, but a failure is not
+  // thrown until a URL is first accessed. Two recorded consumer defects drive
+  // this shape: refusing at load meant runs that never open a connection
+  // (type-only test legs, `check`) still demanded DB env; and throwing on the
+  // first failure surfaced missing variables one per run. So failures are
+  // collected across all databases and the aggregate is thrown lazily, naming
+  // everything that must be fixed at once.
+  const urlIssues: ConfigError[] = []
+  const collect = (fn: () => string): string | undefined => {
+    try {
+      return fn()
+    } catch (err) {
+      if (err instanceof ConfigError) {
+        urlIssues.push(err)
+        return undefined
+      }
+      throw err
+    }
+  }
+  const refuseUrls = (): never => {
+    const details = urlIssues
+      .map(e => `  - ${e.message.replace(/^\[pipework\] /, '').trimEnd().split('\n').join('\n    ')}`)
+      .join('\n')
+    throw new ConfigError(
+      `Database URL resolution failed (${String(urlIssues.length)} problem${urlIssues.length === 1 ? '' : 's'}):\n\n${details}`,
+      'Fix every item above — they are all reported in this one run.',
+    )
+  }
+
+  for (const [name, dbConfig] of Object.entries(config.databases)) {
+    const url = collect(() => resolveDbUrl(dbConfig.url, dbConfig.testUrl, environment, name))
+    const appUrl = dbConfig.appUrl !== undefined
+      ? collect(() => resolveDbUrl(dbConfig.appUrl!, dbConfig.appTestUrl, environment, name, { strategy: isolationStrategyFor(name) }))
+      : undefined
+    const systemUrl = dbConfig.systemUrl !== undefined
+      ? collect(() => resolveDbUrl(dbConfig.systemUrl!, dbConfig.systemTestUrl, environment, name, { strategy: isolationStrategyFor(name), role: 'system' }))
+      : undefined
+    // Outside test mode the field is inert — production already migrates as
+    // `url`'s role — so it is neither resolved nor exposed. `{ resolved }`
+    // rather than a bare string so a failed resolution is still a property
+    // that refuses on access, not a property that quietly went missing.
+    const testOwner = dbConfig.testOwnerUrl !== undefined && environment === 'test'
+      ? { resolved: collect(() => resolveTestOwnerUrl(dbConfig.testOwnerUrl!, url, name)) }
+      : undefined
+    dbMap.set(name, resolveDatabase(name, dbConfig, url, appUrl, systemUrl, testOwner, baseDir, refuseUrls))
+  }
+
+  const declaredNames = [...dbMap.keys()]
+
+  const defaultDbName = config.defaultDatabase
+  if (defaultDbName !== undefined && !dbMap.has(defaultDbName)) {
+    const suggestion = closestMatch(defaultDbName, declaredNames)
+    throw new ConfigError(
+      `defaultDatabase "${defaultDbName}" is not a declared database.`,
+      suggestion !== null
+        ? `Did you mean "${suggestion}"? Declared databases: ${declaredNames.join(', ')}`
+        : `Declared databases: ${declaredNames.join(', ')}`,
+    )
+  }
+
+  // The database resolved by a no-name db()/pipe(): the sole database, or the
+  // explicitly-configured defaultDatabase. Undefined only when multiple are
+  // declared with no default — genuine ambiguity, which both no-name resolvers
+  // surface as a ConfigError.
+  const resolveDefaultName = (): string | undefined => {
+    if (declaredNames.length === 1) return declaredNames[0]!
+    if (defaultDbName !== undefined) return defaultDbName
+    return undefined
+  }
+
+  const doors: Record<string, ResolvedDoor> = {}
+  for (const [doorName, door] of Object.entries(config.doors ?? {})) {
+    // The schema refused a door with no resolvable database.
+    doors[doorName] = Object.freeze({ name: doorName, table: door.table, database: door.database ?? resolveDefaultName()!, reason: door.reason })
+  }
+
+  const frameworkDoors: Record<string, ResolvedDoor> = {}
+  const defaultName = resolveDefaultName()
+  if (config.storage !== undefined && defaultName !== undefined && dbMap.get(defaultName)?.rls?.platformRole !== undefined) {
+    frameworkDoors['pipework.storage_sweep'] = Object.freeze({
+      name: 'pipework.storage_sweep', table: 'storage_file', database: defaultName,
+      reason: 'the storage sweep expires files and finds objects no file references, across tenants',
+      framework: true as const, ops: ['select', 'delete'] as const,
+    })
+  }
+
+  const release = resolveRelease(config.release, environment)
+
+  const env = Object.freeze(resolveEnvVars((config.env ?? {}) as import('./env-types.js').EnvDefs, environment))
+
+  return {
+    raw: config,
+    environment,
+    release,
+    observability: {
+      slowQueryMs: config.observability?.slowQueryMs ?? 500,
+      inFlightQueryMs: config.observability?.inFlightQueryMs,
+      logAllQueries: config.observability?.logAllQueries ?? false,
+      poolMetricsInterval: config.observability?.poolMetricsInterval ?? 0,
+      onStatement: config.observability?.onStatement,
+    },
+    trace: {
+      hotRetentionDays: config.trace?.hotRetentionDays ?? 7,
+      errorRetentionDays: config.trace?.errorRetentionDays ?? 30,
+      partitionLeadDays: config.trace?.partitionLeadDays ?? 2,
+      safetyFactor: config.trace?.safetyFactor ?? 4,
+      structuralMax: config.trace?.structuralMax,
+      captureInputs: config.trace?.captureInputs ?? true,
+      maxExternalSteps: config.trace?.maxExternalSteps ?? 1000,
+      io: Object.freeze({ ...(config.trace?.io ?? {}) }),
+      auditChunkSize: config.trace?.auditChunkSize ?? 5000,
+    },
+    audit: {
+      retentionDays: config.audit?.retentionDays ?? 365,
+    },
+    env,
+    doors: Object.freeze(doors),
+    frameworkDoors: Object.freeze(frameworkDoors),
+
+    database(name?: string): ResolvedDatabase {
+      if (name === undefined) {
+        const resolved = resolveDefaultName()
+        if (resolved !== undefined) {
+          return dbMap.get(resolved)!
+        }
+        throw new ConfigError(
+          'Multiple databases configured — you must specify which one.',
+          `Declared databases: ${declaredNames.join(', ')}\n\n  Use db("${declaredNames[0]}") to specify which database, or set defaultDatabase in pipework.config.ts.`,
+        )
+      }
+      const db = dbMap.get(name)
+      if (!db) {
+        const suggestion = closestMatch(name, declaredNames)
+        const hint = suggestion !== null
+          ? `Did you mean "${suggestion}"? Declared databases: ${declaredNames.join(', ')}`
+          : `Declared databases: ${declaredNames.join(', ')}`
+        throw new ConfigError(`Unknown database "${name}".`, hint)
+      }
+      return db
+    },
+
+    databases(): ReadonlyMap<string, ResolvedDatabase> {
+      return dbMap
+    },
+
+    databaseNames(): readonly string[] {
+      return declaredNames
+    },
+
+    defaultDatabaseName(): string {
+      const resolved = resolveDefaultName()
+      if (resolved !== undefined) {
+        return resolved
+      }
+      throw new ConfigError(
+        'Multiple databases configured — you must specify which one.',
+        `Declared databases: ${declaredNames.join(', ')}\n\n  Set defaultDatabase in pipework.config.ts to pick one.`,
+      )
+    },
+
+    isolationStrategy(dbName: string): IsolationStrategy {
+      return isolationStrategyFor(dbName)
+    },
+  }
+}
+
+function resolveDatabase(
+  name: string,
+  config: DatabaseConfig,
+  url: string | undefined,
+  appUrl: string | undefined,
+  systemUrl: string | undefined,
+  testOwner: { resolved: string | undefined } | undefined,
+  baseDir: string,
+  refuseUrls: () => never,
+): ResolvedDatabase {
+  const resolved = {
+    name,
+    baseDir,
+    schema: config.schema,
+    // Absolutized here — the single place — so every consumer (generate,
+    // migrate safety gate, test template provisioning) is cwd-independent.
+    // resolve(base, abs) === abs, so already-absolute consumer paths stay valid.
+    migrations: config.migrations !== undefined ? resolve(baseDir, config.migrations) : undefined,
+    extensions: config.extensions ?? [],
+    migrationTable: config.migrationTable ?? `__pipework_migrations_${name}`,
+    pool: {
+      max: config.pool?.max ?? 10,
+      idleTimeout: config.pool?.idleTimeout ?? 30,
+      ...(config.pool?.publishReservation === true ? { publishReservation: true } : {}),
+      ...(config.pool?.settings !== undefined ? { settings: stringifySettings(config.pool.settings) } : {}),
+    },
+    ...(config.rls !== undefined
+      ? { rls: { sessionVar: config.rls.sessionVar, force: config.rls.force, ...(config.rls.platformRole !== undefined ? { platformRole: config.rls.platformRole } : {}) } }
+      : {}),
+  }
+  // Lazy URL properties, attached with defineProperty rather than object
+  // literal getters: a getter in a spread source is evaluated BY the spread,
+  // which would turn the deferred refusal back into a load-time one. A URL
+  // that failed to resolve throws the aggregate refusal on first access, so
+  // config metadata (names, migrations, pool sizing) stays usable by code
+  // paths that never dial a connection.
+  Object.defineProperty(resolved, 'url', {
+    enumerable: true,
+    get: () => url ?? refuseUrls(),
+  })
+  if (config.appUrl !== undefined) {
+    Object.defineProperty(resolved, 'appUrl', {
+      enumerable: true,
+      get: () => appUrl ?? refuseUrls(),
+    })
+  }
+  if (config.systemUrl !== undefined) {
+    Object.defineProperty(resolved, 'systemUrl', {
+      enumerable: true,
+      get: () => systemUrl ?? refuseUrls(),
+    })
+  }
+  // Only in test mode does this property exist at all: outside it the field is
+  // configured but meaningless, and an absent property is what every consumer
+  // already reads as "migrate as the test login".
+  if (testOwner !== undefined) {
+    Object.defineProperty(resolved, 'testOwnerUrl', {
+      enumerable: true,
+      get: () => testOwner.resolved ?? refuseUrls(),
+    })
+  }
+  return resolved as unknown as ResolvedDatabase
+}
+
+function closestMatch(input: string, candidates: string[]): string | null {
+  if (candidates.length === 0) return null
+
+  let best: string | null = null
+  let bestDistance = Infinity
+
+  for (const candidate of candidates) {
+    const d = levenshtein(input.toLowerCase(), candidate.toLowerCase())
+    if (d < bestDistance && d <= Math.max(input.length, candidate.length) * 0.6) {
+      bestDistance = d
+      best = candidate
+    }
+  }
+
+  return best
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array.from({ length: n + 1 }, () => 0))
+
+  for (let i = 0; i <= m; i++) dp[i]![0] = i
+  for (let j = 0; j <= n; j++) dp[0]![j] = j
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      dp[i]![j] = Math.min(
+        dp[i - 1]![j]! + 1,
+        dp[i]![j - 1]! + 1,
+        dp[i - 1]![j - 1]! + cost,
+      )
+    }
+  }
+
+  return dp[m]![n]!
+}

package/src/core/config/namespace.ts

@@ -0,0 +1,14 @@
+import { loadConfig, trunkConfigSchema, ConfigError } from './index.js'
+import { discoverInstance } from './discover.js'
+
+/** Configuration namespace — loads and resolves Blueprint configs, discovers pipework.config.ts. */
+export const config = {
+  /** Parses and resolves a raw Blueprint into a ResolvedConfig with environment detection. */
+  load: loadConfig,
+  /** Walks up from cwd to find pipework.config.ts, imports it, and returns the Manifold. */
+  discover: discoverInstance,
+  /** The zod schema for Blueprint validation — useful for custom config tooling. */
+  configSchema: trunkConfigSchema,
+  /** Thrown for configuration problems — includes a suggestion for how to fix. */
+  ConfigError,
+}

package/src/core/config/resolve.ts

@@ -0,0 +1,195 @@
+import type { Environment, IsolationStrategy } from './schema.js'
+import { ConfigError } from './errors.js'
+import { appPoolCreated } from './app-pool.js'
+
+/**
+ * Passed when resolving the app-role pair (`appUrl`/`appTestUrl`), which carries
+ * the transaction-isolation carve-out on value-identity. Absent when resolving
+ * the owner pair (`url`/`testUrl`), which has no carve-out: that connection is
+ * dialed under every strategy.
+ */
+export interface AppRolePair {
+  /** This database's resolved test-isolation strategy. */
+  readonly strategy: IsolationStrategy
+  /** Which connection's fields the pair names in refusals; default `app`. */
+  readonly role?: 'app' | 'system'
+}
+
+const ENVIRONMENTS: readonly string[] = ['test', 'development', 'production']
+
+/**
+ * Strict resolution for Blueprint `requireEnvironment`: PIPEWORK_ENV, then
+ * NODE_ENV, each of which must name a known environment. Unset or unknown
+ * is an error rather than development.
+ */
+export function resolveEnvironmentStrict(): Environment {
+  const hint = 'Set PIPEWORK_ENV or NODE_ENV to development, test or production.'
+  const explicit = process.env['PIPEWORK_ENV']
+  if (explicit !== undefined && explicit !== '') {
+    if (ENVIRONMENTS.includes(explicit)) return explicit as Environment
+    throw new ConfigError(
+      `PIPEWORK_ENV is ${JSON.stringify(explicit)}, which is not an environment, and requireEnvironment is set.`,
+      hint,
+    )
+  }
+  const nodeEnv = process.env['NODE_ENV']
+  if (nodeEnv !== undefined && nodeEnv !== '') {
+    if (ENVIRONMENTS.includes(nodeEnv)) return nodeEnv as Environment
+    throw new ConfigError(
+      `NODE_ENV is ${JSON.stringify(nodeEnv)}, which is not an environment, and requireEnvironment is set.`,
+      hint,
+    )
+  }
+  throw new ConfigError(
+    'Neither PIPEWORK_ENV nor NODE_ENV is set, and requireEnvironment is set.',
+    hint,
+  )
+}
+
+export function resolveEnvironment(): Environment {
+  const explicit = process.env['PIPEWORK_ENV']
+  if (explicit === 'test' || explicit === 'development' || explicit === 'production') {
+    return explicit
+  }
+
+  const nodeEnv = process.env['NODE_ENV']
+  if (nodeEnv === 'test') return 'test'
+  if (nodeEnv === 'production') return 'production'
+
+  return 'development'
+}
+
+export function resolveDbUrl(
+  envVarName: string,
+  testEnvVarName: string | undefined,
+  environment: Environment,
+  dbName?: string,
+  appRolePair?: AppRolePair,
+): string {
+  if (environment === 'test') {
+    // The pair being resolved, so every refusal below names the fields the
+    // reader actually has to edit rather than always saying url/testUrl.
+    const urlField = appRolePair === undefined ? 'url' : appRolePair.role === 'system' ? 'systemUrl' : 'appUrl'
+    const testUrlField = appRolePair === undefined ? 'testUrl' : appRolePair.role === 'system' ? 'systemTestUrl' : 'appTestUrl'
+
+    if (testEnvVarName === undefined) {
+      throw new ConfigError(
+        `Database "${dbName ?? envVarName}" has no ${testUrlField} configured, but environment is "test".`,
+        `Add ${testUrlField} to your database config:\n\n` +
+        `  databases: {\n` +
+        `    ${dbName ?? 'app'}: {\n` +
+        `      ${urlField}: '${envVarName}',\n` +
+        `      ${testUrlField}: '${envVarName}_TEST',  // <-- add this\n` +
+        `    },\n` +
+        `  }\n\n` +
+        `Then set ${envVarName}_TEST in your environment.`,
+      )
+    }
+
+    // D4a (subseam audit 2026-07-16): a testUrl that resolves to the real
+    // database means "tests" run against production — the harness
+    // creates/drops databases and rolls back transactions on what it assumes
+    // is a dedicated instance, and RLS-inertness goes unnoticed. Name-identity
+    // first: both fields reading one variable is a config-shape defect,
+    // regardless of what the variable holds.
+    if (testEnvVarName === envVarName) {
+      throw new ConfigError(
+        `Database "${dbName ?? envVarName}" uses the same environment variable "${envVarName}" for ${urlField} and ${testUrlField} — test isolation is defeated.`,
+        `${testUrlField} must be its own variable pointing at a separate database:\n\n` +
+        `  databases: {\n` +
+        `    ${dbName ?? 'app'}: {\n` +
+        `      ${urlField}: '${envVarName}',\n` +
+        `      ${testUrlField}: '${envVarName}_TEST',  // <-- its own variable\n` +
+        `    },\n` +
+        `  }\n\n` +
+        `Then set ${envVarName}_TEST to a separate database's connection string.`,
+      )
+    }
+
+    const value = process.env[testEnvVarName]
+    if (value !== undefined && value !== '') {
+      const urlValue = process.env[envVarName]
+      // 0.17.1: value-identity on the app-role pair is a false positive under a
+      // strategy that never creates the app-role pool — the value satisfies
+      // config resolution and is then never dialed by it. The refusal stands
+      // wherever the pool IS created, and for the owner pair in every mode.
+      // Name-identity above is NOT carved out: one env var serving both fields
+      // carries no intent and cannot be told from a typo.
+      const inert = appRolePair !== undefined && !appPoolCreated(appRolePair.strategy)
+      if (!inert && urlValue !== undefined && urlValue !== '' && urlValue === value) {
+        throw new ConfigError(
+          `Database "${dbName ?? envVarName}": "${testEnvVarName}" and "${envVarName}" hold the identical connection string — test isolation is defeated.`,
+          `Tests would run against the same database "${envVarName}" points at. ` +
+          `Point ${testEnvVarName} at a separate database.` +
+          (appRolePair !== undefined
+            ? `\n\nIdentical app-role values are accepted only under "transaction" isolation, ` +
+              `where the harness overrides every role onto one rolled-back connection and the ` +
+              `app-role pool is never created. This database resolves to "${appRolePair.strategy}" ` +
+              `isolation, which creates it — so ${testEnvVarName} is genuinely dialed here.`
+            : ''),
+        )
+      }
+      return value
+    }
+
+    throw new ConfigError(
+      `Missing test database URL: environment variable "${testEnvVarName}" is not set.`,
+      `Set ${testEnvVarName} in .env.test (or .env.test.local for a machine-local value) or in your environment.`,
+    )
+  }
+
+  const value = process.env[envVarName]
+  if (value !== undefined && value !== '') return value
+
+  throw new ConfigError(
+    `Missing database URL: environment variable "${envVarName}" is not set.`,
+    `Set ${envVarName} in your .env file or environment.`,
+  )
+}
+
+
+/**
+ * Resolve `testOwnerUrl`: the connection whose ROLE migrates the test template.
+ *
+ * Outside test mode there is no such thing — production migrates as `url`'s
+ * role already — so this is only ever called with `environment === 'test'`.
+ *
+ * No identity refusal against `url` here, and deliberately so: the field names
+ * the variable holding the owner's credentials, and a venue that exports one
+ * `DATABASE_URL` per role set legitimately points this at the same variable
+ * name `url` uses. What that variable holds in test mode is the test cluster's
+ * owner. The isolation refusals stay where they belong, on `url`/`testUrl`,
+ * which is the connection tests actually run on.
+ */
+export function resolveTestOwnerUrl(
+  envVarName: string,
+  testUrl: string | undefined,
+  dbName: string,
+): string {
+  const value = process.env[envVarName]
+  if (value === undefined || value === '') {
+    throw new ConfigError(
+      `Database "${dbName}": testOwnerUrl names "${envVarName}", which is not set.`,
+      `Set ${envVarName} to a connection string for the role that should migrate the test ` +
+      `template, or remove testOwnerUrl to migrate as the test login.`,
+    )
+  }
+
+  // The template is CREATEd on testUrl's server and then migrated on this one.
+  // Two different servers means the migrations land in a database nobody
+  // clones, and the template gets cloned empty — a silent, bewildering failure
+  // that is cheap to refuse here.
+  if (testUrl !== undefined) {
+    const owner = new URL(value)
+    const test = new URL(testUrl)
+    if (owner.host !== test.host) {
+      throw new ConfigError(
+        `Database "${dbName}": testOwnerUrl ("${envVarName}") points at ${owner.host}, but the test database is on ${test.host}.`,
+        `The template is created on the test server and migrated as the owner, so both must ` +
+        `be the same server. Point ${envVarName} at ${test.host}.`,
+      )
+    }
+  }
+
+  return value
+}