@prisma-next/mongo-contract-psl 0.14.0-dev.5 → 0.14.0-dev.50

package/src/interpreter.ts

@@ -5,12 +5,25 @@ import type {
 import { computeProfileHash, computeStorageHash } from '@prisma-next/contract/hashing';
 import {
   type Contract,
+  type ContractEnum,
   type ContractField,
   type ContractReferenceRelation,
   type ContractValueObject,
   type CrossReference,
   crossRef,
+  type JsonValue,
+  type ValueSetRef,
 } from '@prisma-next/contract/types';
+import type { EnumTypeHandle } from '@prisma-next/contract-authoring';
+import { errorEnumCodecNotInPackStack } from '@prisma-next/errors/control';
+import type {
+  AuthoringContributions,
+  AuthoringEntityContext,
+} from '@prisma-next/framework-components/authoring';
+import {
+  instantiateAuthoringEntityType,
+  isAuthoringEntityTypeDescriptor,
+} from '@prisma-next/framework-components/authoring';
 import type { CodecLookup } from '@prisma-next/framework-components/codec';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import {
@@ -20,17 +33,25 @@ import {
   MongoIndex,
   type MongoIndexKeyDirection,
   MongoStorage,
+  type MongoValueSetInput,
 } from '@prisma-next/mongo-contract';
 import { mongoContractCanonicalizationHooks } from '@prisma-next/mongo-contract/canonicalization-hooks';
 import type { CollationOptions } from '@prisma-next/mongo-value/mongodb-types';
 import type {
-  ParsePslDocumentResult,
-  PslField,
-  PslModel,
-  PslNamespace,
+  CompositeTypeSymbol,
+  FieldSymbol,
+  ModelSymbol,
+  NamespaceSymbol,
+  PslExtensionBlock,
   PslSpan,
+  ResolvedAttribute,
+  SymbolTable,
 } from '@prisma-next/psl-parser';
+import { nodePslSpan } from '@prisma-next/psl-parser';
+import type { SourceFile } from '@prisma-next/psl-parser/syntax';
+import { assertDefined } from '@prisma-next/utils/assertions';
 import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { deriveJsonSchema, derivePolymorphicJsonSchema } from './derive-json-schema';
 import {
@@ -44,42 +65,49 @@ import {
   parseRelationAttribute,
 } from './psl-helpers';
 
+/**
+ * Encode an authored enum value to its codec-encoded JSON form via the codec resolved by id from the
+ * contract's codec lookup, so a non-identity `encodeJson` (permitted by the `mongoCodec` factory) is
+ * respected. Matches the TS builder's `encodeEnumValue`: the lookup is always threaded in production,
+ * and a codecId the lookup cannot resolve is a hard error — the enum uses a codec that is not part of
+ * the contract's pack stack.
+ */
+function encodeEnumValue(value: unknown, codecId: string, codecLookup: CodecLookup): JsonValue {
+  const codec = codecLookup.get(codecId);
+  if (!codec) {
+    throw errorEnumCodecNotInPackStack({ codecId });
+  }
+  return codec.encodeJson(value);
+}
+
 export interface InterpretPslDocumentToMongoContractInput {
-  readonly document: ParsePslDocumentResult;
+  readonly symbolTable: SymbolTable;
+  readonly sourceFile: SourceFile;
+  readonly sourceId: string;
   readonly scalarTypeDescriptors: ReadonlyMap<string, string>;
   readonly codecLookup?: CodecLookup;
+  readonly seedDiagnostics?: readonly ContractSourceDiagnostic[];
+  readonly authoringContributions?: AuthoringContributions;
+  /** The target's default codec ids for an `enum` block that omits `@@type`. */
+  readonly enumInferenceCodecs?: { readonly text: string; readonly int: string };
 }
 
 /**
- * Name of the framework-parser synthesised bucket for top-level
- * declarations. Re-declared locally so the interpreter does not have to
- * import from `@prisma-next/framework-components/psl-ast`.
- */
-const UNSPECIFIED_PSL_NAMESPACE_NAME = '__unspecified__';
-
-/**
- * Mongo FR16c validation: Mongo's authoring DSL exposes the connection's
- * database as the only namespace surface today, so the PSL interpreter
- * rejects every explicit `namespace { … }` block. The implicit
- * `__unspecified__` bucket (top-level declarations) is the only
- * namespace Mongo accepts. `namespace unbound { … }` is rejected too —
- * Mongo has no late-binding namespace concept on the PSL surface (the
- * database name comes from the connection string, not from PSL).
+ * Mongo's PSL surface binds the database from the connection string, so every
+ * explicit namespace block is invalid, including `namespace unbound { … }`.
  */
 function validateNamespaceBlocksForMongoTarget(input: {
-  readonly namespaces: readonly PslNamespace[];
+  readonly namespaces: readonly NamespaceSymbol[];
   readonly sourceId: string;
+  readonly sourceFile: SourceFile;
   readonly diagnostics: ContractSourceDiagnostic[];
 }): void {
   for (const namespace of input.namespaces) {
-    if (namespace.name === UNSPECIFIED_PSL_NAMESPACE_NAME) {
-      continue;
-    }
     input.diagnostics.push({
       code: 'PSL_UNSUPPORTED_NAMESPACE_BLOCK',
       message: `Mongo does not support \`namespace ${namespace.name} { … }\` blocks (the database is bound by the connection string; declare models at the document top level instead).`,
       sourceId: input.sourceId,
-      span: namespace.span,
+      span: nodePslSpan(namespace.node.syntax, input.sourceFile),
     });
   }
 }
@@ -101,16 +129,16 @@ function fkRelationPairKey(declaringModel: string, targetModel: string): string
   return `${declaringModel}::${targetModel}`;
 }
 
-function resolveFieldMappings(model: PslModel): FieldMappings {
+function resolveFieldMappings(model: ModelSymbol): FieldMappings {
   const pslNameToMapped = new Map<string, string>();
-  for (const field of model.fields) {
+  for (const field of Object.values(model.fields)) {
     const mapped = getMapName(field.attributes) ?? field.name;
     pslNameToMapped.set(field.name, mapped);
   }
   return { pslNameToMapped };
 }
 
-function resolveCollectionName(model: PslModel): string {
+function resolveCollectionName(model: ModelSymbol): string {
   return getMapName(model.attributes) ?? lowerFirst(model.name);
 }
 
@@ -123,12 +151,12 @@ interface MongoModelEntry {
   readonly base?: CrossReference;
 }
 
-type DiscriminatorDeclaration = { readonly fieldName: string; readonly span: PslModel['span'] };
+type DiscriminatorDeclaration = { readonly fieldName: string; readonly span: PslSpan };
 type BaseDeclaration = {
   readonly baseName: string;
   readonly value: string;
   readonly collectionName: string;
-  readonly span: PslModel['span'];
+  readonly span: PslSpan;
 };
 
 function mongoCrossRef(modelName: string): CrossReference {
@@ -136,7 +164,7 @@ function mongoCrossRef(modelName: string): CrossReference {
 }
 
 function collectPolymorphismDeclarations(
-  document: ParsePslDocumentResult,
+  models: readonly ModelSymbol[],
   sourceId: string,
   diagnostics: ContractSourceDiagnostic[],
 ): {
@@ -145,32 +173,31 @@ function collectPolymorphismDeclarations(
 } {
   const discriminatorDeclarations = new Map<string, DiscriminatorDeclaration>();
   const baseDeclarations = new Map<string, BaseDeclaration>();
-  const allPslModels = document.ast.namespaces.flatMap((ns) => ns.models);
 
-  for (const pslModel of allPslModels) {
-    for (const attr of pslModel.attributes) {
+  for (const model of models) {
+    for (const attr of model.attributes) {
       if (attr.name === 'discriminator') {
         const fieldName = getPositionalArgument(attr);
         if (!fieldName) {
           diagnostics.push({
             code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
-            message: `Model "${pslModel.name}" @@discriminator requires a field name argument`,
+            message: `Model "${model.name}" @@discriminator requires a field name argument`,
             sourceId,
             span: attr.span,
           });
           continue;
         }
-        const discField = pslModel.fields.find((f) => f.name === fieldName);
+        const discField = model.fields[fieldName];
         if (discField && discField.typeName !== 'String') {
           diagnostics.push({
             code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
-            message: `Discriminator field "${fieldName}" on model "${pslModel.name}" must be of type String, but is "${discField.typeName}"`,
+            message: `Discriminator field "${fieldName}" on model "${model.name}" must be of type String, but is "${discField.typeName}"`,
             sourceId,
             span: attr.span,
           });
           continue;
         }
-        discriminatorDeclarations.set(pslModel.name, { fieldName, span: attr.span });
+        discriminatorDeclarations.set(model.name, { fieldName, span: attr.span });
       }
       if (attr.name === 'base') {
         const baseName = getPositionalArgument(attr, 0);
@@ -178,7 +205,7 @@ function collectPolymorphismDeclarations(
         if (!baseName || !rawValue) {
           diagnostics.push({
             code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
-            message: `Model "${pslModel.name}" @@base requires two arguments: base model name and discriminator value`,
+            message: `Model "${model.name}" @@base requires two arguments: base model name and discriminator value`,
             sourceId,
             span: attr.span,
           });
@@ -188,14 +215,14 @@ function collectPolymorphismDeclarations(
         if (value === undefined) {
           diagnostics.push({
             code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
-            message: `Model "${pslModel.name}" @@base discriminator value must be a quoted string literal`,
+            message: `Model "${model.name}" @@base discriminator value must be a quoted string literal`,
             sourceId,
             span: attr.span,
           });
           continue;
         }
-        const collectionName = resolveCollectionName(pslModel);
-        baseDeclarations.set(pslModel.name, { baseName, value, collectionName, span: attr.span });
+        const collectionName = resolveCollectionName(model);
+        baseDeclarations.set(model.name, { baseName, value, collectionName, span: attr.span });
       }
     }
   }
@@ -207,7 +234,7 @@ function resolvePolymorphism(input: {
   models: Record<string, MongoModelEntry>;
   roots: Record<string, CrossReference>;
   collections: Record<string, Record<string, unknown>>;
-  document: ParsePslDocumentResult;
+  allModels: readonly ModelSymbol[];
   discriminatorDeclarations: Map<string, DiscriminatorDeclaration>;
   baseDeclarations: Map<string, BaseDeclaration>;
   modelNames: ReadonlySet<string>;
@@ -225,11 +252,10 @@ function resolvePolymorphism(input: {
     baseDeclarations,
     modelNames,
     sourceId,
-    document,
+    allModels: allModelViews,
     indexSpans,
     modelIndexesByName,
   } = input;
-  const allPslModels = document.ast.namespaces.flatMap((ns) => ns.models);
   let patched = input.models;
   let roots = input.roots;
   let collections = input.collections;
@@ -249,9 +275,9 @@ function resolvePolymorphism(input: {
     const model = patched[modelName];
     if (!model) continue;
 
-    const pslModel = allPslModels.find((m) => m.name === modelName);
-    const mappedDiscriminatorField = pslModel
-      ? (resolveFieldMappings(pslModel).pslNameToMapped.get(decl.fieldName) ?? decl.fieldName)
+    const modelView = allModelViews.find((m) => m.name === modelName);
+    const mappedDiscriminatorField = modelView
+      ? (resolveFieldMappings(modelView).pslNameToMapped.get(decl.fieldName) ?? decl.fieldName)
       : decl.fieldName;
 
     if (!Object.hasOwn(model.fields, mappedDiscriminatorField)) {
@@ -312,9 +338,9 @@ function resolvePolymorphism(input: {
     }
 
     const baseModel = patched[baseDecl.baseName];
-    const variantPslModel = allPslModels.find((m) => m.name === variantName);
-    if (!variantPslModel) continue;
-    const hasExplicitMap = getMapName(variantPslModel.attributes) !== undefined;
+    const variantModelView = allModelViews.find((m) => m.name === variantName);
+    if (!variantModelView) continue;
+    const hasExplicitMap = getMapName(variantModelView.attributes) !== undefined;
 
     if (hasExplicitMap && baseModel && baseDecl.collectionName !== baseModel.storage.collection) {
       diagnostics.push({
@@ -339,7 +365,7 @@ function resolvePolymorphism(input: {
       };
     }
 
-    const variantCollectionName = resolveCollectionName(variantPslModel);
+    const variantCollectionName = resolveCollectionName(variantModelView);
     if (roots[variantCollectionName]?.model === variantName) {
       if (variantCollectionName === baseCollection && baseModel) {
         roots = { ...roots, [variantCollectionName]: mongoCrossRef(baseDecl.baseName) };
@@ -483,9 +509,7 @@ function parseJsonArg(raw: string | undefined): Record<string, unknown> | undefi
   return undefined;
 }
 
-function parseCollation(
-  attr: import('@prisma-next/psl-parser').PslAttribute,
-): CollationOptions | null | undefined {
+function parseCollation(attr: ResolvedAttribute): CollationOptions | null | undefined {
   const locale = stripQuotesHelper(getNamedArgument(attr, 'collationLocale'));
   if (!locale) {
     const hasAnyCollationArg =
@@ -545,7 +569,7 @@ function parseProjectionList(
 }
 
 function collectIndexes(
-  pslModel: PslModel,
+  pslModel: ModelSymbol,
   fieldMappings: FieldMappings,
   modelNames: ReadonlySet<string>,
   sourceId: string,
@@ -561,12 +585,12 @@ function collectIndexes(
   // rather than fieldMappings.pslNameToMapped because the latter contains
   // every PSL field including relation fields.
   const indexableFieldNames = new Set<string>();
-  for (const f of pslModel.fields) {
+  for (const f of Object.values(pslModel.fields)) {
     if (modelNames.has(f.typeName)) continue;
     indexableFieldNames.add(f.name);
   }
 
-  for (const field of pslModel.fields) {
+  for (const field of Object.values(pslModel.fields)) {
     if (modelNames.has(field.typeName)) continue;
     const uniqueAttr = getAttribute(field.attributes, 'unique');
     if (!uniqueAttr) continue;
@@ -800,7 +824,7 @@ function collectIndexes(
   return indexes;
 }
 
-function isRelationField(field: PslField, modelNames: ReadonlySet<string>): boolean {
+function isRelationField(field: FieldSymbol, modelNames: ReadonlySet<string>): boolean {
   return modelNames.has(field.typeName);
 }
 
@@ -808,17 +832,18 @@ function isRelationField(field: PslField, modelNames: ReadonlySet<string>): bool
 const MONGO_OBJECT_ID_PSL_TYPE = 'ObjectId';
 
 function resolveFieldCodecId(
-  field: PslField,
+  field: FieldSymbol,
   scalarTypeDescriptors: ReadonlyMap<string, string>,
 ): string | undefined {
   return scalarTypeDescriptors.get(field.typeName);
 }
 
 function resolveNonRelationField(
-  field: PslField,
+  field: FieldSymbol,
   ownerName: string,
   compositeTypeNames: ReadonlySet<string>,
   scalarTypeDescriptors: ReadonlyMap<string, string>,
+  codecIdByEnumName: ReadonlyMap<string, string>,
   sourceId: string,
   diagnostics: ContractSourceDiagnostic[],
 ): ContractField | undefined {
@@ -830,6 +855,29 @@ function resolveNonRelationField(
     return field.list ? { ...result, many: true } : result;
   }
 
+  // If this field's declared type is a known enum name, treat the field as a scalar
+  // with that enum's codec and stamp the domain valueSet ref.
+  const enumCodecId = codecIdByEnumName.get(field.typeName);
+  if (enumCodecId !== undefined) {
+    const valueSet: ValueSetRef = {
+      plane: 'domain',
+      entityKind: 'enum',
+      namespaceId: UNBOUND_NAMESPACE_ID,
+      entityName: field.typeName,
+    };
+    const result: ContractField = {
+      type: { kind: 'scalar', codecId: enumCodecId },
+      nullable: field.optional,
+      valueSet,
+    };
+    return field.list ? { ...result, many: true } : result;
+  }
+
+  // Avoid cascading unsupported-type diagnostics after invalid qualification.
+  if (field.malformedType) {
+    return undefined;
+  }
+
   const codecId = resolveFieldCodecId(field, scalarTypeDescriptors);
   if (!codecId) {
     diagnostics.push({
@@ -848,27 +896,106 @@ function resolveNonRelationField(
   return field.list ? { ...result, many: true } : result;
 }
 
+function processEnumDeclarations(input: {
+  readonly enumBlocks: readonly PslExtensionBlock[];
+  readonly sourceId: string;
+  readonly authoringContributions: AuthoringContributions | undefined;
+  readonly entityContext: AuthoringEntityContext;
+  readonly diagnostics: ContractSourceDiagnostic[];
+}): Record<string, ContractEnum> {
+  const builtEnums: Record<string, ContractEnum> = {};
+
+  if (input.enumBlocks.length === 0) return builtEnums;
+
+  const enumDescriptor =
+    input.authoringContributions?.entityTypes?.['enum'] !== undefined &&
+    isAuthoringEntityTypeDescriptor(input.authoringContributions.entityTypes['enum'])
+      ? input.authoringContributions.entityTypes['enum']
+      : undefined;
+
+  if (!enumDescriptor) {
+    for (const decl of input.enumBlocks) {
+      input.diagnostics.push({
+        code: 'PSL_ENUM_MISSING_FACTORY',
+        message: `enum "${decl.name}" requires an "enum" entityType factory in the active authoring contributions`,
+        sourceId: input.sourceId,
+        span: decl.span,
+      });
+    }
+    return builtEnums;
+  }
+
+  for (const decl of input.enumBlocks) {
+    const handle = instantiateAuthoringEntityType<EnumTypeHandle | undefined>(
+      'enum',
+      enumDescriptor,
+      [decl],
+      input.entityContext,
+    );
+
+    if (handle === undefined || handle === null) continue;
+
+    builtEnums[decl.name] = {
+      codecId: handle.codecId,
+      members: handle.enumMembers.map((m) => ({
+        name: m.name,
+        value: blindCast<JsonValue, 'factory-validated enum members are JsonValue-compatible'>(
+          m.value,
+        ),
+      })),
+    };
+  }
+
+  return builtEnums;
+}
+
 export function interpretPslDocumentToMongoContract(
   input: InterpretPslDocumentToMongoContractInput,
 ): Result<Contract, ContractSourceDiagnostics> {
-  const { document, scalarTypeDescriptors, codecLookup } = input;
-  const sourceId = document.ast.sourceId;
-  const diagnostics: ContractSourceDiagnostic[] = [];
+  const { symbolTable, sourceFile, scalarTypeDescriptors, codecLookup } = input;
+  const sourceId = input.sourceId;
+  const diagnostics: ContractSourceDiagnostic[] = [...(input.seedDiagnostics ?? [])];
+  const topLevel = symbolTable.topLevel;
   validateNamespaceBlocksForMongoTarget({
-    namespaces: document.ast.namespaces,
+    namespaces: Object.values(topLevel.namespaces),
     sourceId,
+    sourceFile,
     diagnostics,
   });
-  // Mongo lowers only the implicit `__unspecified__` bucket today —
-  // explicit `namespace { … }` blocks were rejected above. The IR
-  // collection map remains flat (and the Mongo target represents
-  // databases via `MongoTargetDatabase`, populated at compose time by
-  // the connection string rather than authoring-time PSL).
-  const allModels = document.ast.namespaces.flatMap((ns) => ns.models);
-  const allCompositeTypes = document.ast.namespaces.flatMap((ns) => ns.compositeTypes);
+  const allModels: ModelSymbol[] = Object.values(topLevel.models);
+  const allCompositeTypes: CompositeTypeSymbol[] = Object.values(topLevel.compositeTypes);
   const modelNames = new Set(allModels.map((m) => m.name));
   const compositeTypeNames = new Set(allCompositeTypes.map((ct) => ct.name));
 
+  const topLevelEnumBlocks = Object.values(topLevel.blocks)
+    .filter((b) => b.keyword === 'enum')
+    .map((b) => b.block);
+
+  const builtEnums = processEnumDeclarations({
+    enumBlocks: topLevelEnumBlocks,
+    sourceId,
+    authoringContributions: input.authoringContributions,
+    entityContext: {
+      family: 'mongo',
+      target: 'mongo',
+      ...ifDefined('enumInferenceCodecs', input.enumInferenceCodecs),
+      ...ifDefined('codecLookup', codecLookup),
+      sourceId,
+      diagnostics: {
+        push: (d) => {
+          diagnostics.push(
+            blindCast<ContractSourceDiagnostic, 'sink diagnostics are span-compatible'>(d),
+          );
+        },
+      },
+    },
+    diagnostics,
+  });
+
+  const codecIdByEnumName: Map<string, string> = new Map(
+    Object.entries(builtEnums).map(([name, e]) => [name, e.codecId]),
+  );
+
   const models: Record<string, MongoModelEntry> = {};
   const collections: Record<string, Record<string, unknown>> = {};
   const roots: Record<string, CrossReference> = {};
@@ -882,7 +1009,7 @@ export function interpretPslDocumentToMongoContract(
     readonly targetModelName: string;
     readonly relationName?: string;
     readonly cardinality: '1:1' | '1:N';
-    readonly field: PslField;
+    readonly field: FieldSymbol;
   }
   const backrelationCandidates: BackrelationCandidate[] = [];
 
@@ -893,7 +1020,7 @@ export function interpretPslDocumentToMongoContract(
     const fields: Record<string, ContractField> = {};
     const relations: Record<string, ContractReferenceRelation> = {};
 
-    for (const field of pslModel.fields) {
+    for (const field of Object.values(pslModel.fields)) {
       if (isRelationField(field, modelNames)) {
         const relation = parseRelationAttribute(field.attributes);
 
@@ -902,9 +1029,7 @@ export function interpretPslDocumentToMongoContract(
             modelName: pslModel.name,
             fieldName: field.name,
             targetModelName: field.typeName,
-            ...(relation?.relationName !== undefined
-              ? { relationName: relation.relationName }
-              : {}),
+            ...ifDefined('relationName', relation?.relationName),
             cardinality: field.list ? '1:N' : '1:1',
             field,
           });
@@ -933,7 +1058,7 @@ export function interpretPslDocumentToMongoContract(
             declaringModel: pslModel.name,
             fieldName: field.name,
             targetModel: field.typeName,
-            ...(relation.relationName !== undefined ? { relationName: relation.relationName } : {}),
+            ...ifDefined('relationName', relation.relationName),
             localFields: localMapped,
             targetFields: targetMapped,
           });
@@ -946,6 +1071,7 @@ export function interpretPslDocumentToMongoContract(
         pslModel.name,
         compositeTypeNames,
         scalarTypeDescriptors,
+        codecIdByEnumName,
         sourceId,
         diagnostics,
       );
@@ -956,7 +1082,9 @@ export function interpretPslDocumentToMongoContract(
     }
 
     const isVariantModel = pslModel.attributes.some((attr) => attr.name === 'base');
-    const hasIdField = pslModel.fields.some((f) => getAttribute(f.attributes, 'id') !== undefined);
+    const hasIdField = Object.values(pslModel.fields).some(
+      (f) => getAttribute(f.attributes, 'id') !== undefined,
+    );
     // Variant models inherit the base's identity and are validated through their base.
     if (!isVariantModel) {
       if (!hasIdField) {
@@ -1011,12 +1139,13 @@ export function interpretPslDocumentToMongoContract(
   const valueObjects: Record<string, ContractValueObject> = {};
   for (const compositeType of allCompositeTypes) {
     const fields: Record<string, ContractField> = {};
-    for (const field of compositeType.fields) {
+    for (const field of Object.values(compositeType.fields)) {
       const resolved = resolveNonRelationField(
         field,
         compositeType.name,
         compositeTypeNames,
         scalarTypeDescriptors,
+        codecIdByEnumName,
         sourceId,
         diagnostics,
       );
@@ -1078,7 +1207,7 @@ export function interpretPslDocumentToMongoContract(
   }
 
   const { discriminatorDeclarations, baseDeclarations } = collectPolymorphismDeclarations(
-    document,
+    allModels,
     sourceId,
     diagnostics,
   );
@@ -1086,7 +1215,7 @@ export function interpretPslDocumentToMongoContract(
     models,
     roots,
     collections,
-    document,
+    allModels,
     discriminatorDeclarations,
     baseDeclarations,
     modelNames,
@@ -1105,6 +1234,28 @@ export function interpretPslDocumentToMongoContract(
   const resolvedModels = polyResult.models;
   const resolvedCollections = polyResult.collections;
 
+  // The storage value set is the source of truth for both the emit typing and the validator's
+  // `enum` keyword. Built once, ahead of validator derivation, from each enum's codec-encoded member
+  // values (mirroring SQL's build-contract). Encoding needs the codec lookup; production always
+  // threads it (the CLI control stack supplies it), so its absence when enums exist is a wiring bug,
+  // not a runtime input to tolerate.
+  const storageValueSets: Record<string, MongoValueSetInput> = {};
+  const enumEntries = Object.entries(builtEnums);
+  if (enumEntries.length > 0) {
+    assertDefined(
+      codecLookup,
+      'Mongo PSL interpretation requires a codec lookup to encode enum values',
+    );
+    for (const [enumName, builtEnum] of enumEntries) {
+      storageValueSets[enumName] = {
+        kind: 'valueSet',
+        values: builtEnum.members.map((m) =>
+          encodeEnumValue(m.value, builtEnum.codecId, codecLookup),
+        ),
+      };
+    }
+  }
+
   for (const [, modelEntry] of Object.entries(resolvedModels)) {
     if (modelEntry.base) continue;
 
@@ -1125,9 +1276,15 @@ export function interpretPslDocumentToMongoContract(
         variantEntries,
         valueObjects,
         codecLookup,
+        storageValueSets,
       );
     } else {
-      coll['validator'] = deriveJsonSchema(modelEntry.fields, valueObjects, codecLookup);
+      coll['validator'] = deriveJsonSchema(
+        modelEntry.fields,
+        valueObjects,
+        codecLookup,
+        storageValueSets,
+      );
     }
   }
 
@@ -1144,18 +1301,27 @@ export function interpretPslDocumentToMongoContract(
       'arktype-validated JSON shapes satisfy MongoCollectionInput by construction'
     >(raw);
   }
+  const hasValueSets = Object.keys(storageValueSets).length > 0;
+
   const unboundNamespace = buildMongoNamespace({
     id: UNBOUND_NAMESPACE_ID,
-    entries: { collection: collectionInputs },
+    entries: {
+      collection: collectionInputs,
+      ...(hasValueSets ? { valueSet: storageValueSets } : {}),
+    },
   });
-  // Hash the constructed (normalized) collection map, not the raw input
-  // literals — persisted storageHash values were computed over the
-  // constructed form.
+  // Hash the constructed (normalized) entries, not the raw input literals —
+  // persisted storageHash values were computed over the constructed form.
   const storageWithoutHash = {
     namespaces: {
       [UNBOUND_NAMESPACE_ID]: {
         id: UNBOUND_NAMESPACE_ID,
-        entries: { collection: unboundNamespace.entries.collection },
+        entries: {
+          collection: unboundNamespace.entries.collection,
+          ...(unboundNamespace.entries.valueSet !== undefined
+            ? { valueSet: unboundNamespace.entries.valueSet }
+            : {}),
+        },
       },
     },
   };
@@ -1173,6 +1339,8 @@ export function interpretPslDocumentToMongoContract(
   }) as Contract['storage'];
   const capabilities: Record<string, Record<string, boolean>> = {};
 
+  const hasEnums = Object.keys(builtEnums).length > 0;
+
   return ok({
     targetFamily,
     target,
@@ -1182,6 +1350,7 @@ export function interpretPslDocumentToMongoContract(
         [UNBOUND_NAMESPACE_ID]: {
           models: polyResult.models,
           ...(Object.keys(valueObjects).length > 0 ? { valueObjects } : {}),
+          ...(hasEnums ? { enum: builtEnums } : {}),
         },
       },
     },