@prisma-next/family-sql 0.12.0-dev.2 → 0.12.0-dev.21

package/src/core/migrations/control-policy.ts

@@ -0,0 +1,89 @@
+import {
+  type Contract,
+  type ControlPolicy,
+  effectiveControlPolicy,
+} from '@prisma-next/contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+
+/**
+ * The target object a control policy governs for a single planner call,
+ * resolved from the target's own IR. `undefined` means the call's target
+ * object could not be positively established — a fail-closed signal: any
+ * policy stricter than `managed` drops such a call rather than emitting it.
+ */
+export interface ControlPolicySubject {
+  readonly namespaceId: string;
+  readonly explicitNodeControlPolicy?: ControlPolicy;
+  readonly table?: string;
+  readonly column?: string;
+  readonly typeName?: string;
+  /**
+   * Whether the call creates a whole, previously-absent top-level storage
+   * object (e.g. a table or an enum/type), as opposed to modifying an
+   * existing object. This is the only thing `tolerated` permits: it is a
+   * create-if-absent policy, so an op that touches an existing object — add
+   * column, add index/constraint, alter, drop — is never allowed under it.
+   */
+  readonly createsNewObject: boolean;
+}
+
+/**
+ * The control policy that governs a single call. The `external` default is an
+ * un-overridable namespace floor: when the contract default is `external`, no
+ * per-object `managed` override can escalate DDL above the floor, so the
+ * policy is forced to `external` regardless of the node's own declaration.
+ * Every other default defers to the node's effective control policy.
+ */
+function controlPolicyForCall(
+  subject: ControlPolicySubject | undefined,
+  defaultControlPolicy: ControlPolicy | undefined,
+): ControlPolicy {
+  if (defaultControlPolicy === 'external') {
+    return 'external';
+  }
+  return effectiveControlPolicy(subject?.explicitNodeControlPolicy, defaultControlPolicy);
+}
+
+/**
+ * Whether a call is allowed to emit under a given control policy.
+ *
+ * - `managed` — full lifecycle, every op allowed.
+ * - `tolerated` — create-if-absent only: allowed iff the call creates a whole
+ *   new top-level object (and its subject was positively resolved). Anything
+ *   that modifies an existing object, and anything whose subject could not be
+ *   resolved, is suppressed.
+ * - `external` / `observed` — no DDL at all.
+ */
+function callAllowedUnderControlPolicy(
+  policy: ControlPolicy,
+  subject: ControlPolicySubject | undefined,
+): boolean {
+  switch (policy) {
+    case 'managed':
+      return true;
+    case 'tolerated':
+      return subject?.createsNewObject === true;
+    case 'external':
+    case 'observed':
+      return false;
+  }
+}
+
+export function filterCallsByControlPolicy<TCall>(options: {
+  readonly calls: readonly TCall[];
+  readonly contract: Contract<SqlStorage>;
+  readonly resolveControlPolicySubject: (call: TCall) => ControlPolicySubject | undefined;
+}): readonly TCall[] {
+  const defaultControlPolicy = options.contract.defaultControlPolicy;
+  const kept: TCall[] = [];
+
+  for (const call of options.calls) {
+    const subject = options.resolveControlPolicySubject(call);
+    const policy = controlPolicyForCall(subject, defaultControlPolicy);
+    if (callAllowedUnderControlPolicy(policy, subject)) {
+      kept.push(call);
+    }
+  }
+
+  return Object.freeze(kept);
+}

package/src/core/migrations/types.ts

@@ -22,6 +22,7 @@ import type {
   SchemaIssue,
   SchemaVerifier,
 } from '@prisma-next/framework-components/control';
