@prisma-next/sql-schema-ir 0.14.0 → 0.15.0-dev.1

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,68 @@ 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),
+        // Contract-derived and introspected columns both set `this.many`
+        // directly (with `nativeType` as the bare element type; array-ness
+        // never rides on a `[]` suffix). `codecRef.many` is a fallback for
+        // hand-built nodes that carry a codec ref without the column-level
+        // flag. 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;
 }

package/src/ir/sql-index-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 interface SqlIndexIRInput {
   readonly columns: readonly string[];
@@ -17,8 +20,29 @@ export interface SqlIndexIRInput {
  * `unique` field — introspection sees the underlying index regardless
  * of whether the user expressed it as `@@index` or `@@unique`, and the
  * verifier needs to distinguish them when comparing to the Contract.
+ *
+ * Implements `DiffableNode` so an index is directly a table's diff-tree
+ * child. Indexes are frequently unnamed, so `id` is derived from the column
+ * tuple — the same tuple that makes two indexes the same index, so it
+ * doubles as the pairing key. `isEqualTo` is symmetric structural equality
+ * on the remaining attributes: `unique`, `type`, and `options`. A unique
+ * index and a non-unique index on the same columns are different objects
+ * and are not equal — there is no "stronger satisfies weaker".
+ *
+ * Deliberately column-tuple-only (not `unique`): a contract `@@index`
+ * (non-unique) must still pair against a live unique index of the same
+ * columns so the differ can report the mismatch as an incompatible index
+ * change rather than a spurious missing+extra pair — see
+ * `planner.unique-index-structural.test.ts`. The corollary is that two
+ * indexes legitimately coexisting on one table with the *same* column tuple
+ * (e.g. a unique index and a redundant plain index Postgres has no problem
+ * hosting side by side) collide on this id; the postgres control adapter's
+ * introspection keeps only one such index per table+column-tuple rather
+ * than handing the differ two same-tree siblings it cannot represent.
  */
-export class SqlIndexIR extends SqlSchemaIRNode {
+export class SqlIndexIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.index;
+
   readonly columns: readonly string[];
   readonly unique: boolean;
   declare readonly name?: string;
@@ -36,4 +60,62 @@ export class SqlIndexIR extends SqlSchemaIRNode {
     if (input.annotations !== undefined) this.annotations = input.annotations;
     freezeNode(this);
   }
+
+  get id(): string {
+    return `index:${this.columns.join(',')}`;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  static is(node: SqlSchemaIRNode): node is SqlIndexIR {
+    return node.nodeKind === RelationalSchemaNodeKind.index;
+  }
+
+  /**
+   * Symmetric structural equality: two paired index nodes are equal iff their
+   * `unique` flag, `type`, and (loosely-compared) `options` all match. There
+   * is no satisfaction — a unique index does not equal a non-unique index.
+   * `options` compares loosely (introspection stringifies reloptions); `type`
+   * compares strictly after the introspection-side btree→undefined
+   * normalization done at construction.
+   */
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'SqlIndexIR', SqlIndexIR.is);
+    return (
+      this.unique === node.unique &&
+      this.type === node.type &&
+      indexOptionsLooselyEqual(this.options, node.options)
+    );
+  }
+}
+
+/**
+ * Option-bag equality ported from the relational walk: same key set, values
+ * compared via `String()` coercion — Postgres introspection returns
+ * reloptions values as raw strings (`'70'`, `'false'`) while contract option
+ * leaves are typed (number, boolean, string).
+ */
+function indexOptionsLooselyEqual(
+  a: Record<string, unknown> | undefined,
+  b: Record<string, unknown> | undefined,
+): boolean {
+  const aKeys = a ? Object.keys(a).sort() : [];
+  const bKeys = b ? Object.keys(b).sort() : [];
+  if (aKeys.length !== bKeys.length) return false;
+  for (let i = 0; i < aKeys.length; i += 1) {
+    if (aKeys[i] !== bKeys[i]) return false;
+  }
+  if (aKeys.length === 0) return true;
+  for (const key of aKeys) {
+    if (String(a?.[key]) !== String(b?.[key])) {
+      return false;
+    }
+  }
+  return true;
 }

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

@@ -7,20 +7,32 @@ import { IRNodeBase } from '@prisma-next/framework-components/ir';
  *
  * SQL Schema IR represents the actual database state as discovered by
  * introspection (the parallel to SQL Contract IR, which represents the
- * desired state). Like the Contract side, today's Schema IR has no
- * polymorphic dispatch — verifiers and planners walk by structural
- * position, not by inspecting `kind` — so a single family-level
- * discriminator is sufficient. Future per-leaf overrides land cleanly
- * the same way as on the Contract side.
+ * desired state).
  *
  * The discriminator is installed as a non-enumerable own property,
  * matching the SqlNode pattern. This keeps `JSON.stringify(node)`
  * canonical (no `kind` field), keeps `toEqual({...})` test assertions
  * against pre-lift flat shapes passing, and keeps `node.kind` readable
