@prisma-next/cli 0.3.0-dev.12 → 0.3.0-dev.123

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.
 
@@ -56,17 +57,17 @@ Emit `contract.json` and `contract.d.ts` from `config.contract`.
 
 **Canonical command:**
 ```bash
-prisma-next contract emit [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+prisma-next contract emit [--config <path>] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 **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'),
 });
 ```
 
@@ -91,7 +87,6 @@ Options:
 - `-q, --quiet`: Quiet mode (errors only)
 - `-v, --verbose`: Verbose output (debug info, timings)
 - `-vv, --trace`: Trace output (deep internals, stack traces)
-- `--timestamps`: Add timestamps to output
 - `--color/--no-color`: Force/disable color output
 
 Examples:
@@ -102,27 +97,30 @@ prisma-next contract emit
 # JSON output
 prisma-next contract emit --json
 
-# Verbose output with timestamps
-prisma-next contract emit -v --timestamps
+# Verbose output
+prisma-next contract emit -v
 ```
 
 ### `prisma-next db verify`
 
-Verify that a database instance matches the emitted contract by checking marker presence, hash equality, and target compatibility.
+Verify that a database instance matches the emitted contract by checking the marker first and, by default, the live schema second.
 
 **Command:**
 ```bash
-prisma-next db verify [--db <url>] [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+prisma-next db verify [--db <url>] [--config <path>] [--marker-only | --schema-only] [--strict] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 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)
+- `--marker-only`: Skip schema verification and only check the database marker
+- `--schema-only`: Skip marker verification and only check whether the live schema satisfies the contract
+- `--strict`: When schema verification runs, schema elements not present in the contract are considered an error
+- `--marker-only` cannot be combined with `--schema-only` or `--strict` (exit code 2, `PN-CLI-4012`). `--schema-only --strict` is valid.
 - `--json`: Output as JSON object
 - `-q, --quiet`: Quiet mode (errors only)
 - `-v, --verbose`: Verbose output (debug info, timings)
 - `-vv, --trace`: Trace output (deep internals, stack traces)
-- `--timestamps`: Add timestamps to output
 - `--color/--no-color`: Force/disable color output
 
 Examples:
@@ -133,11 +131,20 @@ prisma-next db verify
 # Specify database URL
 prisma-next db verify --db postgresql://user:pass@localhost/db
 
+# Marker-only verification when callers accept the trade-off
+prisma-next db verify --db postgresql://user:pass@localhost/db --marker-only
+
+# Schema-only verification without relying on marker state
+prisma-next db verify --db postgresql://user:pass@localhost/db --schema-only
+
+# Strict schema verification (extras fail)
+prisma-next db verify --db postgresql://user:pass@localhost/db --strict
+
 # JSON output
 prisma-next db verify --json
 
-# Verbose output with timestamps
-prisma-next db verify -v --timestamps
+# Verbose output
+prisma-next db verify -v
 ```
 
 **Config File Requirements:**
@@ -146,6 +153,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 +166,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,52 +177,80 @@ 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
-4. **Verify**: Calls `familyInstance.verify()` which:
+3. **Create Family Instance**: Creates a `ControlPlaneStack` via `createControlPlaneStack()` and passes it to `config.family.create(stack)` to create a family instance
+4. **Verify Marker**: 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 profile hash: Returns `PN-RTM-3002` if `profileHash` doesn't match (when present)
+   - Compares marker presence: Returns `PN-RUN-3001` if marker is missing
+   - Compares target compatibility: Returns `PN-RUN-3003` if contract target doesn't match config target
+   - Compares storage hash: Returns `PN-RUN-3002` if `storageHash` doesn't match
+   - Compares profile hash: Returns `PN-RUN-3002` if `profileHash` doesn't match (when present)
    - Checks codec coverage (optional): Compares contract column types against supported codec types and reports missing codecs
+5. **Verify Schema (default)**: Unless `--marker-only` is provided, calls `familyInstance.schemaVerify()` to catch schema mismatches such as missing tables or columns after manual DDL. By default this runs in tolerant mode; `--strict` treats schema elements not present in the contract as an error.
+6. **Schema-only mode**: `--schema-only` skips marker verification entirely and runs only `schemaVerify()`. This is useful for brownfield adoption and corrupt-marker diagnosis.
 
 **Output Format (TTY):**
 
 Success:
-```
-✔ Database matches contract
-  coreHash: sha256:abc123...
+```text
+✔ Database marker and schema match contract
+  verification: marker + schema
+  storageHash: sha256:abc123...
   profileHash: sha256:def456...
 ```
 
