pipework 0.252.0 → 0.253.0

package/src/cli/index.ts

@@ -0,0 +1,303 @@
+import { parseArgs } from 'node:util'
+import { loadEnvFiles } from '../core/config/env.js'
+import { bold, error } from './output.js'
+import { handleError } from './errors.js'
+
+const USAGE = `
+${bold('pipework')} — TypeScript framework for multi-tenant SaaS
+
+${bold('Commands:')}
+  init              Scaffold pipework.config.ts and migrations directory
+  sync              Generate workspace files (package.json, pnpm-workspace.yaml)
+  install           Sync workspace + pnpm install
+  upgrade [ver]     Upgrade pipework to a version (default: latest) + install
+  add <pkg@ver>     Add dependency to config, sync, and install
+  remove <pkg>      Remove dependency from config, sync, and install
+  generate          Generate SQL migrations from Drizzle schema changes
+  migrate           Run pending migrations for all databases
+  openapi           Write an http surface's OpenAPI document (no database needed; --surface <name>, --out <file>)
+  run <script>      Execute a script as a traced, audited flow (with --tenant: one transaction, rolled back if it throws)
+  test              Run tests with automatic database setup
+  check             Type-check, lint, and boundary enforcement
+  lint [eslint args]  Lint the current module (the workspace at its root) with check's config; every argument goes to eslint
+  codemod           Fill missing @downstream cardinality across the corpus
+  db                Database lifecycle: setup, teardown, reset
+  alerts unit-fault Record an abnormal systemd stop (ExecStopPost=pipework alerts unit-fault --unit %n)
+  alerts stale      Exit 1 and name any background loop that has stopped (run from a systemd timer; --max-age loop=5m)
+  dev               Start all surfaces with file watching
+  serve             Start all surfaces for production (no file watching)
+
+${bold('Options:')}
+  --help, -h              Show this help message
+  --version, -v           Show version
+  --name                  Migration name (used with generate)
+  --confirm               Required for production migrations
+  --tenant                Tenant ID; the script runs in one transaction on the default database
+  --job-type              Override job type (default: "script")
+  --port <n>              Port for the http surface that declares none (also PORT; dev, serve)
+  --surface <name>        openapi: the http surface to describe (default: the only one with openapi info)
+  --out <file>            openapi: write the document here instead of stdout
+  --worker-only           serve: run only the worker surfaces (no http port, no script surfaces: those belong to the main process)
+
+${bold('Scoping (check, test):')}
+  --fast                  Affected-only (branch diff); test runs fast tiers only
+  --full                  All modules, all test tiers
+  --all                   Run against all modules
+  --staged                Scope to staged changes (for pre-commit hooks)
+  --module <path>         Scope to a specific module
+  --suite <name>          Run a specific test suite/profile (test only)
+  --reap                  Drop orphan test databases and exit (test only)
+  --shard <i>/<n>         Run part i of n disjoint parts of the selected run (test, check); the n parts together equal the unsharded run
+
+${bold('Examples:')}
+  pipework init
+  pipework upgrade
+  pipework upgrade 0.8.0
+  pipework add stripe@^17.0.0
+  pipework remove stripe
+  pipework generate --name add-users
+  pipework generate --db app
+  pipework migrate --db app
+  pipework migrate --confirm          # required in production
+  pipework dev
+  pipework dev --port 4000
+  pipework serve                      # production: bind every surface, no watcher
+  pipework serve --worker-only        # an extra job worker against the same queue; opens no port
+  pipework dev --entry src/server.ts
+  pipework openapi --out openapi.json
+  pipework run ./scripts/seed.ts
+  pipework run ./scripts/backfill.ts --tenant t-123
+  pipework test
+  pipework test --all
+  pipework test --suite integration
+  pipework test --full --shard 2/4    # CI: part 2 of 4 across machines
+  pipework test --reap                # drop orphan test databases
+  pipework check --staged
+  pipework check --all
+  pipework lint                       # the module you are in, exactly as check lints it
+  pipework lint --format json --output-file r.json src/a.ts   # only src/a.ts
+  pipework codemod
+  pipework codemod --dry-run
+  pipework alerts unit-fault --unit subseam-core.service   # reads $SERVICE_RESULT, $EXIT_CODE, $EXIT_STATUS
+  pipework alerts stale --max-age jobs.claim=5m            # exit 1 with a line per stale loop; 0 and silent when none
+`
+
+export async function run(argv: string[]): Promise<void> {
+  // `lint` hands everything after it to eslint, flags included, so it is dispatched
+  // before parseArgs, which would refuse eslint's options.
+  if (argv[0] === 'lint') {
+    const cwd = process.cwd()
+    loadEnvFiles(cwd)
+    try {
+      const { lintCommand } = await import('./commands/lint.js')
+      process.exitCode = await lintCommand(cwd, argv.slice(1))
+    } catch (err) {
+      handleError(err)
+    }
+    return
+  }
+
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+      db: { type: 'string' },
+      unit: { type: 'string' },
+      database: { type: 'string' },
+      'max-age': { type: 'string', multiple: true },
+      name: { type: 'string' },
+      port: { type: 'string' },
+      surface: { type: 'string' },
+      out: { type: 'string' },
+      'worker-only': { type: 'boolean' },
+      entry: { type: 'string' },
+      confirm: { type: 'boolean' },
+      'allow-destructive': { type: 'boolean' },
+      'acknowledge-lock': { type: 'boolean' },
+      tenant: { type: 'string' },
+      'job-type': { type: 'string' },
+      all: { type: 'boolean' },
+      module: { type: 'string' },
+      staged: { type: 'boolean' },
+      fast: { type: 'boolean' },
+      full: { type: 'boolean' },
+      suite: { type: 'string' },
+      reap: { type: 'boolean' },
+      shard: { type: 'string' },
+      test: { type: 'boolean' },
+      'admin-url': { type: 'string' },
+      'dry-run': { type: 'boolean' },
+    },
+  })
+
+  if (values.help === true || positionals.length === 0) {
+    process.stderr.write(USAGE)
+    return
+  }
+
+  if (values.version === true) {
+    const { readFileSync } = await import('node:fs')
+    const { join, dirname } = await import('node:path')
+    const { fileURLToPath } = await import('node:url')
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version: string }
+    process.stdout.write(`${pkg.version}\n`)
+    return
+  }
+
+  const command = positionals[0]
+  const cwd = process.cwd()
+
+  loadEnvFiles(cwd)
+
+  try {
+    switch (command) {
+      case 'init': {
+        const { init } = await import('./commands/init.js')
+        await init(cwd)
+        break
+      }
+      case 'sync': {
+        const { syncCommand } = await import('./commands/sync.js')
+        await syncCommand(cwd)
+        break
+      }
+      case 'install': {
+        const { install } = await import('./commands/install.js')
+        await install(cwd)
+        break
+      }
+      case 'upgrade': {
+        const targetVersion = positionals[1]
+        const { upgrade: upgradeCmd } = await import('./commands/upgrade.js')
+        await upgradeCmd(cwd, targetVersion)
+        break
+      }
+      case 'add': {
+        const pkgs = positionals.slice(1)
+        const { add: addCmd } = await import('./commands/add.js')
+        await addCmd(cwd, pkgs)
+        break
+      }
+      case 'remove': {
+        const pkgs = positionals.slice(1)
+        const { remove: removeCmd } = await import('./commands/remove.js')
+        await removeCmd(cwd, pkgs)
+        break
+      }
+      case 'generate': {
+        const { generate } = await import('./commands/generate.js')
+        await generate({
+          db: values.db,
+          name: values.name,
+          cwd,
+        })
+        break
+      }
+      case 'migrate': {
+        const { migrate } = await import('./commands/migrate.js')
+        await migrate({
+          db: values.db,
+          cwd,
+          confirm: values.confirm,
+          allowDestructive: values['allow-destructive'],
+          acknowledgeLock: values['acknowledge-lock'],
+        })
+        break
+      }
+      case 'openapi': {
+        const { openapi } = await import('./commands/openapi.js')
+        await openapi({ cwd, surface: values.surface, out: values.out })
+        break
+      }
+      case 'run': {
+        const scriptPath = positionals[1]
+        if (scriptPath === undefined || scriptPath === '') {
+          error('Missing script path.')
+          process.stderr.write(`\n  Usage: ${bold('pipework run <script> [-- args...]')}\n\n`)
+          process.exit(1)
+        }
+        const { run: runScript } = await import('./commands/run.js')
+        await runScript({
+          script: scriptPath,
+          cwd,
+          tenant: values.tenant,
+          jobType: values['job-type'],
+        })
+        break
+      }
+      case 'test': {
+        const { parseScope: parseScopeTest } = await import('./commands/scope.js')
+        const parsedTest = parseScopeTest({ all: values.all, module: values.module, staged: values.staged, fast: values.fast, full: values.full, suite: values.suite })
+        const vitestArgs = positionals.slice(1)
+        const { parseShard } = await import('./commands/shard.js')
+        const shardTest = values.shard === undefined ? undefined : parseShard(values.shard)
+        if (shardTest !== undefined && values.reap === true) {
+          throw new Error('--shard cannot be combined with --reap.')
+        }
+        const { test: runTests } = await import('./commands/test.js')
+        await runTests({
+          cwd,
+          db: values.db,
+          vitestArgs,
+          scope: parsedTest.scope,
+          suite: parsedTest.suite,
+          fast: parsedTest.fast,
+          reap: values.reap,
+          shard: shardTest,
+        })
+        break
+      }
+      case 'check': {
+        const { parseScope: parseScopeCheck } = await import('./commands/scope.js')
+        const parsedCheck = parseScopeCheck({ all: values.all, module: values.module, staged: values.staged, fast: values.fast, full: values.full })
+        const { parseShard: parseShardCheck } = await import('./commands/shard.js')
+        const shardCheck = values.shard === undefined ? undefined : parseShardCheck(values.shard)
+        const { check } = await import('./commands/check.js')
+        await check(cwd, parsedCheck.scope, shardCheck)
+        break
+      }
+      case 'codemod': {
+        const { codemod } = await import('./commands/codemod.js')
+        await codemod({ cwd, dryRun: values['dry-run'] === true })
+        break
+      }
+      case 'db': {
+        const subcommand = positionals[1]
+        const { db: dbCmd } = await import('./commands/db.js')
+        await dbCmd({
+          cwd,
+          subcommand,
+          db: values.db,
+          test: values.test,
+          confirm: values.confirm,
+          adminUrl: values['admin-url'],
+        })
+        break
+      }
+      case 'alerts': {
+        const { alertsCommand } = await import('./commands/alerts.js')
+        await alertsCommand({ cwd, subcommand: positionals[1], unit: values.unit, database: values.database, maxAge: values['max-age'] })
+        break
+      }
+      case 'dev': {
+        const { dev } = await import('./commands/dev.js')
+        dev({ port: values.port, entry: values.entry, cwd })
+        break
+      }
+      case 'serve': {
+        const { serve } = await import('./commands/serve.js')
+        serve({ port: values.port, workerOnly: values['worker-only'] === true, cwd })
+        break
+      }
+      default:
+        error(`Unknown command: "${command}"`)
+        process.stderr.write(`\n  Run ${bold('pipework --help')} to see available commands.\n\n`)
+        process.exit(1)
+    }
+  } catch (err) {
+    handleError(err)
+  }
+}

