okmodel 0.8.0 → 0.9.1

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

@@ -0,0 +1,65 @@
+/**
+ * Machine-readable `okm migrate plan --json` (D279).
+ *
+ * The document is the plan the comment renderer reads. It is not parsed
+ * back out of the human SQL text.
+ */
+import type { MigrationClass } from "./classify.js";
+import type { Finding } from "./lint.js";
+import type { MigrationPlan, PlanStep } from "./plan.js";
+/** One step in a plan document. `lock` matches the human `-- lock:` line. */
+export type PlanStepJson = {
+    readonly class: MigrationClass;
+    readonly lock: string;
+    readonly sql: string;
+};
+/** One lint finding in a plan document. */
+export type PlanFindingJson = {
+    readonly severity: "error" | "warning";
+    readonly code: string;
+    readonly place: string;
+    readonly reason: string;
+    readonly fix: string;
+};
+/**
+ * What `okm migrate plan --json` prints.
+ *
+ * `class` is the strictest class, the same value as the human header.
+ */
+export type PlanDocument = {
+    readonly name: string;
+    readonly class: MigrationClass;
+    readonly steps: readonly PlanStepJson[];
+    readonly findings: readonly PlanFindingJson[];
+};
+/**
+ * Builds the document `okm migrate plan --json` prints.
+ *
+ * `lockText` is the same callback {@link formatPlan} uses, so a lock line
+ * that includes a row estimate is the same string in both outputs.
+ *
+ * @param plan - Plan the command already computed
+ * @param findings - Lint findings for that plan
+ * @param lockText - Annotated lock, when a target answered
+ * @returns The document
+ */
+export declare function planDocument(plan: MigrationPlan, findings: readonly Finding[], lockText?: (step: PlanStep) => string): PlanDocument;
+/**
+ * Serialises a plan document.
+ *
+ * @param plan - Plan the command already computed
+ * @param findings - Lint findings for that plan
+ * @param lockText - Annotated lock, when a target answered
+ * @returns JSON text ending in a newline
+ */
+export declare function formatPlanJson(plan: MigrationPlan, findings: readonly Finding[], lockText?: (step: PlanStep) => string): string;
+/**
+ * Reads a plan document.
+ *
+ * Extra fields are ignored. A missing field, or a class that is not
+ * `expand`, `contract`, or `unclassified`, is refused.
+ *
+ * @param text - JSON from `okm migrate plan --json`
+ * @returns The document
+ */
+export declare function parsePlanJson(text: string): PlanDocument;

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

@@ -56,17 +56,29 @@ export declare function assertTargetAlias(targets: readonly TargetRecord[]): voi
  * @param allowPooler - The invocation opted in
  */
 export declare function assertDirectConnection(url: string, allowPooler: boolean): void;
+/** Options for {@link assertStableBackend}. */
+export type StableBackendOptions = {
+    /**
+     * Holds another backend between pid reads so a LIFO transaction-mode
+     * pooler cannot hand the next read the same server. Resolves to a release
+     * function that ends the hold.
+     */
+    readonly holdBackend?: () => Promise<() => Promise<void>>;
+};
 /**
- * Refuses a session whose backend pid changes between two statements.
+ * Refuses a session whose backend pid changes across eight statements.
  *
- * The two reads are separate round trips and are not wrapped in a
- * transaction. A transaction-mode pooler can hand back a different backend
- * for the second one. `--allow-pooler` skips the probe.
+ * The reads are separate round trips and are not wrapped in a transaction.
+ * A transaction-mode pooler can hand back a different backend. Two reads
+ * miss a default PgBouncer with `server_round_robin=0` (LIFO); eight reads
+ * plus an optional hold between them catch that case. A direct session
+ * keeps one pid. `--allow-pooler` skips the probe.
  *
  * @param readPid - Reads `pg_backend_pid()` on the session under test
  * @param allowPooler - The invocation opted in
+ * @param options - Optional hold used by the migrate warm-and-hold probe
  */
-export declare function assertStableBackend(readPid: () => Promise<string>, allowPooler: boolean): Promise<void>;
+export declare function assertStableBackend(readPid: () => Promise<string>, allowPooler: boolean, options?: StableBackendOptions): Promise<void>;
 /**
  * Lists configured targets.
  *

package/dist/tooling/migrate/pooler-probe.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pid probe for transaction-mode poolers (B-41).
+ *
+ * Eight separate `pg_backend_pid()` reads on the caller's session. Two or
+ * more distinct pids mean a pooler handed out a new backend. A direct
+ * session keeps one pid.
+ *
+ * Warm-and-hold for LIFO PgBouncer (`server_round_robin=0`) needs extra
+ * connections and deadlocks a single-connection target (PGlite wire) when
+ * apply/seed already hold `max: 1`. That path stays in the PgBouncer test
+ * via {@link holdBackendBetweenReads}; production keeps URL heuristics plus
+ * these eight reads.
+ */
+import { type StableBackendOptions } from "./policy.js";
+/**
+ * Refuses a session whose backend pid changes across eight reads.
+ *
+ * @param _url - Target URL (unused; kept for call-site stability)
+ * @param readPid - Reads `pg_backend_pid()` on the session under test
+ * @param allowPooler - The invocation opted in
+ * @param options - Optional hold between reads (PgBouncer tests)
+ */
+export declare function probeStableBackend(_url: string, readPid: () => Promise<string>, allowPooler: boolean, options?: StableBackendOptions): Promise<void>;

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

