@wildo-ai/saas-backend-lib 1.0.1

package/src/databases/services/zod-to-mongoose-schema-convertor.backend.service.ts

@@ -0,0 +1,2486 @@
+import { injectable, inject } from 'inversify';
+import { Schema, Model, Document, Connection, Types } from 'mongoose';
+import { z } from 'zod';
+import {
+  ResourceConfiguration,
+  ResourceType,
+
+  CoreResourceOperation,
+  CoreResourceType,
+  ErrorType,
+  ErrorCustomMessageReference,
+} from '@wildo-ai/saas-models';
+
+
+import {
+  isZodPipe,
+  getPipeInputSchema,
+  isZodObject,
+  getZodType,
+  EnumLikeType,
+  hasZodType,
+  isZodArray,
+  isZodOptional,
+  isZodNullable,
+  isZodDefault,
+  getZodDefSchemaProperty,
+  getZodDefArrayProperty,
+  getZodDefStringProperty,
+  getZodDefFunctionProperty,
+  getZodDefProperty,
+  getZodDef,
+  getZodObjectShape,
+  isZodTransform,
+  isZodCustom,
+  isZodTuple,
+  isDiscriminatedUnion,
+  isZodUnion,
+  isZodIntersection,
+  isZodLiteral,
+  isZodLazy,
+  isZodTypeAny,
+  isZodRecord,
+  isZodSet,
+  isDBIndexed,
+  isForeignKey,
+  unwrapSchema,
+  getEnumValues,
+  isUnique,
+  getUniqueParams,
+  UniqueFieldParams,
+  isPrimaryKey,
+  hasTtl,
+  getTtlParams,
+  TtlFieldParams,
+} from '@wildo-ai/zod-decorators';
+
+import {
+  SCHEMA_DEFAULT_OPTIONS,
+  SCHEMA_SUBDOCUMENT_OPTIONS,
+  initModelFromSchema
+} from './db-utils';
+
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+
+
+/**
+ * Interface for union inheritance schema information (not model instances)
+ * Represents different inheritance options in a discriminated union
+ */
+export interface UnionInheritance_SchemaInfo {
+  discriminatorKey: string;
+  discriminatorValue: string;
+  schema: Schema;
+  zodSchema: z.ZodTypeAny;
+}
+
+/**
+ * Options for schema conversion
+ */
+export interface SchemaConversionOptions {
+  includeIndexes?: boolean;
+  applyDefaults?: boolean;
+  maxDepth?: number;
+  connection?: Connection; // optional connection to bind model creation
+}
+
+/**
+ * Info for unique index application
+ */
+export interface UniqueIndexInfo {
+  path: string;
+  params: UniqueFieldParams;
+}
+
+/**
+ * Info for TTL (Time To Live) index application.
+ * MongoDB will automatically delete documents when the TTL expires.
+ */
+export interface TtlIndexInfo {
+  path: string;
+  params: TtlFieldParams;
+}
+
+/**
+ * Interface for generated model information (for debugging)
+ */
+export interface GeneratedModelInfo {
+  resourceType: ResourceType;
+  modelName: string;
+  mainModel: Model<any & Document>;
+  inheritanceSchemas: UnionInheritance_SchemaInfo[];
+  inheritanceModels: Model<any & Document>[];
+  schemaFieldCount: number;
+  indexCount: number;
+  conversionOptions: SchemaConversionOptions;
+  createdAt: Date;
+}
+
+/**
+ * Debug statistics for model generation
+ */
+export interface ModelGenerationStats {
+  totalResources: number;
+  totalMainModels: number;
+  totalInheritanceModels: number;
+  totalSchemaFields: number;
+  totalIndexes: number;
+  resourceTypes: ResourceType[];
+  conversionTime: number;
+}
+
+/**
+ * Service for converting Zod schemas to Mongoose schemas
+ * Handles decorators for database indexing and resource references
+ * Supports discriminated unions and complex nested objects
+ *
+ * IMPORTANT: This service is STATELESS and does NOT create inheritance models
+ * to avoid global state mutations. Use the returned schemas to create models externally.
+ *
+ * Features unified error handling with ErrorBuilderBackendService for schema conversion errors.
+ */
+@injectable()
+export class ZodToMongooseSchemaConvertorBackendService {
+
+  // =================================================================
+  // CONSTRUCTOR AND CONFIGURATION
+  // =================================================================
+
+  private readonly DEFAULT_MAX_DEPTH = 25;
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private errorBuilder: ErrorBuilderBackendService
+  ) {
+    this.logDebug = this.logger.debugByType('ZodToMongooseSchemaConvertorBackendService');
+    this.logger.setDebugTypeLogging('ZodToMongooseSchemaConvertorBackendService', false);
+  }
+
+  // =================================================================
+  // PUBLIC API METHODS
+  // =================================================================
+
+  /**
+   * Converts a ResourceConfiguration to a Mongoose model
+   * @param resourceConfiguration The resource configuration containing the schema
+   * @param options Conversion options
+   * @returns Object containing the main model and union inheritance schema information
+   * @throws Error if schema conversion fails
+   */
+  /**
+   * NOTE: TDatabaseSchema has been removed. Backend-only fields are now marked with
+   * the `isBackendOnly` decorator on mainSchema and handled at the service layer.
+   */
+  convertResourceConfigurationToModel<
+    TCustomOperationEnum extends EnumLikeType | undefined,
+    TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined,
+    TMainSchema extends z.ZodTypeAny
+  >(
+    resourceConfiguration: ResourceConfiguration<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    options: SchemaConversionOptions = {}
+  ): {
+    mainModel: Model<any & Document>;
+    inheritanceSchemas: UnionInheritance_SchemaInfo[];
+  } {
+
+    const startTime = Date.now();
+
+
+    if (!resourceConfiguration) {
+      const error = this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        { customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED }
+      );
+      throw error;
+    }
+
+    if (!resourceConfiguration.mainSchema) {
+      const error = this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        { customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED, }
+      );
+      throw error;
+    }
+
+    // NOTE: databaseSchema was removed - mainSchema now contains all fields including backend-only (marked with isBackendOnly decorator)
+    const schemaToConvert = resourceConfiguration.mainSchema;
+    const modelLabel = resourceConfiguration.resourceIdentifier as string;
+
+
+
+    // Get the collection name (may be different from model name for USER_SELF_* resources)
+    const collectionName = this.getCollectionNameForResource(resourceConfiguration.resourceIdentifier);
+
+    if (!modelLabel) {
+      const error = this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        { customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED }
+      );
+      throw error;
+    }
+
+    try {
+      // Convert Zod schema to Mongoose schema with clean state
+      const conversionResult = this.convertZodSchemaToMongooseSchemaWithCleanup(
+        schemaToConvert,
+        options,
+        resourceConfiguration
+      );
+
+      // Initialize main model with custom collection name if different from model name and optional connection
+      const mainModel = initModelFromSchema(
+        conversionResult.mongooseSchema,
+        modelLabel,
+        collectionName,
+        options.connection
+      );
+
+      // Log debug information if debug logging is enabled
+      this.logDebug(`Converted schema for resource '${modelLabel}'`, {
+        resourceType: resourceConfiguration.resourceIdentifier,
+        modelName: modelLabel,
+        schemaFieldCount: this.countSchemaFields(conversionResult.mongooseSchema),
+        indexCount: conversionResult.mongooseSchema.indexes().length,
+        inheritanceCount: conversionResult.inheritanceSchemas.length,
+        conversionTime: Date.now() - startTime,
+        conversionOptions: options
+      });
+
+      return {
+        mainModel,
+        inheritanceSchemas: conversionResult.inheritanceSchemas
+      };
+    } catch (error) {
+      const conversionError = this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED,
+          context: {
+            resourceType: resourceConfiguration.resourceIdentifier,
+            modelLabel,
+            originalError: error instanceof Error ? error.message : (typeof error === 'object' ? JSON.stringify(error, null, 2) : String(error))
+          }
+        }
+      );
+      throw conversionError;
+    }
+  }
+
+  /**
+   * Creates a Mongoose model directly from a Zod schema (utility method)
+   * @param zodSchema The Zod schema
+   * @param modelName The name for the model
+   * @param options Conversion options
+   * @returns Object containing the main model and union inheritance schemas
+   * @throws Error if schema conversion fails
+   */
+  createModelFromZodSchema(
+    zodSchema: z.ZodTypeAny,
+    modelName: string,
+    options: SchemaConversionOptions = {}
+  ): {
+    mainModel: Model<any & Document>;
+    inheritanceSchemas: UnionInheritance_SchemaInfo[];
+  } {
+
+    if (!zodSchema) {
+      const error = this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        { customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED }
+      );
+      throw error;
+    }
+
+    if (!modelName || typeof modelName !== 'string') {
+      const error = this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        { customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED }
+      );
+      throw error;
+    }
+
+    try {
+      const conversionResult = this.convertZodSchemaToMongooseSchemaWithCleanup(zodSchema, options, undefined);
+      const mainModel = initModelFromSchema(conversionResult.mongooseSchema, modelName);
+
+      this.logDebug(`Created model from Zod schema '${modelName}'`, {
+        modelName,
+        schemaFieldCount: this.countSchemaFields(conversionResult.mongooseSchema),
+        indexCount: conversionResult.mongooseSchema.indexes().length,
+        inheritanceCount: conversionResult.inheritanceSchemas.length,
+        conversionOptions: options
+      });
+
+      return {
+        mainModel,
+        inheritanceSchemas: conversionResult.inheritanceSchemas
+      };
+    } catch (error) {
+      const modelError = this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_MODEL_BUILD_FAILED,
+          context: {
+            modelName,
+            originalError: error instanceof Error ? error.message : (typeof error === 'object' ? JSON.stringify(error, null, 2) : String(error))
+          }
+        }
+      );
+      throw modelError;
+    }
+  }
+
+  /**
+   * Creates inheritance models from union inheritance schemas
+   * This is a separate method to allow external control over model creation
+   * @param unionRootModel The union root model (base for all inheritance options)
+   * @param inheritanceSchemas The union inheritance schemas to create models from
+   * @returns Array of created inheritance models
+   */
+  createInheritanceModels(
+    unionRootModel: Model<any & Document>,
+    inheritanceSchemas: UnionInheritance_SchemaInfo[]
+  ): Model<any & Document>[] {
+
+    const models: Model<any & Document>[] = [];
+
+    for (const inheritanceSchema of inheritanceSchemas) {
+      try {
+        const inheritanceModelName = `${unionRootModel.modelName}_${inheritanceSchema.discriminatorValue}`;
+        const inheritanceModel = unionRootModel.discriminator(inheritanceModelName, inheritanceSchema.schema);
+        models.push(inheritanceModel);
+      } catch (error) {
+        this.logger.warn(`Failed to create inheritance model for value '${inheritanceSchema.discriminatorValue}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    this.logDebug(`Created inheritance models for union root model '${unionRootModel.modelName}'`, {
+      unionRootModelName: unionRootModel.modelName,
+      inheritanceModelsCount: models.length,
+      inheritanceValues: inheritanceSchemas.map(s => s.discriminatorValue)
+    });
+
+    return models;
+  }
+
+  // =================================================================
+  // MAIN CONVERSION METHODS
+  // =================================================================
+
+  /**
+   * Converts a Zod schema to a Mongoose schema with proper cleanup
+   * @param zodSchema The Zod schema to convert
+   * @param options Conversion options
+   * @returns Object containing mongoose schema and union inheritance information
+   */
+  private convertZodSchemaToMongooseSchemaWithCleanup(
+    zodSchema: z.ZodTypeAny,
+    options: SchemaConversionOptions = {},
+    resourceConfiguration?: any
+  ): {
+    mongooseSchema: Schema;
+    inheritanceSchemas: UnionInheritance_SchemaInfo[];
+  } {
+
+    if (!zodSchema) {
+      const error = this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        { customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED }
+      );
+      throw error;
+    }
+
+    const maxDepth = options.maxDepth || this.DEFAULT_MAX_DEPTH;
+    const processedSchemas = new WeakSet<z.ZodTypeAny>();
+    const schemaCache = new WeakMap<z.ZodTypeAny, Schema>();
+    const inheritanceSchemas: UnionInheritance_SchemaInfo[] = [];
+    const indexesToApply: string[] = [];
+    const uniqueIndexesToApply: UniqueIndexInfo[] = [];
+    const ttlIndexesToApply: TtlIndexInfo[] = [];
+
+    try {
+      // Convert Zod schema to Mongoose schema definition
+      const schemaDefinition = this.convertZodTypeToMongooseDefinition(
+        zodSchema,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        '',
+        0,
+        maxDepth
+      );
+
+
+
+
+
+      // Remove discriminatorKey from schema definition if present (it's not a valid Mongoose field type)
+      // discriminatorKey is used for model-level discriminator configuration, not schema definition
+      const { discriminatorKey, ...cleanSchemaDefinition } = schemaDefinition as any;
+
+      // CRDT field-level metadata — schemaless Mixed field for per-field LWW timestamps.
+      // Only populated for resources that have isCRDT() fields.
+      cleanSchemaDefinition._field_meta = { type: Schema.Types.Mixed };
+
+      // Create the Mongoose schema
+      const mongooseSchema = new Schema(cleanSchemaDefinition, SCHEMA_DEFAULT_OPTIONS);
+
+      // Apply standard transforms (convert ObjectId to string in toObject/toJSON)
+      this.applyStandardTransforms(mongooseSchema);
+
+      // Apply indexes if enabled
+      if (options.includeIndexes !== false) {
+        this.applyIndexesToSchema(mongooseSchema, indexesToApply, uniqueIndexesToApply, ttlIndexesToApply);
+      }
+
+      return {
+        mongooseSchema,
+        inheritanceSchemas
+      };
+    } catch (error) {
+      // Cleanup
+      inheritanceSchemas.length = 0;
+      indexesToApply.length = 0;
+      ttlIndexesToApply.length = 0;
+      uniqueIndexesToApply.length = 0;
+
+      const conversionError = this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.ZOD_CONVERTER_SCHEMA_CONVERSION_FAILED,
+          context: {
+            originalError: error instanceof Error ? error.message : (typeof error === 'object' ? JSON.stringify(error, null, 2) : String(error)),
+            maxDepth: options.maxDepth
+          }
+        }
+      );
+      throw conversionError;
+    }
+  }
+
+  /**
+   * Converts a Zod type to a Mongoose schema definition
+   * @param zodType The Zod type to convert
+   * @param processedSchemas Set to track circular references
+   * @param inheritanceSchemas Array to collect union inheritance schemas
+   * @param indexesToApply Array to collect index paths
+   * @param uniqueIndexesToApply Array to collect unique index paths with params
+   * @param ttlIndexesToApply Array to collect TTL index paths with params
+   * @param currentPath Current object path for indexing
+   * @param currentDepth Current recursion depth
+   * @param maxDepth Maximum allowed recursion depth
+   * @returns The Mongoose schema definition
+   */
+  private convertZodTypeToMongooseDefinition(
+    zodType: z.ZodTypeAny,
+    processedSchemas: WeakSet<z.ZodTypeAny>,
+    schemaCache: WeakMap<z.ZodTypeAny, Schema>,
+    inheritanceSchemas: UnionInheritance_SchemaInfo[],
+    indexesToApply: string[],
+    uniqueIndexesToApply: UniqueIndexInfo[],
+    ttlIndexesToApply: TtlIndexInfo[],
+    currentPath: string = '',
+    currentDepth: number = 0,
+    maxDepth: number = 10
+  ): any {
+
+
+
+    // Depth check
+    if (currentDepth >= maxDepth) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    try {
+      // Handle pipe types (from .transform(), .pipe(), etc.) - unwrap to input schema
+      // In Zod v4, transforms create pipe types with 'in' and 'out' schemas
+      if (isZodPipe(zodType)) {
+        const inputSchema = getPipeInputSchema(zodType);
+        if (inputSchema) {
+          // For pipe types, recursively process the input schema
+        return this.convertZodTypeToMongooseDefinition(
+            inputSchema,
+          processedSchemas,
+          schemaCache,
+          inheritanceSchemas,
+          indexesToApply,
+          uniqueIndexesToApply,
+          ttlIndexesToApply,
+          currentPath,
+          currentDepth,
+          maxDepth
+        );
+        }
+      }
+
+      // Handle ZodObject (main case for resource schemas)
+      // In Zod v4, object schemas have type: "object"
+      if (isZodObject(zodType)) {
+
+        // Check cache for existing schema to handle recursion
+        if (schemaCache.has(zodType)) {
+          return schemaCache.get(zodType);
+        }
+
+        // Create a new Schema instance immediately to allow self-reference
+        // We use a temporary empty definition, then add paths to it
+        const newSchema = new Schema({}, SCHEMA_SUBDOCUMENT_OPTIONS);
+        schemaCache.set(zodType, newSchema);
+
+        // Use public .shape property (Zod v4 API)
+        const shape = getZodObjectShape(zodType);
+
+
+
+        const mongooseDefinition: any = {};
+
+        for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+          if (fieldName.startsWith('$') || typeof fieldSchema !== 'object' || fieldSchema === null) {
+            if (fieldName.startsWith('$')) {
+              this.logger.warn(`[ZodToMongoose] Skipping '$'-prefixed key '${fieldName}' (value type: ${typeof fieldSchema}) at path='${currentPath}'. Assumed Zod internal — if this is a user field, the filter is incorrect.`);
+            }
+            continue;
+          }
+
+          const fieldPath = currentPath ? `${currentPath}.${fieldName}` : fieldName;
+
+          const fieldDefinition = this.convertZodFieldToMongooseField(
+            fieldSchema as z.ZodTypeAny,
+            processedSchemas,
+            schemaCache,
+            inheritanceSchemas,
+            indexesToApply,
+            uniqueIndexesToApply,
+            ttlIndexesToApply,
+            fieldPath,
+            currentDepth + 1,
+            maxDepth
+          );
+
+          // Safety check: ensure field definition is valid
+          if (!fieldDefinition || typeof fieldDefinition !== 'object' ||
+            (!fieldDefinition.type && !Array.isArray(fieldDefinition) && typeof fieldDefinition !== 'object')) {
+            this.logger.warn(`[ZodToMongoose] Invalid field definition for ${fieldPath}`, { fieldDefinition });
+            this.logger.warn(`[ZodToMongoose] Zod field type was: ${typeof fieldSchema}`);
+            mongooseDefinition[fieldName] = { type: Schema.Types.Mixed };
+          } else {
+            // CRITICAL: If fieldDefinition is a Schema instance (from nested object),
+            // wrap it in { type: ... } to prevent Mongoose from iterating over its properties
+            if (this.isSchemaLike(fieldDefinition)) {
+              mongooseDefinition[fieldName] = {
+                type: fieldDefinition,
+                _id: false
+              };
+            } else {
+              mongooseDefinition[fieldName] = fieldDefinition;
+            }
+          }
+        }
+
+        // Final validation: ensure all fields have proper type properties
+        // Only validate at depth 0 (top-level). Nested objects will be validated by Mongoose
+        // when they're added to their parent schema
+        if (currentDepth === 0) {
+          this.validateAndFixFieldTypes(mongooseDefinition, 'unknown');
+        }
+
+        // If this is the top-level call (depth 0), we return the definition object
+        // so the caller can create the main Schema.
+        // If this is a nested object (depth > 0), we return the Schema instance we created.
+        if (currentDepth === 0) {
+          return mongooseDefinition;
+        } else {
+          newSchema.add(mongooseDefinition);
+          this.applyStandardTransforms(newSchema);
+          return newSchema;
+        }
+      }
+
+      // For non-object types, convert as field
+      return this.convertZodFieldToMongooseField(
+        zodType,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+    } catch (error) {
+      processedSchemas.delete(zodType);
+      this.logger.error(`[ZodToMongoose] convertZodTypeToMongooseDefinition FAILED at path='${currentPath}', depth=${currentDepth}: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }
+
+  // =================================================================
+  // FIELD CONVERSION METHODS
+  // =================================================================
+
+  /**
+   * Converts a single Zod field to a Mongoose field definition
+   * @param zodField The Zod field schema
+   * @param processedSchemas Set to track circular references
+   * @param inheritanceSchemas Array to collect union inheritance schemas
+   * @param indexesToApply Array to collect index paths
+   * @param ttlIndexesToApply Array to collect TTL index paths
+   * @param currentPath Current field path
+   * @param currentDepth Current recursion depth
+   * @param maxDepth Maximum allowed recursion depth
+   * @returns The Mongoose field definition
+   */
+  private convertZodFieldToMongooseField(
+    zodField: z.ZodTypeAny,
+    processedSchemas: WeakSet<z.ZodTypeAny>,
+    schemaCache: WeakMap<z.ZodTypeAny, Schema>,
+    inheritanceSchemas: UnionInheritance_SchemaInfo[],
+    indexesToApply: string[],
+    uniqueIndexesToApply: UniqueIndexInfo[],
+    ttlIndexesToApply: TtlIndexInfo[],
+    currentPath: string,
+    currentDepth: number,
+    maxDepth: number
+  ): any {
+
+    // Special handling for _id fields - always convert to ObjectId
+    const fieldName = currentPath.split('.').pop() || '';
+    if (fieldName === '_id') {
+      const definition: any = {
+        type: Schema.Types.ObjectId,
+        // Ensure Mongoose can auto-generate _id when not provided
+        default: () => new Types.ObjectId(),
+        required: false
+      };
+
+      return definition;
+    }
+
+    // Unwrap optional fields
+    // In Zod v4, optional schemas have type: "optional"
+    if (isZodOptional(zodField)) {
+      const innerType = getZodDefSchemaProperty(zodField, 'innerType');
+      if (!innerType) {
+        return { type: Schema.Types.Mixed, required: false };
+      }
+      const innerField = this.convertZodFieldToMongooseField(
+        innerType,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+      // For optional fields, explicitly ensure they are NOT required
+      if (!innerField || typeof innerField !== 'object') {
+        return { type: Schema.Types.Mixed, required: false };
+      }
+
+      // Handle arrays specially (arrays don't have required property)
+      if (Array.isArray(innerField)) {
+        return innerField; // Arrays don't have required property
+      }
+
+      // CRITICAL: If innerField is a Schema instance (from nested object), wrap it properly
+      // Do NOT destructure Schema instances as this spreads their internal properties
+      if (this.isSchemaLike(innerField)) {
+        return {
+          type: innerField,
+          required: false,
+          _id: false
+        };
+      }
+
+      // Remove any required: true and explicitly set required: false for optional fields
+      const { required, ...optionalField } = innerField;
+
+      // Explicitly set required: false to ensure Mongoose recognizes this as optional
+      const result = Object.keys(optionalField).length === 0 && innerField.type
+        ? { type: innerField.type, required: false }
+        : { ...optionalField, required: false };
+
+      return result;
+    }
+
+    // Unwrap nullable fields
+    // In Zod v4, nullable schemas have type: "nullable"
+    if (isZodNullable(zodField)) {
+      const innerType = getZodDefSchemaProperty(zodField, 'innerType');
+      if (!innerType) {
+        return { type: Schema.Types.Mixed };
+      }
+      const innerField = this.convertZodFieldToMongooseField(
+        innerType,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+      // Ensure we always have at least the type information
+      if (!innerField || typeof innerField !== 'object') {
+        return { type: Schema.Types.Mixed };
+      }
+
+      // CRITICAL: If innerField is a Schema instance (from nested object), wrap it properly
+      // Do NOT destructure Schema instances as this spreads their internal properties
+      if (this.isSchemaLike(innerField)) {
+        return {
+          type: innerField,
+          _id: false
+        };
+      }
+
+      // For nullable fields, we typically don't want required=true
+      const { required, ...nullableField } = innerField;
+      if (Object.keys(nullableField).length === 0 && innerField.type) {
+        return { type: innerField.type };
+      }
+      return nullableField;
+    }
+
+    // Unwrap default fields
+    // In Zod v4, default schemas have type: "default"
+    if (isZodDefault(zodField)) {
+      const defaultValueProp = getZodDefProperty(zodField, 'defaultValue');
+      const defaultValue = typeof defaultValueProp === 'function'
+        ? (defaultValueProp as () => unknown)()
+        : defaultValueProp;
+
+      const innerType = getZodDefSchemaProperty(zodField, 'innerType');
+      if (!innerType) {
+        return { type: Schema.Types.Mixed, default: defaultValue };
+      }
+
+      const innerField = this.convertZodFieldToMongooseField(
+        innerType,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+
+      // Remove required property for fields with defaults (Mongoose treats absence as optional)
+      // Ensure we always have at least the type information
+      if (!innerField || typeof innerField !== 'object') {
+        return { type: Schema.Types.Mixed, default: defaultValue };
+      }
+
+      // Handle arrays BEFORE destructuring (arrays don't have required property)
+      if (Array.isArray(innerField)) {
+        return {
+          type: innerField,
+          default: defaultValue
+        };
+      }
+
+      // CRITICAL: If innerField is a Schema instance (from nested object), wrap it properly
+      // Do NOT destructure Schema instances as this spreads their internal properties
+      if (this.isSchemaLike(innerField)) {
+        return {
+          type: innerField,
+          default: defaultValue,
+          _id: false
+        };
+      }
+
+      const { required, ...fieldWithoutRequired } = innerField;
+
+      // Check if this is a nested object schema (has 'type' property with nested fields)
+      // CRITICAL: Do NOT spread if type is a Schema instance!
+      const isNestedObjectSchema = fieldWithoutRequired.type &&
+        typeof fieldWithoutRequired.type === 'object' &&
+        !Array.isArray(fieldWithoutRequired.type) &&
+        !this.isSchemaLike(fieldWithoutRequired.type) &&
+        Object.keys(fieldWithoutRequired.type).length > 0;
+
+      if (isNestedObjectSchema && defaultValue && typeof defaultValue === 'object') {
+        // For nested objects with defaults, preserve field type definitions
+        // and merge defaults into the appropriate fields
+        const nestedFields = { ...fieldWithoutRequired.type };
+
+        for (const [fieldName, defaultFieldValue] of Object.entries(defaultValue)) {
+          if (nestedFields[fieldName] && typeof nestedFields[fieldName] === 'object') {
+            // Preserve the existing field definition and add the default
+            nestedFields[fieldName] = {
+              ...nestedFields[fieldName],
+              default: defaultFieldValue
+            };
+          }
+        }
+
+        return {
+          type: nestedFields,
+          default: defaultValue,
+          _id: false
+        };
+      }
+
+      // This check is no longer needed since arrays are handled before destructuring
+
+      // Ensure we have at least the type property for primitive fields
+      const result = Object.keys(fieldWithoutRequired).length === 0 && innerField.type
+        ? { type: innerField.type }
+        : fieldWithoutRequired;
+
+      return {
+        ...result,
+        default: defaultValue
+      };
+    }
+
+    // Handle pipe types (from .transform(), .pipe(), etc.) - extract the input schema
+    // In Zod v4, transforms create pipe types with 'in' and 'out' schemas
+    if (isZodPipe(zodField)) {
+      const inputSchema = getPipeInputSchema(zodField);
+      if (inputSchema) {
+      return this.convertZodFieldToMongooseField(
+          inputSchema,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+      }
+    }
+
+    // Handle transform types (standalone transform, no underlying schema)
+    // In Zod v4, transform types are standalone
+    if (isZodTransform(zodField)) {
+      // Transform types don't have an underlying schema, return Mixed
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Handle custom types (from .refine(), .superRefine(), etc.)
+    // In Zod v4, custom types don't wrap schemas - refinements are stored as checks
+    // For custom types, we need to check if there's an underlying schema
+    // This is complex - for now, return Mixed
+    if (isZodCustom(zodField)) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Handle arrays
+    // In Zod v4, array schemas have type: "array"
+    if (isZodArray(zodField)) {
+      const element = getZodDefSchemaProperty(zodField, 'element');
+      if (!element) {
+        return [{ type: Schema.Types.Mixed }];
+      }
+
+      const elementType = this.convertZodFieldToMongooseField(
+        element,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        `${currentPath}[]`,
+        currentDepth + 1,
+        maxDepth
+      );
+
+      // Check for array-level decorators before returning
+      let arrayDefinition: any = [elementType];
+
+      // Handle array-level resource reference (convert array elements to ObjectId)
+      if (isForeignKey(zodField)) {
+        arrayDefinition = [{
+          type: Schema.Types.ObjectId
+        }];
+      }
+
+      // Collect index information for decorated array fields
+      // Skip primary keys - they're already indexed via unique index or field-level index
+      if (isDBIndexed(zodField) && !isPrimaryKey(zodField) && currentPath) {
+        indexesToApply.push(currentPath);
+      }
+
+      // Collect unique index information for array fields
+      if (isUnique(zodField) && currentPath) {
+        const uniqueParams = getUniqueParams(zodField);
+        uniqueIndexesToApply.push({ path: currentPath, params: uniqueParams || {} });
+      }
+
+      // Collect TTL index information for array fields (rare, but possible for array of dates)
+      if (hasTtl(zodField) && currentPath) {
+        const ttlParams = getTtlParams(zodField);
+        if (ttlParams) {
+          ttlIndexesToApply.push({ path: currentPath, params: ttlParams });
+        }
+      }
+
+      return arrayDefinition;
+    }
+
+    // Handle tuples
+    // In Zod v4, tuple schemas have type: "tuple"
+    if (isZodTuple(zodField)) {
+      return [{ type: Schema.Types.Mixed }];
+    }
+
+    // Handle nested objects
+    // In Zod v4, object schemas have type: "object"
+    if (isZodObject(zodField)) {
+      const nestedDefinition = this.convertZodTypeToMongooseDefinition(
+        zodField,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+
+      // If nestedDefinition is a Schema instance (from cache or new), return it directly as type
+      if (nestedDefinition instanceof Schema) {
+        return {
+          type: nestedDefinition,
+          _id: false
+        };
+      }
+
+      // Otherwise wrap the definition
+      return {
+        type: nestedDefinition,
+        _id: false // Disable automatic _id for subdocuments unless explicitly defined
+      };
+    }
+
+    // Handle discriminated unions
+    // Mongoose discriminators only work on top-level models, NOT on embedded sub-documents.
+    // At depth 0 we collect schema info for later discriminator model creation.
+    // At depth > 0 we flatten into a superset schema (all fields from all options,
+    // non-discriminator fields optional) so field types and indexes are preserved.
+    if (isDiscriminatedUnion(zodField)) {
+      if (currentDepth === 0) {
+        return this.handleDiscriminatedUnionField(
+          zodField,
+          processedSchemas,
+          schemaCache,
+          inheritanceSchemas,
+          indexesToApply,
+          uniqueIndexesToApply,
+          ttlIndexesToApply,
+          currentPath,
+          currentDepth,
+          maxDepth
+        );
+      }
+      return this.flattenDiscriminatedUnionForSubdocument(
+        zodField,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+    }
+
+    // Handle regular unions - analyze for smart type detection
+    // In Zod v4, union schemas have type: "union"
+    if (isZodUnion(zodField)) {
+      return this.handleZodUnion(zodField);
+    }
+
+    // Handle intersections - merge the types
+    // In Zod v4, intersection schemas have type: "intersection"
+    if (isZodIntersection(zodField)) {
+      const left = getZodDefSchemaProperty(zodField, 'left');
+      const right = getZodDefSchemaProperty(zodField, 'right');
+
+      if (!left || !right) {
+        return { type: Schema.Types.Mixed };
+      }
+
+      const leftDef = this.convertZodFieldToMongooseField(
+        left,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+      const rightDef = this.convertZodFieldToMongooseField(
+        right,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+
+      // Merge object definitions
+      if (this.isObjectDefinition(leftDef) && this.isObjectDefinition(rightDef)) {
+        return { ...leftDef, ...rightDef };
+      }
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Handle literals
+    // In Zod v4, literal schemas have type: "literal"
+    if (isZodLiteral(zodField)) {
+      const literalValue = getZodDefProperty(zodField, 'value');
+      return {
+        type: typeof literalValue === 'string' ? String :
+          typeof literalValue === 'number' ? Number :
+            typeof literalValue === 'boolean' ? Boolean : Schema.Types.Mixed,
+        enum: [literalValue]
+      };
+    }
+
+    // Handle lazy types (recursive schemas)
+    // In Zod v4, lazy schemas have type: "lazy"
+    if (isZodLazy(zodField)) {
+      const getter = getZodDefFunctionProperty(zodField, 'getter');
+      if (!getter) {
+        return { type: Schema.Types.Mixed };
+      }
+      const innerSchema = getter();
+      return this.convertZodFieldToMongooseField(
+        innerSchema,
+        processedSchemas,
+        schemaCache,
+        inheritanceSchemas,
+        indexesToApply,
+        uniqueIndexesToApply,
+        ttlIndexesToApply,
+        currentPath,
+        currentDepth,
+        maxDepth
+      );
+    }
+
+    // Handle basic types with decorators - unwrap to get the core type
+    const coreType = this.unwrapDecoratedType(zodField);
+    const baseDefinition = this.getBaseMongooseType(coreType, schemaCache);
+
+    // Apply resource reference (ObjectId)
+    if (isForeignKey(zodField)) {
+      const definition: any = {
+        type: Schema.Types.ObjectId
+      };
+
+      // Only add required property if the field is actually required
+      if (this.isFieldRequired(zodField)) {
+        definition.required = true;
+      }
+
+      // Collect index information instead of applying immediately
+      // Skip primary keys - they're already indexed via unique index or field-level index
+      if (isDBIndexed(zodField) && !isPrimaryKey(zodField) && currentPath) {
+        indexesToApply.push(currentPath);
+      }
+
+      // Collect unique index information
+      if (isUnique(zodField) && currentPath) {
+        const uniqueParams = getUniqueParams(zodField);
+        uniqueIndexesToApply.push({ path: currentPath, params: uniqueParams || {} });
+      }
+
+      return definition;
+    }
+
+    // Collect TTL index information for Date fields
+    // TTL indexes enable automatic document expiration in MongoDB
+    if (hasTtl(zodField) && currentPath) {
+      const ttlParams = getTtlParams(zodField);
+      if (ttlParams) {
+        ttlIndexesToApply.push({ path: currentPath, params: ttlParams });
+      }
+    }
+
+    // Collect index information for decorated fields
+    // Skip primary keys - they're already indexed via unique index or field-level index
+    if (isDBIndexed(zodField) && !isPrimaryKey(zodField) && currentPath) {
+      indexesToApply.push(currentPath);
+    }
+
+    // Collect unique index information for decorated fields
+    if (isUnique(zodField) && currentPath) {
+      const uniqueParams = getUniqueParams(zodField);
+      uniqueIndexesToApply.push({ path: currentPath, params: uniqueParams || {} });
+    }
+
+    // Only add required property if the field is actually required
+    if (this.isFieldRequired(zodField)) {
+      const definition = baseDefinition || { type: Schema.Types.Mixed };
+      return {
+        ...definition,
+        required: true
+      };
+    }
+
+    return baseDefinition || { type: Schema.Types.Mixed };
+  }
+
+  // =================================================================
+  // TYPE HANDLING METHODS
+  // =================================================================
+
+  /**
+   * Flattens a discriminated union into a superset schema for embedded sub-documents.
+   *
+   * WHY: Mongoose discriminators only work on top-level models (root collections),
+   * NOT on embedded sub-documents or array elements. Attempting to use discriminator
+   * APIs on sub-schemas causes "Invalid schema configuration" errors ($id leak,
+   * initializeTimestamps, etc.).
+   *
+   * CONSEQUENCES OF THIS APPROACH:
+   *  - All fields from ALL union options are merged into one flat schema.
+   *  - The discriminator key stays required; all other fields become optional
+   *    at the Mongoose layer (since each variant uses a different subset).
+   *  - Per-variant required constraints are NOT enforced by Mongoose — Zod handles
+   *    validation at the application layer before data reaches MongoDB.
+   *  - Field types and indexes ARE preserved (unlike Schema.Types.Mixed).
+   *  - First-seen-wins: if two options define the same field with different types,
+   *    only the first option's type is used.
+   *
+   * PREFERRED SOLUTION: When possible, define discriminated unions at the root
+   * resource schema level (depth 0) where Mongoose discriminators work natively.
+   * Use sub-document discriminated unions only when the domain model requires it,
+   * accepting the trade-offs above.
+   */
+  private flattenDiscriminatedUnionForSubdocument(
+    zodField: z.ZodTypeAny,
+    processedSchemas: WeakSet<z.ZodTypeAny>,
+    schemaCache: WeakMap<z.ZodTypeAny, Schema>,
+    inheritanceSchemas: UnionInheritance_SchemaInfo[],
+    indexesToApply: string[],
+    uniqueIndexesToApply: UniqueIndexInfo[],
+    ttlIndexesToApply: TtlIndexInfo[],
+    currentPath: string,
+    currentDepth: number,
+    maxDepth: number
+  ): any {
+    const discriminatorKey = getZodDefStringProperty(zodField, 'discriminator');
+    const optionsArray = getZodDefArrayProperty(zodField, 'options');
+
+    if (!discriminatorKey || !optionsArray || optionsArray.length === 0) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    const options = optionsArray.filter(isZodTypeAny);
+    if (options.length === 0) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    this.logger.warn(
+      `[ZodToMongoose] Discriminated union at path='${currentPath}' (depth=${currentDepth}) is inside a sub-document. ` +
+      `Mongoose discriminators only work on root-level models. Flattening ${options.length} variants into a superset schema ` +
+      `(discriminator='${discriminatorKey}'). Consequences: non-discriminator fields are optional at Mongoose level, ` +
+      `per-variant required constraints rely on Zod validation. Preferred solution: move discriminated unions to root schema level.`
+    );
+
+    const mergedDefinition: Record<string, any> = {};
+
+    for (const option of options) {
+      if (!isZodObject(option)) continue;
+
+      const optionShape = getZodObjectShape(option);
+      for (const [fieldName, fieldSchema] of Object.entries(optionShape)) {
+        const existing = mergedDefinition[fieldName];
+        if (existing) {
+          // Field already seen from a previous variant. Union enum values if both
+          // definitions carry an enum array (e.g. variant field with different enums
+          // per option). Otherwise keep the first definition (same base type).
+          if (Array.isArray(existing.enum) && fieldName !== discriminatorKey) {
+            const fieldPath = currentPath ? `${currentPath}.${fieldName}` : fieldName;
+            const fieldDef = this.convertZodFieldToMongooseField(
+              fieldSchema as z.ZodTypeAny,
+              processedSchemas, schemaCache, inheritanceSchemas,
+              indexesToApply, uniqueIndexesToApply, ttlIndexesToApply,
+              fieldPath, currentDepth + 1, maxDepth
+            );
+            if (fieldDef && Array.isArray(fieldDef.enum)) {
+              existing.enum = [...new Set([...existing.enum, ...fieldDef.enum])];
+            }
+          }
+          continue;
+        }
+
+        const fieldPath = currentPath ? `${currentPath}.${fieldName}` : fieldName;
+        const fieldDef = this.convertZodFieldToMongooseField(
+          fieldSchema as z.ZodTypeAny,
+          processedSchemas,
+          schemaCache,
+          inheritanceSchemas,
+          indexesToApply,
+          uniqueIndexesToApply,
+          ttlIndexesToApply,
+          fieldPath,
+          currentDepth + 1,
+          maxDepth
+        );
+
+        if (fieldName === discriminatorKey) {
+          mergedDefinition[fieldName] = fieldDef;
+        } else if (typeof fieldDef === 'object' && fieldDef !== null && !Array.isArray(fieldDef) && !(fieldDef instanceof Schema)) {
+          mergedDefinition[fieldName] = { ...fieldDef, required: false };
+        } else {
+          mergedDefinition[fieldName] = fieldDef;
+        }
+      }
+    }
+
+    const nestedSchema = new Schema(mergedDefinition, SCHEMA_SUBDOCUMENT_OPTIONS);
+    this.applyStandardTransforms(nestedSchema);
+    return nestedSchema;
+  }
+
+  /**
+   * Handles discriminated union fields by collecting schema information
+   * @param zodField The discriminated union field
+   * @param processedSchemas Set to track circular references
+   * @param inheritanceSchemas Array to collect union inheritance schemas
+   * @param indexesToApply Array to collect index paths
+   * @param currentPath Current field path
+   * @param currentDepth Current recursion depth
+   * @param maxDepth Maximum allowed recursion depth
+   * @returns Base schema definition for the discriminated union
+   */
+  private handleDiscriminatedUnionField(
+    zodField: z.ZodTypeAny,
+    processedSchemas: WeakSet<z.ZodTypeAny>,
+    schemaCache: WeakMap<z.ZodTypeAny, Schema>,
+    inheritanceSchemas: UnionInheritance_SchemaInfo[],
+    indexesToApply: string[],
+    uniqueIndexesToApply: UniqueIndexInfo[],
+    ttlIndexesToApply: TtlIndexInfo[],
+    currentPath: string,
+    currentDepth: number,
+    maxDepth: number
+  ): any {
+
+    const discriminatorKey = getZodDefStringProperty(zodField, 'discriminator');
+    const optionsArray = getZodDefArrayProperty(zodField, 'options');
+
+    if (!discriminatorKey || !optionsArray || optionsArray.length === 0) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Filter and validate options are ZodTypeAny
+    const options = optionsArray.filter(isZodTypeAny);
+    if (options.length === 0) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Use the first option as the union root schema structure
+    const rootOption = options[0];
+    const rootDefinition = this.convertZodTypeToMongooseDefinition(
+      rootOption,
+      processedSchemas,
+      schemaCache,
+      inheritanceSchemas,
+      indexesToApply,
+      uniqueIndexesToApply,
+      ttlIndexesToApply,
+      currentPath,
+      currentDepth,
+      maxDepth
+    );
+
+    // Collect union inheritance schemas for later model creation (but don't create models here)
+    for (let optionIndex = 0; optionIndex < options.length; optionIndex++) {
+      const option = options[optionIndex];
+      try {
+        const optionDefinition = this.convertZodTypeToMongooseDefinition(
+          option,
+          processedSchemas,
+          schemaCache,
+          inheritanceSchemas,
+          indexesToApply,
+          uniqueIndexesToApply,
+          ttlIndexesToApply,
+          currentPath,
+          currentDepth,
+          maxDepth
+        );
+
+        // Create Mongoose schema for this union inheritance option
+        const inheritanceOptionSchema = new Schema(optionDefinition, SCHEMA_SUBDOCUMENT_OPTIONS);
+        this.applyStandardTransforms(inheritanceOptionSchema);
+
+        // Extract discriminator value from the option's shape
+        // In Zod v4, use public .shape property and get literal value from def
+        // Unwrap the discriminator field to handle optional/nullable/default wrappers
+        let discriminatorValue: string | null = null;
+        if (discriminatorKey && isZodObject(option)) {
+          const optionShape = getZodObjectShape(option);
+          const discriminatorField = optionShape[discriminatorKey];
+          if (discriminatorField) {
+            // Unwrap the field to get the actual literal/enum value
+            const unwrappedField = unwrapSchema(discriminatorField);
+            if (isZodLiteral(unwrappedField)) {
+              const literalValue = getZodDefProperty(unwrappedField, 'value');
+              if (literalValue !== undefined && literalValue !== null) {
+                discriminatorValue = String(literalValue);
+              }
+            } else {
+              // Try to get value from enum if it's an enum field
+              const enumValues = getEnumValues(unwrappedField);
+              if (enumValues.length > 0) {
+                discriminatorValue = String(enumValues[0]);
+              }
+            }
+          }
+
+          // Fallback: If shape approach failed, try to extract from schema definition directly
+          // This handles cases where extended schemas might not expose shape correctly
+          if (!discriminatorValue && discriminatorField) {
+            const def = getZodDef(discriminatorField);
+            if (def && def.type === 'literal' && def.value !== undefined) {
+              discriminatorValue = String(def.value);
+            }
+          }
+        }
+
+        // If we couldn't extract a discriminator value, use index-based fallback to ensure uniqueness
+        // This prevents "Discriminator with name 'unknown' already exists" errors
+        if (!discriminatorValue || discriminatorValue === 'unknown') {
+          discriminatorValue = `option_${optionIndex}`;
+          this.logDebug(`Could not extract discriminator value for union option ${optionIndex}, using fallback: ${discriminatorValue}`, {
+            discriminatorKey,
+            optionIndex
+          });
+        }
+
+        // Store schema information for later inheritance model creation
+        inheritanceSchemas.push({
+          discriminatorKey,
+          discriminatorValue: String(discriminatorValue),
+          schema: inheritanceOptionSchema,
+          zodSchema: option
+        });
+      } catch (error) {
+        this.logger.warn(`Failed to process union inheritance option: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    // Return the union root definition with discriminator key
+    return {
+      ...rootDefinition,
+      discriminatorKey
+    };
+  }
+
+  /**
+   * Unwraps decorated Zod types to get the core type for instanceof checks
+   * @param zodField The potentially decorated Zod field
+   * @returns The core Zod type without decoration wrappers
+   */
+  private unwrapDecoratedType(zodField: z.ZodTypeAny): z.ZodTypeAny {
+    // Use the centralized unwrapSchema function from zod-decorators
+    return unwrapSchema(zodField);
+  }
+
+  /**
+   * Handles ZodUnion types intelligently
+   * @param zodUnion The Zod union to analyze
+   * @returns Appropriate Mongoose type definition
+   */
+  private handleZodUnion(zodUnion: z.ZodTypeAny): any {
+    const options = getZodDefArrayProperty(zodUnion, 'options');
+    if (!options) {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Collect all enum values and check if all options are string-like
+    const enumValues: string[] = [];
+    let allStringLike = true;
+
+    for (const option of options) {
+      if (!isZodTypeAny(option)) continue;
+
+      const optionType = getZodType(option);
+
+      // Handle enum (check for entries in Zod v4, or enum property for native enums)
+      if (optionType === 'enum') {
+        // Use centralized getEnumValues function
+        const optionEnumValues = getEnumValues(option);
+        enumValues.push(...optionEnumValues);
+        continue;
+      }
+
+      // Handle ZodString (allows any string)
+      if (optionType === 'string') {
+        // String type allows any string value, so we just continue
+        continue;
+      }
+
+      // If we encounter a non-string type, fall back to Mixed
+      allStringLike = false;
+      break;
+    }
+
+    // If all options are string-like (enum + string), return String with enum validation
+    if (allStringLike) {
+      if (enumValues.length > 0) {
+        return {
+          type: String,
+          enum: [...new Set(enumValues)] // Remove duplicates
+        };
+      } else {
+        return { type: String };
+      }
+    }
+
+    // Fall back to Mixed for complex unions
+    return { type: Schema.Types.Mixed };
+  }
+
+  /**
+   * Gets the base Mongoose type for a Zod field
+   * @param zodField The Zod field to get the type for
+   * @param schemaCache Cache of created schemas for recursive types
+   * @returns The base Mongoose type definition
+   */
+  private getBaseMongooseType(zodField: z.ZodTypeAny, schemaCache?: WeakMap<z.ZodTypeAny, Schema>): any {
+    const zodType = getZodType(zodField);
+
+    // Handle string types
+    // In Zod v4, string schemas have type: "string"
+    if (zodType === 'string') {
+      const definition: any = { type: String };
+
+      // Add string-specific validations
+      // In Zod v4, checks are stored in def.checks array
+      const checks = getZodDefArrayProperty(zodField, 'checks');
+      if (checks) {
+
+        for (const check of checks) {
+          if (typeof check === 'object' && check !== null) {
+            const checkKind = (check as Record<string, unknown>).kind;
+            const checkValue = (check as Record<string, unknown>).value;
+
+            if (checkKind === 'min' && typeof checkValue === 'number') {
+              definition.minlength = checkValue;
+            } else if (checkKind === 'max' && typeof checkValue === 'number') {
+              definition.maxlength = checkValue;
+            } else if (checkKind === 'regex' && checkValue instanceof RegExp) {
+              definition.match = checkValue;
+            }
+          }
+        }
+      }
+
+      return definition;
+    }
+
+    // Handle number types
+    // In Zod v4, number schemas have type: "number" or "int"
+    if (zodType === 'number' || zodType === 'int') {
+      const definition: any = { type: Number };
+
+      const checks = getZodDefArrayProperty(zodField, 'checks');
+      if (checks) {
+
+        for (const check of checks) {
+          if (typeof check === 'object' && check !== null) {
+            const checkKind = (check as Record<string, unknown>).kind;
+            const checkValue = (check as Record<string, unknown>).value;
+
+            if (checkKind === 'min' && typeof checkValue === 'number') {
+              definition.min = checkValue;
+            } else if (checkKind === 'max' && typeof checkValue === 'number') {
+              definition.max = checkValue;
+            }
+          }
+        }
+      }
+
+      return definition;
+    }
+
+    // Handle bigint types
+    // In Zod v4, bigint schemas have type: "bigint"
+    // Mongoose 6+ supports BigInt natively, which stores as BSON Long (64-bit)
+    // For arbitrarily large bigints, we store as String for maximum precision
+    if (zodType === 'bigint') {
+      // Use String type for storage to preserve full precision of arbitrarily large bigints
+      // The application layer handles conversion to/from BigInt
+      return {
+        type: String,
+        get: (v: string | null | undefined) => v ? BigInt(v) : v,
+        set: (v: bigint | string | null | undefined) => v !== null && v !== undefined ? String(v) : v
+      };
+    }
+
+    // Handle boolean types
+    // In Zod v4, boolean schemas have type: "boolean"
+    if (zodType === 'boolean') {
+      return { type: Boolean };
+    }
+
+    // Handle date types
+    // In Zod v4, date schemas have type: "date"
+    if (zodType === 'date') {
+      return { type: Date };
+    }
+
+    // Handle enum types
+    // In Zod v4, enum schemas have type: "enum" and values are in def.entries
+    if (zodType === 'enum') {
+      // Use centralized getEnumValues function
+      const enumValues = getEnumValues(zodField);
+
+      return {
+        type: String,
+        enum: enumValues
+      };
+    }
+
+    // NOTE: In Zod v4, .brand() no longer creates a wrapper type.
+    // Branded schemas report their underlying type (e.g., 'string') directly.
+    // The branding is purely a TypeScript compile-time feature.
+    // No special handling is needed for branded types in Zod v4.
+
+    // Handle record types - z.record() represents plain objects with dynamic keys
+    // In Zod v4, record schemas have type: "record"
+    if (isZodRecord(zodField)) {
+      // Default to Mixed for non-recursive records
+      // Only use Map if we detect a recursive schema that requires it
+      const valueType = getZodDefSchemaProperty(zodField, 'valueType');
+      let mapValueType: any = null;
+
+      if (valueType && isZodLazy(valueType)) {
+          // For recursive records (like properties: z.record(z.lazy(...))), we MUST use Map with the schema
+          // otherwise we lose the recursive structure.
+
+          // Try to resolve lazy type from cache if available
+          if (schemaCache) {
+          const getter = getZodDefFunctionProperty(valueType, 'getter');
+          if (getter) {
+            const inner = getter();
+            if (schemaCache.has(inner)) {
+              mapValueType = schemaCache.get(inner);
+            }
+          }
+        }
+      }
+
+      // If we found a recursive schema, return Map
+      if (mapValueType) {
+        return { type: Map, of: mapValueType };
+      }
+
+      // Default to Mixed for non-recursive records
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Handle Set types
+    // In Zod v4, set schemas have type: "set"
+    // Sets are stored as arrays in MongoDB with getter/setter for conversion
+    if (zodType === 'set') {
+      const valueType = getZodDefSchemaProperty(zodField, 'valueType');
+
+      // Try to determine the value type for the Set
+      let setValueType: any = Schema.Types.Mixed;
+      if (valueType) {
+        const valueTypeDefinition = this.getBaseMongooseType(valueType, schemaCache);
+        if (valueTypeDefinition?.type) {
+          setValueType = valueTypeDefinition.type;
+        }
+      }
+
+      return {
+        type: [setValueType],
+        get: (v: any[] | null | undefined) => v ? new Set(v) : v,
+        set: (v: Set<any> | any[] | null | undefined) => {
+          if (v === null || v === undefined) return v;
+          return v instanceof Set ? Array.from(v) : v;
+        }
+      };
+    }
+
+    // Handle Map types
+    // In Zod v4, map schemas have type: "map"
+    if (zodType === 'map') {
+      const valueType = getZodDefSchemaProperty(zodField, 'valueType');
+
+      // Try to determine the value type for the Map
+      let mapValueType: any = Schema.Types.Mixed;
+      if (valueType) {
+        const valueTypeDefinition = this.getBaseMongooseType(valueType, schemaCache);
+        if (valueTypeDefinition?.type) {
+          mapValueType = valueTypeDefinition.type;
+        }
+      }
+
+      return { type: Map, of: mapValueType };
+    }
+
+    // Handle any/unknown types
+    // In Zod v4, any/unknown schemas have type: "any" or "unknown"
+    if (zodType === 'any' || zodType === 'unknown') {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Handle void/undefined types
+    // In Zod v4, void/undefined schemas have type: "void" or "undefined"
+    if (zodType === 'void' || zodType === 'undefined') {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Handle never type
+    // In Zod v4, never schemas have type: "never"
+    if (zodType === 'never') {
+      return { type: Schema.Types.Mixed };
+    }
+
+    // Fallback for unknown types
+    this.logger.warn(`[ZodToMongoose] Unknown Zod type, using Mixed. Type: ${typeof zodField}`);
+    return { type: Schema.Types.Mixed };
+  }
+
+  // =================================================================
+  // VALIDATION AND HELPER METHODS
+  // =================================================================
+
+  /**
+   * Validates and fixes field types to ensure Mongoose compatibility
+   * @param mongooseDefinition The mongoose schema definition to validate
+   * @param resourceType The resource type for debugging
+   */
+  private validateAndFixFieldTypes(mongooseDefinition: any, resourceType: string): void {
+    this.validateFieldsRecursively(mongooseDefinition, resourceType, '');
+  }
+
+  /**
+   * Recursively validates and fixes field types
+   * @param obj The object to validate
+   * @param resourceType The resource type for debugging
+   * @param path The current field path for debugging
+   */
+  /**
+   * Checks if a value is a Mongoose Schema instance or looks like one
+   * More robust than instanceof to handle different Schema versions/instances
+   */
+  private isSchemaLike(value: any): boolean {
+    if (!value || typeof value !== 'object') return false;
+    // Check instanceof first (most reliable)
+    if (value instanceof Schema) {
+      return true;
+    }
+    // Check for Schema constructor
+    if (value.constructor && value.constructor.name === 'Schema') {
+      return true;
+    }
+    // Check for Schema-specific properties as fallback
+    // A real Schema instance has: paths, methods, statics, virtuals, options
+    // Even newly created empty schemas have these
+    return (
+      typeof value.paths === 'object' &&
+      typeof value.methods === 'object' &&
+      typeof value.statics === 'object' &&
+      typeof value.virtuals === 'object' &&
+      typeof value.options === 'object'
+    );
+  }
+
+
+  private validateFieldsRecursively(obj: any, resourceType: string, path: string): void {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+      return;
+    }
+
+
+    // CRITICAL: If obj itself is a Schema instance, do not iterate over it
+    // Schema instances have internal properties that should not be validated as fields
+    if (this.isSchemaLike(obj)) {
+      return;
+    }
+
+    for (const [fieldName, fieldValue] of Object.entries(obj)) {
+      const fieldPath = path ? `${path}.${fieldName}` : fieldName;
+
+      // CRITICAL: If fieldValue is a Schema instance, skip it entirely
+      // Schema instances are already valid and should not be validated
+      if (this.isSchemaLike(fieldValue)) {
+        continue;
+      }
+
+      if (fieldValue && typeof fieldValue === 'object' && !Array.isArray(fieldValue)) {
+        // CRITICAL: If fieldValue has a 'type' property that is a Schema instance,
+        // skip validation entirely - it's already properly wrapped
+        if ('type' in fieldValue && this.isSchemaLike(fieldValue.type)) {
+          continue;
+        }
+
+        // Check if this is a field definition (should have a type property or be a nested object)
+        const hasTypeProperty = 'type' in fieldValue;
+        const hasNestedFields = Object.keys(fieldValue).some(key =>
+          key !== 'default' && key !== 'required' && key !== '_id' && key !== 'type' &&
+          typeof fieldValue[key] === 'object'
+        );
+
+        // Valid Mongoose schema properties that don't require a 'type' property
+        const validMongooseProperties = [
+          'match', 'min', 'max', 'minlength', 'maxlength',
+          'enum', 'required', 'default', 'validate', 'get', 'set',
+          'transform', 'alias', 'immutable', 'sparse', 'unique',
+          'index', 'select', 'populate', 'discriminator', '_id'
+        ];
+
+        const hasOnlyValidMongooseProperties = Object.keys(fieldValue).every(key =>
+          validMongooseProperties.includes(key)
+        );
+
+        if (!hasTypeProperty && !hasNestedFields && !hasOnlyValidMongooseProperties) {
+          // This field is missing a type property - fix it
+          this.logger.warn(`[ZodToMongoose] FIXING field '${fieldPath}' in resource '${resourceType}': Missing type property`);
+          this.logger.warn(`[ZodToMongoose] Field value keys: ${Object.keys(fieldValue as Record<string, unknown>).join(', ')}`);
+
+          let mongooseType: any = Schema.Types.Mixed; // Default fallback
+
+          // Try to infer type from default value if available
+          if ('default' in fieldValue) {
+            const defaultValue = fieldValue.default;
+            if (typeof defaultValue === 'boolean') {
+              mongooseType = Schema.Types.Boolean;
+            } else if (typeof defaultValue === 'string') {
+              mongooseType = Schema.Types.String;
+            } else if (typeof defaultValue === 'number') {
+              mongooseType = Schema.Types.Number;
+            } else if (defaultValue instanceof Date) {
+              mongooseType = Schema.Types.Date;
+            }
+          }
+          // For fields with only 'required: true', assume String as a safe default
+          else if ('required' in fieldValue && Object.keys(fieldValue).length === 1) {
+            mongooseType = String;
+          }
+
+          // Fix the field definition
+          obj[fieldName] = {
+            type: mongooseType,
+            ...fieldValue
+          };
+
+          this.logger.warn(`[ZodToMongoose] Fixed to: ${JSON.stringify(obj[fieldName])}`);
+        } else if (hasNestedFields) {
+          // Recursively validate nested objects, but exclude valid Mongoose properties AND type
+          const validMongooseKeys = ['match', 'min', 'max', 'minlength', 'maxlength', 'enum', 'required', 'default', 'validate', 'get', 'set', 'transform', 'alias', 'immutable', 'sparse', 'unique', 'index', 'select', 'populate', 'discriminator', '_id', 'type'];
+          const nestedFields = Object.fromEntries(
+            Object.entries(fieldValue).filter(([key]) => !validMongooseKeys.includes(key))
+          );
+          this.validateFieldsRecursively(nestedFields, resourceType, fieldPath);
+        } else if (hasTypeProperty && fieldValue.type && typeof fieldValue.type === 'object') {
+          // CRITICAL: If fieldValue.type is a Schema instance, DO NOT validate it
+          // Schema instances have internal properties (methods, options, etc.) that should not be treated as fields
+          if (!this.isSchemaLike(fieldValue.type)) {
+            // This is a nested object type (plain object definition) - validate its contents
+            this.validateFieldsRecursively(fieldValue.type, resourceType, fieldPath);
+          }
+          // If it's a Schema instance, we skip validation - it's already a valid Mongoose schema
+        }
+      }
+    }
+  }
+
+
+  // =================================================================
+  // UTILITY AND HELPER METHODS
+  // =================================================================
+
+  /**
+   * Maps USER_SELF_* resources to their equivalent collection names
+   * This ensures USER_SELF resources use the same MongoDB collections
+   * as their non-SELF counterparts while maintaining separate models
+   */
+  private getCollectionNameForResource(resourceType: ResourceType): string {
+    const collectionMapping: Record<string, string> = {
+      [CoreResourceType.USER_SELF]: CoreResourceType.USERS,
+      [CoreResourceType.USER_SELF_PROFILES]: CoreResourceType.USER_PROFILES,
+      [CoreResourceType.USER_SELF_PREFERENCES]: CoreResourceType.USER_PREFERENCES,
+    };
+
+    // Return mapped collection name or original resource type
+    return collectionMapping[resourceType as string] || (resourceType as string);
+  }
+
+  /**
+   * Standardizes toObject/toJSON to serialize ObjectId fields as strings.
+   * Keeps internal schema types as ObjectId for queries, but outputs strings for DTO parsing.
+   */
+  private applyStandardTransforms(mongooseSchema: Schema): void {
+    const hasToObject = (mongooseSchema as any).options?.toObject;
+    const hasToJSON = (mongooseSchema as any).options?.toJSON;
+
+    mongooseSchema.set('toObject', {
+      ...(hasToObject || {}),
+      transform: (doc: any, ret: any) => {
+        this.serializeObjectIds(ret);
+        if (typeof (hasToObject as any)?.transform === 'function') {
+          (hasToObject as any).transform(doc, ret);
+        }
+        return ret;
+      }
+    });
+
+    mongooseSchema.set('toJSON', {
+      ...(hasToJSON || {}),
+      transform: (doc: any, ret: any) => {
+        this.serializeObjectIds(ret);
+        if (typeof (hasToJSON as any)?.transform === 'function') {
+          (hasToJSON as any).transform(doc, ret);
+        }
+        return ret;
+      }
+    });
+  }
+
+  private serializeObjectIds(obj: any): void {
+    if (!obj || typeof obj !== 'object') return;
+    const stack: any[] = [obj];
+    while (stack.length) {
+      const current = stack.pop();
+      for (const key of Object.keys(current)) {
+        const value = current[key];
+        if (value && typeof value === 'object') {
+          // ObjectId array
+          if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+              const v = value[i] as any;
+              if (v && typeof v === 'object' && (v as any)?._bsontype === 'ObjectId') {
+                value[i] = String(v);
+              } else if (v && typeof v === 'object') {
+                stack.push(v);
+              }
+            }
+          } else if ((value as any)?._bsontype === 'ObjectId' || value instanceof (Types as any).ObjectId) {
+            current[key] = String(value);
+          } else {
+            stack.push(value);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Determines if a Zod field is required
+   * @param zodField The Zod field to check
+   * @returns True if the field is required
+   */
+  private isFieldRequired(zodField: z.ZodTypeAny): boolean {
+    // Check if it's wrapped in ZodOptional or ZodNullable
+    // In Zod v4, optional/nullable schemas have type: "optional" or "nullable"
+    if (isZodOptional(zodField) || isZodNullable(zodField)) {
+      return false;
+    }
+
+    // Check if it has a default value
+    // In Zod v4, default schemas have type: "default"
+    if (isZodDefault(zodField)) {
+      return false;
+    }
+
+    // Otherwise, it's required
+    return true;
+  }
+
+  /**
+   * Applies indexes to a Mongoose schema
+   * @param mongooseSchema The schema to apply indexes to
+   * @param indexesToApply Array of field paths to index
+   * @param uniqueIndexesToApply Array of unique index info with paths and params
+   * @param ttlIndexesToApply Array of TTL index info with paths and params
+   */
+  private applyIndexesToSchema(
+    mongooseSchema: Schema,
+    indexesToApply: string[],
+    uniqueIndexesToApply: UniqueIndexInfo[] = [],
+    ttlIndexesToApply: TtlIndexInfo[] = []
+  ): void {
+    const appliedPaths = new Set<string>();
+
+    // First, collect all paths that will have unique indexes to avoid duplicates
+    const uniqueIndexPaths = new Set<string>();
+    for (const uniqueInfo of uniqueIndexesToApply) {
+      const normalizedPath = (uniqueInfo.path || '').replace(/\[\]/g, '').trim();
+      if (normalizedPath) {
+        uniqueIndexPaths.add(normalizedPath);
+      }
+    }
+
+    // Apply regular indexes
+    for (const rawPath of indexesToApply) {
+      try {
+        // Normalize array notation and trim whitespace
+        const normalizedPath = (rawPath || '').replace(/\[\]/g, '').trim();
+
+        // Skip invalid or empty paths
+        if (!normalizedPath) continue;
+
+        // Never attempt to index _id (MongoDB manages it). Also skip nested '.*._id'
+        if (normalizedPath === '_id' || normalizedPath.endsWith('._id')) {
+          continue;
+        }
+
+        // Skip paths that will have unique indexes (unique indexes already create an index)
+        if (uniqueIndexPaths.has(normalizedPath)) {
+          continue;
+        }
+
+        // De-duplicate
+        if (appliedPaths.has(normalizedPath)) continue;
+        appliedPaths.add(normalizedPath);
+
+        // Create a simple index on the field
+        const indexSpec: Record<string, 1> = {};
+        indexSpec[normalizedPath] = 1;
+        mongooseSchema.index(indexSpec);
+      } catch (error) {
+        this.logger.warn(`[ZodToMongoose] Failed to apply index on path '${rawPath}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    // Apply unique indexes
+    const appliedUniquePaths = new Set<string>();
+    for (const uniqueInfo of uniqueIndexesToApply) {
+      try {
+        // Normalize array notation and trim whitespace
+        const normalizedPath = (uniqueInfo.path || '').replace(/\[\]/g, '').trim();
+
+        // Skip invalid or empty paths
+        if (!normalizedPath) continue;
+
+        // Never attempt to index _id (MongoDB manages it). Also skip nested '.*._id'
+        if (normalizedPath === '_id' || normalizedPath.endsWith('._id')) {
+          continue;
+        }
+
+        // De-duplicate (unique indexes take precedence, so remove from regular indexes if exists)
+        if (appliedUniquePaths.has(normalizedPath)) continue;
+        appliedUniquePaths.add(normalizedPath);
+
+        const params = uniqueInfo.params || {};
+        const scope = params.scope || 'global';
+        const sparse = params.sparse !== false; // Default to true
+
+        // Create index spec based on scope or compoundWith
+        const indexSpec: Record<string, 1> = {};
+
+        if (params.compoundWith) {
+          // Resolve compoundWith field — handles polymorphic renames automatically
+          let compoundField = params.compoundWith;
+          if (!(mongooseSchema as any).paths?.[compoundField]) {
+            const suffix = compoundField.charAt(0).toUpperCase() + compoundField.slice(1);
+            const schemaFields = Object.keys((mongooseSchema as any).paths || {});
+            const match = schemaFields.find(p => p.endsWith(suffix) && p !== normalizedPath);
+            if (match) {
+              compoundField = match;
+            } else {
+              this.logger.warn(`[ZodToMongoose] compoundWith field '${params.compoundWith}' not found in schema paths (suffix '${suffix}'). Available: ${schemaFields.join(', ')}`);
+            }
+          }
+          indexSpec[compoundField] = 1;
+          indexSpec[normalizedPath] = 1;
+        } else if (scope === 'organization') {
+          // Compound unique index: organizationId + field
+          indexSpec['organizationId'] = 1;
+          indexSpec[normalizedPath] = 1;
+        } else if (scope === 'user') {
+          // Compound unique index: createdByUserId + field
+          indexSpec['createdByUserId'] = 1;
+          indexSpec[normalizedPath] = 1;
+        } else {
+          // Global unique index
+          indexSpec[normalizedPath] = 1;
+        }
+
+        // Apply unique index with options
+        const indexOptions: { unique: true; sparse?: boolean } = { unique: true };
+        if (sparse) {
+          indexOptions.sparse = true;
+        }
+
+        mongooseSchema.index(indexSpec, indexOptions);
+      } catch (error) {
+        this.logger.warn(`[ZodToMongoose] Failed to apply unique index on path '${uniqueInfo.path}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    // Apply TTL indexes
+    // MongoDB TTL indexes automatically delete documents after a specified time
+    // TTL indexes can only be applied to Date fields
+    const appliedTtlPaths = new Set<string>();
+    for (const ttlInfo of ttlIndexesToApply) {
+      try {
+        // Normalize array notation and trim whitespace
+        const normalizedPath = (ttlInfo.path || '').replace(/\[\]/g, '').trim();
+
+        // Skip invalid or empty paths
+        if (!normalizedPath) continue;
+
+        // De-duplicate
+        if (appliedTtlPaths.has(normalizedPath)) continue;
+        appliedTtlPaths.add(normalizedPath);
+
+        const params = ttlInfo.params;
+        const expireAfterSeconds = params.expireAfterSeconds;
+
+        // Create TTL index on the field
+        const indexSpec: Record<string, 1> = {};
+        indexSpec[normalizedPath] = 1;
+
+        // Apply TTL index with expireAfterSeconds option
+        mongooseSchema.index(indexSpec, { expireAfterSeconds });
+
+        this.logDebug(`Applied TTL index on path '${normalizedPath}' with expireAfterSeconds: ${expireAfterSeconds}`);
+      } catch (error) {
+        this.logger.warn(`[ZodToMongoose] Failed to apply TTL index on path '${ttlInfo.path}': ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  /**
+   * Checks if a definition is an object definition (not a primitive type)
+   * @param definition The definition to check
+   * @returns True if it's an object definition
+   */
+  private isObjectDefinition(definition: any): boolean {
+    return definition &&
+      typeof definition === 'object' &&
+      !Array.isArray(definition) &&
+      !definition.type &&
+      Object.keys(definition).length > 0;
+  }
+
+  /**
+   * Generates a hash for a schema for caching purposes
+   * @param schema The schema to hash
+   * @returns A hash string
+   */
+  private getSchemaHash(schema: any): string {
+    try {
+      const schemaString = JSON.stringify(schema, (key, value) => {
+        if (typeof value === 'function') return '[Function]';
+        if (value instanceof RegExp) return value.toString();
+        return value;
+      });
+      return schemaString.length.toString(36) + schemaString.slice(0, 10);
+    } catch {
+      return Math.random().toString(36).substr(2, 9);
+    }
+  }
+
+  // =================================================================
+  // DEBUG AND UTILITY METHODS
+  // =================================================================
+
+  /**
+   * Debug display method to show schema structure for a specific model
+   * @param model The Mongoose model to analyze
+   * @param showDetails Whether to show detailed field information
+   */
+  debugDisplayModelSchema(model: Model<any>, showDetails: boolean = true): void {
+
+    this.logDebug(`\n🔍 === MODEL SCHEMA DEBUG: ${model.modelName} ===`);
+    this.logDebug(`Collection: ${model.collection.name}`);
+    this.logDebug(`Schema Fields: ${this.countSchemaFields(model.schema)}`);
+    this.logDebug(`Indexes: ${model.schema.indexes().length}`);
+
+    if (showDetails) {
+      this.displaySchemaStructure(model.schema, model.modelName);
+
+      const indexes = model.schema.indexes();
+      if (indexes.length > 0) {
+        this.logDebug('\n🗂️  Indexes:');
+        indexes.forEach((index, i) => {
+          const [fields, options] = index;
+          const fieldsStr = Object.entries(fields)
+            .map(([field, direction]) => `${field}:${direction}`)
+            .join(', ');
+          const optionsStr = options && Object.keys(options).length > 0
+            ? ` (${Object.entries(options).map(([k, v]) => `${k}:${v}`).join(', ')})`
+            : '';
+          this.logDebug(`  ${i + 1}. {${fieldsStr}}${optionsStr}`);
+        });
+      }
+    }
+    this.logDebug('=================================\n');
+  }
+
+  /**
+   * Debug method to show simplified schema summary
+   * @param models Array of models to analyze
+   */
+  debugShowModelsSummary(models: Model<any>[]): void {
+
+    this.logDebug('\n📋 === MODELS SUMMARY ===');
+
+    if (models.length === 0) {
+      this.logDebug('No models provided.');
+      return;
+    }
+
+    for (const model of models) {
+      const fieldCount = this.countSchemaFields(model.schema);
+      const indexCount = model.schema.indexes().length;
+      this.logDebug(`${model.modelName}: ${fieldCount} fields, ${indexCount} indexes`);
+    }
+    this.logDebug('========================\n');
+  }
+
+  /**
+   * Counts schema fields recursively
+   * @param schema The Mongoose schema
+   * @returns Total field count
+   */
+  private countSchemaFields(schema: Schema): number {
+    if (!schema || !schema.paths) return 0;
+
+    const paths = schema.paths;
+    const pathNames = Object.keys(paths)
+      .filter(path => !['__v', '_version_db_doc'].includes(path))
+      .sort();
+
+    return pathNames.length;
+  }
+
+  /**
+   * Displays the structure of a Mongoose schema for debugging
+   * @param schema The schema to display
+   * @param schemaName Optional name for the schema
+   * @param options Display options
+   */
+  private displaySchemaStructure(
+    schema: Schema,
+    schemaName: string = 'Schema',
+    options: {
+      showIndexes?: boolean;
+      showValidators?: boolean;
+      maxDepth?: number;
+    } = {}
+  ): void {
+    const { showIndexes = true, showValidators = false, maxDepth = 3 } = options;
+
+    this.logDebug(`\n=== ${schemaName} Structure ===`);
+
+    if (!schema || !schema.paths) {
+      this.logDebug('No schema paths found');
+      return;
+    }
+
+    const paths = schema.paths;
+    const pathNames = Object.keys(paths)
+      .filter(path => !['__v', '_version_db_doc'].includes(path))
+      .sort();
+
+    for (const pathName of pathNames) {
+      const pathInfo = this.getPathTypeInfo(paths[pathName]);
+
+      // Start with base type
+      let pathDisplay = `${pathName}: `;
+
+      if (pathInfo.isArray) {
+        // For arrays, show [ElementType] format
+        const elementType = pathInfo.arrayElementType || 'Mixed';
+        pathDisplay += `[${elementType}]`;
+      } else {
+        pathDisplay += pathInfo.type;
+      }
+
+      // Collect all additional info in parentheses
+      const additionalInfo: string[] = [];
+
+      // Required vs Optional
+      if (pathInfo.isRequired) {
+        additionalInfo.push('required');
+      } else {
+        additionalInfo.push('optional');
+      }
+
+      // Enum values
+      if (pathInfo.enumValues.length > 0) {
+        const enumList = pathInfo.enumValues.join(', ');
+        additionalInfo.push(`enum: [${enumList}]`);
+      }
+
+      // Default value
+      if (pathInfo.hasDefault) {
+        let defaultStr = '';
+        if (Array.isArray(pathInfo.defaultValue)) {
+          defaultStr = `[${pathInfo.defaultValue.join(', ')}]`;
+        } else if (typeof pathInfo.defaultValue === 'object' && pathInfo.defaultValue !== null) {
+          defaultStr = JSON.stringify(pathInfo.defaultValue);
+        } else if (typeof pathInfo.defaultValue === 'string') {
+          defaultStr = `"${pathInfo.defaultValue}"`;
+        } else {
+          defaultStr = String(pathInfo.defaultValue);
+        }
+        additionalInfo.push(`default: ${defaultStr}`);
+      }
+
+      // Validators
+      if (showValidators && pathInfo.validators.length > 0) {
+        additionalInfo.push(`validators: [${pathInfo.validators.join(', ')}]`);
+      }
+
+      // Add all additional info in parentheses
+      if (additionalInfo.length > 0) {
+        pathDisplay += ` (${additionalInfo.join(', ')})`;
+      }
+
+      this.logDebug(`  ${pathDisplay}`);
+
+      // Show nested structure for objects
+      if (pathInfo.isNested && maxDepth > 0) {
+        this.displayNestedPathStructure(paths[pathName], 2, maxDepth - 1, showValidators);
+      }
+    }
+
+    if (showIndexes) {
+      const indexes = schema.indexes();
+      if (indexes.length > 0) {
+        this.logDebug('\n  Indexes:');
+        indexes.forEach((index, i) => {
+          this.logDebug(`    ${i + 1}. ${JSON.stringify(index[0])} ${JSON.stringify(index[1] || {})}`);
+        });
+      }
+    }
+
+    this.logDebug(`\nTotal paths: ${pathNames.length}`);
+  }
+
+  /**
+   * Displays nested path structure recursively with comprehensive details
+   * @param path The path to display
+   * @param indent Current indentation level
+   * @param maxDepth Maximum depth to display
+   * @param showValidators Whether to show validator information
+   */
+  private displayNestedPathStructure(path: any, indent: number = 0, maxDepth: number = 2, showValidators: boolean = false): void {
+    if (maxDepth <= 0) return;
+
+    const spaces = '  '.repeat(indent);
+
+    if (path.schema && path.schema.paths) {
+      const nestedPaths = Object.keys(path.schema.paths)
+        .filter(nestedPath => !['__v', '_version_db_doc'].includes(nestedPath))
+        .sort();
+
+      for (const nestedPath of nestedPaths) {
+        const nestedPathInfo = this.getPathTypeInfo(path.schema.paths[nestedPath]);
+
+        // Build display string for nested field
+        let nestedDisplay = `${nestedPath}: `;
+
+        if (nestedPathInfo.isArray) {
+          const elementType = nestedPathInfo.arrayElementType || 'Mixed';
+          nestedDisplay += `[${elementType}]`;
+        } else {
+          nestedDisplay += nestedPathInfo.type;
+        }
+
+        // Collect additional info for nested fields
+        const nestedAdditionalInfo: string[] = [];
+
+        // Required vs Optional
+        if (nestedPathInfo.isRequired) {
+          nestedAdditionalInfo.push('required');
+        } else {
+          nestedAdditionalInfo.push('optional');
+        }
+
+        // Enum values
+        if (nestedPathInfo.enumValues.length > 0) {
+          const enumList = nestedPathInfo.enumValues.join(', ');
+          nestedAdditionalInfo.push(`enum: [${enumList}]`);
+        }
+
+        // Default value
+        if (nestedPathInfo.hasDefault) {
+          let defaultStr = '';
+          if (Array.isArray(nestedPathInfo.defaultValue)) {
+            defaultStr = `[${nestedPathInfo.defaultValue.join(', ')}]`;
+          } else if (typeof nestedPathInfo.defaultValue === 'object' && nestedPathInfo.defaultValue !== null) {
+            defaultStr = JSON.stringify(nestedPathInfo.defaultValue);
+          } else if (typeof nestedPathInfo.defaultValue === 'string') {
+            defaultStr = `"${nestedPathInfo.defaultValue}"`;
+          } else {
+            defaultStr = String(nestedPathInfo.defaultValue);
+          }
+          nestedAdditionalInfo.push(`default: ${defaultStr}`);
+        }
+
+        // Validators
+        if (showValidators && nestedPathInfo.validators.length > 0) {
+          nestedAdditionalInfo.push(`validators: [${nestedPathInfo.validators.join(', ')}]`);
+        }
+
+        // Add additional info in parentheses
+        if (nestedAdditionalInfo.length > 0) {
+          nestedDisplay += ` (${nestedAdditionalInfo.join(', ')})`;
+        }
+
+        this.logDebug(`${spaces}${nestedDisplay}`);
+
+        if (nestedPathInfo.isNested) {
+          this.displayNestedPathStructure(path.schema.paths[nestedPath], indent + 1, maxDepth - 1, showValidators);
+        }
+      }
+    }
+  }
+
+  /**
+   * Gets comprehensive type information for a schema path
+   * @param schemaType The schema type to analyze
+   * @returns Object containing detailed type information
+   */
+  private getPathTypeInfo(schemaType: any): {
+    type: string;
+    isRequired: boolean;
+    hasDefault: boolean;
+    defaultValue: any;
+    isArray: boolean;
+    arrayElementType: string;
+    isNested: boolean;
+    validators: string[];
+    enumValues: string[];
+    isOptional: boolean;
+  } {
+    let type = 'Mixed';
+    let isRequired = false;
+    let hasDefault = false;
+    let defaultValue: any = undefined;
+    let isArray = false;
+    let arrayElementType = '';
+    let isNested = false;
+    const validators: string[] = [];
+    const enumValues: string[] = [];
+
+    if (schemaType) {
+      // Get type name
+      if (schemaType.instance) {
+        type = schemaType.instance;
+      } else if (schemaType.constructor && schemaType.constructor.name) {
+        type = schemaType.constructor.name;
+      }
+
+      // Check if required
+      if (schemaType.isRequired) {
+        isRequired = true;
+      }
+
+      // Check if has default and get the actual value
+      if (schemaType.defaultValue !== undefined) {
+        hasDefault = true;
+        defaultValue = schemaType.defaultValue;
+
+        // Handle function defaults
+        if (typeof defaultValue === 'function') {
+          try {
+            const result = defaultValue();
+            defaultValue = result;
+          } catch (e) {
+            defaultValue = '[Function]';
+          }
+        }
+      }
+
+      // Check if array and get element type
+      if (schemaType.constructor && schemaType.constructor.name === 'Array') {
+        isArray = true;
+
+        // Try to get array element type
+        if (schemaType.caster) {
+          if (schemaType.caster.instance) {
+            arrayElementType = schemaType.caster.instance;
+          } else if (schemaType.caster.constructor && schemaType.caster.constructor.name) {
+            arrayElementType = schemaType.caster.constructor.name;
+          }
+
+          // Check for enum values in array elements
+          if (schemaType.caster.enumValues && Array.isArray(schemaType.caster.enumValues)) {
+            enumValues.push(...schemaType.caster.enumValues);
+          }
+        }
+      }
+
+      // Check if nested (has embedded schema)
+      if (schemaType.schema) {
+        isNested = true;
+        type = 'Object';
+      }
+
+      // Check for enum values
+      if (schemaType.enumValues && Array.isArray(schemaType.enumValues)) {
+        enumValues.push(...schemaType.enumValues);
+      }
+
+      // Collect validators
+      if (schemaType.validators && Array.isArray(schemaType.validators)) {
+        validators.push(...schemaType.validators.map((v: any) => v.type || 'custom'));
+      }
+    }
+
+    const isOptional = !isRequired;
+
+    return {
+      type,
+      isRequired,
+      hasDefault,
+      defaultValue,
+      isArray,
+      arrayElementType,
+      isNested,
+      validators,
+      enumValues,
+      isOptional
+    };
+  }
+}