@prisma-next/family-sql 0.3.0-dev.16 → 0.3.0-dev.162

package/src/core/runtime-instance.ts

@@ -1,144 +1,22 @@
-import { assertRuntimeContractRequirementsSatisfied } from '@prisma-next/core-execution-plane/framework-components';
-import type {
-  RuntimeAdapterDescriptor,
-  RuntimeDriverDescriptor,
-  RuntimeDriverInstance,
-  RuntimeFamilyDescriptor,
-  RuntimeFamilyInstance,
-  RuntimeTargetDescriptor,
-} from '@prisma-next/core-execution-plane/types';
-import type { Log, Plugin, RuntimeVerifyOptions } from '@prisma-next/runtime-executor';
-import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
-import type {
-  Adapter,
-  LoweredStatement,
-  SelectAst,
-  SqlDriver,
-} from '@prisma-next/sql-relational-core/ast';
-import type {
-  Runtime,
-  RuntimeOptions,
-  SqlRuntimeAdapterInstance,
-  SqlRuntimeExtensionDescriptor,
-} from '@prisma-next/sql-runtime';
-import { createRuntime, createRuntimeContext } from '@prisma-next/sql-runtime';
+import type { RuntimeFamilyInstance } from '@prisma-next/framework-components/execution';
 
 /**
- * SQL runtime driver instance type.
- * Combines identity properties with SQL-specific behavior methods.
- */
-export type SqlRuntimeDriverInstance<TTargetId extends string = string> = RuntimeDriverInstance<
-  'sql',
-  TTargetId
-> &
-  SqlDriver;
-
-// Re-export SqlRuntimeAdapterInstance from sql-runtime for consumers
-export type { SqlRuntimeAdapterInstance } from '@prisma-next/sql-runtime';
-
-/**
- * SQL runtime family instance interface.
- * Extends base RuntimeFamilyInstance with SQL-specific runtime creation method.
+ * 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 runtime from contract, driver options, and verification settings.
-   *
-   * Extension packs are routed through composition (at instance creation time),
-   * not through this method. This aligns with control-plane composition patterns.
-   *
-   * @param options - Runtime creation options
-   * @param options.contract - SQL contract
-   * @param options.driverOptions - Driver options (e.g., PostgresDriverOptions)
-   * @param options.verify - Runtime verification options
-   * @param options.plugins - Optional plugins
-   * @param options.mode - Optional runtime mode
-   * @param options.log - Optional log instance
-   * @returns Runtime instance
-   */
-  createRuntime<TContract extends SqlContract<SqlStorage>>(options: {
-    readonly contract: TContract;
-    readonly driverOptions: unknown;
-    readonly verify: RuntimeVerifyOptions;
-    readonly plugins?: readonly Plugin<
-      TContract,
-      Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
-      SqlDriver
-    >[];
-    readonly mode?: 'strict' | 'permissive';
-    readonly log?: Log;
-  }): Runtime;
-}
+export interface SqlRuntimeFamilyInstance extends RuntimeFamilyInstance<'sql'> {}
 
 /**
- * Creates a SQL runtime family instance from runtime descriptors.
+ * Creates a SQL execution-plane family instance.
  *
- * Routes the same framework composition as control-plane:
- * family, target, adapter, driver, extensionPacks (all as descriptors with IDs).
+ * This will be renamed to `createSqlExecutionFamilyInstance()` as part of `TML-1842`.
  */
