okmodel 0.5.1 → 0.7.0

package/dist/shared/z7s6fpxv.js

@@ -0,0 +1,62 @@
+import {
+  OkmError2
+} from "./52szzakm.js";
+
+// src/dialects/pg/view/refresh.ts
+async function refreshView(session, name, concurrently) {
+  const host = asHost(session);
+  await host.connected;
+  const timeout = host.timeouts?.statement;
+  const options = timeout === undefined ? undefined : { timeout };
+  const text = `refresh materialized view${concurrently ? " concurrently" : ""} ${quote(name)}`;
+  const connection = await host.pool.reserve?.();
+  if (connection === undefined) {
+    throw new OkmError2("OKM1111", "Refresh needs a driver that can reserve a connection.", {
+      fix: { summary: "Use a Postgres driver that supports interactive transactions." }
+    });
+  }
+  try {
+    if (concurrently) {
+      await connection.execute("select set_config('app.unscoped', 'on', false)");
+      try {
+        await connection.execute(text, undefined, options);
+      } finally {
+        await connection.execute("select set_config('app.unscoped', '', false)").catch(() => {
+          return;
+        });
+      }
+      return;
+    }
+    await connection.execute("begin");
+    try {
+      await connection.execute("select set_config('app.unscoped', 'on', true)");
+      await connection.execute(text, undefined, options);
+      await connection.execute("commit");
+    } catch (error) {
+      await connection.execute("rollback").catch(() => {
+        return;
+      });
+      throw error;
+    }
+  } catch (error) {
+    const { mapPostgresError } = await import("./63qtkrca.js");
+    const mapped = mapPostgresError(error, {
+      ...host.http !== undefined ? { http: host.http } : {},
+      ...host.includeValues === true ? { includeValues: true } : {},
+      ...host.schema !== undefined ? { schema: host.schema } : {}
+    });
+    host.logger?.error?.({ code: mapped.code, summary: mapped.summary });
+    throw mapped;
+  } finally {
+    await connection.release();
+  }
+}
+function asHost(session) {
+  return session;
+}
+function quote(name) {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+export {
+  refreshView
+};

package/dist/shared/{n7mcc1gk.js → zchaghkf.js}

@@ -18,6 +18,7 @@ var FAMILIES = {
   hasAnyKey: ["jsonb"],
   path: ["json", "jsonb"],
   matches: ["tsvector"],
+  relevance: ["tsvector"],
   "json.set": ["json", "jsonb"],
   "arr.append": ["array"],
   "arr.remove": ["array"]
@@ -53,7 +54,7 @@ var ACCEPTED = {
   jsonb: ["eq", "not", "contains", "containedBy", "hasKey", "hasAnyKey", "path", "json.set"],
   json: ["eq", "not", "path", "json.set"],
   range: ["eq", "not", "lt", "lte", "gt", "gte", "contains", "containedBy", "overlaps"],
-  tsvector: ["eq", "not", "matches"],
+  tsvector: ["eq", "not", "matches", "relevance"],
   scalar: ["eq", "not", "lt", "lte", "gt", "gte", "between", "inList", "notIn", "inc"]
 };
 var SAFE_TYPE = /^[A-Za-z_][A-Za-z0-9_]*(\(\d+\))?(\[\])*$/;
@@ -81,7 +82,7 @@ function assertOperatorFits(column, name) {
   if (families.includes(columnFamily(column.dataType)))
     return;
   const accepted = ACCEPTED[columnFamily(column.dataType)];
-  const search = name === "matches" && columnFamily(column.dataType) === "text" ? " Text search needs a tsvector column." : "";
+  const search = (name === "matches" || name === "relevance") && columnFamily(column.dataType) === "text" ? " Search needs a column built for search, not a plain text column." : "";
   throw new OkmError2("OKM1124", `Operator ${name} does not apply to ${column.dataType} column ${column.field}. Accepted operators: ${accepted.join(", ")}.${search}`, { fix: { summary: `Use one of: ${accepted.join(", ")}.` } });
 }
 function sqlType(dataType, column) {
@@ -110,7 +111,7 @@ function assertBoundText(value, role) {
 }
 function assertRegconfig(config) {
   if (!REGCONFIG.test(config)) {
-    throw new OkmError2("OKM1122", `Text search config ${config} must be a regconfig name such as english or pg_catalog.simple.`, { fix: { summary: "Pass a regconfig name. Quotes and extra clauses are not accepted." } });
+    throw new OkmError2("OKM1122", `Language ${config} is not a text search language. Pass a name such as english.`, { fix: { summary: "Pass a language name such as english." } });
   }
 }
 function textArray(values, role) {

package/dist/shared/{9m80mkac.js → ze4hxsmy.js}

@@ -1,6 +1,6 @@
 import {
   ColumnBuilder2
-} from "./c9z5g0fm.js";
+} from "./ywr8hmey.js";
 import {
   definition
 } from "./tmbdywx0.js";

package/dist/shared/zm0ptry0.js

@@ -0,0 +1,40 @@
+import {
+  isConnectionLost
+} from "./cnkky55j.js";
+import {
+  rejectClosed
+} from "./kb2sdhfb.js";
+
+// src/adapters/pg/reserved.ts
+var RESET_ALL = "RESET ALL";
+var UNLOCK = "SELECT pg_advisory_unlock_all()";
+async function resetSession2(depth, run) {
+  if (depth > 0)
+    await run("ROLLBACK").catch(() => {
+      return;
+    });
+  try {
+    await run(RESET_ALL);
+    await run(UNLOCK);
+  } catch {
+    await run("ROLLBACK").catch(() => {
+      return;
+    });
+    await run(RESET_ALL);
+    await run(UNLOCK);
+  }
+}
+async function resetQueried2(session) {
+  await resetSession2(session.inTransaction() ? 1 : 0, (text) => text === "ROLLBACK" ? session.rollback() : session.query(text, undefined, undefined));
+}
+function refuseWhenLost2(lost, run) {
+  if (lost.on)
+    return rejectClosed();
+  return run().catch((error) => {
+    if (isConnectionLost(error))
+      lost.on = true;
+    throw error;
+  });
+}
+
+export { resetSession2, resetQueried2, refuseWhenLost2 };

package/dist/shared/{nsva2a6b.js → znm0bpp5.js}

@@ -13,6 +13,9 @@ var RESERVED_PRESETS = new Set([
   "insert",
   "update",
   "delete",
+  "descendants",
+  "ancestors",
+  "sync",
   "archive",
   "restore",
   "withArchived",

package/dist/shared/zp9fmend.js

@@ -0,0 +1,145 @@
+import {
+  DriverError2
+} from "./cm3w0ywp.js";
+import {
+  armDriverError,
+  send,
+  connectClient
+} from "./w79hsckn.js";
+import {
+  resetSession2
+} from "./zm0ptry0.js";
+import {
+  cursorStream
+} from "./7kms6fvj.js";
+import {
+  isConnectionLost
+} from "./cnkky55j.js";
+import {
+  WireSession
+} from "./1qa0qajz.js";
+import {
+  rejectClosed,
+  runCall
+} from "./kb2sdhfb.js";
+
+// src/adapters/pg/nodepostgres-extra.ts
+async function checkout(held) {
+  const { pool, counters, named, isClosed } = held;
+  if (isClosed())
+    return rejectClosed();
+  const client = await connectClient(pool, held.acquireMs, counters);
+  counters.reserved += 1;
+  let lost = false;
+  const onError = () => {
+    lost = true;
+  };
+  const events = client;
+  events.on("error", onError);
+  const local = new Set;
+  const session = new WireSession((text, params) => {
+    const pending = send(client, text, params, named, client);
+    const guarded = pending.catch((error) => {
+      if (isConnectionLost(error) || lost) {
+        lost = true;
+        if (isConnectionLost(error))
+          throw error;
+        throw Object.assign(new DriverError2("CONNECTION_CLOSED", { cause: error }), {
+          code: "CONNECTION_CLOSED"
+        });
+      }
+      throw error;
+    });
+    guarded.cancel = () => {
+      pending.cancel?.();
+    };
+    return guarded;
+  }, held.notices, isClosed, true, () => {
+    counters.reservedBusy += 1;
+  }, () => {
+    counters.reservedBusy = Math.max(0, counters.reservedBusy - 1);
+  }, local);
+  const guard = (run) => lost ? rejectClosed() : run();
+  let released = false;
+  return {
+    execute: (text, params, options) => guard(() => runCall(isClosed(), options, (watch) => session.query(text, params, watch))),
+    batch: (statements, options) => guard(() => runCall(isClosed(), options, async (watch) => {
+      const { runAtomicBatch } = await import("./b76b8d95.js");
+      return runAtomicBatch(session, statements, watch);
+    })),
+    cancel() {
+      session.cancel();
+    },
+    async release() {
+      if (released)
+        return;
+      released = true;
+      try {
+        if (!lost)
+          await reset(session, client);
+      } finally {
+        counters.reserved = Math.max(0, counters.reserved - 1);
+        events.removeListener("error", onError);
+        client.release(lost);
+      }
+    }
+  };
+}
+async function reset(session, client) {
+  await resetSession2(session.depth(), (text) => client.query(text));
+}
+async function listen(held, channel, onNotify) {
+  const { pool, counters } = held;
+  const client = await connectClient(pool, held.acquireMs, counters);
+  counters.reserved += 1;
+  const quoted = quoteIdent(channel);
+  const onNotification = (message) => {
+    if (message.channel === channel)
+      onNotify(message.payload ?? "");
+  };
+  client.on("notification", onNotification);
+  let released = false;
+  const release = (dead) => {
+    if (released)
+      return;
+    released = true;
+    client.removeListener("notification", onNotification);
+    client.removeListener("error", release);
+    counters.reserved = Math.max(0, counters.reserved - 1);
+    client.release(Boolean(dead));
+  };
+  armDriverError(client, release);
+  try {
+    await client.query(`LISTEN ${quoted}`);
+  } catch (error) {
+    release(false);
+    throw error;
+  }
+  return async () => {
+    if (released)
+      return;
+    try {
+      await client.query(`UNLISTEN ${quoted}`);
+    } finally {
+      release(false);
+    }
+  };
+}
+function streamRows(checkout, text, params) {
+  return async function* () {
+    const connection = await checkout();
+    try {
+      yield* cursorStream((statement, values) => connection.execute(statement, values), text, params);
+    } finally {
+      await connection.release();
+    }
+  }();
+}
+function quoteIdent(name) {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+export {
+  checkout,
+  listen,
+  streamRows
+};

package/dist/shared/{y005b761.js → zy8r7qvz.js}

@@ -3,7 +3,7 @@ import {
   assertNamespace2,
   normaliseEdges,
   assertProvenance
-} from "./t4tbsy9h.js";
+} from "./358zsv4r.js";
 import {
   assertIdentifier2,
   fitIdentifier2,
@@ -23,7 +23,11 @@ function viewObject(input) {
   const query = readQuery(input.name, input.query);
   assertNamespace2(namespace);
   assertProvenance(input.provenance);
-  const definition = { columns, query };
+  const definition = {
+    columns,
+    query,
+    ...input.securityInvoker === true ? { securityInvoker: true } : {}
+  };
   return {
     kind: "view",
     identity: { kind: "view", namespace, name: input.name },

package/dist/tooling/cli.js

@@ -1,6 +1,6 @@
-import"../shared/8bwbwy8h.js";
+import"../shared/qq3899ht.js";
 import"../shared/n442h54c.js";
-import"../shared/krxx77g0.js";
+import"../shared/14vx95q4.js";
 import {
   formatFindings,
   hasError,
@@ -9,9 +9,11 @@ import {
   generateProject,
   planProject,
   checkProject
-} from "../shared/qv2ydck9.js";
-import"../shared/ga3sfy93.js";
-import"../shared/8xsbagad.js";
+} from "../shared/gs74dbj5.js";
+import {
+  sessionFailure
+} from "../shared/tsvww22q.js";
+import"../shared/9s0ypp87.js";
 import {
   OkmError2
 } from "../shared/52szzakm.js";
@@ -23,7 +25,7 @@ import { fileURLToPath } from "node:url";
 
 // src/tooling/migrate/commands.ts
 function formatFailure(error, verbose = false) {
-  const mapped = OkmError2.from(error);
+  const mapped = sessionFailure(error) ?? OkmError2.from(error);
   let text = `error ${mapped.code}: ${mapped.message}
 ${mapped.fix.summary}
 `;
@@ -71,12 +73,12 @@ async function run(argv, io) {
     return;
   }
   if (command === "dev") {
-    const { devProject } = await import("../shared/sdc7r2ww.js");
+    const { devProject } = await import("../shared/rs73fca9.js");
     stdout(await devProject(cwd));
     return;
   }
   if (command === "push") {
-    const { pushProject } = await import("../shared/q58y17hy.js");
+    const { pushProject } = await import("../shared/2shdbn8q.js");
     stdout(await pushProject(cwd, invoke(splitFlags(rest))));
     return;
   }
@@ -95,17 +97,17 @@ async function run(argv, io) {
       return;
     }
     if (sub === "apply") {
-      const { applyProject } = await import("../shared/q58y17hy.js");
+      const { applyProject } = await import("../shared/2shdbn8q.js");
       stdout(await applyProject(cwd, invoke(parsed), stdout));
       return;
     }
     if (sub === "status") {
-      const { statusProject } = await import("../shared/6mnp99hx.js");
+      const { statusProject } = await import("../shared/svncdeh5.js");
       stdout(await statusProject(cwd, invoke(parsed)));
       return;
     }
     if (sub === "check") {
-      const { checkMigrations } = await import("../shared/7zwwyh0v.js");
+      const { checkMigrations } = await import("../shared/wa07eas9.js");
       const provision = parsed.flags.includes("--provision") || rest.slice(1).includes("--provision");
       stdout(await checkMigrations(cwd, invoke(parsed), { provision }));
       return;
@@ -118,13 +120,13 @@ async function run(argv, io) {
         fix: { summary: "Pass okm seed <file>." }
       });
     }
-    const { seedProject } = await import("../shared/2pqx26h8.js");
+    const { seedProject } = await import("../shared/w72kgg4q.js");
     stdout(await seedProject(cwd, parsed.name, invoke(parsed)));
     return;
   }
   if (command === "doctor") {
     const parsed = splitFlags(rest);
-    const { doctorProject } = await import("../shared/ps7a6h14.js");
+    const { doctorProject } = await import("../shared/kr0jzbw2.js");
     stdout(await doctorProject(cwd, parsed.name, invoke(parsed)));
     return;
   }
@@ -136,7 +138,7 @@ async function run(argv, io) {
       });
     }
     if (sub === "list" || sub === "check") {
-      const { extProject } = await import("../shared/janx09m5.js");
+      const { extProject } = await import("../shared/ktz42yez.js");
       stdout(await extProject(cwd, sub, invoke(splitFlags(rest.slice(1)))));
       return;
     }
@@ -270,10 +272,34 @@ function numberFlag(flag, value) {
   return parsed;
 }
 
+// src/tooling/node-version.ts
+function nodeSupportsConfigTypes(version) {
+  const match = /^v(\d+)\.(\d+)/.exec(version);
+  if (match === null)
+    return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  if (major > 22)
+    return true;
+  if (major < 22)
+    return false;
+  return minor >= 18;
+}
+function nodeStartupMessage(version, bunRuntime) {
+  if (bunRuntime || nodeSupportsConfigTypes(version))
+    return;
+  return `okm needs Node.js >=22.18 to load a .ts config (type stripping). This process is ${version}. Run bun --bun okm to use the Bun runtime.
+`;
+}
+
 // src/tooling/cli.ts
 var here = dirname(fileURLToPath(import.meta.url));
 var packageJsonPath = join(here, "..", "..", "package.json");
-if (process.argv.includes("--version")) {
+var nodeProblem = nodeStartupMessage(process.version, process.versions.bun !== undefined);
+if (nodeProblem !== undefined) {
+  process.stderr.write(nodeProblem);
+  process.exitCode = 1;
+} else if (process.argv.includes("--version")) {
   process.stdout.write(`${readPackageVersion(packageJsonPath)}
 `);
 } else {

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

@@ -49,6 +49,14 @@ export type ApplyRequest = {
      * `SET ROLE` before any statement. That statement is not a plan step.
      */
     readonly migrationRole?: string;
+    /**
+     * Application role.
+     *
+     * After the plan, this role receives `SELECT` on `okm_meta` and nothing
+     * else. `connect()` can then read the stored hash. Check scratch paths
+     * leave this unset.
+     */
+    readonly appRole?: string;
     /**
      * Schema the migration role may create in.
      *
@@ -95,6 +103,12 @@ export type ApplyReport = {
     /** Set when the runner issued `SET ROLE` at session start. */
     readonly setRole?: string;
 };
+/**
+ * Creates `okm_meta`, `okm_history`, and `okm_backfill` when they are absent.
+ *
+ * @param execute - Runs one statement on the apply or check connection
+ */
+export declare function ensureMigrationTables(execute: (sql: string) => Promise<unknown>): Promise<void>;
 /**
  * Groups pending steps into the transactions apply will run.
  *

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

@@ -1,10 +1,9 @@
 /**
  * `okm migrate check` proves a migration history is sound (D196).
  *
- * The command replays every file into a scratch schema through
- * {@link applyTarget}, then plans the introspected schema back to that
- * file's catalog. It also checks the previous catalog, the head, and the
- * linter. Nothing here changes apply.
+ * The command replays every file into a scratch schema inside one transaction
+ * and rolls that transaction back. It also checks the previous catalog, the
+ * head, and the linter. Nothing here changes apply.
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import { type MigrationClass } from "./classify.js";

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

@@ -76,6 +76,10 @@ export declare const STEP_CLASS: {
     readonly "rename-sequence": "contract";
     readonly "backfill-expand": "expand";
     readonly "backfill-contract": "contract";
+    readonly "enable-rls": "expand";
+    readonly "create-policy": "expand";
+    readonly "drop-policy": "contract";
+    readonly "disable-rls": "contract";
     readonly "raw-sql": "unclassified";
 };
 /** A planner operation. */

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

@@ -59,10 +59,11 @@ export type MigrateConfig = {
         readonly statementTimeoutMs?: number;
     };
     /**
-     * Migration role and application role.
+     * Migration role, application role, and the optional reporting role.
      *
      * A name is external unless it is also listed in `managed`. The plan creates
-     * a managed role and never drops one.
+     * a managed role and never drops one. `reporting` receives select only.
+     * `columns` grants select or update on named columns.
      */
     readonly roles?: RolesInput;
 };

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

@@ -1,8 +1,9 @@
 /**
  * Engine-version checks `okm migrate apply` runs before the first statement.
  *
- * The only engine-dependent feature in 0.2 is a `uuidv7()` database default,
- * which Postgres has from 18. Nothing here is reachable from `connect()`.
+ * An explicit `uuidv7()` database default needs {@link UUIDV7_POSTGRES}.
+ * A bare `t.id()` stores `gen_random_uuid()` and does not match here.
+ * Nothing here is reachable from `connect()`.
  */
 import type { DriverConnection } from "../../contracts/driver.js";
 import type { StoredMigration } from "./files.js";

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

@@ -2,7 +2,7 @@
  * Migration files on disk: SQL from {@link formatPlan} plus the catalog hash.
  */
 import { parseCatalog } from "../../contracts/catalog/document.js";
-import { type PlanStep } from "./plan.js";
+import { type MigrationPlan, type PlanStep } from "./plan.js";
 /** One migration the applier can run and resume. */
 export type StoredMigration = {
     readonly id: string;
@@ -25,6 +25,16 @@ export type StoredMigration = {
  * @returns Migrations in apply order
  */
 export declare function loadMigrations(directory: string): readonly StoredMigration[];
+/**
+ * Reads one migration SQL file.
+ *
+ * Line endings and a UTF-8 BOM are normalized. A non-empty file with no steps
+ * and no `-- no steps` line is refused.
+ *
+ * @param path - `*.sql` path
+ * @returns The plan
+ */
+export declare function readMigrationPlan(path: string): MigrationPlan;
 /**
  * Loads the last migration's catalog, which is the head snapshot.
  *

package/dist/tooling/migrate/index.js

@@ -1,26 +1,27 @@
-import"../../shared/krxx77g0.js";
-import"../../shared/8bwbwy8h.js";
+import"../../shared/14vx95q4.js";
+import"../../shared/qq3899ht.js";
 import"../../shared/n442h54c.js";
 import {
   applyTarget2,
   backfillTiming2
-} from "../../shared/cctw17hj.js";
+} from "../../shared/p6qc5gcp.js";
 import {
-  loadMigrations,
-  loadHeadSnapshot,
   readReference
-} from "../../shared/gde73es6.js";
-import"../../shared/szm0cksa.js";
-import"../../shared/fancm5pt.js";
+} from "../../shared/m6p12kbr.js";
+import"../../shared/8skf0cam.js";
+import"../../shared/b5pftnn2.js";
 import {
+  projectPath,
+  loadMigrations,
+  loadHeadSnapshot,
   loadBuiltSchema,
   loadConfig
-} from "../../shared/qv2ydck9.js";
+} from "../../shared/gs74dbj5.js";
 import {
   assertTargetPolicy,
   selectTarget
-} from "../../shared/ga3sfy93.js";
-import"../../shared/8xsbagad.js";
+} from "../../shared/tsvww22q.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>;