okmodel 0.2.1 → 0.4.0

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

@@ -0,0 +1,28 @@
+/**
+ * `okm doctor`.
+ *
+ * A code prints the registry entry. With no code, the project is loaded and
+ * each table's triggers are listed. When `roles` is set, the command also
+ * connects and checks that those roles exist, that a managed role can be
+ * created, and that the application role can reach each managed object.
+ */
+import type { CatalogObject } from "../../contracts/catalog/types.js";
+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
+ */
+export declare function doctorProject(cwd: string, code: string | undefined, flags?: InvokeFlags): Promise<string>;
+/**
+ * One line per table that has a trigger.
+ *
+ * @param objects - Catalog objects
+ * @returns The listing, or `no triggers` when none are present
+ */
+export declare function formatTriggers(objects: readonly CatalogObject[]): string;

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

@@ -0,0 +1,35 @@
+/**
+ * Live drift for `okm check`.
+ *
+ * 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`, `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.
+ *
+ * @param url - Target URL
+ * @param author - Schema catalog, including roles when the config names them
+ * @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;

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

@@ -0,0 +1,50 @@
+/**
+ * Row estimates for `okm migrate plan` (D194).
+ *
+ * The numbers come from `pg_class.reltuples` on a selected target. They are
+ * printed next to the lock and then discarded. The linter never reads them,
+ * and `okm generate` never asks for them.
+ */
+import type { PlanStep } from "./plan.js";
+/**
+ * Estimated rows above which an `ACCESS EXCLUSIVE` lock prints a note.
+ *
+ * The note is text on the lock line. It is not a lint finding.
+ */
+export declare const LARGE_TABLE_ROWS = 1000000;
+/** What `pg_class` said about one table. */
+export type RowEstimate = {
+    readonly kind: "rows";
+    readonly reltuples: number;
+} | {
+    readonly kind: "unknown";
+};
+/**
+ * Reads `reltuples` for the named tables.
+ *
+ * The statements run in one read-only transaction. A table that is absent
+ * from the result is not entered in the map: the printer treats that as
+ * `new table`. `reltuples` of `-1` is {@link RowEstimate} `unknown`. This
+ * never scans a table.
+ *
+ * @param url - Target URL
+ * @param schema - Schema the plan qualifies, usually `public`
+ * @param tables - Table names the plan steps name
+ * @returns One entry per relation `pg_class` returned
+ */
+export declare function readRowEstimates(url: string, schema: string, tables: readonly string[]): Promise<ReadonlyMap<string, RowEstimate>>;
+/**
+ * Lock line with estimates, the safe-rewrite label, and the large-table note.
+ *
+ * @param step - One plan step
+ * @param estimates - `reltuples` for tables that exist on the target
+ * @returns The text after `-- lock: `
+ */
+export declare function annotateLock(step: PlanStep, estimates: ReadonlyMap<string, RowEstimate>): string;
+/**
+ * Compact phrase for one estimate.
+ *
+ * @param count - Rounded `reltuples`
+ * @returns `about 4.2M rows` and the same shape for thousands and billions
+ */
+export declare function aboutRows(count: number): string;

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

@@ -0,0 +1,17 @@
+/**
+ * `okm ext list` and `okm ext check`.
+ *
+ * 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.
+ */
+import { type InvokeFlags } from "./policy.js";
+/**
+ * Runs `list` or `check` against the selected target.
+ *
+ * @param cwd - Project directory
+ * @param command - `list` or `check`
+ * @param flags - Target and protection flags
+ * @returns Text for stdout, including the trailing newline
+ */
+export declare function extProject(cwd: string, command: "list" | "check", flags: InvokeFlags): Promise<string>;

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

