@prisma-next/family-sql 0.11.0 → 0.12.0-dev.10

package/src/core/ir/sql-contract-serializer-base.ts

@@ -1,11 +1,19 @@
 import { ContractValidationError } from '@prisma-next/contract/contract-validation-error';
 import type { Contract } from '@prisma-next/contract/types';
 import type { ContractSerializer } from '@prisma-next/framework-components/control';
-import { type Namespace, NamespaceBase } from '@prisma-next/framework-components/ir';
 import {
+  type Namespace,
+  NamespaceBase,
+  UNBOUND_NAMESPACE_ID,
+} from '@prisma-next/framework-components/ir';
+import { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';
+import {
+  buildSqlNamespace,
   type SqlNamespaceTablesInput,
   SqlStorage,
+  type SqlStorageInput,
   type SqlStorageTypeEntry,
+  SqlUnboundNamespace,
   StorageTable,
   type StorageTableInput,
 } from '@prisma-next/sql-contract/types';
@@ -13,12 +21,17 @@ import {
   createSqlContractSchema,
   validateSqlContractFully,
 } from '@prisma-next/sql-contract/validators';
+import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
 import { type Type, type } from 'arktype';
 
 const NamespaceRawSchema = type({
   id: 'string',
   'kind?': 'string',
+  // Undeclared keys (`tables`, `enum`, and any pack-contributed slot maps)
+  // intentionally pass through; the slot loop below iterates them by name.
+  '+': 'ignore',
 });
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
@@ -79,6 +92,10 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     return contract as unknown as JsonObject;
   }
 
+  shouldPreserveEmpty = sqlContractCanonicalizationHooks.shouldPreserveEmpty;
+
+  sortStorage = sqlContractCanonicalizationHooks.sortStorage;
+
   protected parseSqlContractStructure(json: unknown): Contract<SqlStorage> {
     return validateSqlContractFully<Contract<SqlStorage>>(
       json,
@@ -99,27 +116,51 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
         : undefined;
 
     const rawNamespaces = validated.storage.namespaces;
-    const hydratedNamespaces =
-      rawNamespaces !== undefined ? this.hydrateSqlNamespaceMap(rawNamespaces) : undefined;
+    if (rawNamespaces === undefined) {
+      throw new ContractValidationError(
+        'Contract storage.namespaces is required after structural validation',
+        'structural',
+      );
+    }
+    const hydratedNamespaces = this.hydrateSqlNamespaceMap(rawNamespaces);
+    // Compatibility shim: production code that addresses `__unbound__` for table
+    // metadata lookups (collection-contract, query-plan-mutations, model-accessor,
+    // query-plan-meta, where-binding) uses optional chaining and tolerates absence,
+    // but runtime-qualification (TML-2605) has not yet landed cross-namespace table
+    // routing. Injecting the empty singleton here keeps helpers that augment the
+    // deserialized JSON (e.g. buildMixedPolyContract) working by providing a slot to
+    // write into. Once runtime-qualification routes table lookups by namespace, this
+    // shim should be removed.
+    const unbound = hydratedNamespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance;
 
     return {
       ...validated,
       storage: new SqlStorage({
         storageHash: validated.storage.storageHash,
-        ...(hydratedTypes !== undefined ? { types: hydratedTypes } : {}),
-        ...(hydratedNamespaces !== undefined ? { namespaces: hydratedNamespaces } : {}),
+        ...ifDefined('types', hydratedTypes),
+        // Cast narrows the result of hydrateSqlNamespaceMap from the wider
+        // framework `Namespace` to the SQL-family `SqlNamespace`.
+        namespaces: blindCast<
+          SqlStorageInput['namespaces'],
+          'hydrated SQL namespaces are SqlNamespace instances (family hydration guarantees this)'
+        >({ ...hydratedNamespaces, [UNBOUND_NAMESPACE_ID]: unbound }),
       }),
     };
   }
 
   protected hydrateSqlNamespaceMap(
     namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,
-  ): Readonly<Record<string, Namespace | SqlNamespaceTablesInput>> {
+  ): Readonly<Record<string, Namespace>> {
     return Object.fromEntries(
-      Object.entries(namespaces).map(([nsId, raw]) => [
-        nsId,
-        this.hydrateSqlNamespaceEntry(nsId, raw),
-      ]),
+      Object.entries(namespaces).map(([nsId, namespaceEntryRaw]) => {
+        // Raw entries passed structural validation; hydrate materialises family IR class instances.
+        const namespaceHydrated = this.hydrateSqlNamespaceEntry(nsId, namespaceEntryRaw);
+        const namespaceMaterialised =
+          namespaceHydrated instanceof NamespaceBase
+            ? namespaceHydrated
+            : buildSqlNamespace(namespaceHydrated);
+        return [nsId, namespaceMaterialised];
+      }),
     );
   }
 
@@ -173,34 +214,27 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
       }
     }
 
