prisma-next 0.5.0-dev.9 → 0.5.0

package/dist/types-D7x-IFLO.d.mts

@@ -0,0 +1,858 @@
+import { t as CliStructuredError } from "./cli-errors-B9OBbled.mjs";
+import { Result } from "@prisma-next/utils/result";
+import { ContractSourceDiagnostics, ContractSourceProvider } from "@prisma-next/config/config-types";
+import { ControlAdapterDescriptor, ControlDriverDescriptor, ControlDriverInstance, ControlExtensionDescriptor, ControlFamilyDescriptor, ControlFamilyInstance, ControlTargetDescriptor, CoreSchemaView, MigrationPlanOperation, MigrationPlannerConflict, OperationPreview, SignDatabaseResult, VerifyDatabaseResult, VerifyDatabaseSchemaResult } from "@prisma-next/framework-components/control";
+import { TargetBoundComponentDescriptor } from "@prisma-next/framework-components/components";
+import { Contract, ContractMarkerRecord } from "@prisma-next/contract/types";
+import { PslDocumentAst } from "@prisma-next/framework-components/psl-ast";
+import { OnDiskMigrationPackage } from "@prisma-next/migration-tools/package";
+
+//#region src/control-api/operations/db-verify.d.ts
+/**
+ * Inputs for the aggregate `db verify` operation.
+ *
+ * Loader → verifier pipeline. The loader (sole descriptor-import
+ * boundary) builds a {@link import('@prisma-next/migration-tools/aggregate').ContractSpaceAggregate};
+ * the aggregate verifier bundles `markerCheck` + per-space pre-projected
+ * `schemaCheck`. `mode: 'strict' | 'lenient'` maps directly to the user
+ * facing `--strict` flag.
+ */
+interface ExecuteDbVerifyOptions<TFamilyId extends string, TTargetId extends string> {
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly contract: Contract;
+  readonly migrationsDir: string;
+  readonly targetId: TTargetId;
+  readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly mode: 'strict' | 'lenient';
+  readonly skipSchema: boolean;
+  readonly skipMarker: boolean;
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Result of the aggregate verify operation.
+ *
+ * Marker-check failures are surfaced as a {@link CliStructuredError}
+ * (same envelope code `5002` the legacy `runContractSpaceVerifierMarkerCheck`
+ * emitted, so downstream tooling and integration tests assert on the
+ * same shape).
+ *
+ * On success, the per-space schema results are returned for the CLI to
+ * render. When `skipSchema` is true (`--marker-only`), the schema map
+ * is empty.
+ */
+interface ExecuteDbVerifySuccess {
+  readonly schemaResults: ReadonlyMap<string, VerifyDatabaseSchemaResult>;
+  readonly memberOrder: readonly string[];
+  readonly appSpaceId: string;
+}
+type ExecuteDbVerifyResult = Result<ExecuteDbVerifySuccess, CliStructuredError>;
+/**
+ * Loader → verifier pipeline shared by `db verify` modes (`full`,
+ * `marker-only`, `schema-only`).
+ *
+ * 1. **Load**: build a {@link import('@prisma-next/migration-tools/aggregate').ContractSpaceAggregate}
+ *    from descriptors + on-disk on-disk artefacts. Layout / drift /
+ *    integrity / disjointness violations short-circuit with a
+ *    structured CLI error.
+ * 2. **Read DB state**: marker rows + (when `skipSchema` is `false`)
+ *    schema introspection.
+ * 3. **Verify**: {@link verifyAggregate} returns per-space
+ *    `markerCheck` + per-space pre-projected `schemaCheck` (closes F23).
+ *    Marker mismatches map to `CliStructuredError` (code `5002`) so
+ *    callers (CLI command) can render and exit. Schema results are
+ *    returned to the caller verbatim.
+ */
+declare function executeDbVerify<TFamilyId extends string, TTargetId extends string>(options: ExecuteDbVerifyOptions<TFamilyId, TTargetId>): Promise<ExecuteDbVerifyResult>;
+//#endregion
+//#region src/control-api/types.d.ts
+/**
+ * Options for creating a control client.
+ *
+ * Note: This is NOT the same as CLI config. There's no `contract` field,
+ * no file paths. The client is config-agnostic.
+ *
+ * The descriptor types use permissive `any` because family-specific descriptors
+ * (e.g., SqlFamilyDescriptor) have more specific `create` method signatures that
+ * are not compatible with the base ControlFamilyDescriptor type due to TypeScript
+ * variance rules. The client implementation casts these internally.
+ */
+interface ControlClientOptions {
+  readonly family: ControlFamilyDescriptor<any, any>;
+  readonly target: ControlTargetDescriptor<any, any, any>;
+  readonly adapter: ControlAdapterDescriptor<any, any, any>;
+  /** Optional - control client can be created without driver for offline operations */
+  readonly driver?: ControlDriverDescriptor<any, any, any, any>;
+  readonly extensionPacks?: ReadonlyArray<ControlExtensionDescriptor<any, any, any>>;
+  /**
+   * Optional default connection for auto-connect.
+   * When provided, operations will auto-connect if not already connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+}
+/**
+ * Action names for control-api operations that can emit progress events.
+ */
+type ControlActionName = 'dbInit' | 'dbUpdate' | 'dbVerify' | 'migrationApply' | 'verify' | 'schemaVerify' | 'sign' | 'introspect' | 'emit';
+/**
+ * Progress event emitted during control-api operation execution.
+ *
+ * Events model operation progress using a span-based model:
+ * - `spanStart`: Begin a timed segment (supports nesting via parentSpanId)
+ * - `spanEnd`: Complete a timed segment
+ *
+ * All operation-specific progress (e.g., per-migration-operation) is modeled
+ * as nested spans rather than special event types.
+ *
+ * Events are delivered via an optional `onProgress` callback to avoid polluting
+ * return types. If the callback is absent, operations emit no events (zero overhead).
+ */
+type ControlProgressEvent = {
+  readonly action: ControlActionName;
+  readonly kind: 'spanStart';
+  readonly spanId: string;
+  readonly parentSpanId?: string;
+  readonly label: string;
+} | {
+  readonly action: ControlActionName;
+  readonly kind: 'spanEnd';
+  readonly spanId: string;
+  readonly outcome: 'ok' | 'skipped' | 'error';
+};
+/**
+ * Callback function for receiving progress events during control-api operations.
+ *
+ * @param event - The progress event emitted by the operation
+ */
+type OnControlProgress = (event: ControlProgressEvent) => void;
+/**
+ * Options for the verify operation.
+ */
+interface VerifyOptions {
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: unknown;
+  /**
+   * Database connection. If provided, verify will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Options for the schemaVerify operation.
+ */
+interface SchemaVerifyOptions {
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: unknown;
+  /**
+   * Whether to use strict mode for schema verification.
+   * In strict mode, extra tables/columns are reported as issues.
+   * Default: false (tolerant mode - allows superset)
+   */
+  readonly strict?: boolean;
+  /**
+   * Database connection. If provided, schemaVerify will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Options for the sign operation.
+ */
+interface SignOptions {
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: unknown;
+  /**
+   * Path to the contract file (for metadata in the result).
+   */
+  readonly contractPath?: string;
+  /**
+   * Path to the config file (for metadata in the result).
+   */
+  readonly configPath?: string;
+  /**
+   * Database connection. If provided, sign will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Options for the dbInit operation.
+ */
+interface DbInitOptions {
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: unknown;
+  /**
+   * Mode for the dbInit operation.
+   * - 'plan': Returns planned operations without applying
+   * - 'apply': Applies operations and writes marker
+   */
+  readonly mode: 'plan' | 'apply';
+  /**
+   * Database connection. If provided, dbInit will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /**
+   * On-disk migrations directory. Always required — every `db init`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Options for the dbUpdate operation.
+ */
+interface DbUpdateOptions {
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: unknown;
+  /**
+   * Mode for the dbUpdate operation.
+   * - 'plan': Returns planned operations without applying
+   * - 'apply': Applies operations and writes marker/ledger
+   */
+  readonly mode: 'plan' | 'apply';
+  /**
+   * Database connection. If provided, dbUpdate will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /**
+   * When true, allows applying plans that contain destructive operations
+   * (e.g., DROP TABLE, DROP COLUMN, ALTER TYPE).
+   * When false (default), the operation returns a failure if the plan
+   * includes destructive operations, prompting the user to confirm interactively
+   * or re-run with -y/--yes.
+   */
+  readonly acceptDataLoss?: boolean;
+  /**
+   * On-disk migrations directory. Always required — every `db update`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Options for the dbVerify operation.
+ *
+ * Drives the loader → aggregate-verifier pipeline. `strict` maps to
+ * `verifyAggregate({ mode: 'strict' | 'lenient' })`; `skipSchema`
+ * mirrors the `--marker-only` CLI flag and short-circuits the schema
+ * portion of the verifier.
+ */
+interface DbVerifyOptions {
+  readonly contract: unknown;
+  readonly migrationsDir: string;
+  readonly strict: boolean;
+  readonly skipSchema: boolean;
+  readonly skipMarker: boolean;
+  readonly connection?: unknown;
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Options for the introspect operation.
+ */
+interface IntrospectOptions {
+  /**
+   * Optional schema name to introspect.
+   */
+  readonly schema?: string;
+  /**
+   * Database connection. If provided, introspect will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Contract configuration for emit operation.
+ */
+interface EmitContractConfig {
+  /**
+   * Contract source provider.
+   */
+  readonly source: ContractSourceProvider;
+  /**
+   * Output path for contract.json.
+   * The .d.ts types file will be colocated (e.g., contract.json → contract.d.ts).
+   */
+  readonly output: string;
+}
+/**
+ * Options for the emit operation.
+ */
+interface EmitOptions {
+  /**
+   * Contract configuration containing source, output, and types paths.
+   */
+  readonly contractConfig: EmitContractConfig;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Per-space breakdown of an aggregate plan / apply.
+ *
+ * Surfaces the canonical schedule shape — extensions alphabetically,
+ * then app — together with the operations attributed to each space and,
+ * when the run was applied, the resulting per-space marker hash.
+ *
+ * M6 sub-spec § Output shape contract — every space involved in a run
+ * is observable in the success summary, including its post-apply
+ * marker, so the per-space invariant is visible to the user (closing
+ * F4 / F7 from `e2e-verification.md`).
+ */
+interface AggregatePerSpaceExecutionEntry {
+  readonly spaceId: string;
+  /** `'app'` for the application's contract space; `'extension'` for any extension space. */
+  readonly kind: 'app' | 'extension';
+  /**
+   * Operations attributed to this space (display ops). In `mode: 'plan'`
+   * this is the planned set; in `mode: 'apply'` it is the same set
+   * (every op was executed in order, the runner does not skip).
+   */
+  readonly operations: ReadonlyArray<{
+    readonly id: string;
+    readonly label: string;
+    readonly operationClass: string;
+  }>;
+  /**
+   * Post-apply marker hash for this space. Present only when the run
+   * was applied (i.e. `mode: 'apply'` and the runner returned ok).
+   * Equals the per-space plan's `destination.storageHash`.
+   */
+  readonly marker?: {
+    readonly storageHash: string;
+  };
+}
+/**
+ * Successful dbInit result.
+ */
+interface DbInitSuccess {
+  readonly mode: 'plan' | 'apply';
+  readonly plan: {
+    readonly operations: ReadonlyArray<{
+      readonly id: string;
+      readonly label: string;
+      readonly operationClass: string;
+    }>;
+    /**
+     * Family-agnostic textual preview of the planned operations, e.g.
+     * `language: 'sql'` for SQL families and `language: 'mongodb-shell'`
+     * for the Mongo family. Replaces the previous `sql?: readonly string[]`
+     * field; consumers that previously read `plan.sql` should read
+     * `plan.preview?.statements.map((s) => s.text)`.
+     */
+    readonly preview?: OperationPreview;
+  };
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly execution?: {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+  };
+  readonly marker?: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). Present whenever the aggregate flow
+   * produced one — both `mode: 'plan'` and `mode: 'apply'`.
+   *
+   * See {@link AggregatePerSpaceExecutionEntry}.
+   */
+  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly summary: string;
+}
+/**
+ * Failure codes for dbInit operation.
+ */
+type DbInitFailureCode = 'PLANNING_FAILED' | 'MARKER_ORIGIN_MISMATCH' | 'RUNNER_FAILED';
+/**
+ * Failure details for dbInit operation.
+ */
+interface DbInitFailure {
+  readonly code: DbInitFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+  readonly marker?: {
+    readonly storageHash?: string;
+    readonly profileHash?: string;
+  };
+  readonly destination?: {
+    readonly storageHash: string;
+    readonly profileHash?: string | undefined;
+  };
+}
+/**
+ * Result type for dbInit operation.
+ * Uses Result pattern: success returns DbInitSuccess, failure returns DbInitFailure.
+ */
+type DbInitResult = Result<DbInitSuccess, DbInitFailure>;
+/**
+ * Successful dbUpdate result.
+ */
+interface DbUpdateSuccess {
+  readonly mode: 'plan' | 'apply';
+  readonly plan: {
+    readonly operations: ReadonlyArray<{
+      readonly id: string;
+      readonly label: string;
+      readonly operationClass: string;
+    }>;
+    /**
+     * Family-agnostic textual preview of the planned operations, e.g.
+     * `language: 'sql'` for SQL families and `language: 'mongodb-shell'`
+     * for the Mongo family. Replaces the previous `sql?: readonly string[]`
+     * field; consumers that previously read `plan.sql` should read
+     * `plan.preview?.statements.map((s) => s.text)`.
+     */
+    readonly preview?: OperationPreview;
+  };
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly execution?: {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+  };
+  readonly marker?: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   */
+  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly summary: string;
+}
+/**
+ * Failure codes for dbUpdate operation.
+ */
+type DbUpdateFailureCode = 'PLANNING_FAILED' | 'RUNNER_FAILED' | 'DESTRUCTIVE_CHANGES';
+/**
+ * Failure details for dbUpdate operation.
+ */
+interface DbUpdateFailure {
+  readonly code: DbUpdateFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+/**
+ * Result type for dbUpdate operation.
+ * Uses Result pattern: success returns DbUpdateSuccess, failure returns DbUpdateFailure.
+ */
+type DbUpdateResult = Result<DbUpdateSuccess, DbUpdateFailure>;
+/**
+ * Successful emit result.
+ * Contains the hashes and paths of emitted files.
+ */
+interface EmitSuccess {
+  /** Storage hash of the emitted contract */
+  readonly storageHash: string;
+  /** Execution hash of the emitted contract (if execution section exists) */
+  readonly executionHash?: string;
+  /** Profile hash of the emitted contract (target-specific) */
+  readonly profileHash: string;
+  /** The emitted contract as JSON string */
+  readonly contractJson: string;
+  /** The emitted contract TypeScript declarations */
+  readonly contractDts: string;
+}
+/**
+ * Failure codes for emit operation.
+ */
+type EmitFailureCode = 'CONTRACT_SOURCE_INVALID' | 'CONTRACT_VALIDATION_FAILED' | 'EMIT_FAILED';
+/**
+ * Failure details for emit operation.
+ */
+interface EmitFailure {
+  readonly code: EmitFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+  readonly diagnostics?: ContractSourceDiagnostics;
+}
+/**
+ * Result type for emit operation.
+ * Uses Result pattern: success returns EmitSuccess, failure returns EmitFailure.
+ */
+type EmitResult = Result<EmitSuccess, EmitFailure>;
+/**
+ * Options for the aggregate-walking `migrationApply` operation.
+ *
+ * The control-api operation is responsible for: loading the
+ * contract-space aggregate, reading per-space marker rows from the
+ * live database, plotting per-space paths via `graphWalkStrategy`
+ * (replay-only — no synth, no introspection), and dispatching
+ * through the shared `applyAggregate` primitive. The CLI command
+ * just resolves the descriptor surface (config, refs, contract
+ * envelope, app-space migration packages) and hands the inputs in.
+ *
+ * Sub-spec § `migration apply` semantics + § Required changes 1.
+ */
+interface MigrationApplyOptions {
+  /** Already-validated app contract (the canonical "where we are heading" hash). */
+  readonly contract: unknown;
+  /** Migrations root directory (`migrations/` under the project). */
+  readonly migrationsDir: string;
+  /**
+   * Already-loaded app-space migration packages. The CLI loads these
+   * via `loadMigrationPackages(appMigrationsDir)` before invoking
+   * `migrationApply`.
+   */
+  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
+  /**
+   * Optional app-space ref override. When provided, the app member's
+   * graph-walk targets this hash instead of `contract.storage.storageHash`.
+   * Extension members always walk to their own `headRef.hash`.
+   */
+  readonly refHash?: string;
+  /**
+   * Required invariants on the user-supplied app-space ref. Threaded
+   * into the graph-walk's `required` calculation so the planner picks
+   * an invariant-bearing path. Ignored when `refHash` is absent.
+   */
+  readonly refInvariants?: readonly string[];
+  /**
+   * Resolved name of the user-supplied app-space ref (the literal the
+   * user passed to `--ref`). Decorates `pathDecision.refName` and any
+   * `MIGRATION.NO_INVARIANT_PATH` envelope raised during graph-walk.
+   * Ignored when `refHash` is absent.
+   */
+  readonly refName?: string;
+  /**
+   * Database connection. If provided, migrationApply will connect before executing.
+   * If omitted, the client must already be connected.
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Record of a successfully applied per-space migration. One entry per
+ * contract space that had pending migrations — empty `applied` means
+ * every space was already at its head.
+ */
+/**
+ * One entry per authored migration package applied. Preserves the
+ * single-space `migrationsApplied` count semantics (each entry is
+ * one migration directory) so `applied.length === migrationsApplied`.
+ *
+ * Per-space aggregate detail (markers, ops grouped by space) lives
+ * on `perSpace[]`; this list is the per-edge view.
+ */
+interface MigrationApplyAppliedEntry {
+  readonly spaceId: string;
+  readonly dirName: string;
+  readonly migrationHash: string;
+  readonly from: string;
+  readonly to: string;
+  readonly operationsExecuted: number;
+}
+/**
+ * Successful migrationApply result. Carries both the legacy
+ * single-space fields (`markerHash` is the **app member's** post-apply
+ * marker, surfaced for back-compat with single-space callers) and the
+ * per-space breakdown (`perSpace` — markers / operations / canonical
+ * order, per M6 sub-spec § Output shape).
+ */
+/**
+ * Path-decision summary for the **app member** post-apply. Surfaced
+ * for back-compat with single-space callers (and the cli-journeys
+ * suite, which inspects `requiredInvariants`/`satisfiedInvariants`/
+ * `selectedPath` to validate invariant routing).
+ *
+ * Per-space path decisions for extension members are not surfaced —
+ * extensions own their own ref/invariant control.
+ */
+interface MigrationApplyPathDecision {
+  readonly fromHash: string;
+  readonly toHash: string;
+  readonly alternativeCount: number;
+  readonly tieBreakReasons: readonly string[];
+  readonly refName?: string;
+  readonly requiredInvariants: readonly string[];
+  readonly satisfiedInvariants: readonly string[];
+  readonly selectedPath: readonly {
+    readonly dirName: string;
+    readonly migrationHash: string;
+    readonly from: string;
+    readonly to: string;
+    readonly invariants: readonly string[];
+  }[];
+}
+interface MigrationApplySuccess {
+  readonly migrationsApplied: number;
+  readonly markerHash: string;
+  readonly applied: readonly MigrationApplyAppliedEntry[];
+  readonly summary: string;
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   * Always present for the aggregate-walking operation.
+   */
+  readonly perSpace: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  /**
+   * Path-decision data for the app member. Present whenever the
+   * graph-walk strategy ran for the app (i.e. always for the
+   * aggregate-walking apply path). Absent only for the no-op
+   * "Already up to date" early return when the app has no plan.
+   */
+  readonly pathDecision?: MigrationApplyPathDecision;
+}
+/**
+ * Failure codes for migrationApply operation.
+ */
+type MigrationApplyFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
+/**
+ * Failure details for migrationApply operation.
+ */
+interface MigrationApplyFailure {
+  readonly code: MigrationApplyFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+/**
+ * Result type for migrationApply operation.
+ */
+type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyFailure>;
+/**
+ * Options for the standalone executeContractEmit function.
+ *
+ * `executeContractEmit` is the canonical publication path for both the
+ * `prisma-next contract emit` CLI command and the `@prisma-next/vite-plugin-contract-emit`
+ * Vite plugin. Do not duplicate the load → emit → publish dance elsewhere; if a
+ * caller needs additional behavior, extend this options shape and update the
+ * single implementation rather than building a parallel publication path.
+ *
+ * Concurrent calls for the same output JSON path are serialized per-output via
+ * a FIFO queue; concurrent calls for distinct outputs run in parallel.
+ */
+interface ContractEmitOptions {
+  /** Path to the prisma-next.config.ts file */
+  readonly configPath: string;
+  /** Optional AbortSignal for cancelling the in-flight emit */
+  readonly signal?: AbortSignal;
+  /** Optional progress callback for observing source-resolution and emit spans */
+  readonly onProgress?: OnControlProgress;
+}
+/**
+ * Result from the standalone executeContractEmit function.
+ *
+ * Always describes the bytes that were just published to disk. Failures throw
+ * (config / source-resolution / emit / publish) — callers do not need to
+ * branch on a result discriminator.
+ */
+interface ContractEmitResult {
+  /** Hash of the storage contract (schema-level) */
+  readonly storageHash: string;
+  /** Hash of the execution contract (if execution section exists) */
+  readonly executionHash?: string;
+  /** Hash of the profile (target+extensions) */
+  readonly profileHash: string;
+  /** Paths to the emitted files */
+  readonly files: {
+    /** Path to the emitted contract.json file */readonly json: string; /** Path to the emitted contract.d.ts file */
+    readonly dts: string;
+  };
+  /**
+   * Warning surfaced by `validateContractDeps` after a successful publication.
+   * Callers (CLI, Vite plugin) decide how to render this; the operation does
+   * not write to stderr itself. Undefined when no warning was raised.
+   */
+  readonly validationWarning?: string;
+}
+/**
+ * Programmatic control client for Prisma Next operations.
+ *
+ * Lifecycle: `connect(connection)` before operations, `close()` when done.
+ * Both `init()` and `connect()` are auto-called by operations if needed,
+ * but `connect()` requires a connection so must be called explicitly first
+ * unless a default connection was provided in options.
+ *
+ * @see README.md "Programmatic Control API" section for usage examples
+ */
+interface ControlClient {
+  /**
+   * Initializes the client by creating the control plane stack,
+   * family instance, and validating framework components.
+   *
+   * Idempotent (safe to call multiple times).
+   * Called automatically by `connect()` if not already initialized.
+   */
+  init(): void;
+  /**
+   * Establishes a database connection.
+   * Auto-calls `init()` if not already initialized.
+   * Must be called before any database operations unless a default connection
+   * was provided in options.
+   *
+   * @param connection - Driver-specific connection input (e.g., URL string for Postgres).
+   *   If omitted, uses the default connection from options (if provided).
+   * @throws If connection fails, already connected, driver is not configured,
+   *   or no connection provided and no default connection in options.
+   */
+  connect(connection?: unknown): Promise<void>;
+  /**
+   * Closes the database connection.
+   * Idempotent (safe to call multiple times).
+   * After close(), can call `connect()` again with same or different URL.
+   */
+  close(): Promise<void>;
+  /**
+   * Verifies database marker matches the contract.
+   * Compares storageHash and profileHash.
+   *
+   * @returns Structured result (ok: false for mismatch, not throwing)
+   * @throws If not connected or infrastructure failure
+   */
+  verify(options: VerifyOptions): Promise<VerifyDatabaseResult>;
+  /**
+   * Verifies database schema satisfies the contract requirements.
+   *
+   * @param options.strict - If true, extra tables/columns are issues. Default: false
+   * @returns Structured result with schema issues
+   * @throws If not connected or infrastructure failure
+   */
+  schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult>;
+  /**
+   * Signs the database with a contract signature.
+   * Writes or updates the signature if schema verification passes.
+   * Idempotent (no-op if signature already matches).
+   *
+   * @returns Structured result
+   * @throws If not connected or infrastructure failure
+   */
+  sign(options: SignOptions): Promise<SignDatabaseResult>;
+  /**
+   * Initializes database schema from contract.
+   * Uses additive-only policy (no destructive changes).
+   *
+   * @param options.mode - 'plan' to preview, 'apply' to execute
+   * @returns Result pattern: Ok with planned/executed operations, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  dbInit(options: DbInitOptions): Promise<DbInitResult>;
+  /**
+   * Updates a database schema to match the current contract.
+   * Creates the signature table if it does not exist. No preconditions required.
+   * Allows additive, widening, and destructive operation classes.
+   *
+   * @param options.mode - 'plan' to preview, 'apply' to execute
+   * @returns Result pattern: Ok with planned/executed operations, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
+  /**
+   * Verifies the database against every contract space (app + extensions).
+   *
+   * Loader → aggregate-verifier pipeline:
+   * - The loader catches layout / drift / disjointness violations.
+   * - The aggregate verifier surfaces marker-vs-on-disk drift and orphan
+   *   markers, and (unless `skipSchema` is true) per-space schema
+   *   verification with pre-projection (closes F23).
+   *
+   * @returns Result pattern: per-space schema results on success;
+   *          structured CLI error on marker / loader failure.
+   * @throws If not connected or infrastructure failure
+   */
+  dbVerify(options: DbVerifyOptions): Promise<ExecuteDbVerifyResult>;
+  /**
+   * Reads the contract marker from the database.
+   * Returns null if no marker exists (fresh database).
+   *
+   * @throws If not connected or infrastructure failure
+   */
+  readMarker(): Promise<ContractMarkerRecord | null>;
+  /**
+   * Reads every marker row (one per contract space). Used by the
+   * per-space verifier to detect orphan marker rows and marker-vs-on-disk
+   * drift after a database connection has been established.
+   */
+  readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
+  /**
+   * Applies pre-planned on-disk migrations to the database.
+   * Each migration runs in its own transaction with full execution checks.
+   * Resume-safe: re-running after failure picks up from the last applied migration.
+   *
+   * @param options.originHash - Explicit source hash for the apply path
+   * @param options.destinationHash - Explicit destination hash for the apply path
+   * @param options.pendingMigrations - Ordered migrations to execute
+   * @returns Result pattern: Ok with applied details, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult>;
+  /**
+   * Introspects the database schema.
+   *
+   * @returns Raw schema IR
+   * @throws If not connected or infrastructure failure
+   */
+  introspect(options?: IntrospectOptions): Promise<unknown>;
+  /**
+   * Converts a schema IR to a schema view for CLI tree rendering.
+   * Delegates to the family instance's toSchemaView method.
+   *
+   * @param schemaIR - The schema IR from introspect()
+   * @returns CoreSchemaView if the family supports it, undefined otherwise
+   */
+  toSchemaView(schemaIR: unknown): CoreSchemaView | undefined;
+  /**
+   * Infers a PSL contract AST from an introspected schema IR.
+   * Delegates to the family instance's inferPslContract method.
+   *
+   * @param schemaIR - The schema IR from introspect()
+   * @returns PslDocumentAst if the family supports the capability, undefined otherwise
+   */
+  inferPslContract(schemaIR: unknown): PslDocumentAst | undefined;
+  /**
+   * Renders a textual preview of a migration plan's operations for the CLI's
+   * "DDL preview" output. Delegates to the family instance's
+   * `toOperationPreview` method.
+   *
+   * @param operations - The migration plan operations to render
+   * @returns OperationPreview if the family supports the capability, undefined otherwise
+   */
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview | undefined;
+  /**
+   * Emits the contract to JSON and TypeScript declarations.
+   * This is an offline operation that does NOT require a database connection.
+   * Uses `init()` to create the stack but does NOT call `connect()`.
+   *
+   * @returns Result pattern: Ok with emit details, NotOk with failure details
+   */
+  emit(options: EmitOptions): Promise<EmitResult>;
+}
+//#endregion
+export { ExecuteDbVerifyOptions as A, EmitSuccess as C, SchemaVerifyOptions as D, OnControlProgress as E, executeDbVerify as M, SignOptions as O, EmitResult as S, MigrationApplyPathDecision as T, DbUpdateSuccess as _, ControlClient as a, EmitFailureCode as b, DbInitFailure as c, DbInitResult as d, DbInitSuccess as f, DbUpdateResult as g, DbUpdateOptions as h, ControlActionName as i, ExecuteDbVerifyResult as j, VerifyOptions as k, DbInitFailureCode as l, DbUpdateFailureCode as m, ContractEmitOptions as n, ControlClientOptions as o, DbUpdateFailure as p, ContractEmitResult as r, ControlProgressEvent as s, AggregatePerSpaceExecutionEntry as t, DbInitOptions as u, EmitContractConfig as v, IntrospectOptions as w, EmitOptions as x, EmitFailure as y };
+//# sourceMappingURL=types-D7x-IFLO.d.mts.map