@@ -0,0 +1,53 @@
+/**
+ * Extension alters and the apply preflight.
+ *
+ * Create and drop SQL come from the dialect. An upgrade is `ALTER EXTENSION
+ * … UPDATE`, marked `path-unverified` until apply checks
+ * `pg_extension_update_paths`. A move is `SET SCHEMA` and only when the
+ * declaration is relocatable.
+ */
+import type { CatalogObject } from "../../contracts/catalog/types.js";
+import type { DriverConnection } from "../../contracts/driver.js";
+import { type StepKind } from "./classify.js";
+/** One extension alter. The planner stores it as a plan step. */
+export type ExtensionStep = {
+    readonly sql: string;
+    readonly kind: StepKind;
+    readonly class: "expand" | "contract";
+    readonly action: "ddl";
+    readonly lock: string;
+    readonly transactional: boolean;
+    readonly path?: "unverified";
+};
+/** Migrations the preflight reads. Only the statement text is used. */
+type MigrationSql = {
+    readonly steps: readonly {
+        readonly sql: string;
+    }[];
+};
+/**
+ * Upgrade and move steps for extensions whose definition changed.
+ *
+ * Exact downgrades and moves of a non-relocatable extension are OKM1814.
+ * Dropping an extension that an object in the next catalog still uses is
+ * OKM1814. `DROP` is never `CASCADE`.
+ *
+ * @param beforeBy - Previous objects, keyed by identity
+ * @param afterBy - Next objects, keyed by identity
+ * @param dropKeys - Identities the plan drops
+ * @returns Alter steps. Creates and drops stay in the main planner
+ */
+export declare function extensionAlterSteps(beforeBy: ReadonlyMap<string, CatalogObject>, afterBy: ReadonlyMap<string, CatalogObject>, dropKeys: ReadonlySet<string>): ExtensionStep[];
+/**
+ * Refuses a migration that names an extension the server cannot install,
+ * or an upgrade with no path.
+ *
+ * The server is asked only when a step creates or upgrades an extension.
+ * The check runs before any statement.
+ *
+ * @param connection - The reserved apply connection
+ * @param migrations - Migrations in apply order
+ * @throws OkmError OKM1811 when the extension is not available, OKM1814 when the update path is missing
+ */
+export declare function assertExtensionsAvailable(connection: DriverConnection, migrations: readonly MigrationSql[]): Promise<void>;
+export {};

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

@@ -1,6 +1,7 @@
 /**
  * Migration files on disk: SQL from {@link formatPlan} plus the catalog hash.
  */