-Failure:
+Marker-only success:
+```text
+✔ Database marker matches contract
+  verification: marker only (--marker-only)
+  storageHash: sha256:abc123...
+  profileHash: sha256:def456...
+
+⚠ Schema verification skipped because --marker-only was provided
 ```
-✖ Marker missing (PN-RTM-3001)
+
+Marker failure:
+```text
+✖ Marker missing (PN-RUN-3001)
   Why: Contract marker not found in database
   Fix: Run `prisma-next db sign --db <url>` to create marker
 ```
 
+Schema drift failure:
+`db verify` prints the schema verification tree / JSON payload and exits with code 1.
+
 **Output Format (JSON):**
 
 ```json
 {
   "ok": true,
-  "summary": "Database matches contract",
+  "summary": "Database marker and schema match contract",
+  "mode": "full",
   "contract": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "marker": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "target": {
     "expected": "postgres"
   },
   "missingCodecs": [],
+  "schema": {
+    "summary": "Database schema satisfies contract",
+    "counts": {
+      "pass": 12,
+      "warn": 0,
+      "fail": 0,
+      "totalNodes": 12
+    },
+    "strict": false
+  },
   "meta": {
     "configPath": "/path/to/prisma-next.config.ts",
-    "contractPath": "/path/to/src/prisma/contract.json"
+    "contractPath": "/path/to/src/prisma/contract.json",
+    "schemaVerification": "performed"
   },
   "timings": {
     "total": 42
@@ -229,22 +261,27 @@ Failure:
 **Error Codes:**
 
 - `PN-CLI-4010`: Missing driver in config — provide a driver descriptor
-- `PN-RTM-3001`: Marker missing - Contract marker not found in database
-- `PN-RTM-3002`: Hash mismatch - Contract hash does not match database marker
-- `PN-RTM-3003`: Target mismatch - Contract target does not match config target
+- `PN-RUN-3001`: Marker missing - Contract marker not found in database
+- `PN-RUN-3002`: Hash mismatch - Contract hash does not match database marker
+- `PN-RUN-3003`: Target mismatch - Contract target does not match config target
+- Exit code 1 with schema verification payload: Schema does not match the contract (default mode or `--schema-only`)
 
 **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,48 +295,89 @@ interface ControlFamilyInstance {
 }
 ```
 
-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.
+Use `createControlPlaneStack()` from `@prisma-next/core-control-plane/stack` to create the stack with sensible defaults (`driver` defaults to `undefined`, `extensionPacks` defaults to `[]`).
 
-### `prisma-next db introspect`
+The SQL family provides this via `@prisma-next/family-sql/control`. The `verify()` method handles marker checks, full `db verify` follows it with `schemaVerify()`, `--marker-only` skips that schema step, and `--schema-only` runs `schemaVerify()` without marker checks.
 
-Inspect the live database schema and display it as a human-readable tree or machine-consumable JSON.
+### `prisma-next db schema`
+
+Inspect the live database schema and display it as a human-readable tree or machine-consumable JSON. This command is read-only and never writes files.
 
 **Command:**
 ```bash
-prisma-next db introspect [--db <url>] [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+prisma-next db schema [--db <url>] [--config <path>] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 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)
 - `-v, --verbose`: Verbose output (debug info, timings)
 - `-vv, --trace`: Trace output (deep internals, stack traces)
-- `--timestamps`: Add timestamps to output
 - `--color/--no-color`: Force/disable color output
 
 Examples:
 ```bash
 # Use config defaults
-prisma-next db introspect
+prisma-next db schema
 
 # Specify database URL
