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

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

@@ -6,15 +6,17 @@
  * by migration planners and other tools that need to compare schema states.
  */
 
-import type { ColumnDefault, Contract } from '@prisma-next/contract/types';
+import type { ColumnDefault, Contract, ControlPolicy } from '@prisma-next/contract/types';
+import { effectiveControlPolicy } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
   OperationContext,
   SchemaIssue,
   SchemaVerificationNode,
+  VerificationStatus,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
-import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+
 import {
   isPostgresEnumStorageEntry,
   isStorageTypeInstance,
@@ -26,9 +28,12 @@ import {
 } from '@prisma-next/sql-contract/types';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import { canonicalStringify } from '@prisma-next/utils/canonical-stringify';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { extractCodecControlHooks } from '../assembly';
 import type { CodecControlHooks } from '../migrations/types';
+import { emitIssueAndNodeUnderControlPolicy } from './control-verify-emit';
+import { verifierDisposition } from './verifier-disposition';
 import {
   arraysEqual,
   computeCounts,
@@ -38,6 +43,8 @@ import {
   verifyUniqueConstraints,
 } from './verify-helpers';
 
+export type ColumnsCompatible = (declared: string, live: string) => boolean;
+
 /**
  * Function type for normalizing raw database default expressions into ColumnDefault.
  * Target-specific implementations handle database dialect differences.
@@ -101,6 +108,11 @@ export interface VerifySqlSchemaOptions {
     enumType: PostgresEnumStorageEntry,
     namespaceId: string,
   ) => readonly string[] | null;
+  /**
+   * Target-supplied compatible-shape relation for `external` column type checks.
+   * Defaults to exact string equality when omitted.
+   */
+  readonly columnsCompatible?: ColumnsCompatible;
 }
 
 /**
@@ -123,6 +135,7 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     normalizeDefault,
     normalizeNativeType,
     resolveExistingEnumValues,
+    columnsCompatible,
   } = options;
   const startTime = Date.now();
 
@@ -140,7 +153,10 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     >),
   };
   for (const ns of Object.values(contract.storage.namespaces)) {
-    const nsEnums = (ns as { enum?: Record<string, PostgresEnumStorageEntry> }).enum;
+    const nsEnums = blindCast<
+      { readonly type?: Readonly<Record<string, PostgresEnumStorageEntry | StorageTypeInstance>> },
+      'postgres target namespace entries carry a type slot beyond the family-shared SqlNamespace.entries type'
+    >(ns.entries).type;
     if (nsEnums) {
       for (const [k, v] of Object.entries(nsEnums)) {
         allStorageTypesMap[k] = v;
@@ -159,6 +175,7 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     storageTypes,
     ...ifDefined('normalizeDefault', normalizeDefault),
     ...ifDefined('normalizeNativeType', normalizeNativeType),
+    ...ifDefined('columnsCompatible', columnsCompatible),
   });
 
   validateFrameworkComponentsForExtensions(contract, options.frameworkComponents);
@@ -171,51 +188,54 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
   // namespace coordinate — a bare-name aggregation would collapse them
   // (last-write-wins) and verify only one.
   const typeNodes: SchemaVerificationNode[] = [];
+  // Storage-type findings dispatch through the same control policy as tables
+  // and columns: each issue's disposition (fail / warn / suppress) is resolved
+  // from the type's effective control so an `external`/`observed` enum no longer
+  // hard-fails on value drift. `suppress` drops the issue entirely; the node
+  // status is the worst surviving disposition.
   const pushTypeNode = (
     typeName: string,
     contractPath: string,
     typeIssues: readonly SchemaIssue[],
+    controlPolicy: ControlPolicy,
   ): void => {
-    if (typeIssues.length > 0) {
-      issues.push(...typeIssues);
+    let status: VerificationStatus = 'pass';
+    let code = '';
+    let emitted = 0;
+    for (const issue of typeIssues) {
+      const disposition = verifierDisposition(controlPolicy, issue.kind);
+      if (disposition === 'suppress') continue;
+      issues.push(issue);
+      emitted += 1;
+      if (code === '') code = issue.kind;
+      if (disposition === 'fail') {
+        status = 'fail';
+      } else if (disposition === 'warn' && status !== 'fail') {
+        status = 'warn';
+      }
     }
     typeNodes.push({
-      status: typeIssues.length > 0 ? 'fail' : 'pass',
+      status,
       kind: 'storageType',
       name: `type ${typeName}`,
       contractPath,
-      code: typeIssues.length > 0 ? (typeIssues[0]?.kind ?? '') : '',
-      message:
-        typeIssues.length > 0
-          ? `${typeIssues.length} issue${typeIssues.length === 1 ? '' : 's'}`
-          : '',
+      code: status === 'pass' ? '' : code,
+      message: emitted > 0 ? `${emitted} issue${emitted === 1 ? '' : 's'}` : '',
       expected: undefined,
       actual: undefined,
       children: [],
     });
   };
 
-  // Top-level `storage.types`: codec-typed entries via codec hooks; a
-  // defensive top-level enum is verified under the unbound coordinate.
+  // Top-level `storage.types`: codec-typed entries via codec hooks.
   for (const [typeName, typeInstance] of Object.entries(contract.storage.types ?? {})) {
-    if (isPostgresEnumStorageEntry(typeInstance)) {
-      pushTypeNode(
-        typeName,
-        `storage.types.${typeName}`,
-        verifyEnumType({
-          typeName,
-          typeInstance,
-          schema,
-          resolveExistingEnumValues,
-          namespaceId: UNBOUND_NAMESPACE_ID,
-        }),
-      );
-    } else if (isStorageTypeInstance(typeInstance)) {
+    if (isStorageTypeInstance(typeInstance)) {
       const hook = codecHooks.get(typeInstance.codecId);
       pushTypeNode(
         typeName,
         `storage.types.${typeName}`,
         hook?.verifyType ? hook.verifyType({ typeName, typeInstance, schema }) : [],
+        effectiveControlPolicy(undefined, contract.defaultControlPolicy),
       );
     }
   }
@@ -224,13 +244,13 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
   for (const nsId of Object.keys(contract.storage.namespaces)) {
     const ns = contract.storage.namespaces[nsId];
     if (!ns) continue;
-    const nsEnums = ns.enum;
+    const nsEnums = ns.entries['type'];
     if (!nsEnums) continue;
     for (const [typeName, entry] of Object.entries(nsEnums)) {
       if (!isPostgresEnumStorageEntry(entry)) continue;
       pushTypeNode(
         typeName,
-        `storage.namespaces.${nsId}.enum.${typeName}`,
+        `storage.namespaces.${nsId}.entries.type.${typeName}`,
         verifyEnumType({
           typeName,
           typeInstance: entry,
@@ -238,12 +258,17 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
           resolveExistingEnumValues,
           namespaceId: nsId,
         }),
+        effectiveControlPolicy(entry.control, contract.defaultControlPolicy),
       );
     }
   }
 
   if (typeNodes.length > 0) {
-    const typesStatus = typeNodes.some((n) => n.status === 'fail') ? 'fail' : 'pass';
+    const typesStatus: VerificationStatus = typeNodes.some((n) => n.status === 'fail')
+      ? 'fail'
+      : typeNodes.some((n) => n.status === 'warn')
+        ? 'warn'
+        : 'pass';
     rootChildren.push({
       status: typesStatus,
       kind: 'storageTypes',
@@ -303,8 +328,6 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
   };
 }
 
-type VerificationStatus = 'pass' | 'warn' | 'fail';
-
 /**
  * Native verification walk for `PostgresEnumStorageEntry` instances (no codec hook).
  *
@@ -386,6 +409,7 @@ function verifySchemaTables(options: {
   storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
+  columnsCompatible?: ColumnsCompatible;
 }): { issues: SchemaIssue[]; rootChildren: SchemaVerificationNode[] } {
   const {
     contract,
@@ -396,7 +420,9 @@ function verifySchemaTables(options: {
     storageTypes,
     normalizeDefault,
     normalizeNativeType,
+    columnsCompatible,
   } = options;
+  const contractDefaultControl = contract.defaultControlPolicy;
   const issues: SchemaIssue[] = [];
   const rootChildren: SchemaVerificationNode[] = [];
   const schemaTables = schema.tables;
@@ -407,34 +433,44 @@ function verifySchemaTables(options: {
   for (const namespaceId of namespaceIds) {
     const ns = contract.storage.namespaces[namespaceId];
     if (!ns) continue;
-    for (const [tableName, contractTableRaw] of Object.entries(ns.tables)) {
+    for (const [tableName, contractTableRaw] of Object.entries(ns.entries.table)) {
       if (!(contractTableRaw instanceof StorageTable)) {
         throw new Error(
-          `verifySqlSchema: expected StorageTable at storage.namespaces.${namespaceId}.tables.${tableName}`,
+          `verifySqlSchema: expected StorageTable at storage.namespaces.${namespaceId}.entries.table.${tableName}`,
         );
       }
       const contractTable = contractTableRaw;
+      const tableControlPolicy = effectiveControlPolicy(
+        contractTable.control,
+        contractDefaultControl,
+      );
       const schemaTable = schemaTables[tableName];
-      const tablePath = `storage.namespaces.${namespaceId}.tables.${tableName}`;
+      const tablePath = `storage.namespaces.${namespaceId}.entries.table.${tableName}`;
 
       if (!schemaTable) {
-        issues.push({
+        const issue: SchemaIssue = {
           kind: 'missing_table',
           table: tableName,
           namespaceId,
           message: `Table "${tableName}" is missing from database`,
-        });
-        rootChildren.push({
-          status: 'fail',
-          kind: 'table',
-          name: `table ${tableName}`,
-          contractPath: tablePath,
-          code: 'missing_table',
-          message: `Table "${tableName}" is missing`,
-          expected: undefined,
-          actual: undefined,
-          children: [],
-        });
+        };
+        emitIssueAndNodeUnderControlPolicy(
+          tableControlPolicy,
+          issue,
+          {
+            status: 'fail',
+            kind: 'table',
+            name: `table ${tableName}`,
+            contractPath: tablePath,
+            code: 'missing_table',
+            message: `Table "${tableName}" is missing`,
+            expected: undefined,
+            actual: undefined,
+            children: [],
+          },
+          issues,
+          rootChildren,
+        );
         continue;
       }
 
@@ -444,6 +480,7 @@ function verifySchemaTables(options: {
         tableName,
         namespaceId,
         tablePath,
+        tableControlPolicy,
         issues,
         strict,
         typeMetadataRegistry,
@@ -451,6 +488,7 @@ function verifySchemaTables(options: {
         storageTypes,
         ...ifDefined('normalizeDefault', normalizeDefault),
         ...ifDefined('normalizeNativeType', normalizeNativeType),
+        ...ifDefined('columnsCompatible', columnsCompatible),
       });
       rootChildren.push(buildTableNode(tableName, tablePath, tableChildren));
     }
@@ -459,29 +497,33 @@ function verifySchemaTables(options: {
   if (strict) {
     for (const tableName of Object.keys(schemaTables)) {
       const claimed = namespaceIds.some(
-        (namespaceId) => contract.storage.namespaces[namespaceId]?.tables[tableName] !== undefined,
+        (namespaceId) =>
+          contract.storage.namespaces[namespaceId]?.entries.table[tableName] !== undefined,
       );
       if (!claimed) {
-        // `namespaceId` is intentionally absent: an extra table exists in the
-        // live database but is not claimed by any contract namespace, so there
-        // is no contract coordinate to stamp here. Planners that consume this
-        // issue must handle the unstamped case (drop / quarantine by name).
-        issues.push({
+        const extraTableControlPolicy = effectiveControlPolicy(undefined, contractDefaultControl);
+        const issue: SchemaIssue = {
           kind: 'extra_table',
           table: tableName,
           message: `Extra table "${tableName}" found in database (not in contract)`,
-        });
-        rootChildren.push({
-          status: 'fail',
-          kind: 'table',
-          name: `table ${tableName}`,
-          contractPath: `storage.namespaces.*.tables.${tableName}`,
-          code: 'extra_table',
-          message: `Extra table "${tableName}" found`,
-          expected: undefined,
-          actual: undefined,
-          children: [],
-        });
+        };
+        emitIssueAndNodeUnderControlPolicy(
+          extraTableControlPolicy,
+          issue,
+          {
+            status: 'fail',
+            kind: 'table',
+            name: `table ${tableName}`,
+            contractPath: `storage.namespaces.*.entries.table.${tableName}`,
+            code: 'extra_table',
+            message: `Extra table "${tableName}" found`,
+            expected: undefined,
+            actual: undefined,
+            children: [],
+          },
+          issues,
+          rootChildren,
+        );
       }
     }
   }
@@ -495,6 +537,7 @@ function verifyTableChildren(options: {
   tableName: string;
   namespaceId: string;
   tablePath: string;
+  tableControlPolicy: ControlPolicy;
   issues: SchemaIssue[];
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
@@ -502,6 +545,7 @@ function verifyTableChildren(options: {
   storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
+  columnsCompatible?: ColumnsCompatible;
 }): SchemaVerificationNode[] {
   const {
     contractTable,
@@ -509,6 +553,7 @@ function verifyTableChildren(options: {
     tableName,
     namespaceId,
     tablePath,
+    tableControlPolicy,
     issues,
     strict,
     typeMetadataRegistry,
@@ -516,6 +561,7 @@ function verifyTableChildren(options: {
     storageTypes,
     normalizeDefault,
     normalizeNativeType,
+    columnsCompatible,
   } = options;
   const tableChildren: SchemaVerificationNode[] = [];
   const columnNodes = collectContractColumnNodes({
@@ -524,6 +570,7 @@ function verifyTableChildren(options: {
     tableName,
     namespaceId,
     tablePath,
+    tableControlPolicy,
     issues,
     strict,
     typeMetadataRegistry,
@@ -531,6 +578,7 @@ function verifyTableChildren(options: {
     storageTypes,
     ...ifDefined('normalizeDefault', normalizeDefault),
     ...ifDefined('normalizeNativeType', normalizeNativeType),
+    ...ifDefined('columnsCompatible', columnsCompatible),
   });
   if (columnNodes.length > 0) {
     tableChildren.push(buildColumnsNode(tablePath, columnNodes));
@@ -542,6 +590,7 @@ function verifyTableChildren(options: {
       tableName,
       namespaceId,
       tablePath,
+      tableControlPolicy,
       issues,
       columnNodes,
     });
@@ -553,6 +602,7 @@ function verifyTableChildren(options: {
       schemaTable.primaryKey,
       tableName,
       namespaceId,
+      tableControlPolicy,
       issues,
     );
     if (pkStatus === 'fail') {
@@ -567,6 +617,18 @@ function verifyTableChildren(options: {
         actual: schemaTable.primaryKey,
         children: [],
       });
+    } else if (pkStatus === 'warn') {
+      tableChildren.push({
+        status: 'warn',
+        kind: 'primaryKey',
+        name: `primary key: ${contractTable.primaryKey.columns.join(', ')}`,
+        contractPath: `${tablePath}.primaryKey`,
+        code: 'primary_key_mismatch',
+        message: 'Primary key mismatch',
+        expected: contractTable.primaryKey,
+        actual: schemaTable.primaryKey,
+        children: [],
+      });
     } else {
       tableChildren.push({
         status: 'pass',
@@ -581,23 +643,29 @@ function verifyTableChildren(options: {
       });
     }
   } else if (schemaTable.primaryKey && strict) {
-    issues.push({
+    const issue: SchemaIssue = {
       kind: 'extra_primary_key',
       table: tableName,
       namespaceId,
       message: 'Extra primary key found in database (not in contract)',
-    });
-    tableChildren.push({
-      status: 'fail',
-      kind: 'primaryKey',
-      name: `primary key: ${schemaTable.primaryKey.columns.join(', ')}`,
-      contractPath: `${tablePath}.primaryKey`,
-      code: 'extra_primary_key',
-      message: 'Extra primary key found',
-      expected: undefined,
-      actual: schemaTable.primaryKey,
-      children: [],
-    });
+    };
+    emitIssueAndNodeUnderControlPolicy(
+      tableControlPolicy,
+      issue,
+      {
+        status: 'fail',
+        kind: 'primaryKey',
+        name: `primary key: ${schemaTable.primaryKey.columns.join(', ')}`,
+        contractPath: `${tablePath}.primaryKey`,
+        code: 'extra_primary_key',
+        message: 'Extra primary key found',
+        expected: undefined,
+        actual: schemaTable.primaryKey,
+        children: [],
+      },
+      issues,
+      tableChildren,
+    );
   }
 
   // Verify FK constraints only for FKs with constraint: true.
@@ -611,6 +679,7 @@ function verifyTableChildren(options: {
       tableName,
       namespaceId,
       tablePath,
+      tableControlPolicy,
       issues,
       strict,
     );
@@ -624,6 +693,7 @@ function verifyTableChildren(options: {
     tableName,
     namespaceId,
     tablePath,
+    tableControlPolicy,
     issues,
     strict,
   );
@@ -648,6 +718,7 @@ function verifyTableChildren(options: {
     tableName,
     namespaceId,
     tablePath,
+    tableControlPolicy,
     issues,
     strict,
   );
@@ -662,6 +733,7 @@ function collectContractColumnNodes(options: {
   tableName: string;
   namespaceId: string;
   tablePath: string;
+  tableControlPolicy: ControlPolicy;
   issues: SchemaIssue[];
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
@@ -669,6 +741,7 @@ function collectContractColumnNodes(options: {
   storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
+  columnsCompatible?: ColumnsCompatible;
 }): SchemaVerificationNode[] {
   const {
     contractTable,
@@ -676,6 +749,7 @@ function collectContractColumnNodes(options: {
     tableName,
     namespaceId,
     tablePath,
+    tableControlPolicy,
     issues,
     strict,
     typeMetadataRegistry,
@@ -683,6 +757,7 @@ function collectContractColumnNodes(options: {
     storageTypes,
     normalizeDefault,
     normalizeNativeType,
+    columnsCompatible,
   } = options;
   const columnNodes: SchemaVerificationNode[] = [];
 
@@ -691,24 +766,30 @@ function collectContractColumnNodes(options: {
     const columnPath = `${tablePath}.columns.${columnName}`;
 
     if (!schemaColumn) {
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'missing_column',
         table: tableName,
         namespaceId,
         column: columnName,
         message: `Column "${tableName}"."${columnName}" is missing from database`,
-      });
-      columnNodes.push({
-        status: 'fail',
-        kind: 'column',
-        name: `${columnName}: missing`,
-        contractPath: columnPath,
-        code: 'missing_column',
-        message: `Column "${columnName}" is missing`,
-        expected: undefined,
-        actual: undefined,
-        children: [],
-      });
+      };
+      emitIssueAndNodeUnderControlPolicy(
+        tableControlPolicy,
+        issue,
+        {
+          status: 'fail',
+          kind: 'column',
+          name: `${columnName}: missing`,
+          contractPath: columnPath,
+          code: 'missing_column',
+          message: `Column "${columnName}" is missing`,
+          expected: undefined,
+          actual: undefined,
+          children: [],
+        },
+        issues,
+        columnNodes,
+      );
       continue;
     }
 
@@ -720,6 +801,7 @@ function collectContractColumnNodes(options: {
         contractColumn,
         schemaColumn,
         columnPath,
+        tableControlPolicy,
         issues,
         strict,
         typeMetadataRegistry,
@@ -727,6 +809,7 @@ function collectContractColumnNodes(options: {
         storageTypes,
         ...ifDefined('normalizeDefault', normalizeDefault),
         ...ifDefined('normalizeNativeType', normalizeNativeType),
+        ...ifDefined('columnsCompatible', columnsCompatible),
       }),
     );
   }
@@ -740,31 +823,46 @@ function appendExtraColumnNodes(options: {
   tableName: string;
   namespaceId: string;
   tablePath: string;
+  tableControlPolicy: ControlPolicy;
   issues: SchemaIssue[];
   columnNodes: SchemaVerificationNode[];
 }): void {
-  const { contractTable, schemaTable, tableName, namespaceId, tablePath, issues, columnNodes } =
-    options;
+  const {
+    contractTable,
+    schemaTable,
+    tableName,
+    namespaceId,
+    tablePath,
+    tableControlPolicy,
+    issues,
+    columnNodes,
+  } = options;
   for (const [columnName, { nativeType }] of Object.entries(schemaTable.columns)) {
     if (!contractTable.columns[columnName]) {
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'extra_column',
         table: tableName,
         namespaceId,
         column: columnName,
         message: `Extra column "${tableName}"."${columnName}" found in database (not in contract)`,
-      });
-      columnNodes.push({
-        status: 'fail',
-        kind: 'column',
-        name: `${columnName}: extra`,
-        contractPath: `${tablePath}.columns.${columnName}`,
-        code: 'extra_column',
-        message: `Extra column "${columnName}" found`,
-        expected: undefined,
-        actual: nativeType,
-        children: [],
-      });
+      };
+      emitIssueAndNodeUnderControlPolicy(
+        tableControlPolicy,
+        issue,
+        {
+          status: 'fail',
+          kind: 'column',
+          name: `${columnName}: extra`,
+          contractPath: `${tablePath}.columns.${columnName}`,
+          code: 'extra_column',
+          message: `Extra column "${columnName}" found`,
+          expected: undefined,
+          actual: nativeType,
+          children: [],
+        },
+        issues,
+        columnNodes,
+      );
     }
   }
 }
@@ -776,6 +874,7 @@ function verifyColumn(options: {
   contractColumn: StorageTable['columns'][string];
   schemaColumn: SqlSchemaIR['tables'][string]['columns'][string];
   columnPath: string;
+  tableControlPolicy: ControlPolicy;
   issues: SchemaIssue[];
   strict: boolean;
   typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
@@ -783,6 +882,7 @@ function verifyColumn(options: {
   storageTypes: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
+  columnsCompatible?: ColumnsCompatible;
 }): SchemaVerificationNode {
   const {
     tableName,
@@ -791,12 +891,14 @@ function verifyColumn(options: {
     contractColumn,
     schemaColumn,
     columnPath,
+    tableControlPolicy,
     issues,
     strict,
     codecHooks,
     storageTypes,
     normalizeDefault,
     normalizeNativeType,
+    columnsCompatible,
   } = options;
   const columnChildren: SchemaVerificationNode[] = [];
   let columnStatus: VerificationStatus = 'pass';
@@ -812,8 +914,14 @@ function verifyColumn(options: {
   const schemaNativeType =
     normalizeNativeType?.(schemaColumn.nativeType) ?? schemaColumn.nativeType;
 
-  if (contractNativeType !== schemaNativeType) {
-    issues.push({
+  const typesMatch =
+    contractNativeType === schemaNativeType ||
+    (tableControlPolicy === 'external' &&
+      (columnsCompatible?.(contractNativeType, schemaNativeType) ??
+        contractNativeType === schemaNativeType));
+
+  if (!typesMatch) {
+    const issue: SchemaIssue = {
       kind: 'type_mismatch',
       table: tableName,
       namespaceId,
@@ -821,19 +929,23 @@ function verifyColumn(options: {
       expected: contractNativeType,
       actual: schemaNativeType,
       message: `Column "${tableName}"."${columnName}" has type mismatch: expected "${contractNativeType}", got "${schemaNativeType}"`,
-    });
-    columnChildren.push({
-      status: 'fail',
-      kind: 'type',
-      name: 'type',
-      contractPath: `${columnPath}.nativeType`,
-      code: 'type_mismatch',
-      message: `Type mismatch: expected ${contractNativeType}, got ${schemaNativeType}`,
-      expected: contractNativeType,
-      actual: schemaNativeType,
-      children: [],
-    });
-    columnStatus = 'fail';
+    };
+    const disposition = verifierDisposition(tableControlPolicy, issue.kind);
+    if (disposition !== 'suppress') {
+      issues.push(issue);
+      columnChildren.push({
+        status: disposition,
+        kind: 'type',
+        name: 'type',
+        contractPath: `${columnPath}.nativeType`,
+        code: 'type_mismatch',
+        message: `Type mismatch: expected ${contractNativeType}, got ${schemaNativeType}`,
+        expected: contractNativeType,
+        actual: schemaNativeType,
+        children: [],
+      });
+      columnStatus = disposition;
+    }
   }
 
   if (resolvedContractColumn.codecId) {
@@ -869,7 +981,7 @@ function verifyColumn(options: {
   }
 
   if (contractColumn.nullable !== schemaColumn.nullable) {
-    issues.push({
+    const issue: SchemaIssue = {
       kind: 'nullability_mismatch',
       table: tableName,
       namespaceId,
@@ -877,44 +989,52 @@ function verifyColumn(options: {
       expected: String(contractColumn.nullable),
       actual: String(schemaColumn.nullable),
       message: `Column "${tableName}"."${columnName}" has nullability mismatch: expected ${contractColumn.nullable ? 'nullable' : 'not null'}, got ${schemaColumn.nullable ? 'nullable' : 'not null'}`,
-    });
-    columnChildren.push({
-      status: 'fail',
-      kind: 'nullability',
-      name: 'nullability',
-      contractPath: `${columnPath}.nullable`,
-      code: 'nullability_mismatch',
-      message: `Nullability mismatch: expected ${contractColumn.nullable ? 'nullable' : 'not null'}, got ${schemaColumn.nullable ? 'nullable' : 'not null'}`,
-      expected: contractColumn.nullable,
-      actual: schemaColumn.nullable,
-      children: [],
-    });
-    columnStatus = 'fail';
+    };
+    const disposition = verifierDisposition(tableControlPolicy, issue.kind);
+    if (disposition !== 'suppress') {
+      issues.push(issue);
+      columnChildren.push({
+        status: disposition,
+        kind: 'nullability',
+        name: 'nullability',
+        contractPath: `${columnPath}.nullable`,
+        code: 'nullability_mismatch',
+        message: `Nullability mismatch: expected ${contractColumn.nullable ? 'nullable' : 'not null'}, got ${schemaColumn.nullable ? 'nullable' : 'not null'}`,
+        expected: contractColumn.nullable,
+        actual: schemaColumn.nullable,
+        children: [],
+      });
+      columnStatus = disposition;
+    }
   }
 
   if (contractColumn.default) {
     if (!schemaColumn.default) {
       const defaultDescription = describeColumnDefault(contractColumn.default);
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'default_missing',
         table: tableName,
         namespaceId,
         column: columnName,
         expected: defaultDescription,
         message: `Column "${tableName}"."${columnName}" should have default ${defaultDescription} but database has no default`,
-      });
-      columnChildren.push({
-        status: 'fail',
-        kind: 'default',
-        name: 'default',
-        contractPath: `${columnPath}.default`,
-        code: 'default_missing',
-        message: `Default missing: expected ${defaultDescription}`,
-        expected: defaultDescription,
-        actual: undefined,
-        children: [],
-      });
-      columnStatus = 'fail';
+      };
+      const disposition = verifierDisposition(tableControlPolicy, issue.kind);
+      if (disposition !== 'suppress') {
+        issues.push(issue);
+        columnChildren.push({
+          status: disposition,
+          kind: 'default',
+          name: 'default',
+          contractPath: `${columnPath}.default`,
+          code: 'default_missing',
+          message: `Default missing: expected ${defaultDescription}`,
+          expected: defaultDescription,
+          actual: undefined,
+          children: [],
+        });
+        columnStatus = disposition;
+      }
     } else if (
       !columnDefaultsEqual(
         contractColumn.default,
@@ -924,9 +1044,8 @@ function verifyColumn(options: {
       )
     ) {
       const expectedDescription = describeColumnDefault(contractColumn.default);
-      // schemaColumn.default is now a raw string, describe it as-is
       const actualDescription = schemaColumn.default;
-      issues.push({
+      const issue: SchemaIssue = {
         kind: 'default_mismatch',
         table: tableName,
         namespaceId,
@@ -934,41 +1053,49 @@ function verifyColumn(options: {
         expected: expectedDescription,
         actual: actualDescription,
         message: `Column "${tableName}"."${columnName}" has default mismatch: expected ${expectedDescription}, got ${actualDescription}`,
-      });
-      columnChildren.push({
-        status: 'fail',
-        kind: 'default',
-        name: 'default',
-        contractPath: `${columnPath}.default`,
-        code: 'default_mismatch',
-        message: `Default mismatch: expected ${expectedDescription}, got ${actualDescription}`,
-        expected: expectedDescription,
-        actual: actualDescription,
-        children: [],
-      });
-      columnStatus = 'fail';
+      };
+      const disposition = verifierDisposition(tableControlPolicy, issue.kind);
+      if (disposition !== 'suppress') {
+        issues.push(issue);
+        columnChildren.push({
+          status: disposition,
+          kind: 'default',
+          name: 'default',
+          contractPath: `${columnPath}.default`,
+          code: 'default_mismatch',
+          message: `Default mismatch: expected ${expectedDescription}, got ${actualDescription}`,
+          expected: expectedDescription,
+          actual: actualDescription,
+          children: [],
+        });
+        columnStatus = disposition;
+      }
     }
   } else if (strict && schemaColumn.default) {
-    issues.push({
+    const issue: SchemaIssue = {
       kind: 'extra_default',
       table: tableName,
       namespaceId,
       column: columnName,
       actual: schemaColumn.default,
       message: `Column "${tableName}"."${columnName}" has default ${schemaColumn.default} in database but contract specifies no default`,
-    });
-    columnChildren.push({
-      status: 'fail',
-      kind: 'default',
-      name: 'default',
-      contractPath: `${columnPath}.default`,
-      code: 'extra_default',
-      message: `Extra default: ${schemaColumn.default}`,
-      expected: undefined,
-      actual: schemaColumn.default,
-      children: [],
-    });
-    columnStatus = 'fail';
+    };
+    const disposition = verifierDisposition(tableControlPolicy, issue.kind);
+    if (disposition !== 'suppress') {
+      issues.push(issue);
+      columnChildren.push({
+        status: disposition,
+        kind: 'default',
+        name: 'default',
+        contractPath: `${columnPath}.default`,
+        code: 'extra_default',
+        message: `Extra default: ${schemaColumn.default}`,
+        expected: undefined,
+        actual: schemaColumn.default,
+        children: [],
+      });
+      columnStatus = disposition;
+    }
   }
 
   // Single-pass aggregation for better performance