+import { parseCatalog } from "../../contracts/catalog/document.js";
 import { type PlanStep } from "./plan.js";
 /** One migration the applier can run and resume. */
 export type StoredMigration = {
@@ -17,3 +18,14 @@ export type StoredMigration = {
  * @returns Migrations in apply order
  */
 export declare function loadMigrations(directory: string): readonly StoredMigration[];
+/**
+ * Loads the last migration's catalog, which is the head snapshot.
+ *
+ * @param directory - Migrations directory
+ * @returns The last file, or `undefined` when there are none
+ */
+export declare function loadHeadSnapshot(directory: string): {
+    readonly id: string;
+    readonly catalogHash: string;
+    readonly catalog: ReturnType<typeof parseCatalog>;
+} | undefined;

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

@@ -1,7 +1,8 @@
 /**
  * Public entry for `okmodel/migrate`.
  *
- * `defineConfig` and its types. The CLI imports planning and apply helpers
- * from their modules, so those names are not exported.
+ * `defineConfig`, its types, and `provision` for one configured target.
+ * The CLI imports planning and apply helpers from their modules.
  */
 export { defineConfig, type MigrateConfig, type TargetInput } from "./config.js";
+export { provision } from "./provision.js";

package/dist/tooling/migrate/index.js

@@ -1,7 +1,73 @@
+import"../../shared/wqem4jed.js";
+import"../../shared/8jb4ymh2.js";
+import"../../shared/n442h54c.js";
+import {
+  applyTarget2,
+  backfillTiming2
+} from "../../shared/s4mb6a4b.js";
+import {
+  loadMigrations,
+  loadHeadSnapshot,
+  readReference
+} from "../../shared/7nk68fj8.js";
+import {
+  assertTargetPolicy,
+  selectTarget,
+  loadBuiltSchema,
+  loadConfig
+} from "../../shared/q6zsyh31.js";
+import"../../shared/n5y9zyj1.js";
+import"../../shared/41kv2xdm.js";
+import {
+  OkmError2
+} from "../../shared/52szzakm.js";
+
 // src/tooling/migrate/config.ts
 function defineConfig(config) {
   return config;
 }
+// src/tooling/migrate/provision.ts
+import { join } from "node:path";
+async function provision(target, cwd = process.cwd()) {
+  const config = await loadConfig(cwd);
+  const selected = selectTarget(config, target);
+  assertTargetPolicy(selected, "provision");
+  const directory = join(cwd, config.migrations ?? "migrations");
+  const migrations = loadMigrations(directory);
+  const head = loadHeadSnapshot(directory);
+  if (head === undefined) {
+    throw new OkmError2("invalid", "There is no head snapshot to provision.", {
+      fix: { summary: "Run okm generate before provision." }
+    });
+  }
+  const built = await loadBuiltSchema(cwd, config);
+  const report = await applyTarget2({
+    url: selected.url,
+    target: selected.name,
+    protected: selected.protected,
+    allowPooler: config.allowPooler === true,
+    ...backfillTiming2(config.backfill),
+    migrations,
+    snapshot: {
+      catalog: head.catalog,
+      migrationId: head.id,
+      catalogHash: head.catalogHash,
+      reference: readReference(built.tables, built.casing, head.catalog),
+      only: true
+    },
+    ...config.roles !== undefined ? { migrationRole: config.roles.migration } : {},
+    lintDirectory: directory
+  });
+  if (report.applied.length === 0)
+    return `target ${report.target}
+nothing to apply
+`;
+  return `target ${report.target}
+${report.applied.map((id) => `applied ${id}`).join(`
+`)}
+`;
+}
 export {
-  defineConfig
+  defineConfig,
+  provision
 };

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

@@ -0,0 +1,51 @@
+/**
+ * Lint rules for one plan step or one catalog column.
+ *
+ * A rule reads the statement and the catalogs. It does not connect.
+ */
+import type { Catalog, ColumnObject } from "../../contracts/catalog/types.js";
+import type { PlanStep } from "./plan.js";
+/** Destructive, compatibility, data, locking, or a schema type preference. */
+export type LintCategory = "destructive" | "backward-incompatible" | "data-dependent" | "locking" | "type-preference";
+/** An error blocks plan, check, and apply. A warning is printed and does not. */
+export type LintSeverity = "error" | "warning";
+/** What a step rule can see. Catalogs are the plan's before and after. */
+export type StepInput = {
+    readonly step: PlanStep;
+    readonly before: Catalog;
+    readonly after: Catalog;
+    readonly existingTables: ReadonlySet<string>;
+    /** Steps before this one. A safe `SET NOT NULL` is recognised from them. */
+    readonly earlier: readonly PlanStep[];
+    /** Steps after this one. A unique index built for a constraint is recognised from them. */
+    readonly later: readonly PlanStep[];
+};
+/** One step rule. `check` returns a reason for each hit, or nothing. */
+export type StepRule = {
+    readonly code: string;
+    readonly category: Exclude<LintCategory, "type-preference">;
+    readonly severity: LintSeverity;
+    /** One line for the codes table. */
+    readonly doc: string;
+    readonly check: (input: StepInput) => readonly string[];
+};
+/** One schema rule. `okm check` runs these on the author catalog. */
+export type ColumnRule = {
+    readonly code: string;
+    readonly category: "type-preference";
+    readonly severity: "warning";
+    /** One line for the codes table. */
+    readonly doc: string;
+    readonly check: (column: ColumnObject) => string | undefined;
+};
+/**
+ * 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.
+ */
+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[];

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

@@ -0,0 +1,71 @@
+/**
+ * Runs the migration linter.
+ *
+ * The linter reads a plan and the two catalogs. It does not connect.
+ * An override is a `-- okm-allow` line on the statement. It silences only
+ * the code it names, and only with a reason.
+ */
+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";
+/** One finding. `place` is `step N` or `table.column`, optionally prefixed with the file. */
+export type Finding = {
+    readonly severity: LintSeverity;
+    readonly code: string;
+    readonly place: string;
+    readonly reason: string;
+    readonly fix: string;
+};
+/**
+ * Lints every step. Type preferences are {@link lintCatalog}, not here.
+ *
+ * @param plan - Parsed or planned steps, including `-- okm-allow` lines
+ * @param before - Catalog the statements start from
+ * @param after - Catalog the statements end on
+ * @returns Findings in step order, then code order
+ */
+export declare function lintPlan(plan: MigrationPlan, before: Catalog, after: Catalog): readonly Finding[];
+/**
+ * Lints type preferences on the author catalog.
+ *
+ * @param source - Schema catalog `okm check` loaded
+ * @returns One warning per column that prefers another type
+ */
+export declare function lintCatalog(source: Catalog): readonly Finding[];
+/**
+ * Lints each SQL file against the previous file's catalog.
+ *
+ * The walk starts at the first file, against an empty catalog, so a later
+ * file sees the catalog the file before it left. The sibling `.catalog.json`
+ * is the catalog after that file. When `pending` is passed, only those
+ * migration ids contribute findings. The earlier files are still read.
+ *
+ * @param directory - Migrations directory. Missing means there are none
+ * @param pending - Migration ids still to run. Omit to lint every file
+ * @returns Findings, each place prefixed with the migration id
+ */
+export declare function lintMigrationDirectory(directory: string, pending?: ReadonlySet<string>): readonly Finding[];
+/**
+ * Prints findings one per line, in a form CI can grep.
+ *
+ * @param findings - Findings from {@link lintPlan} or {@link lintCatalog}
+ * @returns The text, or `""` when there are none. A non-empty result ends in a newline
+ */
+export declare function formatFindings(findings: readonly Finding[]): string;
+/**
+ * Reports whether any finding is an error.
+ *
+ * @param findings - Findings to scan
+ * @returns `true` when plan, check, or apply must fail
+ */
+export declare function hasError(findings: readonly Finding[]): boolean;
+/**
+ * OKM1510 for an unresolved error finding.
+ *
+ * The message is the finding lines, so the failure text stays greppable.
+ *
+ * @param findings - Findings that include at least one error
+ * @returns The error apply, plan, and check throw before continuing
+ */
+export declare function lintRefusal(findings: readonly Finding[]): OkmError;

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

@@ -0,0 +1,17 @@
+/**
+ * Tables OKModel owns: `okm_meta`, `okm_history`, and `okm_backfill`.
+ *
+ * Apply creates them. They are not part of the author schema. Plan, push,
+ * check, and doctor omit them on both sides, so a diff neither drops them
+ * nor creates them.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+/**
+ * Removes the migration history tables and the objects that belong to them.
+ *
+ * A catalog that has neither is returned as itself.
+ *
+ * @param source - Catalog about to be diffed or diagnosed
+ * @returns The catalog without OKModel's own tables
+ */
+export declare function omitManagedObjects(source: Catalog): Catalog;

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

@@ -6,26 +6,81 @@
  * OKM1530. The planner never prompts.
  *
  * Picklist and enum removals are expand `UPDATE`s plus a contract swap
- * (D131). Those data steps are plain statements here. Batching them is P52.
+ * (D131). Each data step is a backfill: one idempotent `UPDATE` per batch,
+ * with `-- backfill` naming the primary key (D195).
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import type { DeclaredRename } from "../../dialects/pg/declarations.js";
+import { type BackfillSpec } from "./backfill.js";
+import { type MigrationClass, type StepKind } from "./classify.js";
 import { type Replacement } from "./values.js";
-/** Expand, contract, or a step that is neither. */
-export type MigrationClass = "expand" | "contract" | "unclassified";
+export type { MigrationClass, StepKind };
 /**
  * One statement in a plan.
  *
- * `backfill` is data; P16B runs it as written. `transactional: false` marks a
- * step that cannot share a transaction with a later use (`ALTER TYPE … ADD
- * VALUE`, spec 19.2).
+ * `backfill` is data. A step with {@link PlanStep.backfill} is one idempotent
+ * `UPDATE` per batch, outside the migration transaction. `transactional: false`
+ * also marks a step that cannot share a transaction (`ALTER TYPE … ADD VALUE`,
+ * a concurrent index).
  */
 export type PlanStep = {
     readonly sql: string;
     readonly class: MigrationClass;
+    /**
+     * Planner operation. Absent on a step built by hand.
+     *
+     * The class comes from this kind. A statement with no kind and no class
+     * comment is `raw-sql`.
+     */
+    readonly kind?: StepKind;
     readonly action: "ddl" | "backfill";
     readonly lock: string;
+    /**
+     * Tables the statement names.
+     *
+     * Used to look up `pg_class.reltuples` when a plan is printed against a
+     * reachable target. {@link formatPlan} does not write this into a file.
+     */
+    readonly tables?: readonly string[];
+    /**
+     * Set when the step was emitted by a safe rewrite (D193).
+     *
+     * Display only. A migration file does not record it.
+     */
+    readonly safeRewrite?: true;
     readonly transactional: boolean;
+    /**
+     * Set when the statement is a batched backfill.
+     *
+     * The header is `table`, `key`, and `batch`. The statement receives `$1`
+     * and `$2`. Absent on a data step written without that header.
+     */
+    readonly backfill?: BackfillSpec;
+    /**
+     * Set on an extension upgrade the planner could not check.
+     *
+     * Apply reads `pg_extension_update_paths` before any statement and refuses
+     * a missing path. Offline `okm migrate plan` leaves this unverified.
+     */
+    readonly path?: "unverified";
+    /**
+     * Set on `CREATE OR REPLACE` of a function whose signature did not change.
+     *
+     * The statement is expand. The flag says the body or the settings changed.
+     */
+    readonly behavior?: "change";
+    /**
+     * `-- okm-allow` lines directly above the statement.
+     *
+     * A reason silences that code only. An empty reason, or a code the
+     * statement did not trigger, is OKM1510 and silences nothing.
+     */
+    readonly allows?: readonly StepAllow[];
+};
+/** One `-- okm-allow CODE: reason` line above a statement. */
+export type StepAllow = {
+    readonly code: string;
+    readonly reason: string;
 };
 /** A named plan and the class of its strictest step. */
 export type MigrationPlan = {
@@ -42,6 +97,13 @@ export type PlanRequest = {
     readonly schema?: string;
     /** Concrete schema written into the SQL. Identities stay logical. */
     readonly name?: string;
+    /**
+     * Rows per backfill batch written into the step header.
+     *
+     * Omitted uses the built-in default of 1000. A later apply reads `batch=`
+     * from the file, which overrides `defineConfig({ backfill })`.
+     */
+    readonly batchSize?: number;
 };
 /**
  * Builds a plan from catalog `before` to catalog `after`.
@@ -49,14 +111,20 @@ export type PlanRequest = {
  * @param request - Catalogs, declared renames, and `--replace` flags
  * @returns Steps in apply order, with one class for the plan
  */
-export declare function planMigration(request: PlanRequest): MigrationPlan;
+export declare function planMigration(input: PlanRequest): MigrationPlan;
 /**
- * Prints a plan. The text is SQL plus class comments, never TypeScript.
+ * Prints a plan. The header is the strictest class. Each step prints its
+ * class and lock. The text is SQL plus those comments, never TypeScript.
+ *
+ * `okm generate` calls this with no `lockText`, so a file stays free of row
+ * estimates. `okm migrate plan` passes `lockText` only after a reachable
+ * target has answered.
  *
  * @param plan - Plan from {@link planMigration}
- * @returns The text `okm generate` writes and `okm migrate plan` prints
+ * @param lockText - Replaces the lock comment when a target supplied estimates
+ * @returns The text `okm generate` writes. `okm migrate plan` uses the same text offline
  */
-export declare function formatPlan(plan: MigrationPlan): string;
+export declare function formatPlan(plan: MigrationPlan, lockText?: (step: PlanStep) => string): string;
 /**
  * Reads a plan written by {@link formatPlan}.
  *

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

@@ -5,9 +5,14 @@
  * `.catalog`, which runs that validation. Generate writes SQL only.
  */
 import { type DeclaredRename } from "../../dialects/pg/declarations.js";
+import type { BuiltSchema } from "../../dialects/pg/schema.js";
+import type { AnyTable } from "../../dialects/pg/table.js";
 import type { Catalog } from "../../contracts/catalog/types.js";
 import { type MigrateConfig } from "./config.js";
+import { type InvokeFlags } from "./policy.js";
 import { type MigrationPlan } from "./plan.js";
+import { type Finding } from "./lint.js";
+type Built = BuiltSchema<readonly AnyTable[]>;
 /**
  * Validates the schema and writes `.okm/`.
  *
@@ -23,24 +28,47 @@ export declare function buildProject(cwd: string): Promise<string>;
  * @param cwd - Project directory
  * @param name - Migration name
  * @param flags - `--replace` values
- * @returns The SQL path, or `undefined` when nothing changed
+ * @returns The SQL path and lint findings, or `undefined` when nothing changed
  */
-export declare function generateProject(cwd: string, name: string, flags: readonly string[]): Promise<string | undefined>;
+export declare function generateProject(cwd: string, name: string, flags: readonly string[]): Promise<{
+    readonly path: string;
+    readonly findings: readonly Finding[];
+} | undefined>;
 /**
  * Plans and returns the text. Nothing is written.
  *
+ * When one target is configured, or `--target` names one, and that database
+ * answers, the printed lock lines include `pg_class` row estimates. No
+ * target, several targets without `--target`, or a target that cannot be
+ * reached leaves the text identical to {@link formatPlan}.
+ *
  * @param cwd - Project directory
  * @param name - Plan name
  * @param flags - `--replace` values
- * @returns The plan
+ * @param invoke - Target and protection flags, when the command passed them
+ * @returns The plan, its lint findings, and the text to print
  */
-export declare function planProject(cwd: string, name: string, flags: readonly string[]): Promise<MigrationPlan>;
+export declare function planProject(cwd: string, name: string, flags: readonly string[], invoke?: InvokeFlags): Promise<{
+    readonly plan: MigrationPlan;
+    readonly findings: readonly Finding[];
+    readonly text: string;
+}>;
 /**
  * Validates the schema, then reports stale renames and unlisted table files.
  *
+ * When exactly one target is configured, or `--target` names one, the
+ * read-only `check` and `drift` classes are allowed and a database that
+ * already has `okm_meta` is compared with the schema. A difference is
+ * OKM1520. Several targets and no `--target` skip that comparison.
+ *
+ * Lint findings are computed from the plan and the catalog before any
+ * connection. An error finding is OKM1510. Warnings are returned.
+ *
  * @param cwd - Project directory
+ * @param flags - `--target`, when the caller passed one
+ * @returns Warning findings. Errors throw
  */
-export declare function checkProject(cwd: string): Promise<void>;
+export declare function checkProject(cwd: string, flags?: InvokeFlags): Promise<readonly Finding[]>;
 /**
  * Table files whose names do not appear in the schema module.
  *
@@ -60,6 +88,28 @@ export declare function projectHead(cwd: string): Promise<{
     readonly catalog: Catalog;
     readonly renames: readonly DeclaredRename[];
 }>;
+/**
+ * Loads the config, the schema, and the previous catalog snapshot.
+ *
+ * A `renamedFrom` that the previous catalog does not contain is OKM1020.
+ *
+ * @param cwd - Project directory
+ * @returns The loaded project
+ */
+export declare function openProject(cwd: string): Promise<{
+    readonly config: MigrateConfig;
+    readonly built: Built;
+    readonly previous: Catalog;
+    readonly renames: readonly DeclaredRename[];
+}>;
+/**
+ * Loads the schema named by `config`.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @returns The built schema, with roles attached when the config declares them
+ */
+export declare function loadBuiltSchema(cwd: string, config: MigrateConfig): Promise<Built>;
 /**
  * Loads `okmodel.config.ts`.
  *
@@ -67,3 +117,12 @@ export declare function projectHead(cwd: string): Promise<{
  * @returns The config object
  */
 export declare function loadConfig(cwd: string): Promise<MigrateConfig>;
+/**
+ * Loads the module named by `spec` and returns the schema it exports.
+ *
+ * @param cwd - Project directory
+ * @param spec - Path from `defineConfig({ schema })`, relative to `cwd`
+ * @returns The built schema
+ */
+export declare function loadSchema(cwd: string, spec: string): Promise<Built>;
+export {};