- * for future polymorphic dispatch.
+ * for dispatch.
+ *
+ * Both `kind` and `nodeKind` are required: every concrete leaf is a node
+ * the generic differ can pair and compare, so every leaf must declare which
+ * node it is. `nodeKind` has no default here — every direct subclass sets its
+ * own literal value (the relational leaves via `RelationalSchemaNodeKind`,
+ * target concretions via their own vocabulary, e.g. `PostgresSchemaNodeKind`).
  */
 export abstract class SqlSchemaIRNode extends IRNodeBase {
-  readonly kind?: string;
+  declare readonly kind: string;
+
+  /**
+   * Enumerable discriminant identifying which node this is (column / primary
+   * key / foreign key / unique / index / check / database / namespace /
+   * table / policy / role / …). Concretions set a unique value; the
+   * `.is`/`.assert` guards compare against it. Unlike `kind`, it is
+   * enumerable, so it survives a spread that flattens a node into a plain
+   * object.
+   */
+  abstract readonly nodeKind: string;
 
   constructor() {
     super();
@@ -32,3 +44,42 @@ export abstract class SqlSchemaIRNode extends IRNodeBase {
     });
   }
 }
+
+/**
+ * Asserts `node` matches `predicate`, narrowing its type to `T`. The one
+ * shared implementation every node class's `static assert` and `isEqualTo`
+ * reach for, instead of each hand-writing its own throw: the message names
+ * the class the caller expected.
+ */
+export function assertNode<T extends SqlSchemaIRNode>(
+  node: SqlSchemaIRNode | undefined,
+  className: string,
+  predicate: (node: SqlSchemaIRNode) => node is T,
+): asserts node is T {
+  if (node === undefined || !predicate(node)) {
+    throw new Error(`Expected a ${className} but got nodeKind=${node?.nodeKind ?? 'undefined'}`);
+  }
+}
+
+/**
+ * Defines a non-enumerable own property, the same treatment `kind` gets
+ * above: a derivation-time render-support field stays out of
+ * `JSON.stringify`, `toEqual({...})` structural assertions, and spreads,
+ * while remaining directly readable (`node.field`) for the one consumer
+ * that resolves it at plan time. A no-op when `value` is `undefined` — the
+ * property is simply absent, matching every other optional field on these
+ * nodes.
+ */
+export function defineNonEnumerable<T extends object>(
+  target: T,
+  key: string,
+  value: unknown,
+): void {
+  if (value === undefined) return;
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+}

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

@@ -1,4 +1,6 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
 import { freezeNode } from '@prisma-next/framework-components/ir';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
 import type { SqlAnnotations } from './sql-column-ir';
 import { SqlSchemaIRNode } from './sql-schema-ir-node';
 import { SqlTableIR, type SqlTableIRInput } from './sql-table-ir';
