@prisma-next/family-sql 0.3.0-dev.4 → 0.3.0-dev.41

package/src/core/migrations/plan-helpers.ts

@@ -0,0 +1,164 @@
+import type { NotOk, Ok } from '@prisma-next/utils/result';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type {
+  AnyRecord,
+  CreateSqlMigrationPlanOptions,
+  SqlMigrationPlan,
+  SqlMigrationPlanOperation,
+  SqlMigrationPlanOperationStep,
+  SqlMigrationPlanOperationTarget,
+  SqlMigrationRunnerErrorCode,
+  SqlMigrationRunnerFailure,
+  SqlMigrationRunnerSuccessValue,
+  SqlPlannerConflict,
+  SqlPlannerFailureResult,
+  SqlPlannerSuccessResult,
+} from './types';
+
+const readOnlyEmptyObject: Record<string, never> = Object.freeze({});
+
+function cloneRecord<T extends AnyRecord>(value: T): T {
+  if (value === readOnlyEmptyObject) {
+    return value;
+  }
+  return Object.freeze({ ...value }) as T;
+}
+
+function freezeSteps(
+  steps: readonly SqlMigrationPlanOperationStep[],
+): readonly SqlMigrationPlanOperationStep[] {
+  if (steps.length === 0) {
+    return Object.freeze([]);
+  }
+  return Object.freeze(
+    steps.map((step) =>
+      Object.freeze({
+        description: step.description,
+        sql: step.sql,
+        ...(step.meta ? { meta: cloneRecord(step.meta) } : {}),
+      }),
+    ),
+  );
+}
+
+function freezeDetailsValue<T>(value: T): T {
+  // Primitives and null/undefined are already immutable, return as-is
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (typeof value !== 'object') {
+    return value;
+  }
+  // Arrays: shallow clone and freeze
+  if (Array.isArray(value)) {
+    return Object.freeze([...value]) as T;
+  }
+  // Objects: shallow clone and freeze (matching cloneRecord pattern)
+  return Object.freeze({ ...value }) as T;
+}
+
+function freezeTargetDetails<TTargetDetails>(
+  target: SqlMigrationPlanOperationTarget<TTargetDetails>,
+): SqlMigrationPlanOperationTarget<TTargetDetails> {
+  return Object.freeze({
+    id: target.id,
+    ...(target.details !== undefined ? { details: freezeDetailsValue(target.details) } : {}),
+  });
+}
+
+function freezeOperation<TTargetDetails>(
+  operation: SqlMigrationPlanOperation<TTargetDetails>,
+): SqlMigrationPlanOperation<TTargetDetails> {
+  return Object.freeze({
+    id: operation.id,
+    label: operation.label,
+    ...(operation.summary ? { summary: operation.summary } : {}),
+    operationClass: operation.operationClass,
+    target: freezeTargetDetails(operation.target),
+    precheck: freezeSteps(operation.precheck),
+    execute: freezeSteps(operation.execute),
+    postcheck: freezeSteps(operation.postcheck),
+    ...(operation.meta ? { meta: cloneRecord(operation.meta) } : {}),
+  });
+}
+
+function freezeOperations<TTargetDetails>(
+  operations: readonly SqlMigrationPlanOperation<TTargetDetails>[],
+): readonly SqlMigrationPlanOperation<TTargetDetails>[] {
+  if (operations.length === 0) {
+    return Object.freeze([]);
+  }
+  return Object.freeze(operations.map((operation) => freezeOperation(operation)));
+}
+
+export function createMigrationPlan<TTargetDetails>(
+  options: CreateSqlMigrationPlanOptions<TTargetDetails>,
+): SqlMigrationPlan<TTargetDetails> {
+  return Object.freeze({
+    targetId: options.targetId,
+    ...(options.origin !== undefined
+      ? { origin: options.origin ? Object.freeze({ ...options.origin }) : null }
+      : {}),
+    destination: Object.freeze({ ...options.destination }),
+    operations: freezeOperations(options.operations),
+    ...(options.meta ? { meta: cloneRecord(options.meta) } : {}),
+  });
+}
+
+export function plannerSuccess<TTargetDetails>(
+  plan: SqlMigrationPlan<TTargetDetails>,
+): SqlPlannerSuccessResult<TTargetDetails> {
+  return Object.freeze({
+    kind: 'success',
+    plan,
+  });
+}
+
+export function plannerFailure(conflicts: readonly SqlPlannerConflict[]): SqlPlannerFailureResult {
+  return Object.freeze({
+    kind: 'failure' as const,
+    conflicts: Object.freeze(
+      conflicts.map((conflict) =>
+        Object.freeze({
+          kind: conflict.kind,
+          summary: conflict.summary,
+          ...(conflict.why ? { why: conflict.why } : {}),
+          ...(conflict.location ? { location: Object.freeze({ ...conflict.location }) } : {}),
+          ...(conflict.meta ? { meta: cloneRecord(conflict.meta) } : {}),
+        }),
+      ),
+    ),
+  });
+}
+
+/**
+ * Creates a successful migration runner result.
+ */
+export function runnerSuccess(value: {
+  operationsPlanned: number;
+  operationsExecuted: number;
+}): Ok<SqlMigrationRunnerSuccessValue> {
+  return ok(
+    Object.freeze({
+      operationsPlanned: value.operationsPlanned,
+      operationsExecuted: value.operationsExecuted,
+    }),
+  );
+}
+
+/**
+ * Creates a failed migration runner result.
+ */
+export function runnerFailure(
+  code: SqlMigrationRunnerErrorCode,
+  summary: string,
+  options?: { why?: string; meta?: AnyRecord },
+): NotOk<SqlMigrationRunnerFailure> {
+  const failure: SqlMigrationRunnerFailure = Object.freeze({
+    code,
+    summary,
+    ...(options?.why ? { why: options.why } : {}),
+    ...(options?.meta ? { meta: cloneRecord(options.meta) } : {}),
+  });
+  return notOk(failure);
+}