-prisma-next db introspect --db postgresql://user:pass@localhost/db
+prisma-next db schema --db postgresql://user:pass@localhost/db
 
 # JSON output
-prisma-next db introspect --json
+prisma-next db schema --json
+
+# Verbose output
+prisma-next db schema -v
+```
+
+### `prisma-next contract infer`
+
+Inspect the live database schema and write an inferred PSL contract to disk. Use this for brownfield adoption when you want a starting `contract.prisma` before running `contract emit` and `db sign`.
+
+**Command:**
+```bash
+prisma-next contract infer [--db <url>] [--config <path>] [--output <path>] [--json] [-v] [-q] [--color/--no-color]
+```
+
+Options:
+- `--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)
+- `--output <path>`: Write the inferred PSL contract to the specified path
+- `--json`: Output a JSON result envelope (includes `psl.path`)
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output (debug info, timings)
+- `-vv, --trace`: Trace output (deep internals, stack traces)
+- `--color/--no-color`: Force/disable color output
+
+Examples:
+```bash
+# Infer contract.prisma next to the configured contract.json output
+prisma-next contract infer
+
+# Specify database URL
+prisma-next contract infer --db postgresql://user:pass@localhost/db
+
+# Override the output path
+prisma-next contract infer --output ./prisma/contract.prisma
 
-# Verbose output with timestamps
-prisma-next db introspect -v --timestamps
+# JSON output
+prisma-next contract infer --json
 ```
 
+By default, `contract infer` writes to:
+1. `--output <path>`, if provided
+2. `contract.prisma` next to `config.contract.output`
+3. `contract.prisma` in the current working directory
+
 **Config File Requirements:**
 
-The `db introspect` command requires a `driver` in the config to connect to the database:
+Both `db schema` and `contract infer` require a `driver` in the config to connect to the 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';
@@ -312,7 +390,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 +398,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 +465,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:**
 
@@ -417,17 +495,16 @@ Mark the database as matching the emitted contract by writing or updating the co
 
 **Command:**
 ```bash
-prisma-next db sign [--db <url>] [--config <path>] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+prisma-next db sign [--db <url>] [--config <path>] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 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)
 - `-v, --verbose`: Verbose output (debug info, timings)
 - `-vv, --trace`: Trace output (deep internals, stack traces)
-- `--timestamps`: Add timestamps to output
 - `--color/--no-color`: Force/disable color output
 
 Examples:
@@ -441,8 +518,8 @@ prisma-next db sign --db postgresql://user:pass@localhost/db
 # JSON output
 prisma-next db sign --json
 
-# Verbose output with timestamps
-prisma-next db sign -v --timestamps
+# Verbose output
+prisma-next db sign -v
 ```
 
 **Config File Requirements:**
@@ -463,13 +540,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 +551,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 +568,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 +576,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 +603,7 @@ Failure (schema mismatch):
   "ok": true,
   "summary": "Database signed (marker created)",
   "contract": {
-    "coreHash": "sha256:abc123...",
+    "storageHash": "sha256:abc123...",
     "profileHash": "sha256:def456..."
   },
   "target": {
@@ -557,7 +630,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 +641,7 @@ For updated markers:
     "created": false,
     "updated": true,
     "previous": {
-      "coreHash": "sha256:old-hash",
+      "storageHash": "sha256:old-hash",
       "profileHash": "sha256:old-profile-hash"
     }
   },
@@ -584,12 +657,11 @@ 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:**
-- **`db schema-verify`**: `db sign` calls `schemaVerify` as a precondition before writing the marker. If schema verification fails, `db sign` exits without writing the marker.
-- **`db verify`**: `db verify` checks that the marker exists and matches the contract. `db sign` writes the marker that `db verify` checks.
+- **`db verify`**: `db verify` checks that the marker exists and matches the contract, then runs schema verification by default. `db sign` writes the marker that `db verify` checks. Use `db verify --marker-only` for marker-only verification and `db verify --schema-only` to inspect only the live schema.
 
 **Idempotency:**
 The `db sign` command is idempotent and safe to run multiple times:
