@prisma-next/core-control-plane 0.3.0-pr.99.4 → 0.3.0-pr.99.6

package/dist/stack.mjs

@@ -0,0 +1,30 @@
+//#region src/stack.ts
+/**
+* Creates a ControlPlaneStack from component descriptors.
+*
+* Provides sensible defaults:
+* - `driver` defaults to `undefined` (optional for commands that don't need DB connection)
+* - `extensionPacks` defaults to `[]` (empty array)
+*
+* @example
+* ```ts
+* const stack = createControlPlaneStack({
+*   target: postgresTarget,
+*   adapter: postgresAdapter,
+*   driver: postgresDriver, // optional
+*   extensionPacks: [pgvector], // optional
+* });
+* ```
+*/
+function createControlPlaneStack(input) {
+	return {
+		target: input.target,
+		adapter: input.adapter,
+		driver: input.driver,
+		extensionPacks: input.extensionPacks ?? []
+	};
+}
+
+//#endregion
+export { createControlPlaneStack };
+//# sourceMappingURL=stack.mjs.map

package/dist/stack.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.mjs","names":[],"sources":["../src/stack.ts"],"sourcesContent":["import type {\n  ControlAdapterDescriptor,\n  ControlDriverDescriptor,\n  ControlExtensionDescriptor,\n  ControlPlaneStack,\n  ControlTargetDescriptor,\n} from './types';\n\n/**\n * Creates a ControlPlaneStack from component descriptors.\n *\n * Provides sensible defaults:\n * - `driver` defaults to `undefined` (optional for commands that don't need DB connection)\n * - `extensionPacks` defaults to `[]` (empty array)\n *\n * @example\n * ```ts\n * const stack = createControlPlaneStack({\n *   target: postgresTarget,\n *   adapter: postgresAdapter,\n *   driver: postgresDriver, // optional\n *   extensionPacks: [pgvector], // optional\n * });\n * ```\n */\nexport function createControlPlaneStack<TFamilyId extends string, TTargetId extends string>(input: {\n  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;\n  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;\n  readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;\n  readonly extensionPacks?: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[] | undefined;\n}): ControlPlaneStack<TFamilyId, TTargetId> {\n  return {\n    target: input.target,\n    adapter: input.adapter,\n    driver: input.driver,\n    extensionPacks: input.extensionPacks ?? [],\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAyBA,SAAgB,wBAA4E,OAKhD;AAC1C,QAAO;EACL,QAAQ,MAAM;EACd,SAAS,MAAM;EACf,QAAQ,MAAM;EACd,gBAAgB,MAAM,kBAAkB,EAAE;EAC3C"}

package/dist/types-CsaU_uQP.d.mts

@@ -0,0 +1,595 @@
+import { t as CoreSchemaView } from "./schema-view-BG_ebqoV.mjs";
+import { AdapterDescriptor, AdapterInstance, DriverDescriptor, DriverInstance, ExtensionDescriptor, ExtensionInstance, FamilyDescriptor, FamilyInstance, TargetBoundComponentDescriptor, TargetDescriptor, TargetInstance } from "@prisma-next/contract/framework-components";
+import { ContractIR } from "@prisma-next/contract/ir";
+import { ContractMarkerRecord, TargetFamilyHook } from "@prisma-next/contract/types";
+import { Result } from "@prisma-next/utils/result";
+
+//#region src/migrations.d.ts
+
+/**
+ * Migration operation classes define the safety level of an operation.
+ * - 'additive': Adds new structures without modifying existing ones (safe)
+ * - 'widening': Relaxes constraints or expands types (generally safe)
+ * - 'destructive': Removes or alters existing structures (potentially unsafe)
+ */
+type MigrationOperationClass = 'additive' | 'widening' | 'destructive';
+/**
+ * Policy defining which operation classes are allowed during a migration.
+ */
+interface MigrationOperationPolicy {
+  readonly allowedOperationClasses: readonly MigrationOperationClass[];
+}
+/**
+ * A single migration operation for display purposes.
+ * Contains only the fields needed for CLI output (tree view, JSON envelope).
+ */
+interface MigrationPlanOperation {
+  /** Unique identifier for this operation (e.g., "table.users.create"). */
+  readonly id: string;
+  /** Human-readable label for display in UI/CLI (e.g., "Create table users"). */
+  readonly label: string;
+  /** The class of operation (additive, widening, destructive). */
+  readonly operationClass: MigrationOperationClass;
+}
+/**
+ * A migration plan for display purposes.
+ * Contains only the fields needed for CLI output (summary, JSON envelope).
+ */
+interface MigrationPlan {
+  /** The target ID this plan is for (e.g., 'postgres'). */
+  readonly targetId: string;
+  /** Destination contract identity that the plan intends to reach. */
+  readonly destination: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  /** Ordered list of operations to execute. */
+  readonly operations: readonly MigrationPlanOperation[];
+}
+/**
+ * A conflict detected during migration planning.
+ */
+interface MigrationPlannerConflict {
+  /** Kind of conflict (e.g., 'typeMismatch', 'nullabilityConflict'). */
+  readonly kind: string;
+  /** Human-readable summary of the conflict. */
+  readonly summary: string;
+  /** Optional explanation of why this conflict occurred. */
+  readonly why?: string;
+}
+/**
+ * Successful planner result with the migration plan.
+ */
+interface MigrationPlannerSuccessResult {
+  readonly kind: 'success';
+  readonly plan: MigrationPlan;
+}
+/**
+ * Failed planner result with the list of conflicts.
+ */
+interface MigrationPlannerFailureResult {
+  readonly kind: 'failure';
+  readonly conflicts: readonly MigrationPlannerConflict[];
+}
+/**
+ * Union type for planner results.
+ */
+type MigrationPlannerResult = MigrationPlannerSuccessResult | MigrationPlannerFailureResult;
+/**
+ * Success value for migration runner execution.
+ */
+interface MigrationRunnerSuccessValue {
+  readonly operationsPlanned: number;
+  readonly operationsExecuted: number;
+}
+/**
+ * Failure details for migration runner execution.
+ */
+interface MigrationRunnerFailure {
+  /** Error code for the failure. */
+  readonly code: string;
+  /** Human-readable summary of the failure. */
+  readonly summary: string;
+  /** Optional explanation of why the failure occurred. */
+  readonly why?: string;
+  /** Optional metadata for debugging and UX (e.g., schema issues, SQL state). */
+  readonly meta?: Record<string, unknown>;
+}
+/**
+ * Result type for migration runner execution.
+ */
+type MigrationRunnerResult = Result<MigrationRunnerSuccessValue, MigrationRunnerFailure>;
+/**
+ * Execution-time checks configuration for migration runners.
+ * All checks default to `true` (enabled) when omitted.
+ */
+interface MigrationRunnerExecutionChecks {
+  /**
+   * Whether to run prechecks before executing operations.
+   * Defaults to `true` (prechecks are run).
+   */
+  readonly prechecks?: boolean;
+  /**
+   * Whether to run postchecks after executing operations.
+   * Defaults to `true` (postchecks are run).
+   */
+  readonly postchecks?: boolean;
+  /**
+   * Whether to run idempotency probe (check if postcheck is already satisfied before execution).
+   * Defaults to `true` (idempotency probe is run).
+   */
+  readonly idempotencyChecks?: boolean;
+}
+/**
+ * Migration planner interface for planning schema changes.
+ * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends string = string> {
+  plan(options: {
+    readonly contract: unknown;
+    readonly schema: unknown;
+    readonly policy: MigrationOperationPolicy;
+    /**
+     * Active framework components participating in this composition.
+     * Families/targets can interpret this list to derive family-specific metadata.
+     * All components must have matching familyId and targetId.
+     */
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  }): MigrationPlannerResult;
+}
+/**
+ * Migration runner interface for executing migration plans.
+ * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
+  execute(options: {
+    readonly plan: MigrationPlan;
+    readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+    readonly destinationContract: unknown;
+    readonly policy: MigrationOperationPolicy;
+    readonly callbacks?: {
+      onOperationStart?(op: MigrationPlanOperation): void;
+      onOperationComplete?(op: MigrationPlanOperation): void;
+    };
+    /**
+     * Execution-time checks configuration.
+     * All checks default to `true` (enabled) when omitted.
+     */
+    readonly executionChecks?: MigrationRunnerExecutionChecks;
+    /**
+     * Active framework components participating in this composition.
+     * Families/targets can interpret this list to derive family-specific metadata.
+     * All components must have matching familyId and targetId.
+     */
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  }): Promise<MigrationRunnerResult>;
+}
+/**
+ * Optional capability interface for targets that support migrations.
+ * Targets that implement migrations expose this via their descriptor.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TFamilyInstance - The family instance type (e.g., SqlControlFamilyInstance)
+ */
+interface TargetMigrationsCapability<TFamilyId extends string = string, TTargetId extends string = string, TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>> {
+  createPlanner(family: TFamilyInstance): MigrationPlanner<TFamilyId, TTargetId>;
+  createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Control-plane family instance interface.
+ * Extends the base FamilyInstance with control-plane domain actions.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TSchemaIR - The schema IR type returned by introspect() (family-specific)
+ */
+interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR = unknown> extends FamilyInstance<TFamilyId> {
+  /**
+   * Validates a contract JSON and returns a validated ContractIR (without mappings).
+   * Mappings are runtime-only and should not be part of ContractIR.
+   *
+   * Note: The returned ContractIR may include additional fields from the emitted contract
+   * (like coreHash, profileHash) that are not part of the ContractIR type but are preserved
+   * for use by verify/sign operations.
+   */
+  validateContractIR(contractJson: unknown): ContractIR;
+  /**
+   * Verifies the database marker against the contract.
+   * Compares target, coreHash, and profileHash.
+   *
+   * @param options.contractIR - The validated contract (from validateContractIR). Must have
+   *   coreHash and target fields for verification. These fields are present in emitted
+   *   contracts but not in the ContractIR type definition.
+   */
+  verify(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR: unknown;
+    readonly expectedTargetId: string;
+    readonly contractPath: string;
+    readonly configPath?: string;
+  }): Promise<VerifyDatabaseResult>;
+  /**
+   * Verifies the database schema against the contract.
+   * Compares contract requirements against live database schema.
+   */
+  schemaVerify(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR: unknown;
+    readonly strict: boolean;
+    readonly contractPath: string;
+    readonly configPath?: string;
+    /**
+     * Active framework components participating in this composition.
+     * All components must have matching familyId and targetId.
+     */
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
+  }): Promise<VerifyDatabaseSchemaResult>;
+  /**
+   * Signs the database with the contract marker.
+   * Writes or updates the contract marker if schema verification passes.
+   * This operation is idempotent - if the marker already matches, no changes are made.
+   */
+  sign(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR: unknown;
+    readonly contractPath: string;
+    readonly configPath?: string;
+  }): Promise<SignDatabaseResult>;
+  /**
+   * Reads the contract marker from the database.
+   * Returns null if no marker exists.
+   */
+  readMarker(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+  }): Promise<ContractMarkerRecord | null>;
+  /**
+   * Introspects the database schema and returns a family-specific schema IR.
+   *
+   * This is a read-only operation that returns a snapshot of the live database schema.
+   * The method is family-owned and delegates to target/adapter-specific introspectors
+   * to perform the actual schema introspection.
+   *
+   * @param options - Introspection options
+   * @param options.driver - Control plane driver for database connection
+   * @param options.contractIR - Optional contract for contract-guided introspection.
+   *   When provided, families may use it for filtering, optimization, or validation
+   *   during introspection. The contract does not change the meaning of "what exists"
+   *   in the database - it only guides how introspection is performed.
+   * @returns Promise resolving to the family-specific Schema IR (e.g., `SqlSchemaIR` for SQL).
+   *   The IR represents the complete schema snapshot at the time of introspection.
+   */
+  introspect(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR?: unknown;
+  }): Promise<TSchemaIR>;
+  /**
+   * Optionally projects a family-specific Schema IR into a core schema view.
+   * Families that provide this method enable rich tree output for CLI visualization.
+   * Families that do not provide it still support introspection via raw Schema IR.
+   */
+  toSchemaView?(schema: TSchemaIR): CoreSchemaView;
+  /**
+   * Emits contract JSON and DTS as strings.
+   * Uses the instance's preassembled state (operation registry, type imports, extension IDs).
+   * Handles stripping mappings and validation internally.
+   */
+  emitContract(options: {
+    readonly contractIR: ContractIR | unknown;
+  }): Promise<EmitContractResult>;
+}
+/**
+ * Control-plane target instance interface.
+ * Extends the base TargetInstance with control-plane specific behavior.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface ControlTargetInstance<TFamilyId extends string, TTargetId extends string> extends TargetInstance<TFamilyId, TTargetId> {}
+/**
+ * Control-plane adapter instance interface.
+ * Extends the base AdapterInstance with control-plane specific behavior.
+ * Families extend this with family-specific adapter interfaces.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface ControlAdapterInstance<TFamilyId extends string, TTargetId extends string> extends AdapterInstance<TFamilyId, TTargetId> {}
+/**
+ * Control-plane driver instance interface.
+ * Extends the base DriverInstance with control-plane specific behavior.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface ControlDriverInstance<TFamilyId extends string, TTargetId extends string> extends DriverInstance<TFamilyId, TTargetId> {
+  query<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<{
+    readonly rows: Row[];
+  }>;
+  close(): Promise<void>;
+}
+/**
+ * Control-plane extension instance interface.
+ * Extends the base ExtensionInstance with control-plane specific behavior.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface ControlExtensionInstance<TFamilyId extends string, TTargetId extends string> extends ExtensionInstance<TFamilyId, TTargetId> {}
+/**
+ * Operation context for propagating metadata through control-plane operation call chains.
+ * Inspired by OpenTelemetry's Context and Sentry's Scope patterns.
+ *
+ * This context carries informational metadata (like file paths) that can be used for
+ * error reporting, logging, and debugging, but is not required for structural correctness.
+ * It allows subsystems to propagate context without coupling to file I/O concerns.
+ *
+ * @example
+ * ```typescript
+ * const context: OperationContext = {
+ *   contractPath: './contract.json',
+ *   configPath: './prisma-next.config.ts',
+ * };
+ *
+ * await runner.execute({ plan, driver, destinationContract: contract, context });
+ * ```
+ */
+interface OperationContext {
+  /**
+   * Path to the contract file (if applicable).
+   * Used for error reporting and metadata, not for file I/O.
+   */
+  readonly contractPath?: string;
+  /**
+   * Path to the configuration file (if applicable).
+   * Used for error reporting and metadata, not for file I/O.
+   */
+  readonly configPath?: string;
+  /**
+   * Additional metadata that can be propagated through the call chain.
+   * Extensible for future needs without breaking changes.
+   */
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A bundle of control-plane component descriptors for a specific family and target.
+ *
+ * This struct groups the target, adapter, driver (optional), and extension packs
+ * needed to create a family instance and run CLI commands. Use `createControlPlaneStack()`
+ * to construct with sensible defaults.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface ControlPlaneStack<TFamilyId extends string, TTargetId extends string> {
+  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;
+  readonly driver: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly extensionPacks: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[];
+}
+/**
+ * Descriptor for a control-plane family (e.g., SQL).
+ * Provides the family hook and factory method.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TFamilyInstance - The family instance type
+ */
+interface ControlFamilyDescriptor<TFamilyId extends string, TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>> extends FamilyDescriptor<TFamilyId> {
+  readonly hook: TargetFamilyHook;
+  create<TTargetId extends string>(stack: ControlPlaneStack<TFamilyId, TTargetId>): TFamilyInstance;
+}
+/**
+ * Descriptor for a control-plane target component (e.g., Postgres target).
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TTargetInstance - The target instance type
+ * @template TFamilyInstance - The family instance type for migrations (optional)
+ */
+interface ControlTargetDescriptor<TFamilyId extends string, TTargetId extends string, TTargetInstance extends ControlTargetInstance<TFamilyId, TTargetId> = ControlTargetInstance<TFamilyId, TTargetId>, TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>> extends TargetDescriptor<TFamilyId, TTargetId> {
+  /**
+   * Optional migrations capability.
+   * Targets that support migrations expose this property.
+   * The capability is parameterized by family and target IDs to ensure type-level
+   * compatibility of framework components.
+   */
+  readonly migrations?: TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>;
+  create(): TTargetInstance;
+}
+/**
+ * Descriptor for a control-plane adapter component (e.g., Postgres adapter).
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TAdapterInstance - The adapter instance type
+ */
+interface ControlAdapterDescriptor<TFamilyId extends string, TTargetId extends string, TAdapterInstance extends ControlAdapterInstance<TFamilyId, TTargetId> = ControlAdapterInstance<TFamilyId, TTargetId>> extends AdapterDescriptor<TFamilyId, TTargetId> {
+  create(): TAdapterInstance;
+}
+/**
+ * Descriptor for a control-plane driver component (e.g., Postgres driver).
+ *
+ * The connection input type is driver-specific. For example:
+ * - Postgres uses a connection string (URL)
+ * - Other drivers may accept structured objects (e.g., file paths, credentials)
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TDriverInstance - The driver instance type
+ * @template TConnection - The connection input type (defaults to `string` for URL-based drivers)
+ */
+interface ControlDriverDescriptor<TFamilyId extends string, TTargetId extends string, TDriverInstance extends ControlDriverInstance<TFamilyId, TTargetId> = ControlDriverInstance<TFamilyId, TTargetId>, TConnection = string> extends DriverDescriptor<TFamilyId, TTargetId> {
+  create(connection: TConnection): Promise<TDriverInstance>;
+}
+/**
+ * Descriptor for a control-plane extension component (e.g., pgvector).
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TExtensionInstance - The extension instance type
+ */
+interface ControlExtensionDescriptor<TFamilyId extends string, TTargetId extends string, TExtensionInstance extends ControlExtensionInstance<TFamilyId, TTargetId> = ControlExtensionInstance<TFamilyId, TTargetId>> extends ExtensionDescriptor<TFamilyId, TTargetId> {
+  create(): TExtensionInstance;
+}
+/**
+ * Result type for database marker verification operations.
+ */
+interface VerifyDatabaseResult {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly summary: string;
+  readonly contract: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly marker?: {
+    readonly coreHash?: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly missingCodecs?: readonly string[];
+  readonly codecCoverageSkipped?: boolean;
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+/**
+ * Schema issue type for schema verification results.
+ */
+interface SchemaIssue {
+  readonly kind: 'missing_table' | 'missing_column' | 'extra_table' | 'extra_column' | 'extra_primary_key' | 'extra_foreign_key' | 'extra_unique_constraint' | 'extra_index' | 'type_mismatch' | 'nullability_mismatch' | 'primary_key_mismatch' | 'foreign_key_mismatch' | 'unique_constraint_mismatch' | 'index_mismatch' | 'extension_missing';
+  readonly table: string;
+  readonly column?: string;
+  readonly indexOrConstraint?: string;
+  readonly expected?: string;
+  readonly actual?: string;
+  readonly message: string;
+}
+/**
+ * Contract-shaped verification tree node for schema verification results.
+ * Family-agnostic structure that follows the contract structure.
+ */
+interface SchemaVerificationNode {
+  readonly status: 'pass' | 'warn' | 'fail';
+  readonly kind: string;
+  readonly name: string;
+  readonly contractPath: string;
+  readonly code: string;
+  readonly message: string;
+  readonly expected: unknown;
+  readonly actual: unknown;
+  readonly children: readonly SchemaVerificationNode[];
+}
+/**
+ * Result type for database schema verification operations.
+ */
+interface VerifyDatabaseSchemaResult {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly summary: string;
+  readonly contract: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly schema: {
+    readonly issues: readonly SchemaIssue[];
+    readonly root: SchemaVerificationNode;
+    readonly counts: {
+      readonly pass: number;
+      readonly warn: number;
+      readonly fail: number;
+      readonly totalNodes: number;
+    };
+  };
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath?: string;
+    readonly strict: boolean;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+/**
+ * Result type for contract emission operations.
+ */
+interface EmitContractResult {
+  readonly contractJson: string;
+  readonly contractDts: string;
+  readonly coreHash: string;
+  readonly profileHash: string;
+}
+/**
+ * Result envelope for schema introspection operations.
+ * Used by CLI for JSON output when introspecting database schemas.
+ *
+ * @template TSchemaIR - The family-specific Schema IR type (e.g., `SqlSchemaIR` for SQL)
+ */
+interface IntrospectSchemaResult<TSchemaIR> {
+  readonly ok: true;
+  readonly summary: string;
+  readonly target: {
+    readonly familyId: string;
+    readonly id: string;
+  };
+  readonly schema: TSchemaIR;
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly dbUrl?: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+/**
+ * Result type for database signing operations.
+ * Returned when writing or updating the contract marker in the database.
+ */
+interface SignDatabaseResult {
+  readonly ok: boolean;
+  readonly summary: string;
+  readonly contract: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly marker: {
+    readonly created: boolean;
+    readonly updated: boolean;
+    readonly previous?: {
+      readonly coreHash?: string;
+      readonly profileHash?: string;
+    };
+  };
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+//#endregion
+export { MigrationRunnerExecutionChecks as A, MigrationPlanOperation as C, MigrationPlannerResult as D, MigrationPlannerFailureResult as E, MigrationRunnerResult as M, MigrationRunnerSuccessValue as N, MigrationPlannerSuccessResult as O, TargetMigrationsCapability as P, MigrationPlan as S, MigrationPlannerConflict as T, SignDatabaseResult as _, ControlExtensionDescriptor as a, MigrationOperationClass as b, ControlFamilyInstance as c, ControlTargetInstance as d, EmitContractResult as f, SchemaVerificationNode as g, SchemaIssue as h, ControlDriverInstance as i, MigrationRunnerFailure as j, MigrationRunner as k, ControlPlaneStack as l, OperationContext as m, ControlAdapterInstance as n, ControlExtensionInstance as o, IntrospectSchemaResult as p, ControlDriverDescriptor as r, ControlFamilyDescriptor as s, ControlAdapterDescriptor as t, ControlTargetDescriptor as u, VerifyDatabaseResult as v, MigrationPlanner as w, MigrationOperationPolicy as x, VerifyDatabaseSchemaResult as y };
+//# sourceMappingURL=types-CsaU_uQP.d.mts.map

package/dist/types-CsaU_uQP.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CsaU_uQP.d.mts","names":[],"sources":["../src/migrations.ts","../src/types.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { A as MigrationRunnerExecutionChecks, C as MigrationPlanOperation, D as MigrationPlannerResult, E as MigrationPlannerFailureResult, M as MigrationRunnerResult, N as MigrationRunnerSuccessValue, O as MigrationPlannerSuccessResult, P as TargetMigrationsCapability, S as MigrationPlan, T as MigrationPlannerConflict, _ as SignDatabaseResult, a as ControlExtensionDescriptor, b as MigrationOperationClass, c as ControlFamilyInstance, d as ControlTargetInstance, f as EmitContractResult, g as SchemaVerificationNode, h as SchemaIssue, i as ControlDriverInstance, j as MigrationRunnerFailure, k as MigrationRunner, l as ControlPlaneStack, m as OperationContext, n as ControlAdapterInstance, o as ControlExtensionInstance, p as IntrospectSchemaResult, r as ControlDriverDescriptor, s as ControlFamilyDescriptor, t as ControlAdapterDescriptor, u as ControlTargetDescriptor, v as VerifyDatabaseResult, w as MigrationPlanner, x as MigrationOperationPolicy, y as VerifyDatabaseSchemaResult } from "./types-CsaU_uQP.mjs";
+export { type ControlAdapterDescriptor, type ControlAdapterInstance, type ControlDriverDescriptor, type ControlDriverInstance, type ControlExtensionDescriptor, type ControlExtensionInstance, type ControlFamilyDescriptor, type ControlFamilyInstance, type ControlPlaneStack, type ControlTargetDescriptor, type ControlTargetInstance, type EmitContractResult, type IntrospectSchemaResult, type MigrationOperationClass, type MigrationOperationPolicy, type MigrationPlan, type MigrationPlanOperation, type MigrationPlanner, type MigrationPlannerConflict, type MigrationPlannerFailureResult, type MigrationPlannerResult, type MigrationPlannerSuccessResult, type MigrationRunner, type MigrationRunnerExecutionChecks, type MigrationRunnerFailure, type MigrationRunnerResult, type MigrationRunnerSuccessValue, type OperationContext, type SchemaIssue, type SchemaVerificationNode, type SignDatabaseResult, type TargetMigrationsCapability, type VerifyDatabaseResult, type VerifyDatabaseSchemaResult };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {  };