refactor(sql-authoring): authoring index types carry the disjoint element union; planning IDs leave names and comments

IndexNode and IndexConstraint express columns/fields xor expression as an
input-type union (no stored discriminant) and IndexNode's remaining
fields become required-but-undefined; construction sites pick the arm
from the data or defer the xor decision to lowerAuthoredIndex's runtime
guard via blindCast. Warning docs and test names describe the exact-name
body warning by behavior, and the index-drift suite names its cases by
what they exercise.

Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden-electric

packages/2-sql/1-core/contract/src/foreign-key-materialization.ts

@@ -96,6 +96,8 @@ export function materializeForeignKeysAndIndexes(
         synthesizedIndexes.push(
           lowerAuthoredIndex(tableName, {
             columns: reference.source.columns,
+            where: undefined,
+            unique: undefined,
             map: undefined,
             name: undefined,
             type: undefined,

packages/2-sql/1-core/contract/src/index-naming.ts

@@ -53,7 +53,7 @@ function formatExactNameBodyWarning(warning: ExactNameBodyWarning): string {
 }
 
 /**
- * Flushes collected D9 warnings once per contract build: per-item warnings
+ * Flushes collected exact-name-body warnings once per contract build: per-item warnings
  * (each naming its object) up to the threshold, one summary with the name
  * list above it — an adopted contract re-emit (which carries `map:` + body
  * for every adopted object once infer emits them) must not wall-of-text.

packages/2-sql/1-core/contract/test/index-naming.test.ts

@@ -1,11 +1,31 @@
 import { computeIndexContentHash } from '@prisma-next/sql-schema-ir/naming';
 import { describe, expect, it, vi } from 'vitest';
 import {
+  type AuthoredIndexInput,
   type ExactNameBodyWarning,
   flushExactNameBodyWarnings,
-  lowerAuthoredIndex,
+  lowerAuthoredIndex as lowerAuthoredIndexStrict,
 } from '../src/index-naming';
 
+type LooseAuthoredIndexInput = {
+  readonly columns?: readonly string[];
+  readonly expression?: string;
+  readonly where?: string;
+  readonly unique?: boolean;
+  readonly map?: string;
+  readonly name?: string;
+  readonly type?: string;
+  readonly options?: Record<string, unknown>;
+};
+
+function lowerAuthoredIndex(
+  tableName: string,
+  authored: LooseAuthoredIndexInput,
+  warnings?: { push(warning: ExactNameBodyWarning): void },
+) {
+  return lowerAuthoredIndexStrict(tableName, authored as AuthoredIndexInput, warnings);
+}
+
 function captureWarnings(run: () => void) {
   const emitWarning = vi.spyOn(process, 'emitWarning').mockImplementation(() => {});
   try {
@@ -177,7 +197,7 @@ describe('lowerAuthoredIndex — cross-field guards', () => {
   });
 });
 
-describe('lowerAuthoredIndex — D9 exact-name body warning collection', () => {
+describe('lowerAuthoredIndex — exact-name body warning collection', () => {
   it('pushes into a provided collector instead of emitting', () => {
     const collected: ExactNameBodyWarning[] = [];
     const warnings = captureWarnings(() => {
@@ -231,7 +251,7 @@ describe('flushExactNameBodyWarnings — threshold batching', () => {
   });
 });
 
-describe('lowerAuthoredIndex — D9 exact-name body warning', () => {
+describe('lowerAuthoredIndex — exact-name body warning', () => {
   const expectedMessage =
     'index "users_email_eq" uses map: with a SQL body. Drift detection compares the authored ' +
     "SQL text byte-for-byte against Postgres's reprinted form, which is only reliable when the " +
@@ -240,7 +260,7 @@ describe('lowerAuthoredIndex — D9 exact-name body warning', () => {
     'replace map: with name: (keeping the body text unchanged) and apply the resulting rename ' +
     'migration.';
 
-  it('fires for map + expression with the exact D9 wording and code', () => {
+  it('fires for map + expression with the pinned wording and code', () => {
     const warnings = captureWarnings(() => {
       lowerAuthoredIndex('user', { expression: 'lower(email)', map: 'users_email_eq' });
     });

packages/2-sql/2-authoring/contract-psl/src/interpreter.ts

@@ -1000,16 +1000,21 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
         }
         columnNames = mapped;
       }
-      indexNodes.push({
-        ...ifDefined('columns', columnNames),
-        ...ifDefined('expression', parsed.expression),
-        ...ifDefined('where', parsed.where),
-        ...ifDefined('unique', parsed.unique),
-        ...ifDefined('name', parsed.name),
-        ...ifDefined('map', parsed.map),
-        ...ifDefined('type', parsed.type),
-        ...ifDefined('options', parsed.options),
-      });
+      indexNodes.push(
+        // The interpreter's own diagnostics pre-empt the neither/both
+        // element cases; the cast defers final enforcement to
+        // lowerAuthoredIndex's runtime guard.
+        blindCast<IndexNode, 'columns-xor-expression enforced by lowerAuthoredIndex'>({
+          ...ifDefined('columns', columnNames),
+          ...ifDefined('expression', parsed.expression),
+          where: parsed.where,
+          unique: parsed.unique,
+          name: parsed.name,
+          map: parsed.map,
+          type: parsed.type,
+          options: parsed.options,
+        }),
+      );
       continue;
     }
     const contributedModelAttribute = input.modelAttributesByName.get(modelAttribute.name);

packages/2-sql/2-authoring/contract-psl/test/interpreter.index-naming.test.ts

@@ -139,7 +139,7 @@ describe('@@index matrix threading at PSL lowering', () => {
     });
   });
 
-  it('map with an expression lowers exact and draws the D9 warning', () => {
+  it('map with an expression lowers exact and draws the exact-name body warning', () => {
     const emitWarning = vi.spyOn(process, 'emitWarning').mockImplementation(() => {});
     try {
       const result = interpretMatrix(`model User {

packages/2-sql/2-authoring/contract-ts/src/build-contract.ts

@@ -685,8 +685,9 @@ export function buildSqlContractFromDefinition(
   );
 
   const tablesByNamespace: Record<string, Record<string, StorageTableInput>> = {};
-  // D9 warnings collect across the whole build and flush once (threshold-
-  // batched) — an adopted contract carries map: + body on many objects.
+  // Exact-name body warnings collect across the whole build and flush once
+  // (threshold-batched) — an adopted contract carries map: + body on many
+  // objects.
   const exactNameBodyWarnings: ExactNameBodyWarning[] = [];
   const modelNameToNamespaceId = new Map<string, string>();
   const executionDefaults: ExecutionMutationDefault[] = [];

packages/2-sql/2-authoring/contract-ts/src/contract-definition.ts

@@ -55,21 +55,30 @@ export interface UniqueConstraintNode {
   readonly name?: string;
 }
 
-export interface IndexNode {
-  /** Column tuple. Exactly one of `columns` / `expression` is set. */
-  readonly columns?: readonly string[];
-  /** Opaque SQL: the entire element list of CREATE INDEX — never parsed. */
-  readonly expression?: string;
+/** A definition-tree index's element structure — column tuple xor expression. */
+export type IndexNodeElements =
+  | {
+      /** Column tuple. */
+      readonly columns: readonly string[];
+      readonly expression?: never;
+    }
+  | {
+      readonly columns?: never;
+      /** Opaque SQL: the entire element list of CREATE INDEX — never parsed. */
+      readonly expression: string;
+    };
+
+export type IndexNode = IndexNodeElements & {
   /** Opaque SQL: partial-index predicate (WHERE body, without the keyword). */
-  readonly where?: string;
-  readonly unique?: boolean;
+  readonly where: string | undefined;
+  readonly unique: boolean | undefined;
   /** Exact physical name (`map:`) — adopted verbatim, no wire hash. */
-  readonly map?: string;
+  readonly map: string | undefined;
   /** Managed wire-name prefix (`name:`) — lowers to `<name>_<8hex>`. */
-  readonly name?: string;
-  readonly type?: string;
-  readonly options?: Record<string, unknown>;
-}
+  readonly name: string | undefined;
+  readonly type: string | undefined;
+  readonly options: Record<string, unknown> | undefined;
+};
 
 export interface ForeignKeyNode {
   readonly columns: readonly string[];

packages/2-sql/2-authoring/contract-ts/src/contract-dsl.ts

@@ -830,15 +830,24 @@ export type UniqueConstraint<FieldNames extends readonly string[] = readonly str
   readonly name?: string;
 };
 
+/** An authored index constraint's element structure — field tuple xor expression. */
+export type IndexConstraintElements<FieldNames extends readonly string[] = readonly string[]> =
+  | {
+      /** Field-name tuple. */
+      readonly fields: FieldNames;
+      readonly expression?: never;
+    }
+  | {
+      readonly fields?: never;
+      /** Opaque SQL: the entire CREATE INDEX element list — never parsed. */
+      readonly expression: string;
+    };
+
 export type IndexConstraint<
   FieldNames extends readonly string[] = readonly string[],
   Name extends string | undefined = string | undefined,
-> = {
+> = IndexConstraintElements<FieldNames> & {
   readonly kind: 'index';
-  /** Field-name tuple. Exactly one of `fields` / `expression` is set. */
-  readonly fields?: FieldNames;
-  /** Opaque SQL: the entire CREATE INDEX element list — never parsed. */
-  readonly expression?: string;
   readonly where?: string;
   readonly unique?: boolean;
   readonly name?: Name;
@@ -1034,18 +1043,18 @@ function createConstraintsDsl<IndexTypes extends IndexTypeMap = Record<never, ne
       typeof fieldsOrOptions === 'object' &&
       'expression' in fieldsOrOptions;
     const opts = isExpressionForm ? fieldsOrOptions : options;
-    return {
-      kind: 'index',
-      ...(isExpressionForm
-        ? { expression: fieldsOrOptions.expression }
-        : { fields: normalizeFieldRefInput(fieldsOrOptions) }),
+    const carried = {
+      kind: 'index' as const,
       ...(opts?.name !== undefined ? { name: opts.name } : {}),
       ...(opts?.map !== undefined ? { map: opts.map } : {}),
       ...(opts?.where !== undefined ? { where: opts.where } : {}),
       ...(opts?.unique !== undefined ? { unique: opts.unique } : {}),
       ...(opts?.type !== undefined ? { type: opts.type } : {}),
       ...(opts?.options !== undefined ? { options: opts.options as Record<string, unknown> } : {}),
     };
+    return isExpressionForm
+      ? { ...carried, expression: fieldsOrOptions.expression }
+      : { ...carried, fields: normalizeFieldRefInput(fieldsOrOptions) };
   }
 
   function foreignKey<

packages/2-sql/2-authoring/contract-ts/src/contract-lowering.ts

@@ -810,18 +810,26 @@ function resolveModelNode(
     columns: mapFieldNamesToColumnNames(spec.modelName, unique.fields, spec.fieldToColumn),
     ...(unique.name ? { name: unique.name } : {}),
   })) satisfies readonly UniqueConstraintNode[];
-  const indexes = (spec.sqlSpec?.indexes ?? []).map((index) => ({
-    ...(index.fields !== undefined
-      ? { columns: mapFieldNamesToColumnNames(spec.modelName, index.fields, spec.fieldToColumn) }
-      : {}),
-    ...ifDefined('expression', index.expression),
-    ...ifDefined('where', index.where),
-    ...ifDefined('unique', index.unique),
-    ...ifDefined('name', index.name),
-    ...ifDefined('map', index.map),
-    ...ifDefined('type', index.type),
-    ...ifDefined('options', index.options),
-  })) satisfies readonly IndexNode[];
+  const indexes = (spec.sqlSpec?.indexes ?? []).map((index): IndexNode => {
+    const carried = {
+      where: index.where,
+      unique: index.unique,
+      name: index.name,
+      map: index.map,
+      type: index.type,
+      options: index.options,
+    };
+    return index.expression !== undefined
+      ? { ...carried, expression: index.expression }
+      : {
+          ...carried,
+          columns: mapFieldNamesToColumnNames(
+            spec.modelName,
+            index.fields ?? [],
+            spec.fieldToColumn,
+          ),
+        };
+  });
   const foreignKeys = resolveForeignKeyNodes(spec, allSpecs, extensions);
   const relations = Object.entries(spec.relations).map(([relationName, relationBuilder]) =>
     resolveRelationNode(relationName, relationBuilder.build(), spec, allSpecs, extensions),

packages/2-sql/2-authoring/contract-ts/test/contract-builder.index-naming.test.ts

@@ -256,7 +256,7 @@ describe('constraints.index — full matrix', () => {
     ]);
   });
 
-  it('map with an expression lowers exact and draws the D9 warning', () => {
+  it('map with an expression lowers exact and draws the exact-name body warning', () => {
     const emitWarning = vi.spyOn(process, 'emitWarning').mockImplementation(() => {});
     try {
       const contract = defineTestContract({