@prisma-next/family-sql 0.14.0-dev.49 → 0.14.0-dev.50

package/src/core/diff/verifier-disposition.ts

@@ -1,58 +1,30 @@
 import type { ControlPolicy } from '@prisma-next/contract/types';
 import type {
-  SchemaIssue,
+  SchemaDiffIssue,
   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.
+ * Classifies a codec `verifyType` hook finding into the target-neutral
+ * categories the framework grades. A storage type is a named type instance
+ * (e.g. a native enum); the only shape divergence it can carry is a change
+ * to its value set, so a paired mismatch always classifies as `valueDrift`.
  */
-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':
-    case 'check_mismatch':
-      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';
-    case 'check_missing':
-      return 'declaredMissing';
-    case 'check_removed':
-      return 'extraAuxiliary';
+export function classifyStorageTypeDiffIssue(issue: SchemaDiffIssue): VerifierIssueCategory {
+  if (issue.reason === 'not-found') {
+    return 'declaredMissing';
   }
+  if (issue.reason === 'not-expected') {
+    return 'extraAuxiliary';
+  }
+  return 'valueDrift';
 }
 
 export function verifierDisposition(
   controlPolicy: ControlPolicy,
-  issueKind: SchemaIssue['kind'],
+  issue: SchemaDiffIssue,
 ): VerifierOutcome {
-  return dispositionForCategory(controlPolicy, classifySqlVerifierIssueKind(issueKind));
+  return dispositionForCategory(controlPolicy, classifyStorageTypeDiffIssue(issue));
 }

package/src/core/ir/sql-schema-verifier-base.ts

@@ -1,5 +1,5 @@
 import type {
-  SchemaIssue,
+  SchemaDiffIssue,
   SchemaVerifier,
   SchemaVerifyOptions,
   SchemaVerifyResult,
@@ -9,7 +9,7 @@ import type {
  * SQL family `SchemaVerifier` abstract base. Centralises the SQL-shared
  * walk (table-by-table + column-by-column matching keyed by
  * `(namespace.id, name)`, FK / unique / index comparisons via the
- * existing helpers in `verify-helpers.ts`) and exposes a protected hook
+ * shared satisfaction helpers in `sql-schema-diff.ts`) and exposes a protected hook
  * for target extensions (Postgres functions, RLS policies, future
  * target-only kinds).
  *
@@ -29,7 +29,7 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
   implements SchemaVerifier<TContract, TSchema>
 {
   verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult {
-    const issues: SchemaIssue[] = [];
+    const issues: SchemaDiffIssue[] = [];
     issues.push(...this.verifyCommonSqlSchema(options));
     issues.push(...this.verifyTargetExtensions(options));
     return { ok: issues.length === 0, issues };
@@ -43,7 +43,7 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
    */
   protected abstract verifyCommonSqlSchema(
     options: SchemaVerifyOptions<TContract, TSchema>,
-  ): readonly SchemaIssue[];
+  ): readonly SchemaDiffIssue[];
 
   /**
    * Target-specific extensions — e.g. Postgres functions, future RLS
@@ -52,5 +52,5 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
    */
   protected abstract verifyTargetExtensions(
     options: SchemaVerifyOptions<TContract, TSchema>,
-  ): readonly SchemaIssue[];
+  ): readonly SchemaDiffIssue[];
 }

package/src/core/migrations/contract-to-schema-ir.ts

@@ -1,4 +1,5 @@
 import type { ColumnDefault, Contract, JsonValue } from '@prisma-next/contract/types';
+import type { CodecRef } from '@prisma-next/framework-components/codec';
 import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
 import {
   type CheckConstraint,
@@ -12,16 +13,17 @@ import {
   type UniqueConstraint,
 } from '@prisma-next/sql-contract/types';
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
-import type {
-  SqlAnnotations,
-  SqlCheckConstraintIRInput,
-  SqlColumnIR,
-  SqlForeignKeyIR,
-  SqlIndexIR,
+import {
+  type SqlAnnotations,
+  type SqlCheckConstraintIRInput,
+  type SqlColumnIRInput,
+  type SqlForeignKeyIRInput,
+  type SqlIndexIRInput,
   SqlSchemaIR,
   SqlTableIR,
-  SqlUniqueIR,
+  type SqlUniqueIRInput,
 } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 
 /**
@@ -72,7 +74,7 @@ function convertColumn(
   storageTypes: ResolvedStorageTypes,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
-): SqlColumnIR {
+): SqlColumnIRInput {
   // Resolve `typeRef` so columns that delegate their `nativeType`/`codecId`/
   // `typeParams` to a named `storage.types` entry expand the same way as
   // columns that inline those fields. Without this resolution, a
@@ -98,6 +100,43 @@ function convertColumn(
       'default',
       column.default != null && renderDefault ? renderDefault(column.default, column) : undefined,
     ),
+    // Contract-derived columns are resolved by construction: the computed
+    // full native type doubles as the resolved value, and the contract's
+    // structured default is the resolved default (the introspected side
+    // stamps its normalizer's parse of the raw expression).
+    resolvedNativeType: nativeType,
+    ...ifDefined('resolvedDefault', column.default ?? undefined),
+    // The column's codec identity, carried the same way the query AST
+    // carries `CodecRef` (TML-2456) — the migration planner's op-builders
+    // resolve DDL rendering from this at plan time (Decision 5), instead of
+    // reading a derivation-precomputed render payload.
+    codecRef: buildColumnCodecRef(resolved, column.many),
+    codecBaseNativeType: resolved.nativeType,
+    ...(column.typeRef !== undefined ? { codecNamedType: true } : {}),
+  };
+}
+
+/**
+ * Builds the column's `CodecRef` from its resolved (post-`typeRef`) codec
+ * identity — the same construction the query AST and the migration DDL
+ * renderer already use (TML-2456, TML-2918).
+ */
+function buildColumnCodecRef(
+  resolved: Pick<StorageColumn, 'codecId' | 'nativeType' | 'typeParams'>,
+  many: boolean | undefined,
+): CodecRef {
+  return {
+    codecId: resolved.codecId,
+    ...ifDefined(
+      'typeParams',
+      resolved.typeParams !== undefined
+        ? blindCast<
+            JsonValue,
+            'resolved.typeParams is JsonValue-shaped storage metadata; the narrowed (non-undefined) value lands in CodecRef.typeParams which is JsonValue'
+          >(resolved.typeParams)
+        : undefined,
+    ),
+    ...ifDefined('many', many),
   };
 }
 
@@ -193,22 +232,26 @@ function convertCheck(check: CheckConstraint, storage: SqlStorage): SqlCheckCons
   };
 }
 
-function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
+function convertUnique(unique: UniqueConstraint): SqlUniqueIRInput {
   return {
     columns: unique.columns,
     ...ifDefined('name', unique.name),
   };
 }
 
-function convertIndex(index: Index): SqlIndexIR {
+function convertIndex(index: Index): SqlIndexIRInput {
   return {
     columns: index.columns,
     unique: false,
     ...ifDefined('name', index.name),
+    // Carried so the derived index node compares type/options against the
+    // introspected side (the legacy walk read them from the contract).
+    ...ifDefined('type', index.type),
+    ...ifDefined('options', index.options),
   };
 }
 
-function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
+function convertForeignKey(fk: ForeignKey): SqlForeignKeyIRInput {
   return {
     columns: fk.source.columns,
     referencedTable: fk.target.tableName,
@@ -228,7 +271,7 @@ function convertTable(
   renderDefault: DefaultRenderer | undefined,
   storage: SqlStorage,
 ): SqlTableIR {
-  const columns: Record<string, SqlColumnIR> = {};
+  const columns: Record<string, SqlColumnIRInput> = {};
   for (const [colName, colDef] of Object.entries(table.columns)) {
     columns[colName] = convertColumn(
       colName,
@@ -244,7 +287,7 @@ function convertTable(
     ...table.uniques.map((unique) => unique.columns.join(',')),
     ...(table.primaryKey ? [table.primaryKey.columns.join(',')] : []),
   ]);
-  const fkBackingIndexes: SqlIndexIR[] = [];
+  const fkBackingIndexes: SqlIndexIRInput[] = [];
   for (const fk of table.foreignKeys) {
     if (fk.index === false) continue;
     const key = fk.source.columns.join(',');
@@ -262,7 +305,7 @@ function convertTable(
       ? table.checks.map((c) => convertCheck(c, storage))
       : undefined;
 
-  return {
+  return new SqlTableIR({
     name,
     columns,
     ...ifDefined('primaryKey', table.primaryKey),
@@ -270,7 +313,7 @@ function convertTable(
     uniques: table.uniques.map(convertUnique),
     indexes: [...table.indexes.map(convertIndex), ...fkBackingIndexes],
     ...ifDefined('checks', checks),
-  };
+  });
 }
 
 /**
@@ -383,7 +426,7 @@ export function contractNamespaceToSchemaIR(
   }
   const namespace = storage.namespaces[namespaceId];
   if (!namespace) {
-    return { tables: {} };
+    return new SqlSchemaIR({ tables: {} });
   }
   const storageTypes: ResolvedStorageTypes = { ...(storage.types ?? {}) };
   const tables: Record<string, SqlTableIR> = {};
@@ -398,7 +441,7 @@ export function contractNamespaceToSchemaIR(
       storage,
     );
   }
-  return { tables };
+  return new SqlSchemaIR({ tables });
 }
 
 export function contractToSchemaIR(
@@ -410,7 +453,7 @@ export function contractToSchemaIR(
   }
 
   if (!contract) {
-    return { tables: {} };
+    return new SqlSchemaIR({ tables: {} });
   }
 
   const storage = contract.storage;
@@ -442,10 +485,10 @@ export function contractToSchemaIR(
     options.resolveEnumNamespaceSchema,
   );
 
-  return {
+  return new SqlSchemaIR({
     tables,
     ...ifDefined('annotations', annotations),
-  };
+  });
 }
 
 function deriveAnnotations(

package/src/core/migrations/native-type-expander.ts

@@ -0,0 +1,28 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import { extractCodecControlHooks } from '../assembly';
+
+/**
+ * Builds the codec-hook-composed `expandNativeType` callback the contract→IR
+ * derivation uses to expand parameterized native types (e.g. `character` +
+ * `{ length: 36 }` → `character(36)`). Returns `undefined` when no framework
+ * components are supplied, so callers can omit the option entirely.
+ */
+export function buildNativeTypeExpander(
+  frameworkComponents?: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>,
+) {
+  if (!frameworkComponents) {
+    return undefined;
+  }
+  const codecHooks = extractCodecControlHooks(frameworkComponents);
+  return (input: {
+    readonly nativeType: string;
+    readonly codecId?: string;
+    readonly typeParams?: Record<string, unknown>;
+  }) => {
+    if (!input.typeParams) return input.nativeType;
+    if (!input.codecId) return input.nativeType;
+    const hooks = codecHooks.get(input.codecId);
+    if (!hooks?.expandNativeType) return input.nativeType;
+    return hooks.expandNativeType(input);
+  };
+}

package/src/core/migrations/schema-differ.ts

@@ -1,40 +1,41 @@
-import type { Contract } from '@prisma-next/contract/types';
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
-import type {
-  SchemaDiffer,
-  VerifyDatabaseSchemaResult,
-} from '@prisma-next/framework-components/control';
+import type { SchemaDiffIssue } from '@prisma-next/framework-components/control';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
 
 /**
- * Inputs to a SQL target's schema-differ (`diffDatabaseSchema` /
- * `verifyDatabaseSchema` on the descriptor): the contract (the expected side
- * derives from it), the introspected actual schema node, and the resolution
- * context the relational diff needs.
+ * The full-tree node diff a SQL target produces for the family verify
+ * verdict: the target derives the expected tree from the contract, applies
+ * the pre-diff normalizations (semantic satisfaction, FK schema-segment
+ * resolution), runs the generic differ, and ownership-scopes the result.
+ * Strict gating, control-policy disposition, and the verdict itself are the
+ * family's post-diff filters over this output.
  */
-export interface DiffDatabaseSchemaInput {
+export interface SqlSchemaDiffResult {
+  /** The full, ownership-scoped diff issue list. */
+  readonly issues: readonly SchemaDiffIssue[];
+  /**
+   * Resolves a diff issue's subject table's declared control policy directly
+   * from the contract (Decision 5's own-layer-per-concern discipline extends
+   * here too: control policy is a contract concern, resolved by the target
+   * at disposition time — never stamped on the diff node). `undefined`
+   * when the issue's path resolves to no contract table (a genuine orphan,
+   * or a non-table subject).
+   */
+  readonly resolveControlPolicy: (issue: SchemaDiffIssue) => ControlPolicy | undefined;
+  /**
+   * The expected/actual namespace-node pairs the codec `verifyType` hooks
+   * run over — one per contract namespace with tables, paired by DDL
+   * schema; a flat target repeats its sole actual root per such namespace.
+   */
+  readonly namespacePairs: ReadonlyArray<{ readonly actual: SqlSchemaIRNode | undefined }>;
+}
+
+export interface SqlSchemaDiffInput {
   readonly contract: Contract<SqlStorage>;
   readonly schema: SqlSchemaIRNode;
-  readonly strict: boolean;
-  readonly typeMetadataRegistry: ReadonlyMap<string, { readonly nativeType?: string }>;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
 }
 
-/**
- * The `SchemaDiffer` a SQL target implements: the black-box comparison of the
- * contract's expected schema against the introspected actual schema, projected
- * to the two issue lists. How it computes them is private to the target.
- */
-export type SqlDiffDatabaseSchema = SchemaDiffer<DiffDatabaseSchemaInput>['diff'];
-
-/**
- * The same combined comparison as {@link SqlDiffDatabaseSchema}, wrapped in the
- * verify envelope (`ok`/`summary`/`code`/`target`/`timings`) plus the
- * pass/warn/fail tree the CLI renders. Verify calls this instead of the diff so
- * the relational walk that produces the tree runs once per verify, not once for
- * the diff and again for the tree.
- */
-export type SqlVerifyDatabaseSchema = (
-  input: DiffDatabaseSchemaInput,
-) => VerifyDatabaseSchemaResult;
+export type SqlSchemaDiffFn = (input: SqlSchemaDiffInput) => SqlSchemaDiffResult;

package/src/core/migrations/types.ts

@@ -4,7 +4,6 @@ import type {
   ContractSpace,
   ControlAdapterDescriptor,
   ControlExtensionDescriptor,
-  DiffIssue,
   MigrationOperationPolicy,
   MigrationPlan,
   MigrationPlannerConflict,
@@ -17,7 +16,8 @@ import type {
   MigrationRunnerResult,
   OperationContext,
   OpFactoryCall,
-  SchemaIssue,
+  SchemaDiffIssue,
+  SchemaOwnership,
 } from '@prisma-next/framework-components/control';
 import type { AggregateMigrationEdgeRef } from '@prisma-next/migration-tools/aggregate';
 import type {
@@ -28,7 +28,7 @@ import type {
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import type { SqlOperationDescriptors } from '@prisma-next/sql-operations';
-import type { SqlSchemaIR, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import type { SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
 import type { SqlControlAdapter } from '../control-adapter';
 
@@ -99,20 +99,29 @@ export interface FieldEventContext {
 }
 
 export interface CodecControlHooks<TTargetDetails = unknown> {
+  /**
+   * `schema` is typed as the family-level `SqlSchemaIRNode` (not the concrete
+   * `SqlSchemaIR` class) because the actual value handed in is whatever
+   * per-namespace node the calling target's tree shape produces — a flat
+   * `SqlSchemaIR` for SQLite, a `PostgresNamespaceSchemaNode` for Postgres —
+   * read structurally for its `tables`/`nativeEnumTypeNames` fields. Hooks
+   * that need the concrete Postgres shape narrow via
+   * `PostgresNamespaceSchemaNode.is(schema)`.
+   */
   planTypeOperations?: (options: {
     readonly typeName: string;
     readonly typeInstance: StorageTypeInstance;
     readonly contract: Contract<SqlStorage>;
-    readonly schema: SqlSchemaIR;
+    readonly schema: SqlSchemaIRNode;
     readonly schemaName?: string;
     readonly policy: MigrationOperationPolicy;
   }) => StorageTypePlanResult<TTargetDetails>;
   verifyType?: (options: {
     readonly typeName: string;
     readonly typeInstance: StorageTypeInstance;
-    readonly schema: SqlSchemaIR;
+    readonly schema: SqlSchemaIRNode;
     readonly schemaName?: string;
-  }) => readonly SchemaIssue[];
+  }) => readonly SchemaDiffIssue[];
   introspectTypes?: (options: {
     readonly driver: SqlControlDriverInstance<string>;
     readonly schemaName?: string;
@@ -346,15 +355,15 @@ export interface SqlMigrationPlannerPlanOptions {
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
   /**
-   * Caller-supplied keep-predicate the planner applies to its schema diff
-   * (via `SchemaDiff.filter`) before building operations. The orchestration
-   * constructs it so the diff findings reaching op-building are exactly the
-   * contract space's own — e.g. dropping the `extra` findings for elements a
-   * sibling contract space declares, so the planner never emits DROP ops
-   * against another space's tables. The planner applies it blindly and holds
-   * no ownership logic. Absent for single-space plans.
+   * Ownership oracle over the whole contract-space composition (the passive
+   * aggregate). The planner asks it, per live extra node, whether any space
+   * declares that entity: a sibling-owned node is left untouched, an unowned
+   * node is a genuine extra it may drop under a destructive policy. The
+   * planner holds no list of other spaces' names — ownership lives in the
+   * aggregate; it only asks. Absent for a single-space plan handed no
+   * aggregate. See {@link SchemaOwnership}.
    */
-  readonly keepDiffIssue?: (issue: DiffIssue) => boolean;
+  readonly ownership?: SchemaOwnership;
 }
 
 export interface SqlMigrationPlanner<TTargetDetails> {

package/src/exports/control.ts

@@ -39,6 +39,7 @@ export {
 } from '../core/migrations/control-policy';
 export type { PlanFieldEventOperationsOptions } from '../core/migrations/field-event-planner';
 export { planFieldEventOperations } from '../core/migrations/field-event-planner';
+export { buildNativeTypeExpander } from '../core/migrations/native-type-expander';
 export {
   createMigrationPlan,
   plannerFailure,
@@ -47,6 +48,11 @@ export {
   runnerSuccess,
 } from '../core/migrations/plan-helpers';
 export { INIT_ADDITIVE_POLICY } from '../core/migrations/policies';
+export type {
+  SqlSchemaDiffFn,
+  SqlSchemaDiffInput,
+  SqlSchemaDiffResult,
+} from '../core/migrations/schema-differ';
 export type {
   CodecControlHooks,
   CreateSqlMigrationPlanOptions,

package/src/exports/diff.ts

@@ -1,18 +1,38 @@
 /**
  * SQL relational schema-diff exports.
  *
- * The shared relational diff that each SQL target descriptor's
- * `diffDatabaseSchema` composes (Postgres adds its structural policy diff on
- * top; SQLite is relational only). Pure — no database connection required.
+ * The generic node differ (`buildPostgresPlanDiff` / `buildSqlitePlanDiff`)
+ * drives both plan and verify; this module surfaces the shared
+ * semantic-satisfaction predicates and verify-verdict machinery that survive
+ * it. Pure — no database connection required.
  */
 
 export type {
-  NativeTypeNormalizer,
-  VerifySqlSchemaOptions,
-} from '../core/diff/sql-schema-diff';
-export { verifySqlSchema, verifySqlSchemaTree } from '../core/diff/sql-schema-diff';
+  SemanticSatisfactionInput,
+  SemanticSatisfactionResult,
+} from '../core/diff/diff-tree-normalization';
+export {
+  neutralizeFlatExpectedFkSchemas,
+  normalizeFlatActualForDiff,
+  resolveSemanticSatisfaction,
+} from '../core/diff/diff-tree-normalization';
+export type {
+  SqlDiffVerdict,
+  SqlDiffVerdictInput,
+  StorageTypeVerdict,
+  StorageTypeVerdictInput,
+  VerifySqlSchemaByDiffInput,
+} from '../core/diff/schema-verify';
+export {
+  classifyDiffSubjectGranularity,
+  classifySqlDiffIssue,
+  computeSqlDiffVerdict,
+  computeStorageTypeVerdict,
+  verifySqlSchemaByDiff,
+} from '../core/diff/schema-verify';
+export type { NativeTypeNormalizer } from '../core/diff/sql-schema-diff';
 export {
   arraysEqual,
   isIndexSatisfied,
   isUniqueConstraintSatisfied,
-} from '../core/diff/verify-helpers';
+} from '../core/diff/sql-schema-diff';