okmodel 0.3.0 → 0.4.0

package/dist/shared/{1tfdfvhh.js → yjw02enp.js}

@@ -1,10 +1,12 @@
-import"./t616ynfn.js";
+import"./8jb4ymh2.js";
 import"./n442h54c.js";
+import"./wqem4jed.js";
 import {
   listTargets,
   loadConfig
-} from "./5nmdenb6.js";
-import"./2ssqrv66.js";
+} from "./q6zsyh31.js";
+import"./n5y9zyj1.js";
+import"./41kv2xdm.js";
 
 // src/tooling/migrate/dev.ts
 import { mkdirSync } from "node:fs";
@@ -17,7 +19,7 @@ async function devProject(cwd) {
 `;
   const directory = join(cwd, config.out ?? ".okm", "dev-db");
   mkdirSync(directory, { recursive: true });
-  const { open } = await import("./kgnc8grt.js");
+  const { open } = await import("./gdh9mrtp.js");
   const pool = await open({ dataDir: directory });
   try {
     await pool.execute("select 1");

package/dist/shared/{ydaz1sv3.js → zg24x0hm.js}

@@ -3,7 +3,7 @@ import {
   readHandle,
   readCall,
   attachHttp
-} from "./k34e0xf2.js";
+} from "./kkzwp3d2.js";
 import {
   fail
 } from "./xrfnq5k8.js";

package/dist/tooling/cli.js

@@ -1,14 +1,17 @@
-import"../shared/t616ynfn.js";
+import"../shared/8jb4ymh2.js";
 import"../shared/n442h54c.js";
+import"../shared/wqem4jed.js";
 import {
+  formatFindings,
+  hasError,
+  lintRefusal,
   buildProject,
   generateProject,
   planProject,
   checkProject
-} from "../shared/5nmdenb6.js";
-import {
-  formatPlan
-} from "../shared/2ssqrv66.js";
+} from "../shared/q6zsyh31.js";
+import"../shared/n5y9zyj1.js";
+import"../shared/41kv2xdm.js";
 import {
   OkmError2
 } from "../shared/52szzakm.js";
@@ -35,26 +38,31 @@ async function run(argv, io) {
     return;
   }
   if (command === "check") {
-    await checkProject(cwd, invoke(splitFlags(rest)));
+    const findings = await checkProject(cwd, invoke(splitFlags(rest)));
+    const warnings = formatFindings(findings);
+    if (warnings.length > 0)
+      stdout(warnings);
     stdout(`ok
 `);
     return;
   }
   if (command === "generate") {
     const parsed = splitFlags(rest);
-    const path = await generateProject(cwd, parsed.name ?? "migration", parsed.flags);
-    stdout(path === undefined ? `no changes
-` : `${path}
+    const written = await generateProject(cwd, parsed.name ?? "migration", parsed.flags);
+    stdout(written === undefined ? `no changes
+` : `${written.path}
 `);
+    if (written !== undefined)
+      stdout(formatFindings(written.findings));
     return;
   }
   if (command === "dev") {
-    const { devProject } = await import("../shared/1tfdfvhh.js");
+    const { devProject } = await import("../shared/yjw02enp.js");
     stdout(await devProject(cwd));
     return;
   }
   if (command === "push") {
-    const { pushProject } = await import("../shared/dbjej1tw.js");
+    const { pushProject } = await import("../shared/kj680nxv.js");
     stdout(await pushProject(cwd, invoke(splitFlags(rest))));
     return;
   }
@@ -65,23 +73,44 @@ async function run(argv, io) {
       if (parsed.name === undefined) {
         throw new OkmError2("invalid", "okm migrate plan needs a name.");
       }
-      stdout(formatPlan(await planProject(cwd, parsed.name, parsed.flags)));
+      const planned = await planProject(cwd, parsed.name, parsed.flags, invoke(parsed));
+      stdout(planned.text);
+      stdout(formatFindings(planned.findings));
+      if (hasError(planned.findings))
+        throw lintRefusal(planned.findings);
       return;
     }
     if (sub === "apply") {
-      const { applyProject } = await import("../shared/dbjej1tw.js");
-      stdout(await applyProject(cwd, invoke(parsed)));
+      const { applyProject } = await import("../shared/kj680nxv.js");
+      stdout(await applyProject(cwd, invoke(parsed), stdout));
       return;
     }
     if (sub === "status") {
-      const { statusProject } = await import("../shared/scwxrpx2.js");
+      const { statusProject } = await import("../shared/c5g81ngb.js");
       stdout(await statusProject(cwd, invoke(parsed)));
       return;
     }
