okmodel 0.5.0 → 0.6.0

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

@@ -1,10 +1,13 @@
 import {
   functionObject,
   triggerObject
-} from "../../../shared/9x25fxhc.js";
+} from "../../../shared/y34a8714.js";
 import {
   staticNamespace2
-} from "../../../shared/t4tbsy9h.js";
+} from "../../../shared/358zsv4r.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.d.ts

@@ -5,7 +5,8 @@
  * Each builder is a separate export so a bundle can keep only the ones it calls.
  */
 export { schema, type BuiltSchema, type SchemaCodecs, type SchemaInput, type SchemaRequires, } from "./schema.js";
-export { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type Table, type TableOptions, } from "./table.js";
+export { withOwner, type DeclaredOwner } from "./owner.js";
+export { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type FilterOperator, type Table, type TableOptions, } from "./table.js";
 export type { PresetQuery } from "./preset.js";
 export { custom } from "./custom.js";
 export { ColumnBuilder } from "./column.js";

package/dist/dialects/pg/index.js

@@ -2,7 +2,10 @@ import {
   jsonReplacer2,
   json2,
   jsonb2
-} from "../../shared/gjthds9j.js";
+} from "../../shared/9628a9xt.js";
+import {
+  withOwner2
+} from "../../shared/xqve9598.js";
 import {
   encodeInstant,
   decodeInstant,
@@ -14,25 +17,22 @@ import {
   time2,
   timetz2,
   interval2
-} from "../../shared/1g0drakv.js";
+} from "../../shared/5yv4k6a6.js";
 import {
-  one2,
-  many2,
-  manyThrough2,
   schema2
-} from "../../shared/3p4b1fg0.js";
+} from "../../shared/hazqqecq.js";
 import {
   domainType
-} from "../../shared/g7ez901n.js";
+} from "../../shared/ywspezzx.js";
+import {
+  one2,
+  many2,
+  manyThrough2
+} from "../../shared/k68eedmy.js";
 import {
   id2,
   uuid2
-} from "../../shared/dyj86cmj.js";
-import {
-  table2,
-  index2,
-  sql2
-} from "../../shared/jsd07prz.js";
+} from "../../shared/2jd1sn0e.js";
 import {
   text2,
   varchar2,
@@ -40,13 +40,18 @@ import {
   citext2,
   encodeText,
   decodeText
-} from "../../shared/4m9fn52z.js";
+} from "../../shared/ed0b8k4s.js";
+import {
+  table2,
+  index2,
+  sql2
+} from "../../shared/rpycarcr.js";
 import {
   ColumnBuilder2,
   required,
   openColumn,
   formatType
-} from "../../shared/c9z5g0fm.js";
+} from "../../shared/ywr8hmey.js";
 import {
   definition,
   rejected
@@ -54,11 +59,12 @@ import {
 import {
   sameNamespace2,
   compareText
-} from "../../shared/t4tbsy9h.js";
+} from "../../shared/358zsv4r.js";
 import {
   tag
 } from "../../shared/cn0n68ft.js";
 import {
+  OkmError2,
   catalogError2
 } from "../../shared/52szzakm.js";
 var __defProp = Object.defineProperty;
@@ -909,6 +915,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
@@ -998,5 +1009,6 @@ export {
   tstzrange,
   tsvector,
   uuid2 as uuid,
-  varchar2 as varchar
+  varchar2 as varchar,
+  withOwner2 as withOwner
 };

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

@@ -15,6 +15,13 @@ export type IntrospectOptions = {
      * When omitted, roles, grants, and default privileges are not read.
      */
     readonly managedRoles?: readonly string[];
+    /**
+     * Read-only role.
+     *
+     * Schema `USAGE` is read for this role only. Other roles keep the schema
+     * privileges they already have.
+     */
+    readonly reportingRole?: string;
 };
 /** A connection that can run one query. Parameters are `$1`, `$2`, … */
 export type CatalogQuery = {

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

@@ -21,8 +21,13 @@ export type ColumnModel = {
      * call a codec it does not need.
      */
     readonly decode: ((wire: string) => unknown) | undefined;
-    /** Excluded from a default select. Named selects still return it. Includes never return it. */
-    readonly hidden: boolean;
+    /**
+     * Excluded from a default select. Named selects still return it. Includes never return it.
+     *
+     * `"filter"` is still excluded, and `where` and `orderBy` may name it.
+     * `true` is excluded and refused there (OKM1120).
+     */
+    readonly hidden: boolean | "filter";
     /**
      * Redacted in logs, errors, and `inspect()`.
      *

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/owner.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Table ownership marks (`external` and `ignored`).
+ *
+ * The mark lives on the table value, not in `table()` options. `schema()` does
+ * not read it, so a featureless app does not load this module. Tooling stamps
+ * the catalog before it plans.
+ */
+import type { Catalog, Owner } from "../../contracts/catalog/types.js";
+import type { AnyTable } from "./table.js";
+/** Owners a declaration may set. `managed` stays the default. */
+export type DeclaredOwner = Exclude<Owner, "managed">;
+/**
+ * Marks a table `external` or `ignored`.
+ *
+ * `external` is known and queryable, and a plan never creates, alters, or
+ * drops it. `ignored` is invisible to diffs, plans, and `okm check`. The
+ * table stays on the schema, so the client can still name it.
+ *
+ * @param table - A `table()` value
+ * @param owner - `external` or `ignored`
+ * @returns The same table
+ */
+export declare function withOwner<T extends AnyTable>(table: T, owner: DeclaredOwner): T;
+/**
+ * Reads the mark {@link withOwner} stored.
+ *
+ * @param table - A table value
+ * @returns The mark, or `undefined` when the table is managed
+ */
+export declare function tableOwner(table: object): DeclaredOwner | undefined;
+/**
+ * Copies `owner` onto a table and the objects that belong to it.
+ *
+ * Columns, indexes, constraints, triggers, policies, and sequences that
+ * depend on the table follow the table. A catalog with no marks is returned
+ * as itself.
+ *
+ * @param source - Catalog from `schema()`
+ * @param marks - SQL table name to owner
+ * @returns The catalog planning and drift should read
+ */
+export declare function stampOwnership(source: Catalog, marks: ReadonlyMap<string, DeclaredOwner>): Catalog;

package/dist/dialects/pg/path-endpoint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Marks the table a path ends on.
+ *
+ * The symbol lives here so a column-only app and a featureless app do not
+ * load it. `archivable()` reads it. Compile hashes named fields, so the mark
+ * stays out of the catalog.
+ */
+/**
+ * Property set on the tenant table a path ends on.
+ *
+ * An options spread does not copy it. The rewrite sets it on the table object.
+ */
+export declare const pathEndpoint: unique symbol;
+/**
+ * Records that `table` is the end of a path.
+ *
+ * @param table - The rewritten tenant table
+ * @returns The same table, marked
+ */
+export declare function markPathEndpoint<T extends object>(table: T): T;

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

@@ -23,6 +23,9 @@ export declare function assertRoleHealth(runner: Runner, roles: RolesInput, obje
 /**
  * Refuses to apply role changes when the acting role lacks `CREATEROLE`.
  *
+ * A superuser can create roles when `rolcreaterole` is false, so `rolsuper`
+ * satisfies the same check.
+ *
  * @param runner - Database connection
  * @param role - The role that will run `CREATE ROLE` or `ALTER ROLE`
  */

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

@@ -1,11 +1,12 @@
 /**
- * `roles: { migration, app }`.
+ * `roles: { migration, app, reporting? }`.
  *
  * The object contributes role, grant, and default-privilege records. `schema()`
  * does not import this module. Tooling calls {@link attachRoles} when the
  * config names roles.
  */
 import type { Catalog, CatalogObject } from "../../../contracts/catalog/types.js";
+import { OkmError } from "../../../contracts/error.js";
 /** A role the plan creates and alters. It is never dropped. */
 export type ManagedRole = {
     readonly name: string;
@@ -14,37 +15,101 @@ export type ManagedRole = {
     /** `INHERIT` when not `false`. */
     readonly inherit?: boolean;
 };
+/**
+ * One column grant.
+ *
+ * `on` is the table, view, or materialized view name. `select` and `update`
+ * name columns. A hidden column is included only when it is listed here.
+ */
+export type ColumnGrantInput = {
+    /** Role that receives the privilege. */
+    readonly role: string;
+    /** Table, view, or materialized view. */
+    readonly on: string;
+    /** Columns granted `SELECT`. */
+    readonly select?: readonly string[];
+    /** Columns granted `UPDATE`. */
+    readonly update?: readonly string[];
+};
+/**
+ * Why a `roles` declaration was refused.
+ *
+ * `reporting_distinct` means the reporting role is the migration or
+ * application role. `reporting_write` means that role was granted a write.
+ */
+export type RoleDeclarationReason = "reporting_distinct" | "reporting_write";
+/**
+ * A `roles` declaration this version refuses.
+ *
+ * The kind stays `invalid`. No new OKM code: OKM1825 is a missing privilege
+ * at doctor time, and OKM1060 is a column definition.
+ */
+export declare class RoleDeclarationError extends OkmError {
+    /** Which rule refused the declaration. */
+    readonly reason: RoleDeclarationReason;
+    /**
+     * @param reason - Which rule failed
+     * @param message - What the author should change
+     */
+    constructor(reason: RoleDeclarationReason, message: string);
+}
+/**
+ * Columns of one table, for the reporting role's hidden-column rule.
+ *
+ * `hidden` is true for `.hidden()` and for `hidden({ filterable: true })`.
+ */
+export type TableExposure = {
+    /** SQL table name. */
+    readonly table: string;
+    /** Field name and SQL name. `hidden` is left out of the reporting role. */
+    readonly columns: readonly {
+        readonly field: string;
+        readonly sql: string;
+        readonly hidden: boolean;
+    }[];
+};
 /**
  * Roles named by `defineConfig`.
  *
  * A string is external: it must already exist. A name listed in `managed` is
- * created when `pg_roles` does not have it.
+ * created when `pg_roles` does not have it. `reporting` receives select only.
  */
 export type RolesInput = {
     /** Role that runs migrations. */
     readonly migration: string;
     /** Role the application connects as. */
     readonly app: string;
+    /**
+     * Read-only role.
+     *
+     * Select on tables, views, and materialized views, usage on schemas, and
+     * default privileges for later tables. No write and no execute.
+     */
+    readonly reporting?: string;
     /** Roles this catalog creates and alters. */
     readonly managed?: readonly ManagedRole[];
+    /** Column `SELECT` or `UPDATE` grants. */
+    readonly columns?: readonly ColumnGrantInput[];
 };
 /**
  * Adds role, grant, and default-privilege objects to a catalog.
  *
  * Grants and default privileges are for {@link RolesInput.app} on every
- * managed table, view, materialized view, sequence, and function. Fine-grained
- * grants are not accepted here.
+ * managed table, view, materialized view, sequence, and function. Column
+ * grants and the reporting role are added when `input` names them.
  *
  * @param source - Catalog from `schema()`
  * @param input - Migration role, application role, and managed roles
+ * @param exposure - Hidden columns. Omitted when no table hides one
  * @returns A catalog that includes those objects
  */
-export declare function attachRoles(source: Catalog, input: RolesInput): Catalog;
+export declare function attachRoles(source: Catalog, input: RolesInput, exposure?: readonly TableExposure[]): Catalog;
 /**
  * Catalog records for one `roles` configuration.
  *
  * @param input - Migration role, application role, and managed roles
  * @param built - Objects already in the catalog
+ * @param exposure - Hidden columns. Omitted when no table hides one
  * @returns Role, grant, and default-privilege records
  */
-export declare function contributeRoles(input: RolesInput, built: readonly CatalogObject[]): readonly CatalogObject[];
+export declare function contributeRoles(input: RolesInput, built: readonly CatalogObject[], exposure?: readonly TableExposure[]): readonly CatalogObject[];

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

@@ -19,6 +19,17 @@ export type PrivilegeStatement = {
     readonly sql: string;
     readonly kind: "revoke" | "revoke-default" | "create-role" | "alter-role" | "grant-default" | "grant";
 };
+/**
+ * Privilege name for a column grant.
+ *
+ * Columns are sorted so the identity is stable. The catalog stores this
+ * string. It does not grow the grant type.
+ *
+ * @param name - `SELECT` or `UPDATE`
+ * @param columns - SQL column names
+ * @returns `SELECT(email,name)`
+ */
+export declare function columnPrivilege(name: string, columns: readonly string[]): string;
 /**
  * Diffs role, grant, and default-privilege objects into SQL.
  *

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

@@ -114,6 +114,8 @@ export type TenancySchema<S, TTables extends readonly AnyTable[], TTenancy> = TT
     readonly "~byName": {
         readonly [T in TTables[number] as T["~name"]]: T extends {
             readonly "~global": string;
+        } ? T : T extends {
+            readonly "~path": string;
         } ? T : T & {
             readonly "~row": RowFrom<TenantFields<TTenancy["key"]>>;
             readonly "~insert": InsertFrom<TenantFields<TTenancy["key"]>>;

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

@@ -154,7 +154,8 @@ export type Table<TName extends string, TColumns, TRelations extends Readonly<Re
      * Allowlisted client filters.
      *
      * A hidden field in `allow`, `sort`, or `relations` throws OKM1123 here.
-     * `parse` loads the parser on first use.
+     * `parse` loads the parser on first use. An operator outside
+     * {@link FilterOperator} is not assignable.
      *
      * @param spec - Fields, operators, and sorts the caller may send
      * @returns A parser for one request object
@@ -163,10 +164,23 @@ export type Table<TName extends string, TColumns, TRelations extends Readonly<Re
         parse(query: unknown): Promise<ParsedFilters>;
     };
 };
+/**
+ * Operators `filters().parse` applies.
+ *
+ * `path`, `matches`, `similar`, `wordSimilar`, boolean trees, relation
+ * quantifiers, and write operators are not in this list. A caller cannot
+ * name them in `allow`.
+ */
+export type FilterOperator = "eq" | "in" | "inList" | "notIn" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "endsWith" | "contains" | "like" | "ilike" | "not" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey";
 /** What {@link Table.filters} accepts. */
 export type FilterSpec = {
-    readonly allow?: Readonly<Record<string, readonly string[]>>;
+    readonly allow?: Readonly<Record<string, readonly FilterOperator[]>>;
     readonly sort?: readonly string[];
+    /**
+     * Relation name to the fields a caller may filter.
+     *
+     * `parse` turns `{ list: { name: { startsWith: "a" } } }` into `has`.
+     */
     readonly relations?: Readonly<Record<string, readonly string[]>>;
 };
 /** `where` and `orderBy` a caller can spread into `find`. */
@@ -266,7 +280,7 @@ type PrimaryOf<TOptions> = TOptions extends {
  * @typeParam TColumns - Column builders
  * @typeParam TOptions - Options argument
  */
-type DeclaredTable<TName extends string, TColumns, TOptions> = Table<TName, TColumns, RelationsOf<TOptions>, PrimaryOf<TOptions>, NoInfer<TOptions>> & TraitShapes<TColumns, TOptions> & ArchiveFlag<TOptions> & PresetFlag<TOptions> & OmitFlag<TOptions> & GlobalFlag<TOptions>;
+type DeclaredTable<TName extends string, TColumns, TOptions> = Table<TName, TColumns, RelationsOf<TOptions>, PrimaryOf<TOptions>, NoInfer<TOptions>> & TraitShapes<TColumns, TOptions> & ArchiveFlag<TOptions> & PresetFlag<TOptions> & OmitFlag<TOptions> & GlobalFlag<TOptions> & PathFlag<TOptions>;
 type ArchiveFlag<TOptions> = TOptions extends {
     readonly traits: infer TTraits;
 } ? HasArchive<TTraits> : unknown;
@@ -291,6 +305,14 @@ type GlobalFlag<TOptions> = TOptions extends {
 } ? {
     readonly "~global": TReason;
 } : unknown;
+/** A path table keeps its own columns. The schema type does not add the tenant key. */
+type PathFlag<TOptions> = TOptions extends {
+    readonly tenancy: {
+        readonly via: infer TVia extends string;
+    };
+} ? {
+    readonly "~path": TVia;
+} : unknown;
 type TraitShapes<TColumns, TOptions> = TOptions extends {
     readonly traits: infer TTraits;
 } ? TTraits extends readonly {

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/tenancy.d.ts

@@ -16,9 +16,15 @@ import type { AnyTable } from "./table.js";
 export type TenantFields<Key extends string> = {
     readonly [K in Key]: ColumnBuilder<string, FlagTrue<PlainFlags, "guarded">>;
 };
-/** One tenant value, or a reason for leaving the scope. The value is not a cache key. */
+/**
+ * One tenant value, or a reason for leaving the scope. The value is not a cache key.
+ *
+ * `values` is set when the tenant is several keys. `value` stays the first key,
+ * which is what a single-key scope already stored.
+ */
 export type TenantCall = {
     readonly value: string;
+    readonly values?: Readonly<Record<string, string>>;
 } | {
     readonly unscoped: string;
 };
@@ -49,10 +55,45 @@ export type TenancyRule = {
  */
 export type ColumnTenancy = {
     readonly key: string;
+    /** Every tenant field, in declaration order. One entry for column tenancy. */
+    readonly keys?: readonly string[];
     readonly type: "uuid";
-    readonly strategy: "column";
+    readonly strategy: string;
     /** Tables with the tenant column, widened uniques, and composite references. */
     rewrite(tables: readonly AnyTable[]): readonly AnyTable[];
+    /** Path table: isolation follows a relation instead of a tenant column. */
+    isPath?(table: string): boolean;
+    /**
+     * Steps from a path table to the tenant table.
+     *
+     * Absent when `table` has its own tenant column.
+     */
+    pathOf?(table: string): readonly {
+        readonly child: string;
+        readonly parent: string;
+        readonly localField: string;
+        readonly remoteField: string;
+    }[] | undefined;
+    /**
+     * Writes a locking `EXISTS` for an insert into a path table.
+     *
+     * @returns `false` when `table` is not a path table
+     */
+    lockPredicate?(input: {
+        readonly table: string;
+        readonly fieldSql: (field: string) => string | undefined;
+        readonly encode: ((value: unknown) => string) | undefined;
+        readonly alias: string;
+        readonly appended: boolean;
+        readonly scope: TenantCall | undefined;
+        readonly sink: TenancyText;
+    }): boolean;
+    /**
+     * Checks a path update's new parent in the same statement.
+     *
+     * A column-tenant table ignores it.
+     */
+    noteParent?(table: string, set: Readonly<Record<string, unknown>>, sink: TenancyText, scope: TenantCall | undefined, fieldSql: (field: string) => string | undefined): void;
     /** The guarded uuid column, for emitted row types. */
     column(): object;
     predicate(input: {
@@ -95,7 +136,8 @@ export type ColumnTenancy = {
 /**
  * Reads `schema({ tenancy })`.
  *
- * Omitted stays `undefined`. Anything else must be `columnTenancy()`.
+ * Omitted stays `undefined`. Anything else must carry `rewrite`. The strategy
+ * name stays on the object from `okmodel/tenancy`. This file does not list them.
  *
  * @param value - The option the caller passed
  * @returns The tenancy object, or `undefined`