@prisma-next/sql-contract-ts 0.12.0-dev.9 → 0.13.0-dev.1

package/src/contract-lowering.ts

@@ -1,4 +1,5 @@
 import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
+import type { ExtensionPackRef } from '@prisma-next/framework-components/components';
 import {
   isPostgresEnumStorageEntry,
   type PostgresEnumStorageEntry,
@@ -35,6 +36,7 @@ import {
   emitTypedCrossModelFallbackWarnings,
   emitTypedNamedTypeFallbackWarnings,
 } from './contract-warnings';
+import { isEnumTypeHandle } from './enum-type';
 
 type RuntimeModel = ContractModelBuilder<
   string | undefined,
@@ -84,6 +86,13 @@ function resolveFieldDescriptor(
   }
 
   if ('typeRef' in fieldState && fieldState.typeRef) {
+    if (isEnumTypeHandle(fieldState.typeRef)) {
+      return {
+        codecId: fieldState.typeRef.codecId,
+        nativeType: fieldState.typeRef.nativeType,
+      };
+    }
+
     const typeRef =
       typeof fieldState.typeRef === 'string'
         ? fieldState.typeRef
@@ -253,6 +262,41 @@ function resolveRelationForeignKeys(
     }
 
     const targetModelName = resolveRelationModelName(relation.toModel);
+
+    // F-relfk: cross-space relations carry a spaceId; skip the local spec lookup
+    // and include cross-space coordinates so resolveForeignKeyNodes routes the FK
+    // through the cross-space path.
+    if (relation.spaceId !== undefined) {
+      const fields = normalizeRelationFieldNames(relation.from);
+      const targetFields = normalizeRelationFieldNames(relation.to);
+      assertRelationFieldArity({
+        modelName: spec.modelName,
+        relationName,
+        leftLabel: 'source',
+        leftFields: fields,
+        rightLabel: 'target',
+        rightFields: targetFields,
+      });
+
+      foreignKeys.push({
+        kind: 'fk',
+        fields,
+        targetModel: targetModelName,
+        targetFields,
+        targetSpaceId: relation.spaceId,
+        ...(relation.namespaceId !== undefined ? { targetNamespaceId: relation.namespaceId } : {}),
+        ...(relation.tableName !== undefined ? { targetTableName: relation.tableName } : {}),
+        ...(relation.sql.fk.name ? { name: relation.sql.fk.name } : {}),
+        ...(relation.sql.fk.onDelete ? { onDelete: relation.sql.fk.onDelete } : {}),
+        ...(relation.sql.fk.onUpdate ? { onUpdate: relation.sql.fk.onUpdate } : {}),
+        ...(relation.sql.fk.constraint !== undefined
+          ? { constraint: relation.sql.fk.constraint }
+          : {}),
+        ...(relation.sql.fk.index !== undefined ? { index: relation.sql.fk.index } : {}),
+      });
+      continue;
+    }
+
     if (!allSpecs.has(targetModelName)) {
       throw new Error(
         `Relation "${spec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
@@ -308,17 +352,12 @@ function lowerBelongsToRelation(
   relation: Extract<RelationState, { kind: 'belongsTo' }>,
   currentSpec: RuntimeModelSpec,
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
+  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
 ): RelationNode {
   const targetModelName = resolveRelationModelName(relation.toModel);
-  const targetSpec = allSpecs.get(targetModelName);
-  if (!targetSpec) {
-    throw new Error(
-      `Relation "${currentSpec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
-    );
-  }
-
   const fromFields = normalizeRelationFieldNames(relation.from);
   const toFields = normalizeRelationFieldNames(relation.to);
+
   assertRelationFieldArity({
     modelName: currentSpec.modelName,
     relationName,
@@ -328,6 +367,48 @@ function lowerBelongsToRelation(
     rightFields: toFields,
   });
 
+  // Cross-space path: the target lives in a different contract space.
+  // Resolve from the brand carried on the BelongsToRelation instead of
+  // requiring a local model spec — matching how the FK lowering works.
+  if (relation.spaceId !== undefined) {
+    assertKnownExtensionPack(
+      extensionPacks,
+      relation.spaceId,
+      `Relation "${currentSpec.modelName}.${relationName}"`,
+    );
+    const targetTable = relation.tableName ?? targetModelName.toLowerCase();
+    const parentColumns = mapFieldNamesToColumnNames(
+      currentSpec.modelName,
+      fromFields,
+      currentSpec.fieldToColumn,
+    );
+    // For cross-space relations, the `to` field names map directly to column
+    // names because we have no fieldToColumn map for the remote model.
+    // (The brand carries the table name; field→column resolution on the remote
+    // side is deferred to the planner which has access to the remote contract.)
+    return {
+      fieldName: relationName,
+      toModel: targetModelName,
+      toTable: targetTable,
+      cardinality: 'N:1',
+      spaceId: relation.spaceId,
+      ...(relation.namespaceId !== undefined ? { namespaceId: relation.namespaceId } : {}),
+      on: {
+        parentTable: currentSpec.tableName,
+        parentColumns,
+        childTable: targetTable,
+        childColumns: toFields,
+      },
+    };
+  }
+
+  const targetSpec = allSpecs.get(targetModelName);
+  if (!targetSpec) {
+    throw new Error(
+      `Relation "${currentSpec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
+    );
+  }
+
   return {
     fieldName: relationName,
     toModel: targetModelName,
@@ -472,9 +553,10 @@ function resolveRelationNode(
   relation: RelationState,
   currentSpec: RuntimeModelSpec,
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
+  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
 ): RelationNode {
   if (relation.kind === 'belongsTo') {
-    return lowerBelongsToRelation(relationName, relation, currentSpec, allSpecs);
+    return lowerBelongsToRelation(relationName, relation, currentSpec, allSpecs, extensionPacks);
   }
 
   if (relation.kind === 'hasMany' || relation.kind === 'hasOne') {
@@ -484,7 +566,7 @@ function resolveRelationNode(
   return lowerManyToManyRelation(relationName, relation, currentSpec, allSpecs);
 }
 
-function lowerForeignKeyNode(
+function lowerLocalForeignKeyNode(
   spec: RuntimeModelSpec,
   targetSpec: RuntimeModelSpec,
   foreignKey: {
@@ -516,11 +598,74 @@ function lowerForeignKeyNode(
   };
 }
 
+function lowerCrossSpaceForeignKeyNode(
+  spec: RuntimeModelSpec,
+  foreignKey: {
+    readonly fields: readonly string[];
+    readonly targetFields: readonly string[];
+    readonly targetModel: string;
+    readonly targetSpaceId: string;
+    readonly targetNamespaceId?: string;
+    readonly targetTableName?: string;
+    readonly name?: string | undefined;
+    readonly onDelete?: ForeignKeyConstraint['onDelete'] | undefined;
+    readonly onUpdate?: ForeignKeyConstraint['onUpdate'] | undefined;
+    readonly constraint?: boolean | undefined;
+    readonly index?: boolean | undefined;
+  },
+): ForeignKeyNode {
+  return {
+    columns: mapFieldNamesToColumnNames(spec.modelName, foreignKey.fields, spec.fieldToColumn),
+    references: {
+      model: foreignKey.targetModel,
+      table: foreignKey.targetTableName ?? foreignKey.targetModel.toLowerCase(),
+      columns: foreignKey.targetFields,
+      ...(foreignKey.targetNamespaceId !== undefined
+        ? { namespaceId: foreignKey.targetNamespaceId }
+        : {}),
+      spaceId: foreignKey.targetSpaceId,
+    },
+    ...(foreignKey.name ? { name: foreignKey.name } : {}),
+    ...(foreignKey.onDelete ? { onDelete: foreignKey.onDelete } : {}),
+    ...(foreignKey.onUpdate ? { onUpdate: foreignKey.onUpdate } : {}),
+    ...(foreignKey.constraint !== undefined ? { constraint: foreignKey.constraint } : {}),
+    ...(foreignKey.index !== undefined ? { index: foreignKey.index } : {}),
+  };
+}
+
+function assertKnownExtensionPack(
+  extensionPacks: Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  spaceId: string,
+  context: string,
+): void {
+  if (extensionPacks !== undefined && Object.hasOwn(extensionPacks, spaceId)) {
+    return;
+  }
+  throw new Error(
+    `${context} references contract space "${spaceId}" but "${spaceId}" is not declared in extensionPacks. Add the pack to extensionPacks.`,
+  );
+}
+
 function resolveForeignKeyNodes(
   spec: RuntimeModelSpec,
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
+  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
 ): readonly ForeignKeyNode[] {
   const relationForeignKeys = resolveRelationForeignKeys(spec, allSpecs).map((foreignKey) => {
+    // F-relfk: relation-derived FKs for cross-space targets carry targetSpaceId;
+    // route them through the cross-space path, just like explicit sql() FKs.
+    if (foreignKey.targetSpaceId !== undefined) {
+      assertKnownExtensionPack(
+        extensionPacks,
+        foreignKey.targetSpaceId,
+        `Relation-derived foreign key on "${spec.modelName}"`,
+      );
+      return lowerCrossSpaceForeignKeyNode(spec, {
+        ...foreignKey,
+        targetSpaceId: foreignKey.targetSpaceId,
+      });
+    }
+
     const targetSpec = allSpecs.get(foreignKey.targetModel);
     if (!targetSpec) {
       throw new Error(
@@ -528,10 +673,22 @@ function resolveForeignKeyNodes(
       );
     }
 
-    return lowerForeignKeyNode(spec, targetSpec, foreignKey);
+    return lowerLocalForeignKeyNode(spec, targetSpec, foreignKey);
   });
 
   const sqlForeignKeys = (spec.sqlSpec?.foreignKeys ?? []).map((foreignKey) => {
+    if (foreignKey.targetSpaceId !== undefined) {
+      assertKnownExtensionPack(
+        extensionPacks,
+        foreignKey.targetSpaceId,
+        `Foreign key on "${spec.modelName}"`,
+      );
+      return lowerCrossSpaceForeignKeyNode(spec, {
+        ...foreignKey,
+        targetSpaceId: foreignKey.targetSpaceId,
+      });
+    }
+
     const targetSpec = allSpecs.get(foreignKey.targetModel);
     if (!targetSpec) {
       throw new Error(
@@ -539,7 +696,7 @@ function resolveForeignKeyNodes(
       );
     }
 
-    return lowerForeignKeyNode(spec, targetSpec, foreignKey);
+    return lowerLocalForeignKeyNode(spec, targetSpec, foreignKey);
   });
 
   return [...relationForeignKeys, ...sqlForeignKeys];
@@ -550,6 +707,7 @@ function resolveModelNode(
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
   storageTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry>,
   storageTypeReverseLookup: ReadonlyMap<StorageTypeInstance | PostgresEnumStorageEntry, string>,
+  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
 ): ModelNode {
   const fields: FieldNode[] = [];
 
@@ -567,6 +725,11 @@ function resolveModelNode(
       throw new Error(`Column name resolution failed for "${spec.modelName}.${fieldName}"`);
     }
 
+    const enumHandle =
+      'typeRef' in fieldState && isEnumTypeHandle(fieldState.typeRef)
+        ? fieldState.typeRef
+        : undefined;
+
     fields.push({
       fieldName,
       columnName,
@@ -574,6 +737,7 @@ function resolveModelNode(
       nullable: fieldState.nullable,
       ...(fieldState.default ? { default: fieldState.default } : {}),
       ...(fieldState.executionDefaults ? { executionDefaults: fieldState.executionDefaults } : {}),
+      ...(enumHandle !== undefined ? { enumTypeHandle: enumHandle } : {}),
     });
   }
 
@@ -588,9 +752,9 @@ function resolveModelNode(
     ...ifDefined('type', index.type),
     ...ifDefined('options', index.options),
   })) satisfies readonly IndexNode[];
-  const foreignKeys = resolveForeignKeyNodes(spec, allSpecs);
+  const foreignKeys = resolveForeignKeyNodes(spec, allSpecs, extensionPacks);
   const relations = Object.entries(spec.relations).map(([relationName, relationBuilder]) =>
-    resolveRelationNode(relationName, relationBuilder.build(), spec, allSpecs),
+    resolveRelationNode(relationName, relationBuilder.build(), spec, allSpecs, extensionPacks),
   );
 
   return {
@@ -614,6 +778,7 @@ function resolveModelNode(
     ...(indexes.length > 0 ? { indexes } : {}),
     ...(foreignKeys.length > 0 ? { foreignKeys } : {}),
     ...(relations.length > 0 ? { relations } : {}),
+    ...ifDefined('control', spec.sqlSpec?.control),
   };
 }
 
@@ -687,7 +852,10 @@ function collectRuntimeModelSpecs(definition: ContractInput): RuntimeCollection
   };
 }
 
-function lowerModels(collection: RuntimeCollection): readonly ModelNode[] {
+function lowerModels(
+  collection: RuntimeCollection,
+  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+): readonly ModelNode[] {
   emitTypedCrossModelFallbackWarnings(collection);
 
   const storageTypeReverseLookup = buildStorageTypeReverseLookup(collection.storageTypes);
@@ -697,16 +865,18 @@ function lowerModels(collection: RuntimeCollection): readonly ModelNode[] {
       collection.modelSpecs,
       collection.storageTypes,
       storageTypeReverseLookup,
+      extensionPacks,
     ),
   );
 }
 
 export function buildContractDefinition(definition: ContractInput): ContractDefinition {
   const collection = collectRuntimeModelSpecs(definition);
-  const models = lowerModels(collection);
+  const models = lowerModels(collection, definition.extensionPacks);
 
   return {
     target: definition.target,
+    ...ifDefined('defaultControlPolicy', definition.defaultControlPolicy),
     ...(definition.extensionPacks ? { extensionPacks: definition.extensionPacks } : {}),
     ...(definition.storageHash ? { storageHash: definition.storageHash } : {}),
     ...(definition.foreignKeyDefaults ? { foreignKeyDefaults: definition.foreignKeyDefaults } : {}),
@@ -715,6 +885,9 @@ export function buildContractDefinition(definition: ContractInput): ContractDefi
       : {}),
     ...(definition.namespaces ? { namespaces: definition.namespaces } : {}),
     ...(definition.createNamespace ? { createNamespace: definition.createNamespace } : {}),
+    ...(definition.enums && Object.keys(definition.enums).length > 0
+      ? { enums: definition.enums }
+      : {}),
     models,
   };
 }

package/src/contract-types.ts

@@ -6,11 +6,11 @@ import type {
   StorageHashBase,
 } from '@prisma-next/contract/types';
 import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';
+import type { StorageType } from '@prisma-next/framework-components/ir';
 import type { IndexTypeRegistration } from '@prisma-next/sql-contract/index-types';
 import type {
   ContractWithTypeMaps,
   Index,
-  PostgresEnumStorageEntry,
   ReferentialAction,
   StorageTypeInstance,
   TypeMaps,
@@ -144,10 +144,7 @@ type DefinitionNamespaces<Definition> = Definition extends {
 type DefinitionTypes<Definition> = Definition extends {
   readonly types?: unknown;
 }
-  ? Present<Definition['types']> extends Record<
-      string,
-      StorageTypeInstance | PostgresEnumStorageEntry
-    >
+  ? Present<Definition['types']> extends Record<string, StorageType>
     ? Present<Definition['types']>
     : Record<never, never>
   : Record<never, never>;
@@ -311,10 +308,7 @@ type DescriptorTypeRef<Descriptor> = Descriptor extends {
   ? TypeRef
   : undefined;
 
-type LookupNamedStorageTypeKeyByValue<
-  Definition,
-  TypeRef extends StorageTypeInstance | PostgresEnumStorageEntry,
-> = {
+type LookupNamedStorageTypeKeyByValue<Definition, TypeRef extends StorageType> = {
   [TypeName in keyof DefinitionTypes<Definition> & string]: [TypeRef] extends [
     DefinitionTypes<Definition>[TypeName],
   ]
@@ -326,7 +320,7 @@ type LookupNamedStorageTypeKeyByValue<
 
 type ResolveNamedStorageTypeKey<Definition, TypeRef> = TypeRef extends string
   ? TypeRef
-  : TypeRef extends StorageTypeInstance | PostgresEnumStorageEntry
+  : TypeRef extends StorageType
     ? [LookupNamedStorageTypeKeyByValue<Definition, TypeRef>] extends [never]
       ? string
       : LookupNamedStorageTypeKeyByValue<Definition, TypeRef>
@@ -540,6 +534,7 @@ type BuiltStorageTables<Definition> = {
       };
       readonly target: {
         readonly namespaceId: NamespaceId;
+        readonly spaceId?: string;
         readonly tableName: string;
         readonly columns: readonly string[];
       };
@@ -564,9 +559,9 @@ type BuiltStorageTables<Definition> = {
 };
 
 type BuiltDocumentScopedTypes<Definition> = {
-  readonly [K in keyof DefinitionTypes<Definition> as DefinitionTypes<Definition>[K] extends PostgresEnumStorageEntry
-    ? never
-    : K]: DefinitionTypes<Definition>[K];
+  readonly [K in keyof DefinitionTypes<Definition> as DefinitionTypes<Definition>[K] extends StorageTypeInstance
+    ? K
+    : never]: DefinitionTypes<Definition>[K];
 };
 
 type BuiltDomain<Definition> =
@@ -586,19 +581,20 @@ type BuiltStorage<Definition> = {
   readonly types?: BuiltDocumentScopedTypes<Definition>;
   // The primary namespace key is target-specific: Postgres uses `public` (the
   // default schema), all other SQL targets use `__unbound__`. The namespace
-  // carries the narrowed tables shape so downstream DSL surfaces keep
+  // carries the narrowed `entries.table` shape so downstream DSL surfaces keep
   // literal-keyed access without an optional-narrowing dance. The shape is
   // described inline (rather than intersecting with `SqlStorage['namespaces']`)
   // so its `Readonly<Record<string, Namespace>>` index signature doesn't
-  // collapse `keyof tables` to `string`. The literal object is still
-  // structurally assignable to `SqlStorage['namespaces']` because every value
-  // satisfies the framework `Namespace` interface.
+  // collapse slot keys to `string`. The literal object is still structurally
+  // assignable to `SqlStorage['namespaces']` because every value satisfies the
+  // framework `Namespace` interface.
   readonly namespaces: {
     readonly [K in DefaultStorageNamespaceId<Definition>]: {
       readonly id: K;
       readonly kind: string;
-      readonly tables: BuiltStorageTables<Definition>;
-      readonly enum?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+      readonly entries: {
+        readonly table: BuiltStorageTables<Definition>;
+      };
     };
   } & {
     readonly [Ns in Exclude<
@@ -607,8 +603,9 @@ type BuiltStorage<Definition> = {
     >]: {
       readonly id: Ns;
       readonly kind: string;
-      readonly tables: Record<never, never>;
-      readonly enum?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+      readonly entries: {
+        readonly table: Record<never, never>;
+      };
     };
   };
 };

package/src/enum-type.ts

@@ -0,0 +1,236 @@
+import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
+import { blindCast } from '@prisma-next/utils/casts';
+
+// ---------------------------------------------------------------------------
+// EnumMember — a single member declaration with literal type preservation
+// ---------------------------------------------------------------------------
+
+/**
+ * A single enum member produced by `member()`. The `Name` and `Value` generics
+ * are preserved as literal types so `enumType()` can carry the ordered value
+ * tuple in its return type.
+ */
+export interface EnumMember<Name extends string, Value extends string> {
+  readonly name: Name;
+  readonly value: Value;
+}
+
+/**
+ * Declare an enum member. The `value` defaults to `name` when omitted.
+ * Both generics are preserved as literals so downstream `enumType` can
+ * carry the ordered value tuple in its type.
+ */
+export function member<const Name extends string>(name: Name): EnumMember<Name, Name>;
+export function member<const Name extends string, const Value extends string>(
+  name: Name,
+  value: Value,
+): EnumMember<Name, Value>;
+export function member<const Name extends string, const Value extends string = Name>(
+  name: Name,
+  value?: Value,
+): EnumMember<Name, Value> {
+  return {
+    name,
+    value: blindCast<
+      Value,
+      'overload signatures enforce Value=Name when value is omitted; default generic Value=Name makes this safe'
+    >(value ?? name),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal types for inferring the literal tuple from the members spread
+// ---------------------------------------------------------------------------
+
+type MembersToValues<Members extends readonly EnumMember<string, string>[]> = {
+  readonly [K in keyof Members]: Members[K] extends EnumMember<string, infer V> ? V : never;
+};
+
+type MembersToNames<Members extends readonly EnumMember<string, string>[]> = {
+  readonly [K in keyof Members]: Members[K] extends EnumMember<infer N, string> ? N : never;
+};
+
+type MembersAccessorMap<Members extends readonly EnumMember<string, string>[]> = {
+  readonly [M in Members[number] as M['name']]: M['value'];
+};
+
+// ---------------------------------------------------------------------------
+// EnumTypeHandle — the authoring handle returned by enumType()
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal brand that identifies an EnumTypeHandle in the lowering pipeline.
+ * Not exported — callers only interact with `EnumTypeHandle`.
+ */
+export const ENUM_TYPE_HANDLE_BRAND = Symbol('EnumTypeHandle');
+
+/**
+ * Authoring handle returned by `enumType()`. Carries:
+ *
+ * - The ordered literal value tuple (`.values`) and name tuple (`.names`)
+ *   so downstream type-tests can assert literal preservation.
+ * - A namespaced member accessor map (`.members`) to avoid collisions with
+ *   `.values` / `.has` / `.nameOf` / `.ordinalOf`.
+ * - Runtime helpers `.has()`, `.nameOf()`, `.ordinalOf()`.
+ * - Internal metadata (`enumName`, `codecId`, `nativeType`,
+ *   `enumMembers`) for the lowering pipeline.
+ *
+ * The type is generic over the ordered value tuple so callers that assign
+ * `const Role = enumType(...)` retain the literal tuple on `.values`.
+ */
+export interface EnumTypeHandle<
+  Name extends string = string,
+  Values extends readonly string[] = readonly string[],
+  Names extends readonly string[] = readonly string[],
+  MembersMap extends Record<string, string> = Record<string, string>,
+> {
+  /** Internal brand for lowering-pipeline detection. */
+  readonly [ENUM_TYPE_HANDLE_BRAND]: true;
+
+  /** The enum's declared name (used as the key in domain `enum` / storage `valueSet`). */
+  readonly enumName: Name;
+
+  /** codecId from the codec passed to `enumType`. */
+  readonly codecId: string;
+
+  /** nativeType from the codec passed to `enumType`. */
+  readonly nativeType: string;
+
+  /** Ordered member list for lowering (name + value pairs). */
+  readonly enumMembers: readonly { readonly name: string; readonly value: string }[];
+
+  /** Ordered literal value tuple. Declaration order is preserved. */
+  readonly values: Values;
+
+  /** Ordered literal name tuple. Declaration order is preserved. */
+  readonly names: Names;
+
+  /**
+   * Namespaced accessor map: `Role.members.User === 'user'`.
+   * Namespaced under `.members` to avoid collisions with `.values` / `.has`.
+   */
+  readonly members: MembersMap;
+
+  /** Returns `true` if `v` is a declared member value. */
+  has(v: string): boolean;
+
+  /** Returns the member name for a value, or `undefined` if not found. */
+  nameOf(v: string): string | undefined;
+
+  /** Returns the zero-based declaration index of a value, or `-1` if not found. */
+  ordinalOf(v: string): number;
+}
+
+// ---------------------------------------------------------------------------
+// enumType()
+// ---------------------------------------------------------------------------
+
+/**
+ * Declare a domain enum for use in TS-authoring contracts.
+ *
+ * - The codec is an explicit required argument — the `codecId` and
+ *   `nativeType` are taken from the passed `ColumnTypeDescriptor` (e.g.
+ *   `{ codecId: 'pg/text@1', nativeType: 'text' }` from a field preset
+ *   output or a direct inline object).
+ * - `const` generics on the members spread preserve the ordered literal
+ *   value tuple so `Role.values` is `readonly ['user','admin']`, not
+ *   `string[]`.
+ * - Well-formedness assertions at construction: non-empty member list;
+ *   unique names; unique values.
+ *
+ * The returned handle wires into `field.namedType(handle)` to set
+ * `valueSet` refs on both the domain field and the storage column.
+ *
+ * @example
+ * ```ts
+ * const Role = enumType('Role', { codecId: 'pg/text@1', nativeType: 'text' },
+ *   member('User', 'user'),
+ *   member('Admin', 'admin'),
+ * );
+ * // Role.values → readonly ['user', 'admin']
+ * // Role.members.User → 'user'
+ * ```
+ */
+export function enumType<
+  const Name extends string,
+  const Codec extends Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>,
+  const Members extends readonly [EnumMember<string, string>, ...EnumMember<string, string>[]],
+>(
+  name: Name,
+  codec: Codec,
+  ...members: Members
+): EnumTypeHandle<
+  Name,
+  MembersToValues<[...Members]>,
+  MembersToNames<[...Members]>,
+  MembersAccessorMap<[...Members]>
+>;
+export function enumType(
+  name: string,
+  codec: Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>,
+  ...members: EnumMember<string, string>[]
+): EnumTypeHandle;
+export function enumType(
+  name: string,
+  codec: Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>,
+  ...members: EnumMember<string, string>[]
+): EnumTypeHandle {
+  if (members.length === 0) {
+    throw new Error(`enumType("${name}"): must have at least one member.`);
+  }
+
+  const seenNames = new Set<string>();
+  const seenValues = new Set<string>();
+  for (const m of members) {
+    if (seenNames.has(m.name)) {
+      throw new Error(
+        `enumType("${name}"): duplicate member name "${m.name}". Member names must be unique.`,
+      );
+    }
+    seenNames.add(m.name);
+
+    if (seenValues.has(m.value)) {
+      throw new Error(
+        `enumType("${name}"): duplicate member value "${m.value}". Member values must be unique.`,
+      );
+    }
+    seenValues.add(m.value);
+  }
+
+  const values = Object.freeze(members.map((m) => m.value));
+  const names = Object.freeze(members.map((m) => m.name));
+  const enumMembers = Object.freeze(members.map((m) => ({ name: m.name, value: m.value })));
+
+  const membersAccessor = Object.freeze(Object.fromEntries(members.map((m) => [m.name, m.value])));
+
+  const valueSet = new Set(values);
+  const valueToName = new Map(members.map((m) => [m.value, m.name]));
+  const valueToOrdinal = new Map(values.map((v, i) => [v, i]));
+
+  return {
+    [ENUM_TYPE_HANDLE_BRAND]: true,
+    enumName: name,
+    codecId: codec.codecId,
+    nativeType: codec.nativeType,
+    enumMembers,
+    values,
+    names,
+    members: membersAccessor,
+    has: (v: string) => valueSet.has(v),
+    nameOf: (v: string) => valueToName.get(v),
+    ordinalOf: (v: string) => valueToOrdinal.get(v) ?? -1,
+  };
+}
+
+/**
+ * Returns true when the value is an `EnumTypeHandle` produced by
+ * `enumType()`. Used in the lowering pipeline to detect enum handles
+ * in field state without importing the BRAND symbol at every call site.
+ */
+export function isEnumTypeHandle(value: unknown): value is EnumTypeHandle {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Reflect.get(value, ENUM_TYPE_HANDLE_BRAND) === true
+  );
+}