pipework 0.252.0 → 0.252.1

package/src/data/db/identifiers.ts

@@ -0,0 +1,16 @@
+const VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_\-]*$/
+
+export function assertValidIdentifier(value: string, label: string): void {
+  if (!VALID_IDENTIFIER.test(value)) {
+    throw new Error(
+      `[pipework] Invalid SQL identifier for ${label}: "${value}"\n\n` +
+      `  Identifiers must start with a letter or underscore and contain only\n` +
+      `  letters, digits, underscores, and hyphens.\n`
+    )
+  }
+}
+
+export function quoteIdentifier(value: string, label: string): string {
+  assertValidIdentifier(value, label)
+  return `"${value}"`
+}

package/src/data/db/idx/index.ts

@@ -0,0 +1,9 @@
+// Index and constraint builders — manual layer (wrappable)
+// Each re-export can be replaced with a pipework wrapper as needed.
+// e.g., `index` could auto-include tenant_id for tenant-scoped tables.
+
+export {
+  index, uniqueIndex,
+  primaryKey, foreignKey,
+  unique, check,
+} from '../../query/pg-core/index.js'

package/src/data/db/in-list.ts

@@ -0,0 +1,49 @@
+import { sql } from './sql.js'
+import type { SQL, Column } from './types.js'
+
+const CAST = /^[a-z_][a-z0-9_]*(\([0-9, ]+\))?$/i
+
+function fail(problem: string, fix: string): never {
+  throw new Error(`[pipework] filter.inList: ${problem}\n\n  Fix: ${fix}\n`)
+}
+
+function elementType(values: readonly (string | number)[], cast: string | undefined): string {
+  if (cast !== undefined && !CAST.test(cast)) fail(`cast "${cast}" is not a plain type name.`, "pass a type name such as 'uuid' or 'int'.")
+  const numeric = typeof values[0] === 'number'
+  for (const v of values as readonly unknown[]) {
+    if (v === null || v === undefined) fail('the list holds a null or undefined value.', 'drop nulls before passing the list.')
+    if (typeof v !== (numeric ? 'number' : 'string')) {
+      fail('the list must hold only strings or only numbers.', 'pass a list of one type, or convert the values first.')
+    }
+    if (numeric && !Number.isFinite(v as number)) fail('the list holds NaN or a non-finite number.', 'pass finite numbers only.')
+  }
+  if (cast !== undefined) return cast
+  if (!numeric) return 'text'
+  return (values as readonly number[]).every(v => Number.isInteger(v)) ? 'bigint' : 'numeric'
+}
+
+function bind(values: readonly string[] | readonly number[], cast: string | undefined): SQL {
+  if (!Array.isArray(values)) fail('the values are not an array.', 'pass a string[] or number[].')
+  return sql`${sql.param(values)}::${sql.raw(elementType(values, cast))}[]`
+}
+
+/**
+ * Membership of a JS list: `<expr> = ANY($1::text[])`, the list bound as one array parameter
+ * whatever its length and hashed by Postgres. An empty list is `false` (no parameter).
+ * Strings bind as `text`, integers as `bigint`, other numbers as `numeric`; pass `cast` for
+ * other columns, e.g. `inList(t.id, ids, 'uuid')`. Lifts `inArray`'s 65,535-parameter limit.
+ */
+export function inList(expr: Column | SQL, values: readonly string[] | readonly number[], cast?: string): SQL<boolean> {
+  if (values.length === 0 && cast !== undefined) bind(values, cast)
+  return values.length === 0 ? sql<boolean>`false` : sql<boolean>`${expr} = ANY(${bind(values, cast)})`
+}
+
+/**
+ * Non-membership of a JS list: `<expr> <> ALL($1::text[])`, the list bound as one array
+ * parameter. An empty list is `true` (no parameter). Types and `cast` as for `inList`
+ * (`notInList(t.id, ids, 'uuid')`); lifts `notInArray`'s 65,535-parameter limit.
+ */
+export function notInList(expr: Column | SQL, values: readonly string[] | readonly number[], cast?: string): SQL<boolean> {
+  if (values.length === 0 && cast !== undefined) bind(values, cast)
+  return values.length === 0 ? sql<boolean>`true` : sql<boolean>`${expr} <> ALL(${bind(values, cast)})`
+}

