@prisma-next/cli 0.3.0-dev.6 → 0.3.0-dev.64

package/README.md

@@ -22,6 +22,7 @@ Provide a command-line interface that:
 - **Extension Pack Descriptor Assembly**: Collect adapter and extension descriptors for emission
 - **Help Output Formatting**: Custom styled help output with command trees and formatted descriptions
 - **Config Management**: Load and validate `prisma-next.config.ts` files using Arktype validation
+- **CLI Binary Compatibility**: Build emits `dist/cli.mjs` and also writes a compatibility shim at `dist/cli.js`
 
 ### Wiring validation
 
@@ -31,9 +32,9 @@ This prevents runtime mismatches (for example: a contract that declares extensio
 
 Commands that enforce wiring validation:
 - **`db verify`**
-- **`db introspect`** (when a contract is provided)
 - **`db sign`**
 - **`db init`**
+- **`db update`**
 
 If you hit a wiring validation error: add the required descriptors to `config.extensionPacks` (matched by descriptor `id`) and re-run the command.
 
@@ -46,7 +47,7 @@ Commands use separate short and long descriptions via `setCommandDescriptions()`
 - **Short description**: One-liner used in command trees and headers (e.g., "Emit signed contract artifacts")
 - **Long description**: Multiline text shown at the bottom of help output with detailed context
 
-See `.cursor/rules/cli-command-descriptions.mdc` for details.
+See `src/utils/command-helpers.ts` for `setCommandDescriptions()` and `getLongDescription()`.
 
 ## Commands
 
@@ -61,12 +62,12 @@ prisma-next contract emit [--config <path>] [--json] [-v] [-q] [--timestamps] [-
 
 **Config File Requirements:**
 
-The `contract emit` command requires a `driver` in the config (even though it doesn't use it) because `ControlFamilyDescriptor.create()` requires it for consistency:
+The `contract emit` command does not require a `driver` in the config since it doesn't connect to a database:
 
 ```typescript
 import { defineConfig } from '@prisma-next/cli/config-types';
+import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
 import postgresAdapter from '@prisma-next/adapter-postgres/control';
-import postgresDriver from '@prisma-next/driver-postgres/control';
 import postgres from '@prisma-next/target-postgres/control';
 import sql from '@prisma-next/family-sql/control';
 import { contract } from './prisma/contract';
@@ -75,13 +76,8 @@ export default defineConfig({
   family: sql,
   target: postgres,
   adapter: postgresAdapter,
-  driver: postgresDriver, // Required even though emit doesn't use it
   extensionPacks: [],
-  contract: {
-    source: contract,
-    output: 'src/prisma/contract.json',
-    types: 'src/prisma/contract.d.ts',
-  },
+  contract: typescriptContract(contract, 'src/prisma/contract.json'),
 });
 ```
 
@@ -116,7 +112,7 @@ prisma-next db verify [--db <url>] [--config <path>] [--json] [-v] [-q] [--times
 ```
 
 Options:
-- `--db <url>`: Database connection string (optional; defaults to `config.db.url` if set)
+- `--db <url>`: Database connection string (optional; defaults to `config.db.connection` if set)
 - `--config <path>`: Optional. Path to `prisma-next.config.ts` (defaults to `./prisma-next.config.ts` if present)
 - `--json`: Output as JSON object
 - `-q, --quiet`: Quiet mode (errors only)
@@ -146,6 +142,7 @@ The `db verify` command requires a `driver` in the config to connect to the data
 
 ```typescript
 import { defineConfig } from '@prisma-next/cli/config-types';
+import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
 import postgresAdapter from '@prisma-next/adapter-postgres/control';
 import postgresDriver from '@prisma-next/driver-postgres/control';
 import postgres from '@prisma-next/target-postgres/control';
@@ -158,13 +155,9 @@ export default defineConfig({
   adapter: postgresAdapter,
   driver: postgresDriver,
   extensionPacks: [],
-  contract: {
-    source: contract,
-    output: 'src/prisma/contract.json',
-    types: 'src/prisma/contract.d.ts',
-  },
+  contract: typescriptContract(contract, 'src/prisma/contract.json'),
   db: {
-    url: process.env.DATABASE_URL, // Optional: can also use --db flag
+    connection: process.env.DATABASE_URL, // Optional: can also use --db flag
   },
 });
 ```
@@ -173,12 +166,12 @@ export default defineConfig({
 
 1. **Load Contract**: Reads the emitted `contract.json` from `config.contract.output`
 2. **Connect to Database**: Uses `config.driver.create(url)` to create a driver
-3. **Create Family Instance**: Calls `config.family.create()` with target, adapter, driver, and `extensionPacks` (passed as `extensions`) to create a family instance
+3. **Create Family Instance**: Creates a `ControlPlaneStack` via `createControlPlaneStack()` and passes it to `config.family.create(stack)` to create a family instance
 4. **Verify**: Calls `familyInstance.verify()` which:
    - Reads the contract marker from the database
    - Compares marker presence: Returns `PN-RTM-3001` if marker is missing
    - Compares target compatibility: Returns `PN-RTM-3003` if contract target doesn't match config target
-   - Compares core hash: Returns `PN-RTM-3002` if `coreHash` doesn't match
+  - Compares storage hash: Returns `PN-RTM-3002` if `storageHash` doesn't match
    - Compares profile hash: Returns `PN-RTM-3002` if `profileHash` doesn't match (when present)
    - Checks codec coverage (optional): Compares contract column types against supported codec types and reports missing codecs
 
@@ -187,7 +180,7 @@ export default defineConfig({
 Success:
 ```
 ✔ Database matches contract
-  coreHash: sha256:abc123...
+  storageHash: sha256:abc123...
   profileHash: sha256:def456...
 ```
 
@@ -205,11 +198,11 @@ Failure:
   "ok": true,
   "summary": "Database matches contract",
   "contract": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "marker": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "target": {
@@ -235,16 +228,20 @@ Failure:
 
 **Family Requirements:**
 
-The family must provide a `create()` method in the family descriptor that returns a `ControlFamilyInstance` with a `verify()` method:
+The family must provide a `create()` method in the family descriptor that accepts a `ControlPlaneStack` and returns a `ControlFamilyInstance` with a `verify()` method:
 
 ```typescript
-interface ControlFamilyDescriptor {
-  create(options: {
-    target: ControlTargetDescriptor;
-    adapter: ControlAdapterDescriptor;
-    driver: ControlDriverDescriptor;
-    extensions: ControlExtensionDescriptor[];
-  }): ControlFamilyInstance;
+interface ControlFamilyDescriptor<TFamilyId, TFamilyInstance> {
+  create<TTargetId extends string>(
+    stack: ControlPlaneStack<TFamilyId, TTargetId>,
+  ): TFamilyInstance;
+}
+
+interface ControlPlaneStack<TFamilyId, TTargetId> {
+  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;
+  readonly driver: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly extensionPacks: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[];
 }
 
 interface ControlFamilyInstance {
@@ -258,6 +255,8 @@ interface ControlFamilyInstance {
 }
 ```
 
+Use `createControlPlaneStack()` from `@prisma-next/core-control-plane/stack` to create the stack with sensible defaults (`driver` defaults to `undefined`, `extensionPacks` defaults to `[]`).
+
 The SQL family provides this via `@prisma-next/family-sql/control`. The `verify()` method handles reading the marker, comparing hashes, and checking codec coverage internally.
 
 ### `prisma-next db introspect`
@@ -270,7 +269,7 @@ prisma-next db introspect [--db <url>] [--config <path>] [--json] [-v] [-q] [--t
 ```
 
 Options:
-- `--db <url>`: Database connection string (optional; defaults to `config.db.url` if set)
+- `--db <url>`: Database connection string (optional; defaults to `config.db.connection` if set)
 - `--config <path>`: Optional. Path to `prisma-next.config.ts` (defaults to `./prisma-next.config.ts` if present)
 - `--json`: Output as JSON object
 - `-q, --quiet`: Quiet mode (errors only)
@@ -300,6 +299,7 @@ The `db introspect` command requires a `driver` in the config to connect to the
 
 ```typescript
 import { defineConfig } from '@prisma-next/cli/config-types';
+import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
 import postgresAdapter from '@prisma-next/adapter-postgres/control';
 import postgresDriver from '@prisma-next/driver-postgres/control';
 import postgres from '@prisma-next/target-postgres/control';
@@ -312,7 +312,7 @@ export default defineConfig({
   driver: postgresDriver,
   extensionPacks: [],
   db: {
-    url: process.env.DATABASE_URL, // Optional: can also use --db flag
+    connection: process.env.DATABASE_URL, // Optional: can also use --db flag
   },
 });
 ```
@@ -320,7 +320,7 @@ export default defineConfig({
 **Introspection Process:**
 
 1. **Connect to Database**: Uses `config.driver.create(url)` to create a driver
-2. **Create Family Instance**: Calls `config.family.create()` with target, adapter, driver, and `extensionPacks` (passed as `extensions`) to create a family instance
+2. **Create Family Instance**: Creates a `ControlPlaneStack` via `createControlPlaneStack()` and passes it to `config.family.create(stack)` to create a family instance
 3. **Introspect**: Calls `familyInstance.introspect()` which:
    - Queries the database catalog to discover schema structure
    - Returns a family-specific schema IR (e.g., `SqlSchemaIR` for SQL family)
@@ -387,7 +387,7 @@ sql schema (tables: 2)
 
 **Error Codes:**
 - `PN-CLI-4010`: Missing driver in config — provide a driver descriptor
-- `PN-CLI-4005`: Missing database URL — provide `--db <url>` or set `db.url` in config
+- `PN-CLI-4005`: Missing database connection — provide `--db <url>` or set `db.connection` in config
 
 **Family Requirements:**
 
@@ -421,7 +421,7 @@ prisma-next db sign [--db <url>] [--config <path>] [--json] [-v] [-q] [--timesta
 ```
 
 Options:
-- `--db <url>`: Database connection string (optional; defaults to `config.db.url` if set)
+- `--db <url>`: Database connection string (optional; defaults to `config.db.connection` if set)
 - `--config <path>`: Optional. Path to `prisma-next.config.ts` (defaults to `./prisma-next.config.ts` if present)
 - `--json`: Output as JSON object
 - `-q, --quiet`: Quiet mode (errors only)
@@ -463,13 +463,9 @@ export default defineConfig({
   adapter: postgresAdapter,
   driver: postgresDriver,
   extensionPacks: [],
-  contract: {
-    source: contract,
-    output: 'src/prisma/contract.json',
-    types: 'src/prisma/contract.d.ts',
-  },
+  contract: typescriptContract(contract, 'src/prisma/contract.json'),
   db: {
-    url: process.env.DATABASE_URL, // Optional: can also use --db flag
+    connection: process.env.DATABASE_URL, // Optional: can also use --db flag
   },
 });
 ```
@@ -478,7 +474,7 @@ export default defineConfig({
 
 1. **Load Contract**: Reads the emitted `contract.json` from `config.contract.output`
 2. **Connect to Database**: Uses `config.driver.create(url)` to create a driver
-3. **Create Family Instance**: Calls `config.family.create()` with target, adapter, driver, and `extensionPacks` (passed as `extensions`) to create a family instance
+3. **Create Family Instance**: Creates a `ControlPlaneStack` via `createControlPlaneStack()` and passes it to `config.family.create(stack)` to create a family instance
 4. **Schema Verification (Precondition)**: Calls `familyInstance.schemaVerify()` to verify the database schema matches the contract:
    - If verification fails: Prints schema verification output and exits with code 1 (marker is not written)
    - If verification passes: Proceeds to marker signing
@@ -495,7 +491,7 @@ export default defineConfig({
 Success (new marker):
 ```
 ✔ Database signed (marker created)
-  coreHash: sha256:abc123...
+  storageHash: sha256:abc123...
   profileHash: sha256:def456...
   Total time: 42ms
 ```
@@ -503,16 +499,16 @@ Success (new marker):
 Success (updated marker):
 ```
 ✔ Database signed (marker updated from sha256:old-hash)
-  coreHash: sha256:abc123...
+  storageHash: sha256:abc123...
   profileHash: sha256:def456...
-  previous coreHash: sha256:old-hash
+  previous storageHash: sha256:old-hash
   Total time: 42ms
 ```
 
 Success (already up-to-date):
 ```
 ✔ Database already signed with this contract
-  coreHash: sha256:abc123...
+  storageHash: sha256:abc123...
   profileHash: sha256:def456...
   Total time: 42ms
 ```
@@ -530,7 +526,7 @@ Failure (schema mismatch):
   "ok": true,
   "summary": "Database signed (marker created)",
   "contract": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "target": {
@@ -557,7 +553,7 @@ For updated markers:
   "ok": true,
   "summary": "Database signed (marker updated from sha256:old-hash)",
   "contract": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "target": {
@@ -568,7 +564,7 @@ For updated markers:
     "created": false,
     "updated": true,
     "previous": {
-      "coreHash": "sha256:old-hash",
+      "storageHash": "sha256:old-hash",
       "profileHash": "sha256:old-profile-hash"
     }
   },
@@ -584,7 +580,7 @@ For updated markers:
 
 **Error Codes:**
 - `PN-CLI-4010`: Missing driver in config — provide a driver descriptor
-- `PN-CLI-4005`: Missing database URL — provide `--db <url>` or set `db.url` in config
+- `PN-CLI-4005`: Missing database connection — provide `--db <url>` or set `db.connection` in config
 - Exit code 1: Schema verification failed — database schema does not match contract (marker is not written)
 
 **Relationship to Other Commands:**
@@ -631,7 +627,7 @@ prisma-next db init [--db <url>] [--config <path>] [--plan] [--json] [-v] [-q] [
 ```
 
 Options:
-- `--db <url>`: Database connection string (optional; defaults to `config.db.url` if set)
+- `--db <url>`: Database connection string (optional; defaults to `config.db.connection` if set)
 - `--config <path>`: Optional. Path to `prisma-next.config.ts` (defaults to `./prisma-next.config.ts` if present)
 - `--plan`: Only show the migration plan, do not apply it
 - `--json [format]`: Output as JSON (`object` only; `ndjson` is not supported for this command)
@@ -662,6 +658,7 @@ The `db init` command requires a `driver` in the config to connect to the databa
 
 ```typescript
 import { defineConfig } from '@prisma-next/cli/config-types';
+import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
 import postgresAdapter from '@prisma-next/adapter-postgres/control';
 import postgresDriver from '@prisma-next/driver-postgres/control';
 import postgres from '@prisma-next/target-postgres/control';
@@ -674,13 +671,9 @@ export default defineConfig({
   adapter: postgresAdapter,
   driver: postgresDriver,
   extensionPacks: [],
-  contract: {
-    source: contract,
-    output: 'src/prisma/contract.json',
-    types: 'src/prisma/contract.d.ts',
-  },
+  contract: typescriptContract(contract, 'src/prisma/contract.json'),
   db: {
-    url: process.env.DATABASE_URL, // Optional: can also use --db flag
+    connection: process.env.DATABASE_URL, // Optional: can also use --db flag
   },
 });
 ```
@@ -689,7 +682,7 @@ export default defineConfig({
 
 1. **Load Contract**: Reads the emitted `contract.json` from `config.contract.output`
 2. **Connect to Database**: Uses `config.driver.create(url)` to create a driver
-3. **Create Family Instance**: Calls `config.family.create()` with target, adapter, driver, and `extensionPacks` (passed as `extensions`)
+3. **Create Family Instance**: Creates a `ControlPlaneStack` via `createControlPlaneStack()` and passes it to `config.family.create(stack)` to create a family instance
 4. **Introspect Schema**: Calls `familyInstance.introspect()` to get the current database schema IR
 5. **Validate wiring**: Ensures the contract is compatible with the CLI config:
    - `contract.targetFamily` matches `config.family.familyId`
@@ -750,7 +743,7 @@ Applying migration plan and verifying schema...
   "plan": {
     "targetId": "postgres",
     "destination": {
-      "coreHash": "sha256:abc123..."
+      "storageHash": "sha256:abc123..."
     },
     "operations": [
       {
@@ -765,7 +758,7 @@ Applying migration plan and verifying schema...
     "operationsExecuted": 4
   },
   "marker": {
-    "coreHash": "sha256:abc123..."
+    "storageHash": "sha256:abc123..."
   }
 }
 ```
@@ -784,6 +777,25 @@ Applying migration plan and verifying schema...
 - If the database already has a marker that matches the destination contract, `db init` succeeds as a noop (0 operations planned/executed).
 - If the database has a marker that does **not** match the destination contract, `db init` fails (including in `--plan` mode). Use `db init` for bootstrapping; use your migration workflow to reconcile existing databases.
 
+### `prisma-next db update`
+
+Update your database schema to match the currently emitted contract.
+
+`db update` differs from `db init`:
+
+- Works on any database, whether or not it has been initialized with `db init` (creates the signature table if missing)
+- Allows `additive`, `widening`, and `destructive` operation classes where supported by planner/runner
+- Disables per-operation runner execution checks by default (precheck/postcheck/idempotency)
+- In `--plan` mode for SQL targets, prints a DDL preview derived from planned operations
+
+**Command:**
+```bash
+prisma-next db update [--db <url>] [--config <path>] [--plan] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+```
+
+**Error codes (additional to shared CLI/runtime codes):**
+- `RUNNER_FAILED`: runner rejected apply (origin mismatch, failed checks, policy failures, or execution errors)
+
 **Config File (`prisma-next.config.ts`):**
 
 The CLI uses a config file to specify the target family, target, adapter, extensionPacks, and contract.
@@ -797,6 +809,7 @@ The CLI uses a config file to specify the target family, target, adapter, extens
 
 ```typescript
 import { defineConfig } from '@prisma-next/cli/config-types';
+import { typescriptContract } from '@prisma-next/sql-contract-ts/config-types';
 import postgresAdapter from '@prisma-next/adapter-postgres/control';
 import postgres from '@prisma-next/target-postgres/control';
 import sql from '@prisma-next/family-sql/control';
@@ -807,42 +820,167 @@ export default defineConfig({
   target: postgres,
   adapter: postgresAdapter,
   extensionPacks: [],
-  contract: {
-    source: contract, // Can be a value or a function: () => import('./contract').then(m => m.contract)
-    output: 'src/prisma/contract.json', // Optional: defaults to 'src/prisma/contract.json'
-    types: 'src/prisma/contract.d.ts', // Optional: defaults to output with .d.ts extension
-  },
+  contract: typescriptContract(contract, 'src/prisma/contract.json'),
 });
 ```
 
-The `contract.source` field can be:
-- A direct value: `source: contract`
-- A synchronous function: `source: () => contract`
-- An asynchronous function: `source: () => import('./contract').then(m => m.contract)`
+Prefer helper utilities for authoring mode selection:
+- `typescriptContract(contractIR, outputPath?)` from `@prisma-next/sql-contract-ts/config-types` for TS-authored contracts
+- `prismaContract(schemaPath, { output?, target? })` from `@prisma-next/sql-contract-psl/provider` for PSL-authored providers
+- Provider failures are returned as structured diagnostics for CLI rendering
 
 The `contract.output` field specifies the path to `contract.json`. This is the canonical location where other CLI commands can find the contract JSON artifact. Defaults to `'src/prisma/contract.json'` if not specified.
 
-The `contract.types` field specifies the path to `contract.d.ts`. Defaults to `output` with `.d.ts` extension (replaces `.json` with `.d.ts` if output ends with `.json`, otherwise appends `contract.d.ts` to the directory containing output).
+`contract.d.ts` is always colocated with `contract.json` and derived from `contract.output` (`contract.json` → `contract.d.ts`).
 
 **Output:**
 - `contract.json`: Includes `_generated` metadata field indicating it's a generated artifact (excluded from canonicalization/hashing)
 - `contract.d.ts`: Includes warning header comments indicating it's a generated file
 
+### `prisma-next migration plan`
+
+Plan a migration from contract changes. Compares the emitted contract against the latest on-disk migration state and produces a new migration package with the required operations. No database connection is needed — fully offline.
+
+```bash
+prisma-next migration plan [--config <path>] [--name <slug>] [--from <hash>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+```
+
+**Options:**
+- `--config <path>`: Path to `prisma-next.config.ts`
+- `--name <slug>`: Name slug for the migration directory (default: `migration`)
+- `--from <hash>`: Explicit starting contract hash (overrides latest chain leaf detection)
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output (debug info, timings)
+- `--timestamps`: Add timestamps to output
+
+**What it does:**
+1. Loads config and reads `contract.json` (the "to" contract)
+2. Reads existing migrations from `config.migrations.dir` (default: `migrations/`)
+3. Reconstructs the migration chain and finds the leaf (current state)
+4. Diffs the leaf contract against the new contract using the target's migration planner (same planner as `db init`)
+5. Writes a new migration package (`migration.json` + `ops.json`) and attests the `migrationId`
+
+### `prisma-next migration show`
+
+Display a migration package's operations, DDL preview, and metadata. Accepts a directory path, a hash prefix (git-style matching against `migrationId`), or defaults to the latest migration.
+
+```bash
+prisma-next migration show [target] [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+```
+
+**Options:**
+- `[target]`: Migration directory path or migrationId hash prefix (defaults to latest)
+- `--config <path>`: Path to `prisma-next.config.ts`
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output
+- `--timestamps`: Add timestamps to output
+
+**What it does:**
+1. If `target` is a path (contains `/` or `\`), reads that directory directly
+2. If `target` is a hash prefix, scans all attested migrations and matches against `migrationId`
+3. If no target, defaults to the latest migration (chain leaf)
+4. Displays operations with operation class badges, destructive warnings, and DDL preview
+
+**Destructive warnings:** When a migration contains destructive operations (e.g., `DROP TABLE`, `ALTER COLUMN TYPE`), the output includes a prominent `⚠` warning about potential data loss.
+
+### `prisma-next migration status`
+
+Show the migration graph and applied status. Adapts based on context:
+
+- **With DB connection**: Shows applied/pending markers and "you are here" indicators
+- **Without DB connection**: Shows the graph structure from disk only
+
+```bash
+prisma-next migration status [--db <url>] [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+```
+
+**Options:**
+- `--db <url>`: Database connection string (enables online mode)
+- `--config <path>`: Path to `prisma-next.config.ts`
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output
+- `--timestamps`: Add timestamps to output
+
+**What it does:**
+1. Reads migration packages from disk and reconstructs the chain
+2. If a DB connection is available, reads the marker to determine applied/pending status
+3. Displays the graph as a linear chain with `◄ DB` and `◄ Contract` markers
+4. Shows operation summaries with destructive operation highlighting
+5. Falls back to offline mode if DB connection fails
+
+**Known limitation:** Branched migration graphs (multiple leaves) produce an error. Only linear chains are visualized.
+
+### `prisma-next migration apply`
+
+Apply planned migrations to the database. Executes previously planned migrations (created by `migration plan`). Compares the database marker against the migration chain to determine which migrations are pending, then executes them sequentially. Each migration runs in its own transaction. Does not plan new migrations — run `migration plan` first.
+
+```bash
+prisma-next migration apply [--db <url>] [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+```
+
+**Options:**
+- `--db <url>`: Database connection string (optional; defaults to `config.db.connection`)
+- `--config <path>`: Path to `prisma-next.config.ts`
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output (debug info, timings)
+- `--timestamps`: Add timestamps to output
+
+**What it does:**
+1. Reads attested migration packages from `config.migrations.dir`
+2. Reconstructs the migration chain (skips drafts with `migrationId: null`)
+3. Reads the current contract hash from `contract.json`
+4. Connects to the database and reads the current marker hash
+5. Finds the path from the marker hash to the current contract hash
+6. Executes each pending migration in order using the target's `MigrationRunner`
+7. Each migration runs in its own transaction with prechecks, postchecks, and idempotency checks enabled
+8. After each migration, the runner verifies the schema and updates the marker/ledger
+
+**Config requirements:** Requires `driver` and `db.connection` (or `--db`). `migrations.dir` is optional and defaults to `migrations/`.
+
+**Resume semantics:** If a migration fails, previously applied migrations are preserved. Re-running `migration apply` resumes from the last successful migration.
+
+**Planning requirement:** `migration apply` now requires the current contract hash to exist in attested on-disk migrations. If the contract has changed and no migration was planned, apply exits with an error and asks you to run `migration plan`.
+
+### `prisma-next migration verify`
+
+Verify a migration package's integrity by recomputing the content-addressed `migrationId`.
+
+```bash
+prisma-next migration verify --dir <path>
+```
+
+- **Verified**: stored `migrationId` matches recomputed value
+- **Draft**: `migrationId` is null — automatically attests the package
+- **Mismatch**: package has been modified since attestation (command exits non-zero)
+
 ## Architecture
 
 ```mermaid
 flowchart TD
     CLI[CLI Entry Point]
-    CMD[Emit Command]
+    CMD_EMIT[Emit Command]
+    CMD_DB[DB Commands]
+    CMD_MIG[Migration Commands]
     LOAD[TS Contract Loader]
     EMIT[Emitter]
+    CTRL[Control Client]
+    MIG_TOOLS["@prisma-next/migration-tools"]
     FS[File System]
 
-    CLI --> CMD
-    CMD --> LOAD
+    CLI --> CMD_EMIT
+    CLI --> CMD_DB
+    CLI --> CMD_MIG
+    CMD_EMIT --> LOAD
     LOAD --> EMIT
-    EMIT --> CMD
-    CMD --> FS
+    CMD_DB --> CTRL
+    CMD_MIG --> CTRL
+    CMD_MIG --> MIG_TOOLS
+    MIG_TOOLS --> FS
+    CTRL --> FS
 ```
 
 ## Config Validation and Normalization
@@ -865,18 +1003,19 @@ See `.cursor/rules/config-validation-and-normalization.mdc` for detailed pattern
 - **Error Handling**: Uses `exitOverride()` to catch unhandled errors (non-structured errors that fail fast) and print stack traces. Commands handle structured errors themselves via `process.exit()`.
 - **Command Taxonomy**: Groups commands by domain/plane (e.g., `contract emit`)
 - **Help Formatting**: Uses `configureHelp()` to customize help output with styled format matching normal command output. Root help shows "prisma-next" title with command tree; command help shows "prisma-next <command> ➜ <description>" with options and docs URLs. See `utils/output.ts` for help formatters.
-- **Command Descriptions**: Commands use `setCommandDescriptions()` to set separate short and long descriptions. See `utils/command-helpers.ts` and `.cursor/rules/cli-command-descriptions.mdc`.
+- **Command Descriptions**: See the “Command Descriptions” section above for `setCommandDescriptions()` usage.
 
 ### Contract Emit Command (`commands/contract-emit.ts`)
 - Canonical command implementation using commander
 - Supports global flags (JSON, verbosity, color, timestamps)
 - **Error Handling**: Uses structured errors (`CliStructuredError`), Result pattern (`performAction`), and `process.exit()`. Commands wrap logic in `performAction()`, process results with `handleResult()`, and call `process.exit(exitCode)` directly. See `.cursor/rules/cli-error-handling.mdc` for details.
 - Loads the user's config module (`prisma-next.config.ts`)
-- Resolves contract from config:
-  - Uses `config.contract.source` (supports sync and async functions)
-  - User's config is responsible for loading the contract (can use `loadContractFromTs` or any other method)
+- Resolves contract from provider:
+  - Calls `config.contract.source()` and expects `Result<ContractIR, Diagnostics>`
+  - Source-specific parsing/loading stays inside providers
+  - Provider diagnostics are surfaced as actionable CLI failures
   - Throws error if `config.contract` is missing
-- Uses artifact paths from `config.contract.output/types` (already normalized by `defineConfig()` with defaults applied)
+- Uses artifact path from `config.contract.output` (already normalized by `defineConfig()` with defaults applied)
 - Creates family instance via `config.family.create()` (assembles operation registry, type imports, extension IDs)
 - Calls `familyInstance.emitContract()` with raw contract (instance handles stripping mappings and validation internally)
 - Outputs human-readable or JSON format based on flags
@@ -999,6 +1138,8 @@ export default defineConfig({
 - **`commander`**: CLI argument parsing and command routing
 - **`esbuild`**: Bundling TypeScript contract files with import allowlisting
 - **`@prisma-next/emitter`**: Contract emission engine (returns strings)
+- **`@prisma-next/migration-tools`**: On-disk migration I/O, attestation, and chain reconstruction
+- **`@prisma-next/core-control-plane`**: Config types, migration operation types, error types, control plane stack
 
 ## Design Decisions
 
@@ -1058,18 +1199,111 @@ pnpm test:integration       # Run integration tests only
 pnpm test:e2e               # Run e2e tests only
 ```
 
+## Programmatic Control API
+
+The CLI package provides a programmatic control client for running control-plane operations without using the command line. This is useful for:
+
+- Integration with build tools and CI pipelines
+- Custom orchestration workflows
+- Test automation
+- Programmatic database management
+
+### Basic Usage
+
+```typescript
+import { createControlClient } from '@prisma-next/cli/control-api';
+import sql from '@prisma-next/family-sql/control';
+import postgres from '@prisma-next/target-postgres/control';
+import postgresAdapter from '@prisma-next/adapter-postgres/control';
+import postgresDriver from '@prisma-next/driver-postgres/control';
+
+// Create a control client with framework component descriptors
+const client = createControlClient({
+  family: sql,
+  target: postgres,
+  adapter: postgresAdapter,
+  driver: postgresDriver,
+  extensionPacks: [],
+});
+
+try {
+  // Connect to database
+  await client.connect(databaseUrl);
+
+  // Run operations
+  const verifyResult = await client.verify({ contractIR });
+  const initResult = await client.dbInit({ contractIR, mode: 'apply' });
+  const updateResult = await client.dbUpdate({ contractIR, mode: 'apply' });
+  const introspectResult = await client.introspect();
+} finally {
+  // Clean up
+  await client.close();
+}
+```
+
+### Available Operations
+
+| Method | Description |
+|--------|-------------|
+| `connect(url)` | Establishes database connection |
+| `close()` | Closes connection (idempotent) |
+| `readMarker()` | Reads contract marker from database (null if none) |
+| `verify(options)` | Verifies database marker matches contract |
+| `schemaVerify(options)` | Verifies database schema satisfies contract |
+| `sign(options)` | Writes contract marker to database |
+| `dbInit(options)` | Initializes database schema from contract |
+| `dbUpdate(options)` | Updates database schema to match contract |
+| `migrationApply(options)` | Applies pre-planned migration edges to database |
+| `introspect(options)` | Introspects database schema |
+
+### Result Types
+
+Operations return structured result types:
+
+- `readMarker()` → `ContractMarkerRecord | null`
+- `verify()` → `VerifyDatabaseResult`
+- `schemaVerify()` → `VerifyDatabaseSchemaResult`
+- `sign()` → `SignDatabaseResult`
+- `dbInit()` → `Result<DbInitSuccess, DbInitFailure>` (uses Result pattern)
+- `dbUpdate()` → `Result<DbUpdateSuccess, DbUpdateFailure>` (uses Result pattern)
+- `migrationApply()` → `Result<MigrationApplySuccess, MigrationApplyFailure>` (uses Result pattern)
+- `introspect()` → Schema IR (family-specific)
+
+### Error Handling
+
+- **Connection errors**: Thrown as exceptions from `connect()`
+- **Not connected errors**: Thrown if operations called before `connect()`
+- **Driver not configured**: Thrown if driver is not provided in options
+- **Operation failures**: Returned as structured results (not thrown)
+
+### Key Differences from CLI
+
+| Aspect | CLI | Control API |
+|--------|-----|-------------|
+| Config | Reads `prisma-next.config.ts` | Accepts descriptors directly |
+| File I/O | Reads contract.json from disk | Accepts contract IR directly |
+| Output | Formats for console | Returns structured data |
+| Exit codes | Uses `process.exit()` | Returns results/throws |
+
 ## Entrypoints
 
 The CLI package exports several subpaths for different use cases:
 
 - **`@prisma-next/cli`** (main export): Exports `loadContractFromTs` and `createContractEmitCommand`
 - **`@prisma-next/cli/config-types`**: Exports `defineConfig` and config types
+- **`@prisma-next/cli/control-api`**: Exports `createControlClient` and control API types
 - **`@prisma-next/cli/commands/db-init`**: Exports `createDbInitCommand`
+- **`@prisma-next/cli/commands/db-update`**: Exports `createDbUpdateCommand`
 - **`@prisma-next/cli/commands/db-introspect`**: Exports `createDbIntrospectCommand`
 - **`@prisma-next/cli/commands/db-schema-verify`**: Exports `createDbSchemaVerifyCommand`
 - **`@prisma-next/cli/commands/db-sign`**: Exports `createDbSignCommand`
 - **`@prisma-next/cli/commands/db-verify`**: Exports `createDbVerifyCommand`
 - **`@prisma-next/cli/commands/contract-emit`**: Exports `createContractEmitCommand`
+- **`@prisma-next/cli/commands/migration-plan`**: Exports `createMigrationPlanCommand`
+- **`@prisma-next/cli/commands/migration-show`**: Exports `createMigrationShowCommand`
+- **`@prisma-next/cli/commands/migration-status`**: Exports `createMigrationStatusCommand`
+- **`@prisma-next/cli/commands/migration-apply`**: Exports `createMigrationApplyCommand`
+- **`@prisma-next/cli/commands/migration-verify`**: Exports `createMigrationVerifyCommand`
 - **`@prisma-next/cli/config-loader`**: Exports `loadConfig` function
 
 **Important**: `loadContractFromTs` is exported from the main package (`@prisma-next/cli`). See `.cursor/rules/cli-package-exports.mdc` for import patterns.