okmodel 0.1.0 → 0.2.1

package/dist/runtime/types.d.ts

@@ -4,11 +4,14 @@
  * Row shapes are the schema's `~row`. Operators are the tagged helpers.
  * A plain object is not a where value when the column type is an object.
  */
+import type { DriverTimeouts, Notice } from "../contracts/driver.js";
 import type { SafeResult } from "../contracts/error.js";
 import type { QuerySchema } from "../dialects/pg/model.js";
 import type { Inc } from "../dialects/pg/ops/inc.js";
-import type { Between, Compare, Eq, InList, Not, NotIn, Or, Pattern, RawPattern, RelationFilter } from "../dialects/pg/operators.js";
+import type { ArrAppend, ArrRemove, JsonSet, Or, RelationFilter } from "../dialects/pg/operators.js";
+import type { FieldWhere, IsJsonObject } from "../dialects/pg/where.js";
 import type { AppliedRule, ReadOp } from "./plan.js";
+export type { FieldWhere, WhereValue } from "../dialects/pg/where.js";
 /** One row of a table in `S`. */
 export type RowOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~byName"][K] extends {
     readonly "~row": infer R;
@@ -17,13 +20,8 @@ export type RowOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~byN
 export type RelationsOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~byName"][K] extends {
     readonly "~relations": infer R;
 } ? R : Record<string, never>;
-type IsObject<V> = V extends object ? V extends readonly unknown[] ? false : null extends V ? false : true : false;
-/** A where operand. Object columns take `eq`, not a bare object. */
-export type WhereValue<V> = (IsObject<V> extends true ? never : V) | null | Eq<V> | Compare<"lt", V> | Compare<"lte", V> | Compare<"gt", V> | Compare<"gte", V> | Between<V> | Pattern<"startsWith"> | Pattern<"contains"> | Pattern<"endsWith"> | RawPattern<"like"> | RawPattern<"ilike"> | InList<V> | NotIn<V> | Not<V | null | Pattern<"startsWith"> | Pattern<"contains"> | Pattern<"endsWith"> | InList<V>>;
-/** Field filters. Relation filters are one level, so the type does not cycle. */
-export type FieldWhere<Row> = {
-    readonly [K in keyof Row]?: WhereValue<Row[K]> | undefined;
-};
+/** Array and JSON writes the column value type can accept. */
+type WriteOp<V> = [unknown] extends [V] ? JsonSet<unknown> | ArrAppend<unknown> | ArrRemove<unknown> : (V extends readonly (infer E)[] ? ArrAppend<E> | ArrRemove<E> : never) | (IsJsonObject<V> extends true ? JsonSet<unknown> : never);
 /** `has`, `none`, and `every` against the related row. */
 export type RelFilter<S extends QuerySchema, Rel> = Rel extends {
     readonly table: infer T extends string;
@@ -95,19 +93,36 @@ export type ResultRow<S extends QuerySchema, K extends keyof S["~byName"], O> =
 } ? Sel : undefined> & IncludeRows<S, K, O extends {
     readonly include: infer Inc;
 } ? Inc : undefined>>;
+/** Per-call cancellation and deadline (spec §15). */
+export type CallOptions = {
+    /** Aborts the call. The statement is cancelled where the driver can, and the call fails as `cancelled`. */
+    readonly signal?: AbortSignal;
+    /** Milliseconds. The call fails as `timeout` when it runs longer. */
+    readonly timeout?: number;
+};
 /** Options shared by reads. */