package/src/cli/output.ts

@@ -0,0 +1,17 @@
+const BOLD = '\x1b[1m'
+const RED = '\x1b[31m'
+const GREEN = '\x1b[32m'
+const YELLOW = '\x1b[33m'
+const CYAN = '\x1b[36m'
+const RESET = '\x1b[0m'
+
+export function bold(text: string): string { return `${BOLD}${text}${RESET}` }
+export function red(text: string): string { return `${RED}${text}${RESET}` }
+export function green(text: string): string { return `${GREEN}${text}${RESET}` }
+export function yellow(text: string): string { return `${YELLOW}${text}${RESET}` }
+export function cyan(text: string): string { return `${CYAN}${text}${RESET}` }
+
+export function info(msg: string): void { process.stderr.write(`${cyan('ℹ')} ${msg}\n`) }
+export function success(msg: string): void { process.stderr.write(`${green('✓')} ${msg}\n`) }
+export function warn(msg: string): void { process.stderr.write(`${yellow('⚠')} ${msg}\n`) }
+export function error(msg: string): void { process.stderr.write(`${red('✗')} ${msg}\n`) }

package/src/cli/port.ts

@@ -0,0 +1,15 @@
+import { ConfigError } from '../core/config/errors.js'
+
+/** Parses the PORT variable: unset or empty is no port; otherwise an integer 0-65535. */
+export function parsePort(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === '') return undefined
+  const text = value.trim()
+  const n = Number(text)
+  if (!/^\d+$/.test(text) || !Number.isInteger(n) || n > 65535) {
+    throw new ConfigError(
+      `PORT is "${value}", which is not a port number.`,
+      'Set PORT to an integer from 0 to 65535, or unset it.',
+    )
+  }
+  return n
+}