package/src/core/migrations/policies.ts

@@ -0,0 +1,8 @@
+import type { MigrationOperationPolicy } from '@prisma-next/core-control-plane/types';
+
+/**
+ * Policy used by `db init`: additive-only operations, no widening/destructive steps.
+ */
+export const INIT_ADDITIVE_POLICY: MigrationOperationPolicy = Object.freeze({
+  allowedOperationClasses: Object.freeze(['additive'] as const),
+});

package/src/core/migrations/types.ts

@@ -0,0 +1,279 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type {
+  ControlAdapterDescriptor,
+  ControlDriverInstance,
+  ControlExtensionDescriptor,
+  ControlTargetDescriptor,
+  ControlTargetInstance,
+  MigrationOperationPolicy,
+  MigrationPlan,
+  MigrationPlannerConflict,
+  MigrationPlannerFailureResult,
+  MigrationPlannerSuccessResult,
+  MigrationPlanOperation,
+  MigrationRunnerExecutionChecks,
+  MigrationRunnerFailure,
+  MigrationRunnerSuccessValue,
+  OperationContext,
+  SchemaIssue,
+} from '@prisma-next/core-control-plane/types';
+import type { SqlContract, SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import type { SqlOperationSignature } from '@prisma-next/sql-operations';
+import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import type { Result } from '@prisma-next/utils/result';
+import type { SqlControlFamilyInstance } from '../control-instance';
+
+export type AnyRecord = Readonly<Record<string, unknown>>;
+
+export interface SqlControlStaticContributions {
+  readonly operationSignatures: () => ReadonlyArray<SqlOperationSignature>;
+}
+
+export interface ComponentDatabaseDependency<TTargetDetails> {
+  readonly id: string;
+  readonly label: string;
+  readonly install: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  readonly verifyDatabaseDependencyInstalled: (schema: SqlSchemaIR) => readonly SchemaIssue[];
+}
+
+export interface ComponentDatabaseDependencies<TTargetDetails> {
+  readonly init?: readonly ComponentDatabaseDependency<TTargetDetails>[];
+}
+
+export interface DatabaseDependencyProvider {
+  readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
+}
+
+export interface StorageTypePlanResult<TTargetDetails> {
+  readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+}
+
+/**
+ * Input for expanding parameterized native types.
+ */
+export interface ExpandNativeTypeInput {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
+export interface CodecControlHooks<TTargetDetails = unknown> {
+  planTypeOperations?: (options: {
+    readonly typeName: string;
+    readonly typeInstance: StorageTypeInstance;
+    readonly contract: SqlContract<SqlStorage>;
+    readonly schema: SqlSchemaIR;
+    readonly schemaName?: string;
+    readonly policy: MigrationOperationPolicy;
+  }) => StorageTypePlanResult<TTargetDetails>;
+  verifyType?: (options: {
+    readonly typeName: string;
+    readonly typeInstance: StorageTypeInstance;
+    readonly schema: SqlSchemaIR;
+    readonly schemaName?: string;
+  }) => readonly SchemaIssue[];
+  introspectTypes?: (options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly schemaName?: string;
+  }) => Promise<Record<string, StorageTypeInstance>>;
+  /**
+   * Expands a parameterized native type to its full SQL representation.
+   * Used by schema verification to compare contract types against database types.
+   *
+   * For example, expands:
+   * - { nativeType: 'character varying', typeParams: { length: 255 } } -> 'character varying(255)'
+   * - { nativeType: 'numeric', typeParams: { precision: 10, scale: 2 } } -> 'numeric(10,2)'
+   *
+   * Returns the expanded type string, or the original nativeType if no expansion is needed.
+   */
+  expandNativeType?: (input: ExpandNativeTypeInput) => string;
+}
+
+export interface SqlControlExtensionDescriptor<TTargetId extends string>
+  extends ControlExtensionDescriptor<'sql', TTargetId>,
+    SqlControlStaticContributions {
+  readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
+}
+
+export interface SqlControlAdapterDescriptor<TTargetId extends string>
+  extends ControlAdapterDescriptor<'sql', TTargetId>,
+    SqlControlStaticContributions {}
+
+export interface SqlMigrationPlanOperationStep {
+  readonly description: string;
+  readonly sql: string;
+  readonly meta?: AnyRecord;
+}
+
+export interface SqlMigrationPlanOperationTarget<TTargetDetails> {
+  readonly id: string;
+  readonly details?: TTargetDetails;
+}
+
+export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlanOperation {
+  readonly summary?: string;
+  readonly target: SqlMigrationPlanOperationTarget<TTargetDetails>;
+  readonly precheck: readonly SqlMigrationPlanOperationStep[];
+  readonly execute: readonly SqlMigrationPlanOperationStep[];
+  readonly postcheck: readonly SqlMigrationPlanOperationStep[];
+  readonly meta?: AnyRecord;
+}
+
+export interface SqlMigrationPlanContractInfo {
+  readonly storageHash: string;
+  readonly profileHash?: string;
+}
+
+export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
+  /**
+   * Origin contract identity that the plan expects the database to currently be at.
+   * If omitted, the runner treats the origin as "no marker present" (empty database),
+   * and will only proceed if no marker exists (or if the marker already matches destination).
+   */
+  readonly origin?: SqlMigrationPlanContractInfo | null;
+  /**
+   * Destination contract identity that the plan intends to reach.
+   */
+  readonly destination: SqlMigrationPlanContractInfo;
+  readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  readonly meta?: AnyRecord;
+}
+
+export type SqlPlannerConflictKind =
+  | 'typeMismatch'
+  | 'nullabilityConflict'
+  | 'indexIncompatible'
+  | 'foreignKeyConflict'
+  | 'missingButNonAdditive'
+  | 'unsupportedExtension'
+  | 'extensionMissing'
+  | 'unsupportedOperation';
+
+export interface SqlPlannerConflictLocation {
+  readonly table?: string;
+  readonly column?: string;
+  readonly index?: string;
+  readonly constraint?: string;
+  readonly extension?: string;
+  readonly type?: string;
+}
+
+export interface SqlPlannerConflict extends MigrationPlannerConflict {
+  readonly kind: SqlPlannerConflictKind;
+  readonly location?: SqlPlannerConflictLocation;
+  readonly meta?: AnyRecord;
+}
+
+export interface SqlPlannerSuccessResult<TTargetDetails>
+  extends Omit<MigrationPlannerSuccessResult, 'plan'> {
+  readonly kind: 'success';
+  readonly plan: SqlMigrationPlan<TTargetDetails>;
+}
+
+export interface SqlPlannerFailureResult extends Omit<MigrationPlannerFailureResult, 'conflicts'> {
+  readonly kind: 'failure';
+  readonly conflicts: readonly SqlPlannerConflict[];
+}
+
+export type SqlPlannerResult<TTargetDetails> =
+  | SqlPlannerSuccessResult<TTargetDetails>
+  | SqlPlannerFailureResult;
+
+export interface SqlMigrationPlannerPlanOptions {
+  readonly contract: SqlContract<SqlStorage>;
+  readonly schema: SqlSchemaIR;
+  readonly policy: MigrationOperationPolicy;
+  readonly schemaName?: string;
+  /**
+   * Active framework components participating in this composition.
+   * SQL targets can interpret this list to derive database dependencies.
+   * All components must have matching familyId ('sql') and targetId.
+   */
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}
+
+export interface SqlMigrationPlanner<TTargetDetails> {
+  plan(options: SqlMigrationPlannerPlanOptions): SqlPlannerResult<TTargetDetails>;
+}
+
+export interface SqlMigrationRunnerExecuteCallbacks<TTargetDetails> {
+  onOperationStart?(operation: SqlMigrationPlanOperation<TTargetDetails>): void;
+  onOperationComplete?(operation: SqlMigrationPlanOperation<TTargetDetails>): void;
+}
+
+export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
+  readonly plan: SqlMigrationPlan<TTargetDetails>;
+  readonly driver: ControlDriverInstance<'sql', string>;
+  /**
+   * Destination contract IR.
+   * Must correspond to `plan.destination` and is used for schema verification and marker/ledger writes.
+   */
+  readonly destinationContract: SqlContract<SqlStorage>;
+  /**
+   * Execution-time policy that defines which operation classes are allowed.
+   * The runner validates each operation against this policy before execution.
+   */
+  readonly policy: MigrationOperationPolicy;
+  readonly schemaName?: string;
+  readonly strictVerification?: boolean;
+  readonly callbacks?: SqlMigrationRunnerExecuteCallbacks<TTargetDetails>;
+  readonly context?: OperationContext;
+  /**
+   * Execution-time checks configuration.
+   * All checks default to `true` (enabled) when omitted.
+   */
+  readonly executionChecks?: MigrationRunnerExecutionChecks;
+  /**
+   * Active framework components participating in this composition.
+   * SQL targets can interpret this list to derive database dependencies.
+   * All components must have matching familyId ('sql') and targetId.
+   */
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}
+
+export type SqlMigrationRunnerErrorCode =
+  | 'DESTINATION_CONTRACT_MISMATCH'
+  | 'MARKER_ORIGIN_MISMATCH'
+  | 'POLICY_VIOLATION'
+  | 'PRECHECK_FAILED'
+  | 'POSTCHECK_FAILED'
+  | 'SCHEMA_VERIFY_FAILED'
+  | 'EXECUTION_FAILED';
+
+export interface SqlMigrationRunnerFailure extends MigrationRunnerFailure {
+  readonly code: SqlMigrationRunnerErrorCode;
+  readonly meta?: AnyRecord;
+}
+
+export interface SqlMigrationRunnerSuccessValue extends MigrationRunnerSuccessValue {}
+
+export type SqlMigrationRunnerResult = Result<
+  SqlMigrationRunnerSuccessValue,
+  SqlMigrationRunnerFailure
+>;
+
+export interface SqlMigrationRunner<TTargetDetails> {
+  execute(
+    options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
+  ): Promise<SqlMigrationRunnerResult>;
+}
+
+export interface SqlControlTargetDescriptor<TTargetId extends string, TTargetDetails>
+  extends ControlTargetDescriptor<
+      'sql',
+      TTargetId,
+      ControlTargetInstance<'sql', TTargetId>,
+      SqlControlFamilyInstance
+    >,
+    SqlControlStaticContributions {
+  createPlanner(family: SqlControlFamilyInstance): SqlMigrationPlanner<TTargetDetails>;
+  createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
+}
+
+export interface CreateSqlMigrationPlanOptions<TTargetDetails> {
+  readonly targetId: string;
+  readonly origin?: SqlMigrationPlanContractInfo | null;
+  readonly destination: SqlMigrationPlanContractInfo;
+  readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  readonly meta?: AnyRecord;
+}