+    if (sub === "check") {
+      const { checkMigrations } = await import("../shared/2321avmn.js");
+      const provision = parsed.flags.includes("--provision") || rest.slice(1).includes("--provision");
+      stdout(await checkMigrations(cwd, invoke(parsed), { provision }));
+      return;
+    }
+  }
+  if (command === "seed") {
+    const parsed = splitFlags(rest);
+    if (parsed.name === undefined) {
+      throw new OkmError2("invalid", "okm seed needs a file.", {
+        fix: { summary: "Pass okm seed <file>." }
+      });
+    }
+    const { seedProject } = await import("../shared/ady1ms74.js");
+    stdout(await seedProject(cwd, parsed.name, invoke(parsed)));
+    return;
   }
   if (command === "doctor") {
     const parsed = splitFlags(rest);
-    const { doctorProject } = await import("../shared/ne02ng5c.js");
+    const { doctorProject } = await import("../shared/84ptn35q.js");
     stdout(await doctorProject(cwd, parsed.name, invoke(parsed)));
     return;
   }
@@ -93,7 +122,7 @@ async function run(argv, io) {
       });
     }
     if (sub === "list" || sub === "check") {
-      const { extProject } = await import("../shared/meck53jv.js");
+      const { extProject } = await import("../shared/tny2t3sm.js");
       stdout(await extProject(cwd, sub, invoke(splitFlags(rest.slice(1)))));
       return;
     }

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

