okmodel 0.1.1 → 0.2.1

package/README.md

@@ -17,6 +17,7 @@ Version 0.1.1. Apache-2.0.
   - [Find](#find)
   - [Errors](#errors)
   - [Close](#close)
+- [Keys](#keys)
 - [Commands](#commands)
 - [Roadmap](#roadmap)
 - [Size](#size)
@@ -24,19 +25,15 @@ Version 0.1.1. Apache-2.0.
 
 ## Install
 
-Install okmodel and the postgres.js driver.
+Four Postgres drivers. Pick the one the runtime already has. postgres.js is the default, on Node and Bun. node-postgres is the other choice on Node and Bun when `pg` is already installed. Bun.sql is built into Bun and runs only there. PGlite is in-process, on Node and Bun.
 
 ```sh
 bun add okmodel postgres
-```
-
-PGlite is the in-process driver.
-
-```sh
+bun add okmodel pg
 bun add okmodel @electric-sql/pglite
 ```
 
-okmodel has no runtime dependencies. The driver is a peer.
+Bun.sql needs no extra package: `import { connect } from "okmodel/pg/bun"`. okmodel has no runtime dependencies. Each installed driver is an optional peer.
 
 ## Quickstart
 
@@ -66,6 +63,8 @@ export default defineConfig({
 
 `t.identity()` is the primary key. An insert omits the id, and the row that comes back carries it. Identity ids come back as strings by default. `t.identity({ as: "number" })` returns numbers. Push and reviewed migrations are two ways to do the same job: pick one per database.
 
+Ids can also be generated in the application. Import `uuidv4`, `uuidv7`, or `okid` from `okmodel/ids` and pass one to `.default()`, or set `defaults.id` on `schema()` for every id column that does not choose its own. A column choice wins. A literal stays a database default. A generator is not stored in the catalog, so changing it does not create a migration, and an insert that bypasses okmodel has to supply the value. An OKID column is text with collation C, so a sortable id orders the same everywhere. Sortable ids include the time they were created.
+
 Tested on PostgreSQL 15 to 18.
 
 `schema.ts`:
@@ -162,6 +161,10 @@ if (row?.title !== "hello" || row.author?.name !== "Ada") {
 }
 ```
 
+A jsonb filter uses `contains`, and the fragment stays a parameter: `{ meta: contains({ published: true }) }`. `json.set(["published"], true)` writes that path inside `update`. The column builder is `t.json()`; the `json` import is this write namespace.
+
+An array column uses `contains` and `overlaps` the same way. `arr.append("news")` and `arr.remove("news")` add or remove one element inside `update`.
+
 ### Errors
 
 `safe` returns the `OkmError` instead of throwing when the author name is already used.
@@ -200,6 +203,14 @@ if (author.name !== "Lin" || author.id.length === 0) {
 await db.close();
 ```
 
+## Keys
+
+`t.identity()` is a bigint identity primary key. Insert and update omit it. It works on every supported Postgres version. The quickstart uses it.
+
+`t.id()` is a uuid primary key. The default is `uuidv7()`, which needs Postgres 18; on an older server `okm migrate apply` stops with OKM1812 before it runs any statement. `t.id({ default: "uuidv4" })` uses `gen_random_uuid()`, built in from Postgres 13. `t.id({ default: "none" })` takes the id on insert and omits it from update.
+
+`.primaryKey()` on a column is a natural key. Insert supplies it. Update cannot change it. A composite key is the `primaryKey` option on the table, naming the columns in order.
+
 ## Commands
 
 | Command                   | What it does                                                                                                                 |
@@ -218,11 +229,13 @@ await db.close();
 
 ## Roadmap
 
-- [x] 0.1 — Schema, queries, and migrations on PostgreSQL, with postgres.js and PGlite.
-- [ ] 0.2 — Hidden and sensitive fields, validation, traits, tenancy, archive and restore, richer relations, presets, transactions, and operators for JSON, arrays, ranges, and search.
-- [ ] 0.3 — Extensions, domains, functions, triggers, views, roles, and grants.
-- [ ] 0.4 — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
-- [ ] 0.5 — A primary with replicas, read routing, and a reference app.
+Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each release is a milestone.
+
+- [x] [0.1](https://github.com/omqkhafi/okmodel/milestone/1) — Schema, queries, and migrations on PostgreSQL, with postgres.js and PGlite.
+- [ ] [0.2](https://github.com/omqkhafi/okmodel/milestone/2) — Hidden and sensitive fields, validation, traits, tenancy, archive and restore, richer relations, presets, transactions, and operators for JSON, arrays, ranges, and search.
+- [ ] [0.3](https://github.com/omqkhafi/okmodel/milestone/3) — Extensions, domains, functions, triggers, views, roles, and grants.
+- [ ] [0.4](https://github.com/omqkhafi/okmodel/milestone/4) — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
+- [ ] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
 
 `okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
 
@@ -232,10 +245,13 @@ Each limit, with the version that lifts it, is in [known limits](https://github.
 
 Measured on this release.
 
-|                                   | Minified |   Gzip | Cold import |
-| --------------------------------- | -------: | -----: | ----------: |
-| Runtime entry                     |    5,525 |  2,042 |    1.758 ms |
-| App startup (10 tables, one find) |   77,537 | 25,625 |    9.922 ms |
+|                                              | Minified |   Gzip | Cold import |
+| -------------------------------------------- | -------: | -----: | ----------: |
+| Runtime entry                                |    5,288 |  2,026 |    1.991 ms |
+| App startup (10 tables, one find)            |   88,938 | 29,778 |   10.380 ms |
+| App startup, every 0.2 feature in use (full) |  113,705 | 37,506 |   12.068 ms |
+
+The full app has column tenancy, `archivable()`, `timestamps()`, validation rules, `one`, `many` and `manyThrough` relations, presets, and calls `include`, `page`, `aggregate`, `tx` and `batch`. A feature costs bytes only in an app that uses it: the full app is 24,767 minified and 7,728 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated.
 
 The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
 

package/dist/adapters/capabilities.d.ts

@@ -41,6 +41,40 @@ export declare const PGLITE_CAPABILITIES: {
     readonly prepared: "unnamed";
     readonly describe: true;
 };
+/**
+ * node-postgres execution flags.
+ *
+ * Interactive transactions, cursor streaming, listen, and cancel are set
+ * because the conformance suite passes them. Describe is false: `pg` cannot
+ * describe a statement without running it, and that case is skipped.
+ * Parameterized queries use the unnamed extended protocol.
+ */
+export declare const NODE_POSTGRES_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: true;
+    readonly listen: true;
+    readonly cancel: true;
+    readonly prepared: "unnamed";
+    readonly describe: false;
+};
+/**
+ * Bun.sql execution flags.
+ *
+ * Interactive transactions, cursor streaming, and listen pass the conformance
+ * suite. `cancel` is false: `Query.cancel()` does not abort the backend
+ * (Bun 1.4), so the cancel and in-flight timeout cases are skipped.
+ * `describe` is false: Bun.sql has no describe API. RAISE NOTICE is not
+ * surfaced, so the notice case is skipped. `prepare` is off, so a
+ * parameterized query does not leave a named statement.
+ */
+export declare const BUNSQL_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: true;
+    readonly listen: true;
+    readonly cancel: false;
+    readonly prepared: "unnamed";
+    readonly describe: false;
+};
 /**
  * Reads one capability flag.
  *

package/dist/adapters/pg/bunsql-extra.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reserved connections for Bun.sql.
+ *
+ * Loaded on the first reserve, batch, or stream. A read does not use it.
+ */
+import type { DriverConnection } from "../../contracts/driver.js";
+import { type HeldPool } from "./bunsql.js";
+/**
+ * Checks out one connection and clears it on release.
+ *
+ * A connection that is gone is neither reset nor parked: Bun.sql has already
+ * dropped it, and parking it would hand a dead session to the next caller.
+ *
+ * @param held - The pool and its counters
+ * @returns A connection the caller must release
+ */
+export declare function checkout(held: HeldPool): Promise<DriverConnection>;

package/dist/adapters/pg/bunsql.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Bun.sql adapter (`okmodel/pg/bun`).
+ *
+ * Bun's built-in client. There is no package to install. This module is the
+ * only place that imports `bun`. It runs on Bun; another runtime cannot load
+ * that import.
+ *
+ * `idleTimeout` stays 0, which is Bun's default: no idle timer, and a
+ * finished script exits without `close()`. `Query.cancel()` does not abort
+ * the backend, so `cancel` is false. Server notices are not surfaced.
+ */
+import { SQL, type ReservedSQL } from "bun";
+import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
+import { noticeBuffer, type WireQuery } from "./session.js";
+export { BUNSQL_CAPABILITIES as capabilities, hasCapability, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** TLS values Bun.sql accepts that this adapter forwards. */
+export type BunSqlTls = boolean | "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+/** Options for {@link open}. */
+export type BunSqlConfig = DriverPoolConfig & {
+    /** Connection URL for this endpoint. */
+    readonly url: string;
+    /**
+     * Named prepared statements, or the unnamed protocol.
+     *
+     * Unnamed is the default (`prepare: false`). `prepared: "named"` is not
+     * for transaction-mode poolers.
+     */
+    readonly prepared?: "named" | "unnamed";
+    /** Session search path for every connection in the pool. */
+    readonly searchPath?: string;
+    /** TLS mode passed to Bun.sql. */
+    readonly ssl?: BunSqlTls;
+};
+/** What a checkout needs from the pool that opened it. */
+export type HeldPool = {
+    readonly sql: SQL;
+    readonly parked: ReservedSQL[];
+    readonly acquireMs: number | undefined;
+    readonly counters: Counters;
+    readonly notices: ReturnType<typeof noticeBuffer>;
+    readonly isClosed: () => boolean;
+};
+/** Pool occupancy. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/**
+ * Opens a Bun.sql pool for one endpoint.
+ *
+ * @param config - URL, pool size, and acquire timeout
+ * @returns The pool
+ */
+export declare function open(config: BunSqlConfig): DriverPool;
+export declare function send(sql: SQL, text: string, params: readonly WireValue[] | undefined): WireQuery;
+export declare function reserve(sql: SQL, acquireMs: number | undefined, counters: Counters): Promise<ReservedSQL>;
+export declare function park(parked: ReservedSQL[], reserved: ReservedSQL): Promise<void>;

package/dist/adapters/pg/call.d.ts

@@ -28,24 +28,14 @@ export declare function needsWatch(options: ExecuteOptions | undefined): boolean
 /**
  * Next transaction depth after one statement.
  *
- * Only a whole command matches, so `ROLLBACK TO SAVEPOINT` stays inside the
- * transaction. Kept here so a read does not load the batch runner.
+ * `BEGIN` may carry modes (`begin isolation level serializable`). `ROLLBACK TO
+ * SAVEPOINT` stays inside the transaction. Kept here so a read does not load the batch runner.
  *
  * @param depth - Depth before the statement
  * @param text - Statement text
  * @returns Depth after a successful statement
  */
 export declare function nextTransactionDepth(depth: number, text: string): number;
-/**
- * Opens a watch for one call.
- *
- * The caller has already rejected a pre-aborted signal and a non-positive
- * timeout.
- *
- * @param options - Options that include a signal or a timeout
- * @returns The watch. The caller must {@link Watch.finish} it
- */
-export declare function openWatch(options: ExecuteOptions): Watch;
 /**
  * Runs `fn` with a watch when the caller set a signal or a timeout.
  *

package/dist/adapters/pg/nodepostgres-extra.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reserved connections for node-postgres.
+ *
+ * Loaded on the first reserve, batch, or stream. A read does not use it.
+ */
+import type { DriverConnection } from "../../contracts/driver.js";
+import { type HeldPool } from "./nodepostgres.js";
+/**
+ * Checks out one client and clears it on release.
+ *
+ * A client whose connection is gone is destroyed on release, and nothing more is
+ * sent to it. A checked-out client has no pool error listener, so one is set here:
+ * without it a dropped socket is an uncaught `error` event.
+ *
+ * @param held - The pool and its counters
+ * @returns A connection the caller must release
+ */
+export declare function checkout(held: HeldPool): Promise<DriverConnection>;

package/dist/adapters/pg/nodepostgres.d.ts

@@ -0,0 +1,57 @@
+/**
+ * node-postgres adapter (`okmodel/pg/pg`).
+ *
+ * One pool per `open` call. `pg` is an optional peer of this entry.
+ * Idle clients are unref'd (`allowExitOnIdle`) and are not closed on a timer
+ * (`idleTimeoutMillis: 0`), so a finished script exits and a live process
+ * keeps its connection. Cancel sends a Postgres CancelRequest on a side
+ * socket. That socket is unref'd.
+ */
+import pg, { type PoolClient, type QueryConfig, type QueryResult } from "pg";
+import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
+import { noticeBuffer, type WireQuery } from "./session.js";
+export { hasCapability, NODE_POSTGRES_CAPABILITIES as capabilities, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** Options for {@link open}. */
+export type NodePostgresConfig = DriverPoolConfig & {
+    /** Connection URL for this endpoint. */
+    readonly url: string;
+    /**
+     * Named prepared statements, or the unnamed protocol.
+     *
+     * Unnamed is the default. It stays valid behind a pooler in transaction mode.
+     * `prepared: "named"` is not for transaction-mode poolers.
+     */
+    readonly prepared?: "named" | "unnamed";
+    /** Session search path for every connection in the pool. */
+    readonly searchPath?: string;
+    /** TLS mode passed to node-postgres. */
+    readonly ssl?: boolean | "require" | "allow" | "prefer" | "verify-full" | object;
+};
+/** What a checkout needs from the pool that opened it. */
+export type HeldPool = {
+    readonly pool: InstanceType<typeof pg.Pool>;
+    readonly acquireMs: number | undefined;
+    readonly counters: Counters;
+    readonly notices: ReturnType<typeof noticeBuffer>;
+    readonly named: boolean;
+    readonly isClosed: () => boolean;
+};
+/** Pool occupancy. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/**
+ * Opens a node-postgres pool for one endpoint.
+ *
+ * @param config - URL, pool size, and acquire timeout
+ * @returns The pool
+ */
+export declare function open(config: NodePostgresConfig): DriverPool;
+export declare function send(runner: {
+    query(config: QueryConfig): Promise<QueryResult>;
+}, text: string, params: readonly WireValue[] | undefined, named: boolean, client: PoolClient | undefined): WireQuery;
+export declare function connectClient(pool: InstanceType<typeof pg.Pool>, acquireMs: number | undefined, counters: Counters): Promise<PoolClient>;

package/dist/adapters/pg/postgres-extra.d.ts

@@ -4,7 +4,8 @@
  * Loaded on the first reserve, batch, describe, or stream.
  */
 import type { Sql } from "postgres";
-import type { DescribeResult, DriverConnection, WireValue } from "../../contracts/driver.js";
+import type { DescribeResult, DriverConnection, ExecuteResult, WireValue } from "../../contracts/driver.js";
+import { type Watch } from "./call.js";
 import { type Canceller, type Counters, type NoticeBuffer } from "./postgresjs.js";
 /** State `open` shares with a checkout. */
 export type HeldPool = {
@@ -41,3 +42,51 @@ export declare function describe(sql: Sql, text: string, params?: readonly WireV
  * @returns Chunks of wire rows
  */
 export declare function stream(sql: Sql, text: string, params?: readonly WireValue[]): AsyncIterable<readonly (readonly WireValue[])[]>;
+/** Refcount a checkout or a listener borrows from the pool. */
+type Gate = {
+    enter(): void;
+    leave(): void;
+};
+/**
+ * Keeps sockets referenced until `release` finishes.
+ *
+ * The caller has already entered `gate`. A second `release` does not change
+ * the count. Checkout failure leaves the gate.
+ *
+ * @param gate - Refcount already entered for this checkout
+ * @param checkout - Reserves the connection
+ * @returns The connection, with release counted once
+ */
+export declare function holdCheckout<T extends {
+    release(): Promise<void>;
+}>(gate: Gate, checkout: () => Promise<T>): Promise<T>;
+/**
+ * Keeps sockets referenced for as long as the listener is active.
+ *
+ * The caller has already entered `gate`.
+ *
+ * @param gate - Listener refcount already entered
+ * @param start - Subscribes and returns the stop function
+ * @returns A stop function that can be called again
+ */
+export declare function holdListener(gate: Gate, start: () => Promise<() => Promise<void>>): Promise<() => Promise<void>>;
+/**
+ * Finishes a query that can be aborted by a signal or a timeout.
+ *
+ * The caller has already tracked `pending` and attached `onAbort`.
+ *
+ * @param pending - The in-flight statement
+ * @param watch - Abort signal and the reason it fired
+ * @param onAbort - Listener the caller attached
+ * @param ctx - Notice slice and the session counters the plain path also uses
+ * @returns The wire result, or a rejected driver error
+ */
+export declare function watchQuery(pending: Canceller & Promise<unknown>, watch: Watch, onAbort: () => void, ctx: {
+    readonly start: number;
+    readonly text: string;
+    readonly notices: NoticeBuffer;
+    leave(): void;
+    note(text: string): void;
+    untrack(pending: Canceller): void;
+}): Promise<ExecuteResult>;
+export {};

package/dist/adapters/pg/postgresjs.d.ts

@@ -88,8 +88,4 @@ export declare class PgSession implements BatchSession {
     private note;
     private enter;
     private leave;
-    private track;
-    private untrack;
-    private watched;
-    private finishWatched;
 }

package/dist/adapters/pg/session.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared interactive session for drivers that speak wire text.
+ *
+ * The postgres.js adapter keeps its own session. node-postgres and Bun.sql
+ * share this one: transaction depth, notices, and a watched cancel.
+ */
+import type { ExecuteResult, Notice, WireValue } from "../../contracts/driver.js";
+import type { BatchSession } from "./batch.js";
+import type { Watch } from "./call.js";
+/** A query the session can abort when the driver supports it. */
+export type WireQuery = Promise<unknown> & {
+    cancel?(): void;
+};
+/** Sends one statement and returns the driver's own result. */
+export type WireSender = (text: string, params: readonly WireValue[] | undefined) => WireQuery;
+/** Notice slice shared by a pool. */
+export type NoticeBuffer = {
+    start(): number;
+    since(start: number): readonly Notice[];
+    push(notice: {
+        readonly severity?: string | undefined;
+        readonly message?: string | undefined;
+        readonly code?: string | undefined;
+    }): void;
+};
+/**
+ * Quotes one identifier.
+ *
+ * @param name - Channel or cursor name
+ * @returns A double-quoted identifier
+ */
+export declare function quoteIdent(name: string): string;
+/**
+ * An empty notice buffer the pool fills as the server sends notices.
+ *
+ * @returns The buffer
+ */
+export declare function noticeBuffer(): NoticeBuffer;
+/**
+ * One connection's statement runner.
+ *
+ * `send` is the driver. This class owns depth, notices, and cancel tracking.
+ */
+export declare class WireSession implements BatchSession {
+    readonly canCancel: boolean;
+    private transactionDepth;
+    private readonly local;
+    private readonly send;
+    private readonly notices;
+    private readonly isClosed;
+    private readonly onEnter;
+    private readonly onLeave;
+    private readonly shared;
+    /**
+     * @param send - Runs one statement on this connection
+     * @param notices - Pool notice buffer
+     * @param isClosed - Pool closed flag
+     * @param canCancel - The driver aborts an in-flight statement
+     * @param onEnter - Marks one statement in flight
+     * @param onLeave - Marks that statement finished
+     * @param shared - Pool-wide in-flight set, when this connection is reserved
+     */
+    constructor(send: WireSender, notices: NoticeBuffer, isClosed: () => boolean, canCancel: boolean, onEnter: () => void, onLeave: () => void, shared?: Set<WireQuery>);
+    /** @inheritdoc */
+    query(text: string, params: readonly WireValue[] | undefined, watch: Watch | undefined): Promise<ExecuteResult>;
+    /** @inheritdoc */
+    inTransaction(): boolean;
+    /** @inheritdoc */
+    abandon(): void;
+    /**
+     * Open transaction depth.
+     *
+     * @returns The depth. Zero means no transaction
+     */
+    depth(): number;
+    /** Aborts in-flight statements on this connection. */
+    cancel(): void;
+    private note;
+    private track;
+    private untrack;
+    private watched;
+    private finishWatched;
+}
+/**
+ * Yields cursor chunks from one connection that is already checked out.
+ *
+ * The cursor is session-local. `ROLLBACK` in the end drops it.
+ *
+ * @param run - Executes on the checked-out connection
+ * @param text - Query to stream
+ * @param params - Wire parameters
+ * @returns Chunks of wire rows
+ */
+export declare function cursorStream(run: (text: string, params?: readonly WireValue[]) => Promise<ExecuteResult>, text: string, params: readonly WireValue[] | undefined): AsyncIterable<readonly (readonly WireValue[])[]>;

package/dist/adapters/pg/watch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Deadline and abort signal for one call.
+ *
+ * Loaded the first time a call passes `signal` or `timeout`. A plain execute
+ * does not load it.
+ */
+import type { ExecuteOptions } from "../../contracts/driver.js";
+import type { Watch } from "./call.js";
+/**
+ * Opens a watch for one call.
+ *
+ * The caller has already rejected a pre-aborted signal and a non-positive
+ * timeout.
+ *
+ * @param options - Options that include a signal or a timeout
+ * @returns The watch. The caller must {@link Watch.finish} it
+ */
+export declare function openWatch(options: ExecuteOptions): Watch;

package/dist/contracts/catalog/object.d.ts

@@ -25,6 +25,7 @@ export type ColumnInput = CommonInput & {
     readonly dataType: string;
     readonly nullable: boolean;
     readonly defaultExpression?: string;
+    readonly collation?: string;
     readonly identity?: {
         readonly always: boolean;
     };

package/dist/contracts/catalog/types.d.ts

@@ -132,16 +132,16 @@ export type ExtensionIdentity = {
 };
 /** Stable identity. The variant depends on the kind. */
 export type ObjectIdentity = NamespaceIdentity | AnchoredIdentity | FunctionIdentity | GrantIdentity | DefaultPrivilegeIdentity | RoleIdentity | ExtensionIdentity;
-/** Where an object came from. */
+/**
+ * Where an object, a query, or a rule came from.
+ *
+ * `source` is the authoring location (`schema.ts:12`). It is recorded when
+ * the object is defined and is not part of the catalog hash.
+ */
 export type Provenance = {
-    readonly origin: "file";
-    readonly name: string;
-} | {
-    readonly origin: "trait";
-    readonly name: string;
-} | {
-    readonly origin: "extension";
+    readonly origin: "file" | "trait" | "extension";
     readonly name: string;
+    readonly source?: string;
 };
 /**
  * An edge to another object.
@@ -179,6 +179,13 @@ export type ColumnDefinition = {
         readonly stored: boolean;
         readonly expression: string;
     };
+    /**
+     * Collation name, such as `C`.
+     *
+     * Absent when the column uses the type's default collation. A client
+     * generator is not stored here.
+     */
+    readonly collation?: string;
 };
 /**
  * Index definition.

package/dist/contracts/connection.d.ts

@@ -31,3 +31,16 @@ export declare function isConnectionErrno(code: string): boolean;
  * @returns `true` when no session remains
  */
 export declare function isConnectionFailure(error: unknown): boolean;
+/**
+ * Reports whether the connection is gone after `error`, or the outcome of a
+ * statement on it is unknown (`outcome_unknown`).
+ *
+ * It reads what {@link isConnectionFailure} reads, plus the messages node-postgres
+ * ("Connection terminated unexpectedly") and Bun.sql (`ERR_POSTGRES_CONNECTION_CLOSED`)
+ * give, and the error's `cause`. Nothing more should be sent to such a connection:
+ * not a rollback, not a reset. Loaded with the code that reserves a connection.
+ *
+ * @param error - Caught value
+ * @returns `true` when the session cannot be used again
+ */
+export declare function isConnectionLost(error: unknown): boolean;

package/dist/contracts/driver.d.ts

@@ -154,10 +154,23 @@ export type DriverPoolConfig = {
     /** Connections in the pool. PGlite is always one. */
     readonly max?: number;
     /**
-     * Wait for a connection up to `acquire` milliseconds, then fail with
-     * OKM1846. Omitted means wait without that deadline.
+     * Ceilings in milliseconds. An adapter reads `acquire`: it waits for a
+     * connection up to that long, then fails with OKM1846. Omitted means wait
+     * without a deadline. The other keys belong to the runtime.
      */
-    readonly timeouts?: {
-        readonly acquire?: number;
-    };
+    readonly timeouts?: DriverTimeouts;
+};
+/**
+ * Ceilings from `connect({ timeouts })`, in milliseconds (spec §15).
+ *
+ * `acquire` bounds the wait for a connection (OKM1846). `statement` is the
+ * default `timeout` of a call that sets none. `transaction` bounds a whole
+ * `tx()`. `idleInTransaction` bounds the time a `tx()` waits between
+ * statements. Every one but `acquire` fails as kind `timeout`.
+ */
+export type DriverTimeouts = {
+    readonly acquire?: number;
+    readonly statement?: number;
+    readonly transaction?: number;
+    readonly idleInTransaction?: number;
 };

package/dist/contracts/error.d.ts

@@ -31,7 +31,7 @@ export type ColumnCode = (typeof COLUMN_CODES)[number];
  * These are spec §21 codes. They are a type only, so the runtime entry does
  * not gain a second registry.
  */
-export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1190" | "OKM1801" | "OKM1802" | "OKM1843";
+export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
 /** Kinds from spec §14, in category order. */
 export declare const ERROR_KINDS: readonly ["invalid", "not_null", "check", "foreign_key", "unique", "exclusion", "conflict", "not_found", "not_unique", "forbidden", "serialization", "deadlock", "lock_timeout", "timeout", "cancelled", "unavailable", "schema_drift", "driver", "read_only", "outcome_unknown"];
 /** One spec §14 kind. */
@@ -51,6 +51,16 @@ export type ErrorFix = {
     /** Accepted name to use instead, when one is close. */
     readonly suggestion?: string;
 };
+/**
+ * One failed validation check.
+ *
+ * `message` is a key, never prose and never a row value. `path` walks the
+ * value: a field name, or a row index then a field name.
+ */
+export type ValidationIssue = {
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+};
 /** Column name to constraint reason. Row values are not included. */
 export type ErrorFields = Readonly<Record<string, string>>;
 /** Body of {@link OkmError.toHttp}. */
@@ -80,6 +90,8 @@ export type ErrorLog = {
     readonly batchIndex: number | null;
     readonly fix: ErrorFix;
     readonly fields: ErrorFields;
+    /** Validation checks, when the failure is OKM1200. */
+    readonly issues?: readonly ValidationIssue[];
     readonly table?: string;
     readonly columns?: readonly string[];
     readonly constraint?: string;
@@ -105,6 +117,8 @@ export type OkmErrorOptions = {
      */
     readonly includeValues?: boolean;
     readonly values?: Readonly<Record<string, string>>;
+    /** Checks from a failed validation. Omitted on every other error. */
+    readonly issues?: readonly ValidationIssue[];
     /**
      * Category overrides from `connect({ errors })`.
      *
@@ -164,6 +178,8 @@ export declare class OkmError extends Error {
     readonly batchIndex: number | null;
     /** Constraint reason used by {@link fields}. */
     readonly fieldReason: string;
+    /** Validation checks. Absent when this error is not a failed check. */
+    readonly issues?: readonly ValidationIssue[];
     /**
      * Same text as `message`.
      *