okmodel 0.5.1 → 0.7.0

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/7k9grvf6.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.7.0",
   "description": "okmodel is a catalog-first TypeScript ORM, PostgreSQL first.",
   "keywords": [
     "migrations",
@@ -126,6 +126,7 @@
     "compiler-api": "bun ./scripts/compiler-api.ts",
     "publint": "publint run . --strict --pack bun",
     "attw": "bun ./scripts/attw.ts",
+    "pack-tracked": "bun ./scripts/pack-tracked.ts",
     "prepack": "bun ./scripts/strip-workspaces.ts strip",
     "postpack": "bun ./scripts/strip-workspaces.ts restore",
     "size": "bun ./scripts/size.ts",
@@ -134,7 +135,7 @@
     "test:postgres": "bun ./scripts/postgres-suite.ts",
     "test:tarball": "bun ./scripts/tarball-smoke.ts",
     "verify": "bun ./scripts/verify.ts",
-    "check": "bun run format:check && bun run lint && bun run typecheck && bun run editor-check && bun run type-cost && bun run layers-check && bun run core-purity && bun run okid-drift && bun run docs:check && bun run readme:check && bun run compiler-api && bun run bundle-purity && bun run build && bun test && bun run test:runtimes && bun run publint && bun run attw && bun run size",
+    "check": "bun run format:check && bun run lint && bun run typecheck && bun run editor-check && bun run type-cost && bun run layers-check && bun run core-purity && bun run okid-drift && bun run docs:check && bun run readme:check && bun run compiler-api && bun run bundle-purity && bun run build && bun test && bun run test:runtimes && bun run publint && bun run attw && bun run pack-tracked && bun run size",
     "bump": "bun ./scripts/bump-version.ts",
     "release-check": "bun ./scripts/release-check.ts",
     "db:up": "bun ./packages/harness/src/docker-cli.ts up",
@@ -142,6 +143,10 @@
     "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",
+    "dev": "bun run site:dev",
+    "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 +183,6 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.18"
   }
 }

package/dist/shared/7m88x3e9.js

@@ -1,45 +0,0 @@
-// src/runtime/trait-read.ts
-function touchFields(model) {
-  const traits = model.traits;
-  if (traits === undefined)
-    return;
-  const names = [];
-  for (const trait of traits) {
-    const touch = trait.touch;
-    if (touch === undefined)
-      continue;
-    for (const field of touch)
-      names.push(field);
-  }
-  return names.length === 0 ? undefined : names;
-}
-function fieldSealed(model, field) {
-  const traits = model.traits;
-  if (traits === undefined)
-    return false;
-  for (const trait of traits) {
-    const sealed = trait.sealed;
-    if (sealed === undefined)
-      continue;
-    for (const name of sealed)
-      if (name === field)
-        return true;
-  }
-  return false;
-}
-function sealingTrait(model, field) {
-  const traits = model.traits;
-  if (traits === undefined)
-    return;
-  for (const trait of traits) {
-    const sealed = trait.sealed;
-    if (sealed === undefined)
-      continue;
-    for (const name of sealed)
-      if (name === field)
-        return trait.name;
-  }
-  return;
-}
-
-export { touchFields, fieldSealed, sealingTrait };