package/src/cli/surface-kinds.ts

@@ -0,0 +1,20 @@
+import { ConfigError } from '../core/config/errors.js'
+import type { SurfaceKind } from '../core/surface/types.js'
+
+export const SURFACE_KINDS_ENV = 'PIPEWORK_SURFACE_KINDS'
+
+const KINDS: readonly SurfaceKind[] = ['http', 'worker', 'script']
+
+/** Parses PIPEWORK_SURFACE_KINDS, a comma list of surface kinds: unset or empty is every kind; an unknown kind is an error. */
+export function parseSurfaceKinds(value: string | undefined): readonly SurfaceKind[] | undefined {
+  if (value === undefined || value.trim() === '') return undefined
+  const parts = value.split(',').map(p => p.trim()).filter(p => p !== '')
+  const bad = parts.filter(p => !(KINDS as readonly string[]).includes(p))
+  if (bad.length > 0 || parts.length === 0) {
+    throw new ConfigError(
+      `${SURFACE_KINDS_ENV} is "${value}"; ${bad.map(b => `"${b}"`).join(', ') || 'no kind'} is not a surface kind.`,
+      `Set ${SURFACE_KINDS_ENV} to a comma list of: ${KINDS.join(', ')}, or unset it.`,
+    )
+  }
+  return [...new Set(parts)] as SurfaceKind[]
+}