+import type { AggregateMigrationEdgeRef } from '@prisma-next/migration-tools/aggregate';
 import type {
   SqlStorage,
   StorageColumn,
@@ -31,6 +32,7 @@ import type {
 import type { SqlOperationDescriptors } 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 { SqlControlAdapter } from '../control-adapter';
 import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
@@ -174,7 +176,7 @@ export interface SqlControlExtensionDescriptor<TTargetId extends string>
 }
 
 export interface SqlControlAdapterDescriptor<TTargetId extends string>
-  extends ControlAdapterDescriptor<'sql', TTargetId> {
+  extends ControlAdapterDescriptor<'sql', TTargetId, SqlControlAdapter<TTargetId>> {
   readonly queryOperations?: () => SqlOperationDescriptors;
 }
 
@@ -384,6 +386,11 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
    * All components must have matching familyId ('sql') and targetId.
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  /**
+   * Per-edge breakdown from graph-walk planning. When present, the runner
+   * writes one ledger row per edge instead of one collapsed row per apply.
+   */
+  readonly migrationEdges: readonly AggregateMigrationEdgeRef[];
 }
 
 export type SqlMigrationRunnerErrorCode =

package/src/core/schema-verify/control-verify-emit.ts

@@ -0,0 +1,46 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import type {
+  SchemaIssue,
+  SchemaVerificationNode,
+  VerifierOutcome,
+} from '@prisma-next/framework-components/control';
+import { verifierDisposition } from './verifier-disposition';
+
+/**
+ * Grades `issue` under `controlPolicy` and, unless suppressed, pushes both the
+ * issue and a status-stamped verification node. Returns the resolved outcome so
+ * the caller never re-grades the same issue.
+ */
+export function emitIssueAndNodeUnderControlPolicy(
+  controlPolicy: ControlPolicy,
+  issue: SchemaIssue,
+  node: SchemaVerificationNode,
+  issues: SchemaIssue[],
+  nodes: SchemaVerificationNode[],
+): VerifierOutcome {
+  const disposition = verifierDisposition(controlPolicy, issue.kind);
+  if (disposition === 'suppress') {
+    return disposition;
+  }
+  issues.push(issue);
+  nodes.push({ ...node, status: disposition });
+  return disposition;
+}
+
+/**
+ * Grades `issue` under `controlPolicy` and, unless suppressed, pushes the issue
+ * (no verification node). Returns the resolved outcome so the caller maps it to
+ * a node status itself without re-grading.
+ */
+export function emitIssueUnderControlPolicy(
+  controlPolicy: ControlPolicy,
+  issue: SchemaIssue,
+  issues: SchemaIssue[],
+): VerifierOutcome {
+  const disposition = verifierDisposition(controlPolicy, issue.kind);
+  if (disposition === 'suppress') {
+    return disposition;
+  }
+  issues.push(issue);
+  return disposition;
+}

package/src/core/schema-verify/verifier-disposition.ts

@@ -0,0 +1,53 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import type {
+  SchemaIssue,
+  VerifierIssueCategory,
+  VerifierOutcome,
+} from '@prisma-next/framework-components/control';
+import { dispositionForCategory } from '@prisma-next/framework-components/control';
+
+/**
+ * Classifies the relational verifier issue kinds the SQL family emits (tables,
+ * columns, constraints, indexes, defaults, enum types) into the target-neutral
+ * categories the framework grades. The relational vocabulary lives here, in the
+ * SQL domain — the framework never switches over `extra_foreign_key` and friends.
+ */
+export function classifySqlVerifierIssueKind(kind: SchemaIssue['kind']): VerifierIssueCategory {
+  switch (kind) {
+    case 'extra_column':
+      return 'extraNestedElement';
+    case 'extra_primary_key':
+    case 'extra_foreign_key':
+    case 'extra_unique_constraint':
+    case 'extra_index':
+    case 'extra_validator':
+    case 'extra_default':
+      return 'extraAuxiliary';
+    case 'extra_table':
+      return 'extraTopLevelObject';
+    case 'missing_schema':
+    case 'missing_table':
+    case 'missing_column':
+    case 'type_missing':
+    case 'default_missing':
+      return 'declaredMissing';
+    case 'type_values_mismatch':
+    case 'enum_values_changed':
+      return 'valueDrift';
+    case 'type_mismatch':
+    case 'nullability_mismatch':
+    case 'primary_key_mismatch':
+    case 'foreign_key_mismatch':
+    case 'unique_constraint_mismatch':
+    case 'index_mismatch':
+    case 'default_mismatch':
+      return 'declaredIncompatible';
+  }
+}
+
+export function verifierDisposition(
+  controlPolicy: ControlPolicy,
+  issueKind: SchemaIssue['kind'],
+): VerifierOutcome {
+  return dispositionForCategory(controlPolicy, classifySqlVerifierIssueKind(issueKind));
+}

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

@@ -3,6 +3,7 @@
  * These functions verify schema IR against contract requirements.
  */
 
+import type { ControlPolicy } from '@prisma-next/contract/types';
 import type {
   SchemaIssue,
   SchemaVerificationNode,
@@ -15,6 +16,10 @@ import type {
   UniqueConstraint,
 } from '@prisma-next/sql-contract/types';
 import type { SqlForeignKeyIR, SqlIndexIR, SqlUniqueIR } from '@prisma-next/sql-schema-ir/types';
+import {
+  emitIssueAndNodeUnderControlPolicy,
+  emitIssueUnderControlPolicy,
+} from './control-verify-emit';
 
 function indexOptionsLooselyEqual(
   a: Record<string, unknown> | undefined,
@@ -135,34 +140,34 @@ export function verifyPrimaryKey(
   schemaPK: PrimaryKey | undefined,
   tableName: string,
   namespaceId: string,
+  tableControlPolicy: ControlPolicy,
   issues: SchemaIssue[],
-): 'pass' | 'fail' {
+): 'pass' | 'warn' | 'fail' {
   if (!schemaPK) {
-    issues.push({
+    const issue: SchemaIssue = {
       kind: 'primary_key_mismatch',
       table: tableName,
       namespaceId,
       expected: contractPK.columns.join(', '),
       message: `Table "${tableName}" is missing primary key`,
-    });
-    return 'fail';
+    };
+    const outcome = emitIssueUnderControlPolicy(tableControlPolicy, issue, issues);
+    return outcome === 'suppress' ? 'pass' : outcome;
   }
 
   if (!arraysEqual(contractPK.columns, schemaPK.columns)) {
-    issues.push({
+    const issue: SchemaIssue = {
       kind: 'primary_key_mismatch',
       table: tableName,
       namespaceId,
       expected: contractPK.columns.join(', '),
       actual: schemaPK.columns.join(', '),
       message: `Table "${tableName}" has primary key mismatch: expected columns [${contractPK.columns.join(', ')}], got [${schemaPK.columns.join(', ')}]`,
-    });
-    return 'fail';
+    };
+    const outcome = emitIssueUnderControlPolicy(tableControlPolicy, issue, issues);
+    return outcome === 'suppress' ? 'pass' : outcome;
   }
 
-  // Name differences are ignored for semantic satisfaction.
-  // Names are persisted for deterministic DDL and diagnostics but are not identity.
-
   return 'pass';
 }
 
@@ -179,6 +184,7 @@ export function verifyForeignKeys(
   tableName: string,
   namespaceId: string,
   tablePath: string,
+  tableControlPolicy: ControlPolicy,
   issues: SchemaIssue[],
   strict: boolean,
 ): SchemaVerificationNode[] {
@@ -207,52 +213,62 @@ export function verifyForeignKeys(
     });
 
     if (!matchingFK) {
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'foreign_key_mismatch',
         table: tableName,
         namespaceId,
         expected: `${contractFK.source.columns.join(', ')} -> ${contractFK.target.tableName}(${contractFK.target.columns.join(', ')})`,
         message: `Table "${tableName}" is missing foreign key: ${contractFK.source.columns.join(', ')} -> ${contractFK.target.tableName}(${contractFK.target.columns.join(', ')})`,
-      });
-      nodes.push({
-        status: 'fail',
-        kind: 'foreignKey',
-        name: `foreignKey(${contractFK.source.columns.join(', ')})`,
-        contractPath: fkPath,
-        code: 'foreign_key_mismatch',
-        message: 'Foreign key missing',
-        expected: contractFK,
-        actual: undefined,
-        children: [],
-      });
+      };
+      emitIssueAndNodeUnderControlPolicy(
+        tableControlPolicy,
+        issue,
+        {
+          status: 'fail',
+          kind: 'foreignKey',
+          name: `foreignKey(${contractFK.source.columns.join(', ')})`,
+          contractPath: fkPath,
+          code: 'foreign_key_mismatch',
+          message: 'Foreign key missing',
+          expected: contractFK,
+          actual: undefined,
+          children: [],
+        },
+        issues,
+        nodes,
+      );
     } else {
       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({
+        const issue: SchemaIssue = {
           kind: 'foreign_key_mismatch',
           table: tableName,
           namespaceId,
-          // 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.source.columns.join(',')})`,
           expected: combinedExpected,
           actual: combinedActual,
           message: `Table "${tableName}" foreign key ${contractFK.source.columns.join(', ')} -> ${contractFK.target.tableName}: ${combinedMessage}`,
-        });
-        nodes.push({
-          status: 'fail',
-          kind: 'foreignKey',
-          name: `foreignKey(${contractFK.source.columns.join(', ')})`,
-          contractPath: fkPath,
-          code: 'foreign_key_mismatch',
-          message: combinedMessage,
-          expected: contractFK,
-          actual: matchingFK,
-          children: [],
-        });
+        };
+        emitIssueAndNodeUnderControlPolicy(
+          tableControlPolicy,
+          issue,
+          {
+            status: 'fail',
+            kind: 'foreignKey',
+            name: `foreignKey(${contractFK.source.columns.join(', ')})`,
+            contractPath: fkPath,
+            code: 'foreign_key_mismatch',
+            message: combinedMessage,
+            expected: contractFK,
+            actual: matchingFK,
+            children: [],
+          },
+          issues,
+          nodes,
+        );
       } else {
         nodes.push({
           status: 'pass',
@@ -286,24 +302,30 @@ export function verifyForeignKeys(
       });
 
       if (!matchingFK) {
-        issues.push({
+        const issue: SchemaIssue = {
           kind: 'extra_foreign_key',
           table: tableName,
           namespaceId,
           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({
-          status: 'fail',
-          kind: 'foreignKey',
-          name: `foreignKey(${schemaFK.columns.join(', ')})`,
-          contractPath: `${tablePath}.foreignKeys[${schemaFK.columns.join(',')}]`,
-          code: 'extra_foreign_key',
-          message: 'Extra foreign key found',
-          expected: undefined,
-          actual: schemaFK,
-          children: [],
-        });
+        };
+        emitIssueAndNodeUnderControlPolicy(
+          tableControlPolicy,
+          issue,
+          {
+            status: 'fail',
+            kind: 'foreignKey',
+            name: `foreignKey(${schemaFK.columns.join(', ')})`,
+            contractPath: `${tablePath}.foreignKeys[${schemaFK.columns.join(',')}]`,
+            code: 'extra_foreign_key',
+            message: 'Extra foreign key found',
+            expected: undefined,
+            actual: schemaFK,
+            children: [],
+          },
+          issues,
+          nodes,
+        );
       }
     }
   }
@@ -329,6 +351,7 @@ export function verifyUniqueConstraints(
   tableName: string,
   namespaceId: string,
   tablePath: string,
+  tableControlPolicy: ControlPolicy,
   issues: SchemaIssue[],
   strict: boolean,
 ): SchemaVerificationNode[] {
@@ -349,27 +372,31 @@ export function verifyUniqueConstraints(
       schemaIndexes.find((idx) => idx.unique && arraysEqual(idx.columns, contractUnique.columns));
 
     if (!matchingUnique && !matchingUniqueIndex) {
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'unique_constraint_mismatch',
         table: tableName,
         namespaceId,
         expected: contractUnique.columns.join(', '),
         message: `Table "${tableName}" is missing unique constraint: ${contractUnique.columns.join(', ')}`,
-      });
-      nodes.push({
-        status: 'fail',
-        kind: 'unique',
-        name: `unique(${contractUnique.columns.join(', ')})`,
-        contractPath: uniquePath,
-        code: 'unique_constraint_mismatch',
-        message: 'Unique constraint missing',
-        expected: contractUnique,
-        actual: undefined,
-        children: [],
-      });
+      };
+      emitIssueAndNodeUnderControlPolicy(
+        tableControlPolicy,
+        issue,
+        {
+          status: 'fail',
+          kind: 'unique',
+          name: `unique(${contractUnique.columns.join(', ')})`,
+          contractPath: uniquePath,
+          code: 'unique_constraint_mismatch',
+          message: 'Unique constraint missing',
+          expected: contractUnique,
+          actual: undefined,
+          children: [],
+        },
+        issues,
+        nodes,
+      );
     } else {
-      // 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',
@@ -384,7 +411,6 @@ export function verifyUniqueConstraints(
     }
   }
 
-  // Check for extra uniques in strict mode
   if (strict) {
     for (const schemaUnique of schemaUniques) {
       const matchingUnique = contractUniques.find((u) =>
@@ -392,24 +418,30 @@ export function verifyUniqueConstraints(
       );
 
       if (!matchingUnique) {
-        issues.push({
+        const issue: SchemaIssue = {
           kind: 'extra_unique_constraint',
           table: tableName,
           namespaceId,
           indexOrConstraint: schemaUnique.name ?? `unique(${schemaUnique.columns.join(',')})`,
           message: `Extra unique constraint found in database (not in contract): ${schemaUnique.columns.join(', ')}`,
-        });
-        nodes.push({
-          status: 'fail',
-          kind: 'unique',
-          name: `unique(${schemaUnique.columns.join(', ')})`,
-          contractPath: `${tablePath}.uniques[${schemaUnique.columns.join(',')}]`,
-          code: 'extra_unique_constraint',
-          message: 'Extra unique constraint found',
-          expected: undefined,
-          actual: schemaUnique,
-          children: [],
-        });
+        };
+        emitIssueAndNodeUnderControlPolicy(
+          tableControlPolicy,
+          issue,
+          {
+            status: 'fail',
+            kind: 'unique',
+            name: `unique(${schemaUnique.columns.join(', ')})`,
+            contractPath: `${tablePath}.uniques[${schemaUnique.columns.join(',')}]`,
+            code: 'extra_unique_constraint',
+            message: 'Extra unique constraint found',
+            expected: undefined,
+            actual: schemaUnique,
+            children: [],
+          },
+          issues,
+          nodes,
+        );
       }
     }
   }
@@ -435,6 +467,7 @@ export function verifyIndexes(
   tableName: string,
   namespaceId: string,
   tablePath: string,
+  tableControlPolicy: ControlPolicy,
   issues: SchemaIssue[],
   strict: boolean,
 ): SchemaVerificationNode[] {
@@ -461,27 +494,31 @@ export function verifyIndexes(
       schemaUniques.find((u) => arraysEqual(u.columns, contractIndex.columns));
 
     if (!matchingIndex && !matchingUniqueConstraint) {
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'index_mismatch',
         table: tableName,
         namespaceId,
         expected: contractIndex.columns.join(', '),
         message: `Table "${tableName}" is missing index: ${contractIndex.columns.join(', ')}`,
-      });
-      nodes.push({
-        status: 'fail',
-        kind: 'index',
-        name: `index(${contractIndex.columns.join(', ')})`,
-        contractPath: indexPath,
-        code: 'index_mismatch',
-        message: 'Index missing',
-        expected: contractIndex,
-        actual: undefined,
-        children: [],
-      });
+      };
+      emitIssueAndNodeUnderControlPolicy(
+        tableControlPolicy,
+        issue,
+        {
+          status: 'fail',
+          kind: 'index',
+          name: `index(${contractIndex.columns.join(', ')})`,
+          contractPath: indexPath,
+          code: 'index_mismatch',
+          message: 'Index missing',
+          expected: contractIndex,
+          actual: undefined,
+          children: [],
+        },
+        issues,
+        nodes,
+      );
     } else {
-      // 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',
@@ -496,10 +533,8 @@ export function verifyIndexes(
     }
   }
 
-  // Check for extra indexes in strict mode
   if (strict) {
     for (const schemaIndex of schemaIndexes) {
-      // Skip unique indexes (they're handled as unique constraints)
       if (schemaIndex.unique) {
         continue;
       }
@@ -510,24 +545,30 @@ export function verifyIndexes(
       );
 
       if (!matchingIndex) {
-        issues.push({
+        const issue: SchemaIssue = {
           kind: 'extra_index',
           table: tableName,
           namespaceId,
           indexOrConstraint: schemaIndex.name ?? `idx(${schemaIndex.columns.join(',')})`,
           message: `Extra index found in database (not in contract): ${schemaIndex.columns.join(', ')}`,
-        });
-        nodes.push({
-          status: 'fail',
-          kind: 'index',
-          name: `index(${schemaIndex.columns.join(', ')})`,
-          contractPath: `${tablePath}.indexes[${schemaIndex.columns.join(',')}]`,
-          code: 'extra_index',
-          message: 'Extra index found',
-          expected: undefined,
-          actual: schemaIndex,
-          children: [],
-        });
+        };
+        emitIssueAndNodeUnderControlPolicy(
+          tableControlPolicy,
+          issue,
+          {
+            status: 'fail',
+            kind: 'index',
+            name: `index(${schemaIndex.columns.join(', ')})`,
+            contractPath: `${tablePath}.indexes[${schemaIndex.columns.join(',')}]`,
+            code: 'extra_index',
+            message: 'Extra index found',
+            expected: undefined,
+            actual: schemaIndex,
+            children: [],
+          },
+          issues,
+          nodes,
+        );
       }
     }
   }