@@ -46,12 +46,13 @@ export declare function generateProject(cwd: string, name: string, flags: readon
  * @param name - Plan name
  * @param flags - `--replace` values
  * @param invoke - Target and protection flags, when the command passed them
- * @returns The plan, its lint findings, and the text to print
+ * @returns The plan, its lint findings, the human text, and the `--json` document. Both forms use the same lock lines
  */
 export declare function planProject(cwd: string, name: string, flags: readonly string[], invoke?: InvokeFlags): Promise<{
     readonly plan: MigrationPlan;
     readonly findings: readonly Finding[];
     readonly text: string;
+    readonly json: string;
 }>;
 /**
  * Validates the schema, then reports stale renames and unlisted table files.
@@ -113,6 +114,14 @@ export declare function openProject(cwd: string): Promise<{
  * @returns The built schema, with roles attached when the config declares them
  */
 export declare function loadBuiltSchema(cwd: string, config: MigrateConfig): Promise<Built>;
+/**
+ * Prints or writes the catalog snapshot.
+ *
+ * @param cwd - Project directory
+ * @param args - Arguments after `export`
+ * @returns Stdout
+ */
+export declare function exportProject(cwd: string, args: readonly string[]): Promise<string>;
 /**
  * Loads `okmodel.config.ts`.
  *

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

@@ -0,0 +1,98 @@
+/**
+ * Turns an introspected catalog into table files and a schema file.
+ *
+ * `schema()` is the only writer. Functions, triggers, and views are written
+ * beside the tables. A kind it cannot store is returned, with the SQL the
+ * catalog already holds, and is not guessed.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type RoutinePlan, type RoutineVerdict } from "./pull-routines.js";
+/** One file `okm pull` writes. */
+export type PullFile = {
+    /** Absolute path. */
+    readonly path: string;
+    /** Source text, before the project formatter runs. */
+    readonly text: string;
+};
+/** One object the schema file does not declare. */
+export type PullSkip = {
+    /** {@link identityKey} of the catalog object. */
+    readonly key: string;
+    /** Catalog kind, or `column` for a type `table()` cannot build. */
+    readonly kind: string;
+    /** `table.column`, or the object name. */
+    readonly label: string;
+    /** Why this step left it out. */
+    readonly reason: string;
+    /** SQL from the catalog. Empty when the kind has no statement of its own. */
+    readonly sql: string;
+};
+/** Where the schema file and the table files go. */
+export type PullLayout = {
+    /** Absolute path of the schema module. */
+    readonly schemaFile: string;
+    /** Absolute directory of one file per table. */
+    readonly tablesDir: string;
+};
+/** Files to write, and the objects those files leave out. */
+export type PullEmission = {
+    readonly files: readonly PullFile[];
+    readonly skipped: readonly PullSkip[];
+    /** Scratch results for the routines the files declare. */
+    readonly verdicts: readonly RoutineVerdict[];
+    readonly counts: {
+        readonly tables: number;
+        readonly functions: number;
+        readonly triggers: number;
+        readonly views: number;
+        readonly materializedViews: number;
+    };
+};
+/** A kind the catalog cannot store, counted for the report. */
+export type PullCount = {
+    readonly kind: string;
+    readonly count: number;
+    readonly reason: string;
+};
+/** Scratch verdicts and the kinds the catalog has no object for. */
+export type PullReview = {
+    readonly plan: RoutinePlan;
+    readonly verdicts: readonly RoutineVerdict[];
+    readonly unexpressed: readonly PullCount[];
+};
+/**
+ * Writes one table module per table and the schema module that imports them.
+ *
+ * Column order, import order, and option keys are sorted, so the same catalog
+ * produces the same text.
+ *
+ * @param source - Catalog from introspection, logical namespace `public`
+ * @param layout - Schema file and tables directory
+ * @param review - Scratch verdicts. Omitted marks every function candidate-only
+ * @returns The files and the objects they do not declare
+ */
+export declare function emitPull(source: Catalog, layout: PullLayout, review?: PullReview): PullEmission;
+/**
+ * Text `okm pull` prints.
+ *
+ * Deferred kinds and kinds the catalog cannot store are always listed,
+ * including a count of zero, so a kind is not dropped without a line.
+ * Each pulled function is `verified`, `candidate-only`, or `unverified`.
+ *
+ * @param counts - Objects the files declare
+ * @param skipped - Objects the files leave out
+ * @param verdicts - Scratch results. Empty when no routine was pulled
+ * @param unexpressed - Aggregates, procedures, event triggers, and rules
+ * @param verb - `imported` for `okm import drizzle`. `pulled` is `okm pull`
+ * @returns The report, with a trailing newline
+ */
+export declare function formatPullReport(counts: PullEmission["counts"], skipped: readonly PullSkip[], verdicts?: readonly RoutineVerdict[], unexpressed?: readonly PullCount[], verb?: "pulled" | "imported"): string;
+/**
+ * SQL table name to the binding `table()` writes.
+ *
+ * A partitioned table is omitted. The binding matches the table file.
+ *
+ * @param source - Introspected catalog
+ * @returns Bindings for tables this step writes
+ */
+export declare function tableExportNames(source: Catalog): ReadonlyMap<string, string>;

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

@@ -0,0 +1,126 @@
+/**
+ * Plans `fn()`, `trigger()`, `view()`, and `materializedView()` for `okm pull`.
+ *
+ * Views and `BEGIN ATOMIC` bodies take edges the catalog already read from
+ * `pg_depend`. A plpgsql or SQL-string body gets table candidates from
+ * {@link sqlIdentifiers}. A view or a function named in that body is an
+ * ordering edge only: `dependsOn` accepts tables and columns. A view query
+ * is matched the same way, so a view over a view waits for the view it names
+ * when `pg_depend` recorded no column edge.
+ */
+import type { Catalog, FunctionObject, IndexObject, MaterializedViewObject, ObjectIdentity, TriggerObject, ViewObject } from "../../contracts/catalog/types.js";
+/** Why a pulled routine is marked the way it is. */
+export type RoutineStatus = "verified" | "candidate-only" | "unverified";
+/** One function, trigger, or view after the scratch replay. */
+export type RoutineVerdict = {
+    /** {@link identityKey} of the catalog object. */
+    readonly key: string;
+    /** Catalog kind. */
+    readonly kind: "function" | "trigger" | "view" | "materializedView";
+    /** Report label. */
+    readonly label: string;
+    /** What the scratch run proved. */
+    readonly status: RoutineStatus;
+    /** Postgres error, or why the scratch schema did not run. Empty when proved or candidate-only. */
+    readonly detail: string;
+};
+/** One object the schema file does not declare. Shape matches the pull skip. */
+export type RoutineSkip = {
+    readonly key: string;
+    readonly kind: string;
+    readonly label: string;
+    readonly reason: string;
+    readonly sql: string;
+};
+/** A function the schema file will declare. */
+export type PlannedFunction = {
+    readonly object: FunctionObject;
+    /** Binding in the schema file. */
+    readonly binding: string;
+    /** Source fragments inside `dependsOn: [...]`. */
+    readonly dependsOn: readonly string[];
+};
+/** A trigger the schema file will declare. */
+export type PlannedTrigger = {
+    readonly object: TriggerObject;
+    readonly binding: string;
+    /** Table binding passed to `on`. */
+    readonly on: string;
+    /** Function binding passed to `calls`. */
+    readonly calls: string;
+};
+/** A view or materialized view the schema file will declare. */
+export type PlannedView = {
+    readonly object: ViewObject | MaterializedViewObject;
+    readonly binding: string;
+    /** Indexes `materializedView()` can store. Expression indexes are skipped. */
+    readonly indexes: readonly IndexObject[];
+};
+/**
+ * Routines to write, and the extra edges the scratch replay orders by.
+ *
+ * `orderEdges` are not written. `dependsOn` cannot name a view or a function.
+ */
+export type RoutinePlan = {
+    readonly functions: readonly PlannedFunction[];
+    readonly triggers: readonly PlannedTrigger[];
+    readonly views: readonly PlannedView[];
+    readonly skipped: readonly RoutineSkip[];
+    /** Identity key to edges added for the scratch order only. */
+    readonly orderEdges: ReadonlyMap<string, readonly ObjectIdentity[]>;
+};
+/** Bindings and declarations inserted into the schema file. */
+export type RenderedRoutines = {
+    readonly imports: readonly string[];
+    readonly body: string;
+    readonly functions: readonly string[];
+    readonly triggers: readonly string[];
+    readonly views: readonly string[];
+};
+/**
+ * Chooses which routines to write and which names `dependsOn` can cite.
+ *
+ * @param source - Introspected catalog
+ * @param tableExports - SQL table name to the binding `table()` writes
+ * @returns The plan. Comments are applied later, from the scratch verdicts
+ */
+export declare function planRoutines(source: Catalog, tableExports: ReadonlyMap<string, string>): RoutinePlan;
+/**
+ * Renders the schema-file text for a plan.
+ *
+ * A missing verdict is candidate-only for a function and unverified for a
+ * view or a trigger. That is what a scratch run that did not happen can say.
+ *
+ * @param plan - Routines to write
+ * @param verdicts - Scratch results, keyed by {@link identityKey}
+ * @returns Imports, bindings, and the `schema()` lists
+ */
+export declare function renderRoutines(plan: RoutinePlan, verdicts: ReadonlyMap<string, RoutineVerdict>): RenderedRoutines;
+/**
+ * Verdicts for a plan when the scratch schema was not created.
+ *
+ * Nothing is verified. A plpgsql function stays candidate-only. A SQL
+ * function, a view, and a trigger are unverified.
+ *
+ * @param plan - Routines that would have been replayed
+ * @param detail - Why the scratch schema was not created
+ * @returns One verdict per planned routine
+ */
+export declare function verdictsWithoutScratch(plan: RoutinePlan, detail: string): readonly RoutineVerdict[];
+/**
+ * Tables, views, and functions named in `body`.
+ *
+ * Unquoted names fold to lower case. A quoted name matches the stored spelling.
+ * The function's own name is included; the caller drops a self-edge.
+ *
+ * @param body - Function body or view query
+ * @param tables - Pulled tables
+ * @param views - Pulled views and materialized views
+ * @param functions - Functions grouped by name
+ * @returns Matches, tables by SQL name and the other two as identities
+ */
+export declare function matchNames(body: string, tables: ReadonlyMap<string, ObjectIdentity>, views: ReadonlyMap<string, ViewObject | MaterializedViewObject>, functions: ReadonlyMap<string, readonly FunctionObject[]>): {
+    readonly tables: readonly string[];
+    readonly views: readonly ObjectIdentity[];
+    readonly functions: readonly ObjectIdentity[];
+};

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,65 @@
+/**
+ * `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.
+ *
+ * When `oxfmt` is missing or fails, the files stay as written and a notice is
+ * printed on stderr. The pull or import report still returns.
+ *
+ * @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/runner.d.ts

@@ -7,6 +7,7 @@
  * `okm_backfill` after each commit.
  */
 import type { DriverConnection } from "../../contracts/driver.js";
+import { OkmError } from "../../contracts/error.js";
 import type { PlanStep } from "./plan.js";
 /** One step with its index in the migration file. */
 export type RunnableStep = {
@@ -79,7 +80,9 @@ export declare function runTarget(connection: DriverConnection, run: TargetRun,
 /**
  * Assumes `role` for the rest of this connection.
  *
- * A second call with the same role does nothing.
+ * A second call with the same role does nothing. A non-superuser that created
+ * the role with `CREATEROLE` is granted membership first: Postgres 15 creates
+ * no membership row, and Postgres 16+ grants `ADMIN` without `SET`.
  *
  * @param connection - Reserved connection
  * @param role - Migration role
@@ -88,6 +91,15 @@ export declare function runTarget(connection: DriverConnection, run: TargetRun,
 export declare function assumeRole(connection: DriverConnection, role: string, session: {
     setRole?: string;
 }): Promise<void>;
+/**
+ * Maps a Postgres role-privilege refusal to a clear `OkmError`.
+ *
+ * @param error - Driver failure
+ * @param role - Role named in the step, when known
+ * @returns A forbidden error that names CREATEROLE or the SET option, or
+ *   `undefined` when the failure is something else
+ */
+export declare function rolePrivilegeError(error: unknown, role?: string): OkmError | undefined;
 /**
  * Lets a new migration role create objects in `schema`.
  *
@@ -110,6 +122,17 @@ export declare function grantAppMeta(connection: DriverConnection, role: string
     setRole?: string;
 }): Promise<void>;
 export declare function grantSchema(connection: DriverConnection, schema: string, role: string): Promise<void>;
+/**
+ * Makes `role` the owner of `schema` when the connecting role can.
+ *
+ * Grants on the schema to reporting and other roles need the migration role
+ * to own it. A connecting role that is not the owner leaves the schema as is.
+ *
+ * @param connection - Reserved connection, before `SET ROLE`
+ * @param schema - Schema the migration writes
+ * @param role - Migration role that was just created
+ */
+export declare function ownSchema(connection: DriverConnection, schema: string, role: string): Promise<void>;
 /**
  * Fails when `GRANT USAGE ON SCHEMA` did not add the role.
  *

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/{ppnnnvj8.js → 09a6vsys.js}

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