@@ -627,18 +699,17 @@ Initialize a database schema from the contract. This command plans and applies *
 
 **Command:**
 ```bash
-prisma-next db init [--db <url>] [--config <path>] [--plan] [--json] [-v] [-q] [--timestamps] [--color/--no-color]
+prisma-next db init [--db <url>] [--config <path>] [--dry-run] [--json] [-v] [-q] [--color/--no-color]
 ```
 
 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
+- `--dry-run`: Only show the migration plan, do not apply it
 - `--json [format]`: Output as JSON (`object` only; `ndjson` is not supported for this command)
 - `-q, --quiet`: Quiet mode (errors only)
 - `-v, --verbose`: Verbose output (debug info, timings)
 - `-vv, --trace`: Trace output (deep internals, stack traces)
-- `--timestamps`: Add timestamps to output
 - `--color/--no-color`: Force/disable color output
 
 Examples:
@@ -647,7 +718,7 @@ Examples:
 prisma-next db init
 
 # Preview migration plan without applying
-prisma-next db init --plan
+prisma-next db init --dry-run
 
 # Specify database URL
 prisma-next db init --db postgresql://user:pass@localhost/db
@@ -662,6 +733,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 +746,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 +757,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`
@@ -699,7 +767,7 @@ export default defineConfig({
 7. **Plan Migration**: Calls `planner.plan()` with the contract IR, schema IR, additive-only policy, and `frameworkComponents` (the active target/adapter/extension descriptors)
    - On conflict: Returns a structured failure with conflict list
    - On success: Returns a migration plan with operations
-8. **Apply Migration** (if not `--plan`):
+8. **Apply Migration** (if not `--dry-run`):
    - Calls `runner.execute()` to apply the plan
    - After execution, verifies schema matches contract
    - Writes contract marker (and records a ledger entry via the target runner)
@@ -722,7 +790,7 @@ prisma-next db init ➜ Bootstrap a database to match the current contract
 Destination hash: sha256:abc123...
 
 This is a dry run. No changes were applied.
-Run without --plan to apply changes.
+Run without --dry-run to apply changes.
 ```
 
 **Output Format (TTY - Apply Mode):**