@@ -17,8 +19,15 @@ export interface SqlSchemaIRInput {
  * The constructor normalises nested `SqlTableIR` instances so
  * downstream walks see a uniform AST regardless of whether the input
  * was a plain-data literal or already-constructed class instances.
+ *
+ * Implements `DiffableNode` as the root of a flat (single-schema) diff
+ * tree: `id` is the fixed sentinel `'database'` (roots have no siblings),
+ * `isEqualTo` is identity (a container has no own attributes), and
+ * `children()` yields the table nodes.
  */
-export class SqlSchemaIR extends SqlSchemaIRNode {
+export class SqlSchemaIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.schema;
+
   readonly tables: Readonly<Record<string, SqlTableIR>>;
   declare readonly annotations?: SqlAnnotations;
 
@@ -35,4 +44,16 @@ export class SqlSchemaIR extends SqlSchemaIRNode {
     if (input.annotations !== undefined) this.annotations = input.annotations;
     freezeNode(this);
   }
+
+  get id(): string {
+    return 'database';
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    return this.id === other.id;
+  }
+
+  children(): readonly DiffableNode[] {
+    return Object.values(this.tables);
+  }
 }

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

@@ -1,5 +1,7 @@
+import type { DiffableNode } from '@prisma-next/framework-components/control';
 import { freezeNode } from '@prisma-next/framework-components/ir';
 import { PrimaryKey, type PrimaryKeyInput } from './primary-key';
+import { RelationalSchemaNodeKind } from './schema-node-kinds';
 import { SqlCheckConstraintIR, type SqlCheckConstraintIRInput } from './sql-check-constraint-ir';
 import { type SqlAnnotations, SqlColumnIR, type SqlColumnIRInput } from './sql-column-ir';
 import { SqlForeignKeyIR, type SqlForeignKeyIRInput } from './sql-foreign-key-ir';
@@ -32,8 +34,17 @@ export interface SqlTableIRInput {
  * walks see a uniform AST regardless of whether the input was a
  * plain-data literal (from introspection) or already-constructed
  * class instances.
+ *
+ * Implements `DiffableNode` so a flat (single-schema) tree is directly
+ * diffable: `id` is the table name; `isEqualTo` is identity (the table's
+ * structural drift is entirely expressed by its children); `children()`
+ * yields every column, the primary key (when present), every foreign key,
+ * unique, index, and check constraint — the same composition and order as
+ * the Postgres table node, minus policies.
  */
-export class SqlTableIR extends SqlSchemaIRNode {
+export class SqlTableIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.table;
+
   readonly name: string;
   readonly columns: Readonly<Record<string, SqlColumnIR>>;
   readonly foreignKeys: ReadonlyArray<SqlForeignKeyIR>;
@@ -79,4 +90,23 @@ export class SqlTableIR extends SqlSchemaIRNode {
     }
     freezeNode(this);
   }
+
+  get id(): string {
+    return this.name;
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    return this.id === other.id;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [
+      ...Object.values(this.columns),
+      ...(this.primaryKey ? [this.primaryKey] : []),
+      ...this.foreignKeys,
+      ...this.uniques,
+      ...this.indexes,
+      ...(this.checks ?? []),
+    ];
+  }
 }

package/src/ir/sql-unique-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 interface SqlUniqueIRInput {
   readonly columns: readonly string[];
@@ -11,8 +14,17 @@ export interface SqlUniqueIRInput {
 /**
  * Schema IR node for a table-level unique constraint as observed by
  * introspection.
+ *
+ * Implements `DiffableNode` so a unique constraint is directly a table's
+ * diff-tree child. Unique constraints are frequently unnamed, so `id` is
+ * derived from the column tuple rather than `name` — the column tuple is
+ * also what makes two unique constraints the same constraint, so it doubles
+ * as the pairing key. There are no further attributes to compare once
+ * columns are equal (the differ pairs on `id`), so `isEqualTo` is identity.
  */
-export class SqlUniqueIR extends SqlSchemaIRNode {
+export class SqlUniqueIR extends SqlSchemaIRNode implements DiffableNode {
+  override readonly nodeKind = RelationalSchemaNodeKind.unique;
+
   readonly columns: readonly string[];
   declare readonly name?: string;
   declare readonly annotations?: SqlAnnotations;
@@ -24,4 +36,25 @@ export class SqlUniqueIR extends SqlSchemaIRNode {
     if (input.annotations !== undefined) this.annotations = input.annotations;
     freezeNode(this);
   }
+
+  get id(): string {
+    return `unique:${this.columns.join(',')}`;
+  }
+
+  children(): readonly DiffableNode[] {
+    return [];
+  }
+
+  static is(node: SqlSchemaIRNode): node is SqlUniqueIR {
+    return node.nodeKind === RelationalSchemaNodeKind.unique;
+  }
+
+  isEqualTo(other: DiffableNode): boolean {
+    const node = blindCast<
+      SqlSchemaIRNode,
+      'every diff-tree node the differ pairs is a SqlSchemaIRNode'
+    >(other);
+    assertNode(node, 'SqlUniqueIR', SqlUniqueIR.is);
+    return this.id === node.id;
+  }
 }

package/src/types.ts

@@ -10,10 +10,19 @@
  */
 
 export { PrimaryKey, type PrimaryKeyInput } from './ir/primary-key';
+export {
+  RelationalSchemaNodeKind,
+  relationalNodeEntityKind,
+  relationalNodeGranularity,
+} from './ir/schema-node-kinds';
 export {
   SqlCheckConstraintIR,
   type SqlCheckConstraintIRInput,
 } from './ir/sql-check-constraint-ir';
+export {
+  SqlColumnDefaultIR,
+  type SqlColumnDefaultIRInput,
+} from './ir/sql-column-default-ir';
 export {
   type SqlAnnotations,
   SqlColumnIR,
@@ -26,7 +35,7 @@ export {
 } from './ir/sql-foreign-key-ir';
 export { SqlIndexIR, type SqlIndexIRInput } from './ir/sql-index-ir';
 export { SqlSchemaIR, type SqlSchemaIRInput } from './ir/sql-schema-ir';
-export { SqlSchemaIRNode } from './ir/sql-schema-ir-node';
+export { assertNode, SqlSchemaIRNode } from './ir/sql-schema-ir-node';
 export { SqlTableIR, type SqlTableIRInput } from './ir/sql-table-ir';
 export { SqlUniqueIR, type SqlUniqueIRInput } from './ir/sql-unique-ir';