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

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,7 +15,8 @@ import type {
   MigrationPlanOperation,
   MigrationRunnerExecutionChecks,
   MigrationRunnerFailure,
-  MigrationRunnerSuccessValue,
+  MigrationRunnerPerSpaceSuccessValue,
+  MigrationRunnerResult,
   OperationContext,
   OpFactoryCall,
   SchemaIssue,
@@ -234,7 +235,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.
    */
@@ -401,7 +402,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 +411,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 +441,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,

package/src/core/schema-verify/verify-sql-schema.ts

@@ -14,6 +14,7 @@ import type {
   SchemaVerificationNode,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import {
   isPostgresEnumStorageEntry,
   isStorageTypeInstance,
@@ -98,6 +99,7 @@ export interface VerifySqlSchemaOptions {
   readonly resolveExistingEnumValues?: (
     schema: SqlSchemaIR,
     enumType: PostgresEnumStorageEntry,
+    namespaceId: string,
   ) => readonly string[] | null;
 }
 
@@ -129,6 +131,8 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
 
   const { contractStorageHash, contractProfileHash, contractTarget } =
     extractContractMetadata(contract);
+  // Column `typeRef` resolution map: keyed by the bare contract type name
+  // (columns carry bare `typeRef`s). Used by `verifySchemaTables` only.
   const allStorageTypesMap: Record<string, PostgresEnumStorageEntry | StorageTypeInstance> = {
     ...((contract.storage.types ?? {}) as Record<
       string,
@@ -136,9 +140,9 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     >),
   };
   for (const ns of Object.values(contract.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)) {
         allStorageTypesMap[k] = v;
       }
     }
@@ -159,48 +163,86 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
 
   validateFrameworkComponentsForExtensions(contract, options.frameworkComponents);
 
-  // Verify storage type instances. PostgresEnumStorageEntry entries are walked
-  // natively (using the bridging adapter `resolveExistingEnumValues`);
-  // remaining codec-typed entries continue to dispatch through the
-  // generic codec-hook `verifyType` path.
-  const storageTypeEntries = Object.entries(storageTypes);
-  if (storageTypeEntries.length > 0) {
-    const typeNodes: SchemaVerificationNode[] = [];
-    for (const [typeName, typeInstance] of storageTypeEntries) {
-      let typeIssues: readonly SchemaIssue[];
-      if (isPostgresEnumStorageEntry(typeInstance)) {
-        typeIssues = verifyEnumType({
+  // Verify storage type instances. Codec-typed `storage.types` entries dispatch
+  // through the generic codec-hook `verifyType` path (keyed by bare name).
+  // `PostgresEnumStorageEntry` enums are walked natively *per namespace* (using
+  // the bridging adapter `resolveExistingEnumValues`) so two namespaces that
+  // declare an enum with the same name are each verified with their own
+  // namespace coordinate — a bare-name aggregation would collapse them
+  // (last-write-wins) and verify only one.
+  const typeNodes: SchemaVerificationNode[] = [];
+  const pushTypeNode = (
+    typeName: string,
+    contractPath: string,
+    typeIssues: readonly SchemaIssue[],
+  ): void => {
+    if (typeIssues.length > 0) {
+      issues.push(...typeIssues);
+    }
+    typeNodes.push({
+      status: typeIssues.length > 0 ? 'fail' : 'pass',
+      kind: 'storageType',
+      name: `type ${typeName}`,
+      contractPath,
+      code: typeIssues.length > 0 ? (typeIssues[0]?.kind ?? '') : '',
+      message:
+        typeIssues.length > 0
+          ? `${typeIssues.length} issue${typeIssues.length === 1 ? '' : 's'}`
+          : '',
+      expected: undefined,
+      actual: undefined,
+      children: [],
+    });
+  };
+
+  // Top-level `storage.types`: codec-typed entries via codec hooks; a
+  // defensive top-level enum is verified under the unbound coordinate.
+  for (const [typeName, typeInstance] of Object.entries(contract.storage.types ?? {})) {
+    if (isPostgresEnumStorageEntry(typeInstance)) {
+      pushTypeNode(
+        typeName,
+        `storage.types.${typeName}`,
+        verifyEnumType({
           typeName,
           typeInstance,
           schema,
           resolveExistingEnumValues,
-        });
-      } else if (isStorageTypeInstance(typeInstance)) {
-        const hook = codecHooks.get(typeInstance.codecId);
-        typeIssues = hook?.verifyType ? hook.verifyType({ typeName, typeInstance, schema }) : [];
-      } else {
-        typeIssues = [];
-      }
-      if (typeIssues.length > 0) {
-        issues.push(...typeIssues);
-      }
-      const typeStatus = typeIssues.length > 0 ? 'fail' : 'pass';
-      const typeCode = typeIssues.length > 0 ? (typeIssues[0]?.kind ?? '') : '';
-      typeNodes.push({
-        status: typeStatus,
-        kind: 'storageType',
-        name: `type ${typeName}`,
-        contractPath: `storage.types.${typeName}`,
-        code: typeCode,
-        message:
-          typeIssues.length > 0
-            ? `${typeIssues.length} issue${typeIssues.length === 1 ? '' : 's'}`
-            : '',
-        expected: undefined,
-        actual: undefined,
-        children: [],
-      });
+          namespaceId: UNBOUND_NAMESPACE_ID,
+        }),
+      );
+    } else if (isStorageTypeInstance(typeInstance)) {
+      const hook = codecHooks.get(typeInstance.codecId);
+      pushTypeNode(
+        typeName,
+        `storage.types.${typeName}`,
+        hook?.verifyType ? hook.verifyType({ typeName, typeInstance, schema }) : [],
+      );
     }
+  }
+
+  // Namespace-scoped enums, verified per `(namespaceId, typeName)`.
+  for (const nsId of Object.keys(contract.storage.namespaces)) {
+    const ns = contract.storage.namespaces[nsId];
+    if (!ns) continue;
+    const nsEnums = ns.enum;
+    if (!nsEnums) continue;
+    for (const [typeName, entry] of Object.entries(nsEnums)) {
+      if (!isPostgresEnumStorageEntry(entry)) continue;
+      pushTypeNode(
+        typeName,
+        `storage.namespaces.${nsId}.enum.${typeName}`,
+        verifyEnumType({
+          typeName,
+          typeInstance: entry,
+          schema,
+          resolveExistingEnumValues,
+          namespaceId: nsId,
+        }),
+      );
+    }
+  }
+
+  if (typeNodes.length > 0) {
     const typesStatus = typeNodes.some((n) => n.status === 'fail') ? 'fail' : 'pass';
     rootChildren.push({
       status: typesStatus,
@@ -275,18 +317,24 @@ function verifyEnumType(options: {
   readonly typeName: string;
   readonly typeInstance: PostgresEnumStorageEntry;
   readonly schema: SqlSchemaIR;
+  readonly namespaceId: string;
   readonly resolveExistingEnumValues?:
-    | ((schema: SqlSchemaIR, enumType: PostgresEnumStorageEntry) => readonly string[] | null)
+    | ((
+        schema: SqlSchemaIR,
+        enumType: PostgresEnumStorageEntry,
+        namespaceId: string,
+      ) => readonly string[] | null)
     | undefined;
 }): readonly SchemaIssue[] {
-  const { typeName, typeInstance, schema, resolveExistingEnumValues } = options;
+  const { typeName, typeInstance, schema, namespaceId, resolveExistingEnumValues } = options;
   const desired = typeInstance.values;
-  const existing = resolveExistingEnumValues?.(schema, typeInstance) ?? null;
+  const existing = resolveExistingEnumValues?.(schema, typeInstance, namespaceId) ?? null;
   if (!existing) {
     return [
       {
         kind: 'type_missing',
         typeName,
+        namespaceId,
         message: `Type "${typeName}" is missing from database`,
       },
     ];
@@ -305,6 +353,7 @@ function verifyEnumType(options: {
   return [
     {
       kind: 'enum_values_changed' as const,
+      namespaceId,
       typeName,
       addedValues,
       removedValues,

package/src/core/timestamp-now-generator.ts

@@ -45,6 +45,7 @@ export function timestampNowControlDescriptor(): MutationDefaultGeneratorDescrip
  * `field.temporal.updatedAt()` lower to byte-identical contracts across
  * targets by construction.
  */
+/* @__NO_SIDE_EFFECTS__ */
 export function temporalAuthoringPresets<
   const CodecId extends string,
   const NativeType extends string,

package/src/exports/control.ts

@@ -17,6 +17,7 @@ export type { SqlControlFamilyInstance } from '../core/control-instance';
 export type {
   ContractToSchemaIROptions,
   DefaultRenderer,
+  EnumStorageKeyResolver,
   NativeTypeExpander,
 } from '../core/migrations/contract-to-schema-ir';
 // Contract → SchemaIR conversion for offline migration planning
@@ -40,9 +41,6 @@ export type {
   ExpandNativeTypeInput,
   FieldEvent,
   FieldEventContext,
-  MultiSpaceRunnerFailure,
-  MultiSpaceRunnerResult,
-  MultiSpaceRunnerSuccessValue,
   ResolveIdentityValueInput,
   SqlControlAdapterDescriptor,
   SqlControlExtensionDescriptor,