okmodel 0.8.0 → 0.9.1

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

@@ -93,6 +93,20 @@ export type ApplyRequest = {
         readonly reference: readonly ReferenceTable[];
         readonly only?: boolean;
     };
+    /**
+     * Catalog hash `okm_meta` must record when this run finishes.
+     *
+     * When the plan (or pending units) leave the database matching the schema
+     * but `okm_meta` still holds an older hash — for example an external table
+     * gained a column and the dependent exported a new snapshot — the runner
+     * re-stamps `okm_meta` and `okm_history` under a fresh id. File apply only
+     * enables that path when `defineConfig({ external })` is set; a foreign or
+     * legacy hash without external snapshots is left for connect or the pre-D208
+     * restamp.
+     */
+    readonly headHash?: string;
+    /** When true, an empty apply may re-stamp `okm_meta` to {@link headHash}. */
+    readonly restampHead?: boolean;
 };
 /** Migrations that ran at least one step in this invocation. */
 export type ApplyReport = {
@@ -147,8 +161,9 @@ export declare function applyProject(cwd: string, flags: InvokeFlags, write?: (t
 /**
  * Prototype sync. Blocked on a protected target.
  *
- * A target named production is not special. Protection is the `protected`
- * flag (spec §19.8). The plan's statements run as one migration.
+ * Plans from the live catalog on the target (not the last migration file),
+ * applies under a fresh `push-<n>` id from `okm_history`, and re-stamps
+ * `okm_meta` when the schema hash moved with no DDL (B-29, B-21).
  *
  * @param cwd - Project directory
  * @param flags - Target and protection flags

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

@@ -22,7 +22,8 @@ export declare function formatFailure(error: unknown, verbose?: boolean): string
  * Runs one `okm` invocation.
  *
  * `--version` stays in the bin. This function handles `build`, `check`,
- * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `doctor`,
+ * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `ext scaffold`,
+ * `ext test`, `doctor`,
  * `driver test`, and `migrate plan`, `apply`, `status`, and `check`.
  *
  * @param argv - Arguments after the program name

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

@@ -45,6 +45,19 @@ export type MigrateConfig = {
      * migration.
      */
     readonly lintFrom?: string;
+    /**
+     * Postgres schema this catalog owns.
+     *
+     * Omitted means `public`. `schema()` still compiles `public`. Tooling
+     * places the catalog here before it plans, and stores `okm_meta` here.
+     */
+    readonly namespace?: string;
+    /**
+     * Snapshots from `okm catalog export`, one path per owning catalog.
+     *
+     * `external()` tables are verified against these files.
+     */
+    readonly external?: readonly string[];
     /**
      * Batched backfill (D195).
      *

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

@@ -19,6 +19,18 @@ import type { RolesInput } from "../../dialects/pg/role/index.js";
  * @param roles - `defineConfig({ roles })`, when set
  */
 export declare function assertAuthorDrift(url: string, author: Catalog, roles?: RolesInput, allowPooler?: boolean): Promise<void>;
+/**
+ * Reprints each domain check the way this server stores it.
+ *
+ * Author spellings such as `VALUE > 0` become `((VALUE > 0))`, so a plan
+ * against a live catalog does not treat the reprint as a permanent change.
+ * The catalog hash still uses the author text (B-37).
+ *
+ * @param runner - Database connection
+ * @param source - Catalog whose domain checks may still be author SQL
+ * @returns A catalog whose domain checks carry the server reprint
+ */
+export declare function sealDomainChecks(runner: CatalogQuery, source: Catalog): Promise<Catalog>;
 /**
  * Turns a postgres.js handle into the query shape introspection uses.
  *

package/dist/tooling/migrate/driver-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Connection URL helpers for migrate commands.
+ *
+ * Pooler client hints in the query string are not Postgres startup parameters.
+ * Every migrate path that opens a driver must strip those hints first. The
+ * URL guard still reads `pgbouncer=true` on the original URL before this runs.
+ */
+/**
+ * Removes the `pgbouncer` query parameter before a driver opens a connection.
+ *
+ * Other pooler hints in the URL are left alone: this version does not
+ * interpret them.
+ *
+ * @param url - A `postgres://` or `postgresql://` URL
+ * @returns The same URL without `pgbouncer` in the query string
+ */
+export declare function driverUrl(url: string): string;

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

@@ -0,0 +1,165 @@
+/**
+ * `okm catalog export` and the check that a dependent catalog runs.
+ *
+ * The snapshot is derived from the schema source. It stores the catalog
+ * hash and, separately, a logical identity. It has no function and no
+ * connection URL. Column names and types are what a dependent verifies.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import type { MigrateConfig } from "./config.js";
+import type { Finding } from "./lint.js";
+/** Snapshot file format. Not the logical schema format. */
+export declare const EXPORT_FORMAT = 1;
+/** Logical schema format. A hash change does not move this. */
+export declare const LOGICAL_FORMAT = 1;
+/** One column a dependent verifies. No default and no expression. */
+export type ExportColumn = {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+};
+/** One table in a snapshot. */
+export type ExportTable = {
+    readonly namespace: string;
+    readonly name: string;
+    readonly columns: readonly ExportColumn[];
+};
+/**
+ * Logical schema identity.
+ *
+ * `namespace` and `name` name the schema. `format` is {@link LOGICAL_FORMAT}.
+ * None of these is the catalog hash.
+ */
+export type LogicalIdentity = {
+    readonly namespace: string;
+    readonly name: string;
+    readonly format: typeof LOGICAL_FORMAT;
+};
+/**
+ * A catalog snapshot.
+ *
+ * `catalogHash` is the physical identity. `logical` is not that hash.
+ * `database` is the database name only, never a URL.
+ */
+export type CatalogSnapshot = {
+    readonly format: typeof EXPORT_FORMAT;
+    readonly logical: LogicalIdentity;
+    readonly catalogHash: string;
+    readonly database?: string;
+    readonly tables: readonly ExportTable[];
+};
+/**
+ * Builds a snapshot from a placed catalog.
+ *
+ * @param source - Catalog tooling plans, after namespace placement
+ * @param namespace - `defineConfig({ namespace })`, or `public`
+ * @param database - Database name, when the config has a target URL
+ * @returns A snapshot with no functions and no connection URL
+ */
+export declare function snapshotFromCatalog(source: Catalog, namespace: string, database?: string): CatalogSnapshot;
+/**
+ * Serializes a snapshot.
+ *
+ * The same catalog returns the same bytes, including the trailing newline.
+ *
+ * @param snapshot - Snapshot to write
+ * @returns UTF-8 JSON
+ */
+export declare function serializeSnapshot(snapshot: CatalogSnapshot): string;
+/**
+ * Reads a snapshot file.
+ *
+ * A missing file and a file that is not this format are OKM1841.
+ *
+ * @param path - Absolute or project-relative path, as the message should name it
+ * @param text - File contents
+ * @returns The snapshot
+ */
+export declare function parseSnapshot(path: string, text: string): CatalogSnapshot;
+/**
+ * Database name from a Postgres URL.
+ *
+ * The user, password, host, and query are not returned.
+ *
+ * @param url - Target URL
+ * @returns The path segment, or `undefined` when the URL has none
+ */
+export declare function databaseName(url: string): string | undefined;
+/**
+ * Namespace `defineConfig` asked for.
+ *
+ * Omitted means `public`.
+ *
+ * @param config - Project config
+ * @returns The schema name
+ */
+export declare function catalogNamespace(config: MigrateConfig): string;
+/**
+ * Loads the snapshots named by `defineConfig({ external })`.
+ *
+ * A missing path is OKM1841.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @returns One snapshot per path, in config order
+ */
+export declare function loadSnapshots(cwd: string, config: MigrateConfig): readonly LoadedSnapshot[];
+/** A snapshot and the config path that named it. */
+export type LoadedSnapshot = {
+    readonly path: string;
+    readonly snapshot: CatalogSnapshot;
+};
+/**
+ * SQL table name to the namespace recorded in a snapshot.
+ *
+ * @param snapshots - Loaded exports
+ * @returns The map `placeCatalog` reads
+ */
+export declare function externalNamespaceMap(snapshots: readonly LoadedSnapshot[]): ReadonlyMap<string, string>;
+/**
+ * Cross-catalog foreign keys, as `okm check` warnings.
+ *
+ * A key inside one namespace is not coupling. The warning does not fail the check.
+ *
+ * @param source - Placed catalog
+ * @returns One warning per foreign key whose namespaces differ
+ */
+export declare function couplingFindings(source: Catalog): readonly Finding[];
+/**
+ * Checks external tables against the snapshot files.
+ *
+ * This does not open a connection. With no `external` paths, a
+ * `withOwner(..., "external")` table stays hands-off and is not OKM1841.
+ * When paths are set, a missing file, a table the snapshots do not list,
+ * or columns that differ is OKM1841.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @param source - Placed catalog
+ */
+export declare function assertSnapshots(cwd: string, config: MigrateConfig, source: Catalog): void;
+/**
+ * Checks external tables against the connected database.
+ *
+ * A different database name on a cross-catalog foreign key is OKM1842.
+ * A hash or column mismatch is a stale snapshot. A missing relation is
+ * a missing object. Both are OKM1841.
+ *
+ * @param url - Target URL
+ * @param source - Placed catalog
+ * @param snapshots - Files {@link assertSnapshots} already read
+ */
+export declare function assertLiveExternal(url: string, source: Catalog, snapshots: readonly LoadedSnapshot[]): Promise<void>;
+/**
+ * Writes the snapshot for one project.
+ *
+ * `--json` prints the bytes. `--out` writes them. With neither, the bytes
+ * are printed.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @param source - Placed catalog
+ * @param args - Arguments after `export`
+ * @returns Stdout, including a trailing newline
+ */
+export declare function renderExport(cwd: string, config: MigrateConfig, source: Catalog, args: readonly string[]): string;

package/dist/tooling/migrate/ext-surface.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Catalog reads shared by `okm ext scaffold` and `okm ext test`.
+ *
+ * Both are read-only. The queries are `pg_depend`, `pg_type`, `pg_proc`,
+ * `pg_operator`, and `pg_settings`. Nothing is created.
+ */
+import type { DriverPool } from "../../contracts/driver.js";
+import type { Extension, ExtensionFunction, ExtensionIndexMethod, ExtensionOperator, ExtensionProvides, ExtensionType } from "../../dialects/pg/ext/index.js";
+/** One extension as the connected server describes it. */
+export type ServerSurface = {
+    readonly name: string;
+    readonly version: string;
+    readonly schema: string;
+    readonly relocatable: boolean;
+    readonly serverMajor: number;
+    readonly types: readonly ExtensionType[];
+    readonly operators: readonly ExtensionOperator[];
+    readonly functions: readonly ExtensionFunction[];
+    readonly indexMethods: readonly ExtensionIndexMethod[];
+    readonly settings: readonly string[];
+};
+/**
+ * Reads one installed extension.
+ *
+ * A name that is not installed is OKM1811. The connection is not asked to
+ * create it.
+ *
+ * @param pool - Connected server
+ * @param name - Extension name
+ * @returns The catalog surface
+ */
+export declare function readSurface(pool: DriverPool, name: string): Promise<ServerSurface>;
+/**
+ * Prints a starting `extension()` definition.
+ *
+ * The developer owns the file. `requires` and `provides` are the fields
+ * `okm ext test` reads. Settings are a comment, because they are not part
+ * of the definition.
+ *
+ * @param surface - Catalog read
+ * @returns TypeScript source, including the trailing newline
+ */
+export declare function renderScaffold(surface: ServerSurface): string;
+/**
+ * Lists mismatches between a definition and the server.
+ *
+ * An empty list means the definition matches. Version failures and signature
+ * failures are both lines in that list.
+ *
+ * @param declared - The loaded `extension()` value
+ * @param server - The catalog read for `declared.name`
+ * @returns Mismatch lines, stable order
+ */
+export declare function surfaceMismatches(declared: Extension, server: ServerSurface): readonly string[];
+/**
+ * Throws when {@link surfaceMismatches} found any line.
+ *
+ * Version lines are OKM1812. A signature line is `invalid`. Both are listed
+ * in the message.
+ *
+ * @param name - Extension name
+ * @param mismatches - Lines from {@link surfaceMismatches}
+ */
+export declare function refuseMismatches(name: string, mismatches: readonly string[]): void;
+/**
+ * Reports whether a value is an `extension()` result.
+ *
+ * @param value - A module export
+ * @returns `true` when it has a name and `contribute`
+ */
+export declare function isExtension(value: unknown): value is Extension;
+/**
+ * Reads `extension()` values exported by a loaded module.
+ *
+ * @param imported - Module namespace
+ * @returns The definitions, in export order
+ */
+export declare function extensionsFromModule(imported: unknown): readonly Extension[];
+/** Provides kept on the type so a scaffold round-trip can name them. */
+export type { ExtensionProvides };

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

@@ -1,9 +1,10 @@
 /**
- * `okm ext list` and `okm ext check`.
+ * `okm ext list`, `check`, `scaffold`, and `test`.
  *
- * Both talk to the selected target. List prints every extension the server
- * can install, and the installed version when one is present. Check compares
- * the schema's declarations with what is installed.
+ * All four talk to the selected target and are read-only, including on a
+ * protected target. List prints every extension the server can install.
+ * Check compares the schema's declarations with what is installed. Scaffold
+ * prints a starting definition. Test checks that definition against the server.
  */
 import { type InvokeFlags } from "./policy.js";
 /**
@@ -15,3 +16,29 @@ import { type InvokeFlags } from "./policy.js";
  * @returns Text for stdout, including the trailing newline
  */
 export declare function extProject(cwd: string, command: "list" | "check", flags: InvokeFlags): Promise<string>;
+/**
+ * Prints a starting definition for one installed extension.
+ *
+ * `--out` writes the file when that path does not exist. An existing file
+ * is refused and nothing is written. Without `--out`, the text is returned
+ * for stdout.
+ *
+ * @param cwd - Project directory
+ * @param name - Extension name
+ * @param flags - Target and protection flags
+ * @param out - File to write, when the caller passed `--out`
+ * @returns The definition, or a one-line wrote message
+ */
+export declare function extScaffold(cwd: string, name: string, flags: InvokeFlags, out?: string): Promise<string>;
+/**
+ * Checks one definition file against the connected server.
+ *
+ * Every declared type, operator, function, and index method must exist with
+ * the declared signature. `requires` must be met (OKM1812).
+ *
+ * @param cwd - Project directory
+ * @param file - Definition file, relative to `cwd` or absolute
+ * @param flags - Target and protection flags
+ * @returns `ok <name>` for each definition
+ */
+export declare function extTest(cwd: string, file: string, flags: InvokeFlags): Promise<string>;

package/dist/tooling/migrate/import-drizzle.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `okm import drizzle` reads a Drizzle schema and writes table files.
+ *
+ * The schema is imported with the project's own `drizzle-orm`. That import
+ * runs the file. okmodel does not depend on drizzle-orm. The catalog is
+ * written by the same emitter as `okm pull`.
+ */
+import { type PullSkip } from "./pull-emit.js";
+/** What `okm import drizzle` prints, and the objects the files leave out. */
+export type ImportDrizzleResult = {
+    /** Report text, including the trailing newline. */
+    readonly text: string;
+    /** Objects that were not written. */
+    readonly skipped: readonly PullSkip[];
+    /** Postgres schema the tables share. `schema()` still compiles `public`. */
+    readonly namespace: string;
+};
+/**
+ * Imports a Drizzle schema and writes one table file per table, plus the schema file.
+ *
+ * The path is a module in the project. `--out` is the directory that receives
+ * `schema.ts` and `tables/`. Without it, an `okmodel.config.ts` in `cwd`
+ * supplies the layout. A project that has no config yet writes `schema.ts`
+ * and `tables/` in `cwd`.
+ *
+ * @param cwd - Project directory the files are written into
+ * @param argv - Arguments after `import drizzle`
+ * @returns The report and the Postgres schema name
+ */
+export declare function importDrizzle(cwd: string, argv: readonly string[]): Promise<ImportDrizzleResult>;
+/**
+ * Reads the schema path and `--out`.
+ *
+ * @param argv - Arguments after `import drizzle`
+ * @returns The path and the optional output directory
+ */
+export declare function parseImportArgs(argv: readonly string[]): {
+    readonly path: string;
+    readonly out: string | undefined;
+};

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

@@ -2,7 +2,10 @@
  * Public entry for `okmodel/migrate`.
  *
  * `defineConfig`, its types, and `provision` for one configured target.
+ * `describe` and `buildCatalog` are the programmatic schema API.
  * The CLI imports planning and apply helpers from their modules.
  */
 export { defineConfig, type MigrateConfig, type TargetInput } from "./config.js";
+export { type LogicalIdentity } from "./export.js";
+export { buildCatalog, describe, type SchemaDescription } from "./schema-api.js";
 export { provision } from "./provision.js";

package/dist/tooling/migrate/index.js

@@ -1,35 +1,80 @@
-import"../../shared/35q0n9tz.js";
-import"../../shared/12z7aznj.js";
+import {
+  serializeCatalog2,
+  parseCatalog2
+} from "../../shared/12z7aznj.js";
+import"../../shared/fk9vef30.js";
+import"../../shared/jvxcp1qk.js";
 import"../../shared/n442h54c.js";
+import"../../shared/4pkz5nvw.js";
 import {
   applyTarget2,
   backfillTiming2
-} from "../../shared/pan0370z.js";
+} from "../../shared/8ma6drzr.js";
 import {
   readReference
-} from "../../shared/mnvjvqyp.js";
-import"../../shared/kj9d8maq.js";
-import"../../shared/p3xbdcvt.js";
+} from "../../shared/8p2bgye0.js";
+import"../../shared/6xqvesa5.js";
+import"../../shared/e1c55v04.js";
+import"../../shared/mz48rs74.js";
 import {
   projectPath,
+  LOGICAL_FORMAT,
   loadMigrations,
   loadHeadSnapshot,
   loadBuiltSchema,
   loadConfig
-} from "../../shared/f4jy1j7x.js";
+} from "../../shared/wp7y8q3y.js";
 import {
   assertTargetPolicy,
   selectTarget
-} from "../../shared/dpc2r7rb.js";
-import"../../shared/sjk86yrx.js";
+} from "../../shared/bdekbvmt.js";
+import {
+  canonicalJson
+} from "../../shared/358zsv4r.js";
 import {
-  OkmError2
+  OkmError2,
+  catalogError2
 } from "../../shared/52szzakm.js";
 
 // src/tooling/migrate/config.ts
 function defineConfig(config) {
   return config;
 }