@@ -750,7 +818,7 @@ Applying migration plan and verifying schema...
   "plan": {
     "targetId": "postgres",
     "destination": {
-      "coreHash": "sha256:abc123..."
+      "storageHash": "sha256:abc123..."
     },
     "operations": [
       {
@@ -765,7 +833,7 @@ Applying migration plan and verifying schema...
     "operationsExecuted": 4
   },
   "marker": {
-    "coreHash": "sha256:abc123..."
+    "storageHash": "sha256:abc123..."
   }
 }
 ```
@@ -777,12 +845,33 @@ Applying migration plan and verifying schema...
 - `PN-CLI-4010`: Missing driver in config
 - `PN-CLI-4020`: Migration planning failed (conflicts)
 - `PN-CLI-4021`: Target does not support migrations
-- `PN-RTM-3000`: Runtime error (includes marker mismatch failures)
+- `PN-RUN-3000`: Runtime error (includes marker mismatch failures)
 
 **Behavior Notes:**
 
 - 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.
+- If the database has a marker that does **not** match the destination contract, `db init` fails (including in `--dry-run` 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 `--dry-run` mode for SQL targets, prints a DDL preview derived from planned operations
+- In interactive mode, destructive plans require confirmation before apply
+- In non-interactive mode, destructive plans fail unless `-y, --yes` is provided
+
+**Command:**
+```bash
+prisma-next db update [--db <url>] [--config <path>] [--dry-run] [-y|--yes] [--interactive|--no-interactive] [--json] [-v] [-q] [--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`):**
 
@@ -797,6 +886,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 +897,192 @@ 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] [--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 migration target detection)
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output (debug info, timings)
+
+**What it does:**
+1. Loads config and reads `contract.json` (the "to" contract)
+2. Reads existing migrations from `config.migrations.dir` (default: `migrations/`)
+3. Determines the starting point: `--from <hash>` if provided, otherwise the latest migration target
+4. Diffs the starting contract against the new contract using the target's migration planner
+5. Writes a new migration package (`migration.json` + `ops.json`) and attests the `migrationId`
+
+**Branching with `--from`:** Use `--from` to create a migration edge from a specific contract hash instead of the latest migration target. This enables branched migration graphs where multiple environments diverge from a common ancestor.
+
+### `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] [--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
+
+**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
+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
+- **With `--ref`**: Targets a specific ref instead of the contract hash; all refs from `refs.json` are rendered on the graph
+
+```bash
+prisma-next migration status [--db <url>] [--ref <name>] [--config <path>] [--json] [-v] [-q] [--color/--no-color]
+```
+
+**Options:**
+- `--db <url>`: Database connection string (enables online mode)
+- `--ref <name>`: Target a named ref from `migrations/refs.json` instead of the current contract hash
+- `--config <path>`: Path to `prisma-next.config.ts`
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+- `-v, --verbose`: Verbose output
+
+**What it does:**
+1. Reads migration packages from disk and reconstructs the migration graph
+2. Loads all refs from `migrations/refs.json` (if present) and renders them on the graph
+3. If `--ref` is provided, uses the ref's hash as the target instead of the contract hash; the active ref is highlighted in bold, other refs are dimmed
+4. If a DB connection is available, reads the marker to determine applied/pending status and shows distance from the ref target (e.g., "2 edge(s) behind ref")
+5. Displays the graph with `◄ DB`, `◄ Contract`, and `◄ ref:<name>` markers
+6. Shows operation summaries with destructive operation highlighting
+7. In `--ref` mode, the `CONTRACT.AHEAD` warning is suppressed — contract being ahead of a ref target is expected in multi-environment workflows
+
+**Branched graphs:** When the migration graph has multiple branches (divergence), status reports an `AMBIGUOUS_TARGET` error with the divergence point and branch details. Use `--ref` to target a specific branch.
+
+### `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 graph 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>] [--ref <name>] [--config <path>] [--json] [-v] [-q] [--color/--no-color]
+```
+
+**Options:**
+- `--db <url>`: Database connection string (optional; defaults to `config.db.connection`)
+- `--ref <name>`: Target a named ref from `migrations/refs.json` instead of the current contract hash
+- `--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)
+
+**What it does:**
+1. Reads attested migration packages from `config.migrations.dir`
+2. Reconstructs the migration graph (skips drafts with `migrationId: null`)
+3. Determines the destination hash: from `--ref` (via `refs.json`) or from `contract.json`
+4. Connects to the database and reads the current marker hash
+5. Finds the shortest path from the marker hash to the destination using graph pathfinding
+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.
+
+**Ref-based routing:** With `--ref`, apply targets the ref's hash instead of the contract hash. This enables multi-environment workflows where staging and production track different points in the migration graph.
+
+### `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)
+
+### `prisma-next migration ref`
+
+Manage named refs in `migrations/refs.json`. Refs map logical environment names (e.g., `staging`, `production`) to contract hashes, enabling multi-environment migration workflows where different environments track different points in the migration graph.
+
+```bash
+prisma-next migration ref set <name> <hash>    # Set a ref to a contract hash
+prisma-next migration ref get <name>            # Get the hash for a ref
+prisma-next migration ref delete <name>         # Delete a ref
+prisma-next migration ref list                  # List all refs
+```
+
+**Options (all subcommands):**
+- `--config <path>`: Path to `prisma-next.config.ts`
+- `--json`: Output as JSON object
+- `-q, --quiet`: Quiet mode (errors only)
+
+**Ref naming rules:** Lowercase alphanumeric with hyphens or forward slashes (e.g., `staging`, `prod/us-east`). No `.` or `..` segments.
+
+**Ref values:** Must be valid contract hashes (`sha256:<64 hex chars>` or `sha256:empty`).
+
+**Atomic writes:** `refs.json` is written atomically via temp file + rename to prevent corruption from concurrent writes.
+
 ## 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
@@ -864,19 +1104,20 @@ See `.cursor/rules/config-validation-and-normalization.mdc` for detailed pattern
 - Exit codes: 0 (success), 1 (runtime error), 2 (usage/config error)
 - **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.
+- **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/formatters/help.ts` for help formatters.
 - **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.
+- Supports global flags (JSON, verbosity, color, interactive, yes)
+- **Error Handling**: Uses structured errors (`CliStructuredError`), Result pattern, and `process.exit()`. Commands return `Result<T, CliStructuredError>`, 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
@@ -890,12 +1131,12 @@ See `.cursor/rules/config-validation-and-normalization.mdc` for detailed pattern
 
 ### Error Handling (`utils/errors.ts`, `utils/cli-errors.ts`, `utils/result.ts`, `utils/result-handler.ts`)
 - **Structured Errors**: Call sites throw `CliStructuredError` instances with full context (why, fix, docsUrl, etc.)
-- **Result Pattern**: Commands wrap logic in `performAction()` which only catches `CliStructuredError` instances
+- **Result Pattern**: Commands return `Result<T, CliStructuredError>` and use `handleResult()` for output and exit codes
 - **Error Conversion**: `CliStructuredError.toEnvelope()` converts errors to envelopes for output formatting
 - **Result Processing**: `handleResult()` processes Results, formats output, and returns exit codes
 - **Exit Codes**:
   - Usage/config errors (PN-CLI-4001-4007) → exit code 2
-  - Runtime errors (PN-RTM-3xxx) → exit code 1
+  - Runtime errors (PN-RUN-3xxx) → exit code 1
   - Success → exit code 0
 - **Fail Fast**: Non-structured errors propagate and are caught by Commander.js's `exitOverride()` with stack traces
 - See `.cursor/rules/cli-error-handling.mdc` for detailed patterns
@@ -905,7 +1146,7 @@ See `.cursor/rules/config-validation-and-normalization.mdc` for detailed pattern
 - **Removed**: `pack-assembly.ts` has been removed. Pack assembly is now handled by family instances. For SQL family, tests can import pack-based helpers directly from `packages/2-sql/3-tooling/family/src/core/assembly.ts` using relative paths.
 - Assembly logic is family-specific and owned by each family's instance implementation (e.g., `createSqlFamilyInstance` in `@prisma-next/family-sql`).
 
-### Output Formatting (`utils/output.ts`)
+### Output Formatting (`utils/formatters/`)
 - **Command Output Formatters**: Format human-readable output for commands (emit, verify, etc.)
   - Paths are shown as relative paths from current working directory (using `relative(process.cwd(), path)`)
   - Success indicators use consistent checkmark (✔) throughout
@@ -947,7 +1188,7 @@ See `.cursor/rules/config-validation-and-normalization.mdc` for detailed pattern
       - `types.storage`: Storage type bindings (`typeId`, `nativeType`, etc.) used in authoring/emission.
     - **`operations`**: Operation signatures the component contributes (extensions), used for type generation and (optionally) validation/lowering.
     - **Component-specific metadata**:
-      - Extensions may also include control-plane-only metadata like `databaseDependencies` (used by verify/schema-verify and not required at runtime).
+      - Extensions may also include control-plane-only metadata like `databaseDependencies` (used by verify and schema verification flows and not required at runtime).
 
 Unlike the older **manifest-based IR** approach (separate JSON manifests + a parsing/validation step to build an IR), descriptors are imported directly from packages (e.g., `@prisma-next/*/control`). This removes a file-format boundary and keeps the data and its types co-located.
 - Benefits: fewer moving parts (no JSON parsing), easier refactors (TypeScript catches drift), and clearer ownership (the package exports the canonical descriptor object).
@@ -999,6 +1240,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 history reconstruction
+- **`@prisma-next/core-control-plane`**: Config types, migration operation types, error types, control plane stack
 
 ## Design Decisions
 
@@ -1058,18 +1301,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-introspect`**: Exports `createDbIntrospectCommand`
-- **`@prisma-next/cli/commands/db-schema-verify`**: Exports `createDbSchemaVerifyCommand`
+- **`@prisma-next/cli/commands/db-update`**: Exports `createDbUpdateCommand`
+- **`@prisma-next/cli/commands/db-schema`**: Exports `createDbSchemaCommand`
 - **`@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/contract-infer`**: Exports `createContractInferCommand`
+- **`@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.