@@ -3,9 +3,14 @@
  *
  * A run holds a session advisory lock. Transactional steps of one migration
  * share a transaction. Steps Postgres cannot run there (`CREATE INDEX
- * CONCURRENTLY`, `ADD VALUE`, `VACUUM`) are their own steps. Each finished
- * step is a history row. A later apply skips those rows.
+ * CONCURRENTLY`, `ADD VALUE`, `VACUUM`) and backfill steps are their own
+ * units. {@link runTarget} runs those units. Each finished step is a history
+ * row. A later apply skips those rows. A backfill records each committed
+ * batch in `okm_backfill` and resumes from that boundary.
  */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type BackfillBatch } from "./runner.js";
+import { type ReferenceTable } from "./reference.js";
 import { type PlanStep } from "./plan.js";
 import type { StoredMigration } from "./files.js";
 import { type InvokeFlags } from "./policy.js";
@@ -51,6 +56,35 @@ export type ApplyRequest = {
      * on this schema before `SET ROLE`. The default is `public`.
      */
     readonly schema?: string;
+    /** Milliseconds to wait after each committed backfill batch. */
+    readonly backfillPauseMs?: number;
+    /** `statement_timeout` for one backfill batch. Falls back to {@link ApplyRequest.statementTimeoutMs}. */
+    readonly backfillStatementTimeoutMs?: number;
+    /** One line after each committed backfill batch. */
+    readonly onProgress?: (line: string) => void;
+    /** Runs after each committed backfill batch, before the pause. */
+    readonly afterBatch?: (batch: BackfillBatch) => void | Promise<void>;
+    /**
+     * Migrations directory to lint before any DDL.
+     *
+     * Only a migration with a step missing from `okm_history` is checked.
+     * `push` omits this: its steps are not files.
+     */
+    readonly lintDirectory?: string;
+    /**
+     * Head snapshot.
+     *
+     * Set by `okm migrate apply` and `provision()`. An empty target installs
+     * this catalog instead of replaying files. `only` refuses a target that
+     * is not empty (OKM1851) and does not fall through to replay.
+     */
+    readonly snapshot?: {
+        readonly catalog: Catalog;
+        readonly migrationId: string;
+        readonly catalogHash: string;
+        readonly reference: readonly ReferenceTable[];
+        readonly only?: boolean;
+    };
 };
 /** Migrations that ran at least one step in this invocation. */
 export type ApplyReport = {
@@ -74,8 +108,9 @@ export declare function applyUnits(migration: StoredMigration, done: ReadonlySet
  * Applies pending migrations on one target.
  *
  * The connection is reserved for the whole run so the advisory lock stays
- * session-scoped. Lock timeout retries that step. Any other failure stops
- * at that step.
+ * session-scoped. Lock timeout retries that step, including `NOT VALID`,
+ * `VALIDATE CONSTRAINT`, `SET NOT NULL`, `ADD CONSTRAINT … USING INDEX`, and
+ * a concurrent index create or drop. Any other failure stops at that step.
  *
  * @param request - Target, flags, and the migrations to consider
  * @returns The target and the migration ids that ran
@@ -84,11 +119,15 @@ export declare function applyTarget(request: ApplyRequest): Promise<ApplyReport>
 /**
  * Applies the migrations in the project to the selected target.
  *
+ * Pending migrations are linted after `okm_history` is read and before any
+ * DDL. A migration the target already applied is left as it ran.
+ *
  * @param cwd - Project directory
  * @param flags - `--target`, protection, pooler, and timeouts
+ * @param write - Receives each backfill progress line, including the newline
  * @returns Text for stdout, including the target name
  */
-export declare function applyProject(cwd: string, flags: InvokeFlags): Promise<string>;
+export declare function applyProject(cwd: string, flags: InvokeFlags, write?: (text: string) => void): Promise<string>;
 /**
  * Prototype sync. Blocked on a protected target.
  *
@@ -100,3 +139,18 @@ export declare function applyProject(cwd: string, flags: InvokeFlags): Promise<s
  * @returns Text for stdout
  */
 export declare function pushProject(cwd: string, flags: InvokeFlags): Promise<string>;
+/**
+ * Pause and statement timeout `defineConfig({ backfill })` sets for a run.
+ *
+ * Omitted fields stay unset so the runner uses its built-in defaults.
+ *
+ * @param backfill - Config block, when the project set one
+ * @returns The fields {@link applyTarget} reads
+ */
+export declare function backfillTiming(backfill: {
+    readonly pauseMs?: number;
+    readonly statementTimeoutMs?: number;
+} | undefined): {
+    readonly backfillPauseMs?: number;
+    readonly backfillStatementTimeoutMs?: number;
+};

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

@@ -0,0 +1,136 @@
+/**
+ * Backfill step header and the per-batch predicate (D195).
+ *
+ * The migration file keeps one `UPDATE`. `-- backfill` names the table, the
+ * primary key, and the batch size. `$1` is the exclusive lower bound and `$2`
+ * is the inclusive upper bound. Null means that side is open. The runner
+ * fills those bounds. This module does not run the batches.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+/**
+ * Rows in one batch when the plan and the config omit `batchSize`.
+ *
+ * A step header `batch=` replaces this for that step.
+ */
+export declare const DEFAULT_BACKFILL_BATCH_SIZE = 1000;
+/**
+ * Milliseconds to wait after a committed batch when the config omits `pauseMs`.
+ *
+ * Zero runs the next batch immediately. Set a pause to rate-limit a large table.
+ */
+export declare const DEFAULT_BACKFILL_PAUSE_MS = 0;
+/**
+ * `statement_timeout` for one batch when the config omits `statementTimeoutMs`.
+ *
+ * This is separate from the apply timeout on DDL. A timed-out batch rolls
+ * back and leaves the previous checkpoint.
+ */
+export declare const DEFAULT_BACKFILL_STATEMENT_TIMEOUT_MS = 30000;
+/** One primary-key column, quoted, with the catalog type used as a cast. */
+export type BackfillColumn = {
+    /** Quoted identifier. */
+    readonly quoted: string;
+    /** Catalog `dataType`, safe to place after `::`. */
+    readonly dataType: string;
+};
+/**
+ * What `-- backfill` records.
+ *
+ * `key` is quoted identifiers in primary-key order. Types live in the
+ * statement's casts, not in the header.
+ */
+export type BackfillSpec = {
+    /** Quoted schema-qualified table, as in the statement. */
+    readonly table: string;
+    /** Quoted key columns. */
+    readonly key: readonly string[];
+    /** Rows per batch. The header value, which overrides config. */
+    readonly batch: number;
+};
+/**
+ * Batch size the planner writes into a new step.
+ *
+ * @param requested - `defineConfig({ backfill: { batchSize } })`, when set
+ * @returns A positive integer. The built-in default is 1000
+ */
+/**
+ * Field for {@link resolveBatchSize} when the config may omit it.
+ *
+ * Exact optional properties reject `batchSize: undefined`.
+ *
+ * @param batchSize - Configured size, when set
+ * @returns `{ batchSize }` or an empty object
+ */
+export declare function batchSizeField(batchSize: number | undefined): {
+    readonly batchSize: number;
+} | Record<string, never>;
+/**
+ * Batch size the planner writes into a new step.
+ *
+ * @param requested - `defineConfig({ backfill: { batchSize } })`, when set
+ * @returns A positive integer. The built-in default is 1000
+ */
+export declare function resolveBatchSize(requested: number | undefined): number;
+/**
+ * Prints the header comment.
+ *
+ * @param spec - Table, key, and batch size
+ * @returns One line, without a trailing newline
+ */
+export declare function formatBackfillHeader(spec: BackfillSpec): string;
+/**
+ * Reads a `-- backfill` line.
+ *
+ * @param line - One comment line
+ * @returns The spec, or `undefined` when the line is not a backfill header
+ */
+export declare function parseBackfillHeader(line: string): BackfillSpec | undefined;
+/**
+ * Primary key of `table`, or OKM1546 when the table has none.
+ *
+ * A backfill walks this key. It does not count rows and it does not scan.
+ *
+ * @param catalogs - Before and after catalogs. The first key found wins
+ * @param table - Unqualified table name
+ * @returns Columns in key order, with cast types
+ */
+export declare function primaryKeyColumns(catalogs: readonly Catalog[], table: string): readonly BackfillColumn[];
+/**
+ * Predicate that limits an idempotent `UPDATE` to one key range.
+ *
+ * `$1` is exclusive and `$2` is inclusive. Either null leaves that side open.
+ * One column compares as itself. A composite key compares as a row, with the
+ * bound stored as a JSON array of text.
+ *
+ * @param columns - Primary key in order
+ * @returns SQL fragment with no leading `and`
+ */
+export declare function keyRangePredicate(columns: readonly BackfillColumn[]): string;
+/**
+ * How many batches `rows` take at `batch` size.
+ *
+ * Zero rows is zero batches. The count is `ceil(rows / batch)`.
+ *
+ * @param rows - Estimated row count
+ * @param batch - Batch size from the step header
+ * @returns The batch count a plan line prints
+ */
+export declare function aboutBatchCount(rows: number, batch: number): number;
+/**
+ * Keyset query that returns the last key of the next batch.
+ *
+ * `$1` is the previous boundary, null for the first batch. `$2` is
+ * `batch - 1`. No row means this batch is the last one.
+ *
+ * @param table - Quoted schema-qualified table
+ * @param columns - Primary key, with cast types
+ * @returns One statement
+ */
+export declare function boundaryQuery(table: string, columns: readonly BackfillColumn[]): string;
+/**
+ * Cast spelling safe to interpolate after `::`.
+ *
+ * @param dataType - Catalog or `format_type` spelling
+ * @returns The same spelling
+ */
+export declare function checkedCast(dataType: string): string;

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

@@ -0,0 +1,65 @@
+/**
+ * `okm migrate check` proves a migration history is sound (D196).
+ *
+ * The command replays every file into a scratch schema through
+ * {@link applyTarget}, then plans the introspected schema back to that
+ * file's catalog. It also checks the previous catalog, the head, and the
+ * linter. Nothing here changes apply.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type MigrationClass } from "./classify.js";
+import { type MigrationPlan } from "./plan.js";
+import { type InvokeFlags } from "./policy.js";
+/** Prefix of the scratch schema. The random suffix makes the name unique. */
+export declare const CHECK_SCHEMA_PREFIX = "okm_check_";
+/**
+ * Runs `okm migrate check` for the project in `cwd`.
+ *
+ * A protected target is refused before any statement. The scratch schema is
+ * dropped before this returns, including when a check fails. `--allow-protected`
+ * does not lift the refusal.
+ *
+ * @param cwd - Project directory
+ * @param flags - `--target` and pooler. Protection is ignored
+ * @param options - `--provision` also compares a snapshot install with a full replay
+ * @returns One summary line, ending in a newline
+ */
+export declare function checkMigrations(cwd: string, flags: InvokeFlags, options?: {
+    readonly provision?: boolean;
+}): Promise<string>;
+/**
+ * Objects in `before` that `after` no longer satisfies.
+ *
+ * A table, column, constraint, or type that disappeared is a gap. A column
+ * whose type changed is a gap. Nullability tightened without a default is a
+ * gap. An added object is not.
+ *
+ * @param before - Previous release catalog
+ * @param after - Catalog the migration stores
+ * @returns One sentence per gap, in catalog order
+ */
+export declare function previousCatalogGaps(before: Catalog, after: Catalog): readonly string[];
+/**
+ * Class of a migration, from step kinds.
+ *
+ * A step with no kind is planned from `before` to `after` instead. The
+ * `-- class:` comment is not read.
+ *
+ * @param plan - Parsed migration file
+ * @param before - Catalog before the migration
+ * @param after - Catalog the file stores
+ * @returns The strictest recomputed class
+ */
+export declare function recomputedMigrationClass(plan: MigrationPlan, before: Catalog, after: Catalog): MigrationClass;
+/**
+ * Whether a previous-catalog gap is allowed.
+ *
+ * The recomputed class must be `contract`. A file whose steps are classified
+ * `expand`, including a hand-edited `-- class:` line, does not allow the gap.
+ *
+ * @param plan - Parsed migration file
+ * @param before - Catalog before the migration
+ * @param after - Catalog the file stores
+ * @returns `true` when the gap may stand
+ */
+export declare function migrationAllowsPreviousGaps(plan: MigrationPlan, before: Catalog, after: Catalog): boolean;

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

@@ -0,0 +1,108 @@
+/**
+ * Expand, contract, or raw SQL.
+ *
+ * `unclassified` is only for a statement the planner did not classify.
+ * The protected-target policy treats that the same as `contract`.
+ */
+export type MigrationClass = "expand" | "contract" | "unclassified";
+/**
+ * One operation the planner can emit.
+ *
+ * A new kind belongs in {@link STEP_CLASS}. The classification test lists
+ * every key, so a kind without a class fails that test.
+ */
+export declare const STEP_CLASS: {
+    readonly "create-table": "expand";
+    readonly "drop-table": "contract";
+    readonly "add-column": "expand";
+    readonly "add-column-required": "contract";
+    readonly "drop-column": "contract";
+    readonly "set-column-type": "contract";
+    readonly "set-not-null": "contract";
+    readonly "drop-not-null": "expand";
+    readonly "set-default": "expand";
+    readonly "drop-default": "contract";
+    readonly "add-identity": "expand";
+    readonly "drop-identity": "contract";
+    readonly "set-identity-always": "contract";
+    readonly "set-identity-by-default": "expand";
+    readonly "add-constraint": "expand";
+    readonly "validate-constraint": "expand";
+    readonly "drop-constraint": "contract";
+    readonly "drop-not-null-check": "expand";
+    readonly "rename-constraint": "contract";
+    readonly "widen-check": "expand";
+    readonly "narrow-check": "contract";
+    readonly "create-index": "expand";
+    readonly "drop-index": "contract";
+    readonly "rename-index": "contract";
+    readonly "create-sequence": "expand";
+    readonly "drop-sequence": "contract";
+    readonly "create-enum": "expand";
+    readonly "recreate-enum": "contract";
+    readonly "add-enum-value": "expand";
+    readonly "rename-enum": "contract";
+    readonly "drop-enum": "contract";
+    readonly "set-enum-column": "contract";
+    readonly "create-domain": "expand";
+    readonly "drop-domain": "contract";
+    readonly "add-domain-check": "expand";
+    readonly "validate-domain-check": "expand";
+    readonly "drop-domain-check": "contract";
+    readonly "rename-domain-check": "expand";
+    readonly "create-extension": "expand";
+    readonly "drop-extension": "contract";
+    readonly "update-extension": "expand";
+    readonly "move-extension": "contract";
+    readonly "create-function": "expand";
+    readonly "drop-function": "contract";
+    readonly "replace-function": "expand";
+    readonly "create-trigger": "expand";
+    readonly "drop-trigger": "contract";
+    readonly "create-view": "expand";
+    readonly "drop-view": "contract";
+    readonly "replace-view": "expand";
+    readonly "create-matview": "expand";
+    readonly "drop-matview": "contract";
+    readonly "refresh-matview": "expand";
+    readonly "create-role": "expand";
+    readonly "alter-role": "contract";
+    readonly grant: "expand";
+    readonly revoke: "contract";
+    readonly "grant-default": "expand";
+    readonly "revoke-default": "contract";
+    readonly "rename-table": "contract";
+    readonly "rename-column": "contract";
+    readonly "rename-sequence": "contract";
+    readonly "backfill-expand": "expand";
+    readonly "backfill-contract": "contract";
+    readonly "raw-sql": "unclassified";
+};
+/** A planner operation. */
+export type StepKind = keyof typeof STEP_CLASS;
+/** Every kind, in table order. */
+export declare const STEP_KINDS: readonly StepKind[];
+/**
+ * Class for one kind.
+ *
+ * @param kind - Planner operation
+ * @returns The class stored on the step
+ */
+export declare function classOf(kind: StepKind): MigrationClass;
+/**
+ * Strictest class in a plan.
+ *
+ * `contract` wins over `unclassified`, which wins over `expand`. An empty
+ * list is `expand`.
+ *
+ * @param classes - One class per step
+ * @returns The class of the plan header
+ */
+export declare function strictestClass(classes: readonly MigrationClass[]): MigrationClass;
+/**
+ * Reports whether a plan comment names a kind.
+ *
+ * @param value - Text after `-- kind: `
+ * @returns `true` when the text is a {@link StepKind}
+ */
+export declare function isStepKind(value: string): value is StepKind;

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

@@ -23,8 +23,8 @@ export declare function formatFailure(error: OkmError): string;
  * Runs one `okm` invocation.
  *
  * `--version` stays in the bin. This function handles `build`, `check`,
- * `generate`, `dev`, `push`, `ext list`, `ext check`, `doctor`, and `migrate plan`,
- * `apply`, and `status`.
+ * `generate`, `dev`, `push`, `seed`, `ext list`, `ext check`, `doctor`, 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

@@ -36,6 +36,28 @@ export type MigrateConfig = {
         readonly lock?: number;
         readonly statement?: number;
     };
+    /**
+     * First migration id that `okm migrate check` lints.
+     *
+     * Files before this id in apply order are the adoption baseline: a project
+     * that turns the linter on later does not fail on old unreasoned drops.
+     * The id itself is linted. `okm migrate apply` still lints every pending
+     * migration.
+     */
+    readonly lintFrom?: string;
+    /**
+     * Batched backfill (D195).
+     *
+     * `batchSize` is what a new plan writes as `batch=`. A step header overrides
+     * it at apply time. `pauseMs` waits between committed batches. `statementTimeoutMs`
+     * is `statement_timeout` for each batch. Omitted fields use the built-in
+     * defaults: 1000 rows, no pause, and 30 seconds.
+     */
+    readonly backfill?: {
+        readonly batchSize?: number;
+        readonly pauseMs?: number;
+        readonly statementTimeoutMs?: number;
+    };
     /**
      * Migration role and application role.
      *

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

@@ -11,6 +11,9 @@ import { type InvokeFlags } from "./policy.js";
 /**
  * Explains one code, or lists the triggers on each table.
  *
+ * A role check connects as the read-only `check` class. A protected target
+ * is allowed. The command does not change the database.
+ *
  * @param cwd - Project directory
  * @param code - Spec code, when the caller passed one
  * @returns Text for stdout, including the trailing newline

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

@@ -4,10 +4,12 @@
  * A database that has never been pushed has no `okm_meta` and is left alone.
  * After push, the introspected catalog is planned back to the schema. Each
  * view is reprinted on this server first, so a `pg_get_viewdef` spelling is
- * not drift. Any remaining statement is OKM1520. `okm_meta` and `okm_history`
- * are omitted by the planner.
+ * not drift. Any remaining statement is OKM1520. `okm_meta`, `okm_history`,
+ * and `okm_backfill` are omitted by the planner.
  */
+import { type Sql } from "postgres";
 import type { Catalog } from "../../contracts/catalog/types.js";
+import { type CatalogQuery, type IntrospectOptions } from "../../dialects/pg/introspect.js";
 import type { RolesInput } from "../../dialects/pg/role/index.js";
 /**
  * Refuses when the connected database differs from the schema.
@@ -17,3 +19,17 @@ 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): Promise<void>;
+/**
+ * Turns a postgres.js handle into the query shape introspection uses.
+ *
+ * @param sql - One connection
+ * @returns A {@link CatalogQuery}
+ */
+export declare function catalogQuery(sql: Sql): CatalogQuery;
+/**
+ * Role names introspection should read, when the config names them.
+ *
+ * @param roles - `defineConfig({ roles })`, when set
+ * @returns The introspect option, or `undefined` when roles are not configured
+ */
+export declare function managedRoleOptions(roles: RolesInput | undefined): IntrospectOptions | undefined;