pipework 0.157.0 → 0.159.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.159.0
+
+- **Fixed: type-checking an app costs what it did on 0.148 again** (#690). Since 0.149 the validator types `check.*` return (`StringSchema`, `OptionalSchema`, `ObjectSchema`, …) were interfaces overriding `optional()` / `nullable()` with `this`-typed results, and `ObjectSchema` an intersection; every comparison with `Schema<T>` recursed to TypeScript's depth limit. On verity's backend that was 11.0M instantiations and over 4 GB (plain `tsc` ran out of heap); it is now 2.0M and 1.1 GB, the same as 0.148. The named types are now aliases of zod's classes, and those classes (`ZodString`, `ZodNumber`, `ZodBoolean`, `ZodEnum`, `ZodLiteral`, `ZodArray`, `ZodOptional`, `ZodNullable`, `ZodObject`, `$strip`) are exported type-only from `pipework`, so an app without zod still exports validators unannotated (#673). `.extend` / `.pick` / `.omit` / `.partial` stay typed and recursive getter schemas still infer. Hover shows zod's types again instead of `Pick<…>` / `Omit<…>`. All existing type names still export.
+
+## 0.158.0
+
+- **Added: session settings that survive connection replacement** (#338). `databases.<name>.pool.settings` (and `tap(url, { settings })`) takes session settings (GUCs) such as `{ statement_timeout: '30s', 'myapp.mode': 'bench' }` and sends them in the startup packet of every pooled connection. postgres.js replaces a connection after its max lifetime (30 to 60 minutes); a session `SET` on the old connection was silently lost on the new one, while startup settings are carried again by every new socket. Values may be strings, numbers or booleans (`on`/`off`). A name that is not letters, digits and underscores with at most one dot is a config error. An unknown non-dotted name makes the connection fail (Postgres's `unrecognized configuration parameter` is the error's `cause`) rather than being ignored.
+
 ## 0.157.0
 
 - **Fixed: `pipework test <path>` that runs nothing exits 1** (#337). When a path or name filter is given and the affected-module scope is empty, nothing ran, and the command used to print `✓ No affected modules — nothing to test` and exit 0, so a reverted file looked green. It now prints `Nothing ran: no affected module in scope (<basis>), so <filters> did not run. Run with --all to test it regardless.` and exits 1. Bare `pipework test` with nothing affected still exits 0. **Behavior change:** a script or hook that passes a path and relied on exit 0 for an unaffected path now fails; add `--all`.

package/REFERENCE.md

@@ -890,7 +890,9 @@ interface ManagedConnection
 
 `ManagedConnection.connectionIds()` returns `ReadonlyArray<{ connectionId: number; backendPid: number }>` for every pooled connection (opening up to `max`), ascending by `connectionId`. `connectionId` is the driver ordinal `StatementEvent.connectionId` carries in `observability.onStatement`; `backendPid` is `pg_backend_pid()`, matching `pg_stat_activity`. It holds all `max` connections, runs one `SELECT pg_backend_pid()` on each and releases them; those probes reach `onStatement` like any statement (plus the driver's type lookup on a new connection). Without `observability.onStatement` (or `logAllQueries`), and on `tap()` connections, it throws a `[pipework]` error.
 
-**`ConnectOptions`** — Options for `tap()` — pool size (default 1) and idle timeout in seconds.
+**`ConnectOptions`** — Options for `tap()` — pool size (default 1), idle timeout in seconds, and `settings` (see below).
+
+**Session settings (`databases.<name>.pool.settings`, `tap({ settings })`)** — `Record<string, string | number | boolean>`, default none. Each entry is a Postgres session setting (GUC) sent in the connection's startup packet, so every pooled socket carries it from its first packet, including a connection the pool replaced at `max_lifetime` or after a backend was terminated. A session `SET` on a pooled connection does not survive replacement; use `settings` for anything that must hold for the life of the pool. Names are `name` or `prefix.name` (letters, digits, underscores); anything else is a config error. Values are stringified (`true` is `on`, `false` is `off`). A dotted custom name (`myapp.tenant`) is always accepted. An unknown non-dotted name is rejected by Postgres: the connection fails, and the first query on the pool rejects, and the error's `cause` is Postgres's own (`unrecognized configuration parameter "..."`); pipework does not translate it.
 
 ```typescript
 interface ConnectOptions

package/dist/REFERENCE.md

@@ -1,7 +1,7 @@
 # Pipework API Reference
 
 > Auto-generated from source JSDoc. Do not edit manually.
-> Generated: 2026-10-09
+> Generated: 2026-10-22
 
 ## Contents
 
@@ -10,6 +10,7 @@
 - [jobs — Background Jobs](#jobs-background-jobs)
 - [pipeline — Multi-Step Pipelines](#pipeline-multi-step-pipelines)
 - [state — State Machines](#state-state-machines)
+- [steps](#steps)
 - [auth — Authentication](#auth-authentication)
 - [rbac — Access Control](#rbac-access-control)
 - [tenant — Multi-Tenancy](#tenant-multi-tenancy)
@@ -30,7 +31,9 @@
 - [cache — Caching](#cache-caching)
 - [credits](#credits)
 - [mail](#mail)
+- [untrustedFetch](#untrustedfetch)
 - [storage](#storage)
+- [support](#support)
 - [webhook — Inbound & Outbound Webhooks](#webhook-inbound-outbound-webhooks)
 - [behavior — Resource Decorators](#behavior-resource-decorators)
 - [fitting — Dependency Injection](#fitting-dependency-injection)
@@ -85,6 +88,18 @@ function createManifold<const TEnv extends EnvDefs = EnvDefs>( raw: Omit<Bluepri
 interface Manifold<TEnv extends EnvDefs = EnvDefs>
 ```
 
+**`ScriptOptions`** — Options for {@link Manifold.script}.
+
+```typescript
+interface ScriptOptions
+```
+
+**`StartOptions`** — Options for {@link Manifold.start}.
+
+```typescript
+interface StartOptions
+```
+
 **`SeedOptions`** — ALS context the {@link Manifold.seed} callback runs under — tenant scope, auth principal, and job type.
 
 ```typescript
@@ -229,6 +244,14 @@ Creates a job queue with claim/complete/fail lifecycle, heartbeat, and dead lett
 
 Executes a fitting handler as a background job with its own Flow context.
 
+### `jobs.later`
+
+The error to throw to end an attempt as "later": pending again after `delayMs`, no attempt counted.
+
+### `jobs.permanent`
+
+The error to throw to dead-letter the job now, whatever attempts remain.
+
 ### `jobs.parseCron`
 
 Parses a 5-field cron expression into a CronSchedule (minute, hour, dom, month, dow).
@@ -269,6 +292,14 @@ Thrown when a transition is not allowed from the current state.
 
 Thrown when the state machine definition is internally inconsistent.
 
+## steps
+
+Step graphs over a job queue: results recorded by their inputs, only missing steps run.
+
+### `steps.define`
+
+Defines a graph of named steps over a jobs Queue. Pass it to `createWorkerSurface({ graphs })` to run its steps.
+
 ## auth — Authentication
 
 Authentication namespace — session management, multi-org support, auth chain resolution.
@@ -289,6 +320,10 @@ Hashes and verifies passwords with scrypt; reports when a stored hash needs reha
 
 Guarded password sign-in that slows, then refuses, repeated failures per account and per client.
 
+### `auth.emailLinks`
+
+Emailed single-use links that prove control of an address: password reset and address verification; the token is never stored.
+
 ### `auth.runChain`
 
 Executes an auth chain (strategy pipeline) to resolve auth + tenant from a request.
@@ -323,7 +358,7 @@ interface AuthContext
 interface AuthStrategy<TAuth>
 ```
 
-**`AuthRequest`** — Normalized request shape passed to auth strategies — headers, cookies, method, url.
+**`AuthRequest`** — Normalized request shape passed to auth strategies — headers, the parsed `Cookie` header, and the upper-case HTTP method.
 
 ```typescript
 interface AuthRequest
@@ -353,6 +388,18 @@ interface TenantResolver<TAuth>
 interface AuthChainConfig<TAuth>
 ```
 
+**`SessionAuth`** — What `sessions.strategy()` authenticates: the token's user and org, its roles, and where the token came from.
+
+```typescript
+type SessionAuth = BaseAuth &
+```
+
+**`SessionStrategyOptions`** — Options for `sessions.strategy()`.
+
+```typescript
+interface SessionStrategyOptions
+```
+
 **`SessionConfig`** — Session configuration — signing keys, issuer, audience, token TTLs, refresh rotation.
 
 ```typescript
@@ -624,6 +671,10 @@ Base error class with code, statusCode, and suggestion fields.
 
 403 — authenticated but insufficient permissions.
 
+### `errors.CrossSiteRequest`
+
+403 `CROSS_SITE_REQUEST` — a cookie-authenticated write that did not come from the app's own site.
+
 ### `errors.Validation`
 
 422 — input validation failed, carries field-level details.
@@ -644,13 +695,17 @@ Base error class with code, statusCode, and suggestion fields.
 
 415 — request body media type not accepted by the route.
 
+### `errors.MalformedMultipart`
+
+400 `MALFORMED_MULTIPART` — a multipart body that cannot be parsed or ends before its closing boundary.
+
 ## lifecycle — Startup & Shutdown
 
 Application lifecycle namespace — startup orchestration with hooks and timeouts.
 
 ### `lifecycle.orchestrate`
 
-Runs pre-start hooks (DB readiness checks, migrations, etc.) with a configurable timeout.
+Runs pre-start hooks (DB readiness checks, migrations, etc.) with a configurable timeout. The hooks run in one trace that names the process; the trace-partition hook runs first, outside it.
 
 ## log — Structured Logging
 
@@ -690,7 +745,7 @@ Creates a worker surface — a long-running process that claims and executes job
 
 ### `surface.script`
 
-Creates a script surface — a one-shot process that runs and exits (migrations, seeds, CLI tools).
+Creates a script surface — a one-shot process that runs and exits (migrations, seeds, CLI tools). The run is traced as a job-kind trace that names the surface.
 
 ## pipe — Database
 
@@ -761,6 +816,10 @@ Acquires a transaction-scoped advisory lock. Released at commit/rollback.
 
 Runs a function in a SERIALIZABLE transaction with automatic retry on serialization failures and deadlocks.
 
+### `pipe.withTimeouts`
+
+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.
+
 ### `pipe.bulkSet`
 
 Bulk UPDATE ... FROM (VALUES ...) — updates multiple rows with per-row values in a single statement.
@@ -769,6 +828,10 @@ Bulk UPDATE ... FROM (VALUES ...) — updates multiple rows with per-row values
 
 Produces a typed VALUES clause for bulk operations — the base primitive for bulkSet and bulkUpsert.
 
+### `pipe.fn`
+
+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.
+
 ### `pipe.field`
 
 Field builders for domain definitions — uuid(), text(), integer(), etc.
@@ -781,13 +844,17 @@ Registers a domain definition with table, validators, and factory projections. T
 
 Returns the global registry of all domain definitions.
 
+### `pipe.external`
+
+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.
+
 ### `pipe.update`
 
 Pipework-owned UPDATE builder — the only consumer-facing way to update pipework-managed tables (Q8).
 
 ### `pipe.insert`
 
-Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8).
+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.
 
 ### `pipe.delete`
 
@@ -795,7 +862,7 @@ Pipework-owned DELETE builder — the only consumer-facing way to delete from pi
 
 ### `pipe.upsert`
 
-Pipework-owned UPSERT builder — insert with conflict resolution (Q8).
+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.
 
 ### Types
 
@@ -811,12 +878,54 @@ interface WindowSpec
 interface ValueColumnDef
 ```
 
+**`JsonbElements`** — A jsonb array read as its elements' text. Produced by {@link jsonbElements}.
+
+```typescript
+interface JsonbElements
+```
+
+**`ArraySource`** — Something whose elements `arrayAny` / `arrayAll` can test.
+
+```typescript
+type ArraySource =
+```
+
+**`ElementOf`** — The element type of an {@link ArraySource}.
+
+```typescript
+type ElementOf<S> =
+```
+
+**`FunctionSpec`** — Declares a SQL function's argument and result-column shapes. See {@link fn}.
+
+```typescript
+interface FunctionSpec<TArgs extends readonly AnyField[], TColumns extends Record<string, AnyField>>
+```
+
+**`FunctionSourceFields`** — The selected fields of a function source: each result column as a typed SQL expression.
+
+```typescript
+type FunctionSourceFields<TColumns extends Record<string, AnyField>> =
+```
+
+**`FunctionSource`** — A function call usable in `.from()` and joins; its result columns are properties of it.
+
+```typescript
+type FunctionSource<TAlias extends string, TColumns extends Record<string, AnyField>> =
+```
+
 **`SerializableOptions`** — Retry policy for {@link serializable}: how many attempts on a serialization failure / deadlock, and the base backoff between them.
 
 ```typescript
 interface SerializableOptions
 ```
 
+**`TimeoutOptions`** — Which timeouts {@link withTimeouts} sets; each a positive integer number of milliseconds.
+
+```typescript
+interface TimeoutOptions
+```
+
 **`ManagedConnection`** — A standalone pooled connection: the raw postgres.js client, its drizzle handle, and a `close()` that ends the pool.
 
 ```typescript
@@ -837,6 +946,10 @@ JSONB query operators — typed helpers for PostgreSQL JSONB containment, key ch
 
 The @> containment operator — tests whether a JSONB column contains the given value.
 
+### `jsonb.merge`
+
+Merges an object into a JSONB column in `.set()`: `coalesce(col, '{}') || value`. Top-level keys overwrite; others are kept.
+
 ### `jsonb.containedBy`
 
 The <@ contained-by operator — tests whether a JSONB column is contained by the given value.
@@ -903,6 +1016,60 @@ type Schema<T = unknown> = z.ZodType<T>
 type Infer<T extends Schema> = z.infer<T>
 ```
 
+**`StringSchema`** — A string validator — what check.string() returns, nameable without importing zod.
+
+```typescript
+interface StringSchema extends z.ZodString
+```
+
+**`NumberSchema`** — A number validator — what check.number() returns.
+
+```typescript
+interface NumberSchema extends z.ZodNumber
+```
+
+**`BooleanSchema`** — A boolean validator — what check.boolean() returns.
+
+```typescript
+interface BooleanSchema extends z.ZodBoolean
+```
+
+**`EnumSchema`** — An enum validator over string literals — what check.enum([...]) returns.
+
+```typescript
+interface EnumSchema<V extends string = string> extends z.ZodEnum<
+```
+
+**`LiteralSchema`** — A literal validator — what check.literal(v) returns.
+
+```typescript
+interface LiteralSchema<V extends string | number | boolean | null = string> extends z.ZodLiteral<V>
+```
+
+**`ArraySchema`** — An array validator — what check.array(item) returns.
+
+```typescript
+interface ArraySchema<Item extends z.core.SomeType = z.core.SomeType> extends z.ZodArray<Item>
+```
+
+**`OptionalSchema`** — An optional validator — what check.optional(inner) returns.
+
+```typescript
+interface OptionalSchema<Inner extends z.core.SomeType = z.core.SomeType> extends z.ZodOptional<Inner>
+```
+
+**`NullableSchema`** — A nullable validator — what check.nullable(inner) returns.
+
+```typescript
+interface NullableSchema<Inner extends z.core.SomeType = z.core.SomeType> extends z.ZodNullable<Inner>
+```
+
+**`ObjectSchema`** — An object validator whose .extend, .pick, .omit and .partial results stay ObjectSchema — what check.object({...}) returns.
+
+```typescript
+type ObjectSchema<S extends Shape = Shape> =
+```
+
 ## temporal — Bitemporal Data
 
 Temporal (bitemporal) data namespace — version history with effective date ranges.
@@ -947,6 +1114,14 @@ Query all versions of temporal records (no date filter).
 
 Close the current version and create a new one with updated data.
 
+### `temporal.setVersion`
+
+Append the next version of an append-only-versions definition: serialised per scope, numbered, never back-dated, audited.
+
+### `temporal.versionAt`
+
+The version in force at a moment: the row with the greatest effectiveFrom at or before it.
+
 ## valve
 
 Valve namespace — typed, directional, gated boundaries between code silos.
@@ -1129,6 +1304,18 @@ Alerts namespace — raise and resolve keyed conditions, grouped, delivered to s
 
 Creates an alerts handle.
 
+### `alerts.http`
+
+Routes for an operations agent: list, get, totals, delivery health, acknowledge, resolve, link; bearer credentials.
+
+### `alerts.clientFaults`
+
+One POST route that records failures reported by browser code as a trace step and an alert; answers 204, no session needed. Send with `reportClientFault` from `pipework/client`.
+
+### `alerts.requestFaults`
+
+An `onInternalError` hook for the HTTP server: raises `request-fault:<METHOD> <route>` for each internal 500.
+
 ### `alerts.webhook`
 
 A sink that POSTs the alert as signed JSON to a URL.
@@ -1161,6 +1348,10 @@ The newest record's `{ seq, hash }` in the tenant's audit hash chain (blueprint
 
 Walks the tenant's audit hash chain and reports the first break (hash-mismatch, prev-mismatch, missing, head-mismatch, anchor-mismatch), or `{ ok: true }`.
 
+### `audit.removeTenant`
+
+Deletes every audit record of one tenant and its hash chain, for the closure of that tenant's account. Irreversible; returns the number of records removed. Other tenants' records and chains are untouched.
+
 ## cache — Caching
 
 In-memory caching namespace — TTL-based with stats, preload, and tenant-aware variants.
@@ -1213,6 +1404,36 @@ Inbound source: SES receipt rule storing raw messages in S3 and notifying a sign
 
 Inbound development source: `.eml` files dropped in a folder, received by `scan()`; refused in production.
 
+## untrustedFetch
+
+Untrusted fetch — fetch one URL a stranger gave without letting them reach the app's private network.
+
+### `untrustedFetch.get`
+
+Fetches `url` with GET and returns `{ ok: true, url, status, contentType, body, bytes }`, or `{ ok: false, reason, message }`
+naming the rule that refused: `scheme`, `address`, `redirects`, `too_large`, `timeout`, `status`, `rejected` or `network`.
+It does not throw for these.
+
+Rules, none of which can be switched off: only `http:` and `https:`; the name is resolved and every address is checked
+(loopback, private, link-local including cloud metadata, CGNAT, unique-local and site-local IPv6, multicast, reserved,
+unspecified, and IPv4-mapped or NAT64 forms of these; literal IP URLs likewise) and the connection goes to a checked
+address; redirects are followed up to `maxRedirects` and each hop is checked as the first, and the app's `headers` go only to the first origin;
+the body is stopped the moment it passes `maxBytes`, whatever Content-Length says; `timeoutMs` covers the whole fetch.
+`accept({ status, contentType, firstBytes })` sees the first 1024 bytes before the body is kept: return false, or a string
+(your own message), to refuse with `rejected`. Messages never contain an address or anything a server sent.
+
+`resolve` and `connect` are for tests: `resolve(hostname)` replaces DNS and `connect(target)` replaces the socket after the
+address check passed, so a test sends a fake public address to a local server. The address check always runs on what `resolve` returns.
+
+The call is the trace step `pipework/fetch:get`; its child `pipework/fetch:outcome` carries host, status, bytes and reason.
+The full URL is recorded only when `urlIsSafeToTrace` is true; otherwise only the host.
+
+```ts
+const got = await untrustedFetch.get(pasted, { maxBytes: 5_000_000, timeoutMs: 10_000, maxRedirects: 3,
+  accept: h => h.firstBytes[0] === 0x25 || 'That does not look like a PDF.' })
+if (!got.ok) return tell(got.message)
+```
+
 ## storage
 
 Storage namespace — tenant-scoped, content-addressed file storage with signed URLs and retention.
@@ -1229,6 +1450,18 @@ S3-compatible backend (AWS S3, MinIO, R2): SigV4 over `fetch`, multipart streami
 
 Local-disk backend for development and tests; refused in production.
 
+## support
+
+Support namespace — tickets from email (and later chat), with replies sent only after an approval.
+
+### `support.create`
+
+Creates the support handle: tickets, messages, notes, links, drafts, `approve`, `receiveEmail`, and the events job.
+
+### `support.templates`
+
+The reply template to spread into `mail.create({ templates })`; it renders the approved draft verbatim.
+
 ## webhook — Inbound & Outbound Webhooks
 
 Webhook namespace — inbound verification, outbound delivery with retries, HMAC signing.
@@ -1319,6 +1552,10 @@ Returns the current Flow or undefined — use for optional context detection.
 
 Creates a Flow for test isolation with optional auth and tenant overrides.
 
+### `flow.actAs`
+
+Runs `fn` as a tenant and user chosen inside a tenantless Flow (sign-up, a public sign-in): RLS, audit and trace under that tenant, on the request's transaction.
+
 ## http — Server
 
 HTTP namespace: `http.file()` builds a file response; the server itself is managed by manifold.start().
@@ -1343,6 +1580,40 @@ interface SecurityConfig
 interface RateLimitConfig
 ```
 
+**`RateLimitWindow`** — One fixed window: at most `max` requests per `windowSeconds`.
+
+```typescript
+interface RateLimitWindow
+```
+
+**`RateLimitClass`**
+
+A named limit class: any of a per-user, per-tenant, per-address and total window, each counted on its own.
+Each key takes one window or an array of windows (distinct `windowSeconds`); a request is counted against
+all of a key's windows and refused if any is over.
+
+```typescript
+interface RateLimitClass
+```
+
+**`RateLimitRefusal`** — What `onRefused` is told about one refused window of one request.
+
+```typescript
+interface RateLimitRefusal
+```
+
+**`RateLimitClassesConfig`**
+
+Named limit classes, checked after auth and counted in Postgres (`pipework_rate_limit_counts`, opted in
+with the blueprint's `rateLimits: {}`), so every server process on the same database shares one count.
+Keys are counted perUser, perTenant, perAddress, total in turn, up to the first key with a window over its max, so one user's
+refused requests don't spend the tenant's budget. The 429's Retry-After is the longest wait of the windows that refused. A route is in `signedIn` (auth required, or optional with
+a user), `public` (no auth, or optional without a user) or the class its fitting names with `.rateLimit(name)`.
+
+```typescript
+interface RateLimitClassesConfig
+```
+
 **`InjectOptions`** — Options for server.inject() — method, url, headers, payload for testing without HTTP.
 
 ```typescript
@@ -1361,6 +1632,12 @@ interface InjectResponse
 interface ServerConfig
 ```
 
+**`InternalErrorFault`** — What `onInternalError` is told about one request that ended in an internal error.
+
+```typescript
+interface InternalErrorFault
+```
+
 **`HandlerResponse`** — Standard handler response shape — statusCode, headers, body.
 
 ```typescript
@@ -1419,7 +1696,7 @@ Generates an OpenAPI 3.1 document from route registrations — schemas derived f
 
 ## trace
 
-Trace namespace — hand the current trace to a process outside Node and record the steps it reports back.
+Trace namespace — hand the current trace to a process outside Node, record the steps it reports back, mark point events, and read a trace tree.
 
 ### `trace.traceparent`
 
@@ -1433,6 +1710,15 @@ W3C `traceparent` for the current trace and open step; `null` outside a traced f
 
 Records steps reported as JSON lines (or objects) by an outside process under the step open now. Synchronous; never throws.
 
+### `trace.event`
+
+Records one zero-length step `external:<name>` under the step open now, with an optional `capture` and `error`. A no-op outside a traced flow; never throws.
+
+### `trace.tree`
+
+Reads every hot trace sharing `rootId` (a request's trace and the jobs it queued) with their steps. Runs on the
+given `db`, so tenant policies apply: only an unrestricted connection (table owner, tests) sees every tenant's rows.
+
 ### Types
 
 **`FlowStepMeta`** — Trace metadata for one documented flow-step: its `path:symbol` graph node id and the per-argument capture projections.
@@ -1453,17 +1739,40 @@ type ExternalStepReport = z.infer<typeof externalStepReportSchema>
 interface ExternalRecordResult
 ```
 
+**`TraceStepNode`** — One step of a trace. `ref` is the flow step's `path:symbol`, or `external:<name>` for a recorded or point-event step.
+
+```typescript
+interface TraceStepNode
+```
+
+**`TraceNode`** — One trace of the tree, with its steps ordered by `seq`.
+
+```typescript
+interface TraceNode
+```
+
+**`TraceTree`** — The traces that share a root id, ordered by when they opened.
+
+```typescript
+interface TraceTree
+```
+
 ## data
 
-### `tap`
+### `StatementTimeoutError`
+
+A statement was cancelled by Postgres for running past the statement timeout a {@link withTimeouts} call set. `cause` is the driver error.
+
+```typescript
+class StatementTimeoutError extends Error constructor(readonly statementTimeoutMs: number, cause: unknown)
+```
+
+### `LockTimeoutError`
 
-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()`.
+A statement gave up waiting for a lock past the lock timeout a {@link withTimeouts} call set. `cause` is the driver error.
 
 ```typescript
-function tap(url: string, options?: ConnectOptions): ManagedConnection
+class LockTimeoutError extends Error constructor(readonly lockTimeoutMs: number, cause: unknown)
 ```
 
 ## request

package/dist/core/config/load.d.ts

@@ -69,6 +69,7 @@ export interface ResolvedDatabase {
     readonly pool: {
         max: number;
         idleTimeout: number;
+        readonly settings?: Readonly<Record<string, string>>;
     };
     readonly rls?: {
         readonly sessionVar: string;

package/dist/core/config/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/core/config/load.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAuB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAK9H,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAEhE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAA;CACpD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kHAAkH;IAClH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,0HAA0H;IAC1H,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAA;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAA;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;IACvB,4LAA4L;IAC5L,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAA;IAC7C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAA;IACzC,SAAS,IAAI,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IAClD,aAAa,IAAI,SAAS,MAAM,EAAE,CAAA;IAClC,mBAAmB,IAAI,MAAM,CAAA;IAC7B,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAA;CACrD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,gHAAgH;IAChH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,qJAAqJ;IACrJ,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9C,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;CACxE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAiBvD"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/core/config/load.ts"],"names":[],"mappings":"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"}

package/dist/core/config/load.js

@@ -18,6 +18,12 @@ export function loadConfig(raw) {
         ?? (config.requireEnvironment === true ? resolveEnvironmentStrict() : resolveEnvironment());
     return buildResolved(config, environment, baseDir);
 }
+function stringifySettings(settings) {
+    const out = {};
+    for (const [k, v] of Object.entries(settings))
+        out[k] = typeof v === 'boolean' ? (v ? 'on' : 'off') : String(v);
+    return out;
+}
 function resolveRelease(def, environment) {
     if (def === undefined)
         return null;
@@ -170,6 +176,7 @@ function resolveDatabase(name, config, url, appUrl, testOwner, baseDir, refuseUr
         pool: {
             max: config.pool?.max ?? 10,
             idleTimeout: config.pool?.idleTimeout ?? 30,
+            ...(config.pool?.settings !== undefined ? { settings: stringifySettings(config.pool.settings) } : {}),
         },
         ...(config.rls !== undefined ? { rls: { sessionVar: config.rls.sessionVar, force: config.rls.force } } : {}),
     };