package/src/core/runtime-descriptor.ts

@@ -0,0 +1,23 @@
+import type { RuntimeFamilyDescriptor } from '@prisma-next/core-execution-plane/types';
+import { createSqlRuntimeFamilyInstance, type SqlRuntimeFamilyInstance } from './runtime-instance';
+
+/**
+ * SQL execution-plane family descriptor.
+ *
+ * Note: this is currently named `sqlRuntimeFamilyDescriptor` because the execution plane
+ * framework types are still using the `Runtime*` naming (`RuntimeFamilyDescriptor`, etc.).
+ *
+ * This will be renamed to `sqlExecutionFamilyDescriptor` as part of `TML-1842`.
+ */
+export const sqlRuntimeFamilyDescriptor: RuntimeFamilyDescriptor<'sql', SqlRuntimeFamilyInstance> =
+  {
+    kind: 'family',
+    id: 'sql',
+    familyId: 'sql',
+    version: '0.0.1',
+    create() {
+      return createSqlRuntimeFamilyInstance();
+    },
+  };
+
+Object.freeze(sqlRuntimeFamilyDescriptor);

package/src/core/runtime-instance.ts

@@ -0,0 +1,22 @@
+import type { RuntimeFamilyInstance } from '@prisma-next/core-execution-plane/types';
+
+/**
+ * SQL execution-plane family instance interface.
+ *
+ * Note: this is currently named `SqlRuntimeFamilyInstance` because the execution plane
+ * framework types are still using the `Runtime*` naming (`RuntimeFamilyInstance`, etc.).
+ *
+ * This will be renamed to `SqlExecutionFamilyInstance` as part of `TML-1842`.
+ */
+export interface SqlRuntimeFamilyInstance extends RuntimeFamilyInstance<'sql'> {}
+
+/**
+ * Creates a SQL execution-plane family instance.
+ *
+ * This will be renamed to `createSqlExecutionFamilyInstance()` as part of `TML-1842`.
+ */
+export function createSqlRuntimeFamilyInstance(): SqlRuntimeFamilyInstance {
+  return {
+    familyId: 'sql' as const,
+  };
+}