@prisma-next/sql-contract-ts 0.14.0-dev.9 → 0.14.0-dev.90

package/package.json

@@ -1,30 +1,30 @@
 {
   "name": "@prisma-next/sql-contract-ts",
-  "version": "0.14.0-dev.9",
+  "version": "0.14.0-dev.90",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL-specific TypeScript contract authoring surface for Prisma Next",
   "dependencies": {
-    "@prisma-next/config": "0.14.0-dev.9",
-    "@prisma-next/contract": "0.14.0-dev.9",
-    "@prisma-next/contract-authoring": "0.14.0-dev.9",
-    "@prisma-next/framework-components": "0.14.0-dev.9",
-    "@prisma-next/sql-contract": "0.14.0-dev.9",
-    "@prisma-next/utils": "0.14.0-dev.9",
-    "arktype": "^2.2.0",
+    "@prisma-next/config": "0.14.0-dev.90",
+    "@prisma-next/contract": "0.14.0-dev.90",
+    "@prisma-next/contract-authoring": "0.14.0-dev.90",
+    "@prisma-next/framework-components": "0.14.0-dev.90",
+    "@prisma-next/sql-contract": "0.14.0-dev.90",
+    "@prisma-next/utils": "0.14.0-dev.90",
+    "arktype": "^2.2.2",
     "pathe": "^2.0.3",
     "ts-toolbelt": "^9.6.0"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.14.0-dev.9",
-    "@prisma-next/tsconfig": "0.14.0-dev.9",
+    "@prisma-next/test-utils": "0.14.0-dev.90",
+    "@prisma-next/tsconfig": "0.14.0-dev.90",
     "@types/pg": "8.20.0",
-    "pg": "8.21.0",
-    "@prisma-next/tsdown": "0.14.0-dev.9",
-    "tsdown": "0.22.1",
+    "pg": "8.22.0",
+    "@prisma-next/tsdown": "0.14.0-dev.90",
+    "tsdown": "0.22.3",
     "typescript": "5.9.3",
-    "vitest": "4.1.8"
+    "vitest": "4.1.10"
   },
   "peerDependencies": {
     "typescript": ">=5.9"

package/src/authoring-helper-runtime.ts

@@ -63,7 +63,7 @@ export function createTypeHelpersFromNamespace(
       continue;
     }
 
-    helpers[key] = createTypeHelpersFromNamespace(value as AuthoringTypeNamespace, currentPath);
+    helpers[key] = createTypeHelpersFromNamespace(value, currentPath);
   }
 
   return helpers;
@@ -133,11 +133,7 @@ export function createFieldHelpersFromNamespace(
       continue;
     }
 
-    helpers[key] = createFieldHelpersFromNamespace(
-      value as AuthoringFieldNamespace,
-      createLeafHelper,
-      currentPath,
-    );
+    helpers[key] = createFieldHelpersFromNamespace(value, createLeafHelper, currentPath);
   }
 
   return helpers;

package/src/authoring-type-utils.ts

@@ -2,6 +2,7 @@ import type {
   AuthoringArgumentDescriptor,
   AuthoringFieldPresetDescriptor,
 } from '@prisma-next/framework-components/authoring';