+// src/tooling/migrate/schema-api.ts
+var LOGICAL_NAMESPACE = "public";
+function describe(schema) {
+  const source = schemaCatalog(schema);
+  const document = JSON.parse(serializeCatalog2(source));
+  const text = canonicalJson({
+    catalog: document,
+    logical: {
+      format: LOGICAL_FORMAT,
+      name: LOGICAL_NAMESPACE,
+      namespace: LOGICAL_NAMESPACE
+    }
+  });
+  return JSON.parse(text);
+}
+function buildCatalog(description) {
+  if (description === null || typeof description !== "object" || !("catalog" in description)) {
+    catalogError2("OKM1027", "Catalog document is not an object.");
+  }
+  const body = description.catalog;
+  if (body === null || typeof body !== "object") {
+    catalogError2("OKM1027", "Catalog document is not an object.");
+  }
+  return parseCatalog2(JSON.stringify(body));
+}
+function schemaCatalog(schema) {
+  if (schema === null || typeof schema !== "object") {
+    catalogError2("OKM1020", "describe() needs the schema() result.");
+  }
+  const catalog = schema.catalog;
+  if (typeof catalog !== "object" || catalog === null || !("objects" in catalog)) {
+    catalogError2("OKM1020", "describe() needs the schema() result.");
+  }
+  return catalog;
+}
 // src/tooling/migrate/provision.ts
 async function provision(target, cwd = process.cwd()) {
   const config = await loadConfig(cwd);
@@ -71,6 +116,8 @@ ${report.applied.map((id) => `applied ${id}`).join(`
 `;
 }
 export {
+  buildCatalog,
   defineConfig,
+  describe,
   provision
 };

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

@@ -42,10 +42,27 @@ export type ColumnRule = {
  * Step rules, lowest free code in each category.
  *
  * OKM1534 to OKM1537 are errors when the statement is not the safe form.
- * OKM1538 stays a warning: a rewriting type change has no safe form here.
+ * OKM1538 stays a warning, and only when the type change rewrites the table.
  */
 export declare const STEP_RULES: readonly StepRule[];
 /**
  * Type preferences. Warnings, read from the schema catalog by `okm check`.
  */
 export declare const COLUMN_RULES: readonly ColumnRule[];
+/**
+ * Collapses whitespace and lowercases SQL outside quoted identifiers.
+ *
+ * @param sql - One statement
+ * @returns The comparison form
+ */
+export declare function normalizedSql(sql: string): string;
+/**
+ * A create or alter of a domain, or a `LANGUAGE sql` function.
+ *
+ * Offline lint cannot see the reprint. The allow is still for that statement.
+ * `okm migrate check` decides whether the text actually differs.
+ *
+ * @param sql - One statement
+ * @returns `true` when OKM1552 can fire for this statement
+ */
+export declare function statementMayReprint(sql: string): boolean;

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, PlanStep } from "./plan.js";
 /** One finding. `place` is `step N`, `step N statement M`, or `table.column`. */
 export type Finding = {
     readonly severity: LintSeverity;
@@ -26,6 +26,19 @@ export type Finding = {
  * @returns Findings in step order, then code order
  */
 export declare function lintPlan(plan: MigrationPlan, before: Catalog, after: Catalog): readonly Finding[];
+/**
+ * Warns when a replayed domain check or `LANGUAGE sql` body reprints.
+ *
+ * Called from `okm migrate check` after introspection. A warning does not
+ * fail the command. An allow with an empty reason, or a code the replay did
+ * not trigger, is OKM1510.
+ *
+ * @param declared - Catalog stored with the migration
+ * @param stored - Catalog read back from the scratch schema
+ * @param steps - Statements of that migration, including `-- okm-allow`
+ * @returns Findings in catalog order
+ */
+export declare function lintReprints(declared: Catalog, stored: Catalog, steps: readonly PlanStep[]): readonly Finding[];
 /**
  * Lints type preferences on the author catalog.
  *

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

@@ -0,0 +1,18 @@
+/**
+ * Places a `schema()` catalog into the namespace from `defineConfig`.
+ *
+ * `schema()` compiles `public`. Planning reads this copy, so two catalogs
+ * on one database do not share table identities. An `external` table keeps
+ * the namespace from its snapshot. A catalog that is already `public` and
+ * has no external namespace is returned as itself, so its hash does not change.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+/**
+ * Rewrites managed objects into `namespace` and external tables into `externalNamespaces`.
+ *
+ * @param source - Catalog from `schema()`, after ownership is stamped
+ * @param namespace - Postgres schema this catalog owns. `public` is the default
+ * @param externalNamespaces - SQL table name to the owning catalog's namespace
+ * @returns `source` when nothing moves, otherwise a new catalog
+ */
+export declare function placeCatalog(source: Catalog, namespace: string, externalNamespaces: ReadonlyMap<string, string>): Catalog;