okmodel 0.5.1 → 0.6.0

package/dist/tooling/migrate/index.js

@@ -1,26 +1,27 @@
-import"../../shared/krxx77g0.js";
-import"../../shared/8bwbwy8h.js";
+import"../../shared/wkme6tep.js";
+import"../../shared/qq3899ht.js";
 import"../../shared/n442h54c.js";
 import {
   applyTarget2,
   backfillTiming2
-} from "../../shared/cctw17hj.js";
+} from "../../shared/nx9hh281.js";
 import {
-  loadMigrations,
-  loadHeadSnapshot,
   readReference
-} from "../../shared/gde73es6.js";
-import"../../shared/szm0cksa.js";
-import"../../shared/fancm5pt.js";
+} from "../../shared/p248q79y.js";
+import"../../shared/knmes2kh.js";
+import"../../shared/vjpnzwjz.js";
 import {
+  projectPath,
+  loadMigrations,
+  loadHeadSnapshot,
   loadBuiltSchema,
   loadConfig
-} from "../../shared/qv2ydck9.js";
+} from "../../shared/t3g0k88x.js";
 import {
   assertTargetPolicy,
   selectTarget
-} from "../../shared/ga3sfy93.js";
-import"../../shared/8xsbagad.js";
+} from "../../shared/ttmg09vd.js";
+import"../../shared/9s0ypp87.js";
 import {
   OkmError2
 } from "../../shared/52szzakm.js";
@@ -30,12 +31,11 @@ function defineConfig(config) {
   return config;
 }
 // src/tooling/migrate/provision.ts
-import { join } from "node:path";
 async function provision(target, cwd = process.cwd()) {
   const config = await loadConfig(cwd);
   const selected = selectTarget(config, target);
   assertTargetPolicy(selected, "provision");
-  const directory = join(cwd, config.migrations ?? "migrations");
+  const directory = projectPath(cwd, config.migrations ?? "migrations");
   const migrations = loadMigrations(directory);
   const head = loadHeadSnapshot(directory);
   if (head === undefined) {
@@ -58,7 +58,7 @@ async function provision(target, cwd = process.cwd()) {
       reference: readReference(built.tables, built.casing, head.catalog),
       only: true
     },
-    ...config.roles !== undefined ? { migrationRole: config.roles.migration } : {},
+    ...config.roles !== undefined ? { migrationRole: config.roles.migration, appRole: config.roles.app } : {},
     lintDirectory: directory
   });
   if (report.applied.length === 0)

package/dist/tooling/migrate/lint.d.ts

@@ -8,7 +8,7 @@
 import type { Catalog } from "../../contracts/catalog/types.js";
 import { OkmError } from "../../contracts/error.js";
 import { type LintSeverity } from "./lint-rules.js";