package/src/client/index.ts

@@ -0,0 +1,4 @@
+export { reportClientFault, pageLeaving, LEAVING_HOLD_MS, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js'
+export type { ClientFaultReport, ReportClientFaultOptions } from './report-fault.js'
+export { startPolling, waitFromResponse } from './poll.js'
+export type { PollingOptions, PollingPage, PollAnswer } from './poll.js'

package/src/client/poll.ts

@@ -0,0 +1,130 @@
+// Browser-safe: no node imports, no runtime dependencies.
+
+/** What an ask may return to slow the next one: the next wait is at least `atLeastMs`. */
+export type PollAnswer = { atLeastMs: number } | void
+
+/** The part of `document` the poller uses. */
+export interface PollingPage {
+  readonly hidden: boolean
+  addEventListener(type: 'visibilitychange', listener: () => void): void
+  removeEventListener(type: 'visibilitychange', listener: () => void): void
+}
+
+export interface PollingOptions {
+  /** First wait in ms, before the first ask. Default 3000. */
+  firstMs?: number
+  /** Each wait is the last times `backOff`, up to this. Default 10000. */
+  longestMs?: number
+  /** At least 1; 1 is a fixed interval. Default 1.5. */
+  backOff?: number
+  /** Default true: nothing is asked while the page is hidden; visible again asks at once and the waits restart from `firstMs`. */
+  pauseWhenHidden?: boolean
+  /** An ask that throws or rejects stops nothing; the error is passed here and the next ask is scheduled. */
+  onError?: (error: unknown) => void
+  /** Default `document` when there is one. */
+  page?: PollingPage
+}
+
+function check(name: string, ok: boolean, rule: string, value: unknown): void {
+  if (!ok) throw new Error(`[pipework] startPolling: ${name} must be ${rule}, got ${String(value)}.`)
+}
+
+/**
+ * Calls `ask` after `firstMs`, then again after each answer, waiting longer each time (`backOff`, up to `longestMs`).
+ * One ask at a time: the next wait starts when the last ask settled. An ask returning `{ atLeastMs }` makes the next
+ * wait at least that long; the back-off carries on as if it had not. While the page is hidden nothing is asked.
+ * Returns `stop`, which is idempotent; an ask still in flight when it is called schedules nothing and reports no error.
+ */
+export function startPolling(ask: () => Promise<PollAnswer>, options: PollingOptions = {}): () => void {
+  const firstMs = options.firstMs ?? 3000
+  const longestMs = options.longestMs ?? 10_000
+  const backOff = options.backOff ?? 1.5
+  check('firstMs', Number.isFinite(firstMs) && firstMs >= 0, 'a non-negative finite number of ms', firstMs)
+  check('longestMs', Number.isFinite(longestMs) && longestMs >= 0, 'a non-negative finite number of ms', longestMs)
+  check('backOff', Number.isFinite(backOff) && backOff >= 1, 'a finite number of at least 1', backOff)
+  check('firstMs', firstMs <= longestMs, `at most longestMs (${longestMs})`, firstMs)
+
+  const page = options.page ?? (globalThis as { document?: PollingPage }).document
+  const watched = options.pauseWhenHidden !== false ? page : undefined
+
+  let stopped = false
+  let inFlight = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let base = firstMs
+
+  const nextWait = (): number => {
+    const wait = base
+    base = Math.min(base * backOff, longestMs)
+    return wait
+  }
+  const clear = (): void => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+  }
+  const schedule = (ms: number): void => {
+    clear()
+    timer = setTimeout(due, ms)
+  }
+  const due = (): void => {
+    timer = undefined
+    if (stopped || watched?.hidden === true) return
+    void run()
+  }
+  const run = async (): Promise<void> => {
+    inFlight = true
+    let answer: { atLeastMs: number } | undefined
+    try {
+      answer = (await ask()) ?? undefined
+    } catch (error) {
+      if (!stopped) options.onError?.(error)
+    }
+    inFlight = false
+    if (stopped) return
+    const atLeast = answer !== undefined && Number.isFinite(answer.atLeastMs) ? answer.atLeastMs : 0
+    schedule(Math.max(nextWait(), atLeast))
+  }
+  const onVisibility = (): void => {
+    if (stopped || watched === undefined || watched.hidden) return
+    clear()
+    base = firstMs
+    if (!inFlight) void run()
+  }
+
+  watched?.addEventListener('visibilitychange', onVisibility)
+  schedule(nextWait())
+
+  return () => {
+    if (stopped) return
+    stopped = true
+    clear()
+    watched?.removeEventListener('visibilitychange', onVisibility)
+  }
+}
+
+function fromHeader(value: string | null): number | undefined {
+  if (value === null) return undefined
+  const text = value.trim()
+  if (/^\d+$/.test(text)) return Number(text) * 1000
+  const at = Date.parse(text)
+  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now())
+}
+
+/**
+ * For a 429 or 503: how long the server asked the client to wait, as `{ atLeastMs }` to return from an ask.
+ * Reads `Retry-After` (seconds or an HTTP date); when that is absent or unreadable (a cross-origin page cannot see it
+ * without CORS `exposedHeaders`), reads `error.retryAfterSeconds` from the JSON body. The response's own body stays unread.
+ * Any other status, or no wait found, gives undefined.
+ */
+export async function waitFromResponse(response: Response): Promise<{ atLeastMs: number } | undefined> {
+  if (response.status !== 429 && response.status !== 503) return undefined
+  const fromHead = fromHeader(response.headers.get('retry-after'))
+  if (fromHead !== undefined) return { atLeastMs: fromHead }
+  try {
+    const body = (await response.clone().json()) as { error?: { retryAfterSeconds?: unknown } } | null
+    const seconds = body?.error?.retryAfterSeconds
+    if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds >= 0) return { atLeastMs: seconds * 1000 }
+  } catch {
+    // no readable body
+  }
+  return undefined
+}

