pipework 0.178.0 → 0.180.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.180.0
+
+- **Added: `pipe.filter.splitPart(a, delimiter, n)` and `pipe.filter.arrayAt(arr, n)`** (#726). `splitPart` is `split_part`; `arrayAt` is one array element by 1-based index. A negative `n` counts from the end in both. For `arrayAt`, an empty array, 0 or an index out of range gives NULL, and its type comes from the column (`uuid[]` gives `SQL<string | null>`).
+- **Added: the rest of the common Postgres text and array functions,** so a package no longer falls back to `pipe.sql` for them:
+  - text: `lower`, `upper`, `trim`, `replace`, `substring`, `reverse`, `lpad`, `rpad`, `regexpReplace`, `regexpMatch` (`~`, or `~*` with `caseInsensitive`) and `stringToArray`;
+  - arrays: `cardinality`, `arrayPosition`, `arraySlice`, `arrayToString`, `arrayAppend` and `arrayRemove`.
+  - Every value a caller passes in is bound as a parameter. Positions and counts must be integers, or the call throws naming the builder.
+
+## 0.179.0
+
+- **Added: split one full run across CI machines with `--shard <i>/<n>`** (#724).
+  - `pipework test --full --shard 2/4` runs part 2 of 4 disjoint parts of the selected test files, using vitest's own split. The parts together run exactly what the unsharded run runs.
+  - A part whose files are all in projects that use no database skips test database setup.
+  - `pipework check --full --shard 2/4` deals modules round-robin to lint and type check, the slow steps. The quick repo-wide checks run in every part, and files outside every module are linted in part 1.
+  - Every machine must get the same scope flags. A value that is not `<i>/<n>` with `1 <= i <= n` is refused, naming `--shard`, and `--shard` cannot be combined with `--reap`.
+
 ## 0.178.0
 
 - **Added: failures that were only logged now leave a row an alert can read** (failure-alert class, part 4 of 4). New table `pipework_faults`, which comes with the `alerts` blueprint key; run `pipework generate` and migrate.

package/REFERENCE.md

@@ -731,6 +731,11 @@ Expression helpers for `.set()`, `.values()` and `.where()` (a string or number
 - `filter.interval(amount, unit)` — `($1::double precision * interval '1 <unit>')`, `amount` bound; a non-finite amount throws.
 - `filter.strpos(a, b)`, `filter.textContains(a, b)`, `filter.startsWith(a, prefix)` — exact-text tests, no `%`/`_`/backslash wildcards (unlike `like`). `a`, `b`, `prefix` take a column, expression or string.
 - `filter.left(a, n)`, `filter.right(a, n)`, `filter.length(a)` — text slices and length.
+- `filter.splitPart(a, delimiter, n)` — `split_part($a, $delimiter, $n)`; negative `n` counts from the end (PG 14+). `filter.lower(a)`, `filter.upper(a)`, `filter.reverse(a)` — `lower`/`upper`/`reverse`.
+- `filter.trim(a, { side?, characters? })` — `trim(both|leading|trailing [$characters] from a)`. `filter.replace(a, from, to)` — `replace`. `filter.substring(a, from, count?)` — `substring(a, from[, count])`. `filter.lpad(a, length, fill?)` / `filter.rpad(...)` — `lpad`/`rpad`.
+- `filter.regexpReplace(a, pattern, replacement, flags?)` — `regexp_replace`; `filter.regexpMatch(a, pattern, { caseInsensitive? })` — `a ~ pattern` (`~*` when case-insensitive); `filter.stringToArray(a, delimiter)` — `string_to_array`. Pattern, replacement, flags and delimiter are always bound.
+- `filter.arrayAt(arr, n)` — `(arr)[n]`, 1-based; negative `n` is `(arr)[cardinality(arr) + n + 1]`; NULL for 0, out of range or `'{}'`. Typed from the column (`uuid[]` gives `SQL<string | null>`); `n` must be an integer or it throws.
+- `filter.cardinality(arr)`, `filter.arrayPosition(col, value)` (`array_position`, NULL when absent), `filter.arraySlice(col, from, to)` (`(col)[from:to]`), `filter.arrayToString(arr, delimiter)`, `filter.arrayAppend(col, value)` and `filter.arrayRemove(col, value)` (for `.set()`). Values are bound and cast to the column's element type.
 - `filter.concat(...parts)` — `(p1 || p2 || ...)`, at least two parts, each a string, column or expression (`scalar(...)` for a subquery). A null part makes the result null; wrap it in `coalesce` if not wanted.
 - `pipe.sql.inList(values, cast?)` — list match for a JS list: `` sql`id ${sql.inList(ids, 'uuid')}` `` renders `= ANY(...)`, so an empty list matches nothing; never build `IN (${sql.join(...)})`, which is a syntax error when the list is empty. `cast` is the element type, default `text`.
 - `filter.arrayReplace(col, from, to)` — `array_replace`, every `from` becomes `to`; `filter.arrayHas(col, value)` — `$value = ANY(col)`. `col` must be an array column; values are cast to its element type.
@@ -2097,6 +2102,8 @@ Generates an OpenAPI 3.1 document from route registrations — schemas derived f
 
 `pipework test <path>` runs only affected modules; when a path is given and no module is affected it prints "Nothing ran" naming the path and exits 1, so a reverted file cannot look green. Add `--all` to run it regardless. Bare `pipework test` with nothing affected still exits 0.
 
+`--shard <i>/<n>` (test and check) splits one run across n machines. `pipework test --full --shard 2/4` runs the second of four disjoint parts of the test files (vitest's `--shard`, so a file selected by two projects counts once per project); the four parts together run exactly what `--full` runs. Before database setup, `test` works out which projects have files in the part and provisions test databases only if one of them uses a database. `pipework check --shard i/n` deals the modules to lint and type check round-robin in sorted order, so the parts are disjoint and together cover every module; the repo-wide steps (doctrine, flow, startup, boundaries, dependencies) run in every part, and root-level lint files run in part 1. Combine it with `--full`, `--fast`, `--module` or `--suite`: every machine must be given the same scope flags. A value that is not `<i>/<n>` with `1 <= i <= n` is refused, naming `--shard`.
+
 ## data
 
 ### `tap`

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/cli/commands/check.d.ts

@@ -1,5 +1,6 @@
 import type { ScopeMode } from '../../workspace/affected.js';
-export declare function check(cwd: string, scope?: ScopeMode): Promise<void>;
+import { type Shard } from './shard.js';
+export declare function check(cwd: string, scope?: ScopeMode, shard?: Shard): Promise<void>;
 /** The startup checks that need no database — what `serve` would refuse before connecting. */
 export declare function runStartupChecks(cwd: string): Promise<boolean>;
 export interface ModuleScope {

package/dist/cli/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check.ts"],"names":[],"mappings":"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"}