package/src/data/db/index.ts

@@ -0,0 +1,9 @@
+export { pipe } from './db.js'
+export type { DB, SQL, Table, Column, TransactionConfig } from './types.js'
+export { flowStorage as flowContext, runInContext, requireContext, getContext } from '../../request/context/store.js'
+export type { Flow } from '../../request/context/types.js'
+export { createTestContext as createContext } from '../../request/context/create.js'
+export { type ManagedConnection, type ConnectOptions, tap, createManagedConnection } from './pool.js'
+export { assertValidIdentifier, quoteIdentifier } from './identifiers.js'
+export { excluded } from './excluded.js'
+export { isDeadlock, logDeadlock, createDebugFn } from './instrumentation.js'

package/src/data/db/insert-split.ts

@@ -0,0 +1,137 @@
+// A drizzle handle's `insert(T).values(rows)` past postgres.js's 65,534-parameter
+// limit runs as several statements on that same handle, inside one transaction
+// (a savepoint when the handle is already a transaction), so a caller never counts binds.
+
+import type { PostgresJsDatabase } from '../query/postgres-js/index.js'
+import { getTableColumns } from '../query/index.js'
+
+/**
+ * Parameters one statement may bind, counting one per column per row (an upper
+ * bound; the margin covers `sql` values and an upsert's `set`). Not configurable.
+ */
+export const MAX_STATEMENT_PARAMETERS = 30_000
+
+/** Rows per statement under the parameter limit. */
+export function rowsPerStatement(table: unknown): number {
+  const columns = Object.keys(getTableColumns(table as never)).length
+  return Math.max(1, Math.floor(MAX_STATEMENT_PARAMETERS / Math.max(1, columns)))
+}
+
+type AnyFn = (...args: never[]) => unknown
+type Handle = PostgresJsDatabase
+interface Originals { insert: AnyFn; transaction: AnyFn }
+
+const patched = new WeakSet<object>()
+const originals = new WeakMap<object, Originals>()
+
+/**
+ * Patches `handle` in place (own `insert` and `transaction`) and returns it.
+ * `values(list)` over the budget returns a split insert; any other insert is
+ * drizzle's own builder. Transactions opened from the handle are patched too.
+ */
+export function splitLargeInserts(handle: Handle): Handle {
+  if (patched.has(handle)) return handle
+  patched.add(handle)
+  const h = handle as unknown as Record<string, AnyFn>
+  const insert = h['insert']!
+  const transaction = h['transaction']!
+  originals.set(handle, { insert, transaction })
+
+  h['insert'] = ((table: unknown): unknown => {
+    const builder = (insert as (this: unknown, t: unknown) => Record<string, AnyFn>).call(handle, table)
+    const values = builder['values']!
+    builder['values'] = ((rows: unknown): unknown => {
+      if (Array.isArray(rows) && rows.length > rowsPerStatement(table)) {
+        return new SplitInsert(handle, table, rows)
+      }
+      return (values as (this: unknown, r: unknown) => unknown).call(builder, rows)
+    }) as AnyFn
+    return builder
+  }) as AnyFn
+
+  h['transaction'] = ((fn: (tx: Handle) => Promise<unknown>, config?: unknown): unknown =>
+    (transaction as (this: unknown, f: unknown, c?: unknown) => unknown).call(
+      handle,
+      (tx: Handle) => fn(splitLargeInserts(tx)),
+      config,
+    )) as AnyFn
+
+  return handle
+}
+
+type Call = readonly [method: 'onConflictDoNothing' | 'onConflictDoUpdate' | 'returning', args: unknown[]]
+
+/** The insert `values(list)` returns for a list over the budget; awaiting it runs the slices. */
+class SplitInsert implements PromiseLike<unknown> {
+  private readonly calls: Call[] = []
+
+  constructor(
+    private readonly handle: Handle,
+    private readonly table: unknown,
+    private readonly rows: readonly unknown[],
+  ) {}
+
+  onConflictDoNothing(config?: unknown): this {
+    this.calls.push(['onConflictDoNothing', config === undefined ? [] : [config]])
+    return this
+  }
+
+  onConflictDoUpdate(config: unknown): this {
+    this.calls.push(['onConflictDoUpdate', [config]])
+    return this
+  }
+
+  returning(fields?: unknown): this {
+    this.calls.push(['returning', fields === undefined ? [] : [fields]])
+    return this
+  }
+
+  execute(): Promise<unknown> {
+    const size = rowsPerStatement(this.table)
+    const returns = this.calls.some(([method]) => method === 'returning')
+    return (this.handle.transaction as unknown as (fn: (tx: Handle) => Promise<unknown>) => Promise<unknown>)(async (tx) => {
+      const insert = originals.get(tx)!.insert as (this: unknown, t: unknown) => Record<string, AnyFn>
+      const rows: unknown[] = []
+      let count = 0
+      for (let i = 0; i < this.rows.length; i += size) {
+        let statement: unknown = insert.call(tx, this.table)['values']!(this.rows.slice(i, i + size) as never)
+        for (const [method, args] of this.calls) {
+          statement = (statement as Record<string, (...a: unknown[]) => unknown>)[method]!(...args)
+        }
+        const out = await (statement as PromiseLike<unknown>)
+        if (Array.isArray(out)) rows.push(...out)
+        const written = (out as { count?: unknown } | null)?.count
+        if (typeof written === 'number') count += written
+      }
+      return returns ? rows : Object.assign([], { count })
+    })
+  }
+
+  then<R1 = unknown, R2 = never>(
+    onfulfilled?: ((value: unknown) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): Promise<R1 | R2> {
+    return this.execute().then(onfulfilled, onrejected)
+  }
+
+  catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<unknown> {
+    return this.execute().catch(onrejected)
+  }
+
+  finally(onfinally?: (() => void) | null): Promise<unknown> {
+    return this.execute().finally(onfinally)
+  }
+
+  private refuse(method: string): never {
+    throw new Error(
+      `[pipework] ${method}() is not available: this insert has ${String(this.rows.length)} rows, over Postgres's ` +
+      `parameter limit, so it is split into several statements of at most ${String(rowsPerStatement(this.table))} rows. ` +
+      'Await it to run them in one transaction, or pass a shorter list.',
+    )
+  }
+
+  toSQL(): never { return this.refuse('toSQL') }
+  getSQL(): never { return this.refuse('getSQL') }
+  prepare(): never { return this.refuse('prepare') }
+  $dynamic(): never { return this.refuse('$dynamic') }
+}

package/src/data/db/instrumentation.ts

@@ -0,0 +1,82 @@
+import { getBaseLogger } from '../../core/logging/logger.js'
+import { getContext } from '../../request/context/store.js'
+import type { ResolvedObservability } from '../../core/config/load.js'
+
+const DEADLOCK_CODE = '40P01'
+const QUERY_TRUNCATE_LENGTH = 500
+
+/** postgres.js's `debug` hook signature. */
+type DebugFn = (connection: number, query: string, parameters: unknown[]) => void
+
+/**
+ * True when the driver's `debug` hook exists ONLY to feed a statement observer.
+ * Such a connection's errors are put back to their unobserved shape by the
+ * driver error boundary; `logAllQueries` connections are left exactly as they
+ * are today, that mode having already opted into verbose errors.
+ */
+export function isObserverOnly(config: ResolvedObservability): boolean {
+  return config.onStatement !== undefined && !config.logAllQueries
+}
+
+/**
+ * The driver's `debug` hook for a connection, or undefined when nothing is
+ * observing. Query logging and the caller-supplied `onStatement` observer are
+ * independent: either alone installs the hook, and with both configured both
+ * fire for every statement.
+ */
+export function createDebugFn(config: ResolvedObservability): DebugFn | undefined {
+  const logQuery = config.logAllQueries ? createQueryLogFn() : undefined
+  const observer = config.onStatement
+
+  if (!logQuery && !observer) return undefined
+  if (!observer) return logQuery
+  if (!logQuery) {
+    return (connection, query, parameters) => {
+      observer({ connectionId: connection, query, parameters })
+    }
+  }
+
+  return (connection, query, parameters) => {
+    logQuery(connection, query, parameters)
+    observer({ connectionId: connection, query, parameters })
+  }
+}
+
+function createQueryLogFn(): DebugFn {
+  return (connection: number, query: string) => {
+    const logger = getBaseLogger()
+    const ctx = getContext()
+    const fields: Record<string, unknown> = {
+      query: query.length > QUERY_TRUNCATE_LENGTH ? query.slice(0, QUERY_TRUNCATE_LENGTH) + '...' : query,
+      connection,
+    }
+
+    if (ctx) {
+      if (ctx.tenant !== null) fields['tenant'] = ctx.tenant
+      if (ctx.requestId !== '') fields['requestId'] = ctx.requestId
+    }
+
+    logger.debug(fields, 'query:execute')
+  }
+}
+
+export function isDeadlock(err: unknown): boolean {
+  if (!(err instanceof Error)) return false
+  return 'code' in err && (err as { code: unknown }).code === DEADLOCK_CODE
+}
+
+export function logDeadlock(err: unknown, dbName: string): void {
+  const logger = getBaseLogger()
+  const ctx = getContext()
+  const fields: Record<string, unknown> = {
+    err,
+    database: dbName,
+  }
+
+  if (ctx) {
+    if (ctx.tenant !== null) fields['tenant'] = ctx.tenant
+    if (ctx.requestId !== '') fields['requestId'] = ctx.requestId
+  }
+
+  logger.error(fields, 'deadlock detected')
+}

package/src/data/db/maintenance.ts

@@ -0,0 +1,28 @@
+// The maintenance setting: lets framework passes that must read or update the
+// built-in trace and audit tables across tenants (closing a trace, expiring
+// stale ones, retiring an audit partition, verifying the tenantless chain)
+// satisfy those tables' row-level security policies. Set transaction-locally,
+// by the framework only; application code must never set it.
+
+import { sql } from './sql.js'
+import type { DB } from './index.js'
+
+export const MAINTENANCE_SETTING = 'pipework.maintenance'
+
+/** The policy predicate that admits a maintenance transaction. */
+export const MAINTENANCE_CLAUSE = `current_setting('${MAINTENANCE_SETTING}', true) = 'on'`
+
+/**
+ * Runs `fn` in a transaction (a savepoint when `db` is already one) with the
+ * maintenance setting on, and puts the previous value back when `fn` returns.
+ */
+export async function withMaintenance<T>(db: DB, fn: (tx: DB) => Promise<T>): Promise<T> {
+  return db.transaction(async raw => {
+    const tx = raw as unknown as DB
+    const before = await tx.execute(sql`SELECT current_setting(${MAINTENANCE_SETTING}, true) AS v`)
+    await tx.execute(sql`SELECT set_config(${MAINTENANCE_SETTING}, 'on', true)`)
+    const result = await fn(tx)
+    await tx.execute(sql`SELECT set_config(${MAINTENANCE_SETTING}, ${(before[0]?.['v'] as string | null) ?? ''}, true)`)
+    return result
+  })
+}

package/src/data/db/namespace.ts

@@ -0,0 +1,107 @@
+import { pipe as getDb, pipeSystem, pipeDoor } from './db.js'
+import { sql } from './sql.js'
+import { labelled } from './query-label.js'
+import { migrateAll, migrateOne } from '../migrate/index.js'
+import { filter } from './filter.js'
+import { excluded } from './excluded.js'
+import { advisoryLock, tryAdvisoryLock } from './advisory-lock.js'
+import { serializable } from './serializable.js'
+import { withTimeouts } from './timeouts.js'
+import { bulkSet } from './bulk-set.js'
+import { values } from './values.js'
+import { fn } from './function-source.js'
+import { update, insert, remove, upsert } from '../write/index.js'
+
+import { aliasedRelation, aliasedTable, aliasedTableColumn, getTableColumns, getTableName, getViewName, getViewSelectedFields, isTable, createMany, createOne, relations } from '../query/index.js'
+
+// Domain definitions
+import { field, define, definitions, external } from '../domain/index.js'
+
+// Pipework-owned type aliases
+export type { DB, SQL, Table, Column, TransactionConfig } from './types.js'
+
+/** Query operators and aggregates — eq, gt, lt, and, or, count, sum, etc. */
+export { filter } from './filter.js'
+
+/** Returns excluded-column references for onConflictDoUpdate set clauses. */
+export { excluded } from './excluded.js'
+
+/** Database accessor — returns a Drizzle DB instance scoped to the current request/job/test context. Requires active AsyncLocalStorage context. */
+export const pipe = Object.assign(getDb, {
+  /** The system channel — deliberate cross-tenant access for pre-tenant surfaces (auth membership resolution, public webhook ingress, admin tooling). Never tenant-scoped or tenant-guarded; runs on the owner-role connection outside the request transaction. */
+  system: pipeSystem,
+
+  /** A named cross-tenant read: `pipe.door(name, db => ...)`. The door is declared under `doors` in config; the callback runs in one transaction on the platform-role connection and may SELECT from the door's table and from non-tenant tables. Needs `rls.platformRole`. */
+  door: pipeDoor,
+
+  /** Query operators and aggregates — eq, gt, lt, and, or, count, sum, etc. */
+  filter,
+
+  /** Names every statement `fn` starts, in `query:slow` and `query:in-flight` log lines: `pipe.labelled('servable-footprints', async () => await ...)`. A query builder is lazy: `fn` must await it, not return it, or it runs outside the scope. */
+  labelled,
+
+  /** Raw statement tag — for a statement pipework does not model. Interpolated values are parameters; `sql.raw` is not. Runs on the caller's connection, so inside a request it is the request transaction. Writes still go through pipe.update / insert / delete, which is what audit hooks. */
+  sql,
+
+  // Introspection — aliasedTable, aliasedRelation, getTableColumns, getTableName, getViewName, etc.
+  aliasedRelation,
+  aliasedTable,
+  aliasedTableColumn,
+  getTableColumns,
+  getTableName,
+  getViewName,
+  getViewSelectedFields,
+  isTable,
+
+  // Relations — relations(), createOne(), createMany()
+  createMany,
+  createOne,
+  relations,
+
+  /** Runs migrations for all configured databases. */
+  migrate: migrateAll,
+  /** Runs migrations for a single named database. */
+  migrateOne,
+
+  /** Returns excluded-column references for onConflictDoUpdate set clauses. */
+  excluded,
+
+  /** Acquires a transaction-scoped advisory lock. Released at commit/rollback. */
+  advisoryLock,
+
+  /** Non-blocking advisoryLock: true if the transaction-scoped lock was won, false if another transaction holds it. */
+  tryAdvisoryLock,
+
+  /** Runs a function in a SERIALIZABLE transaction with automatic retry on serialization failures and deadlocks. */
+  serializable,
+
+  /** Sets statement_timeout and/or lock_timeout for the current transaction in one statement, then runs fn; a statement cancelled for them rejects with StatementTimeoutError or LockTimeoutError. */
+  withTimeouts,
+
+  /** Bulk UPDATE ... FROM (VALUES ...) — updates multiple rows with per-row values in a single statement. */
+  bulkSet,
+
+  /** Produces a typed VALUES clause for bulk operations — the base primitive for bulkSet and bulkUpsert. */
+  values,
+
+  /** A set-returning SQL function as a typed source for `.from()` and joins — `pipe.fn('schema.f', { args: [field.uuid()], columns: { path: field.text() } })`. Arguments are bound and cast to their declared types. */
+  fn,
+
+  /** Field builders for domain definitions — uuid(), text(), integer(), etc. */
+  field,
+  /** Registers a domain definition with table, validators, and factory projections. The `auditEntity` option names the `@touches` entity writes to this table are audited under (see `__flowStep`). */
+  define,
+  /** Returns the global registry of all domain definitions. */
+  definitions,
+  /** Declares a table or view another service owns (`pipe.external(name, fields, { schema, table? })`): typed columns and every query operator, read-only, never migrated, not tenant-scoped. */
+  external,
+
+  /** Pipework-owned UPDATE builder — the only consumer-facing way to update pipework-managed tables (Q8). */
+  update,
+  /** Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction. */
+  insert,
+  /** Pipework-owned DELETE builder — the only consumer-facing way to delete from pipework-managed tables (Q8). */
+  delete: remove,
+  /** Pipework-owned UPSERT builder — insert with conflict resolution (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction; rows repeating a conflict key across statements do not fail as one statement would. */
+  upsert,
+})

package/src/data/db/owner-labels.ts

@@ -0,0 +1,9 @@
+/**
+ * Callers that legitimately open the owner-role connection of a platform-mode
+ * database: they run DDL. Everything else runs on the platform role.
+ */
+export const OWNER_LABEL_MIGRATE = 'migrate'
+/** Trace and audit partition maintenance (`createTracePartitionStartupHook`, `scheduleTracePartitionMaintenance`): the app passes it `getOrCreate(config, 'owner', label)`. */
+export const OWNER_LABEL_TRACE_PARTITIONS = 'trace-partition-maintenance'
+
+export const OWNER_DDL_LABELS: readonly string[] = [OWNER_LABEL_MIGRATE, OWNER_LABEL_TRACE_PARTITIONS]

package/src/data/db/pool.ts

@@ -0,0 +1,187 @@
+import postgres from 'postgres'
+import { drizzle, type PostgresJsDatabase } from '../query/postgres-js/index.js'
+import type { ResolvedDatabase } from '../../core/config/load.js'
+import type { ResolvedObservability } from '../../core/config/load.js'
+import { createDebugFn, isObserverOnly } from './instrumentation.js'
+import { markObservedConnection } from '../query/postgres-js/driver-error-boundary.js'
+import { warnRawClientIsUnsanitized } from './raw-client-warning.js'
+import { splitLargeInserts } from './insert-split.js'
+import { createStatementWatch } from './query-watch.js'
+
+/** Which database role a pooled connection authenticates as. `owner` runs migrations/bootstrap and owns tables (bypasses RLS); `app` is the non-owner, non-BYPASSRLS runtime role that RLS policies enforce against; `system` is the platform role (`rls.platformRole`, via `systemUrl`), which reaches a tenant table only through a declared door. */
+export type ConnectionRole = 'owner' | 'app' | 'system'
+
+/** A standalone pooled connection: the raw postgres.js client, its drizzle handle, and a `close()` that ends the pool. */
+export interface ManagedConnection {
+  readonly name: string
+  /**
+   * The raw postgres.js client — deliberately unmediated. With
+   * `observability.onStatement` configured, queries issued through it fall
+   * outside pipework's driver error boundary, so their errors serialize bind
+   * parameters; `connection.drizzle` does not. Reading this on an observed
+   * connection logs a warning once per database.
+   */
+  readonly client: postgres.Sql
+  readonly drizzle: PostgresJsDatabase
+  /** Test override only: this connection's handle for `pipe.system()`, reading across tenants under row-level security. */
+  readonly system?: PostgresJsDatabase
+  /** Test override only: a handle for `pipe.door(name)` on the test connection, with that door's setting open for each statement. */
+  readonly door?: (name: string) => PostgresJsDatabase
+  /**
+   * The ids of every pooled connection (opening up to `max`), ascending by
+   * `connectionId`. `connectionId` is the driver ordinal that
+   * `observability.onStatement` events carry as `StatementEvent.connectionId`;
+   * `backendPid` is the server's `pg_backend_pid()`, matching `pg_stat_activity`.
+   *
+   * Holds all `max` connections at once, runs one `SELECT pg_backend_pid()` on
+   * each, then releases them. The probes are real statements, so they reach
+   * `onStatement` like any other: one `SELECT pg_backend_pid()` per connection,
+   * plus the driver's own type lookup on a connection not yet used. Waits for
+   * connections in use elsewhere to be free.
+   *
+   * Needs the driver's `debug` hook (configure `observability.onStatement`);
+   * without it, throws.
+   */
+  connectionIds(): Promise<ReadonlyArray<{ connectionId: number; backendPid: number }>>
+  close(options?: { timeoutSeconds?: number }): Promise<void>
+}
+
+/** Options for `tap()` — pool size (default 1), idle timeout in seconds, and session settings (GUCs) sent in every connection's startup packet. */
+export interface ConnectOptions {
+  readonly max?: number
+  readonly idleTimeout?: number
+  readonly settings?: Readonly<Record<string, string | number | boolean>>
+}
+
+function startupSettings(settings: Readonly<Record<string, string | number | boolean>>): 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
+}
+
+const PROBE_QUERY = 'SELECT pg_backend_pid() AS pid'
+
+/** Slot the wrapped debug hook fills with the ordinal of the connection a probe runs on. */
+interface ProbeSlot { current: ((connectionId: number) => void) | null }
+
+async function probeConnectionIds(
+  client: postgres.Sql,
+  slot: ProbeSlot | undefined,
+): Promise<ReadonlyArray<{ connectionId: number; backendPid: number }>> {
+  if (!slot) {
+    throw new Error(
+      '[pipework] connectionIds() cannot read the driver\'s connection ordinals: this connection has no statement hook.\n' +
+      '  Fix: connectionIds() exists to correlate with observability.onStatement events; configure observability.onStatement on the manifold.',
+    )
+  }
+  const max = client.options.max
+  const settled = await Promise.allSettled(Array.from({ length: max }, () => client.reserve()))
+  const reserved = settled.flatMap(r => (r.status === 'fulfilled' ? [r.value] : []))
+  try {
+    const failed = settled.find((r): r is PromiseRejectedResult => r.status === 'rejected')
+    if (failed) throw failed.reason
+    const out: Array<{ connectionId: number; backendPid: number }> = []
+    for (const conn of reserved) {
+      let connectionId: number | undefined
+      slot.current = (id: number) => { connectionId ??= id }
+      let rows: Array<{ pid: number }>
+      try {
+        rows = await conn.unsafe<Array<{ pid: number }>>(PROBE_QUERY)
+      } finally {
+        slot.current = null
+      }
+      const pid = rows[0]?.pid
+      if (connectionId === undefined || pid === undefined) {
+        throw new Error('[pipework] connectionIds() could not read a connection\'s ordinal and backend pid.\n  Fix: report this as a bug; the probe statement was not seen by the driver hook.')
+      }
+      out.push({ connectionId, backendPid: pid })
+    }
+    out.sort((a, b) => a.connectionId - b.connectionId)
+    if (new Set(out.map(o => o.connectionId)).size !== out.length) {
+      throw new Error('[pipework] connectionIds() saw the same connection twice.\n  Fix: report this as a bug; reserved connections must be distinct.')
+    }
+    return out
+  } finally {
+    for (const conn of reserved) conn.release()
+  }
+}
+
+/**
+ * Opens a standalone managed connection outside the manifold's pools — the
+ * sanctioned door for contexts where `pipe()` structurally cannot resolve:
+ * `worker_threads`, detached monitors, one-off scripts. Callers own the
+ * lifecycle: always `await conn.close()`.
+ */
+export function tap(url: string, options?: ConnectOptions): ManagedConnection {
+  const client = postgres(url, {
+    max: options?.max ?? 1,
+    onnotice: () => {},
+    ...(options?.idleTimeout !== undefined ? { idle_timeout: options.idleTimeout } : {}),
+    ...(options?.settings !== undefined ? { connection: startupSettings(options.settings) } : {}),
+  })
+
+  const db = splitLargeInserts(drizzle(client))
+
+  return {
+    name: 'manual',
+    client,
+    drizzle: db,
+    connectionIds: () => probeConnectionIds(client, undefined),
+    async close(options) {
+      await client.end(endOptions(options))
+    },
+  }
+}
+
+/** Builds the pooled connection for one resolved database — used by the manifold's pool manager; consumers outside a managed context use `tap()` or `pool.getOrCreate()`. */
+export function createManagedConnection(
+  config: ResolvedDatabase,
+  onClose: () => void,
+  observability?: ResolvedObservability,
+  applicationName?: string,
+): ManagedConnection {
+  const baseDebug = observability ? createDebugFn(observability) : undefined
+  const slot: ProbeSlot | undefined = baseDebug ? { current: null } : undefined
+  const debug = baseDebug && slot
+    ? ((connection, query, parameters) => {
+        if (slot.current && query === PROBE_QUERY) slot.current(connection)
+        baseDebug(connection, query, parameters)
+      }) as typeof baseDebug
+    : undefined
+  const client = postgres(config.url, {
+    max: config.pool.max,
+    idle_timeout: config.pool.idleTimeout,
+    onnotice: () => {},
+    ...(config.pool.settings !== undefined || applicationName !== undefined
+      ? { connection: { ...(applicationName !== undefined ? { application_name: applicationName } : {}), ...config.pool.settings } }
+      : {}),
+    ...(debug ? { debug } : {}),
+  })
+
+  const observerOnly = observability !== undefined && isObserverOnly(observability)
+  if (observerOnly) markObservedConnection(client)
+
+  const statementWatch = observability
+    ? createStatementWatch({ database: config.name, url: config.url, slowQueryMs: observability.slowQueryMs, inFlightQueryMs: observability.inFlightQueryMs })
+    : undefined
+  const db = splitLargeInserts(drizzle(client, statementWatch ? { statementWatch: statementWatch.watch } : {}))
+
+  return {
+    name: config.name,
+    get client() {
+      if (observerOnly) warnRawClientIsUnsanitized(config.name)
+      return client
+    },
+    drizzle: db,
+    connectionIds: () => probeConnectionIds(client, slot),
+    async close(options) {
+      onClose()
+      await statementWatch?.close()
+      await client.end(endOptions(options))
+    },
+  }
+}
+
+function endOptions(options: { timeoutSeconds?: number } | undefined): { timeout?: number } {
+  return options?.timeoutSeconds === undefined ? {} : { timeout: options.timeoutSeconds }
+}

package/src/data/db/query-label.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+const scope = new AsyncLocalStorage<string>()
+
+/** Runs `fn` with `label` naming every statement it starts, in slow-query and in-flight-query log lines. */
+export function labelled<T>(label: string, fn: () => T): T {
+  return scope.run(label, fn)
+}
+
+/** The label of the enclosing `labelled` scope, if any. */
+export function currentQueryLabel(): string | undefined {
+  return scope.getStore()
+}