okmodel 0.8.0 → 0.9.0

package/dist/tooling/migrate/pull-verify.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Replays pulled routines on a scratch schema.
+ *
+ * Create order is the catalog's dependency order, plus lexical edges for a
+ * plpgsql or SQL-string body. `check_function_bodies` is on. A SQL function
+ * or a view whose dependency is missing fails creation. A plpgsql body is
+ * not proved by creation, so a function that is created is still
+ * candidate-only. The scratch schema is dropped before this returns.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { CatalogQuery } from "../../dialects/pg/introspect.js";
+import { type RoutinePlan, type RoutineVerdict } from "./pull-routines.js";
+/**
+ * Creates the planned routines from empty and records what that proved.
+ *
+ * Types are created first. Everything else follows the catalog dependency
+ * order, so a function with no edge is created before its tables. Routine
+ * bodies see only the scratch schema. A role that cannot create a schema
+ * leaves every function unproved.
+ *
+ * @param runner - Database connection. Statements share its session
+ * @param source - Introspected catalog
+ * @param plan - Routines `okm pull` will write
+ * @returns One verdict per planned function, trigger, and view
+ */
+export declare function verifyPulled(runner: CatalogQuery, source: Catalog, plan: RoutinePlan): Promise<readonly RoutineVerdict[]>;

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

@@ -0,0 +1,62 @@
+/**
+ * `okm pull` reads a database and writes table files plus a schema file.
+ *
+ * The selected namespaces are only read. A scratch schema is created and
+ * dropped to verify functions and views, then dropped before this returns.
+ * A protected target is allowed. An existing file is refused before anything
+ * is written.
+ */
+import { type PullFile, type PullLayout, type PullSkip } from "./pull-emit.js";
+/** What `okm pull` prints, and the objects the files leave out. */
+export type PullResult = {
+    /** Report text, including the trailing newline. */
+    readonly text: string;
+    /** Objects that were not written. */
+    readonly skipped: readonly PullSkip[];
+};
+/**
+ * Introspects the selected namespaces and writes the schema source.
+ *
+ * The default namespace is `current_schema()`. `--schema` selects others and
+ * may be repeated. `--out` is the directory that receives `schema.ts` and
+ * `tables/`. Without it, the project's schema path and tables directory are
+ * used. A tables directory that the config omits is `tables` beside the
+ * schema file.
+ *
+ * @param cwd - Project directory
+ * @param argv - Arguments after `pull`
+ * @returns The report
+ */
+export declare function pullProject(cwd: string, argv: readonly string[]): Promise<PullResult>;
+/**
+ * Reads `--out`, `--schema`, and `--target` from a pull invocation.
+ *
+ * @param argv - Arguments after `pull`
+ * @returns The flags this command reads
+ */
+export declare function parsePullArgs(argv: readonly string[]): {
+    readonly target: string | undefined;
+    readonly allowProtected: boolean;
+    readonly out: string | undefined;
+    readonly schemas: readonly string[];
+};
+/**
+ * Resolves the schema file and the tables directory for a pull or an import.
+ *
+ * `--out` writes `schema.ts` and `tables/` under that directory. Without it,
+ * the project's schema path and tables directory are used.
+ *
+ * @param cwd - Project directory
+ * @param schema - Config schema path
+ * @param tables - Config tables directory, when set
+ * @param out - `--out` directory, when set
+ * @returns Absolute paths
+ */
+export declare function pullLayout(cwd: string, schema: string, tables: string | undefined, out: string | undefined): PullLayout;
+/**
+ * Refuses an existing file, writes the rest, and formats them.
+ *
+ * @param files - Files from {@link emitPull}
+ * @param verb - `Pull` or `Import`, named in OKM1855
+ */
+export declare function commitPullFiles(files: readonly PullFile[], verb?: "Pull" | "Import"): void;

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

@@ -0,0 +1,32 @@
+/**
+ * Warns when a domain check or a `LANGUAGE sql` body reprints (D276).
+ *
+ * The comparison runs after `okm migrate check` has created the objects.
+ * The linter itself does not connect. A matching stored text is silent.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { LintSeverity } from "./lint-rules.js";
+import type { PlanStep } from "./plan.js";
+/** Check-stage warning for a reprinted domain check or SQL function body. */
+export declare const REPRINT_CODE = "OKM1552";
+/** One reprint comparison, before the registry sentence is attached. */
+export type ReprintHit = {
+    readonly severity: LintSeverity;
+    readonly code: string;
+    readonly place: string;
+    readonly reason: string;
+};
+/**
+ * Compares declared text with the text Postgres stored.
+ *
+ * A step that does not create or replace the object is skipped, so a later
+ * migration does not repeat the warning. `-- okm-allow OKM1552: reason` on
+ * that step silences it. An empty reason, or an allow on a statement whose
+ * text matches, is OKM1510.
+ *
+ * @param declared - Catalog stored with the migration
+ * @param stored - Catalog introspection read back after the replay
+ * @param steps - Statements of that migration, including allows
+ * @returns Findings in catalog order
+ */
+export declare function reprintHits(declared: Catalog, stored: Catalog, steps: readonly PlanStep[]): readonly ReprintHit[];

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