package/src/client/report-fault.ts

@@ -0,0 +1,119 @@
+// Browser-safe: no node imports, no runtime dependencies.
+
+/** A failure the browser reports to the route made by `alerts.clientFaults`. */
+export interface ClientFaultReport {
+  /** A key of the route's `apps`. */
+  app: string
+  /** Where it happened: 1-100 characters of `A-Za-z0-9._:/-`, e.g. `checkout`. */
+  where: string
+  kind: 'error' | 'rejection' | 'render' | 'request'
+  /** Default `error`; a browser cannot raise `critical`. */
+  severity?: 'warning' | 'error'
+  /** At most 100 characters. */
+  code?: string
+  /** 1-500 characters; longer is cut by `reportClientFault`. */
+  message: string
+  /** At most 4096 characters; longer is cut by `reportClientFault`. */
+  stack?: string
+  /** A route pattern such as `/orders/:id`, at most 200 characters; never a page URL (no `?`, `#` or `://`). */
+  route?: string
+  /** At most 100 characters. */
+  release?: string
+  /** The trace id the page last saw: the `x-pipework-trace-id` header of an answer (expose it with CORS `exposedHeaders`). */
+  traceId?: string
+  /** The `x-request-id` of the answer the page last saw. At most 100 characters of `A-Za-z0-9._:-`. */
+  requestId?: string
+}
+
+export const CLIENT_FAULT_MESSAGE_MAX = 500
+export const CLIENT_FAULT_STACK_MAX = 4096
+
+/** How long a report made after `beforeunload` is held waiting for `pagehide` before the page is taken to be staying. */
+export const LEAVING_HOLD_MS = 10_000
+
+export interface ReportClientFaultOptions {
+  /** Default `hold`: a report made while the page is leaving waits, and is dropped if the page goes. `send` sends at once (a save cut off by leaving). */
+  whileLeaving?: 'hold' | 'send'
+}
+
+let leaving = false
+let left = false
+let timer: ReturnType<typeof setTimeout> | undefined
+let held: Array<() => void> = []
+
+function clearHold(): void {
+  if (timer !== undefined) clearTimeout(timer)
+  timer = undefined
+  held = []
+}
+
+function stay(): void {
+  const pending = held
+  leaving = false
+  left = false
+  if (timer !== undefined) clearTimeout(timer)
+  timer = undefined
+  held = []
+  for (const send of pending) send()
+}
+
+const win = globalThis as unknown as {
+  addEventListener?: (type: string, listener: (event: { persisted?: boolean }) => void, options?: { passive: boolean }) => void
+}
+
+if (typeof win.addEventListener === 'function') {
+  win.addEventListener('beforeunload', () => {
+    leaving = true
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(stay, LEAVING_HOLD_MS)
+  }, { passive: true })
+  win.addEventListener('pagehide', () => {
+    leaving = true
+    left = true
+    clearHold()
+  }, { passive: true })
+  win.addEventListener('pageshow', (event) => {
+    if (event.persisted === true) stay()
+  }, { passive: true })
+}
+
+/** True from `beforeunload` until the page stays again (the hold timer ran out or a bfcache restore); stays true after `pagehide`. */
+export function pageLeaving(): boolean {
+  return leaving
+}
+
+/**
+ * Sends a failure to the intake route at `url` with `keepalive`, so it survives a page unload.
+ * Cuts `message` and `stack` to their caps. A report made while the page is leaving is held and dropped on `pagehide`,
+ * unless `options.whileLeaving` is `send`. Never throws and never rejects: a report that cannot be sent is dropped.
+ */
+export function reportClientFault(url: string, report: ClientFaultReport, options?: ReportClientFaultOptions): void {
+  try {
+    const body: ClientFaultReport = { ...report, message: report.message.slice(0, CLIENT_FAULT_MESSAGE_MAX) }
+    if (body.stack !== undefined) body.stack = body.stack.slice(0, CLIENT_FAULT_STACK_MAX)
+    const send = (): void => {
+      try {
+        const sent = fetch(url, {
+          method: 'POST',
+          keepalive: true,
+          credentials: 'include',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(body),
+        })
+        Promise.resolve(sent).catch(() => undefined)
+      } catch {
+        // dropped
+      }
+    }
+    if (options?.whileLeaving !== 'send') {
+      if (left) return
+      if (leaving) {
+        held.push(send)
+        return
+      }
+    }
+    send()
+  } catch {
+    // dropped
+  }
+}