+import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
 import type { ScalarFieldBuilder, ScalarFieldState } from './contract-dsl';
 
 export type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (
@@ -114,9 +115,11 @@ export type FieldBuilderFromPresetDescriptor<
   ConstraintName extends string | undefined = undefined,
 > = ScalarFieldBuilder<
   ScalarFieldState<
-    ResolveTemplateValue<Descriptor['output']['codecId'], Args> extends string
-      ? ResolveTemplateValue<Descriptor['output']['codecId'], Args>
-      : string,
+    ColumnTypeDescriptor<
+      ResolveTemplateValue<Descriptor['output']['codecId'], Args> extends string
+        ? ResolveTemplateValue<Descriptor['output']['codecId'], Args>
+        : string
+    >,
     undefined,
     ResolveTemplateValue<Descriptor['output']['nullable'], Args> extends true ? true : false,
     undefined,

package/src/build-contract.ts

@@ -22,9 +22,16 @@ import {
   type ValueSetRef,
 } from '@prisma-next/contract/types';
 import { type CapabilityMatrix, mergeCapabilityMatrices } from '@prisma-next/contract-authoring';
-import type { CodecLookup } from '@prisma-next/framework-components/codec';
+import type {
+  AuthoringContributions,
+  AuthoringEntityTypeDescriptor,
+  AuthoringEntityTypeNamespace,
+} from '@prisma-next/framework-components/authoring';
+import { isAuthoringEntityTypeDescriptor } from '@prisma-next/framework-components/authoring';
+import type { CodecLookup, ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';
+import { tableEntityKind, valueSetEntityKind } from '@prisma-next/sql-contract/entity-kinds';
 import { validateIndexTypes } from '@prisma-next/sql-contract/index-type-validation';
 import {
   createIndexTypeRegistry,
@@ -33,9 +40,8 @@ import {
 } from '@prisma-next/sql-contract/index-types';
 import {
   applyFkDefaults,
-  buildSqlNamespace,
   type CheckConstraintInput,
-  type SqlNamespaceTablesInput,
+  type SqlNamespaceInput,
   SqlStorage,
   type SqlStorageInput,
   type StorageColumn,
@@ -45,6 +51,7 @@ import {
   toStorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import { validateStorageSemantics } from '@prisma-next/sql-contract/validators';
+import { deriveValueSetFromEntity } from '@prisma-next/sql-contract/value-set-derivation-hook';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type {
@@ -74,10 +81,23 @@ function encodeColumnDefault(
   defaultInput: ColumnDefault,
   codecId: string,
   codecLookup?: CodecLookup,
+  many = false,
 ): ColumnDefault {
   if (defaultInput.kind === 'function') {
     return { kind: 'function', expression: defaultInput.expression };
   }
+  if (many) {
+    if (!Array.isArray(defaultInput.value)) {
+      throw new Error(
+        `Literal default on a list column must be an array; received ${typeof defaultInput.value}. ` +
+          'A scalar default on a list field must be rejected at the authoring surface.',
+      );
+    }
+    return {
+      kind: 'literal',
+      value: defaultInput.value.map((element) => encodeViaCodec(element, codecId, codecLookup)),
+    };
+  }
   return {
     kind: 'literal',
     value: encodeViaCodec(defaultInput.value, codecId, codecLookup),
@@ -160,6 +180,176 @@ function isValueObjectField(
   return 'valueObjectName' in field;
 }
 
+/**
+ * Resolves a deferred entity-ref column descriptor (e.g. a `pg.enum(handle)`
+ * column) against the field's now-known owning namespace: attaches the
+ * storage `valueSet` ref the collected entity's derived value-set is stored
+ * under. `nativeType` / `typeParams.typeName` stay bare here — schema
+ * qualification (e.g. `auth.aal_level`) is a target concern applied in the
+ * next step, `qualifyColumnDescriptor`. A descriptor with no `entityRef` (the
+ * ordinary case) passes through unchanged.
+ */
+function resolveEntityRefDescriptor(
+  descriptor: ColumnTypeDescriptor,
+  namespaceId: string,
+): ColumnTypeDescriptor {
+  const entityRef = descriptor.entityRef;
+  if (entityRef === undefined) return descriptor;
+
+  return {
+    ...descriptor,
+    valueSet: {
+      plane: 'storage',
+      entityKind: 'valueSet',
+      namespaceId,
+      entityName: entityRef.entityName,
+    },
+  };
+}
+
+/**
+ * A target's contract-construction-time column-type qualifier, contributed
+ * through `target.authoring.qualifyColumnType`. Given a column's bare type
+ * info and its owning `namespaceId`, it returns the type info the target's
+ * schema semantics require (e.g. Postgres schema-qualifies a native-enum
+ * column's type name to `auth.aal_level`). The dispatch keys off the codec
+ * id, so every codec — including ones needing no change — is passed through
+ * and the caller stays codec-blind. Targets without the hook leave every
+ * column bare.
+ */
+type ColumnTypeQualifier = (
+  input: {
+    readonly codecId: string;
+    readonly nativeType: string;
+    readonly typeParams?: Record<string, unknown>;
+  },
+  namespaceId: string,
+) => { readonly nativeType: string; readonly typeParams?: Record<string, unknown> };
+
+/**
+ * Structural check for a target that contributes a `qualifyColumnType` hook
+ * on its authoring contributions. Duck-typed (mirroring
+ * `contract-psl`'s `hasColumnFromEntityHook`) so the SQL family stays blind
+ * to the target's qualification logic and no framework/family interface has
+ * to name the hook.
+ */
+function hasColumnTypeQualifier(
+  authoring: AuthoringContributions,
+): authoring is AuthoringContributions & { readonly qualifyColumnType: ColumnTypeQualifier } {
+  return 'qualifyColumnType' in authoring && typeof authoring.qualifyColumnType === 'function';
+}
+
+function resolveColumnTypeQualifier(
+  target: ContractDefinition['target'],
+): ColumnTypeQualifier | undefined {
+  const authoring = target.authoring;
+  if (authoring === undefined) return undefined;
+  return hasColumnTypeQualifier(authoring) ? authoring.qualifyColumnType : undefined;
+}
+
+/**
+ * Applies the target's `qualifyColumnType` hook to a scalar column descriptor
+ * at construction, so the storage column and the domain field (which derives
+ * its `type.typeParams` from the storage column) are both built already
+ * qualified in a single pass. A descriptor whose codec the target leaves
+ * unchanged passes through untouched.
+ */
+function qualifyColumnDescriptor(
+  descriptor: ColumnTypeDescriptor,
+  namespaceId: string,
+  qualify: ColumnTypeQualifier | undefined,
+): ColumnTypeDescriptor {
+  if (qualify === undefined) return descriptor;
+  const qualified = qualify(
+    {
+      codecId: descriptor.codecId,
+      nativeType: descriptor.nativeType,
+      ...ifDefined('typeParams', descriptor.typeParams),
+    },
+    namespaceId,
+  );
+  if (
+    qualified.nativeType === descriptor.nativeType &&
+    qualified.typeParams === descriptor.typeParams
+  ) {
+    return descriptor;
+  }
+  return {
+    ...descriptor,
+    nativeType: qualified.nativeType,
+    ...ifDefined('typeParams', qualified.typeParams),
+  };
+}
+
+type CollectedColumnEntities = Record<string, Record<string, Record<string, unknown>>>;
+
+/**
+ * Records a deferred column's entity-ref into the namespace-scoped collection
+ * accumulator (`namespaceId → entityKind → entityName`) — folded into the same
+ * namespace assembly `deriveEntityValueSets`/`entries.<kind>` step as the
+ * entities-channel attachments, so a column-collected entity gets its
+ * value-set the same way an entities-channel one does.
+ *
+ * The same handle reused by many columns in one namespace is normal (a native
+ * enum type backs any number of columns) and records the identical entity once.
+ * Two *different* entity instances sharing a name+kind in one namespace is a
+ * name collision — the emitted `entries.valueSet.<name>` could only reflect one
+ * of them, silently mismatching the other column's type/cast. PSL hard-errors
+ * on the equivalent (`PSL_DUPLICATE_DECLARATION`); the TS path rejects it too.
+ */
+function collectEntityFromColumn(
+  collected: CollectedColumnEntities,
+  namespaceId: string,
+  entityRef: NonNullable<ColumnTypeDescriptor['entityRef']>,
+): void {
+  const forNs = collected[namespaceId] ?? {};
+  const forKind = forNs[entityRef.entityKind] ?? {};
+  const existing = forKind[entityRef.entityName];
+  if (existing !== undefined && existing !== entityRef.entity) {
+    throw new Error(
+      `buildSqlContractFromDefinition: two different "${entityRef.entityKind}" entities named "${entityRef.entityName}" in namespace "${namespaceId}" — pack-entity names must be unique per namespace.`,
+    );
+  }
+  forKind[entityRef.entityName] = entityRef.entity;
+  forNs[entityRef.entityKind] = forKind;
+  collected[namespaceId] = forNs;
+}
+
+/**
+ * Merges a namespace's entities-channel attachments (lowered from the
+ * `entities` handle list, carried on `ContractDefinition.attachedEntities`)
+ * with the entities collected from that namespace's deferred entity-ref
+ * columns. A column-collected entity that shadows a *different* attached
+ * entity of the same kind+name (or vice-versa) is the same name-collision bug
+ * `collectEntityFromColumn` guards against across columns, so it is rejected
+ * the same way — by entity identity, so the same handle attached and used by
+ * a column does not throw.
+ */
+function mergeColumnAndAttachedEntities(
+  namespaceId: string,
+  attached: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  columnCollected: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+): Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined {
+  if (attached === undefined) return columnCollected;
+  if (columnCollected === undefined) return attached;
+  const kinds = new Set([...Object.keys(attached), ...Object.keys(columnCollected)]);
+  const result: Record<string, Readonly<Record<string, unknown>>> = {};
+  for (const kind of kinds) {
+    const attachedForKind = attached[kind];
+    const columnForKind = columnCollected[kind];
+    for (const [name, entity] of Object.entries(columnForKind ?? {})) {
+      const existing = attachedForKind?.[name];
+      if (existing !== undefined && existing !== entity) {
+        throw new Error(
+          `buildSqlContractFromDefinition: two different "${kind}" entities named "${name}" in namespace "${namespaceId}" — a column-referenced entity conflicts with an attached one; pack-entity names must be unique per namespace.`,
+        );
+      }
+    }
+    result[kind] = { ...attachedForKind, ...columnForKind };
+  }
+  return result;
+}
+
 const JSONB_CODEC_ID = 'pg/jsonb@1';
 const JSONB_NATIVE_TYPE = 'jsonb';
 
@@ -235,28 +425,28 @@ function buildStorageColumn(
     };
   }
 
-  if (field.many) {
-    return {
-      nativeType: JSONB_NATIVE_TYPE,
-      codecId: JSONB_CODEC_ID,
-      nullable: field.nullable,
-    };
-  }
-
   const codecId = field.descriptor.codecId;
   const encodedDefault =
     field.default !== undefined
-      ? encodeColumnDefault(field.default, codecId, codecLookup)
+      ? encodeColumnDefault(field.default, codecId, codecLookup, field.many === true)
       : undefined;
 
+  // `storageValueSetRef` (derived from an `enumTypeHandle`) takes precedence
+  // when present — the established domain-enum path. `field.descriptor.valueSet`
+  // is the fallback: set by an entity-ref type constructor (e.g. `pg.enum(Ref)`)
+  // that resolved the field's type against a value-set-deriving entity with no
+  // domain enum involved. A field carries at most one of the two in practice.
+  const valueSet = storageValueSetRef ?? field.descriptor.valueSet;
+
   return {
     nativeType: field.descriptor.nativeType,
     codecId,
     nullable: field.nullable,
+    ...(field.many ? { many: true as const } : {}),
     ...ifDefined('typeParams', field.descriptor.typeParams),
     ...ifDefined('default', encodedDefault),
     ...ifDefined('typeRef', field.descriptor.typeRef),
-    ...ifDefined('valueSet', storageValueSetRef),
+    ...ifDefined('valueSet', valueSet),
   };
 }
 
@@ -298,9 +488,122 @@ function collectStorageNamespaceCoordinateIds(definition: ContractDefinition): S
       ids.add(model.namespaceId);
     }
   }
+  for (const id of Object.keys(definition.attachedEntities ?? {})) {
+    if (id.length > 0) {
+      ids.add(id);
+    }
+  }
   return ids;
 }
 
+/**
+ * Entry kinds the framework assembler itself manages (`table` from models,
+ * `valueSet` from `enums` and attached-entity value-set derivation). A
+ * pack-attached entity claiming one of these would silently clobber or be
+ * clobbered by the managed slot, so it is rejected outright.
+ */
+const MANAGED_ENTRY_KINDS = new Set([tableEntityKind.kind, valueSetEntityKind.kind]);
+
+function assertNoManagedEntityKinds(
+  namespaceId: string,
+  entitiesForNs: Readonly<Record<string, unknown>> | undefined,
+): void {
+  if (entitiesForNs === undefined) return;
+  for (const kind of Object.keys(entitiesForNs)) {
+    if (MANAGED_ENTRY_KINDS.has(kind)) {
+      throw new Error(
+        `buildSqlContractFromDefinition: attached entity in namespace "${namespaceId}" declares entry kind "${kind}", which is managed by the framework (table/valueSet) and cannot be attached.`,
+      );
+    }
+  }
+}
+
+/**
+ * Walks the flat `entityTypes` namespace tree contributed by the target pack
+ * and every extension pack, indexing descriptors by their `discriminator` —
+ * the same string a pack entity's entries-map key (`entries.<kind>`) uses.
+ * Mirrors `contract-psl`'s `buildEntityTypesByDiscriminator`, recomposed here
+ * from the packs `ContractDefinition` already carries (`target` +
+ * `extensionPacks`) since the TS assembler has no single pre-merged
+ * `AuthoringContributions` input to read the way the PSL interpreter does.
+ */
+function collectEntityTypeDescriptorsByDiscriminator(
+  definition: ContractDefinition,
+): ReadonlyMap<string, AuthoringEntityTypeDescriptor> {
+  const result = new Map<string, AuthoringEntityTypeDescriptor>();
+  const walk = (namespace: AuthoringEntityTypeNamespace): void => {
+    for (const value of Object.values(namespace)) {
+      if (isAuthoringEntityTypeDescriptor(value)) {
+        result.set(value.discriminator, value);
+      } else {
+        walk(value);
+      }
+    }
+  };
+  const components = [definition.target, ...Object.values(definition.extensionPacks ?? {})];
+  for (const component of components) {
+    const entityTypes = component.authoring?.entityTypes;
+    if (entityTypes !== undefined) {
+      walk(entityTypes);
+    }
+  }
+  return result;
+}
+
+/**
+ * Derives value-sets for every pack entity declared in one namespace,
+ * reusing the same `SqlValueSetDerivingEntityTypeOutput.deriveValueSet` hook
+ * `contract-psl`'s `lowerExtensionBlocksForNamespace` folds into
+ * `entries.valueSet` on the PSL path — so a TS-attached entity (e.g. a
+ * native enum) gets its value-set the same way. Entity kinds with no
+ * registered descriptor, or whose descriptor output doesn't derive a
+ * value-set, contribute nothing.
+ */
+function deriveEntityValueSets(
+  entitiesForNs: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
+  entityTypesByDiscriminator: ReadonlyMap<string, AuthoringEntityTypeDescriptor>,
+): Record<string, StorageValueSetInput> | undefined {
+  if (entitiesForNs === undefined) return undefined;
+  let result: Record<string, StorageValueSetInput> | undefined;
+  for (const [kind, entitiesByName] of Object.entries(entitiesForNs)) {
+    const descriptor = entityTypesByDiscriminator.get(kind);
+    if (descriptor === undefined) continue;
+    for (const [name, entity] of Object.entries(entitiesByName)) {
+      const derivedValueSet = deriveValueSetFromEntity(descriptor.output, entity);
+      if (derivedValueSet === undefined) continue;
+      result ??= {};
+      result[name] = derivedValueSet;
+    }
+  }
+  return result;
+}
+
+/**
+ * Merges a namespace's `enumType()`-derived value-sets with its pack-entity-
+ * derived value-sets. Both land in the same `entries.valueSet[name]` slot —
+ * which drives value-set → codec typing and the domain-enum CHECK — so a
+ * same-named entry in both would let one silently overwrite the other and
+ * corrupt whichever column resolves against it. The same collision class the
+ * `mergeColumnAndAttachedEntities` guard rejects; the PSL path already hard-errors
+ * on the equivalent (`interpretPslDocumentToSqlContract`). Reject it here too.
+ */
+function mergeNamespaceValueSets(
+  namespaceId: string,
+  enumValueSets: Record<string, StorageValueSetInput> | undefined,
+  packValueSets: Record<string, StorageValueSetInput> | undefined,
+): Record<string, StorageValueSetInput> {
+  if (enumValueSets !== undefined && packValueSets !== undefined) {
+    for (const name of Object.keys(packValueSets)) {
+      if (Object.hasOwn(enumValueSets, name)) {
+        throw new Error(
+          `buildSqlContractFromDefinition: value-set "${name}" in namespace "${namespaceId}" is derived from both an enum and a pack entity — names must be unique per namespace.`,
+        );
+      }
+    }
+  }
+  return { ...enumValueSets, ...packValueSets };
+}
+
 function ensureUnboundNamespaceSlot(
   namespaces: SqlStorageInput['namespaces'],
   createNamespace: ContractDefinition['createNamespace'],
@@ -308,18 +611,15 @@ function ensureUnboundNamespaceSlot(
   if (Object.hasOwn(namespaces, UNBOUND_NAMESPACE_ID)) {
     return namespaces;
   }
-  const unboundInput: SqlNamespaceTablesInput = {
+  const unboundInput: SqlNamespaceInput = {
     id: UNBOUND_NAMESPACE_ID,
     entries: { table: {} },
   };
-  const unbound = createNamespace ? createNamespace(unboundInput) : buildSqlNamespace(unboundInput);
-  return blindCast<
-    SqlStorageInput['namespaces'],
-    'createNamespace may return a target namespace concretion; the unbound slot matches SqlNamespace at runtime'
-  >({
+  const unbound = createNamespace(unboundInput);
+  return {
     [UNBOUND_NAMESPACE_ID]: unbound,
     ...namespaces,
-  });
+  };
 }
 
 export function buildSqlContractFromDefinition(
@@ -328,6 +628,7 @@ export function buildSqlContractFromDefinition(
 ): Contract<SqlStorage> {
   const target = definition.target.targetId;
   const defaultNamespaceId = definition.target.defaultNamespaceId;
+  const qualifyColumnType = resolveColumnTypeQualifier(definition.target);
   const targetFamily = 'sql';
   const resolveNamespaceId = (m: ModelNode): string =>
     m.namespaceId !== undefined && m.namespaceId.length > 0 ? m.namespaceId : defaultNamespaceId;
@@ -346,6 +647,7 @@ export function buildSqlContractFromDefinition(
   const modelNameToNamespaceId = new Map<string, string>();
   const executionDefaults: ExecutionMutationDefault[] = [];
   const modelsByNamespace: Record<string, Record<string, ContractModel>> = {};
+  const collectedColumnEntities: CollectedColumnEntities = {};
   const rootEntries: Array<{
     readonly tableName: string;
     readonly namespaceId: string;
@@ -375,6 +677,7 @@ export function buildSqlContractFromDefinition(
     const fieldToColumn: Record<string, string> = {};
     const domainFields: Record<string, ContractField> = {};
     const domainFieldRefs: Record<string, DomainFieldRef> = {};
+    const checksForTable: CheckConstraintInput[] = [];
 
     for (const field of semanticModel.fields) {
       const executionDefaultPhases =
@@ -417,10 +720,58 @@ export function buildSqlContractFromDefinition(
             }
           : undefined;
 
-      const column = buildStorageColumn(field, storageValueSetRef, codecLookup);
+      // A field authored through a deferred entity-ref column helper (e.g.
+      // `pg.enum(handle)`) carries `descriptor.entityRef`: the referenced
+      // entity is collected into `collectedColumnEntities` (folded into the
+      // same `entries.<kind>` + `entries.valueSet` assembly an entities-channel
+      // attachment goes through) and the descriptor is resolved
+      // against this field's now-known `namespaceId` — the builder call that
+      // produced it ran before the enclosing model associated one. The
+      // descriptor is then handed to the target's `qualifyColumnType` hook,
+      // which schema-qualifies a native-enum column's type name for its
+      // namespace. Keying off the codec id (inside the hook) catches both the
+      // TS `pg.enum(handle)` path (via `entityRef`) and the PSL `pg.enum(Ref)`
+      // path (resolved inline in the interpreter, no `entityRef`). Because the
+      // storage column is built from this qualified descriptor and the domain
+      // field derives its `type.typeParams` from that column, both come out
+      // qualified in this single pass.
+      let resolvedField: FieldNode | ValueObjectFieldNode = field;
+      if (!isValueObjectField(field)) {
+        let descriptor = field.descriptor;
+        const entityRef = descriptor.entityRef;
+        if (entityRef !== undefined) {
+          collectEntityFromColumn(collectedColumnEntities, namespaceId, entityRef);
+          descriptor = resolveEntityRefDescriptor(descriptor, namespaceId);
+        }
+        descriptor = qualifyColumnDescriptor(descriptor, namespaceId, qualifyColumnType);
+        if (descriptor !== field.descriptor) {
+          resolvedField = { ...field, descriptor };
+        }
+      }
+
+      const column = buildStorageColumn(resolvedField, storageValueSetRef, codecLookup);
       columns[field.columnName] = column;
       fieldToColumn[field.fieldName] = field.columnName;
 
+      // A domain enum (`storageValueSetRef`, from an `enumType()` handle) is
+      // stored as a plain scalar column (`text`, `int4`, …) with no native
+      // type of its own to enforce membership, so it needs an explicit
+      // CHECK — scalar or array, since a `text[]` array has no element-level
+      // enforcement either. A value set resolved by an entity-ref type
+      // constructor (`field.descriptor.valueSet`, e.g. `pg.enum(Ref)`) binds
+      // the column to a codec/native-type pairing that IS the storage-level
+      // enforcement (a Postgres native enum type, or another target's
+      // equivalent) — including array columns, since the target enforces
+      // membership on every element of a native-typed array — so no CHECK
+      // for those.
+      if (column.valueSet !== undefined && storageValueSetRef !== undefined) {
+        checksForTable.push({
+          name: `${tableName}_${field.columnName}_check`,
+          column: field.columnName,
+          valueSet: column.valueSet,
+        });
+      }
+
       domainFields[field.fieldName] = buildDomainField(field, column, domainValueSetRef);
 
       if (isValueObjectField(field)) {
@@ -511,15 +862,6 @@ export function buildSqlContractFromDefinition(
     // materialised onto the base `ModelNode`, so the variant builds a domain
     // model (below) but no storage table of its own.
     if (!semanticModel.sharesBaseTable) {
-      const checksForTable: CheckConstraintInput[] = Object.entries(columns).flatMap(
-        ([columnName, col]) => {
-          const valueSet = col.valueSet;
-          return valueSet === undefined
-            ? []
-            : [{ name: `${tableName}_${columnName}_check`, column: columnName, valueSet }];
-        },
-      );
-
       const tableInput: StorageTableInput = {
         columns,
         ...ifDefined('control', semanticModel.control),
@@ -729,25 +1071,35 @@ export function buildSqlContractFromDefinition(
   }
 
   const { createNamespace } = definition;
-  const namespaces = blindCast<
-    SqlStorageInput['namespaces'],
-    'contract authoring materialises each namespace coordinate from the model set and explicit namespace list'
-  >(
-    Object.fromEntries(
-      [...namespaceCoordinateIds].sort().map((id) => {
-        const valueSetEntries = storageValueSetsByNs[id];
-        const nsInput: SqlNamespaceTablesInput = {
-          id,
-          entries: {
-            table: tablesByNamespace[id] ?? {},
-            ...(valueSetEntries !== undefined && Object.keys(valueSetEntries).length > 0
-              ? { valueSet: valueSetEntries }
-              : {}),
-          },
-        };
-        return [id, createNamespace ? createNamespace(nsInput) : buildSqlNamespace(nsInput)];
-      }),
-    ),
+  const entityTypesByDiscriminator = collectEntityTypeDescriptorsByDiscriminator(definition);
+  const namespaces: SqlStorageInput['namespaces'] = Object.fromEntries(
+    [...namespaceCoordinateIds].sort().map((id) => {
+      const entitiesForNs = mergeColumnAndAttachedEntities(
+        id,
+        definition.attachedEntities?.[id],
+        collectedColumnEntities[id],
+      );
+      assertNoManagedEntityKinds(id, entitiesForNs);
+
+      const enumValueSetEntries = storageValueSetsByNs[id];
+      const packValueSetEntries = deriveEntityValueSets(entitiesForNs, entityTypesByDiscriminator);
+      const valueSetEntries =
+        enumValueSetEntries !== undefined || packValueSetEntries !== undefined
+          ? mergeNamespaceValueSets(id, enumValueSetEntries, packValueSetEntries)
+          : undefined;
+
+      const nsInput: SqlNamespaceInput = {
+        id,
+        entries: {
+          table: tablesByNamespace[id] ?? {},
+          ...entitiesForNs,
+          ...(valueSetEntries !== undefined && Object.keys(valueSetEntries).length > 0
+            ? { valueSet: valueSetEntries }
+            : {}),
+        },
+      };
+      return [id, createNamespace(nsInput)];
+    }),
   );
   const storageWithoutHash = {
     ...(Object.keys(documentTypes).length > 0 ? { types: documentTypes } : {}),