okmodel 0.4.0 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 okmodel is a catalog-first TypeScript ORM, PostgreSQL first. Other SQL databases are the direction. CI runs PostgreSQL 15 to 18. The schema is the single source. Migrations and queries come from it.
 
-Version 0.4.0. Apache-2.0.
+Version 0.5.0. Apache-2.0.
 
 ## Contents
 
@@ -58,6 +58,8 @@ Version 0.4.0. Apache-2.0.
   - [Reference data](#reference-data)
   - [Backfill](#backfill)
   - [Testing](#testing)
+  - [Topology](#topology)
+  - [Reference app](#reference-app)
   - [Startup](#startup)
   - [Protected targets](#protected-targets)
 - [Commands](#commands)
@@ -78,9 +80,11 @@ bun add okmodel @electric-sql/pglite
 
 Bun.sql needs no extra package: `import { connect } from "okmodel/pg/bun"`. okmodel has no runtime dependencies. Each installed driver is an optional peer.
 
+The `okm` bin's shebang is node, so `bunx okm` runs it with Node even inside a Bun project. Run `bun --bun okm` when the command must use the Bun runtime (Bun.sql runs only there). A `.ts` config file under plain Node needs Node 22.18 or newer for type stripping.
+
 ## Quickstart
 
-This builds two tables, applies them, and runs one script. The script writes an author and a note, then reads the note with its author. `DATABASE_URL` is a direct Postgres URL, not a pooler.
+This builds two tables, applies them, and runs one script. The script writes an author and a note, then reads the note with its author. `DATABASE_URL` is a direct Postgres URL, not a pooler. Port `6432` and port `6543` count as a pooler. Apply, seed, and check also refuse when the backend pid changes between two statements (OKM1854), unless `--allow-pooler` is set.
 
 ### Configure
 
@@ -371,7 +375,7 @@ if (!(await db.notes.exists({ where: { id: note.id } }))) {
 
 ### Update
 
-`update` changes the columns in `set` on the rows that match `where`. A call with no `where` is OKM1102. `.all(reason)` is the form that means every row.
+`update` changes the columns in `set` on the rows that match `where`. A write with no effective predicate, including undefined values, is OKM1102. An empty `or()` branch is OKM1121. `.all(reason)` is the form that means every row.
 
 ```ts
 // where picks the row. set names the new title.
@@ -380,7 +384,7 @@ await db.notes.update({ where: { id: note.id }, set: { title: "next" } });
 
 ### Delete
 
-`delete` removes the rows that match `where`. A call with no `where` is OKM1102. `.all(reason)` is the form that means every row.
+`delete` removes the rows that match `where`. A write with no effective predicate, including undefined values, is OKM1102. An empty `or()` branch is OKM1121. `.all(reason)` is the form that means every row.
 
 ```ts
 // where picks the row. Without it the call is refused.
@@ -826,7 +830,7 @@ export const app = schema({
 
 ### Views
 
-A view is a saved query. You give it the SQL and the columns that query returns. `db.views.active.find({ limit: 20 })` reads `active`. That handle has no insert or update. There is no query-builder form yet. `okm check` reprints the query on the connected server before it compares, so a difference that is only how that server prints the query is not drift. A materialized view that refreshes while people are reading it needs a unique index, or the declaration is OKM1822. See [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
+A view is a saved query. You give it the SQL and the columns that query returns. `db.views.active.find({ limit: 20 })` reads `active`. That handle has no insert or update. View handles are camelCased: a view named `active_projects` reads as `db.views.activeProjects`. There is no query-builder form yet. `okm check` reprints the query on the connected server before it compares, so a difference that is only how that server prints the query is not drift. A materialized view refreshes with `REFRESH MATERIALIZED VIEW`: the plan populates it with a plain refresh first (Postgres rejects `CONCURRENTLY` on an empty view), then refreshes concurrently when the declaration sets `refresh: "concurrently"`. A materialized view that refreshes while people are reading it needs a unique index, or the declaration is OKM1822. See [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
 
 `views.ts`:
 
@@ -943,7 +947,7 @@ update "public"."notes" set "title" = 'noted' where "title" = 'hello' and ("id"
 
 ### Testing
 
-`okmodel/testing` opens a real pool. `factories` insert rows, `expectQueries` counts statements, and `isolation()` checks that tenant A cannot see tenant B. `okm seed <file>` calls the file's default export with that harness. The target must already be migrated. A protected target is refused unless `--allow-protected`.
+`okmodel/testing` opens a real pool. `factories` insert rows, `expectQueries` counts statements, and `isolation()` checks that tenant A cannot see the row it inserted for tenant B. Each call uses a new pair of tenant ids, deletes what it inserted, and names a factory that is missing. `okm seed <file>` calls the file's default export with that harness. The target must already be migrated. A protected target is refused unless `--allow-protected`.
 
 `factory.ts`:
 
@@ -990,9 +994,86 @@ export default async function seed(t: {
 bunx okm seed seed.ts
 ```
 
+### Topology
+
+`connect({ primary, replicas }, options)` opens one pool per endpoint. An automatic read chooses a replica that has replayed at least as far as this client's last committed write. `routing.consistency` is `"session"` by default. `"eventual"` does not keep that watermark. `routing.maxLag` is a duration (`"5s"`, `"500ms"`, `"2m"`) or a size (`"16MB"`, `"512KB"`, `"1GB"`, `"4096B"`). A bare number is rejected. `find({ route: "primary" })` reads the primary. `find({ route: "replica" })` requires a replica that satisfies the same watermark and lag, and it does not fall back to the primary. `db.using("primary")` or `db.using("replica")` returns a client that forces that route. That client has no `close` and no `using`. `onRoute` receives `{ op, endpoint, reason }`. A throw from it is ignored. A string or an existing pool is one endpoint and serves either `route` from it, and it has no `using`.
+
+The watermark is one value for the whole `connect()`. The root, `for()`, `unscoped()`, `using()`, and `reserve()` share it. A write through any of them moves it for the others. A watermark per `for()` client is not in this version.
+
+When replicas are configured and consistency is `"session"`, a committed write reads `pg_current_wal_insert_lsn()` before its promise resolves. That is one extra round trip: on the primary pool after an autocommit `execute` or `batch`, and on the reserved connection after a successful `COMMIT`. A rollback does not read it. `"eventual"`, and a connect with no replicas, do not read it either.
+
+`routing.select` picks among the replicas that passed health, the watermark, and `maxLag`. The default is `"weighted"`. `weighted` is smooth weighted round-robin. Equal weights take turns. A weight of `0` is rejected. `roundRobin` ignores weights and rotates through the eligible replicas. `leastConnections` uses the replica with the fewest statements already in flight on this client. A tie follows configuration order. `latencyAware` uses the replica with the lowest moving average of round-trip time. A function receives each candidate as `{ name, weight, inflight, latencyMs, lag }` and `{ op: "read" }`. `lag` is the number of bytes the replica is behind the primary, or `null` when that distance is unknown. The function returns one of those objects or its `name`. It runs only when an automatic read has two or more candidates.
+
+A write, a batch, a transaction, or a locking read on a replica route is OKM1840. `route: "replica"` or `using("replica")` with no eligible replica is OKM1843, including a topology with no replicas. An automatic read with `routing.fallback: "error"` and no eligible replica is OKM1844. A migrate target that carries `primary`, `replicas`, `weight`, or `pool` is OKM1845. Waiting for a connection past `timeouts.acquire` is OKM1846, and that wait stays on the endpoint's own pool. The rules are in [topology](https://github.com/omqkhafi/okmodel/blob/main/docs/topology.md).
+
+A replica whose pool is at its maximum, with no idle connection and callers waiting, is skipped. If every replica that can serve the read is in that state, the read uses the primary and `onRoute` reports `fallback:saturated`. When healthy replicas exist and none has caught up, or none is inside `maxLag`, the reason is `fallback:behind`. `route: "replica"` still uses a saturated replica, and it still requires the watermark and `maxLag`.
+
+`replicas.ts`:
+
+```ts
+import { connect } from "okmodel/pg/postgresjs";
+
+import schema from "./schema.ts";
+
+const url = process.env.DATABASE_URL;
+if (url === undefined || url.length === 0) throw new Error("DATABASE_URL is not set");
+const east = process.env.REPLICA_URL;
+if (east === undefined || east.length === 0) throw new Error("REPLICA_URL is not set");
+const west = process.env.REPLICA_URL_WEST ?? east;
+
+const endpoints = {
+  primary: url,
+  replicas: [{ url: east, weight: 2, name: "east" }, west],
+};
+
+const db = await connect(endpoints, {
+  schema,
+  routing: { probe: "1s", fallback: "primary", consistency: "session", select: "weighted" },
+  onRoute(event) {
+    // { op: "read", endpoint: "east", reason: "auto:east" }
+    void event;
+  },
+});
+
+await db.notes.find({ limit: 50 });
+await db.notes.find({ limit: 50, route: "primary" });
+await db.notes.find({ limit: 50, route: "replica" });
+const replica = db.using("replica");
+await replica.notes.find({ limit: 50 });
+await db.close();
+
+const eventual = await connect(endpoints, {
+  schema,
+  routing: { consistency: "eventual" },
+});
+await eventual.notes.find({ limit: 50 });
+await eventual.close();
+
+for (const select of ["roundRobin", "leastConnections", "latencyAware"] as const) {
+  const client = await connect(endpoints, { schema, routing: { select } });
+  await client.notes.find({ limit: 1 });
+  await client.close();
+}
+
+const custom = await connect(endpoints, {
+  schema,
+  routing: {
+    select(candidates) {
+      return candidates[0] ?? "east";
+    },
+  },
+});
+await custom.notes.find({ limit: 1 });
+await custom.close();
+```
+
+### Reference app
+
+The worked example is a project tracker: workspaces as tenants, archive, a function, two views, three generated migrations, and this topology. It is a private package in the repository, not on npm. CI runs it on the primary and two standbys. Board reads go to a replica. A read just after a write, with replay paused, comes back from the primary. The report uses `route: "replica"`. See the [example app](https://github.com/omqkhafi/okmodel/blob/main/docs/example-app.md) and the [reference app notes](https://github.com/omqkhafi/okmodel/blob/main/packages/reference-app/README.md).
+
 ### Startup
 
-`connect()` compares the app with `okm_history`. A database that is ahead by expand migrations still opens. Ahead by a contract migration, or behind the app, is OKM1520 and names the migration. `okm migrate status` prints the same states, plus `failed at step N (resume with okm migrate apply)`.
+`connect()` compares the app with `okm_history`. A database that is ahead by expand migrations still opens. Ahead by a contract migration, or behind the app, is OKM1520 and names the migration. `okm migrate status` prints the same states, plus `failed at step N (resume with okm migrate apply)`, where N is the stored step index. Apply's own `failed at step N` counts from 1, the same number the linter prints.
 
 ### Protected targets
 
@@ -1064,7 +1145,8 @@ Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each rel
 - [x] [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.
 - [x] [0.3](https://github.com/omqkhafi/okmodel/milestone/3) — Extensions, domains, functions, triggers, views, roles, and grants.
 - [x] [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.
+- [x] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
+- [ ] [0.5.1](https://github.com/omqkhafi/okmodel/milestone/7) — QA fixes for 0.5.0.
 
 `okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
 
@@ -1076,11 +1158,11 @@ Measured on this release.
 
 |                                              | Minified |   Gzip | Cold import |
 | -------------------------------------------- | -------: | -----: | ----------: |
-| Runtime entry                                |    5,288 |  2,026 |    2.563 ms |
-| App startup (10 tables, one find)            |   89,461 | 29,720 |   13.379 ms |
-| App startup, every 0.2 feature in use (full) |  119,936 | 39,121 |   13.745 ms |
+| Runtime entry                                |    5,288 |  2,026 |    2.347 ms |
+| App startup (10 tables, one find)            |   89,751 | 29,801 |   15.061 ms |
+| App startup, every 0.2 feature in use (full) |  120,132 | 39,162 |   15.956 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 30,475 minified and 9,401 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated.
+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 30,381 minified and 9,361 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated. The plain app's cold import on this sample is above the 15 ms local reference. That figure is printed and is not a gate.
 
 The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
 
@@ -1092,5 +1174,6 @@ The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/b
 - [Backfill](https://github.com/omqkhafi/okmodel/blob/main/docs/backfill.md)
 - [Provisioning](https://github.com/omqkhafi/okmodel/blob/main/docs/provisioning.md)
 - [Testing](https://github.com/omqkhafi/okmodel/blob/main/docs/testing.md)
+- [Topology](https://github.com/omqkhafi/okmodel/blob/main/docs/topology.md)
 - [Known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md)
 - [Changelog](https://github.com/omqkhafi/okmodel/blob/main/changelog.md)

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

@@ -62,6 +62,26 @@ export declare function serializeCatalog(source: Catalog): string;
  * @returns Lowercase hex digest
  */
 export declare function catalogHash(source: Catalog): string;
+/**
+ * The catalog `connect()` compares with `okm_meta` (D208).
+ *
+ * Roles, grants, and default privileges come from the migration config, not
+ * the schema, so they are left out. A `schema()` catalog never has them, so
+ * `connect()` hashes it unchanged. `okm check` still verifies them. A
+ * catalog without them is returned as is.
+ *
+ * @param source - Catalog document
+ * @returns The catalog without role, grant, and default-privilege objects
+ */
+export declare function startupCatalog(source: Catalog): Catalog;
+/**
+ * {@link catalogHash} of {@link startupCatalog}. The hash `okm_meta` and
+ * `okm_history` store, and the one `connect()` computes.
+ *
+ * @param source - Catalog document
+ * @returns Lowercase hex digest
+ */
+export declare function startupHash(source: Catalog): string;
 /**
  * Loads a build artifact without validating objects.
  *

package/dist/contracts/driver.d.ts

@@ -61,6 +61,13 @@ export type ExecuteOptions = {
      * A deadline is kind `timeout`.
      */
     readonly timeout?: number;
+    /**
+     * Read routing hint.
+     *
+     * Drivers ignore it. A topology router reads it. Absent, the router
+     * classifies the statement.
+     */
+    readonly route?: "primary" | "replica";
 };
 /** Column names and parameter count from a describe. */
 export type DescribeResult = {

package/dist/dialects/pg/filter-parse.d.ts

@@ -3,13 +3,19 @@
  *
  * Loaded the first time `parse()` is called. `filters()` validates the spec
  * before this module exists.
+ *
+ * A request key is equality when the value is a scalar and `eq` is allowed.
+ * An object value names operators: `eq`, `in` (`inList`), `notIn`, `lt`,
+ * `lte`, `gt`, `gte`, `between`, `startsWith`, `endsWith`, `contains`,
+ * `like`, and `ilike`. `sort` is a field name from the sort list.
  */
 import type { ParsedFilters } from "./table.js";
 /**
  * Reads one request object.
  *
- * A plain value is equality when `eq` is allowlisted. `sort` is a field name
- * from the sort list. JSON cannot add an operator.
+ * Lookups use own properties, so `constructor`, `__proto__`, `toString`, and
+ * `hasOwnProperty` are ordinary keys. A key that is not in `allow` is OKM1123.
+ * `sort` is the exception.
  *
  * @param allow - Fields and the operators each one accepts
  * @param sort - Fields a caller may sort by

package/dist/dialects/pg/fn/index.js

@@ -5,6 +5,9 @@ import {
 import {
   staticNamespace2
 } from "../../../shared/t4tbsy9h.js";
+import {
+  assertIdentifier2
+} from "../../../shared/nfzc5z0w.js";
 import {
   OkmError2
 } from "../../../shared/52szzakm.js";
@@ -26,6 +29,11 @@ function fn(name, options) {
       fix: { summary: "Set search_path on the function to the schemas it is allowed to see." }
     });
   }
+  if (options.searchPath !== undefined && options.searchPath.trim().length > 0) {
+    for (const part of options.searchPath.split(",")) {
+      assertIdentifier2(part.trim(), `function ${name} search_path`);
+    }
+  }
   const argTypes = (options.arguments ?? []).map((argument) => argument.type);
   const schema = options.schema ?? "public";
   return {

package/dist/dialects/pg/index.js

@@ -20,7 +20,7 @@ import {
   many2,
   manyThrough2,
   schema2
-} from "../../shared/3p4b1fg0.js";
+} from "../../shared/5enne4ma.js";
 import {
   domainType
 } from "../../shared/g7ez901n.js";
@@ -32,7 +32,7 @@ import {
   table2,
   index2,
   sql2
-} from "../../shared/jsd07prz.js";
+} from "../../shared/ntneex2a.js";
 import {
   text2,
   varchar2,
@@ -59,6 +59,7 @@ import {
   tag
 } from "../../shared/cn0n68ft.js";
 import {
+  OkmError2,
   catalogError2
 } from "../../shared/52szzakm.js";
 var __defProp = Object.defineProperty;
@@ -909,6 +910,11 @@ function notIn(values) {
 }
 // src/dialects/pg/ops/or.ts
 function or(branches) {
+  if (arguments.length !== 1 || !Array.isArray(branches)) {
+    throw new OkmError2("OKM1121", "Pass an array: or([a, b]).", {
+      fix: { summary: "Pass an array: or([a, b])." }
+    });
+  }
   return tag("or", branches);
 }
 // src/dialects/pg/ops/overlaps.ts

package/dist/dialects/pg/introspect.d.ts

@@ -39,6 +39,12 @@ export type CatalogQuery = {
  * @returns A checked catalog
  */
 export declare function introspectSchema(runner: CatalogQuery, concrete: string, logical?: string, options?: IntrospectOptions): Promise<Catalog>;
+/**
+ * A function's argument types as a grant names them, for `pg_proc p`.
+ *
+ * Types only, comma-separated, no spaces. Argument names are left out.
+ */
+export declare const FUNCTION_ARG_TYPES = "replace(oidvectortypes(p.proargtypes), ' ', '')";
 /**
  * Applies one expression as a check and reads Postgres's reprint.
  *

package/dist/dialects/pg/ops/or.d.ts

@@ -3,7 +3,7 @@ import { type Or } from "../operators.js";
  * Disjunction of where objects.
  *
  * @typeParam V - One branch
- * @param branches - Where objects, or-ed
+ * @param branches - Where objects, or-ed. One array: `or([a, b])`
  * @returns A tagged operator
  */
 export declare function or<const V>(branches: readonly V[]): Or<V>;

package/dist/dialects/pg/role/sql.d.ts

@@ -42,6 +42,16 @@ export declare function privilegeSql(before: readonly CatalogObject[], after: re
  * @returns The role, or `undefined` when the statement is not `CREATE ROLE`
  */
 export declare function createdRoleName(sql: string): string | undefined;
+/**
+ * Runs a plan's `CREATE ROLE` so a role another session created first is not an error.
+ *
+ * Roles belong to the cluster. Two databases provisioned at once both find the
+ * role absent, and the second `CREATE ROLE` fails on `pg_authid`.
+ *
+ * @param sql - A `CREATE ROLE` statement from the plan
+ * @returns The statement in a `DO` block that ignores a duplicate role
+ */
+export declare function createRoleOnce(sql: string): string;
 /**
  * Reports whether a statement creates or alters a role.
  *

package/dist/dialects/pg/schema.d.ts

@@ -144,6 +144,13 @@ type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
     readonly "~insert": InsertFrom<TFields>;
     readonly "~update": UpdateFrom<TFields>;
 } & HasArchive<TTraits> & PresetsOfList<TTraits>;
+/**
+ * `~views` when `schema({ views })` declared any, so `db.views` is typed.
+ * Nothing at runtime carries the key.
+ */
+type SchemaViews<TViews extends readonly unknown[]> = TViews extends readonly [] ? unknown : {
+    readonly "~views": TViews;
+};
 /**
  * Compiles tables into a catalog.
  *
@@ -156,19 +163,21 @@ type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
  */
 export declare function schema<const TTables extends readonly AnyTable[], const TTraits extends readonly {
     readonly fields: Readonly<Record<string, object>>;
-}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation"> & {
+}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined, const TViews extends readonly unknown[] = readonly []>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation" | "views"> & {
     readonly traits: TTraits;
     readonly tenancy?: TTenancy;
     readonly validation?: TValidation;
-}): [TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
+    readonly views?: TViews;
+}): ([TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
     readonly "~validation": TValidation;
-};
-export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation"> & {
+}) & SchemaViews<TViews>;
+export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined, const TViews extends readonly unknown[] = readonly []>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation" | "views"> & {
     readonly tenancy?: TTenancy;
     readonly validation?: TValidation;
-}): [TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
+    readonly views?: TViews;
+}): ([TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
     readonly "~validation": TValidation;
-};
+}) & SchemaViews<TViews>;
 /**
  * Registers a hook from an opt-in module.
  *

package/dist/dialects/pg/temporal.d.ts

@@ -114,100 +114,29 @@ export declare function decodeDuration(wire: string): Temporal.Duration;
  */
 export declare function intervalFields(fields: string): string;
 /**
- * Temporal is in the runtime (Node and Bun) and not in this repository's
- * TypeScript libs. These declarations name the methods the codecs call.
+ * Empty names so `Temporal.Instant` and the other codec types merge with
+ * TypeScript's Temporal lib and with `temporal-polyfill`. Method signatures
+ * live in `temporal.local.d.ts` for this repository's typecheck only. They
+ * are not shipped: a second `toString` or `var Temporal` conflicts with those
+ * libraries (QA-L2).
  */
 declare global {
     /** Instant, plain date-time, date, time, and duration. */
     namespace Temporal {
         /** UTC instant. */
         interface Instant {
-            /**
-             * @param options - Fractional digits to keep
-             * @returns ISO-8601 text
-             */
-            toString(options?: {
-                readonly fractionalSecondDigits?: number;
-            }): string;
         }
         /** Date and time without a zone. */
         interface PlainDateTime {
-            /**
-             * @param options - Fractional digits to keep
-             * @returns ISO-8601 text
-             */
-            toString(options?: {
-                readonly fractionalSecondDigits?: number;
-            }): string;
         }
         /** Calendar date. */
         interface PlainDate {
-            /**
-             * @returns `YYYY-MM-DD`
-             */
-            toString(): string;
-            /**
-             * @param duration - Days to add
-             * @returns A later or earlier date
-             */
-            add(duration: {
-                readonly days: number;
-            }): Temporal.PlainDate;
         }
         /** Time of day. */
         interface PlainTime {
-            /**
-             * @param options - Fractional digits to keep
-             * @returns Time text
-             */
-            toString(options?: {
-                readonly fractionalSecondDigits?: number;
-            }): string;
         }
         /** ISO-8601 duration. */
         interface Duration {
-            /**
-             * @returns ISO-8601 duration text
-             */
-            toString(): string;
         }
     }
-    /** Temporal constructors used by the codecs. */
-    var Temporal: {
-        readonly Instant: {
-            /**
-             * @param item - ISO-8601 instant
-             * @returns An instant
-             */
-            from(item: string): Temporal.Instant;
-        };
-        readonly PlainDateTime: {
-            /**
-             * @param item - ISO-8601 date-time
-             * @returns A plain date-time
-             */
-            from(item: string): Temporal.PlainDateTime;
-        };
-        readonly PlainDate: {
-            /**
-             * @param item - `YYYY-MM-DD`
-             * @returns A date
-             */
-            from(item: string): Temporal.PlainDate;
-        };
-        readonly PlainTime: {
-            /**
-             * @param item - Time text
-             * @returns A time
-             */
-            from(item: string): Temporal.PlainTime;
-        };
-        readonly Duration: {
-            /**
-             * @param item - ISO-8601 duration, or numeric fields
-             * @returns A duration
-             */
-            from(item: string | Readonly<Record<string, number>>): Temporal.Duration;
-        };
-    };
 }

package/dist/dialects/pg/view/index.d.ts

@@ -34,10 +34,15 @@ export type ViewOptions = {
  *
  * `contribute` builds the catalog record. Column dependencies are filled
  * from `pg_depend` by scratch verification, not at this call.
+ *
+ * @typeParam N - View name
+ * @typeParam C - Declared output columns
  */
-export type ViewDeclaration = {
-    readonly name: string;
+export type ViewDeclaration<N extends string = string, C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    readonly name: N;
     readonly schema: string;
+    /** Declared columns, for types only. `db.views` reads them. */
+    readonly "~columns"?: C;
     /**
      * Catalog record for this declaration.
      *
@@ -73,10 +78,15 @@ export type MaterializedViewOptions = ViewOptions & {
  * One declared materialized view.
  *
  * Identity is `(namespace, name)`. Indexes are separate catalog objects.
+ *
+ * @typeParam N - Materialized view name
+ * @typeParam C - Declared output columns
  */
-export type MaterializedViewDeclaration = {
-    readonly name: string;
+export type MaterializedViewDeclaration<N extends string = string, C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    readonly name: N;
     readonly schema: string;
+    /** Declared columns, for types only. `db.views` reads them. */
+    readonly "~columns"?: C;
     /**
      * Catalog records for this declaration.
      *
@@ -100,7 +110,9 @@ export type MaterializedViewDeclaration = {
  * @param options - Columns and query
  * @returns The definition object `schema({ views })` stores
  */
-export declare function view(name: string, options: ViewOptions): ViewDeclaration;
+export declare function view<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: ViewOptions & {
+    readonly columns: C;
+}): ViewDeclaration<N, C>;
 /**
  * Declares a materialized view.
  *
@@ -111,4 +123,6 @@ export declare function view(name: string, options: ViewOptions): ViewDeclaratio
  * @param options - Columns, query, indexes, and refresh mode
  * @returns The definition object `schema({ views })` stores
  */
-export declare function materializedView(name: string, options: MaterializedViewOptions): MaterializedViewDeclaration;
+export declare function materializedView<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: MaterializedViewOptions & {
+    readonly columns: C;
+}): MaterializedViewDeclaration<N, C>;

package/dist/dialects/pg/view/index.js

@@ -9,7 +9,7 @@ import {
 } from "../../../shared/dyj86cmj.js";
 import {
   snakeCase
-} from "../../../shared/jsd07prz.js";
+} from "../../../shared/ntneex2a.js";
 import {
   encodeText,
   decodeText

package/dist/dialects/pg/view/scratch.d.ts

@@ -2,8 +2,8 @@
  * Verifies declared views on a scratch schema.
  *
  * Domain and enum types from the catalog are created there, then the tables,
- * then each view. `pg_get_viewdef` replaces the author query and `pg_depend`
- * supplies column edges (D117).
+ * then the functions a view may call, then each view. `pg_get_viewdef`
+ * replaces the author query and `pg_depend` supplies column edges (D117).
  * The scratch schema is dropped before this returns. Plans never use it.
  */
 import type { Catalog } from "../../../contracts/catalog/types.js";

package/dist/runtime/client.d.ts

@@ -37,9 +37,14 @@ export type Session = {
     };
     /** Tenant value or an unscoped reason. Absent on the root client. */
     readonly scope?: CallScope;
-    /** Shared close. `for()` and `unscoped()` reuse the same promise. */
+    /**
+     * Shared close. `for()` and `unscoped()` reuse the same promise.
+     *
+     * `early` is set when `close()` runs before `connected` settles (QA-M5).
+     */
     readonly closing: {
         current: Promise<void> | undefined;
+        early: boolean;
     };
 };
 /** Per-call modifiers of a read. */

package/dist/runtime/conflict.d.ts

@@ -18,9 +18,10 @@ export type ConflictPlan = {
  * @param table - Target table
  * @param value - The option the caller passed
  * @param allow - Guarded fields this write may set
+ * @param tenantKey - The tenant key on a tenant schema, which every unique includes
  * @returns The plan, or `undefined` for the default `"error"`
  */
-export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>): ConflictPlan | undefined;
+export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>, tenantKey?: string): ConflictPlan | undefined;
 /**
  * Appends the conflict clause, or wraps a first-or-create insert.
  *