package/src/core/config/app-pool.ts

@@ -0,0 +1,19 @@
+import type { IsolationStrategy } from './schema.js'
+
+/**
+ * Whether the test harness ever creates the app-role pool under `strategy`.
+ *
+ * Transaction isolation registers its single rolled-back connection as the pool
+ * override under the database's *base* key (`src/test/plugin.ts`), and
+ * `getOrCreate(config, 'app')` falls back to that base override when no
+ * role-specific one is registered (`src/core/pipework.ts`) — so the app-role
+ * pool is never constructed and `appUrl`/`appTestUrl` are never dialed by it.
+ * Every other strategy resolves roles normally (`appUrl ?? url`) and creates it.
+ *
+ * This is the single statement of that fact: both the app-pair value-identity
+ * carve-out (`resolveDbUrl`) and the RLS probe target (`rlsProbeTarget`) are
+ * expressed in terms of it, so the two cannot drift apart.
+ */
+export function appPoolCreated(strategy: IsolationStrategy): boolean {
+  return strategy !== 'transaction'
+}

package/src/core/config/aws-env.ts

@@ -0,0 +1,29 @@
+/** The environment variables AWS credential discovery reads. Empty strings count as unset. */
+export interface AwsEnv {
+  readonly AWS_ACCESS_KEY_ID: string | undefined
+  readonly AWS_SECRET_ACCESS_KEY: string | undefined
+  readonly AWS_SESSION_TOKEN: string | undefined
+  readonly AWS_CONTAINER_CREDENTIALS_RELATIVE_URI: string | undefined
+  readonly AWS_CONTAINER_CREDENTIALS_FULL_URI: string | undefined
+  readonly AWS_CONTAINER_AUTHORIZATION_TOKEN: string | undefined
+  readonly AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE: string | undefined
+  readonly AWS_EC2_METADATA_DISABLED: string | undefined
+}
+
+/** Reads the AWS variables now; called on every resolve, never at import. */
+export function readAwsEnv(): AwsEnv {
+  const get = (name: string): string | undefined => {
+    const v = process.env[name]
+    return v === undefined || v === '' ? undefined : v
+  }
+  return {
+    AWS_ACCESS_KEY_ID: get('AWS_ACCESS_KEY_ID'),
+    AWS_SECRET_ACCESS_KEY: get('AWS_SECRET_ACCESS_KEY'),
+    AWS_SESSION_TOKEN: get('AWS_SESSION_TOKEN'),
+    AWS_CONTAINER_CREDENTIALS_RELATIVE_URI: get('AWS_CONTAINER_CREDENTIALS_RELATIVE_URI'),
+    AWS_CONTAINER_CREDENTIALS_FULL_URI: get('AWS_CONTAINER_CREDENTIALS_FULL_URI'),
+    AWS_CONTAINER_AUTHORIZATION_TOKEN: get('AWS_CONTAINER_AUTHORIZATION_TOKEN'),
+    AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE: get('AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE'),
+    AWS_EC2_METADATA_DISABLED: get('AWS_EC2_METADATA_DISABLED'),
+  }
+}