okmodel 0.5.1 → 0.7.0

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

@@ -5,6 +5,7 @@
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import { type ClientGenerator } from "../../contracts/generator.js";
+import { type PostgresMajor } from "./floor.js";
 import { type SchemaHook, type TableModel } from "./model.js";
 import type { FieldsOfList, HasArchive, PresetsOfList, Trait } from "./trait.js";
 import { type ColumnTenancy, type TenantFields } from "./tenancy.js";
@@ -15,8 +16,16 @@ export type SchemaCodecs = {
     readonly numeric: "string" | "number";
     readonly timestamps: "temporal";
 };
-/** Engine requirement recorded for connect. */
+/**
+ * Engine requirement recorded for connect.
+ *
+ * The stored value is `>=` and a major. `minPostgres` and the deprecated
+ * string form normalise to the same object.
+ */
 export type SchemaRequires = {
+    /**
+     * @deprecated Use `minPostgres`. `">=17"` is the same floor as `minPostgres: 17`.
+     */
     readonly postgres?: string;
 };
 /**
@@ -28,6 +37,15 @@ export type SchemaRequires = {
  */
 export type SchemaInput<TTables extends readonly AnyTable[]> = {
     readonly tables: TTables;
+    /**
+     * Oldest Postgres major this schema runs on.
+     *
+     * Omitted means 15. A feature that needs a newer major is refused here.
+     */
+    readonly minPostgres?: PostgresMajor;
+    /**
+     * @deprecated Use {@link SchemaInput.minPostgres}. `">=17"` is the same floor as `minPostgres: 17`.
+     */
     readonly requires?: SchemaRequires;
     readonly casing?: "snake";
     readonly codecs?: {
@@ -39,8 +57,13 @@ export type SchemaInput<TTables extends readonly AnyTable[]> = {
     /**
      * What a bare `t.id()` means.
      *
-     * `"uuidv7"` and `"uuidv4"` are database defaults. A client generator is
-     * filled on insert and stays out of the catalog. A column option wins.
+     * Omitted, the database default is `gen_random_uuid()`. `"uuidv4"` stores
+     * the same function. `"uuidv7"` stores `uuidv7()` and needs Postgres 18
+     * (`minPostgres: 18`).
+     * Pick `uuidv7` for a large write-heavy table: the ids are time-ordered
+     * and the index stays local. Random ids are fine elsewhere. A client
+     * generator is filled on insert and stays out of the catalog. A column
+     * option wins.
      */
     readonly defaults?: {
         readonly id?: "uuidv7" | "uuidv4" | ClientGenerator<string>;
@@ -80,6 +103,11 @@ export type BuiltSchema<TTables extends readonly AnyTable[]> = {
     readonly types: "emitted" | "inferred";
     readonly casing: "snake" | undefined;
     readonly codecs: SchemaCodecs;
+    /**
+     * Declared floor, normalised to `>=` and a major.
+     *
+     * Absent when the schema names no floor. Connect then uses 15.
+     */
     readonly requires: SchemaRequires | undefined;
     readonly tables: TTables;
     /**
@@ -114,6 +142,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/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`

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

@@ -7,6 +7,23 @@
 import type { ColumnTenancy } from "../tenancy.js";
 import type { SchemaHook, TableModel } from "../model.js";
 import { type AnyTable } from "../table.js";
+/**
+ * Reason from `global("reason")` on a view, when the view opted out.
+ *
+ * The reason is not a catalog field, so the catalog hash does not change.
+ *
+ * @param model - The view's query model
+ * @returns The reason, or `undefined` when the view is not global
+ */
+export declare function viewGlobalReason(model: object): string | undefined;
+/**
+ * Whether `query` names `name` as an identifier.
+ *
+ * @param query - Author SQL
+ * @param name - Table name, SQL or client
+ * @returns Whether the text mentions that name
+ */
+export declare function viewMentions(query: string, name: string): boolean;
 /** What `schema()` passes when it binds a view. */
 export type ViewInstall = (model: {
     [name: string]: TableModel;
@@ -18,12 +35,13 @@ export type ViewInstall = (model: {
  * @param columns - Declared output columns
  * @param query - Author SQL
  * @param tenancy - `global("reason")`, when the view opts out
+ * @param refresh - `plain` stores no `refresh`. A materialized view is `blocking` or `concurrently`
  * @returns Methods stored on the declaration
  */
 export declare function viewClient(name: string, columns: readonly {
     readonly name: string;
     readonly type: string;
-}[], query: string, tenancy: unknown): {
+}[], query: string, tenancy: unknown, refresh?: "plain" | "blocking" | "concurrently"): {
     readonly field: string;
     readonly install: ViewInstall;
     readonly hook: SchemaHook;

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

@@ -43,6 +43,8 @@ export type ViewDeclaration<N extends string = string, C extends readonly ViewCo
     readonly schema: string;
     /** Declared columns, for types only. `db.views` reads them. */
     readonly "~columns"?: C;
+    /** `"view"`. A materialized view is `"materialized"`, which adds `refresh()`. */
+    readonly "~kind": "view";
     /**
      * Catalog record for this declaration.
      *
@@ -87,6 +89,8 @@ export type MaterializedViewDeclaration<N extends string = string, C extends rea
     readonly schema: string;
     /** Declared columns, for types only. `db.views` reads them. */
     readonly "~columns"?: C;
+    /** `"materialized"`. `db.views` adds `refresh()` for this kind only. */
+    readonly "~kind": "materialized";
     /**
      * Catalog records for this declaration.
      *

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

@@ -1,197 +1,33 @@
+import {
+  viewClient
+} from "../../../shared/5e3tf63j.js";
 import {
   viewObject,
   materializedViewObject,
   materializedViewIndex
-} from "../../../shared/y005b761.js";
-import {
-  encodeUuid,
-  decodeUuid
-} from "../../../shared/dyj86cmj.js";
-import {
-  snakeCase
-} from "../../../shared/ntneex2a.js";
-import {
-  encodeText,
-  decodeText
-} from "../../../shared/4m9fn52z.js";
+} from "../../../shared/zy8r7qvz.js";
 import {
   staticNamespace2
-} from "../../../shared/t4tbsy9h.js";
+} from "../../../shared/358zsv4r.js";
 import {
   OkmError2
 } from "../../../shared/52szzakm.js";
 
-// src/dialects/pg/view/client.ts
-function viewClient(name, columns, query, tenancy) {
-  const field = camelCase(name);
-  const marked = readGlobal(name, tenancy);
-  return {
-    field,
-    install(model, scope, tables, casing, scoped) {
-      if (Object.hasOwn(model, field)) {
-        throw new OkmError2("OKM1023", `View ${name} uses the client name ${field}.`, {
-          fix: { summary: "Give the view a name that no table uses." }
-        });
-      }
-      const exposes = exposesKey(columns, scope);
-      if (scope !== undefined && readsTenant(query, tables, casing, scoped)) {
-        if (!exposes && marked === undefined) {
-          throw new OkmError2("OKM1820", `View ${name} reads a tenant table and does not expose ${scope.key}.`, {
-            fix: {
-              summary: "Expose the tenant key so the predicate can be applied, or declare global(reason)."
-            }
-          });
-        }
-        if (exposes) {
-          scope.scopeView(field);
-          scoped.add(name);
-        }
-      }
-      model[field] = {
-        name: field,
-        sql: name,
-        primary: [],
-        uniques: [],
-        columns: columnModels(columns, scope),
-        relations: []
-      };
-    },
-    hook(target, ctx) {
-      publish(field, target, ctx);
-    }
-  };
-}
-function publish(field, target, ctx) {
-  if (ctx.tables === undefined || ctx.table !== undefined)
-    return;
-  const handle = ctx.tables[field];
-  if (typeof handle !== "object" || handle === null)
-    return;
-  const source = handle;
-  const views = target.views;
-  const map = typeof views === "object" && views !== null ? views : {};
-  map[field] = {
-    find: source.find,
-    one: source.one,
-    count: source.count,
-    exists: source.exists
-  };
-  target.views = map;
-  delete ctx.tables[field];
-  delete target[field];
-}
-function columnModels(columns, tenancy) {
-  const seen = new Set;
-  const models = [];
-  for (const column of columns) {
-    const field = fieldName(column.name, tenancy);
-    if (seen.has(field)) {
-      throw new OkmError2("OKM1020", `View column ${column.name} repeats ${field}.`, {
-        fix: { summary: "Declare each output column once." }
-      });
-    }
-    seen.add(field);
-    const uuid = column.type.toLowerCase() === "uuid";
-    const key = tenancy !== undefined && field === tenancy.key;
-    models.push({
-      field,
-      sql: column.name,
-      dataType: column.type,
-      encode: uuid ? (value) => encodeUuid(textValue(value)) : (value) => encodeText(textValue(value)),
-      decode: uuid ? decodeUuid : decodeText,
-      hidden: false,
-      sensitive: false,
-      guarded: key,
-      writable: false,
-      guardUpdate: false
-    });
-  }
-  return models;
-}
-function exposesKey(columns, tenancy) {
-  if (tenancy === undefined)
-    return false;
-  return columns.some((column) => fieldName(column.name, tenancy) === tenancy.key);
-}
-function readsTenant(query, tables, casing, scoped) {
-  for (const name of scoped) {
-    if (mentions(query, name))
-      return true;
-  }
-  for (const table of tables) {
-    const mark = table.options?.tenancy;
-    if (isGlobalMark(mark))
-      continue;
-    const sql = casing === "snake" ? snakeCase(table.name) : table.name;
-    if (mentions(query, sql) || mentions(query, table.name))
-      return true;
-  }
-  return false;
-}
-function readGlobal(name, tenancy) {
-  if (tenancy === undefined)
-    return;
-  if (!isGlobalMark(tenancy)) {
-    throw new OkmError2("OKM1020", `View ${name} tenancy must be global("reason").`, {
-      fix: { summary: 'Pass global("reason") from okmodel/tenancy, or omit tenancy.' }
-    });
-  }
-  return tenancy.reason;
-}
-function isGlobalMark(value) {
-  if (typeof value !== "object" || value === null)
-    return false;
-  const record = value;
-  return record.kind === "global" && typeof record.reason === "string" && record.reason.trim().length > 0;
-}
-function fieldName(column, tenancy) {
-  const field = camelCase(column);
-  if (tenancy !== undefined && (column === tenancy.key || field === tenancy.key))
-    return tenancy.key;
-  return field;
-}
-function camelCase(name) {
-  let out = "";
-  let upper = false;
-  for (const char of name) {
-    if (char === "_") {
-      upper = out.length > 0;
-      continue;
-    }
-    out += upper ? char.toUpperCase() : char;
-    upper = false;
-  }
-  return out;
-}
-function mentions(query, name) {
-  let pattern = '(^|[^A-Za-z0-9_])"?';
-  for (const char of name) {
-    if ("\\^$[]().*+?|{}".includes(char))
-      pattern += "\\";
-    pattern += char;
-  }
-  pattern += '"?(?![A-Za-z0-9_])';
-  return new RegExp(pattern).test(query);
-}
-function textValue(value) {
-  if (typeof value !== "string") {
-    throw new OkmError2("OKM1121", "A view column value must be text.", {
-      fix: { summary: "Pass a string." }
-    });
-  }
-  return value;
-}
-
 // src/dialects/pg/view/index.ts
 function view(name, options) {
   const schema = options.schema ?? "public";
   const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
   const query = bodyText(options.query);
-  const bound = viewClient(name, options.columns, query, options.tenancy);
+  const bound = viewClient(name, options.columns, query, options.tenancy, "plain");
+  let securityInvoker = false;
   return {
     name,
     schema,
-    install: bound.install,
+    "~kind": "view",
+    install(model, tenancy, tables, casing, scoped) {
+      bound.install(model, tenancy, tables, casing, scoped);
+      securityInvoker = tenancy?.strategy === "rls" && scoped.has(name);
+    },
     hook: bound.hook,
     contribute(peers, built) {
       assertPeers(peers);
@@ -203,7 +39,8 @@ function view(name, options) {
           name,
           columns,
           query,
-          provenance
+          provenance,
+          ...securityInvoker ? { securityInvoker: true } : {}
         })
       ];
     }
@@ -213,7 +50,12 @@ function materializedView(name, options) {
   const schema = options.schema ?? "public";
   const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
   const query = bodyText(options.query);
-  const bound = viewClient(name, options.columns, query, options.tenancy);
+  if (options.refresh !== undefined && options.refresh !== "concurrently") {
+    throw new OkmError2("OKM1120", `Materialized view ${name} refresh must be "concurrently".`, {
+      fix: { summary: 'Omit refresh, or pass refresh: "concurrently" with a unique index.' }
+    });
+  }
+  const bound = viewClient(name, options.columns, query, options.tenancy, options.refresh === "concurrently" ? "concurrently" : "blocking");
   const indexes = options.indexes ?? [];
   if (options.refresh === "concurrently" && !indexes.some((index) => index.unique === true)) {
     throw new OkmError2("OKM1822", `Materialized view ${name} refreshes concurrently and has no unique index.`, { fix: { summary: "Add a unique index, or refresh without CONCURRENTLY." } });
@@ -229,6 +71,7 @@ function materializedView(name, options) {
   return {
     name,
     schema,
+    "~kind": "materialized",
     install: bound.install,
     hook: bound.hook,
     contribute(peers, built) {

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

@@ -0,0 +1,24 @@
+/**
+ * `REFRESH MATERIALIZED VIEW` for one view handle.
+ *
+ * Loaded the first time `refresh()` runs. A featureless app, and an app that
+ * never calls it, do not import this module. The name is unqualified so the
+ * session `search_path` selects the schema, matching a view `find`.
+ */
+/**
+ * Refreshes one materialized view on the primary.
+ *
+ * `CONCURRENTLY` when the declaration asked for it. The statement timeout is
+ * the client's, the same ceiling a write uses. A database failure is mapped
+ * and logged like any other statement.
+ *
+ * The refresh runs on a reserved primary connection with `app.unscoped` set
+ * in that same transaction. Under `FORCE ROW LEVEL SECURITY` the owner would
+ * otherwise refresh zero rows. `CONCURRENTLY` cannot run inside a transaction,
+ * so that form sets the session value and clears it before release.
+ *
+ * @param session - Pool, timeout, and logger from the client
+ * @param name - SQL name of the materialized view
+ * @param concurrently - True when the view declares `refresh: "concurrently"`
+ */
+export declare function refreshView(session: object, name: string, concurrently: boolean): Promise<void>;