-import { type MigrationPlan } from "./plan.js";
+import type { MigrationPlan } from "./plan.js";
 /** One finding. `place` is `step N`, `step N statement M`, or `table.column`. */
 export type Finding = {
     readonly severity: LintSeverity;

package/dist/tooling/migrate/lost.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A session that dies in the middle of a command.
+ *
+ * A commit that was sent and never answered stays OKM1401. Every other
+ * dropped connection is unavailable. Cleanup that throws is ignored so the
+ * original failure is the one the command reports.
+ */
+import { OkmError } from "../../contracts/error.js";
+/**
+ * Maps a lost session to unavailable or OKM1401.
+ *
+ * An {@link OkmError} that already has one of those kinds is returned. An
+ * `invalid` error whose cause is a lost session keeps its message and takes
+ * that kind. Anything else returns `undefined`.
+ *
+ * @param error - Caught value
+ * @returns The session failure, or `undefined` when this is some other error
+ */
+export declare function sessionFailure(error: unknown): OkmError | undefined;
+/**
+ * Runs cleanup and ignores its failure.
+ *
+ * A dead session must not replace the error the command is already reporting,
+ * and it must not leave the process waiting on that session.
+ *
+ * @param run - Close, release, or unlock
+ */
+export declare function finishQuiet(run: () => Promise<unknown>): Promise<void>;

package/dist/tooling/migrate/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Config paths resolved against the project directory.
+ */
+/**
+ * Resolves a config path against `cwd`.
+ *
+ * An absolute segment stays absolute. A relative segment, including `..`,
+ * is resolved from `cwd`.
+ *
+ * @param cwd - Project directory
+ * @param parts - `schema`, `tables`, `migrations`, `out`, a seed file, or a child
+ * @returns An absolute path
+ */
+export declare function projectPath(cwd: string, ...parts: readonly string[]): string;

package/dist/tooling/migrate/plan.d.ts

@@ -128,9 +128,12 @@ export declare function formatPlan(plan: MigrationPlan, lockText?: (step: PlanSt
 /**
  * Reads a plan written by {@link formatPlan}.
  *
- * A blank line ends a step. A blank line inside a quote, a dollar quote, or
- * a block comment stays in that step, and so does a `--` line while the
- * quote is still open.
+ * A blank line ends a step. A blank line inside a quote, a dollar quote, a
+ * block comment, or a `BEGIN ATOMIC` routine body stays in that step, and so
+ * does a `--` line while that quote or body is still open.
+ *
+ * `\r\n` and a lone `\r` are read as `\n`. A leading UTF-8 BOM is stripped.
+ * UTF-16 is refused.
  *
  * @param text - SQL file text
  * @returns The plan. The header class is kept when the file has no steps

package/dist/tooling/migrate/runner.d.ts

@@ -95,7 +95,32 @@ export declare function assumeRole(connection: DriverConnection, role: string, s
  * @param schema - Schema the migration writes
  * @param role - Role that was just created
  */
+/**
+ * Grants the application role `SELECT` on `okm_meta`.
+ *
+ * No other privilege. When the session has `SET ROLE`, the grant runs as
+ * the session user and the role is restored. A second apply grants the
+ * same privilege again.
+ *
+ * @param connection - Reserved connection
+ * @param role - Application role. Omitted when the config names none
+ * @param session - Role the runner already assumed
+ */
+export declare function grantAppMeta(connection: DriverConnection, role: string | undefined, session: {
+    setRole?: string;
+}): Promise<void>;
 export declare function grantSchema(connection: DriverConnection, schema: string, role: string): Promise<void>;
+/**
+ * Fails when `GRANT USAGE ON SCHEMA` did not add the role.
+ *
+ * Postgres warns and changes nothing when the acting role does not own the
+ * schema. A later check then reports the grant forever. The migration role
+ * has to own the schema first.
+ *
+ * @param connection - Reserved connection, in the grant's transaction
+ * @param sql - The statement that just ran
+ */
+export declare function assertSchemaUsageLanded(connection: DriverConnection, sql: string): Promise<void>;
 /**
  * Reports whether Postgres refuses to run `sql` inside a transaction.
  *

package/dist/tooling/migrate/sandbox.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Replays `okm migrate check` inside one transaction and rolls it back.
+ *
+ * The scratch schema is created in that transaction. Nothing here updates a
+ * system catalog or a real ACL. A step that cannot run in a transaction is
+ * rewritten to the transactional form, or skipped and named.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { MigrateConfig } from "./config.js";
+import { type MigrationPlan, type PlanStep } from "./plan.js";
+/** One migration the check replays. */
+export type CheckMigration = {
+    readonly id: string;
+    readonly catalog: Catalog;
+    readonly steps: readonly PlanStep[];
+};
+/** The first migration whose replay does not match its catalog. */
+export type ReplayStop = {
+    readonly index: number;
+    readonly back: MigrationPlan;
+};
+/** Replay result. `skips` are statements check did not execute. */
+export type ReplayOutcome = {
+    readonly skips: readonly string[];
+    readonly stop?: ReplayStop;
+};
+/**
+ * Replays `history` in one transaction and rolls it back.
+ *
+ * @param url - Target URL
+ * @param scratch - Schema created inside the transaction
+ * @param config - Roles and timeouts
+ * @param allowPooler - Passed through to the pooler guard
+ * @param history - Migrations in apply order
+ * @returns Skipped statements, and the first catalog mismatch
+ */
+export declare function replayCheckHistory(url: string, scratch: string, config: MigrateConfig, allowPooler: boolean, history: readonly CheckMigration[]): Promise<ReplayOutcome>;
+/**
+ * Compares a head snapshot with a full replay. Both run in rolled-back transactions.
+ *
+ * @param url - Target URL
+ * @param provided - Scratch schema for the snapshot
+ * @param replayed - Scratch schema for the history
+ * @param config - Roles and timeouts
+ * @param allowPooler - Passed through to the pooler guard
+ * @param history - Migrations in apply order
+ * @returns The difference, or `undefined` when the catalogs match
+ */
+export declare function proveCheckSnapshot(url: string, provided: string, replayed: string, config: MigrateConfig, allowPooler: boolean, history: readonly CheckMigration[]): Promise<string | undefined>;
+/**
+ * Rewrites `"public".` to the scratch schema.
+ *
+ * @param steps - Plan steps
+ * @param schema - Scratch schema
+ * @returns The same steps, aimed at `schema`
+ */
+export declare function retargetSteps(steps: readonly PlanStep[], schema: string): readonly PlanStep[];

package/dist/tooling/migrate/sql-lex.d.ts

@@ -6,8 +6,11 @@
  * quote, and `''` is one quote inside it. `E'...'` still treats a backslash
  * as an escape. A dollar quote runs until the same tag; a different tag
  * inside it is text, so `$outer$ ... $inner$ ... $inner$ ... $outer$` stays
- * one span. An unterminated string, quoted identifier, block comment, or
- * dollar quote is one opaque tail. This function does not throw.
+ * one span. A `BEGIN ATOMIC` body of `CREATE FUNCTION` or `CREATE PROCEDURE`
+ * stays in that statement: a semicolon inside it does not split, and
+ * `CASE ... END` does not close the body. `BEGIN ATOMIC` elsewhere still
+ * splits. An unterminated string, quoted identifier, block comment, dollar
+ * quote, or atomic body is one opaque tail. This function does not throw.
  */
 /** Statements of `sql`, comments removed, with no trailing semicolon. */
 export declare function sqlStatements(sql: string): readonly string[];
@@ -15,8 +18,22 @@ export declare function sqlStatements(sql: string): readonly string[];
  * Whether `sql` still has an open quote or block comment.
  *
  * A line comment does not count: it ends at the newline or at the end.
+ * An unclosed `BEGIN ATOMIC` routine body counts too.
  *
  * @param sql - Step text accumulated so far
- * @returns `true` when a later blank line is still inside that quote
+ * @returns `true` when a later blank line is still inside that quote or body
  */
 export declare function sqlQuoteOpen(sql: string): boolean;
+/**
+ * Transaction control in a migration step.
+ *
+ * Dollar-quoted bodies are scanned only for a `DO` block. `CREATE FUNCTION`
+ * and `CREATE PROCEDURE` may commit inside their own body. A `BEGIN ATOMIC`
+ * body stays one statement, so its `END` is not transaction control. A bare
+ * `BEGIN` or `END` inside a `DO` body is plpgsql and is ignored. `ROLLBACK TO`
+ * does not end the outer transaction.
+ *
+ * @param sql - Step text
+ * @returns The command, or `undefined` when the step stays in one transaction
+ */
+export declare function transactionControl(sql: string): string | undefined;

package/dist/tooling/migrate/text.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Migration file text before it is parsed.
+ *
+ * Line endings and a UTF-8 BOM are normalized here, once, so every reader
+ * sees the same plan. UTF-16 is refused. The kind stays `invalid`.
+ */
+import { OkmError } from "../../contracts/error.js";
+/** Why a migration file was refused before it was applied. */
+export type MigrationTextReason = "no-steps" | "utf16";
+/**
+ * A migration file this version will not apply.
+ *
+ * `reason` is `no-steps` or `utf16`. The kind stays `invalid`.
+ */
+export declare class MigrationTextError extends OkmError {
+    /** Which check refused the file. */
+    readonly reason: MigrationTextReason;
+    /**
+     * @param reason - Which check failed
+     * @param message - What the author should change
+     */
+    constructor(reason: MigrationTextReason, message: string);
+}
+/**
+ * Strips a UTF-8 BOM and turns `\r\n` and a lone `\r` into `\n`.
+ *
+ * @param text - File text
+ * @param label - File name used when the text is UTF-16
+ * @returns Text `parsePlan` can split on `\n`
+ */
+export declare function prepareMigrationText(text: string, label?: string): string;
+/**
+ * Refuses a non-empty file that produced no steps and has no `-- no steps` line.
+ *
+ * An intentional empty plan from `formatPlan` carries that line.
+ * Anything else would apply as "nothing to apply" and skip the linter.
+ *
+ * @param text - Text already passed through {@link prepareMigrationText}
+ * @param stepCount - Steps the parser returned
+ * @param label - File name in the error
+ */
+export declare function assertMigrationSteps(text: string, stepCount: number, label: string): void;

package/dist/tooling/node-version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Node version `okm` needs in order to load `okmodel.config.ts`.
+ *
+ * Node 22.18 unflags type stripping. Bun loads TypeScript itself, so the
+ * check does not apply when `bun --bun` is the runtime.
+ */
+/**
+ * Whether `version` can strip types in a `.ts` config.
+ *
+ * @param version - `process.version`, such as `v22.18.0`
+ * @returns `true` for Node 22.18 and every newer major
+ */
+export declare function nodeSupportsConfigTypes(version: string): boolean;
+/**
+ * Startup text when this process cannot load a TypeScript config.
+ *
+ * @param version - `process.version`
+ * @param bunRuntime - `true` when Bun is running the process
+ * @returns The stderr line, or `undefined` when the process can continue
+ */
+export declare function nodeStartupMessage(version: string, bunRuntime: boolean): string | undefined;

package/dist/tooling/testing/facts.d.ts

@@ -2,9 +2,9 @@
  * What a factory needs from a compiled schema: required columns, foreign keys,
  * and which tables are tenant or global.
  *
- * Column tenancy is the only strategy in this version. A table is tenant when
- * its predicate binds a scope, and global when `global("reason")` opted it out.
- * `schemaPerTenant` and `databasePerTenant` are not in 0.4.
+ * A table is tenant when its predicate binds a scope, and global when
+ * `global("reason")` opted it out. Composite and path use that probe.
+ * `schemaPerTenant` and `databasePerTenant` are not in this version.
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import type { QuerySchema, RelationModel } from "../../dialects/pg/model.js";
@@ -46,6 +46,25 @@ export type TableFacts = {
     /** `global("reason")`. Absent on a tenant table and on a schema with no tenancy. */
     readonly globalReason: string | undefined;
 };
+/** One view or materialized view. Isolation reads it; it does not insert into it. */
+export type ViewFacts = {
+    /** Client name, camelCase. */
+    readonly name: string;
+    /** SQL name. */
+    readonly sql: string;
+    readonly kind: "view" | "materializedView";
+    /** Author SQL. */
+    readonly query: string;
+    readonly columns: readonly {
+        readonly field: string;
+        readonly dataType: string;
+        readonly guarded: boolean;
+    }[];
+    /** The predicate binds a scope. A global view is not tenant. */
+    readonly tenant: boolean;
+    /** `global("reason")` on the view. Absent when the view is not global. */
+    readonly globalReason: string | undefined;
+};
 /**
  * Scope value used to ask a tenancy object whether a table is tenant.
  *
@@ -56,13 +75,22 @@ export declare const tenantProbe = "00000000-0000-4000-8000-000000000001";
 /**
  * Reads every table in declaration order.
  *
- * Views and materialized views are in the query model too. They have no rows
- * of their own to insert, so they are left out.
+ * Views are read by {@link readViews}. They are not tables, so they are left out here.
  *
  * @param schema - Compiled schema
  * @returns One facts object per table
  */
 export declare function readFacts(schema: TestingSchema): readonly TableFacts[];
+/**
+ * Reads every view and materialized view in model order.
+ *
+ * A global view is not tenant. The reason comes from the view declaration,
+ * which is not stored on the catalog.
+ *
+ * @param schema - Compiled schema
+ * @returns One facts object per view
+ */
+export declare function readViews(schema: TestingSchema): readonly ViewFacts[];
 /**
  * A column the factory must set when the definition and the overrides omit it.
  *

package/dist/tooling/testing/index.d.ts

@@ -72,7 +72,7 @@ export type Testing<S extends TestingSchema = TestingSchema> = {
     /**
      * Runs the cross-tenant check.
      *
-     * @returns Checked tenant tables and skipped global tables
+     * @returns Checked tenant tables and views, and skipped global objects
      */
     isolation(): Promise<IsolationReport>;
     /** Closes the client and the pool. */

package/dist/tooling/testing/index.js

@@ -1,8 +1,8 @@
 import {
   testing2
-} from "../../shared/v36c5g6p.js";
-import"../../shared/8xsbagad.js";
-import"../../shared/8bwbwy8h.js";
+} from "../../shared/8x72s86k.js";
+import"../../shared/9s0ypp87.js";
+import"../../shared/qq3899ht.js";
 export {
   testing2 as testing
 };

package/dist/tooling/testing/isolation.d.ts

@@ -5,15 +5,21 @@
  * writes as tenant A against that row's key. A returned row, or an update or
  * delete that touches it, is a leak. The row is deleted afterwards. Global
  * tables are skipped and listed.
- * Column tenancy is the strategy this version has. A table is tenant when its
- * predicate says so (D199).
+ * A table is tenant when its predicate says so (D199). Composite tenancy changes
+ * one key at a time. A path table is checked through a parent that belongs to
+ * tenant B.
+ * Tenant views and materialized views are read the same way. The rows are
+ * inserted into the underlying tables, never into the view. A global view is
+ * skipped and listed with its `global("reason")`.
  */
 import { type FactoryHost } from "./factories.js";
-/** What {@link isolation} checked, and the global tables it skipped. */
+/** What {@link isolation} checked, and the global objects it skipped. */
 export type IsolationReport = {
     /** Tenant tables whose queries stayed inside tenant A. */
     readonly checked: readonly string[];
-    /** Global tables, with the reason from `global("reason")`. */
+    /** Tenant views and materialized views whose reads stayed inside tenant A. */
+    readonly views: readonly string[];
+    /** Global tables and views, with the reason from `global("reason")`. */
     readonly skipped: readonly {
         readonly table: string;
         readonly reason: string;
@@ -26,6 +32,6 @@ export type IsolationReport = {
  * already inserted is not reused as tenant B's row.
  *
  * @param host - The open harness
- * @returns The tables that were checked and the global tables that were not
+ * @returns The tables and views that were checked, and the global objects that were not
  */
 export declare function isolation(host: FactoryHost): Promise<IsolationReport>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okmodel",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "okmodel is a catalog-first TypeScript ORM, PostgreSQL first.",
   "keywords": [
     "migrations",
@@ -142,6 +142,9 @@
     "bench": "bun ./packages/bench/src/run.ts",
     "catalog-bench": "bun ./scripts/catalog-bench.ts",
     "attest": "ATTEST_shouldFormat=0 ATTEST_updateSnapshots=0 bun ./packages/attest/src/measure.bench.ts",
+    "site:dev": "bun --cwd site dev",
+    "site:build": "bun --cwd site build",
+    "site:check": "bun --cwd site check",
     "publish:dry": "bun publish --dry-run",
     "prepublishOnly": "bun run build"
   },
@@ -178,6 +181,6 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.18"
   }
 }