Every release, newest first

💥 Breaking Changes

• —DriverCapabilities no longer includes prepared or describe. Prepared-statement mode stays a connect option. A driver that can describe a statement still exposes pool.describe.
• —hidden({ filterable }) accepts only a literal true. false and a boolean variable are type errors. Call hidden() with no argument. Passing false from JavaScript still leaves the column hidden and not filterable.
• —okm migrate plan --json finding reason is an untrusted object. okm migrate baseline --json unmanaged name is an untrusted object. okm migrate status JSON id, kind, and state are untrusted objects. A database error's text is errors[].detail. summary stays a registry sentence, or A database error was returned (<kind>). when the code has no page.
• —db.batch of a versioned update throws OKM1121 before any statement; move that update into tx(). tx.batch is unchanged, and version: "any" stays allowed.
• —Bound parameters stay off an error cause unless includeValues is set. A page cursor for a hidden or sensitive orderBy carries only the primary key (a gone row is OKM1130), and OkmError is branded so instanceof matches across two copies of the class (#541).

behaviour changes

• —Indexes on a tenant table lead with the tenant key (indexes: true, the default). A unique index is unique per tenant, so two tenants may share a value. tenantIndexes: false turns the prefix off for one table. .global("reason") opts one index out (an empty reason is refused) and .scoped() opts one index in. The nearest level wins. An index that already leads with the key is unchanged, and the next okm generate writes nothing. An index that does not is replaced once: CREATE INDEX CONCURRENTLY for the new index, then DROP INDEX CONCURRENTLY for the old one. That is not a blocking rebuild, and okm migrate check accepts it (Q3, D306, #390). OKM1706 stays when prefixing is off.
• —With validation: true, an unknown key on insert, update, upsert / onConflict, first-or-create, insert.validate, insert.check, insert.pick(...).validate, insert.pick(...).check, insert.omit(...).validate, insert.omit(...).check, update.validate, or insert["~standard"].validate is OKM1120 and names the key and the table (R1, D304). A typo-only update names the key instead of saying "update set is empty." insert.check, pick(...).check, and omit(...).check return rule issues and do not throw OKM1200 for a failed rule. An unknown key throws OKM1120 on those calls too, and the rule issues are lost. The Standard Schema validate throws that OKM1120. It does not return { issues } for an unknown key. A failed rule on that surface still returns { issues }.
• —On a versioned() table, an update with version in set is OKM1120 (was OKM1190). A version string other than "any", such as "2", is OKM1120 (was OKM1121). The message says it must be an integer or "any". Insert of version stays OKM1190.
• —okm generate exits 1 when an error finding exists; the migration file is still written; stderr says okm migrate apply will refuse until it is fixed (Q8, #395). A warning-only finding stays exit 0.
• —okm pull and okm import drizzle write relative imports with the .ts extension so Node type stripping and bunx okm can load the schema (R4, #401). tsc needs allowImportingTsExtensions with noEmit, or rewriteRelativeImportExtensions.
• —An update on a versioned() table without version is a TypeScript error; the runtime OKM1120 stays when types are bypassed (Q5, D305, #392). Non-versioned tables are unchanged.
• —okm exit codes follow the outcome. 0 is done or nothing to do. 1 is a command that ran and failed. 2 is usage or configuration (unknown flag, missing config, a Node older than 22.18). 3 is a decision the command will not ask (OKM1530, and a committed step that needs a person: OKM1553, OKM1555). 4 is a guard (OKM1850, OKM1852, OKM1855, OKM1859). 5 is a target that cannot be reached or a refused feature (OKM1802, OKM1803, OKM1811, OKM1812, OKM1843, OKM1844, OKM1846, OKM1854, OKM1860, and a lost connection). Every other code, including OKM1401, planner OKM1541, OKM1554, OKM1556, OKM1851, OKM1857, and OKM1858, stays 1. A script that only checked non-zero still fails. A script that treated every failure as 1 now sees 2 through 5.
• —okm migrate plan --json, okm migrate baseline --json, and okm catalog export --json keep their previous fields inside the okm.cli/1 envelope data. parsePlanJson reads data and still accepts a bare plan document.
• —okm build and okm dev reject an unknown flag. They used to leave the rest of the line unread.
• —A derived name longer than 63 bytes (index, constraint, sequence, check, trigger) keeps the same shape, a UTF-8 prefix, _, and 8 hex characters, but the suffix is now the 32-bit FNV-1a hash of the full name, not the first 8 characters of its SHA-256. The stored name of every such identifier changes once, so the next okm generate plans a change for it. Names that fit in 63 bytes are unchanged. Two long names that shorten to the same stored name stay OKM1023 (duplicate identity) and are never merged. The featureless app startup graph drops 2,415 minified bytes because sha256.ts leaves it (90,763 to 88,348).
• —schema() resolves every cased name once: snake splits an acronym (userID is user_id), casing: "camel" is accepted, any other casing is OKM1060, and two fields that spell one SQL name are OKM1023. A drop and add that are one casing of each other is OKM1530 and names .sqlName() and .renamedFrom(), and a column rename also renames its identity sequence (#535, #548).
• —Under composite tenancy, index().unique() leads with every tenant key, an ordinary index still leads with the first, a key already named moves to the front once, and two indexes that become the same one are OKM1023. tenantIndexes on a global table, or a tenant-index mark when the schema has no tenancy, is OKM1060, and OKM1706 on a using index names index().global("reason") (#546).
• —A table named capabilities is OKM1023, because db.capabilities is reserved on the root client, a scoped client, and inside tx() (#546).
• —find, one, and page reject a plain hidden key, an unknown key, a wrong filterable value, a bad or() branch, and a hidden orderBy, including inside include, and page rejects an unknown option and relevance() (OKM1120). The same plain hidden key and a bad or() are type errors on count, exists, update, and delete, while a filterable hidden column stays valid in where and orderBy (#549, #550).

✨ Added

♻️ Changed

• —CI reads Bun 1.4.3 from .bun-version. The kill-storm wedge in Bun.sql is still there on that version.
• —bun run pack-contract stores Bun content-hash chunks as dist/shared/*.js and dist/tooling/shared/*.js. The count of each name stays exact, so a different hash passes and a new or removed chunk fails. bun run verify:fast warns when the local Bun differs and still exits 0.
• —gate / check always runs (if: always()), keys concurrency on the pull request number (or the commit on main), and requires the full tier for full-ci, a chore(release) title, a change under .github/workflows, or a push to main. A no-op label event mirrors the last gate result for that commit instead of reporting Success from a skipped job. Plan: [docs/ci-and-test-cycle-plan.md](docs/ci-and-test-cycle-plan.md).
• —The drivers CI group is three shards (drivers suite, drivers rest, drivers-conformance). The pglite conformance report and the live compatibility table check sit on the conformance shard; the fast path keeps a cheap case-list sync. Driver and error suites open PGlite from a prepared data directory instead of running initdb on every pool.
• —postgres.js kill-storm uncaught exceptions are documented as an upstream limit (B-02): a minimal postgres.js-only reproduction lives in docs/postgresjs-kill-storm.md, known-limits and the Drivers page recommend okmodel/pg/pg or okmodel/pg/bun where failover is expected, and the adapter's process listener is described as damage control rather than a fix.
• —A pull request that only changes docs/ or site/ skips the runtime test matrix, Postgres, the type-cost step, and attest. gate / check stays the required status and counts that skip as a pass only when the filter says those jobs are irrelevant.
• —CI builds dist once and uploads it. Jobs that need the build download it. Jobs that do not need it skip the build. Bun's install cache is on every install, and typecheck keeps a TypeScript incremental build.
• —The topology CI group is two shards. Topology tests open PGlite from a prepared data directory instead of running initdb on every database.
• —Tier 1 runs on every pull request push: format, lint, typecheck, the unit tests, property tests at a quarter of their count (OKM_PROPERTY_SCALE), and the size gate. Tier 2 (type cost, the editor check, attest, runtimes, the temporal matrix, package checks, Windows, Postgres 15 and 18, and the drivers-conformance group) runs with the full-ci label and on every push to main. A later commit on main does not cancel the run in progress. A failed gate / check on main opens an issue.
• —Docs: connect({ hookm }) is an array; a single observer object or a hooks key does not register observers.
• —okm migrate check prints, after ok N migrations, that an empty-table replay does not catch a step that fails only on real data: NOT NULL on a populated column, a unique index over duplicates, or a check over existing rows (Q4, #391).
• —The Release workflow runs on a v* tag. Before any build it requires the tagged commit to be an ancestor of origin/main, the tag to match package.json, and a ## v changelog section. It then runs the Postgres suite, the pack contract, and npm stage publish with provenance (npm 11.15 or newer, Node 22.14 or newer). A dispatch with publish false checks main and refuses a tag that is not on main. The publish job is the only one with id-token: write and contents: write, and it uses the release environment. No npm token is stored.
• —OKM1601 now also covers a typed raw statement missing from the lock or a lock that does not parse. OKM1602 names the typed raw parameter count. OKM1702 covers typed raw on a for() client and the trusted() escape. The doctor text and docs/errors/ pages are regenerated.

🔥 Removed

• —Deno is not a supported runtime. Portable checks run on Node and Bun, and the runtime entry is imported as an edge bundle on Node (D297).

🐛 Fixed

• —describe() keeps a numeric minPostgres already on the input (max with the computed floor), and index opclass scan reads every *_ops token case-insensitively, so describe(describe(s)) keeps 17 and 18, a description's floor does not fall to 15, and a later gist_trgm_ops after text_pattern_ops still reports pg_trgm (R5, #402).
• —okm migrate check and okm check reprint table checks (including picklists) on the connected server before planning, so an author IN (...) spelling is not permanent OKM1547 or a NOT VALID/VALIDATE swap against pg_get_constraintdef (R2, #399, D128). Check columns are left out of the plan comparison when an author check omits column handles.
• —okm check checks the Postgres major before author drift and required extensions after it, so a pending migration that creates an extension still surfaces OKM1520 instead of OKM1811. An extension an applied or pending migration creates is not refused as a missing install; when the package is absent from the server, OKM1811 points at okm migrate apply. Several targets and no --target print server checks skipped: N targets, pass --target <name> from okm doctor and okm check (#400).
• —Validated insert / update handles expose ~plan again, so batch() and isolation() work with validation: true. A failing rule inside a batch rolls everything back and reports OKM1200 with issues and batchIndex (D302, Q1).
• —The linter no longer refuses the planner's own NOT VALID then VALIDATE pair when the check is on a column added in the same migration with a constant default (or nullable without a default). A validate on an existing column, or after a volatile default, stays OKM1531 (D301).
• —The expand/contract type-change drop recipe no longer puts -- okm-allow OKM1512 on DROP TRIGGER (that code does not fire there and was OKM1510). The trigger needs no allow; the function keeps OKM1515 and the column keeps OKM1512, under a name header so the first statement is a step (B-36).
• —testing() plain-populates materialized views after migrate, and isolation() falls back to a plain refresh when a concurrent refresh says the view is not populated, so refresh: "concurrently" works inside the harness (B-34).
• —Composite tenancy factories generate a distinct uuid per key, honour an explicit full key, and refuse a partial one instead of copying one key onto another; isolation() flip inserts skip identity columns so lists.id cannot be written no longer fails (B-32).
• —Documented that LIFO PgBouncer on a non-heuristic port can pass the pid probe: mark it with ?pgbouncer=true (or a pooler / pgbouncer host). Apply does not warm-and-hold a second backend (B-41).
• —The statement parameter ceiling is 65,533 so OKM1126 fires before postgres.js's MAX_PARAMETERS_EXCEEDED at 65,534 (B-48).
• —A node-postgres call with timeout or signal removes its checkout error listener, so repeated timed calls do not stack listeners on a pooled client. A call that reaches its deadline while waiting for a connection is refused and does not run. A cancel that does not settle destroys that client, so the pool can serve the next call after a kill storm.
• —After an external-table re-stamp, okm migrate status stays current, generate stays no changes, and okm migrate check no longer fails with OKM1549 when the only catalog drift is external columns (B-45).
• —okm migrate check reprints domain checks before planning, so a non-canonical author check such as VALUE > 0 is OKM1552 only and not permanent OKM1547 when generate says no changes (B-37).
• —A trigger WHEN that names OLD and NEW no longer fails okm check / okm migrate check with "expression contains variables of more than one relation"; introspection reads the predicate from pg_get_triggerdef, and those columns are ordinary table dependencies (B-46).
• —defineConfig({ namespace }) places a trigger's called function with the catalog, so generate/apply/check no longer fail OKM1020 for a missing function in public (B-47).
• —The guide roles flow on a fresh database no longer fails with SAVEPOINT can only be used in transaction blocks during provision: schema ownership runs without a savepoint when no transaction is open, CREATEROLE is checked on the connecting user (not the managed migration role), and a failed provision drops empty bootstrap tables so a retry is clean (B-30).

🔒 Security

• —A store fingerprint blocks a state-changing command when there is no terminal (OKM1859, exit 4), including when that invocation passed --allow-protected. Project-config protection still honors --allow-protected. Deleting protected: true does not delete the stored fingerprint. A terminal is friction, not proof of a human. The ceiling is [Protection](docs/protection.md).
• —A postgres.js generic or aborted-connection failure on a statement whose table has a sensitive column no longer leaves parameters or args on error.cause when the driver omits table (B-33 residual, #364).
• —SECURITY.md names the disclosure address, the report policy, and supported lines (the current 0.x minor and the previous minor, 0.10.x and 0.9.x). [Using OKModel safely](docs/using-okmodel-safely.md) covers lockfile pinning, a minimum release age, and what provenance does not prove.
• —inspect() redacts a write the way a read does, and explain() sends the real parameters and then replaces hidden and sensitive values in params and in the plan text. Batch onQuery params and a page cursor redact from the statement's own table, so a concealed value or a tenant id is not left in clear text, and an OKM1210 message for that column does not contain the value (#551, #560, #562).