okmodel 0.7.0 → 0.9.0

package/dist/tooling/driver-test.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `okm driver test`.
+ *
+ * The runner lives in the harness and reuses the conformance suites. This
+ * file only finds that runner and prints what it writes. Tooling does not
+ * import the harness.
+ */
+/**
+ * Runs the conformance suites for the driver named on the command line.
+ *
+ * `<driver>` is `pglite`, `postgresjs`, `pg`, `bun`, `neon`, or a module path.
+ * `--url` is the Postgres URL. `pglite` does not use it. The other built-in
+ * drivers need `--url` or `DATABASE_URL`. A module whose export sets
+ * `memory: true` does not need a URL.
+ *
+ * The report is one header (`driver`, `dialect postgres`) and one row per
+ * case: id, behavior, result (`pass`, `fail`, or `unsupported`), and the
+ * capability when the result is unsupported. A failure exits through
+ * {@link OkmError}. An unsupported case does not.
+ *
+ * @param args - Arguments after `driver test`
+ * @param stdout - Where the report is written
+ */
+export declare function driverTest(args: readonly string[], stdout: (text: string) => void): Promise<void>;
+/**
+ * Path of the `okm driver test` runner.
+ *
+ * A source checkout finds `packages/harness/src/driver-run.ts` and the
+ * command spawns `bun`. The packed build writes
+ * `dist/tooling/driver-run.js`. Splitting puts this module in
+ * `dist/shared/`, so that file is one directory up from the chunk.
+ *
+ * @param here - Directory of this module
+ * @returns Runner path. The caller checks that the file exists
+ */
+export declare function driverRunnerPath(here: string): string;

package/dist/tooling/github/comment.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pull-request comment for `okm migrate plan --json` (D279).
+ *
+ * The text comes from the plan document. It does not read the human plan.
+ */
+import { type PlanDocument } from "../migrate/plan-json.js";
+/**
+ * Hidden marker that identifies the sticky comment.
+ *
+ * A later push updates the comment whose body contains this marker.
+ */
+export declare const PLAN_COMMENT_MARKER = "<!-- okmodel-migrate-plan -->";
+/** A comment the sticky update may replace. */
+export type StickyComment = {
+    readonly id: number;
+    readonly body: string;
+};
+/**
+ * Renders the plan comment.
+ *
+ * The first heading is the strictest class. Each step is one table row
+ * with its class and lock. The lock is the plan's lock line, including a
+ * row estimate when the plan printed one. Lint findings keep their codes.
+ *
+ * @param plan - Document from `okm migrate plan --json`
+ * @returns Markdown, including {@link PLAN_COMMENT_MARKER}
+ */
+export declare function renderPlanComment(plan: PlanDocument): string;
+/**
+ * Comment body for a plan file, or a status line when the file is not a document.
+ *
+ * The status line records exit codes only. It does not include command text.
+ *
+ * @param text - Stdout of `okm migrate plan --json`, when the file exists
+ * @param checkStatus - Exit code of `okm migrate check`
+ * @param planStatus - Exit code of `okm migrate plan --json`
+ * @returns The comment body
+ */
+export declare function planCommentBody(text: string | undefined, checkStatus: string, planStatus: string): string;
+/**
+ * The comment to update, when one already carries the marker.
+ *
+ * The first match wins. A missing match means the caller creates a comment.
+ *
+ * @param comments - Comments already on the pull request
+ * @returns The id to update, or `undefined` to create one
+ */
+export declare function stickyCommentTarget(comments: readonly StickyComment[]): {
+    readonly updateId: number;
+} | undefined;

package/dist/tooling/github/post-comment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates or updates the sticky plan comment (D279).
+ *
+ * Uses `GITHUB_TOKEN` only. The workflow needs `pull-requests: write`.
+ * The token is not written to stdout or stderr.
+ */
+/**
+ * Posts the plan comment for one pull request.
+ *
+ * An existing comment that contains the marker is updated. Otherwise a
+ * comment is created. The body comes from {@link planCommentBody}.
+ *
+ * @param planPath - File written by `okm migrate plan --json`
+ * @param checkStatus - Exit code of `okm migrate check`
+ * @param planStatus - Exit code of `okm migrate plan --json`
+ */
+export declare function postPlanComment(planPath: string, checkStatus: string, planStatus: string): Promise<void>;

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

@@ -22,8 +22,9 @@ 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`, and
- * `migrate plan`, `apply`, `status`, and `check`.
+ * `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
  * @param io - Working directory and stdout. Defaults to the process

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/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,78 @@
-import"../../shared/14vx95q4.js";
-import"../../shared/qq3899ht.js";
+import {
+  serializeCatalog2,
+  parseCatalog2
+} from "../../shared/12z7aznj.js";
+import"../../shared/fk9vef30.js";
+import"../../shared/dd5pmnky.js";
 import"../../shared/n442h54c.js";
 import {
   applyTarget2,
   backfillTiming2
-} from "../../shared/p6qc5gcp.js";
+} from "../../shared/ccsmhv9r.js";
 import {
   readReference
-} from "../../shared/m6p12kbr.js";
-import"../../shared/8skf0cam.js";
-import"../../shared/b5pftnn2.js";
+} from "../../shared/3456242y.js";
+import"../../shared/jpybhf98.js";
+import"../../shared/myk8fswx.js";
 import {
   projectPath,
+  LOGICAL_FORMAT,
   loadMigrations,
   loadHeadSnapshot,
   loadBuiltSchema,
   loadConfig
-} from "../../shared/gs74dbj5.js";
+} from "../../shared/2zdxkt7b.js";
 import {
   assertTargetPolicy,
   selectTarget
-} from "../../shared/tsvww22q.js";
-import"../../shared/9s0ypp87.js";
+} from "../../shared/6nae0spm.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 +114,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;