-export function createSqlRuntimeFamilyInstance<TTargetId extends string>(options: {
-  readonly family: RuntimeFamilyDescriptor<'sql'>;
-  readonly target: RuntimeTargetDescriptor<'sql', TTargetId>;
-  readonly adapter: RuntimeAdapterDescriptor<
-    'sql',
-    TTargetId,
-    SqlRuntimeAdapterInstance<TTargetId>
-  >;
-  readonly driver: RuntimeDriverDescriptor<'sql', TTargetId, SqlRuntimeDriverInstance<TTargetId>>;
-  readonly extensionPacks?: readonly SqlRuntimeExtensionDescriptor<TTargetId>[];
-}): SqlRuntimeFamilyInstance {
-  const {
-    family: familyDescriptor,
-    target: targetDescriptor,
-    adapter: adapterDescriptor,
-    driver: driverDescriptor,
-    extensionPacks: extensionDescriptors = [],
-  } = options;
-
+export function createSqlRuntimeFamilyInstance(): SqlRuntimeFamilyInstance {
   return {
     familyId: 'sql' as const,
-    createRuntime<TContract extends SqlContract<SqlStorage>>(runtimeOptions: {
-      readonly contract: TContract;
-      readonly driverOptions: unknown;
-      readonly verify: RuntimeVerifyOptions;
-      readonly plugins?: readonly Plugin<
-        TContract,
-        Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
-        SqlDriver
-      >[];
-      readonly mode?: 'strict' | 'permissive';
-      readonly log?: Log;
-    }): Runtime {
-      // Validate contract requirements against provided descriptors
-      assertRuntimeContractRequirementsSatisfied({
-        contract: runtimeOptions.contract,
-        family: familyDescriptor,
-        target: targetDescriptor,
-        adapter: adapterDescriptor,
-        extensionPacks: extensionDescriptors,
-      });
-
-      // Create driver instance
-      const driverInstance = driverDescriptor.create(runtimeOptions.driverOptions);
-
-      // Create context via descriptor-first API
-      const context = createRuntimeContext<TContract, TTargetId>({
-        contract: runtimeOptions.contract,
-        target: targetDescriptor,
-        adapter: adapterDescriptor,
-        extensionPacks: extensionDescriptors,
-      });
-
-      const runtimeOptions_: RuntimeOptions<TContract> = {
-        driver: driverInstance,
-        verify: runtimeOptions.verify,
-        context,
-        ...(runtimeOptions.plugins ? { plugins: runtimeOptions.plugins } : {}),
-        ...(runtimeOptions.mode ? { mode: runtimeOptions.mode } : {}),
-        ...(runtimeOptions.log ? { log: runtimeOptions.log } : {}),
-      };
-
-      return createRuntime(runtimeOptions_);
-    },
   };
 }

package/src/core/schema-verify/verify-helpers.ts

@@ -3,7 +3,10 @@
  * These functions verify schema IR against contract requirements.
  */
 
-import type { SchemaIssue, SchemaVerificationNode } from '@prisma-next/core-control-plane/types';
+import type {
+  SchemaIssue,
+  SchemaVerificationNode,
+} from '@prisma-next/framework-components/control';
 import type {
   ForeignKey,
   Index,
@@ -33,9 +36,71 @@ export function arraysEqual(a: readonly string[], b: readonly string[]): boolean
   return true;
 }
 
+// ============================================================================
+// Semantic Satisfaction Predicates
+// ============================================================================
+// These predicates implement the "stronger satisfies weaker" logic for storage
+// objects. They are used by both verification and migration planning to ensure
+// consistent behavior across the control plane.
+
+/**
+ * Checks if a unique constraint requirement is satisfied by the given columns.
+ *
+ * Semantic satisfaction: a unique constraint requirement can be satisfied by:
+ * - A unique constraint with the same columns, OR
+ * - A unique index with the same columns
+ *
+ * @param uniques - The unique constraints in the schema table
+ * @param indexes - The indexes in the schema table
+ * @param columns - The columns required by the unique constraint
+ * @returns true if the requirement is satisfied
+ */
+export function isUniqueConstraintSatisfied(
+  uniques: readonly SqlUniqueIR[],
+  indexes: readonly SqlIndexIR[],
+  columns: readonly string[],
+): boolean {
+  // Check for matching unique constraint
+  const hasConstraint = uniques.some((unique) => arraysEqual(unique.columns, columns));
+  if (hasConstraint) {
+    return true;
+  }
+  // Check for matching unique index (semantic satisfaction)
+  return indexes.some((index) => index.unique && arraysEqual(index.columns, columns));
+}
+
+/**
+ * Checks if an index requirement is satisfied by the given columns.
+ *
+ * Semantic satisfaction: a non-unique index requirement can be satisfied by:
+ * - Any index (unique or non-unique) with the same columns, OR
+ * - A unique constraint with the same columns (stronger satisfies weaker)
+ *
+ * @param indexes - The indexes in the schema table
+ * @param uniques - The unique constraints in the schema table
+ * @param columns - The columns required by the index
+ * @returns true if the requirement is satisfied
+ */
+export function isIndexSatisfied(
+  indexes: readonly SqlIndexIR[],
+  uniques: readonly SqlUniqueIR[],
+  columns: readonly string[],
+): boolean {
+  // Check for any matching index (unique or non-unique)
+  const hasMatchingIndex = indexes.some((index) => arraysEqual(index.columns, columns));
+  if (hasMatchingIndex) {
+    return true;
+  }
+  // Check for matching unique constraint (semantic satisfaction)
+  return uniques.some((unique) => arraysEqual(unique.columns, columns));
+}
+
 /**
  * Verifies primary key matches between contract and schema.
  * Returns 'pass' or 'fail'.
+ *
+ * Uses semantic satisfaction: identity is based on (table + kind + columns).
+ * Name differences are ignored by default (names are for DDL/diagnostics, not identity).
  */
 export function verifyPrimaryKey(
   contractPK: PrimaryKey,
@@ -64,18 +129,8 @@ export function verifyPrimaryKey(
     return 'fail';
   }
 
-  // Compare name if both are modeled
-  if (contractPK.name && schemaPK.name && contractPK.name !== schemaPK.name) {
-    issues.push({
-      kind: 'primary_key_mismatch',
-      table: tableName,
-      indexOrConstraint: contractPK.name,
-      expected: contractPK.name,
-      actual: schemaPK.name,
-      message: `Table "${tableName}" has primary key name mismatch: expected "${contractPK.name}", got "${schemaPK.name}"`,
-    });
-    return 'fail';
-  }
+  // Name differences are ignored for semantic satisfaction.
+  // Names are persisted for deterministic DDL and diagnostics but are not identity.
 
   return 'pass';
 }
@@ -83,6 +138,9 @@ export function verifyPrimaryKey(
 /**
  * Verifies foreign keys match between contract and schema.
  * Returns verification nodes for the tree.
+ *
+ * Uses semantic satisfaction: identity is based on (table + columns + referenced table + referenced columns).
+ * Name differences are ignored by default (names are for DDL/diagnostics, not identity).
  */
 export function verifyForeignKeys(
   contractFKs: readonly ForeignKey[],
@@ -124,15 +182,20 @@ export function verifyForeignKeys(
         children: [],
       });
     } else {
-      // Compare name if both are modeled
-      if (contractFK.name && matchingFK.name && contractFK.name !== matchingFK.name) {
+      const actionMismatches = getReferentialActionMismatches(contractFK, matchingFK);
+      if (actionMismatches.length > 0) {
+        const combinedMessage = actionMismatches.map((m) => m.message).join('; ');
+        const combinedExpected = actionMismatches.map((m) => m.expected).join(', ');
+        const combinedActual = actionMismatches.map((m) => m.actual).join(', ');
         issues.push({
           kind: 'foreign_key_mismatch',
           table: tableName,
-          indexOrConstraint: contractFK.name,
-          expected: contractFK.name,
-          actual: matchingFK.name,
-          message: `Table "${tableName}" has foreign key name mismatch: expected "${contractFK.name}", got "${matchingFK.name}"`,
+          // Set indexOrConstraint so the planner classifies this as a non-additive
+          // conflict (existing FK with wrong actions cannot be fixed additively).
+          indexOrConstraint: matchingFK.name ?? `fk(${contractFK.columns.join(',')})`,
+          expected: combinedExpected,
+          actual: combinedActual,
+          message: `Table "${tableName}" foreign key ${contractFK.columns.join(', ')} -> ${contractFK.references.table}: ${combinedMessage}`,
         });
         nodes.push({
           status: 'fail',
@@ -140,9 +203,9 @@ export function verifyForeignKeys(
           name: `foreignKey(${contractFK.columns.join(', ')})`,
           contractPath: fkPath,
           code: 'foreign_key_mismatch',
-          message: 'Foreign key name mismatch',
-          expected: contractFK.name,
-          actual: matchingFK.name,
+          message: combinedMessage,
+          expected: contractFK,
+          actual: matchingFK,
           children: [],
         });
       } else {
@@ -176,6 +239,7 @@ export function verifyForeignKeys(
         issues.push({
           kind: 'extra_foreign_key',
           table: tableName,
+          indexOrConstraint: schemaFK.name ?? `fk(${schemaFK.columns.join(',')})`,
           message: `Extra foreign key found in database (not in contract): ${schemaFK.columns.join(', ')} -> ${schemaFK.referencedTable}(${schemaFK.referencedColumns.join(', ')})`,
         });
         nodes.push({
@@ -199,10 +263,18 @@ export function verifyForeignKeys(
 /**
  * Verifies unique constraints match between contract and schema.
  * Returns verification nodes for the tree.
+ *
+ * Uses semantic satisfaction: identity is based on (table + kind + columns).
+ * A unique constraint requirement can be satisfied by either:
+ * - A unique constraint with the same columns, or
+ * - A unique index with the same columns
+ *
+ * Name differences are ignored by default (names are for DDL/diagnostics, not identity).
  */
 export function verifyUniqueConstraints(
   contractUniques: readonly UniqueConstraint[],
   schemaUniques: readonly SqlUniqueIR[],
+  schemaIndexes: readonly SqlIndexIR[],
   tableName: string,
   tablePath: string,
   issues: SchemaIssue[],
@@ -213,11 +285,18 @@ export function verifyUniqueConstraints(
   // Check each contract unique exists in schema
   for (const contractUnique of contractUniques) {
     const uniquePath = `${tablePath}.uniques[${contractUnique.columns.join(',')}]`;
+
+    // First check for a matching unique constraint
     const matchingUnique = schemaUniques.find((u) =>
       arraysEqual(u.columns, contractUnique.columns),
     );
 
-    if (!matchingUnique) {
+    // If no matching constraint, check for a unique index with the same columns
+    const matchingUniqueIndex =
+      !matchingUnique &&
+      schemaIndexes.find((idx) => idx.unique && arraysEqual(idx.columns, contractUnique.columns));
+
+    if (!matchingUnique && !matchingUniqueIndex) {
       issues.push({
         kind: 'unique_constraint_mismatch',
         table: tableName,
@@ -236,44 +315,19 @@ export function verifyUniqueConstraints(
         children: [],
       });
     } else {
-      // Compare name if both are modeled
-      if (
-        contractUnique.name &&
-        matchingUnique.name &&
-        contractUnique.name !== matchingUnique.name
-      ) {
-        issues.push({
-          kind: 'unique_constraint_mismatch',
-          table: tableName,
-          indexOrConstraint: contractUnique.name,
-          expected: contractUnique.name,
-          actual: matchingUnique.name,
-          message: `Table "${tableName}" has unique constraint name mismatch: expected "${contractUnique.name}", got "${matchingUnique.name}"`,
-        });
-        nodes.push({
-          status: 'fail',
-          kind: 'unique',
-          name: `unique(${contractUnique.columns.join(', ')})`,
-          contractPath: uniquePath,
-          code: 'unique_constraint_mismatch',
-          message: 'Unique constraint name mismatch',
-          expected: contractUnique.name,
-          actual: matchingUnique.name,
-          children: [],
-        });
-      } else {
-        nodes.push({
-          status: 'pass',
-          kind: 'unique',
-          name: `unique(${contractUnique.columns.join(', ')})`,
-          contractPath: uniquePath,
-          code: '',
-          message: '',
-          expected: undefined,
-          actual: undefined,
-          children: [],
-        });
-      }
+      // Name differences are ignored for semantic satisfaction.
+      // Names are persisted for deterministic DDL and diagnostics but are not identity.
+      nodes.push({
+        status: 'pass',
+        kind: 'unique',
+        name: `unique(${contractUnique.columns.join(', ')})`,
+        contractPath: uniquePath,
+        code: '',
+        message: '',
+        expected: undefined,
+        actual: undefined,
+        children: [],
+      });
     }
   }
 
@@ -288,6 +342,7 @@ export function verifyUniqueConstraints(
         issues.push({
           kind: 'extra_unique_constraint',
           table: tableName,
+          indexOrConstraint: schemaUnique.name ?? `unique(${schemaUnique.columns.join(',')})`,
           message: `Extra unique constraint found in database (not in contract): ${schemaUnique.columns.join(', ')}`,
         });
         nodes.push({
@@ -311,10 +366,18 @@ export function verifyUniqueConstraints(
 /**
  * Verifies indexes match between contract and schema.
  * Returns verification nodes for the tree.
+ *
+ * Uses semantic satisfaction: identity is based on (table + kind + columns).
+ * A non-unique index requirement can be satisfied by either:
+ * - A non-unique index with the same columns, or
+ * - A unique index with the same columns (stronger satisfies weaker)
+ *
+ * Name differences are ignored by default (names are for DDL/diagnostics, not identity).
  */
 export function verifyIndexes(
   contractIndexes: readonly Index[],
   schemaIndexes: readonly SqlIndexIR[],
+  schemaUniques: readonly SqlUniqueIR[],
   tableName: string,
   tablePath: string,
   issues: SchemaIssue[],
@@ -325,11 +388,18 @@ export function verifyIndexes(
   // Check each contract index exists in schema
   for (const contractIndex of contractIndexes) {
     const indexPath = `${tablePath}.indexes[${contractIndex.columns.join(',')}]`;
-    const matchingIndex = schemaIndexes.find(
-      (idx) => arraysEqual(idx.columns, contractIndex.columns) && idx.unique === false,
+
+    // Check for any matching index (unique or non-unique)
+    // A unique index can satisfy a non-unique index requirement (stronger satisfies weaker)
+    const matchingIndex = schemaIndexes.find((idx) =>
+      arraysEqual(idx.columns, contractIndex.columns),
     );
 
-    if (!matchingIndex) {
+    // Also check if a unique constraint satisfies the index requirement
+    const matchingUniqueConstraint =
+      !matchingIndex && schemaUniques.find((u) => arraysEqual(u.columns, contractIndex.columns));
+
+    if (!matchingIndex && !matchingUniqueConstraint) {
       issues.push({
         kind: 'index_mismatch',
         table: tableName,
@@ -348,40 +418,19 @@ export function verifyIndexes(
         children: [],
       });
     } else {
-      // Compare name if both are modeled
-      if (contractIndex.name && matchingIndex.name && contractIndex.name !== matchingIndex.name) {
-        issues.push({
-          kind: 'index_mismatch',
-          table: tableName,
-          indexOrConstraint: contractIndex.name,
-          expected: contractIndex.name,
-          actual: matchingIndex.name,
-          message: `Table "${tableName}" has index name mismatch: expected "${contractIndex.name}", got "${matchingIndex.name}"`,
-        });
-        nodes.push({
-          status: 'fail',
-          kind: 'index',
-          name: `index(${contractIndex.columns.join(', ')})`,
-          contractPath: indexPath,
-          code: 'index_mismatch',
-          message: 'Index name mismatch',
-          expected: contractIndex.name,
-          actual: matchingIndex.name,
-          children: [],
-        });
-      } else {
-        nodes.push({
-          status: 'pass',
-          kind: 'index',
-          name: `index(${contractIndex.columns.join(', ')})`,
-          contractPath: indexPath,
-          code: '',
-          message: '',
-          expected: undefined,
-          actual: undefined,
-          children: [],
-        });
-      }
+      // Name differences are ignored for semantic satisfaction.
+      // Names are persisted for deterministic DDL and diagnostics but are not identity.
+      nodes.push({
+        status: 'pass',
+        kind: 'index',
+        name: `index(${contractIndex.columns.join(', ')})`,
+        contractPath: indexPath,
+        code: '',
+        message: '',
+        expected: undefined,
+        actual: undefined,
+        children: [],
+      });
     }
   }
 
@@ -401,6 +450,7 @@ export function verifyIndexes(
         issues.push({
           kind: 'extra_index',
           table: tableName,
+          indexOrConstraint: schemaIndex.name ?? `idx(${schemaIndex.columns.join(',')})`,
           message: `Extra index found in database (not in contract): ${schemaIndex.columns.join(', ')}`,
         });
         nodes.push({
@@ -423,8 +473,8 @@ export function verifyIndexes(
 
 /**
  * Verifies database dependencies are installed using component-owned verification hooks.
- * Each dependency provides a pure verifyDatabaseDependencyInstalled function that checks
- * whether the dependency is satisfied based on the in-memory schema IR (no DB I/O).
+ * Checks whether each dependency is satisfied by verifying its id is present in
+ * schema.dependencies (populated from introspection).
  *
  * Returns verification nodes for the tree.
  */
@@ -434,16 +484,20 @@ export function verifyDatabaseDependencies(
   issues: SchemaIssue[],
 ): SchemaVerificationNode[] {
   const nodes: SchemaVerificationNode[] = [];
+  const installedIds = new Set(schema.dependencies.map((d) => d.id));
 
   for (const dependency of dependencies) {
-    const depIssues = dependency.verifyDatabaseDependencyInstalled(schema);
+    const isSatisfied = installedIds.has(dependency.id);
     const depPath = `dependencies.${dependency.id}`;
 
-    if (depIssues.length > 0) {
-      // Dependency is not satisfied
-      issues.push(...depIssues);
-      const issuesMessage = depIssues.map((i) => i.message).join('; ');
-      const nodeMessage = issuesMessage ? `${dependency.id}: ${issuesMessage}` : dependency.id;
+    if (!isSatisfied) {
+      const depIssue: SchemaIssue = {
+        kind: 'dependency_missing',
+        dependencyId: dependency.id,
+        message: `Dependency "${dependency.id}" is missing from database`,
+      };
+      issues.push(depIssue);
+      const nodeMessage = depIssue.message;
       nodes.push({
         status: 'fail',
         kind: 'databaseDependency',
@@ -512,3 +566,49 @@ export function computeCounts(node: SchemaVerificationNode): {
     totalNodes: pass + warn + fail,
   };
 }
+
+/**
+ * Compares referential actions between a contract FK and a schema FK.
+ * Only compares when the contract FK explicitly specifies onDelete or onUpdate.
+ * Returns all mismatches (both onDelete and onUpdate) so both are reported at once.
+ *
+ * Note: 'noAction' in the contract is semantically equivalent to undefined in the
+ * schema IR, because the introspection adapter omits 'NO ACTION' (the database default)
+ * to keep the IR sparse. We normalize both sides before comparing.
+ */
+function getReferentialActionMismatches(
+  contractFK: ForeignKey,
+  schemaFK: SqlForeignKeyIR,
+): ReadonlyArray<{ expected: string; actual: string; message: string }> {
+  const mismatches: Array<{ expected: string; actual: string; message: string }> = [];
+
+  const contractOnDelete = normalizeReferentialAction(contractFK.onDelete);
+  const schemaOnDelete = normalizeReferentialAction(schemaFK.onDelete);
+  if (contractOnDelete !== undefined && contractOnDelete !== schemaOnDelete) {
+    mismatches.push({
+      expected: `onDelete: ${contractFK.onDelete}`,
+      actual: `onDelete: ${schemaFK.onDelete ?? 'noAction (default)'}`,
+      message: `onDelete mismatch: expected ${contractFK.onDelete}, got ${schemaFK.onDelete ?? 'noAction (default)'}`,
+    });
+  }
+
+  const contractOnUpdate = normalizeReferentialAction(contractFK.onUpdate);
+  const schemaOnUpdate = normalizeReferentialAction(schemaFK.onUpdate);
+  if (contractOnUpdate !== undefined && contractOnUpdate !== schemaOnUpdate) {
+    mismatches.push({
+      expected: `onUpdate: ${contractFK.onUpdate}`,
+      actual: `onUpdate: ${schemaFK.onUpdate ?? 'noAction (default)'}`,
+      message: `onUpdate mismatch: expected ${contractFK.onUpdate}, got ${schemaFK.onUpdate ?? 'noAction (default)'}`,
+    });
+  }
+
+  return mismatches;
+}
+
+/**
+ * Normalizes a referential action value for comparison.
+ * 'noAction' is the database default and equivalent to undefined (omitted) in the sparse IR.
+ */
+function normalizeReferentialAction(action: string | undefined): string | undefined {
+  return action === 'noAction' ? undefined : action;
+}