-export type ReadOptions<S extends QuerySchema, K extends keyof S["~byName"]> = {
+export type ReadOptions<S extends QuerySchema, K extends keyof S["~byName"]> = CallOptions & {
     readonly where?: WhereOf<S, K>;
     readonly select?: readonly (keyof RowOf<S, K> & string)[];
     readonly orderBy?: OrderBy<RowOf<S, K>>;
     readonly include?: IncludeOf<S, K>;
 };
+/**
+ * Row locks on `find`. They exist inside `tx()` only (OKM1830 outside one).
+ *
+ * `wait` says what happens when a row is locked by another transaction: `nowait`
+ * fails at once (kind `lock_timeout`) and `skip` leaves that row out.
+ */
+export type LockOptions = {
+    readonly lock?: "update" | "share";
+    readonly wait?: "nowait" | "skip";
+};
 /** `find` options. `limit` is required unless the caller uses `.all(reason)`. */
 export type FindOptions<S extends QuerySchema, K extends keyof S["~byName"]> = ReadOptions<S, K> & {
     readonly limit?: number;
 };
 /** A query handle. Await it, or inspect it before it runs. */
-export type Read<T> = Promise<T> & {
+export type Query<T> = Promise<T> & {
     /** Logical intent, rules, plan, SQL, parameters, and the routing decision. */
     inspect(): Inspection | Promise<Inspection>;
     /** Statement text and parameters. */
@@ -120,6 +135,9 @@ export type Read<T> = Promise<T> & {
     }>;
     /** `{ ok, value }` or `{ ok, error }`. */
     safe(): Promise<SafeResult<T>>;
+};
+/** The handle `find`, `one`, `count`, and `exists` return. */
+export type Read<T> = Query<T> & {
     /** Allows `find` or a to-many include without `limit`. */
     all(reason: string): Read<T>;
     /** Turns a null `one()` into `not_found`. */
@@ -127,6 +145,74 @@ export type Read<T> = Promise<T> & {
     /** Streams rows when the driver has `stream`. Otherwise OKM1111. */
     stream(): AsyncIterable<T extends readonly (infer R)[] ? R : T>;
 };
+/** One page: the rows, and the cursor for the next page. `next` is `null` on the last page. */
+export type Page<Row> = {
+    readonly items: readonly Row[];
+    readonly next: string | null;
+};
+/** `page` options. `after` is the `next` of the page before. */
+export type PageOptions<S extends QuerySchema, K extends keyof S["~byName"]> = ReadOptions<S, K> & {
+    /** Rows in the page. At least 1. */
+    readonly limit: number;
+    /** The `next` of the previous page, made for the same `orderBy`. */
+    readonly after?: string | null;
+};
+/**
+ * Fields `sum` and `avg` take: those typed `number` or `string`.
+ *
+ * A `numeric` column is a string by default. The types cannot tell it from a
+ * `text` column, so `sum` over `text` is refused when the call runs (OKM1124).
+ */
+type NumericKeys<Row> = {
+    readonly [F in keyof Row]-?: [NonNullable<Row[F]>] extends [number | string] ? F : never;
+}[keyof Row] & string;
+/** `aggregate` options. A hidden field is refused at runtime. */
+export type AggregateOptions<S extends QuerySchema, K extends keyof S["~byName"]> = CallOptions & {
+    readonly where?: WhereOf<S, K>;
+    /** One result row per distinct combination. Needs `limit`, or `.all(reason)`. */
+    readonly groupBy?: readonly (keyof RowOf<S, K> & string)[];
+    /** Adds `count`, the number of rows in the group. */
+    readonly count?: true;
+    readonly sum?: readonly NumericKeys<RowOf<S, K>>[];
+    readonly avg?: readonly NumericKeys<RowOf<S, K>>[];
+    readonly min?: readonly (keyof RowOf<S, K> & string)[];
+    readonly max?: readonly (keyof RowOf<S, K> & string)[];
+    /** Orders the groups. Only `groupBy` fields. Without it, groups come in `groupBy` order. */
+    readonly orderBy?: OrderBy<RowOf<S, K>>;
+    readonly limit?: number;
+};
+/** A group: its fields, and the aggregates the call named. */
+export type AggregateRow<Row, O> = Show<(O extends {
+    readonly groupBy: readonly (infer G)[];
+} ? Pick<Row, G & keyof Row> : unknown) & (O extends {
+    readonly count: true;
+} ? {
+    readonly count: number;
+} : unknown) & (O extends {
+    readonly sum: readonly (infer F)[];
+} ? {
+    readonly sum: {
+        readonly [P in F & keyof Row]: NonNullable<Row[P]> | null;
+    };
+} : unknown) & (O extends {
+    readonly avg: readonly (infer F)[];
+} ? {
+    readonly avg: {
+        readonly [P in F & keyof Row]: NonNullable<Row[P]> | null;
+    };
+} : unknown) & (O extends {
+    readonly min: readonly (infer F)[];
+} ? {
+    readonly min: {
+        readonly [P in F & keyof Row]: NonNullable<Row[P]> | null;
+    };
+} : unknown) & (O extends {
+    readonly max: readonly (infer F)[];
+} ? {
+    readonly max: {
+        readonly [P in F & keyof Row]: NonNullable<Row[P]> | null;
+    };
+} : unknown)>;
 /** What {@link Read.inspect} returns. */
 export type Inspection = {
     readonly intent: {
@@ -200,7 +286,7 @@ export type Router = {
  *
  * @typeParam T - Insert shape
  */
-type RequiredInsert<T> = {
+export type RequiredInsert<T> = {
     readonly [K in keyof T as undefined extends T[K] ? never : K]: T[K];
 };
 /**
@@ -208,7 +294,7 @@ type RequiredInsert<T> = {
  *
  * @typeParam T - Insert shape
  */
-type OptionalInsert<T> = {
+export type OptionalInsert<T> = {
     readonly [K in keyof T as undefined extends T[K] ? K : never]?: T[K];
 };
 /** Insert shape of one table. */
@@ -219,9 +305,9 @@ export type InsertOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~
 export type UpdateOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~byName"][K] extends {
     readonly "~update": infer U;
 } ? U : never;
-/** `set` values. `undefined` leaves the field unchanged. `inc` adds to it. */
+/** `set` values. `undefined` leaves the field unchanged. `inc` adds to it. `set` and `arr` write json and arrays. */
 export type UpdateSet<S extends QuerySchema, K extends keyof S["~byName"]> = {
-    readonly [F in keyof UpdateOf<S, K>]?: UpdateOf<S, K>[F] | Inc<NonNullable<UpdateOf<S, K>[F]>>;
+    readonly [F in keyof UpdateOf<S, K>]?: UpdateOf<S, K>[F] | Inc<NonNullable<UpdateOf<S, K>[F]>> | WriteOp<NonNullable<UpdateOf<S, K>[F]>>;
 };
 /** Conflict handling on `insert` (spec §11). */
 export type OnConflict<S extends QuerySchema, K extends keyof S["~byName"]> = "error" | "ignore" | {
@@ -235,16 +321,24 @@ export type OnConflict<S extends QuerySchema, K extends keyof S["~byName"]> = "e
 export type InsertOptions<S extends QuerySchema, K extends keyof S["~byName"]> = {
     readonly onConflict?: OnConflict<S, K>;
     readonly returning?: readonly (keyof RowOf<S, K> & string)[];
+    /** Guarded fields this call may set. */
+    readonly allow?: readonly (keyof RowOf<S, K> & string)[];
     readonly expect?: number;
     readonly signal?: AbortSignal;
     readonly timeout?: number;
+    /** `false` skips validation for this call. Codecs still run. */
+    readonly validate?: boolean;
 };
 /** Options for `update` and `delete`. */
 export type WriteOptions<S extends QuerySchema, K extends keyof S["~byName"]> = {
     readonly returning?: readonly (keyof RowOf<S, K> & string)[];
+    /** Guarded fields this call may set. `delete` ignores it. */
+    readonly allow?: readonly (keyof RowOf<S, K> & string)[];
     readonly expect?: number;
     readonly signal?: AbortSignal;
     readonly timeout?: number;
+    /** `false` skips validation for this call. `delete` ignores it. */
+    readonly validate?: boolean;
 };
 /** `{ count }` from an update or delete without `returning`. */
 export type WriteCount = {
@@ -266,6 +360,17 @@ export type Write<T> = Promise<T> & {
     /** Allows `update` or `delete` without `where`. */
     all(reason: string): Write<T>;
 };
+/** `set` plus guarded fields named in `{ allow }`. */
+type AllowedSet<S extends QuerySchema, K extends keyof S["~byName"], Allow extends readonly (keyof RowOf<S, K> & string)[]> = UpdateSet<S, K> & Partial<Pick<RowOf<S, K>, Allow[number]>>;
+/** One update, or a per-row list, when `{ allow }` opens guarded fields. */
+type AllowedUpdate<S extends QuerySchema, K extends keyof S["~byName"], Allow extends readonly (keyof RowOf<S, K> & string)[]> = {
+    readonly where?: WhereOf<S, K>;
+    readonly set: AllowedSet<S, K, Allow>;
+} | readonly {
+    readonly id?: unknown;
+    readonly where?: WhereOf<S, K>;
+    readonly set: AllowedSet<S, K, Allow>;
+}[];
 /** One update, or a per-row list in one statement. */
 export type UpdateTarget<S extends QuerySchema, K extends keyof S["~byName"]> = {
     readonly where?: WhereOf<S, K>;
@@ -275,38 +380,230 @@ export type UpdateTarget<S extends QuerySchema, K extends keyof S["~byName"]> =
     readonly where?: WhereOf<S, K>;
     readonly set: UpdateSet<S, K>;
 }[];
+/** `{ count, archiveId }` from one `archive()` call. */
+export type ArchiveCount = {
+    readonly count: number;
+    readonly archiveId: string;
+};
+/** `archive`, `restore`, and the visibility modifiers. Present only on archivable tables. */
+type ArchiveOps<S extends QuerySchema, K extends keyof S["~byName"] & string, L> = {
+    /**
+     * Archives the active rows that match.
+     *
+     * One new `archiveId` is shared by the row and its cascaded children.
+     * `expect` matches {@link TableApi.update}.
+     */
+    archive(target: {
+        readonly where?: WhereOf<S, K>;
+    }, options?: WriteOptions<S, K>): Write<ArchiveCount>;
+    /**
+     * Restores archived rows.
+     *
+     * `where` restores those rows and the children that carry their `archiveId`.
+     * `archiveId` restores that whole operation. An archived parent fails.
+     */
+    restore(target: {
+        readonly where?: WhereOf<S, K>;
+    } | {
+        readonly archiveId: string;
+    }, options?: WriteOptions<S, K>): Write<WriteCount>;
+    /** Reads, updates, and deletes include archived rows. */
+    withArchived(): TableApi<S, K, L>;
+    /** Reads, updates, and deletes target only archived rows. */
+    onlyArchived(): TableApi<S, K, L>;
+};
+/**
+ * Methods an opt-in feature adds to a table handle.
+ *
+ * The interface is empty here, so an application that imports no feature
+ * pays one empty instantiation per table. A feature's entry point merges its
+ * members in with a module augmentation, and its types appear only when that
+ * entry point is part of the program.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam K - Table name
+ */
+export interface TableExtras<S extends QuerySchema, K extends keyof S["~byName"] & string> {
+}
 /** Methods on one table. */
-export type TableApi<S extends QuerySchema, K extends keyof S["~byName"] & string> = {
-    find<const O extends FindOptions<S, K> & {
+export type TableApi<S extends QuerySchema, K extends keyof S["~byName"] & string, L = unknown> = {
+    find<const O extends FindOptions<S, K> & L & {
         readonly limit: number;
     }>(options: O): Read<readonly ResultRow<S, K, O>[]>;
-    find<const O extends FindOptions<S, K>>(options: O): {
+    find<const O extends FindOptions<S, K> & L>(options: O): {
         all(reason: string): Read<readonly ResultRow<S, K, O>[]>;
     };
     one<const O extends ReadOptions<S, K>>(options?: O): Read<ResultRow<S, K, O> | null>;
-    count(options?: {
+    /**
+     * One page of rows and the cursor for the next.
+     *
+     * Keyset on `orderBy` plus the primary key, so a page is stable while rows
+     * are inserted. Pass `next` back as `after` with the same `orderBy`.
+     */
+    page<const O extends PageOptions<S, K>>(options: O): Query<Page<ResultRow<S, K, O>>>;
+    /**
+     * Counts, sums, averages, and finds extremes, per group.
+     *
+     * The tenant and active-set rules apply as in `find`.
+     */
+    aggregate<const O extends AggregateOptions<S, K> & ({
+        readonly limit: number;
+    } | {
+        readonly groupBy?: undefined;
+    })>(options: O): Query<readonly AggregateRow<RowOf<S, K>, O>[]>;
+    aggregate<const O extends AggregateOptions<S, K>>(options: O): {
+        all(reason: string): Query<readonly AggregateRow<RowOf<S, K>, O>[]>;
+    };
+    count(options?: CallOptions & {
         readonly where?: WhereOf<S, K>;
     }): Read<number>;
-    exists(options?: {
+    exists(options?: CallOptions & {
         readonly where?: WhereOf<S, K>;
     }): Read<boolean>;
     /**
-     * Inserts one row. Unknown keys are dropped.
+     * Inserts one row. Unknown keys are dropped. `{ allow }` may set guarded fields.
      *
      * Optional columns are optional keys, so completion lists the ones not yet written.
      */
+    insert<const Allow extends readonly (keyof RowOf<S, K> & string)[]>(data: RequiredInsert<InsertOf<S, K>> & OptionalInsert<InsertOf<S, K>> & Partial<Pick<RowOf<S, K>, Allow[number]>>, options: InsertOptions<S, K> & {
+        readonly allow: Allow;
+    }): Write<Show<RowOf<S, K>>>;
     insert(data: RequiredInsert<InsertOf<S, K>> & OptionalInsert<InsertOf<S, K>>, options?: InsertOptions<S, K>): Write<Show<RowOf<S, K>>>;
-    /** Inserts a list in one transaction. Unknown keys are dropped. */
-    insert(data: readonly InsertOf<S, K>[], options?: InsertOptions<S, K>): Write<readonly Show<RowOf<S, K>>[]>;
+    /**
+     * Inserts a list in one transaction. Unknown keys are dropped.
+     *
+     * Rows may carry different keys. An omitted key or an explicit `undefined` takes the
+     * database default for that row; `null` stays NULL.
+     */
+    insert(data: readonly (RequiredInsert<InsertOf<S, K>> & OptionalInsert<InsertOf<S, K>>)[], options?: InsertOptions<S, K>): Write<readonly Show<RowOf<S, K>>[]>;
     /** Updates matching rows, or a per-row list in one statement. `where` is required. */
+    update<const Allow extends readonly (keyof RowOf<S, K> & string)[]>(target: AllowedUpdate<S, K, Allow>, options: WriteOptions<S, K> & {
+        readonly allow: Allow;
+    }): Write<WriteCount>;
     update(target: UpdateTarget<S, K>, options?: WriteOptions<S, K>): Write<WriteCount>;
     /** Deletes matching rows. `where` is required. */
     delete(target: {
         readonly where?: WhereOf<S, K>;
     }, options?: WriteOptions<S, K>): Write<WriteCount>;
+} & (S["~byName"][K] extends {
+    readonly "~archive": true;
+} ? ArchiveOps<S, K, L> : unknown) & PresetApi<S, K, L> & TableExtras<S, K>;
+/**
+ * One method per preset the table or its traits declare.
+ *
+ * Each takes the preset's own arguments and returns the table handle with the
+ * preset applied, so calls chain: `tasks.pending().ownedBy(userId).find({})`.
+ * A table without presets adds nothing.
+ */
+type PresetApi<S extends QuerySchema, K extends keyof S["~byName"] & string, L> = S["~byName"][K] extends {
+    readonly "~presets": infer P;
+} ? {
+    readonly [N in keyof P & string]: P[N] extends (...all: infer All) => unknown ? All extends readonly [unknown, ...infer A] ? (...args: A) => TableApi<S, K, L> : never : never;
+} : unknown;
+/**
+ * `[Symbol.asyncDispose]` when `Symbol` defines it.
+ *
+ * The check stays in the built declaration. A consumer `lib` without
+ * `asyncDispose` does not see the method, including with `skipLibCheck` off.
+ */
+type IfAsyncDisposable<S> = S extends {
+    readonly asyncDispose: infer D;
+} ? D extends symbol ? {
+    [K in D]: () => Promise<void>;
+} : object : object;
+/** Tenant key, when the schema set column tenancy. */
+type TenantKeyOf<S> = S extends {
+    readonly tenancy: {
+        readonly key: infer K extends string;
+    };
+} ? K : never;
+/** Tables that stay off the root client because they carry the tenant key. */
+type ScopedName<S extends QuerySchema> = TenantKeyOf<S> extends never ? never : {
+    readonly [K in keyof S["~byName"] & string]: S["~byName"][K] extends {
+        readonly "~global": string;
+    } ? never : K;
+}[keyof S["~byName"] & string];
+/** Tables on the root client. Global tables stay. Tenant tables need `for()`. */
+type RootName<S extends QuerySchema> = Exclude<keyof S["~byName"] & string, ScopedName<S>>;
+/** Options of `tx()` (spec §15). */
+export type TxOptions = {
+    /** Isolation level. The database default when omitted. Only the outermost `tx()` takes it. */
+    readonly isolation?: "read committed" | "repeatable read" | "serializable";
+    /**
+     * How many times to run the callback again after a serialization failure or a
+     * deadlock. Each run is a fresh transaction. Other errors, `cancelled` and
+     * `outcome_unknown` are never retried. Only the outermost `tx()` takes it.
+     */
+    readonly retry?: number;
+    /** Milliseconds for the whole transaction, retries included. The call fails as `timeout`. */
+    readonly timeout?: number;
+    /** Aborts the transaction and rolls it back. The call fails as `cancelled`. */
+    readonly signal?: AbortSignal;
 };
-/** A client typed by its own schema. */
-export type Connected<S extends QuerySchema> = {
+/** What the callback of a batch gets back: one result per operation, in order. */
+type BatchResults<Ops extends readonly unknown[]> = {
+    -readonly [I in keyof Ops]: Awaited<Ops[I]>;
+};
+/**
+ * Tables of a client: the root client leaves tenant tables out. A flag, not a name list,
+ * because a name list as a type argument costs one instantiation per table on every
+ * use of the client (D176).
+ */
+type TxNames<S extends QuerySchema, Root extends boolean> = Root extends true ? RootName<S> : keyof S["~byName"] & string;
+/**
+ * `tx` and `batch`, on the root client, a scoped client, and the client a transaction hands out.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam Root - True on the root client, whose tenant tables need `for()` first
+ */
+type TxApi<S extends QuerySchema, Root extends boolean> = {
+    /**
+     * Runs `fn` in a transaction on one reserved connection of the primary.
+     *
+     * The callback gets a client with the same tables, presets, tenancy and archive
+     * handling. It commits when `fn` resolves and rolls back when it throws. Inside a
+     * transaction this is a savepoint on the same connection.
+     */
+    tx<T>(fn: (t: TxClient<S, Root>) => Promise<T>): Promise<T>;
+    tx<T>(options: TxOptions, fn: (t: TxClient<S, Root>) => Promise<T>): Promise<T>;
+    /**
+     * Runs writes as one atomic unit on the primary. Results come back in order.
+     *
+     * A failure rolls everything back and the error carries `batchIndex`. Inside a
+     * transaction it runs on a savepoint, so the transaction survives a failure.
+     */
+    batch<const Ops extends readonly Write<unknown>[]>(ops: Ops, options?: CallOptions): Promise<BatchResults<Ops>>;
+};
+/**
+ * The client the callback of `tx()` gets.
+ *
+ * Its tables take row locks on `find`. It has no `close` and no `for()`: scope the
+ * client before calling `tx()`.
+ *
+ * @typeParam S - Connected schema
+ * @typeParam Root - True on the root client, whose tenant tables need `for()` first
+ */
+export type TxClient<S extends QuerySchema, Root extends boolean = false> = {
+    readonly [K in TxNames<S, Root>]: TableApi<S, K, LockOptions>;
+} & {
+    /** Looks up a table by name. An unknown name is OKM1120. */
+    table<K extends TxNames<S, Root>>(name: K): TableApi<S, K, LockOptions>;
+    /**
+     * Runs `fn` after the outermost transaction commits.
+     *
+     * It never runs on rollback. Callbacks run in order. An error in one is reported to
+     * `hookm.onError` and never changes the commit result.
+     */
+    afterCommit(fn: () => void | Promise<void>): void;
+    /**
+     * Takes a transaction-level advisory lock. It is released at commit or rollback.
+     *
+     * A string is hashed; a number or bigint is the key itself.
+     */
+    advisoryLock(key: string | number | bigint, options?: CallOptions): Promise<void>;
+} & TxApi<S, Root>;
+/** A client whose tables are already inside one tenant or an unscoped reason. */
+type ScopedClient<S extends QuerySchema> = {
     readonly [K in keyof S["~byName"] & string]: TableApi<S, K>;
 } & {
     /** Looks up a table by name. An unknown name is OKM1120. */
@@ -315,7 +612,45 @@ export type Connected<S extends QuerySchema> = {
     close(): Promise<void>;
     /** Resolves when the dialect and `requires` checks have finished. */
     readonly connected: Promise<void>;
+} & TxApi<S, false> & IfAsyncDisposable<typeof Symbol>;
+/** `for` and `unscoped` on a schema that set tenancy. */
+type ScopeMethods<S extends QuerySchema> = TenantKeyOf<S> extends never ? object : {
+    /**
+     * Opens a client bound to one tenant.
+     *
+     * The value is the scope. Insert fills it. Reads and writes filter on it.
+     * Input cannot set it.
+     *
+     * @param input - The tenant key and its value
+     */
+    for(input: {
+        readonly [K in TenantKeyOf<S>]: string;
+    }): ScopedClient<S>;
+    /**
+     * Opens a client with no tenant predicate.
+     *
+     * The reason is stored and shown by `inspect()`. Insert still needs `for()`.
+     *
+     * @param reason - Why this client leaves the tenant scope
+     */
+    unscoped(reason: string): ScopedClient<S>;
 };
+/** A client typed by its own schema. */
+export type Connected<S extends QuerySchema> = {
+    readonly [K in RootName<S>]: TableApi<S, K>;
+} & {
+    /** Looks up a table by name. A tenant table on the root client is OKM1701. */
+    table<K extends RootName<S>>(name: K): TableApi<S, K>;
+    /**
+     * Closes the pool when this client opened it.
+     *
+     * A second call waits on the same close. A client that adopted a pool
+     * resolves without closing it.
+     */
+    close(): Promise<void>;
+    /** Resolves when the dialect and `requires` checks have finished. */
+    readonly connected: Promise<void>;
+} & TxApi<S, true> & ScopeMethods<S> & IfAsyncDisposable<typeof Symbol>;
 /**
  * A catalog `okm build` wrote.
  *
@@ -363,7 +698,37 @@ export type ConnectOptions<S extends QuerySchema> = {
      * The target name and `NODE_ENV` do not turn it on.
      */
     readonly requireMeta?: boolean;
+    /**
+     * Replaces a built-in client generator by name.
+     *
+     * `uuidv4`, `uuidv7`, and `okid` are the names. A custom function passed to
+     * `.default()` is not replaced. Tests use this for deterministic ids.
+     */
+    readonly generators?: import("../contracts/generator.js").IdGenerators;
     readonly signal?: AbortSignal;
     readonly timeout?: number;
+    /** Ceilings in milliseconds. See {@link Timeouts}. */
+    readonly timeouts?: Timeouts;
+    /** Observers of notices, transactions and errors. They cannot change a query (spec §18). */
+    readonly hookm?: readonly Hookm[];
+};
+/** Ceilings from `connect({ timeouts })`, in milliseconds. Each key is optional. */
+export type Timeouts = DriverTimeouts;
+/** What `hookm.onTransaction` hears. `depth` is 0 for the transaction and 1 and up for savepoints. */
+export type TransactionEvent = {
+    readonly phase: "start" | "commit" | "rollback";
+    readonly depth: number;
+};
+/**
+ * A read-only observer (spec §18).
+ *
+ * Events only. An error a hook throws is dropped and never reaches the call.
+ */
+export type Hookm = {
+    /** A server notice, such as `RAISE NOTICE`. */
+    onNotice?(notice: Notice): void;
+    /** A transaction or batch starts, commits, or rolls back. */
+    onTransaction?(event: TransactionEvent): void;
+    /** An error the runtime could not give to a caller, such as one from an `afterCommit` callback. */
+    onError?(error: unknown): void;
 };
-export {};

package/dist/runtime/validate/bind.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Registers the validation hook.
+ *
+ * Called when `okmodel/validate` is imported and again from each `v` rule,
+ * so a bundler that drops the module side effect still registers the hook
+ * before `schema()` when the app builds a rule first.
+ */
+/**
+ * Adds the validation hook to schemas compiled after this call.
+ */
+export declare function armValidation(): void;

package/dist/runtime/validate/closed.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OKM1201, thrown when a write would validate and `okmodel/validate` is not registered.
+ *
+ * The sentences are the registry entry. The write chunk loads this module when
+ * it builds the error. The featureless startup graph does not.
+ */
+/** What went wrong. The OKM1201 registry summary is this sentence. */
+export declare const VALIDATION_NOT_IMPORTED = "Validation is enabled but `okmodel/validate` was not imported.";
+/** What to do. The OKM1201 registry fix is this sentence. */
+export declare const VALIDATION_NOT_IMPORTED_FIX = "Import \"okmodel/validate\" before schema().";
+/**
+ * Throws OKM1201.
+ *
+ * The category is `input`. The message and the fix are the registry sentences.
+ */
+export declare function refuseMissingValidation(): never;

package/dist/runtime/validate/engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Validation engine.
+ *
+ * Loaded on the first validated write or standalone call. A failed import
+ * rejects that call. Nothing here runs when validation is off.
+ */
+import type { TableModel } from "../../dialects/pg/model.js";
+import type { AnyTable } from "../../dialects/pg/table.js";
+type Op = "insert" | "update";
+/**
+ * Validates a write input and returns the transformed rows.
+ *
+ * Branded values are copied and not checked again. The copy stays mutable so
+ * insert can fill a client default.
+ *
+ * @param model - Table model. The gate is stored here on first use
+ * @param source - Table whose stored rules are read
+ * @param schemaFlag - The schema `validation` option, as stored
+ * @param op - Insert or update
+ * @param input - One row, a list, or an update target
+ * @returns The input with transforms applied
+ */
+export declare function prepare(model: TableModel, source: AnyTable, schemaFlag: unknown, op: Op, input: unknown): Promise<unknown>;
+/**
+ * Standalone `validate` or `check`.
+ *
+ * `valid` returns a frozen branded value or throws OKM1200. `check` returns
+ * the issues and does not throw for a failed check.
+ *
+ * @param model - Table model. The gate is stored here on first use
+ * @param source - Table whose stored rules are read
+ * @param schemaFlag - The schema `validation` option, as stored
+ * @param op - Insert or update
+ * @param body - One row, a list, or an update patch
+ * @param mode - Throw, or return issues
+ * @param pick - Fields to keep. Omitted, every field is kept
+ * @param omit - Fields to drop
+ * @returns The branded value, or the issues
+ */
+export declare function stand(model: TableModel, source: AnyTable, schemaFlag: unknown, op: Op, body: unknown, mode: "valid" | "check", pick?: readonly string[], omit?: readonly string[]): Promise<unknown>;
+export {};

package/dist/runtime/validate/hook.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Table methods validation adds through the shared client hook.
+ *
+ * Core does not name `insert.validate`. The engine loads on the first call.
+ */
+import type { SchemaHookCtx } from "../../dialects/pg/model.js";
+/**
+ * Adds `insert.validate`, `check`, `pick`, `omit`, and the Standard Schema
+ * surface when this table's validation is on.
+ *
+ * A client-level call has no table and does nothing. A table with validation
+ * off is left as core built it.
+ *
+ * @param target - The table handle being built
+ * @param ctx - Table name and the session
+ */
+export declare function attachValidation(target: Record<string, unknown>, ctx: SchemaHookCtx): void;

package/dist/runtime/validate/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validation rules (`okmodel/validate`).
+ *
+ * Importing this module registers the client hook. An application that does
+ * not import it does not load the hook or the engine. It also merges the
+ * typed surface (`insert.validate`, `check`, `pick`, `omit`, the Standard
+ * Schema members, and `update.validate`) into the table type, so a program
+ * that does not import it does not see or pay for those types.
+ */
+import type { QuerySchema } from "../../dialects/pg/model.js";
+import type { ValidateInsert, ValidateUpdate } from "./surface.js";
+declare module "../types.js" {
+    interface TableExtras<S extends QuerySchema, K extends keyof S["~byName"] & string> {
+        /** `insert` plus the validation members when this table validates. */
+        readonly insert: ValidateInsert<S, K>;
+        /** `update` plus `validate` when this table validates. */
+        readonly update: ValidateUpdate<S, K>;
+    }
+}
+export { v } from "./rules.js";
+export type { Rule } from "./rules.js";