-    const typesRaw = rawRecord['types'];
-    const hasUnhydratedPostgresEnumEntry =
-      typesRaw !== undefined &&
-      typeof typesRaw === 'object' &&
-      typesRaw !== null &&
-      Object.values(typesRaw as Record<string, unknown>).some(
-        (entry) =>
-          typeof entry === 'object' &&
-          entry !== null &&
-          (entry as { kind?: unknown }).kind === 'postgres-enum',
-      );
-    if (
-      hasUnhydratedPostgresEnumEntry &&
-      this.entityTypeRegistry.get('postgres-enum') === undefined
-    ) {
-      throw new ContractValidationError(
-        'Per-schema database types (e.g. postgres-enum) under storage.namespaces[..].types require PostgresContractSerializer.',
-        'structural',
-      );
+    const enumRaw = rawRecord['enum'];
+    if (enumRaw !== undefined && typeof enumRaw === 'object' && enumRaw !== null) {
+      for (const entry of Object.values(enumRaw as Record<string, unknown>)) {
+        if (typeof entry !== 'object' || entry === null) continue;
+        const kind = (entry as { kind?: unknown }).kind;
+        if (typeof kind === 'string' && this.entityTypeRegistry.get(kind) === undefined) {
+          throw new ContractValidationError(
+            `Entry kind '${kind}' has no registered hydration factory.`,
+            'structural',
+          );
+        }
+      }
     }
 
     const tables = (result['tables'] ?? {}) as Record<string, StorageTable>;
-    const types = result['types'] as NonNullable<SqlNamespaceTablesInput['types']> | undefined;
+    const enumSlot = result['enum'] as NonNullable<SqlNamespaceTablesInput['enum']> | undefined;
     return {
-      id,
+      ...result,
       tables,
-      ...(types !== undefined ? { types } : {}),
-    };
+      ...(enumSlot !== undefined ? { enum: enumSlot } : {}),
+    } as SqlNamespaceTablesInput;
   }
 
   protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {

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

@@ -1,5 +1,6 @@
 import type { ColumnDefault, Contract } from '@prisma-next/contract/types';
 import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import {
   type ForeignKey,
   type Index,
@@ -52,6 +53,26 @@ export type NativeTypeExpander = (input: {
  */
 export type DefaultRenderer = (def: ColumnDefault, column: StorageColumn) => string;
 
+/**
+ * Target-supplied callback that computes the schema-qualified annotation-map
+ * key for a namespace-scoped enum storage type.
+ *
+ * Enum lookups (`readExistingEnumValues`) are namespace/schema-qualified so two
+ * namespaces holding an enum with the same TypeScript name (and even the same
+ * native type) resolve to distinct live-database types. The *format* of that
+ * key — and the namespace → DDL-schema resolution it depends on — is a
+ * target-specific concern (Postgres schemas; SQLite/MySQL differ), so the
+ * target injects it here as data rather than the family layer importing a
+ * concrete `ddlSchemaName`/key implementation. This keeps the family layer
+ * target-agnostic (no `@prisma-next/target-*` dependency) while the projection
+ * still emits keys that match the target's read side exactly.
+ */
+export type EnumStorageKeyResolver = (
+  storage: SqlStorage,
+  namespaceId: string,
+  nativeType: string,
+) => string;
+
 function convertColumn(
   name: string,
   column: StorageColumn,
@@ -152,6 +173,8 @@ function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
     referencedSchema: fk.target.namespaceId,
     referencedColumns: fk.target.columns,
     ...ifDefined('name', fk.name),
+    ...ifDefined('onDelete', fk.onDelete),
+    ...ifDefined('onUpdate', fk.onUpdate),
   };
 }
 
@@ -263,6 +286,14 @@ export interface ContractToSchemaIROptions {
   readonly annotationNamespace: string;
   readonly expandNativeType?: NativeTypeExpander;
   readonly renderDefault?: DefaultRenderer;
+  /**
+   * Target-supplied resolver for namespace/schema-qualified enum annotation
+   * keys. When provided (Postgres), every namespace-scoped enum is keyed by the
+   * resolver's output so the projected `storageTypes` map matches the target's
+   * `readExistingEnumValues` lookup. Targets without namespace-qualified enum
+   * storage (SQLite) omit it; enums are absent there.
+   */
+  readonly resolveEnumStorageKey?: EnumStorageKeyResolver;
 }
 
 /**
@@ -296,9 +327,9 @@ export function contractToSchemaIR(
     ...((storage.types ?? {}) as ResolvedStorageTypes),
   };
   for (const ns of Object.values(storage.namespaces)) {
-    const nsTypes = (ns as { types?: Record<string, PostgresEnumStorageEntry> }).types;
-    if (nsTypes) {
-      for (const [k, v] of Object.entries(nsTypes)) {
+    const nsEnums = (ns as { enum?: Record<string, PostgresEnumStorageEntry> }).enum;
+    if (nsEnums) {
+      for (const [k, v] of Object.entries(nsEnums)) {
         allTypes[k] = v;
       }
     }
@@ -328,7 +359,11 @@ export function contractToSchemaIR(
     }
   }
 
-  const annotations = deriveAnnotations(storage, options.annotationNamespace);
+  const annotations = deriveAnnotations(
+    storage,
+    options.annotationNamespace,
+    options.resolveEnumStorageKey,
+  );
 
   return {
     tables,
@@ -336,47 +371,61 @@ export function contractToSchemaIR(
   };
 }
 
+/**
+ * Normalises a native enum storage entry to the codec-typed annotation shape
+ * `{codecId, nativeType, typeParams}` the introspector writes and
+ * `readExistingEnumValues` reads (`existing.codecId` + `existing.typeParams.values`).
+ * Without this the projector would emit the raw `PostgresEnumStorageEntry`
+ * shape (top-level `values`, no `typeParams`) and the enum would read as new.
+ */
+function normalizeEnumAnnotation(entry: PostgresEnumStorageEntry): StorageTypeInstance {
+  return toStorageTypeInstance({
+    codecId: entry.codecId,
+    nativeType: entry.nativeType,
+    typeParams: { values: entry.values },
+  });
+}
+
 function deriveAnnotations(
   storage: SqlStorage,
   annotationNamespace: string,
+  resolveEnumStorageKey: EnumStorageKeyResolver | undefined,
 ): SqlAnnotations | undefined {
-  const allTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = {
-    ...((storage.types ?? {}) as ResolvedStorageTypes),
-  };
-  for (const ns of Object.values(storage.namespaces)) {
-    const nsTypes = (ns as { types?: Record<string, PostgresEnumStorageEntry> }).types;
-    if (nsTypes) {
-      for (const [k, v] of Object.entries(nsTypes)) {
-        allTypes[k] = v;
-      }
-    }
-  }
-  const types = allTypes as ResolvedStorageTypes;
-  if (Object.keys(types).length === 0) return undefined;
-  // Re-key by nativeType, normalising every variant to the codec-typed
-  // annotation shape `{codecId, nativeType, typeParams}` produced by the
-  // adapter introspector (`introspectPostgresEnumTypes` writes that shape;
-  // see also `enum-planning.ts § readExistingEnumValues`, which reads
-  // `existing.codecId` + `existing.typeParams.values`). Without this
-  // normalisation, the projector would emit the raw
-  // `PostgresEnumStorageEntry` shape (top-level `values`, no `typeParams`)
-  // and downstream Schema IR consumers that walk the codec-typed shape
-  // would see enum entries as new (e.g. the planner emits a fresh
-  // `CreateEnumTypeCall` instead of the rebuild recipe). Unknown future
-  // kinds without `nativeType` are skipped rather than crashing.
-  const byNativeType: Record<string, StorageTypeInstance> = {};
-  for (const typeInstance of Object.values(types)) {
+  const storageTypes: Record<string, StorageTypeInstance> = {};
+
+  // Top-level `storage.types`: codec-typed entries (vector, decimal, …) keyed
+  // by bare `nativeType` (unchanged). Post-S1.B enums live in
+  // `namespaces[*].enum`, not here; a defensive top-level enum is still
+  // namespace/schema-qualified via the resolver under the unbound coordinate
+  // so it never collides on a bare name.
+  for (const typeInstance of Object.values((storage.types ?? {}) as ResolvedStorageTypes)) {
     if (isPostgresEnumStorageEntry(typeInstance)) {
-      byNativeType[typeInstance.nativeType] = toStorageTypeInstance({
-        codecId: typeInstance.codecId,
-        nativeType: typeInstance.nativeType,
-        typeParams: { values: typeInstance.values },
-      });
+      const key = resolveEnumStorageKey
+        ? resolveEnumStorageKey(storage, UNBOUND_NAMESPACE_ID, typeInstance.nativeType)
+        : typeInstance.nativeType;
+      storageTypes[key] = normalizeEnumAnnotation(typeInstance);
       continue;
     }
     if (isStorageTypeInstance(typeInstance)) {
-      byNativeType[typeInstance.nativeType] = typeInstance;
+      storageTypes[typeInstance.nativeType] = typeInstance;
     }
   }
-  return { [annotationNamespace]: { storageTypes: byNativeType } };
+
+  // Namespace-scoped enums: schema-qualified compound key matching the target's
+  // `readExistingEnumValues` read side, so two namespaces sharing an enum name
+  // (or native type) resolve to distinct live-database types.
+  for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
+    const nsEnums = (ns as { enum?: Record<string, PostgresEnumStorageEntry> }).enum;
+    if (!nsEnums) continue;
+    for (const entry of Object.values(nsEnums)) {
+      if (!isPostgresEnumStorageEntry(entry)) continue;
+      const key = resolveEnumStorageKey
+        ? resolveEnumStorageKey(storage, namespaceId, entry.nativeType)
+        : entry.nativeType;
+      storageTypes[key] = normalizeEnumAnnotation(entry);
+    }
+  }
+
+  if (Object.keys(storageTypes).length === 0) return undefined;
+  return { [annotationNamespace]: { storageTypes } };
 }

package/src/core/migrations/types.ts

@@ -15,12 +15,14 @@ import type {
   MigrationPlanOperation,
   MigrationRunnerExecutionChecks,
   MigrationRunnerFailure,
-  MigrationRunnerSuccessValue,
+  MigrationRunnerPerSpaceSuccessValue,
+  MigrationRunnerResult,
   OperationContext,
   OpFactoryCall,
   SchemaIssue,
   SchemaVerifier,
 } from '@prisma-next/framework-components/control';
+import type { AggregateMigrationEdgeRef } from '@prisma-next/migration-tools/aggregate';
 import type {
   SqlStorage,
   StorageColumn,
@@ -30,6 +32,7 @@ import type {
 import type { SqlOperationDescriptors } from '@prisma-next/sql-operations';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
+import type { SqlControlAdapter } from '../control-adapter';
 import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
@@ -173,7 +176,7 @@ export interface SqlControlExtensionDescriptor<TTargetId extends string>
 }
 
 export interface SqlControlAdapterDescriptor<TTargetId extends string>
-  extends ControlAdapterDescriptor<'sql', TTargetId> {
+  extends ControlAdapterDescriptor<'sql', TTargetId, SqlControlAdapter<TTargetId>> {
   readonly queryOperations?: () => SqlOperationDescriptors;
 }
 
@@ -234,7 +237,7 @@ export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
    * pass the extension's space id. Required at every call site so the
    * type system surfaces every place that needs to thread the value
    * (rather than letting an `?? APP_SPACE_ID` fall-through silently
-   * collapse multi-space markers onto the `'app'` row).
+   * collapse per-space markers onto the `'app'` row).
    *
    * @see specs/framework-mechanism.spec.md § 2.
    */
@@ -383,6 +386,11 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
    * All components must have matching familyId ('sql') and targetId.
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  /**
+   * Per-edge breakdown from graph-walk planning. When present, the runner
+   * writes one ledger row per edge instead of one collapsed row per apply.
+   */
+  readonly migrationEdges: readonly AggregateMigrationEdgeRef[];
 }
 
 export type SqlMigrationRunnerErrorCode =
@@ -401,7 +409,7 @@ export interface SqlMigrationRunnerFailure extends MigrationRunnerFailure {
   readonly meta?: AnyRecord;
 }
 
-export interface SqlMigrationRunnerSuccessValue extends MigrationRunnerSuccessValue {}
+export interface SqlMigrationRunnerSuccessValue extends MigrationRunnerPerSpaceSuccessValue {}
 
 export type SqlMigrationRunnerResult = Result<
   SqlMigrationRunnerSuccessValue,
@@ -410,22 +418,29 @@ export type SqlMigrationRunnerResult = Result<
 
 export interface SqlMigrationRunner<TTargetDetails> {
   /**
-   * Apply a single migration plan, opening and managing its own
-   * transaction (and any target-specific connection-level setup, e.g.
-   * SQLite's `PRAGMA foreign_keys` toggle). Existing single-space
-   * callers route through here.
+   * Apply one or more per-space migration plans, opening and managing the
+   * outer transaction (and any target-specific connection-level setup, e.g.
+   * SQLite's `PRAGMA foreign_keys` toggle). An apply that targets one space
+   * passes a one-element `perSpaceOptions` list.
+   *
+   * The caller orders the input list (typically via the aggregate planner's
+   * `applyOrder`: extensions alphabetical, then app). A failure on any space
+   * rolls back every space's writes.
+   *
+   * Each entry must reference the same `driver` as the top-level `driver`
+   * (the connection the outer transaction is open on).
    */
-  execute(
-    options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
-  ): Promise<SqlMigrationRunnerResult>;
+  execute(options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly perSpaceOptions: ReadonlyArray<SqlMigrationRunnerExecuteOptions<TTargetDetails>>;
+  }): Promise<MigrationRunnerResult>;
 
   /**
    * Apply a single migration plan against an already-open connection
    * **without** opening a transaction. The caller is responsible for
    * wrapping the call (and any siblings) in `BEGIN` / `COMMIT` /
-   * `ROLLBACK`. Used by the per-space runner wiring to fan out across
-   * contract spaces inside one outer transaction so a mid-apply
-   * failure rolls back every space's writes.
+   * `ROLLBACK`. Used by {@link SqlMigrationRunner.execute} to fan out
+   * across contract spaces inside one outer transaction.
    *
    * Idempotent control-table setup (`prisma_contract.*`) and marker
    * writes use `options.space` to address the per-space marker row.
@@ -433,40 +448,8 @@ export interface SqlMigrationRunner<TTargetDetails> {
   executeOnConnection(
     options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
   ): Promise<SqlMigrationRunnerResult>;
-
-  /**
-   * Apply per-space plans across multiple contract spaces inside a
-   * single outer transaction. The caller orders the input list
-   * (typically via the aggregate planner's `applyOrder`: extensions
-   * alphabetical, then app); the runner is responsible for opening
-   * / committing the outer
-   * transaction (and any target-specific connection-level setup such
-   * as the SQLite FK pragma toggle). A failure on any space rolls
-   * back every space's writes.
-   *
-   * Each space's `SqlMigrationRunnerExecuteOptions` must reference the
-   * same `driver` (the connection the outer transaction is open on).
-   * Per-space marker writes use `options.space` to address the row.
-   */
-  executeAcrossSpaces(options: {
-    readonly driver: ControlDriverInstance<'sql', string>;
-    readonly perSpaceOptions: ReadonlyArray<SqlMigrationRunnerExecuteOptions<TTargetDetails>>;
-  }): Promise<MultiSpaceRunnerResult>;
 }
 
-export interface MultiSpaceRunnerSuccessValue {
-  readonly perSpaceResults: ReadonlyArray<{
-    readonly space: string;
-    readonly value: SqlMigrationRunnerSuccessValue;
-  }>;
-}
-
-export interface MultiSpaceRunnerFailure extends SqlMigrationRunnerFailure {
-  readonly failingSpace: string;
-}
-
-export type MultiSpaceRunnerResult = Result<MultiSpaceRunnerSuccessValue, MultiSpaceRunnerFailure>;
-
 export interface SqlControlTargetDescriptor<
   TTargetId extends string,
   TTargetDetails,