okmodel 0.3.0 → 0.4.0

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.3.0. Apache-2.0.
+Version 0.4.0. Apache-2.0.
 
 ## Contents
 
@@ -54,7 +54,14 @@ Version 0.3.0. Apache-2.0.
   - [Views](#views)
   - [Roles and grants](#roles-and-grants)
   - [okm ext and okm doctor](#okm-ext-and-okm-doctor)
+  - [Linter](#linter)
+  - [Reference data](#reference-data)
+  - [Backfill](#backfill)
+  - [Testing](#testing)
+  - [Startup](#startup)
+  - [Protected targets](#protected-targets)
 - [Commands](#commands)
+- [Check a history in CI](#check-a-history-in-ci)
 - [Roadmap](#roadmap)
 - [Size](#size)
 - [Docs](#docs)
@@ -143,13 +150,15 @@ A protected target refuses push. Production settings are in the [production chec
 
 ### Reviewed migrations
 
-Generate writes a SQL file and `.okm`, and apply runs that file later so you can read the migration first.
+Generate writes a SQL file and `.okm`. On an empty database, apply installs that schema and any reference rows. A database that already has history runs the new file, so you can read it first.
 
 ```sh
 bunx okm generate init
 bunx okm migrate apply
 ```
 
+Each step is `expand`, `contract`, or unclassified SQL. Expand is additive. Contract removes or tightens something. On an existing table the planner writes the safe form: a concurrent index, a check or foreign key as `NOT VALID` then `VALIDATE`, and `SET NOT NULL` through a validated check. A backfill step updates rows in batches and resumes after a failure. See [Backfill](#backfill).
+
 ### One client
 
 Import `db` from this file wherever the server handles a request. The process keeps one client.
@@ -880,25 +889,173 @@ okm doctor
 okm doctor OKM1811
 ```
 
+### Linter
+
+A migration plan is checked before it runs. Dropping a table, renaming a column, or adding a unique constraint on a table that already exists is an error. On an existing table the planner writes the safe form: a concurrent index, a check or foreign key as `NOT VALID` then `VALIDATE`, and `SET NOT NULL` through a validated check. The same statements written by hand, without that form, are errors. A type change that rewrites the table stays a warning. `okm generate` prints the finding and still writes the file. `okm migrate plan` and `okm check` exit non-zero on an error. `okm migrate apply` refuses with OKM1510 before any statement. The linter reads the plan and the catalogs. It does not connect. See [the linter](https://github.com/omqkhafi/okmodel/blob/main/docs/linter.md).
+
+```text
+error OKM1511 step 1: drops a table -- fix: Stop reading the table in an expand migration, then drop it in a later contract. Or allow OKM1511 with a reason.
+```
+
+```sql
+-- okm-allow OKM1511: the table is empty and nothing reads it
+drop table "public"."notes";
+```
+
+### Reference data
+
+Rows the application needs are declared on the table. Apply on an empty database inserts a missing key. It does not update or delete. The rows are not part of the catalog hash, so a new key does not need a DDL migration.
+
+`reference.ts`:
+
+```ts
+import { schema, table, t } from "okmodel/pg";
+
+const roles = table(
+  "roles",
+  { code: t.text().primaryKey(), label: t.text() },
+  {
+    reference: {
+      key: "code",
+      rows: [{ code: "admin", label: "Admin" }],
+    },
+  },
+);
+
+export default schema({ tables: [roles] });
+```
+
+### Backfill
+
+A backfill is one idempotent `UPDATE` in the migration file. `$1` is the exclusive lower bound and `$2` is the inclusive upper bound. Null opens that side. Apply commits one batch at a time and resumes from `okm_backfill`. There is no `okm backfill` command. A protected target refuses the step unless that invocation passes `--allow-protected`.
+
+```sql
+-- name: fill
+-- class: expand
+
+-- class: expand
+-- action: backfill
+-- lock: ROW EXCLUSIVE
+-- transactional: false
+-- backfill table="public"."notes" key="id" batch=10
+update "public"."notes" set "title" = 'noted' where "title" = 'hello' and ("id" > $1 or $1 is null) and ("id" <= $2 or $2 is null);
+```
+
+### 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`.
+
+`factory.ts`:
+
+```ts
+import { schema, table, t } from "okmodel/pg";
+import { open } from "okmodel/pg/pglite";
+import { testing } from "okmodel/testing";
+
+const notes = table("notes", { id: t.identity(), title: t.text() });
+const app = schema({ tables: [notes] });
+const harness = await testing(app, { driver: open() });
+const factories = harness.factories({
+  notes: (x) => ({ title: x.words(2) }),
+});
+await harness.expectQueries(1, () => factories.notes.create());
+const rows = await harness.db.notes.find({ limit: 5 });
+if (rows.length !== 1) throw new Error("expected one note");
+await harness.close();
+```
+
+`seed.ts`:
+
+```ts
+export default async function seed(t: {
+  factories(definitions: {
+    authors(x: { words(count: number): string }): { name: string };
+    notes(x: { words(count: number): string; ref(table: string): unknown }): {
+      title: string;
+      authorId: unknown;
+    };
+  }): {
+    notes: { create(): Promise<unknown> };
+  };
+}): Promise<void> {
+  const factories = t.factories({
+    authors: (x) => ({ name: x.words(2) }),
+    notes: (x) => ({ title: x.words(2), authorId: x.ref("authors") }),
+  });
+  await factories.notes.create();
+}
+```
+
+```sh
+bunx okm seed seed.ts
+```
+
+### 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)`.
+
+### Protected targets
+
+`protected: true` is a flag on the target, not on the name and not on `NODE_ENV`. Plan, status, check, ext check, and drift stay allowed. Expand and reference rows stay allowed. An empty protected database can be provisioned. Contract, unclassified SQL, push, backfill, and seed are OKM1850 unless that invocation passes `--allow-protected`. `okm migrate check` writes a scratch schema, so it stays refused, and the flag does not apply. Point it at a throwaway Postgres. Protection does not affect `connect()`.
+
 ## Commands
 
-| Command                   | What it does                                                                                                                 |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `okm build`               | Validates the schema and writes `.okm/` (catalog, hash, emitted row types). `okm generate` writes those files too.           |
-| `okm check`               | Reports a stale `renamedFrom` and a table file the schema does not import.                                                   |
-| `okm generate [name]`     | Writes a SQL migration and `.okm/`. The name defaults to `migration`. Prints `no changes` when the schema matches.           |
-| `okm dev`                 | Uses a target named `dev`, or creates a PGlite database in `.okm/dev-db`. It does not apply migrations or write the catalog. |
-| `okm push`                | Applies the schema directly. Refused when the target is protected.                                                           |
-| `okm migrate plan <name>` | Prints the plan and its class. The name is required.                                                                         |
-| `okm migrate apply`       | Replays migration files on the database.                                                                                     |
-| `okm migrate status`      | Prints version, catalog hash, and state for each target.                                                                     |
-| `okm ext list`            | Prints the extensions the connected server can install and the version that is installed.                                    |
-| `okm ext check`           | Compares those versions with the schema. A missing extension is OKM1811. A pin the server does not meet is OKM1812.          |
-| `okm doctor [code]`       | Lists the triggers on each table. A code argument prints that code.                                                          |
-| `okm --version`           | Prints the package version.                                                                                                  |
+| Command                   | What it does                                                                                                                                                                                             |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `okm build`               | Validates the schema and writes `.okm/`. Does not connect.                                                                                                                                               |
+| `okm check`               | Lints the schema and, after `okm_meta` exists, compares the database. Drift is OKM1520. Allowed on a protected target.                                                                                   |
+| `okm generate [name]`     | Writes a SQL migration and `.okm/`. Prints lint findings and still writes the file. Offline.                                                                                                             |
+| `okm dev`                 | Opens a PGlite database in `.okm/dev-db`, or a target named `dev`. It does not apply migrations.                                                                                                         |
+| `okm push`                | Applies the schema directly. OKM1850 on a protected target unless `--allow-protected`.                                                                                                                   |
+| `okm migrate plan <name>` | Prints each step's class and lock, plus a row estimate when the target answers. Read-only on a protected target. An error finding exits non-zero.                                                        |
+| `okm migrate apply`       | Installs the head snapshot on an empty database, or runs pending files. Expand is allowed on a protected target. Contract, unclassified SQL, and backfill need `--allow-protected`.                      |
+| `okm migrate check`       | Replays the history in a scratch schema and checks the previous catalog, the head, and the linter. Prints `ok N migrations`. Refused on a protected target, and `--allow-protected` does not apply.      |
+| `okm migrate status`      | Prints version, catalog hash, and state. Read-only on a protected target. An unfinished backfill is listed under the table.                                                                              |
+| `okm seed <file>`         | Runs the file's default export against the migrated target. OKM1850 on a protected target unless `--allow-protected`.                                                                                    |
+| `okm ext list`            | Prints extensions the server can install. Read-only on a protected target.                                                                                                                               |
+| `okm ext check`           | Compares installed extensions with the schema. OKM1811 if one is missing, OKM1812 if the pin is not met. Read-only on a protected target. `okm ext test` and `okm ext scaffold` are not in this version. |
+| `okm doctor [code]`       | Lists triggers, or explains one error code. A role check is read-only on a protected target.                                                                                                             |
+| `okm --version`           | Prints the package version.                                                                                                                                                                              |
 
 `okmodel` and `okm` are the same command.
 
+## Check a history in CI
+
+`okm migrate check` is the command for a pipeline. It applies every migration into a scratch schema, plans each result back to that file's catalog, checks the previous catalog, requires the last catalog to match the schema, and lints the history. Success prints `ok N migrations`. A failure exits non-zero.
+
+Point it at a throwaway Postgres. A protected target is refused, and `--allow-protected` does not apply. `defineConfig({ lintFrom: "<migration id>" })` skips lint for files before that id, which is how a project adopts the linter without failing on old migrations. Apply still lints pending migrations only.
+
+The previous-catalog check is schema-level. It does not prove application behaviour. Tenant targets are not checked.
+
+```yaml
+name: migrate
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx okm migrate check
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
+```
+
+The config reads `DATABASE_URL`, and that target is not protected.
+
 ## Roadmap
 
 Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each release is a milestone.
@@ -906,7 +1063,7 @@ Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each rel
 - [x] [0.1](https://github.com/omqkhafi/okmodel/milestone/1) — Schema, queries, and migrations on PostgreSQL, with postgres.js and PGlite.
 - [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.
-- [ ] [0.4](https://github.com/omqkhafi/okmodel/milestone/4) — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
+- [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.
 
 `okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
@@ -919,11 +1076,11 @@ Measured on this release.
 
 |                                              | Minified |   Gzip | Cold import |
 | -------------------------------------------- | -------: | -----: | ----------: |
-| Runtime entry                                |    5,288 |  2,026 |    1.794 ms |
-| App startup (10 tables, one find)            |   89,465 | 29,723 |   10.554 ms |
-| App startup, every 0.2 feature in use (full) |  119,940 | 39,123 |   12.663 ms |
+| 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 |
 
-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,400 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,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 rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
 
@@ -931,6 +1088,9 @@ The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/b
 
 - [Quickstart](https://github.com/omqkhafi/okmodel/blob/main/docs/quickstart.md)
 - [Production checklist](https://github.com/omqkhafi/okmodel/blob/main/docs/production.md)
+- [Linter](https://github.com/omqkhafi/okmodel/blob/main/docs/linter.md)
+- [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)
 - [Known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md)
 - [Changelog](https://github.com/omqkhafi/okmodel/blob/main/changelog.md)
-- [Design spec](https://github.com/omqkhafi/okmodel/blob/main/docs/okmodel-api-design.md)

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

@@ -35,8 +35,12 @@ export declare function renameColumn(source: Catalog, change: {
 /**
  * Renames a table without renaming its constraints or indexes.
  *
- * Column, index, and constraint parents move to the new name. Expression text
- * that names the table is rewritten. Constraint and index names stay.
+ * Column, index, constraint, and trigger parents move to the new name, and
+ * edges that pointed at those objects move with them. Expression text that
+ * names the table is rewritten. Constraint and index names stay. A grant on
+ * the table, or on an identity sequence named `{table}_{column}_seq`, follows
+ * the name the schema will use. The planner emits the `RENAME` for a default
+ * name; a custom name is left as it is.
  *
  * @param source - Catalog document
  * @param change - Namespace, current table name, and the new name

package/dist/dialects/pg/ext/citext.js

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/7fvtrkwr.js";
+} from "../../../shared/ycatkxmq.js";
 
 // src/dialects/pg/ext/citext.ts
 function citext(options = {}) {

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

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/7fvtrkwr.js";
+} from "../../../shared/ycatkxmq.js";
 export {
   extension2 as extension
 };

package/dist/dialects/pg/ext/pg-trgm.js

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/7fvtrkwr.js";
+} from "../../../shared/ycatkxmq.js";
 import {
   tag
 } from "../../../shared/cn0n68ft.js";

package/dist/dialects/pg/index.js

@@ -20,10 +20,10 @@ import {
   many2,
   manyThrough2,
   schema2
-} from "../../shared/x6wysh83.js";
+} from "../../shared/3p4b1fg0.js";
 import {
   domainType
-} from "../../shared/qbxzvwwc.js";
+} from "../../shared/g7ez901n.js";
 import {
   id2,
   uuid2
@@ -32,7 +32,7 @@ import {
   table2,
   index2,
   sql2
-} from "../../shared/6w5j844a.js";
+} from "../../shared/jsd07prz.js";
 import {
   text2,
   varchar2,

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

@@ -8,11 +8,16 @@ import type { CatalogObject } from "../../../contracts/catalog/types.js";
 /** Statements the planner inserts around the rest of the catalog. */
 export type PrivilegeSql = {
     /** Revokes, run while the objects still exist. */
-    readonly revoke: readonly string[];
+    readonly revoke: readonly PrivilegeStatement[];
     /** Role creates, role alters, and default privileges. Before new tables. */
-    readonly prepare: readonly string[];
+    readonly prepare: readonly PrivilegeStatement[];
     /** Grants on objects that exist, or that this plan creates first. */
-    readonly grant: readonly string[];
+    readonly grant: readonly PrivilegeStatement[];
+};
+/** One privilege statement and the planner kind it is. */
+export type PrivilegeStatement = {
+    readonly sql: string;
+    readonly kind: "revoke" | "revoke-default" | "create-role" | "alter-role" | "grant-default" | "grant";
 };
 /**
  * Diffs role, grant, and default-privilege objects into SQL.
@@ -25,9 +30,11 @@ export type PrivilegeSql = {
  * @param before - Previous catalog objects
  * @param after - Next catalog objects
  * @param schema - Concrete schema name
+ * @param recreated - Identity keys this plan drops and creates. Postgres drops
+ * grants with the object, so those grants are issued again after it exists
  * @returns Statements in three groups
  */
-export declare function privilegeSql(before: readonly CatalogObject[], after: readonly CatalogObject[], schema: string): PrivilegeSql;
+export declare function privilegeSql(before: readonly CatalogObject[], after: readonly CatalogObject[], schema: string, recreated?: ReadonlySet<string>): PrivilegeSql;
 /**
  * Role name in `create role`, when the statement is one.
  *

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

@@ -112,7 +112,13 @@ export type TableOptions<TColumns> = {
      */
     readonly presets?: PresetMap<RowFrom<TColumns>>;
     readonly policies?: unknown;
-    readonly reference?: unknown;
+    /**
+     * Rows the application requires to exist.
+     *
+     * Apply inserts a row when its key is missing. It does not update or delete.
+     * The rows stay on the schema. They are not a diff in the catalog.
+     */
+    readonly reference?: ReferenceOption;
     /** `one` and `many`. Other relation kinds stay reserved. */
     readonly relations?: unknown;
 };
@@ -207,6 +213,16 @@ export type InsertFrom<TColumns> = {
 export type UpdateFrom<TColumns, TKey extends string = never> = {
     readonly [K in keyof TColumns as K extends TKey ? never : ColumnUpdateOf<TColumns[K]> extends never ? never : K]: ColumnUpdateOf<TColumns[K]>;
 };
+/**
+ * Rows declared with the table option `reference`.
+ *
+ * `key` is one column name or several, in constraint order. `rows` are the
+ * values apply inserts when that key is absent.
+ */
+export type ReferenceOption = {
+    readonly key: string | readonly string[];
+    readonly rows: readonly Readonly<Record<string, string | number | boolean | null>>[];
+};
 /**
  * Declares a table.
  *

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

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

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

@@ -1,8 +1,9 @@
 /**
  * Verifies declared views on a scratch schema.
  *
- * Tables from the catalog are created there, then each view. `pg_get_viewdef`
- * replaces the author query and `pg_depend` supplies column edges (D117).
+ * 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).
  * The scratch schema is dropped before this returns. Plans never use it.
  */
 import type { Catalog } from "../../../contracts/catalog/types.js";

package/dist/runtime/catalog-cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One in-flight catalog load per key.
+ *
+ * Concurrent `connect()` calls in one process share the parse. A failure is
+ * dropped so the next call can try again. Success stays for the process.
+ */
+/**
+ * Runs `load` once for `key`.
+ *
+ * The map is filled before `load` starts, so a second call on the same tick
+ * waits on the first promise instead of parsing again.
+ *
+ * @param key - Directory and hash, or the artifact hash
+ * @param load - Reads and trusts the catalog
+ * @returns The shared load
+ */
+export declare function loadOnce(key: string, load: () => Promise<void>): Promise<void>;

package/dist/runtime/compat-words.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Words shared by `connect()` and `okm migrate status` (D197).
+ *
+ * The startup check and the status command name the same situations.
+ * A failed step adds the resume hint status prints.
+ */
+/** The database and the app record the same catalog. */
+export declare const CURRENT = "current";
+/** Pending migrations are expand only. */
+export declare const BEHIND_EXPAND = "behind by expand";
+/** A pending migration is not expand. */
+export declare const BEHIND_CONTRACT = "behind by contract";
+/** The database has expand migrations the app does not. */
+export declare const AHEAD_EXPAND = "ahead by expand";
+/** The database has a contract migration the app does not. */
+export declare const AHEAD_CONTRACT = "ahead by contract";
+/**
+ * Status text for a migration that stopped mid-way.
+ *
+ * @param step - Zero-based step that has no `okm_history` row
+ * @returns The state, including the resume hint
+ */
+export declare function failedAt(step: number): string;

package/dist/runtime/drift-detail.d.ts

@@ -2,25 +2,41 @@
  * Compatibility check used only when the catalog hashes differ.
  *
  * Ahead by expand is compatible. Ahead by a contract step, or behind, fails
- * closed (OKM1520).
+ * closed (OKM1520). The class is the value stored in `okm_history`.
  */
 import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
 /** One applied migration, in history order. */
 export type DriftMigration = {
     readonly id: string;
     readonly catalogHash: string;
-    /** True when every step is expand. */
+    /** True when every stored step class is `expand`. */
     readonly expand: boolean;
 };
+/** How far the database and the app have diverged. */
+export type DriftVerdict = {
+    readonly state: "ok";
+} | {
+    readonly state: "ahead by contract";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind by expand";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind by contract";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind";
+    readonly migrationId: string;
+};
 /**
- * Classifies a hash mismatch.
+ * Classifies a hash mismatch from stored history classes.
  *
  * @param codeHash - Hash of the code's catalog
  * @param recordedHash - Hash stored in `okm_meta`
  * @param migrations - Applied migrations, oldest first
  * @returns `ok` when the database is ahead by expand only
  */
-export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): "ok" | "behind" | "contract";
+export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): DriftVerdict;
 /**
  * Reads history and throws OKM1520 when the database is not expand-ahead.
  *

package/dist/runtime/drift.d.ts

@@ -1,8 +1,10 @@
 /**
  * Startup catalog check.
  *
- * The fast path compares two hashes. History, catalog JSON, and
- * {@link loadTrustedCatalog} load only when those hashes differ.
+ * The fast path compares two hashes and returns. History and
+ * `.okm/catalog.json` load only when those hashes differ. A hash read from
+ * `catalog.hash` requires that JSON file; a missing file or a hash that does
+ * not match is OKM1027. Concurrent loads share one parse.
  */
 import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
 import type { QuerySchema } from "../dialects/pg/model.js";

package/dist/runtime/pg/bun.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open5
-} from "../../shared/01yr20s5.js";
+} from "../../shared/sf8m6tfy.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
@@ -11,7 +11,7 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {

package/dist/runtime/pg/pg.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open4
-} from "../../shared/bqha5cg6.js";
+} from "../../shared/6p5k20sm.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
@@ -11,7 +11,7 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {

package/dist/runtime/pg/pglite.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open3
-} from "../../shared/75xkjv0t.js";
+} from "../../shared/fa9vt245.js";
 import {
   PGLITE_CAPABILITIES,
   readCapability2,
@@ -11,7 +11,7 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {

package/dist/runtime/pg/postgresjs.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open2
-} from "../../shared/xw1d69vd.js";
+} from "../../shared/wqem4jed.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
@@ -11,7 +11,7 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/kkzwp3d2.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {

package/dist/runtime/traits/index.js

@@ -1,3 +1,4 @@
+import"../../shared/8jb4ymh2.js";
 import {
   checkPresetNames,
   duplicatePreset
@@ -7,7 +8,7 @@ import {
 } from "../../shared/n0dgs0pb.js";
 import {
   quoteIdent
-} from "../../shared/wekze34d.js";
+} from "../../shared/41kv2xdm.js";
 import {
   functionObject,
   triggerObject
@@ -20,7 +21,7 @@ import {
 } from "../../shared/dyj86cmj.js";
 import {
   snakeCase
-} from "../../shared/6w5j844a.js";
+} from "../../shared/jsd07prz.js";
 import {
   ColumnBuilder2,
   retarget
@@ -37,7 +38,7 @@ import {
   queryHandle,
   attachHttp,
   settleCall
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/kkzwp3d2.js";
 import {
   installArchiveInspect
 } from "../../shared/xrfnq5k8.js";
@@ -458,7 +459,7 @@ function refuse(host, table) {
 }
 var archiveMod;
 function loadArchive() {
-  archiveMod ??= import("../../shared/m9tv7xn7.js");
+  archiveMod ??= import("../../shared/radd3z4g.js");
   return archiveMod;
 }
 async function settle(host, table, mods) {