@prisma-next/sql-schema-ir 0.14.0-dev.7 → 0.14.0-dev.71

package/src/ir/primary-key.ts

@@ -1,5 +1,8 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
 import { freezeNode } from '@prisma-next/framework-components/ir';
-import { SqlSchemaIRNode } from './sql-schema-ir-node';
+import { blindCast } from '@prisma-next/utils/casts';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
+import { assertNode, SqlSchemaIRNode } from './sql-schema-ir-node';
 
 export interface PrimaryKeyInput {
   readonly columns: readonly string[];
@@ -11,8 +14,17 @@ export interface PrimaryKeyInput {
  * shape (same `columns` + optional `name`) so verification can compare
  * intent and actual structurally. Defined here independently to avoid
  * a sql-schema-ir -> sql-contract dependency.
+ *
+ * Implements `DiffableNode` so a primary key is directly a table's diff-tree
+ * child. `id` is a fixed sentinel — a table has at most one primary key, so
+ * there is never a sibling to disambiguate against. `isEqualTo` compares the
+ * column tuple; the PK's own `name` is a database-assigned label with no
+ * semantic weight, so it is not compared (mirrors the policy node's
+ * name-insensitivity to non-identifying detail).
  */
-export class PrimaryKey extends SqlSchemaIRNode {
+export class PrimaryKey extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.primaryKey;
+
   readonly columns: readonly string[];
   declare readonly name?: string;
 
@@ -22,4 +34,28 @@ export class PrimaryKey extends SqlSchemaIRNode {
     if (input.name !== undefined) this.name = input.name;
     freezeNode(this);
   }
+
+  get id(): string {
+    return 'primary-key';
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  static is(node: SqlSchemaIRNode): node is PrimaryKey {
+    return node.nodeKind === RelationalSchemaNodeKind.primaryKey;
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'PrimaryKey', PrimaryKey.is);
+    return (
+      this.columns.length === node.columns.length &&
+      this.columns.every((c, i) => c === node.columns[i])
+    );
+  }
 }

package/src/ir/resolved-default-equality.ts

@@ -0,0 +1,79 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+import { canonicalStringify } from '@prisma-next/utils/canonical-stringify';
+
+/**
+ * Structural equality for two resolved column defaults, ported from the
+ * relational walk's `columnDefaultsEqual` normalized branch: kinds must
+ * match; literal values are normalized (Date and temporal-typed strings to
+ * ISO instants) then compared canonically (JSON objects match their
+ * canonical string form); function expressions compare case- and
+ * whitespace-insensitively.
+ *
+ * `nativeType` provides the temporal-normalization context (the actual
+ * side's resolved native type in a diff comparison).
+ */
+export function resolvedDefaultsEqual(
+  expected: ColumnDefault,
+  actual: ColumnDefault,
+  nativeType?: string,
+): boolean {
+  if (expected.kind !== actual.kind) return false;
+  if (expected.kind === 'literal' && actual.kind === 'literal') {
+    return literalValuesEqual(
+      normalizeLiteralValue(expected.value, nativeType),
+      normalizeLiteralValue(actual.value, nativeType),
+    );
+  }
+  if (expected.kind === 'function' && actual.kind === 'function') {
+    return (
+      normalizeFunctionExpression(expected.expression) ===
+      normalizeFunctionExpression(actual.expression)
+    );
+  }
+  return false;
+}
+
+function normalizeFunctionExpression(expression: string): string {
+  return expression.toLowerCase().replace(/\s+/g, '');
+}
+
+function isTemporalNativeType(nativeType?: string): boolean {
+  if (!nativeType) return false;
+  const normalized = nativeType.toLowerCase();
+  return normalized.includes('timestamp') || normalized === 'date';
+}
+
+function normalizeLiteralValue(value: unknown, nativeType?: string): unknown {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === 'string' && isTemporalNativeType(nativeType)) {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) {
+      return parsed.toISOString();
+    }
+  }
+  return value;
+}
+
+function literalValuesEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+    return canonicalStringify(a) === canonicalStringify(b);
+  }
+  if (typeof a === 'object' && a !== null && typeof b === 'string') {
+    try {
+      return canonicalStringify(a) === canonicalStringify(JSON.parse(b));
+    } catch {
+      return false;
+    }
+  }
+  if (typeof a === 'string' && typeof b === 'object' && b !== null) {
+    try {
+      return canonicalStringify(JSON.parse(a)) === canonicalStringify(b);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}

package/src/ir/schema-node-kinds.ts

@@ -0,0 +1,86 @@
+import type { DiffSubjectGranularity } from '@prisma-next/framework-components/control';
+
+/**
+ * The `nodeKind` discriminant for each relational schema-diff leaf node.
+ * Each node carries a unique value; the differ pairs siblings by `id`, and
+ * these kinds distinguish the node types that appear as `PostgresTableSchemaNode`
+ * children (columns, primary key, foreign keys, uniques, indexes, checks) from
+ * each other and from the RLS policy/role kinds a target defines separately.
+ */
+export const RelationalSchemaNodeKind = {
+  schema: 'sql-schema',
+  table: 'sql-table',
+  column: 'sql-column',
+  columnDefault: 'sql-column-default',
+  primaryKey: 'sql-primary-key',
+  foreignKey: 'sql-foreign-key',
+  unique: 'sql-unique',
+  index: 'sql-index',
+  check: 'sql-check-constraint',
+} as const;
+
+export type RelationalSchemaNodeKind =
+  (typeof RelationalSchemaNodeKind)[keyof typeof RelationalSchemaNodeKind];
+
+/**
+ * The one real map from a relational `nodeKind` to the framework-neutral
+ * {@link DiffSubjectGranularity} its diff issues carry — the SQL family's
+ * post-diff filters (issue category, strict-mode gating) and the framework
+ * aggregate's unclaimed-elements sweep key on the granularity, never on the
+ * `nodeKind` spelling and never on anything stamped on the node. Resolution
+ * is by `nodeKind` equality against this map, not a suffix string match.
+ * Target-specific node kinds (Postgres namespace/table/policy/role) are
+ * outside this family layer's vocabulary and map their own kinds directly.
+ */
+const RELATIONAL_NODE_GRANULARITY: Readonly<
+  Record<RelationalSchemaNodeKind, DiffSubjectGranularity>
+> = {
+  [RelationalSchemaNodeKind.schema]: 'structural',
+  [RelationalSchemaNodeKind.table]: 'entity',
+  [RelationalSchemaNodeKind.column]: 'field',
+  [RelationalSchemaNodeKind.columnDefault]: 'auxiliary',
+  [RelationalSchemaNodeKind.primaryKey]: 'auxiliary',
+  [RelationalSchemaNodeKind.foreignKey]: 'auxiliary',
+  [RelationalSchemaNodeKind.unique]: 'auxiliary',
+  [RelationalSchemaNodeKind.index]: 'auxiliary',
+  [RelationalSchemaNodeKind.check]: 'auxiliary',
+};
+
+function isRelationalSchemaNodeKind(nodeKind: string): nodeKind is RelationalSchemaNodeKind {
+  return Object.hasOwn(RELATIONAL_NODE_GRANULARITY, nodeKind);
+}
+
+/**
+ * Looks up the subject granularity for a relational `nodeKind`. Throws for a
+ * `nodeKind` outside this map (a target-specific kind, e.g. Postgres's
+ * namespace/table/policy/role) — those map their own kinds directly rather
+ * than through this family-level map.
+ */
+export function relationalNodeGranularity(nodeKind: string): DiffSubjectGranularity {
+  if (!isRelationalSchemaNodeKind(nodeKind)) {
+    throw new Error(`relationalNodeGranularity: unrecognized relational node kind "${nodeKind}"`);
+  }
+  return RELATIONAL_NODE_GRANULARITY[nodeKind];
+}
+
+/**
+ * The one real map from a relational `nodeKind` to its storage `entityKind`
+ * — the same vocabulary the contract storage's `entries` dictionary keys use
+ * (`elementCoordinates` walks it). Only the whole-table kind has an entity of
+ * its own; every other relational node (a column, an index, …) is nested
+ * under one and maps to nothing here.
+ */
+const RELATIONAL_NODE_ENTITY_KIND: Partial<Readonly<Record<RelationalSchemaNodeKind, string>>> = {
+  [RelationalSchemaNodeKind.table]: 'table',
+};
+
+/**
+ * Looks up the storage `entityKind` for a relational `nodeKind` — sibling of
+ * {@link relationalNodeGranularity}, resolved by `nodeKind` equality against
+ * {@link RELATIONAL_NODE_ENTITY_KIND}. `undefined` for a target-specific kind
+ * (targets map their own kinds directly) or a relational kind with no entity
+ * of its own.
+ */
+export function relationalNodeEntityKind(nodeKind: string): string | undefined {
+  return isRelationalSchemaNodeKind(nodeKind) ? RELATIONAL_NODE_ENTITY_KIND[nodeKind] : undefined;
+}

package/src/ir/sql-check-constraint-ir.ts

@@ -1,5 +1,8 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
 import { freezeNode } from '@prisma-next/framework-components/ir';
-import { SqlSchemaIRNode } from './sql-schema-ir-node';
+import { blindCast } from '@prisma-next/utils/casts';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
+import { assertNode, SqlSchemaIRNode } from './sql-schema-ir-node';
 
 export interface SqlCheckConstraintIRInput {
   /** Constraint name as stored in the database catalog. */
@@ -16,8 +19,15 @@ export interface SqlCheckConstraintIRInput {
  *
  * Carries the **resolved values** rather than a raw SQL predicate so
  * callers can compare value-sets without parsing SQL.
+ *
+ * Implements `DiffableNode` so a check constraint is directly a table's
+ * diff-tree child: `id` is the constraint name. `isEqualTo` compares
+ * `column` and the permitted-value set (order-insensitive — the database
+ * does not guarantee `IN (...)` ordering).
  */
-export class SqlCheckConstraintIR extends SqlSchemaIRNode {
+export class SqlCheckConstraintIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.check;
+
   readonly name: string;
   readonly column: string;
   readonly permittedValues: readonly string[];
@@ -29,4 +39,35 @@ export class SqlCheckConstraintIR extends SqlSchemaIRNode {
     this.permittedValues = Object.freeze([...input.permittedValues]);
     freezeNode(this);
   }
+
+  get id(): string {
+    return `check:${this.name}`;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  static is(node: SqlSchemaIRNode): node is SqlCheckConstraintIR {
+    return node.nodeKind === RelationalSchemaNodeKind.check;
+  }
+
+  /**
+   * Compares the permitted-value sets only (unordered), matching the
+   * relational walk's `verifyCheckConstraints`: two checks pairing by name
+   * compare their value sets — the `column` field is descriptive, not part
+   * of the comparison, so a name-paired check with equal values verifies
+   * regardless of which column carries it.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'SqlCheckConstraintIR', SqlCheckConstraintIR.is);
+    const thisValues = new Set(this.permittedValues);
+    const otherValues = new Set(node.permittedValues);
+    if (thisValues.size !== otherValues.size) return false;
+    return [...thisValues].every((v) => otherValues.has(v));
+  }
 }

package/src/ir/sql-column-default-ir.ts

@@ -0,0 +1,96 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+import type { DiffableNode } from '@prisma-next/framework-components/control';
+import { freezeNode } from '@prisma-next/framework-components/ir';
+import { blindCast } from '@prisma-next/utils/casts';
+import { resolvedDefaultsEqual } from './resolved-default-equality';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
+import { assertNode, defineNonEnumerable, SqlSchemaIRNode } from './sql-schema-ir-node';
+
+export interface SqlColumnDefaultIRInput {
+  /** Structured resolved default (contract-declared or normalizer-parsed). */
+  readonly resolved?: ColumnDefault;
+  /** Raw database default expression, when known (introspected side). */
+  readonly raw?: string;
+  /**
+   * Native-type context for temporal literal normalization — the owning
+   * column's resolved native type.
+   */
+  readonly nativeTypeContext?: string;
+  /**
+   * The owning column's array-ness, threaded through so the planner's
+   * set-default op-builder can render an array-literal default (e.g.
+   * `ARRAY[...]`) the same way the pre-`plan(start, end)` op-path did. See
+   * {@link import('./sql-column-ir').SqlColumnIRInput.many}.
+   */
+  readonly many?: boolean;
+}
+
+/**
+ * Schema-diff node for a column's default value. The default is the one
+ * column attribute with an extra/missing/drift lifecycle of its own, so it
+ * is a child node of the column rather than a compared attribute: an
+ * undeclared live default surfaces as `not-expected`, a declared default the
+ * database lacks as `not-found`, and a divergent value as `not-equal` — the
+ * three reasons cover the legacy `extra_default` / `default_missing` /
+ * `default_mismatch` vocabulary with no attribute inspection.
+ *
+ * `id` is a fixed sentinel — a column has at most one default. Built
+ * transiently by `SqlColumnIR.children()` from the column's own fields;
+ * never constructed by derivation or introspection directly.
+ */
+export class SqlColumnDefaultIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.columnDefault;
+
+  declare readonly resolved?: ColumnDefault;
+  declare readonly raw?: string;
+  declare readonly nativeTypeContext?: string;
+  /** See {@link SqlColumnDefaultIRInput.many}. Non-enumerable so it stays out of JSON and structural equality. */
+  declare readonly many?: boolean;
+
+  constructor(input: SqlColumnDefaultIRInput) {
+    super();
+    if (input.resolved !== undefined) this.resolved = input.resolved;
+    if (input.raw !== undefined) this.raw = input.raw;
+    if (input.nativeTypeContext !== undefined) this.nativeTypeContext = input.nativeTypeContext;
+    defineNonEnumerable(this, 'many', input.many);
+    freezeNode(this);
+  }
+
+  get id(): string {
+    return 'default';
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  static is(node: SqlSchemaIRNode): node is SqlColumnDefaultIR {
+    return node.nodeKind === RelationalSchemaNodeKind.columnDefault;
+  }
+
+  /**
+   * Structured comparison with `this` as the expected side: both sides
+   * resolved compare per the relational walk's `columnDefaultsEqual`
+   * semantics; a declared expected default against an unparseable actual
+   * (raw present, no resolved parse) is a mismatch; two raw-only nodes fall
+   * back to raw string equality.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'SqlColumnDefaultIR', SqlColumnDefaultIR.is);
+    if (this.resolved !== undefined && node.resolved !== undefined) {
+      return resolvedDefaultsEqual(
+        this.resolved,
+        node.resolved,
+        node.nativeTypeContext ?? this.nativeTypeContext,
+      );
+    }
+    if (this.resolved !== undefined || node.resolved !== undefined) {
+      return false;
+    }
+    return this.raw === node.raw;
+  }
+}

package/src/ir/sql-column-ir.ts

@@ -1,5 +1,12 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+import type { CodecRef } from '@prisma-next/framework-components/codec';
+import type { DiffableNode } from '@prisma-next/framework-components/control';
 import { freezeNode } from '@prisma-next/framework-components/ir';
-import { SqlSchemaIRNode } from './sql-schema-ir-node';
+import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
+import { SqlColumnDefaultIR } from './sql-column-default-ir';
+import { assertNode, defineNonEnumerable, SqlSchemaIRNode } from './sql-schema-ir-node';
 
 /**
  * Namespaced annotations for extensibility. Each namespace
@@ -16,6 +23,56 @@ export interface SqlColumnIRInput {
   /** Raw database default expression (e.g. `'hello'::text`, `nextval('seq')`). */
   readonly default?: string;
   readonly annotations?: SqlAnnotations;
+  /** True when the column is a native array (e.g. `text[]`, `int4[]`). The `nativeType` carries the element type only (e.g. `text`, `int4`). */
+  readonly many?: boolean;
+  /**
+   * Fully resolved native type, comparable across the two diff sides:
+   * the contract-derived side stamps the codec-expanded type (typeRef
+   * resolved, parameterized types expanded, `[]` appended for arrays);
+   * the introspected side stamps the target-normalized type with the same
+   * `[]` convention. Stamped at construction by derivation/introspection;
+   * absent on raw hand-built nodes.
+   */
+  readonly resolvedNativeType?: string;
+  /**
+   * Structured default, comparable across the two diff sides: the
+   * contract-derived side stamps the contract's `ColumnDefault`; the
+   * introspected side stamps the target default-normalizer's parse of the
+   * raw expression. Absent when the column declares no default, or when
+   * the introspected raw default could not be parsed.
+   */
+  readonly resolvedDefault?: ColumnDefault;
+  /**
+   * The column's resolved codec reference — the identity the migration
+   * planner's op-builders resolve DDL type rendering against at plan time
+   * (parameterized type expansion, e.g. `character` + `{ length: 36 }` →
+   * `character(36)`), calling the same codec hooks the pre-`plan(start,
+   * end)` op-path called. Carried the same way the query AST carries
+   * `CodecRef` (TML-2456) and the migration DDL renderer (TML-2918).
+   * Stamped on the EXPECTED (contract-derived) column at derivation,
+   * post-`typeRef` resolution (the referenced storage type's own
+   * codec/params, not the column's `typeRef` pointer). Absent on
+   * introspected/hand-built nodes — the actual side never renders DDL —
+   * and never compared by `isEqualTo`.
+   */
+  readonly codecRef?: CodecRef;
+  /**
+   * The column's resolved BASE native type: pre-parameter-expansion,
+   * pre-array-suffix (e.g. `character`, not `character(36)` or
+   * `character[]`). Distinct from {@link resolvedNativeType} (the EXPANDED
+   * comparison value) — DDL rendering re-expands a parameterized type at
+   * plan time from this base, so it must not already carry the expansion.
+   * Stamped alongside {@link codecRef}.
+   */
+  readonly codecBaseNativeType?: string;
+  /**
+   * True when the contract column declared its type via a named
+   * `storage.types` reference (`typeRef`) rather than inline fields — the
+   * migration planner quotes the base native type as an identifier in this
+   * case (e.g. a native enum's type name), matching the pre-`plan(start,
+   * end)` rendering exactly.
+   */
+  readonly codecNamedType?: boolean;
 }
 
 /**
@@ -24,13 +81,34 @@ export interface SqlColumnIRInput {
  * the column's `name` (Schema IR columns are returned as arrays from
  * introspection queries; the parent table re-keys them into a record
  * for downstream consumers).
+ *
+ * Implements `DiffableNode` so a column is directly a table's diff-tree
+ * child: `id` is the column name (unique among a table's columns); `isEqualTo`
+ * compares this column's own attributes only — never children, since a
+ * column is a leaf. When both sides carry `resolvedNativeType` (stamped at
+ * derivation/introspection), the comparison uses the resolved values —
+ * resolved native type, nullability, and structured default equality per
+ * the relational walk's `columnDefaultsEqual` semantics, with `this` as the
+ * expected side. Otherwise it falls back to comparing raw fields.
  */
-export class SqlColumnIR extends SqlSchemaIRNode {
+export class SqlColumnIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.column;
+
   readonly name: string;
   readonly nativeType: string;
   readonly nullable: boolean;
   declare readonly default?: string;
   declare readonly annotations?: SqlAnnotations;
+  /** True when the column is a native array (e.g. `text[]`, `int4[]`). The `nativeType` carries the element type only (e.g. `text`, `int4`). */
+  declare readonly many?: boolean;
+  declare readonly resolvedNativeType?: string;
+  declare readonly resolvedDefault?: ColumnDefault;
+  /** See {@link SqlColumnIRInput.codecRef}. Non-enumerable so it stays out of JSON and structural equality. */
+  declare readonly codecRef?: CodecRef;
+  /** See {@link SqlColumnIRInput.codecBaseNativeType}. Non-enumerable, same reason as {@link codecRef}. */
+  declare readonly codecBaseNativeType?: string;
+  /** See {@link SqlColumnIRInput.codecNamedType}. Non-enumerable, same reason as {@link codecRef}. */
+  declare readonly codecNamedType?: boolean;
 
   constructor(input: SqlColumnIRInput) {
     super();
@@ -39,6 +117,67 @@ export class SqlColumnIR extends SqlSchemaIRNode {
     this.nullable = input.nullable;
     if (input.default !== undefined) this.default = input.default;
     if (input.annotations !== undefined) this.annotations = input.annotations;
+    if (input.many !== undefined) this.many = input.many;
+    if (input.resolvedNativeType !== undefined) this.resolvedNativeType = input.resolvedNativeType;
+    if (input.resolvedDefault !== undefined) this.resolvedDefault = input.resolvedDefault;
+    defineNonEnumerable(this, 'codecRef', input.codecRef);
+    defineNonEnumerable(this, 'codecBaseNativeType', input.codecBaseNativeType);
+    defineNonEnumerable(this, 'codecNamedType', input.codecNamedType);
     freezeNode(this);
   }
+
+  get id(): string {
+    return `column:${this.name}`;
+  }
+
+  /**
+   * The column's default, when declared/present, is the column's one child
+   * node — it has an extra/missing/drift lifecycle of its own, so the differ
+   * recurses to it rather than `isEqualTo` comparing it. Built transiently
+   * from this column's own fields.
+   */
+  children(): readonly DiffableNode[] {
+    if (this.resolvedDefault === undefined && this.default === undefined) {
+      return [];
+    }
+    return [
+      new SqlColumnDefaultIR({
+        ...ifDefined('resolved', this.resolvedDefault),
+        ...ifDefined('raw', this.default),
+        ...ifDefined('nativeTypeContext', this.resolvedNativeType),
+        // `this.many` is unset on contract-derived columns (array-ness rides
+        // on the `nativeType` `[]` suffix there — `codecRef.many` carries
+        // it instead); introspected/hand-built columns set `this.many`
+        // directly. Either source works for the default node's array-
+        // literal rendering.
+        ...ifDefined('many', this.many ?? this.codecRef?.many),
+      }),
+    ];
+  }
+
+  static is(node: SqlSchemaIRNode): node is SqlColumnIR {
+    return node.nodeKind === RelationalSchemaNodeKind.column;
+  }
+
+  /**
+   * Compares the column's own attributes only — the default lives on the
+   * child node. When both sides carry `resolvedNativeType`, the resolved
+   * value governs (array-ness rides on its `[]` suffix); otherwise raw
+   * fields compare.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'SqlColumnIR', SqlColumnIR.is);
+    if (this.resolvedNativeType !== undefined && node.resolvedNativeType !== undefined) {
+      return this.resolvedNativeType === node.resolvedNativeType && this.nullable === node.nullable;
+    }
+    return (
+      this.nativeType === node.nativeType &&
+      this.nullable === node.nullable &&
+      Boolean(this.many) === Boolean(node.many)
+    );
+  }
 }

package/src/ir/sql-foreign-key-ir.ts

@@ -1,6 +1,9 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
 import { freezeNode } from '@prisma-next/framework-components/ir';
+import { blindCast } from '@prisma-next/utils/casts';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
 import type { SqlAnnotations } from './sql-column-ir';
-import { SqlSchemaIRNode } from './sql-schema-ir-node';
+import { assertNode, SqlSchemaIRNode } from './sql-schema-ir-node';
 
 export type SqlReferentialAction = 'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault';
 
@@ -14,6 +17,15 @@ export interface SqlForeignKeyIRInput {
   readonly onDelete?: SqlReferentialAction;
   readonly onUpdate?: SqlReferentialAction;
   readonly annotations?: SqlAnnotations;
+  /**
+   * The real live DDL namespace of the referenced table, comparable across
+   * the two diff sides. Contract-derived trees stamp it explicitly (resolving
+   * namespace ids — including the unbound sentinel — to the DDL namespace);
+   * introspected FKs default it to `referencedSchema`, whose value already
+   * is the live namespace. Folded into `id` in place of the raw value so an
+   * unbound-namespace contract FK pairs with its introspected counterpart.
+   */
+  readonly resolvedReferencedNamespace?: string;
 }
 
 /**
@@ -23,8 +35,19 @@ export interface SqlForeignKeyIRInput {
  * etc.) and intentionally differ from the Contract IR's nested
  * `references: { table, columns }` shape so that the verifier's
  * structural comparison stays explicit about which side it's reading.
+ *
+ * Implements `DiffableNode` so a foreign key is directly a table's diff-tree
+ * child. Foreign keys are frequently unnamed (introspection may not carry a
+ * constraint name, and the contract side never invents one), so `id` is
+ * derived from the referencing/referenced coordinates rather than `name` —
+ * the same tuple that makes two FK constraints the same constraint. This
+ * also serves as the comparison key: two FKs with the same coordinates are
+ * paired by the differ, and `isEqualTo` then compares the remaining
+ * attribute — the referential actions.
  */
-export class SqlForeignKeyIR extends SqlSchemaIRNode {
+export class SqlForeignKeyIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.foreignKey;
+
   readonly columns: readonly string[];
   readonly referencedTable: string;
   readonly referencedColumns: readonly string[];
@@ -33,6 +56,7 @@ export class SqlForeignKeyIR extends SqlSchemaIRNode {
   declare readonly onDelete?: SqlReferentialAction;
   declare readonly onUpdate?: SqlReferentialAction;
   declare readonly annotations?: SqlAnnotations;
+  declare readonly resolvedReferencedNamespace?: string;
 
   constructor(input: SqlForeignKeyIRInput) {
     super();
@@ -44,6 +68,51 @@ export class SqlForeignKeyIR extends SqlSchemaIRNode {
     if (input.onDelete !== undefined) this.onDelete = input.onDelete;
     if (input.onUpdate !== undefined) this.onUpdate = input.onUpdate;
     if (input.annotations !== undefined) this.annotations = input.annotations;
+    const resolvedReferencedNamespace = input.resolvedReferencedNamespace ?? input.referencedSchema;
+    if (resolvedReferencedNamespace !== undefined) {
+      this.resolvedReferencedNamespace = resolvedReferencedNamespace;
+    }
     freezeNode(this);
   }
+
+  get id(): string {
+    const referencedNamespace = this.resolvedReferencedNamespace ?? '';
+    return `foreign-key:${this.columns.join(',')}->${referencedNamespace}.${this.referencedTable}(${this.referencedColumns.join(',')})`;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  static is(node: SqlSchemaIRNode): node is SqlForeignKeyIR {
+    return node.nodeKind === RelationalSchemaNodeKind.foreignKey;
+  }
+
+  /**
+   * Referential-action comparison with `this` as the expected side, matching
+   * the relational walk's `getReferentialActionMismatches`: `noAction` is the
+   * database default and equivalent to an undeclared action, and drift is
+   * flagged only when the expected side declares a (normalized) action.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'SqlForeignKeyIR', SqlForeignKeyIR.is);
+    return (
+      referentialActionMatches(this.onDelete, node.onDelete) &&
+      referentialActionMatches(this.onUpdate, node.onUpdate)
+    );
+  }
+}
+
+function referentialActionMatches(
+  expected: SqlReferentialAction | undefined,
+  actual: SqlReferentialAction | undefined,
+): boolean {
+  const normalizedExpected = expected === 'noAction' ? undefined : expected;
+  if (normalizedExpected === undefined) return true;
+  const normalizedActual = actual === 'noAction' ? undefined : actual;
+  return normalizedExpected === normalizedActual;
 }