@@ -7,6 +7,7 @@
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import type { MigrateConfig } from "./config.js";
+import { type Finding } from "./lint.js";
 import { type MigrationPlan, type PlanStep } from "./plan.js";
 /** One migration the check replays. */
 export type CheckMigration = {
@@ -22,6 +23,7 @@ export type ReplayStop = {
 /** Replay result. `skips` are statements check did not execute. */
 export type ReplayOutcome = {
     readonly skips: readonly string[];
+    readonly reprints: readonly Finding[];
     readonly stop?: ReplayStop;
 };
 /**
@@ -48,10 +50,14 @@ export declare function replayCheckHistory(url: string, scratch: string, config:
  */
 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.
+ * Rewrites the catalog schema to the scratch schema.
+ *
+ * `source` defaults to `public`. A foreign key aimed at another schema is
+ * left in place.
  *
  * @param steps - Plan steps
  * @param schema - Scratch schema
+ * @param source - Schema the statements currently name
  * @returns The same steps, aimed at `schema`
  */
-export declare function retargetSteps(steps: readonly PlanStep[], schema: string): readonly PlanStep[];
+export declare function retargetSteps(steps: readonly PlanStep[], schema: string, source?: string): readonly PlanStep[];

package/dist/tooling/migrate/schema-api.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Programmatic schema API (D26, D284).
+ *
+ * `describe` turns a `schema()` result into JSON. `buildCatalog` reads that
+ * JSON back into the catalog tooling already plans. Codecs and client
+ * generators stay on the schema. They are functions, and the catalog hash
+ * does not include them.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type LogicalIdentity } from "./export.js";
+/**
+ * JSON description of one schema.
+ *
+ * `logical` names the schema. It is not the catalog hash. `catalog` is the
+ * catalog document: no functions, and object keys in sorted order.
+ */
+export type SchemaDescription = {
+    readonly logical: LogicalIdentity;
+    readonly catalog: Catalog;
+};
+/**
+ * Describes a schema as JSON.
+ *
+ * The logical identity is `public`. Placing the same catalog into another
+ * namespace does not change it. The catalog document keeps the namespaces
+ * the catalog already has, so the catalog hash still changes with placement.
+ *
+ * @param schema - A `schema()` result, or any value that carries its catalog
+ * @returns A description `JSON.stringify` can store
+ */
+export declare function describe(schema: {
+    readonly catalog: Catalog;
+}): SchemaDescription;
+/**
+ * Builds the catalog from a description.
+ *
+ * `JSON.parse(JSON.stringify(describe(schema)))` is a valid argument. The
+ * result has the same catalog hash as `schema.catalog`.
+ *
+ * @param description - Description from {@link describe}, including one read back from JSON
+ * @returns The catalog `okm` plans
+ */
+export declare function buildCatalog(description: SchemaDescription): Catalog;

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

@@ -37,3 +37,21 @@ export declare function sqlQuoteOpen(sql: string): boolean;
  * @returns The command, or `undefined` when the step stays in one transaction
  */
 export declare function transactionControl(sql: string): string | undefined;
+/** One identifier {@link sqlIdentifiers} found outside a string or a comment. */
+export type SqlName = {
+    /** Spelling as written. A quoted name is unescaped. An unquoted name is not folded. */
+    readonly text: string;
+    /** True when the name was a double-quoted identifier. */
+    readonly quoted: boolean;
+};
+/**
+ * Identifiers outside comments, strings, and dollar quotes.
+ *
+ * The quote rules are the same ones {@link sqlStatements} uses. A name inside
+ * a string or a dollar quote is not a match: Postgres still resolves
+ * `'notes'::regclass`, and this scan does not.
+ *
+ * @param sql - Function body or view query
+ * @returns Identifiers in source order
+ */
+export declare function sqlIdentifiers(sql: string): readonly SqlName[];

package/dist/tooling/shared/{3m1hkg7z.js → 04svnxxj.js}

@@ -2,10 +2,10 @@ import {
   DriverError2,
   timedOut2,
   isConnectionLost
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 import {
   PgSession2
-} from "./p7f08ktn.js";
+} from "./62fxpc1p.js";
 import {
   driverErrors,
   rejectClosed,
@@ -13,7 +13,7 @@ import {
   runCall,
   rowsFrom,
   resultFrom
-} from "./xhrnjch9.js";
+} from "./5x3pf400.js";
 
 // src/adapters/pg/postgres-extra.ts
 var RESET_ALL = "RESET ALL";
@@ -48,7 +48,7 @@ async function checkout(pool, timeoutMs) {
     batch: (statements, options) => {
       remember(options?.timeout);
       return guard(() => runCall(pool.isClosed(), options, async (watch) => {
-        const { runAtomicBatch } = await import("./3rrw5w8f.js");
+        const { runAtomicBatch } = await import("./gqwevek4.js");
         return runAtomicBatch(session, statements, watch);
       }));
     },

package/dist/tooling/shared/{ppnnnvj8.js → 0j0jtse1.js}

@@ -1,6 +1,6 @@
 import {
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/result-name.ts
 var PROTOTYPE_KEYS = ",__proto__,constructor,toString,hasOwnProperty,valueOf,isPrototypeOf,propertyIsEnumerable,toLocaleString,__defineGetter__,__defineSetter__,__lookupGetter__,__lookupSetter__,then,";

package/dist/tooling/shared/{z8d7ptht.js → 0r05zhyq.js}

@@ -1,13 +1,13 @@
 import {
   identityColumn2
-} from "./ec71zqgt.js";
+} from "./vwr2y833.js";
 import {
   runWrite
 } from "./n4jqhpqz.js";
 import {
   queryHandle,
   settleCall
-} from "./mtrqn2hn.js";
+} from "./jr2nmr81.js";
 import {
   OkmError,
   throwNamed,
@@ -22,7 +22,7 @@ import {
   list,
   isRecord,
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/sync.ts
 var OPTIONS = ["expect", "signal", "timeout", "route"];
@@ -539,8 +539,8 @@ function callOf(options) {
 async function presetWhere(schema, table, uses) {
   if (uses === undefined)
     return;
-  const { resolve } = await import("./ma2340rx.js");
-  const { stack } = await import("./wwnekq5n.js");
+  const { resolve } = await import("./5bmksndh.js");
+  const { stack } = await import("./5zrzffnk.js");
   return stack(undefined, resolve(schema, table, uses).wheres);
 }
 function noteSafety(session, table, view) {

package/dist/tooling/shared/{a6pp9d12.js → 1800eymw.js}

@@ -1,15 +1,15 @@
 import {
   markClientPool2,
   open2
-} from "./xjs6zqtc.js";
+} from "./rcywj2w8.js";
 import {
   createClient
-} from "./mtrqn2hn.js";
+} from "./jr2nmr81.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("./2wtvc7rw.js").then((mod) => mod.default(target, options, (config) => {
+    return import("./kbqnrs1x.js").then((mod) => mod.default(target, options, (config) => {
       const pool = open2(config);
       markClientPool2(pool);
       return pool;

package/dist/tooling/shared/{cmptmb4f.js → 35zemrmf.js}

@@ -1,6 +1,6 @@
 import {
   tag
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/preset-stack.ts
 function stack2(where, presets) {

package/dist/tooling/shared/{w7qe8sj1.js → 3rmaz3pq.js}

@@ -1,7 +1,7 @@
 import {
   quote,
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/sort.ts
 function insertAtEnd(table, columns, rows, group, tenantFields) {

package/dist/{shared/q0cqt2sp.js → tooling/shared/3yn79q5m.js}

@@ -1,6 +1,6 @@
 import {
   rejectUncancellable
-} from "./ae4j5f42.js";
+} from "./5x3pf400.js";
 
 // src/adapters/pg/no-inflight-timeout.ts
 function noTimeout(options) {

package/dist/tooling/shared/{2revefqt.js → 57btdkgm.js}

@@ -1,6 +1,6 @@
 import {
   refusePrototypeKey
-} from "./ppnnnvj8.js";
+} from "./0j0jtse1.js";
 import {
   throwNamed,
   parseOrder,
@@ -9,7 +9,7 @@ import {
   list,
   isRecord,
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/dialects/pg/ops/bucket.ts
 var RUNTIME = Symbol.for("okmodel.bucket");

package/dist/tooling/shared/{ma2340rx.js → 5bmksndh.js}

@@ -1,11 +1,11 @@
 import {
   stack2
-} from "./cmptmb4f.js";
+} from "./35zemrmf.js";
 import {
   OkmError,
   isOperator,
   operatorValue
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/dialects/pg/preset.ts
 var RESERVED_PRESETS = new Set([

package/dist/tooling/shared/{9xzm7hjg.js → 5p8km5jb.js}

@@ -1,15 +1,15 @@
 import {
   open6,
   seal2
-} from "./djydjpqt.js";
+} from "./t6zjeake.js";
 import {
   createClient
-} from "./mtrqn2hn.js";
+} from "./jr2nmr81.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("./2wtvc7rw.js").then((mod) => mod.default(target, options, open6));
+    return import("./kbqnrs1x.js").then((mod) => mod.default(target, options, open6));
   }
   const pool = isPool(target) ? seal2(target) : await open6({
     ...target !== undefined ? { dataDir: target } : {},

package/dist/tooling/shared/{xhrnjch9.js → 5x3pf400.js}

@@ -57,14 +57,14 @@ function hasCapability2(flags, name) {
 // src/adapters/failure.ts
 var loading;
 function driverErrors() {
-  loading ??= import("./aftb2mwr.js");
+  loading ??= import("./a2xe04bm.js");
   return loading;
 }
 function rejectClosed() {
-  return import("./345tbc2k.js").then((mod) => mod.closed());
+  return import("./sjwkt1pg.js").then((mod) => mod.closed());
 }
 function rejectUncancellable() {
-  return import("./345tbc2k.js").then((mod) => mod.refused());
+  return import("./sjwkt1pg.js").then((mod) => mod.refused());
 }
 function rejectCancelled() {
   return driverErrors().then((mod) => Promise.reject(mod.cancelled()));

package/dist/tooling/shared/{wwnekq5n.js → 5zrzffnk.js}

@@ -1,6 +1,6 @@
 import {
   stack2
-} from "./cmptmb4f.js";
+} from "./35zemrmf.js";
 export {
   stack2 as stack
 };

package/dist/tooling/shared/{p7f08ktn.js → 62fxpc1p.js}

@@ -6,7 +6,7 @@ import {
   runCall,
   EMPTY_NOTICES,
   resultFrom
-} from "./xhrnjch9.js";
+} from "./5x3pf400.js";
 
 // src/adapters/pg/postgresjs.ts
 import net from "node:net";
@@ -118,17 +118,17 @@ function open3(config) {
       return sockets.occupy(() => runCall(closed, options, (watch) => root.query(text, params, watch)));
     },
     batch(statements, options) {
-      return sockets.occupy(() => import("./3m1hkg7z.js").then((mod) => mod.runBatch(held, statements, options)));
+      return sockets.occupy(() => import("./04svnxxj.js").then((mod) => mod.runBatch(held, statements, options)));
     },
     reserve() {
       const gate = sockets.busyGate();
       gate.enter();
-      return import("./3m1hkg7z.js").then((mod) => mod.holdCheckout(gate, () => mod.checkout(held)), (error) => {
+      return import("./04svnxxj.js").then((mod) => mod.holdCheckout(gate, () => mod.checkout(held)), (error) => {
         gate.leave();
         throw error;
       });
     },
-    describe: (text, params) => sockets.occupy(() => import("./3m1hkg7z.js").then((mod) => mod.describe(sql, text, params))),
+    describe: (text, params) => sockets.occupy(() => import("./04svnxxj.js").then((mod) => mod.describe(sql, text, params))),
     stream(text, params) {
       const gate = sockets.busyGate();
       return async function* () {
@@ -143,7 +143,7 @@ function open3(config) {
     listen(channel, onNotify) {
       const gate = sockets.listenerGate();
       gate.enter();
-      return import("./3m1hkg7z.js").then((mod) => mod.holdListener(gate, async () => {
+      return import("./04svnxxj.js").then((mod) => mod.holdListener(gate, async () => {
         const listening = await sql.listen(channel, onNotify);
         return async () => {
           await listening.unlisten();
@@ -213,7 +213,7 @@ class PgSession2 {
       onAbort();
     else
       watch.signal.addEventListener("abort", onAbort, { once: true });
-    return import("./3m1hkg7z.js").then((mod) => mod.watchQuery(pending, watch, onAbort, {
+    return import("./04svnxxj.js").then((mod) => mod.watchQuery(pending, watch, onAbort, {
       start,
       text,
       notices: this.notices,
@@ -265,7 +265,7 @@ class PgSession2 {
   }
 }
 async function* loadStream(sql, text, params) {
-  const { stream } = await import("./3m1hkg7z.js");
+  const { stream } = await import("./04svnxxj.js");
   yield* stream(sql, text, params);
 }
 function send(sql, text, params, named) {

package/dist/tooling/shared/{7ae7rjmn.js → 68tf18v4.js}

@@ -2,13 +2,13 @@ import {
   open5,
   connectClient3,
   send4
-} from "./y5656f0e.js";
+} from "./am04v8na.js";
 import {
   NEON_WEBSOCKET_CAPABILITIES,
   NEON_HTTP_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "./xhrnjch9.js";
+} from "./5x3pf400.js";
 export {
   NEON_WEBSOCKET_CAPABILITIES as capabilities,
   connectClient3 as connectClient,

package/dist/tooling/shared/{rf83gr2d.js → 6vk28rjp.js}

@@ -1,6 +1,10 @@
+import {
+  historySql2
+} from "./dhatassp.js";
+import"./jr2nmr81.js";
 import {
   OkmError
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/compat-words.ts
 var BEHIND_EXPAND = "behind by expand";
@@ -37,10 +41,10 @@ function driftVerdict(codeHash, recordedHash, migrations) {
   const last = migrations.at(-1);
   return { state: "behind", migrationId: last?.id ?? "" };
 }
-async function assertDrift(pool, codeHash, recordedHash, options) {
+async function assertDrift(pool, codeHash, recordedHash, options, namespace = "public") {
   let rows;
   try {
-    const result = await pool.execute("select migration_id, class, catalog_hash from okm_history order by migration_id, step_index", undefined, options);
+    const result = await pool.execute(await historySql2(namespace), undefined, options);
     rows = result.rows;
   } catch (error) {
     throw gapError({ state: "behind", migrationId: "" }, error);

package/dist/tooling/shared/76pv6qff.js

@@ -0,0 +1,9 @@
+import {
+  historySql2,
+  acceptServer2
+} from "./dhatassp.js";
+import"./jr2nmr81.js";
+export {
+  acceptServer2 as acceptServer,
+  historySql2 as historySql
+};

package/dist/tooling/shared/{bz2dqhab.js → 7aews1zg.js}

@@ -3,7 +3,7 @@ import {
   readHandle,
   readCall,
   attachHttp
-} from "./mtrqn2hn.js";
+} from "./jr2nmr81.js";
 import {
   OkmError,
   throwNamed,
@@ -19,13 +19,13 @@ import {
   list,
   isRecord,
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/aggregate.ts
 var BUCKET = Symbol.for("okmodel.bucket");
 var bucketChunk;
 function loadBucketGroup() {
-  return bucketChunk ??= import("./2revefqt.js");
+  return bucketChunk ??= import("./57btdkgm.js");
 }
 var OPTIONS = [
   "where",

package/dist/tooling/shared/{9kazs5p6.js → 7b3xp9gc.js}

@@ -1,6 +1,6 @@
 import {
   emitSqlValue
-} from "./gmcf9cxf.js";
+} from "./ybdew6j7.js";
 import {
   assertOperatorFits,
   sqlType,
@@ -8,7 +8,7 @@ import {
   assertBoundText,
   assertRegconfig,
   textArray
-} from "./3tq8pnb8.js";
+} from "./w5d89rb4.js";
 import {
   isOperator,
   operatorName,
@@ -17,7 +17,7 @@ import {
   quote,
   isRecord,
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/operator-sql.ts
 function emitStructured(table, column, ref, name, value, sink, order) {

package/dist/tooling/shared/{4d2w25vw.js → 7pxncnzs.js}

@@ -1,9 +1,9 @@
 import {
   rejectClosed
-} from "./xhrnjch9.js";
+} from "./5x3pf400.js";
 import {
   isConnectionLost
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/adapters/pg/reserved.ts
 var RESET_ALL = "RESET ALL";

package/dist/tooling/shared/{zvnhh1n0.js → 829fjxyw.js}

@@ -3,7 +3,7 @@ import {
   readHandle,
   readCall,
   attachHttp
-} from "./mtrqn2hn.js";
+} from "./jr2nmr81.js";
 import {
   OkmError,
   throwNamed,
@@ -17,7 +17,7 @@ import {
   isRecord,
   registerFailFix,
   fail2
-} from "./f9mphxej.js";
+} from "./hfq3n3bd.js";
 
 // src/runtime/page.ts
 registerFailFix("OKM1130", "Request the next page with the same orderBy and the exact next value the previous page returned. The cursor encodes that order.");

package/dist/tooling/shared/{dzx85q70.js → 8m5znpdt.js}

@@ -1,6 +1,6 @@
 import {
   mapFailure
-} from "./xhrnjch9.js";
+} from "./5x3pf400.js";
 
 // src/adapters/pg/pglite-wire.ts
 var OIDS = [