okmodel 0.5.0 → 0.6.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.5.0. Apache-2.0.
+Apache-2.0. The published version is [okmodel on npm](https://www.npmjs.com/package/okmodel).
 
 ## Contents
 
@@ -80,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
 
@@ -343,12 +345,12 @@ if (row?.title !== "hello" || row.author?.name !== "Ada") {
 
 ### One
 
-`one` returns the single note for that id. More than one match throws `not_unique`.
+`one` returns the note for that id, or null when none matches. More than one match throws `not_unique`.
 
 ```ts
-// One row. More than one match throws.
+// One row, or null. More than one match throws.
 const single = await db.notes.one({ where: { id: note.id } });
-if (single.title !== "hello") throw new Error("one did not return the note");
+if (single === null || single.title !== "hello") throw new Error("one did not return the note");
 ```
 
 ### Count
@@ -373,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.
@@ -382,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.
@@ -396,6 +398,8 @@ Inserting Ada again fails because the name is unique. `safe` returns that `OkmEr
 ```ts
 import { OkmError, safe } from "okmodel";
 
+import { db } from "./db.ts";
+
 // safe returns the unique error instead of throwing.
 const duplicate = await safe(db.authors.insert({ name: "Ada" }));
 if (duplicate.ok || !(duplicate.error instanceof OkmError) || duplicate.error.kind !== "unique") {
@@ -429,7 +433,7 @@ export const app = schema({ tables: [tasks] });
 
 ### Hidden
 
-A password hash should not come back on an ordinary read. `.hidden()` leaves the column out of `find` and out of `include`. Name it in `select` when that call needs it.
+A password hash should not come back on an ordinary read, and a caller should not be able to filter on it. `.hidden()` leaves the column out of `find` and out of `include`, and `where` and `orderBy` refuse it (OKM1120). Name it in `select` when that call needs it. `hidden({ filterable: true })` allows `where` and `orderBy` and still leaves it out of the default row. `filters()` still refuses a hidden column.
 
 `hidden.ts`:
 
@@ -709,7 +713,7 @@ export async function hide(url: string, id: string): Promise<void> {
 
 ### Tenancy
 
-Every note belongs to one tenant. Column tenancy adds `tenantId` and puts that tenant on every read and write. `db.for({ tenantId }).notes.find({ limit: 20 })` reads one tenant. `global("shared")` marks a table every tenant can read, such as a list of countries. Row-level security is not in this version. See [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
+Every note belongs to one tenant. Column tenancy adds `tenantId` and puts that tenant on every read and write. `db.for({ tenantId }).notes.find({ limit: 20 })` reads one tenant. Composite tenancy passes every key, `compositeTenancy({ key: ["organizationId", "workspaceId"], type: "uuid" })` and `db.for({ organizationId, workspaceId })`. A table without its own key uses `tenancy: via("project.organization")`, up to three relations, and reads and writes follow that path. `global("shared")` marks a table every tenant can read, such as a list of countries. `rlsTenancy({ key: "tenantId", type: "uuid" })` keeps that predicate and adds row-level security policies. A role that owns the tables, a superuser, or `BYPASSRLS` is refused on the first scoped call. See [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
 
 `tenancy.ts`:
 
@@ -828,7 +832,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`:
 
@@ -862,7 +866,13 @@ export const app = schema({
 
 ### Roles and grants
 
-The migration connects as one role and the app connects as another. `roles` names both. The app role receives select, insert, update, and delete on tables and views, select on materialized views, execute on functions, and usage plus select on sequences. Apply runs as the migration role, and switches to it with `SET ROLE` when the connection is someone else. The app role is a role you already created, unless you list it in `managed`. Grants on one column, and row-level security, are not in this version. See [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
+The migration connects as one role and the app connects as another. `roles` names both. The app role receives select, insert, update, and delete on tables and views, select on materialized views, execute on functions, and usage plus select on sequences. Apply also grants that role select on `okm_meta`, and nothing else there, so `connect()` can read the stored hash. Apply runs as the migration role, and switches to it with `SET ROLE` when the connection is someone else. A role you already created is external, unless you list it in `managed`.
+
+`roles.reporting` is a third role that can only select. It gets select on tables, views, and materialized views, usage on schemas, and the same select on tables created later. It does not get insert, update, delete, or execute. A hidden column is left out unless `roles.columns` names it. Under `rlsTenancy()` this role is not `BYPASSRLS` and it is not tenant-safe against its own SQL: it sees no tenant rows until the session sets `app.tenant`, and it can set `app.unscoped` itself and then read every tenant. `unscoped()` is the application client's read escape and is not given to this role.
+
+`roles.columns` grants select or update on named columns: `{ role, on, select, update }`. `on` is the table or view. A listed column grant on a view replaces select on the whole view for the reporting role.
+
+`withOwner(table(...), "ignored")` keeps a table out of diffs, plans, and `okm check`. `"external"` is known and never created, altered, or dropped. A managed table that becomes either stays in the database. Drop it while it is still managed if it should go away. See [known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md).
 
 `roles.ts`:
 
@@ -876,7 +886,13 @@ export default defineConfig({
   schema: "./schema.ts",
   database: url,
   // Apply uses the migration role. The app uses the app role.
-  roles: { migration: "okm_migrate", app: "okm_app", managed: [{ name: "okm_migrate" }] },
+  roles: {
+    migration: "okm_migrate",
+    app: "okm_app",
+    reporting: "okm_report",
+    managed: [{ name: "okm_migrate" }, { name: "okm_report", login: true }],
+    columns: [{ role: "okm_report", on: "tasks", select: ["title"] }],
+  },
 });
 ```
 
@@ -945,7 +961,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, including through a tenant view or materialized view. Each call uses a new pair of tenant ids, deletes what it inserted, and names a factory that is missing. A global table or view is skipped and listed. `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`:
 
@@ -1071,7 +1087,7 @@ The worked example is a project tracker: workspaces as tenants, archive, a funct
 
 ### 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
 
@@ -1144,6 +1160,8 @@ Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each rel
 - [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.
 - [x] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
+- [x] [0.5.1](https://github.com/omqkhafi/okmodel/milestone/7) — QA fixes for 0.5.0.
+- [x] [0.6](https://github.com/omqkhafi/okmodel/milestone/8) — Composite, path, and row-level tenancy, column grants, a reporting role, and SQL constraint names.
 
 `okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
 
@@ -1155,11 +1173,11 @@ Measured on this release.
 
 |                                              | Minified |   Gzip | Cold import |
 | -------------------------------------------- | -------: | -----: | ----------: |
-| 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 |
+| Runtime entry                                |    5,288 |  2,026 |    1.790 ms |
+| App startup (10 tables, one find)            |   90,762 | 30,139 |   10.490 ms |
+| App startup, every 0.2 feature in use (full) |  121,506 | 39,741 |   12.455 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,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 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,744 minified and 9,602 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 under 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).
 

package/dist/adapters/pg/no-inflight-timeout.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Refusal for a driver that cannot cancel an in-flight statement (D224).
+ *
+ * Bun.sql and PGlite throw OKM1120 for a positive `timeout`. The message
+ * stays `timeout` because the PGlite connect graph has two gzip bytes left.
+ * Kind is `invalid`, which separates it from kind `timeout`. `timeout: 0`
+ * still fails immediately as kind `timeout`. `signal` is unchanged.
+ * postgres.js and node-postgres do not import this.
+ */
+/**
+ * Throws OKM1120 when `timeout` is a positive number.
+ *
+ * @param options - Per-call options. Absent, and a non-positive timeout, pass through
+ */
+export declare function noTimeout(options: {
+    readonly timeout?: number;
+} | undefined): void;

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

@@ -42,6 +42,28 @@ export declare function describe(sql: Sql, text: string, params?: readonly WireV
  * @returns Chunks of wire rows
  */
 export declare function stream(sql: Sql, text: string, params?: readonly WireValue[]): AsyncIterable<readonly (readonly WireValue[])[]>;
+type Lost = {
+    on: boolean;
+};
+/**
+ * Rejects later writes once postgres.js reports the reserved socket closed.
+ *
+ * The first statement installs `onclose`. The checkout guard then refuses
+ * the next statement, savepoint, or COMMIT before `socket.write`.
+ *
+ * @param sql - Reserved connection
+ * @param lost - Set when that socket closes
+ */
+/**
+ * Sets `lost` when the reserved socket closes.
+ *
+ * The first statement installs `onclose`. Later statements see the flag
+ * before they write.
+ *
+ * @param sql - Reserved connection
+ * @param lost - Set when that socket closes
+ */
+export declare function watchReserved(sql: Sql, lost: Lost): void;
 /** Refcount a checkout or a listener borrows from the pool. */
 type Gate = {
     enter(): void;

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

@@ -67,11 +67,13 @@ export declare function catalogHash(source: Catalog): string;
  *
  * 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.
+ * `connect()` hashes it unchanged. `okm check` still verifies them. An
+ * `external` or `ignored` owner is planning state. The startup copy writes
+ * it back to `managed`, which is what `schema()` stored. A catalog with
+ * neither privileges nor those owners is returned as is.
  *
  * @param source - Catalog document
- * @returns The catalog without role, grant, and default-privilege objects
+ * @returns The catalog `connect()` hashes
  */
 export declare function startupCatalog(source: Catalog): Catalog;
 /**
@@ -89,11 +91,23 @@ export declare function startupHash(source: Catalog): string;
  * stored hash and the version, then trusts the objects (D133). `okm check`
  * and dev keep {@link parseCatalog}.
  *
- * @param text - Canonical catalog JSON
- * @param hash - SHA-256 of `text`, stored beside the artifact
+ * @param text - Catalog JSON. A BOM is stripped and `\r` is removed before the hash check
+ * @param hash - SHA-256 of that normalized text, stored beside the artifact
  * @returns The catalog document
  */
 export declare function loadTrustedCatalog(text: string, hash: string): Catalog;
+/**
+ * Catalog file bytes the hash covers.
+ *
+ * A leading UTF-8 BOM is dropped. Carriage returns are removed, so a CRLF
+ * checkout hashes like the LF file the writer stored. An LF file is unchanged.
+ * UTF-16 is OKM1027.
+ *
+ * @param text - Raw catalog JSON or hash file
+ * @param label - Name used when the text is UTF-16
+ * @returns Text to hash and parse
+ */
+export declare function catalogFileText(text: string, label?: string): string;
 /**
  * Reads canonical catalog JSON.
  *

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

@@ -106,7 +106,8 @@ export declare function index(input: IndexInput): IndexObject;
  * Builds a constraint object.
  *
  * Primary key names are `{parent}_pkey` and do not include column names.
- * Other names use `nameKey`, which stays fixed when a field is renamed.
+ * Unique and foreign-key names use every SQL column. Checks use `nameKey`,
+ * which stays fixed when a field is renamed. `nameKey` is always stored.
  *
  * @param input - Parent, kind, columns, and the stable name key
  * @returns A constraint envelope

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

@@ -0,0 +1,48 @@
+/**
+ * Row-level security policy catalog objects.
+ *
+ * The factory stores the record. It does not plan SQL. Postgres DDL stays in
+ * the dialect. A schema that never imports `rlsTenancy` does not load this.
+ */
+import type { ObjectIdentity, ObjectRef, Owner, PolicyCommand, PolicyObject, Provenance } from "./types.js";
+/** Input for {@link policyObject}. */
+export type PolicyInput = {
+    readonly parent: ObjectRef;
+    readonly name: string;
+    readonly command: PolicyCommand;
+    readonly expression: string;
+    /** True when the table is `FORCE ROW LEVEL SECURITY`. */
+    readonly force: boolean;
+    readonly owner?: Owner;
+    readonly provenance: Provenance;
+    /** Extra edges. The parent table is always included. */
+    readonly dependencies?: readonly ObjectIdentity[];
+};
+/**
+ * Predicate stored for `{table}_tenant`.
+ *
+ * The text is what `pg_get_expr` prints, so a replayed catalog matches.
+ * An unset `app.tenant` becomes null and the comparison matches no row.
+ *
+ * @param column - SQL name of the tenant column
+ * @param dataType - Postgres type of that column
+ * @returns The `USING` and `WITH CHECK` expression
+ */
+export declare function tenantPolicyExpression(column: string, dataType: string): string;
+/**
+ * Predicate stored for `{table}_unscoped_select`.
+ *
+ * `SELECT` only. Writes stay on the tenant policy.
+ *
+ * @returns The `USING` expression
+ */
+export declare function unscopedPolicyExpression(): string;
+/**
+ * Builds a policy record.
+ *
+ * Identity is `(parent, name)`. A name past the dialect limit is fitted.
+ *
+ * @param input - Parent table, command, and expression
+ * @returns The catalog object
+ */
+export declare function policyObject(input: PolicyInput): PolicyObject;

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

@@ -393,6 +393,13 @@ export type ViewColumn = {
 export type ViewDefinition = {
     readonly columns: readonly ViewColumn[];
     readonly query: string;
+    /**
+     * `WITH (security_invoker = true)`.
+     *
+     * Set only for a view over tenant tables under `rlsTenancy`. Omitted
+     * otherwise, so a view under another strategy keeps the same catalog bytes.
+     */
+    readonly securityInvoker?: true;
 };
 /**
  * Materialized view definition.
@@ -440,10 +447,27 @@ export type RoleObject = CatalogEnvelope<"role", RoleIdentity, RoleDefinition>;
 export type GrantObject = CatalogEnvelope<"grant", GrantIdentity, GrantDefinition>;
 /** A default privilege. Identity is `(forRole, namespace, objectKind, grantee, privilege)`. */
 export type DefaultPrivilegeObject = CatalogEnvelope<"defaultPrivilege", DefaultPrivilegeIdentity, DefaultPrivilegeDefinition>;
+/** Which statements a policy covers. `all` is every command. `select` is reads. */
+export type PolicyCommand = "all" | "select";
+/**
+ * One row-level security policy.
+ *
+ * `expression` is the `USING` text, and the `WITH CHECK` text when `command`
+ * is `all`. `force` is true when the table is `FORCE ROW LEVEL SECURITY`.
+ */
+export type PolicyDefinition = {
+    readonly command: PolicyCommand;
+    readonly expression: string;
+    readonly force: boolean;
+};
+/** A policy. Identity is `(parent, name)`. */
+export type PolicyObject = CatalogEnvelope<"policy", AnchoredIdentity & {
+    readonly kind: "policy";
+}, PolicyDefinition>;
 /**
  * One built catalog object.
  */
-export type CatalogObject = TableObject | ColumnObject | IndexObject | ConstraintObject | SequenceObject | TypeObject | ExtensionObject | FunctionObject | TriggerObject | ViewObject | MaterializedViewObject | RoleObject | GrantObject | DefaultPrivilegeObject;
+export type CatalogObject = TableObject | ColumnObject | IndexObject | ConstraintObject | SequenceObject | TypeObject | ExtensionObject | FunctionObject | TriggerObject | ViewObject | MaterializedViewObject | RoleObject | GrantObject | DefaultPrivilegeObject | PolicyObject;
 /** Format version stored in the serialized catalog. */
 export declare const CATALOG_VERSION = 1;
 /** A catalog document. Object order is identity-key order. */

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

@@ -11,6 +11,8 @@ export type ViewInput = {
     readonly name: string;
     readonly columns: readonly ViewColumn[];
     readonly query: string;
+    /** `WITH (security_invoker = true)`. Omitted from the record when unset. */
+    readonly securityInvoker?: true;
     readonly owner?: Owner;
     readonly provenance: Provenance;
     readonly dependencies?: readonly ObjectIdentity[];

package/dist/contracts/internal.js

@@ -13,7 +13,7 @@ import {
   index3,
   constraint2,
   sequence2
-} from "../shared/t4tbsy9h.js";
+} from "../shared/358zsv4r.js";
 import {
   OWNERS2,
   OBJECT_KINDS2,

package/dist/contracts/location.d.ts

@@ -14,6 +14,16 @@
  * @returns `file.ts:line`, or `undefined` when the runtime has no stack
  */
 export declare function callerLocation(skip: number): string | undefined;
+/**
+ * File and line from stack lines, skipping `location.ts` frames.
+ *
+ * A frame may use `/` or `\`.
+ *
+ * @param lines - `Error.stack` split on `\n`
+ * @param skip - Callers to pass before the frame that is recorded
+ * @returns `file.ts:line`, or `undefined` when no frame remains
+ */
+export declare function locationFromLines(lines: readonly string[], skip: number): string | undefined;
 /**
  * Appends a source location to an error message.
  *

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

@@ -207,6 +207,12 @@ export type ColumnState<TValue> = {
     } | undefined;
     readonly guarded: boolean;
     readonly hidden: boolean;
+    /**
+     * Hidden, and allowed in `where` and `orderBy`.
+     *
+     * Absent otherwise. Not part of the catalog or its hash.
+     */
+    readonly filterable?: true;
     /** Redacted in logs, errors, and `inspect()`. Not part of the catalog hash. */
     readonly sensitive: boolean;
     readonly omitWrite: boolean;
@@ -383,11 +389,16 @@ export declare class ColumnBuilder<TValue, TFlags extends ColumnFlags> {
     /**
      * Excludes the column from the default row.
      *
-     * A named `select` still returns it. Includes never do.
+     * A named `select` still returns it. Includes never do. `where` and
+     * `orderBy` refuse it (OKM1120) unless `filterable` is set. `filters()`
+     * still refuses it.
      *
+     * @param options - `filterable` allows the column in `where` and `orderBy`
      * @returns The same column, hidden
      */
-    hidden(): ColumnBuilder<TValue, FlagTrue<TFlags, "hidden">>;
+    hidden(options?: {
+        readonly filterable?: boolean;
+    }): ColumnBuilder<TValue, FlagTrue<TFlags, "hidden">>;
     /**
      * Redacts the value in logs, errors, and `inspect()`.
      *

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

@@ -4,7 +4,7 @@
  * Planning and scratch comparison both render through here, so a statement
  * has one spelling.
  */
-import type { Catalog, CatalogObject, ColumnObject, FunctionObject, MaterializedViewObject, SequenceObject, TableObject, ViewObject } from "../../contracts/catalog/types.js";
+import type { Catalog, CatalogObject, ColumnObject, FunctionObject, MaterializedViewObject, PolicyObject, SequenceObject, TableObject, ViewObject } from "../../contracts/catalog/types.js";
 /**
  * Quotes one identifier.
  *
@@ -23,6 +23,18 @@ export declare function quoteIdent(name: string): string;
  * @returns SQL statements
  */
 export declare function renderCatalog(source: Catalog, schema: string): readonly string[];
+/**
+ * Pulls a unique constraint in front of a foreign key that references it.
+ *
+ * The primary key is created with the table. A foreign key aimed at another
+ * unique has to wait for that unique. Create order ties those two by name, so
+ * the foreign key can otherwise come first. The planner uses this for creates
+ * and for the list it reverses when it drops.
+ *
+ * @param objects - Create order
+ * @returns The same objects, with those uniques moved forward
+ */
+export declare function uniqueBeforeForeignKey(objects: readonly CatalogObject[]): readonly CatalogObject[];
 /**
  * Reports whether an index belongs to a view or a materialized view.
  *
@@ -74,6 +86,30 @@ export declare function functionSql(object: FunctionObject, schema: string, repl
  * @returns The statement
  */
 export declare function viewSql(object: ViewObject, schema: string, replace: boolean): string;
+/** One policy statement and the planner kind that classifies it. */
+export type PolicyPlanStep = {
+    readonly sql: string;
+    readonly kind: "enable-rls" | "create-policy" | "drop-policy" | "disable-rls";
+};
+/**
+ * `ENABLE`, `FORCE`, and `CREATE POLICY` for one policy.
+ *
+ * The `all` command policy also enables and forces row-level security.
+ * The `select` policy is the unscoped read. Names are the stored identity.
+ *
+ * @param object - Policy to create
+ * @param schema - Concrete schema name
+ * @returns Statements in apply order
+ */
+export declare function policyCreatePlan(object: PolicyObject, schema: string): readonly PolicyPlanStep[];
+/**
+ * `DROP POLICY`, and for the `all` command policy `NO FORCE` and `DISABLE`.
+ *
+ * @param object - Policy to drop
+ * @param schema - Concrete schema name
+ * @returns Statements in apply order
+ */
+export declare function policyDropPlan(object: PolicyObject, schema: string): readonly PolicyPlanStep[];
 /**
  * `CREATE MATERIALIZED VIEW ... WITH NO DATA`.
  *

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

@@ -6,6 +6,14 @@
  */
 import { type BuiltSchema } from "./schema.js";
 import { type AnyTable } from "./table.js";
+/**
+ * Type arguments read from `t.json<T>()` and `t.jsonb<T>()` in schema source.
+ *
+ * The key is `table.field`. QA-L3 kept the wrapper for a bare `t.jsonb()`,
+ * which has no argument and stays `jsonb<unknown>`. The documented call
+ * `t.jsonb<{ published?: boolean }>()` is this map.
+ */
+export type JsonColumnTypes = ReadonlyMap<string, string>;
 /**
  * Emits row, insert, and update interfaces for every table.
  *
@@ -13,6 +21,16 @@ import { type AnyTable } from "./table.js";
  * and `TasksUpdate`.
  *
  * @param source - Schema from {@link schema}
+ * @param jsonTypes - Type arguments from the schema source. Omitted, json and jsonb stay `unknown`
  * @returns Declaration text
  */
-export declare function emitRowTypes(source: BuiltSchema<readonly AnyTable[]>): string;
+export declare function emitRowTypes(source: BuiltSchema<readonly AnyTable[]>, jsonTypes?: JsonColumnTypes): string;
+/**
+ * Reads `t.json<T>()` and `t.jsonb<T>()` type arguments from schema source.
+ *
+ * A bare `t.jsonb()` has no argument. The key is the table name and the field.
+ *
+ * @param source - Schema source, comments removed by the caller or still present
+ * @returns `table.field` to the type argument text
+ */
+export declare function jsonColumnTypes(source: string): JsonColumnTypes;

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

@@ -2,9 +2,30 @@
  * Maps a Postgres {@link DriverError} to an {@link OkmError} (spec §4.2, §14).
  *
  * Adapters normalise the driver into `DriverError`. They do not construct
- * `OkmError`. Constraint names follow the catalog: `{table}_{nameKey}_{tag}`.
+ * `OkmError`. `connect()` passes its schema. A reason then comes from the
+ * error's columns matched to a catalog object. With no catalog, the
+ * constraint name is parsed.
  */
+import type { Catalog } from "../../contracts/catalog/types.js";
 import { OkmError, type ErrorStatuses } from "../../contracts/error.js";
+/**
+ * Catalog and model used to name a unique, foreign key, or check.
+ *
+ * `connect()` passes the schema it already holds. The reference is enough:
+ * matching stays in this module.
+ */
+export type MapPostgresErrorSchema = {
+    readonly catalog: Catalog;
+    readonly model: Readonly<Record<string, {
+        readonly sql: string;
+        readonly columns: readonly SqlField[];
+    }>>;
+};
+/** One column the reason mapper can turn back into a TypeScript field. */
+type SqlField = {
+    readonly field: string;
+    readonly sql: string;
+};
 /** Options for {@link mapPostgresError}. */
 export type MapPostgresErrorOptions = {
     /**
@@ -15,6 +36,15 @@ export type MapPostgresErrorOptions = {
     readonly includeValues?: boolean;
     /** Category overrides from `connect({ errors })`. */
     readonly http?: ErrorStatuses;
+    /**
+     * Schema whose catalog still has the stored name key.
+     *
+     * Columns in the error select the object. The stored name key is the
+     * reason. A composite key that is only the SQL column list becomes the
+     * TypeScript fields. With no columns, the stored name key is the reason.
+     * An index keeps its full name.
+     */
+    readonly schema?: MapPostgresErrorSchema;
 };
 /**
  * Maps a thrown driver error into an {@link OkmError}.
@@ -28,3 +58,4 @@ export type MapPostgresErrorOptions = {
  * @returns A categorised error
  */
 export declare function mapPostgresError(error: unknown, options?: MapPostgresErrorOptions): OkmError;
+export {};

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

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/ycatkxmq.js";
+} from "../../../shared/jgqj11w4.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/ycatkxmq.js";
+} from "../../../shared/jgqj11w4.js";
 export {
   extension2 as extension
 };

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

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

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

@@ -3,17 +3,24 @@
  *
  * 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 `parse` applies. `sort` is a field name
+ * from the sort list. A relation key becomes `has` over the allowlisted fields.
+ * A column key wins when the same name is in `allow` and `relations`.
  */
 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
  * @param query - One request object
+ * @param relations - Relation name to fields, when `filters` passed any
  * @returns Filters a caller can spread into `find`
  */
-export declare function parseQuery(allow: Readonly<Record<string, readonly string[]>>, sort: readonly string[], query: unknown): ParsedFilters;
+export declare function parseQuery(allow: Readonly<Record<string, readonly string[]>>, sort: readonly string[], query: unknown, relations?: Readonly<Record<string, readonly string[]>>): ParsedFilters;