@wildo-ai/saas-backend-lib 1.0.1

package/src/base-classes/services/repositories/repositories-registry-handler.backend.service.ts

@@ -0,0 +1,804 @@
+import 'reflect-metadata';
+import { injectable, inject, Container } from 'inversify';
+import { Model, Connection } from 'mongoose';
+import type {
+  ResourceConfiguration,
+  ResourceConfiguration_OperationRepositoryPath
+} from '@wildo-ai/saas-models';
+import {
+  ResourceType,
+
+  CoreResourceOperation,
+  ResourcesConfig_OperationPathUtils,
+  ErrorType,
+  ErrorCustomMessageReference,
+  PersistenceAdapterType,
+  DEFAULT_PERSISTENCE_ADAPTER,
+  Resources_PaginationRequest,
+  Resources_PaginatedResult
+} from '@wildo-ai/saas-models';
+import { EnumLikeType } from '@wildo-ai/zod-decorators';
+import {
+  IdOrFilterType,
+  IdOrIdsOrFilterType,
+  IdsOrFilterType,
+  RepositoryOptions,
+} from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { RepositoryResourceBackendService } from './repository-resource.backend.service';
+import { ResourceOperationHelperBackendService } from '~wildo-backend-lib/base-classes/services/resource-operations-helper.backend.service';
+import { ZodToMongooseSchemaConvertorBackendService } from '~wildo-backend-lib/databases/services/zod-to-mongoose-schema-convertor.backend.service';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { z } from 'zod';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { PostgreSQLDatabaseBackendService } from '~wildo-backend-lib/databases/services/postgresql-database.backend.service';
+import { ZodToSqlHybridSchemaPlannerBackendService } from '~wildo-backend-lib/databases/services/zod-to-sql-hybrid-schema.planner';
+import { PostgreSQLResourceRepositoryBackendService } from './postgresql-resource-repository.backend.service';
+import { ResourceIdBackendService } from '~wildo-backend-lib/resources/services/resource-id.backend.service';
+
+/**
+ * Backend repository interface (no nominal private members).
+ * Both Mongo and PostgreSQL repositories conform structurally.
+ */
+export interface BackendResourceRepository<
+  TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+  TMainSchema extends z.ZodTypeAny = z.ZodTypeAny
+> {
+  doByPath<T = any, U = any>(
+    operationRepositoryPath: ResourceConfiguration_OperationRepositoryPath,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: any,
+    data?: U,
+    options?: RepositoryOptions
+  ): Promise<T>;
+
+  doByKey<T = any, U = any>(
+    operationRepositoryPathKey: string,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: any,
+    data?: U,
+    options?: RepositoryOptions
+  ): Promise<T>;
+
+  doByExecutionContext<T = any>(
+    executionContext: ExecutionContext<any>,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<T>;
+
+  // Core methods used throughout backend-lib (must be shared across adapters)
+  create<T = any>(executionContext: ExecutionContext<any>, data: any, options?: RepositoryOptions): Promise<T>;
+  createMany<T = any>(executionContext: ExecutionContext<any>, data: any[], options?: RepositoryOptions): Promise<T[]>;
+
+  read<T = any>(
+    executionContext: ExecutionContext<any>,
+    id_or_filter: IdOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<T | null>;
+
+  update<T = any>(
+    executionContext: ExecutionContext<any>,
+    id_or_filter: IdOrFilterType,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<T | null>;
+
+  updateMany<T = any>(
+    executionContext: ExecutionContext<any>,
+    data: any,
+    options?: RepositoryOptions
+  ): Promise<T[]>;
+
+  delete(executionContext: ExecutionContext<any>, id_or_ids_or_filter: IdOrIdsOrFilterType, options?: RepositoryOptions): Promise<string>;
+  deleteMany(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<string[]>;
+
+  list<T = any>(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<T[]>;
+  list<T = any>(
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType,
+    options: RepositoryOptions & { paginated: true; listOptions?: Partial<Resources_PaginationRequest> }
+  ): Promise<Resources_PaginatedResult<T>>;
+
+  search<T = any>(
+    executionContext: ExecutionContext<any>,
+    searchQuery: string,
+    filter?: any,
+    searchOptions?: any,
+    options?: RepositoryOptions
+  ): Promise<Resources_PaginatedResult<T>>;
+
+  count(executionContext: ExecutionContext<any>, filter?: any, options?: RepositoryOptions): Promise<{ count: number }>;
+
+  supportsOperation(operationIdentifier: string): boolean;
+
+  aggregateField(
+    executionContext: ExecutionContext<any>,
+    filter: any,
+    field: string,
+    operation: string,
+  ): Promise<number>;
+
+}
+
+/**
+ * Repository Registry Handler Backend Service
+ *
+ * Central registry for managing all repository resources in the application.
+ * Provides unified access to repositories via operation paths and manages
+ * cross-repository dependencies and relationships.
+ *
+ * Features:
+ * - Repository lifecycle management (create, store, retrieve)
+ * - Operation path-based repository access
+ * - Cross-repository dependency injection
+ * - Automatic repository initialization from resource configurations
+ * - ExecutionContext integration for streamlined operations
+ * - Resource relationship handling
+ * - Unified error handling with ErrorBuilderBackendService
+ */
+@injectable()
+export class RepositoriesRegistryHandlerBackendService {
+
+  private readonly repositories: Map<ResourceType, BackendResourceRepository<any, any, any>>;
+  private readonly repositoryOperationsMap: Map<string, {
+    repository: BackendResourceRepository<any, any, any>;
+    operationRepositoryPath: ResourceConfiguration_OperationRepositoryPath;
+  }>;
+  private isInitialized = false;
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.ZodToMongooseSchemaConvertorService) private readonly zodToMongooseConverter: ZodToMongooseSchemaConvertorBackendService,
+    @inject(SAAS_SERVICE_TYPES.ZodToSqlHybridSchemaPlannerService) private readonly zodToSqlPlanner: ZodToSqlHybridSchemaPlannerBackendService,
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) private readonly resourceRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceOperationHelperService) private readonly resourceOperationHelper: ResourceOperationHelperBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly configService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.PostgreSQLDatabaseService) private readonly postgresqlDb: PostgreSQLDatabaseBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceIdBackendService) private readonly resourceIdService: ResourceIdBackendService
+  ) {
+
+    this.repositories = new Map();
+    this.repositoryOperationsMap = new Map();
+
+    this.logDebug = this.logger.debugByType('RepositoriesRegistryHandler');
+    this.logger.setDebugTypeLogging('RepositoriesRegistryHandler', false);
+
+    this.logDebug('Repository registry service created');
+  }
+
+// ================================
+// Initialize repositories
+// ================================
+
+  public async initializeRepositories(
+    resourceConfigurations: Map<ResourceType, ResourceConfiguration<any, any, any>>,
+    connection?: Connection
+  ): Promise<void> {
+    if (this.isInitialized) {
+      this.logDebug('Registry already initialized, skipping...');
+      return;
+    }
+
+    this.logDebug('Initializing repositories', {
+      resourceCount: resourceConfigurations.size,
+      resourceTypes: Array.from(resourceConfigurations.keys())
+    });
+
+    // First pass: Create all repositories
+    for (const [resourceType] of resourceConfigurations) {
+      try {
+        await this.createRepository(resourceType, connection);
+      } catch (error) {
+        this.logger.error('Failed to create repository', {
+          resourceType,
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+        throw error;
+      }
+    }
+
+
+    this.buildOperationRepositoryPathsMap();
+
+    this.isInitialized = true;
+
+    this.logDebug('Repository registry initialization completed', {
+      repositoryCount: this.repositories.size,
+      operationRepositoryPathsCount: this.repositoryOperationsMap.size
+    });
+  }
+
+
+  private async createRepository(
+    resourceType: ResourceType,
+    connection?: Connection,
+  ): Promise<void> {
+    this.logDebug('Creating repository', { resourceType });
+
+    const defaultAdapter: PersistenceAdapterType = (() => {
+      if (!this.configService.isInitialized()) {
+        return DEFAULT_PERSISTENCE_ADAPTER;
+      }
+      try {
+        const cfg = this.configService.config as any;
+        return (cfg?.database?.defaultAdapter as PersistenceAdapterType) ?? DEFAULT_PERSISTENCE_ADAPTER;
+      } catch {
+        return DEFAULT_PERSISTENCE_ADAPTER;
+      }
+    })();
+
+    // Always use registry as the single source of truth.
+    const resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
+
+    const adapterToUse: PersistenceAdapterType =
+      (resourceConfiguration as any)?.persistenceAdapter ?? defaultAdapter;
+
+    let repository: BackendResourceRepository<any, any, any>;
+
+    if (adapterToUse === 'postgresql') {
+      repository = new PostgreSQLResourceRepositoryBackendService(
+        resourceType,
+        this.postgresqlDb,
+        this.logger,
+        this.errorBuilder,
+        this.resourceRegistry,
+        this.resourceOperationHelper,
+        this,
+        this.zodToSqlPlanner,
+        this.resourceIdService
+      ) as any;
+    } else {
+      repository = RepositoryResourceBackendService.createInstance(
+        resourceType,
+        this.zodToMongooseConverter,
+        this.logger,
+        this.errorBuilder,
+        this.resourceRegistry,
+        this.resourceOperationHelper,
+        this as any,
+        connection,
+        this.resourceIdService
+      ) as any;
+    }
+
+    this.repositories.set(resourceType, repository);
+
+    this.logDebug('Repository created successfully', { resourceType,});
+  }
+
+  private buildOperationRepositoryPathsMap(): void {
+    this.logDebug('Building operation repository paths map');
+
+    let totalOperationRepositoryPaths = 0;
+
+    this.repositories.forEach((repository, resourceType) => {
+      const resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
+
+      if (!resourceConfiguration.operations) {
+        return;
+      }
+
+      resourceConfiguration.operations.forEach(operation => {
+        const operationRepositoryPath = ResourcesConfig_OperationPathUtils.extractOperationRepositoryPath(operation);
+        const operationRepositoryPathKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKey(operationRepositoryPath);
+
+        this.repositoryOperationsMap.set(operationRepositoryPathKey, {
+          repository,
+          operationRepositoryPath
+        });
+
+        totalOperationRepositoryPaths++;
+      });
+    });
+
+    this.logDebug('Operation repository paths map built', {
+      totalOperationRepositoryPaths,
+      operationRepositoryPathKeys: Array.from(this.repositoryOperationsMap.keys()).slice(0, 5) // Show first 5 as sample
+    });
+  }
+
+
+  // ================================
+  // Execute operations
+  // ================================
+
+  public async doByPath<T = any>(
+    operationRepositoryPath: ResourceConfiguration_OperationRepositoryPath,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    const operationRepositoryPathKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKey(operationRepositoryPath);
+
+    this.logDebug('Executing operation by repository path', { operationRepositoryPath, operationRepositoryPathKey, id_or_ids_or_filter });
+
+    return this.doByKey<T>( operationRepositoryPathKey, executionContext, id_or_ids_or_filter, data, options
+    );
+  }
+
+  /**
+   * Execute operation by operation repository path key (string)
+   */
+  public async doByKey<T = any>(
+    operationRepositoryPathKey: string,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    // Validate the key format first
+    ResourcesConfig_OperationPathUtils.validateOperationRepositoryPathKey(operationRepositoryPathKey);
+
+    const operationInfo = this.repositoryOperationsMap.get(operationRepositoryPathKey);
+
+    if (!operationInfo) {
+      throw this.errorBuilder.buildError( ErrorType.NOT_FOUND, executionContext,
+          { context: { operationRepositoryPathKey }, customMessageReference: ErrorCustomMessageReference.REPOSITORIES_REGISTRY_NOT_FOUND } );
+    }
+
+    this.logDebug('Executing operation by repository path key', { operationRepositoryPathKey, id_or_ids_or_filter });
+
+    return operationInfo.repository.doByPath( operationInfo.operationRepositoryPath, executionContext, id_or_ids_or_filter, data, options);
+  }
+
+  /**
+   * Execute operation by ExecutionContext shortcut
+   */
+  public async doByExecutionContext<T = any>(
+    executionContext: ExecutionContext<any>,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    const operation = executionContext.operation;
+    const resourceType = operation.resourceIdentifier as ResourceType;
+    const repository = this.getRepositoryOrThrow(resourceType, executionContext);
+
+    this.logDebug('Executing operation by execution context', { resourceType, operationIdentifier: operation.operationIdentifier });
+
+    return repository.doByExecutionContext(executionContext, data, options);
+  }
+
+  // ================================
+  // Getters
+  // ================================
+
+  public getRepository<
+    TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+    TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+    TMainSchema extends z.ZodTypeAny = z.ZodTypeAny,
+  >(
+    resourceType: ResourceType
+  ): BackendResourceRepository<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | undefined {
+    const repository = this.repositories.get(resourceType);
+
+    if (!repository) {
+      this.logDebug('Repository not found', { resourceType });
+      return undefined;
+    }
+
+    return repository as BackendResourceRepository<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+  }
+
+
+  public getRepositoryOrThrow<
+    TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+    TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+    TMainSchema extends z.ZodTypeAny = z.ZodTypeAny,
+  >(
+    resourceType: ResourceType,
+    executionContext?: ExecutionContext<any>
+  ): BackendResourceRepository<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> {
+    const repository = this.getRepository<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>(resourceType);
+
+    if (!repository) {
+      throw this.errorBuilder.buildError( ErrorType.NOT_FOUND, executionContext,
+          { context: { resourceType }, customMessageReference: ErrorCustomMessageReference.REPOSITORIES_REGISTRY_NOT_FOUND } );
+    }
+
+    return repository;
+  }
+
+
+  public getRegisteredResourceTypes(): ResourceType[] {
+    return Array.from(this.repositories.keys());
+  }
+
+  public getRepositoryCount(): number {
+    return this.repositories.size;
+  }
+
+  public getAvailableOperationRepositoryPaths(): ResourceConfiguration_OperationRepositoryPath[] {
+    return Array.from(this.repositoryOperationsMap.values()).map(info => info.operationRepositoryPath);
+  }
+
+  public hasRepository(resourceType: ResourceType): boolean {
+    return this.repositories.has(resourceType);
+  }
+
+
+  // ================================
+  // Framework-internal infrastructure queries
+  // ================================
+
+  /**
+   * Count documents matching a filter for a given resource type.
+   *
+   * @internal Framework-internal method for infrastructure concerns (e.g., uniqueness validation).
+   * NOT part of the operation lifecycle — the caller is responsible for:
+   * - Authorization (must be performed BEFORE calling this method)
+   * - Scope-aware filter construction (organizationId, userId filters, etc.)
+   * - Audit logging if required
+   *
+   * This method exists on the RepositoriesRegistryHandler (not on BackendResourceRepository)
+   * to ensure it cannot be called by custom app code via the repository interface.
+   *
+   * @param resourceType - The resource type to query
+   * @param filter - Pre-built filter (caller must have applied scope filtering)
+   * @param executionContext - For error context only (NOT used for authorization)
+   * @returns Number of documents matching the filter
+   */
+  public async countDocumentsForInfrastructure(
+    resourceType: ResourceType,
+    filter: Record<string, unknown>,
+    executionContext?: ExecutionContext<any>
+  ): Promise<number> {
+    const repository = this.getRepositoryOrThrow(resourceType, executionContext);
+
+    // Access the underlying database model via internal reference.
+    // This is intentionally not on the BackendResourceRepository public interface.
+    const mongooseModel = (repository as any).mongooseModel;
+    if (!mongooseModel) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORIES_REGISTRY_NOT_FOUND,
+        context: { resourceType, reason: 'No underlying database model found on repository' },
+      });
+    }
+
+    return mongooseModel.countDocuments(filter).exec();
+  }
+
+
+  /**
+   * Atomic conditional update using MongoDB operators.
+   *
+   * Performs a single `findOneAndUpdate` call with caller-supplied filter conditions
+   * and MongoDB update operators (e.g. `$inc`, `$set`). The operation is atomic at
+   * the database level — no intermediate reads that could race.
+   *
+   * @internal Framework-internal method for infrastructure concerns (e.g., credit pool consume).
+   * NOT part of the operation lifecycle — the caller is responsible for:
+   * - Authorization (must be performed BEFORE calling this method)
+   * - Scope-aware filter construction (organizationId, userId filters, etc.)
+   * - Audit logging if required
+   *
+   * @param resourceType - The resource type to update
+   * @param filter - MongoDB filter including guard conditions (e.g., `{ _id, available: { $gte: amount } }`)
+   * @param update - MongoDB update expression (e.g., `{ $inc: { available: -amount } }`)
+   * @param executionContext - For error context only (NOT used for authorization)
+   * @returns The updated document, or null if the filter matched 0 documents (guard failed or not found)
+   */
+  public async atomicConditionalUpdate<T = any>(
+    resourceType: ResourceType,
+    filter: Record<string, unknown>,
+    update: Record<string, unknown>,
+    executionContext?: ExecutionContext<any>,
+  ): Promise<T | null> {
+    const repository = this.getRepositoryOrThrow(resourceType, executionContext);
+
+    const mongooseModel = (repository as any).mongooseModel;
+    if (!mongooseModel) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORIES_REGISTRY_NOT_FOUND,
+        context: { resourceType, reason: 'No underlying database model found on repository' },
+      });
+    }
+
+    const doc = await mongooseModel.findOneAndUpdate(filter, update, { new: true }).exec();
+    return doc ? (doc.toObject ? doc.toObject() : doc) : null;
+  }
+
+  /**
+   * Bulk update documents matching a filter using MongoDB operators.
+   *
+   * Performs a single `updateMany` call to set fields on all matched documents
+   * atomically. Useful for infrastructure tasks like marking batches of records
+   * as processed.
+   *
+   * @internal Framework-internal method for infrastructure concerns.
+   * NOT part of the operation lifecycle — same caveats as `atomicConditionalUpdate`.
+   *
+   * @param resourceType - The resource type to update
+   * @param filter - MongoDB filter (e.g., `{ _id: { $in: ids } }`)
+   * @param update - MongoDB update expression (e.g., `{ $set: { reported: true } }`)
+   * @param executionContext - For error context only (NOT used for authorization)
+   * @returns The number of documents modified
+   */
+  public async bulkUpdateForInfrastructure(
+    resourceType: ResourceType,
+    filter: Record<string, unknown>,
+    update: Record<string, unknown>,
+    executionContext?: ExecutionContext<any>,
+  ): Promise<number> {
+    const repository = this.getRepositoryOrThrow(resourceType, executionContext);
+
+    const mongooseModel = (repository as any).mongooseModel;
+    if (!mongooseModel) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORIES_REGISTRY_NOT_FOUND,
+        context: { resourceType, reason: 'No underlying database model found on repository' },
+      });
+    }
+
+    const result = await mongooseModel.updateMany(filter, update).exec();
+    return result.modifiedCount ?? 0;
+  }
+
+
+// ================================
+// Debug methods
+// ================================
+
+  public getDebugInfo(): {
+    repositoryCount: number;
+    operationRepositoryPathsCount: number;
+    resourceTypes: ResourceType[];
+    isInitialized: boolean;
+  } {
+    return {
+      repositoryCount: this.repositories.size,
+      operationRepositoryPathsCount: this.repositoryOperationsMap.size,
+      resourceTypes: Array.from(this.repositories.keys()),
+      isInitialized: this.isInitialized
+    };
+  }
+
+  public debugDisplayMongooseSchemas(options: {
+    showSchemaStructure?: boolean;
+    showIndexes?: boolean;
+    showVirtuals?: boolean;
+    resourceTypeFilter?: string[];
+    maxFieldDepth?: number;
+  } = {}): void {
+    this.logDebug('Displaying Mongoose schemas debug info', {
+      repositories: this.repositories.size,
+      options
+    });
+
+    // Collect models from all repositories
+    const models: Model<any>[] = [];
+    const resourceTypes: string[] = [];
+
+    for (const [resourceType, repository] of this.repositories) {
+      // Apply resource type filter if specified
+      if (options.resourceTypeFilter && options.resourceTypeFilter.length > 0 &&
+          !options.resourceTypeFilter.includes(resourceType)) {
+        continue;
+      }
+
+      // Access the mongooseModel from the repository
+      const model = (repository as any).mongooseModel;
+      if (model) {
+        models.push(model);
+        resourceTypes.push(resourceType);
+      }
+    }
+
+    this.logDebug('\n🔍 === REPOSITORY MONGOOSE SCHEMAS DEBUG ===\n');
+    this.logDebug(`Found ${models.length} models from ${this.repositories.size} repositories`);
+
+    if (options.resourceTypeFilter && options.resourceTypeFilter.length > 0) {
+      this.logDebug(`Filtered for: [${options.resourceTypeFilter.join(', ')}]`);
+    }
+
+    this.logDebug(`Resource Types: [${resourceTypes.join(', ')}]\n`);
+
+    // Display each model individually using the simplified debug method
+    for (const model of models) {
+      this.zodToMongooseConverter.debugDisplayModelSchema(model, options.showSchemaStructure !== false);
+    }
+
+    this.logDebug('================================================\n');
+  }
+
+  /**
+   * Quick debug function to show schemas summary
+   */
+  public debugShowSchemasSummary(): void {
+    this.logDebug('Displaying schemas summary');
+
+    // Collect models from all repositories
+    const models: Model<any>[] = [];
+
+    for (const [resourceType, repository] of this.repositories) {
+      const model = (repository as any).mongooseModel;
+      if (model) {
+        models.push(model);
+      }
+    }
+
+    this.zodToMongooseConverter.debugShowModelsSummary(models);
+  }
+
+  /**
+   * Validate and filter request data against operation DTO
+   * NOTE: This assumes data has already been cleaned by cleanInputData()
+   */
+  public validateRequestData(data: any, resourceType: ResourceType, operationIdentifier: string): any {
+    if (!data || typeof data !== 'object') {
+      return data;
+    }
+
+    // Get the resource configuration to find the operation
+    const resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
+
+    if (!resourceConfiguration.operations) {
+      // If no operations defined, data is already cleaned so return as-is
+      return data;
+    }
+
+    // Find the operation to get its requestDto
+    const operation = resourceConfiguration.operations.find(op =>
+      op.operationIdentifier === operationIdentifier
+    );
+
+    if (!operation || !operation.requestDto) {
+      // If no operation or requestDto found, data is already cleaned so return as-is
+      return data;
+    }
+
+    try {
+      // Validate against the operation's requestDto
+      const validatedData = operation.requestDto.parse(data);
+      this.logDebug('Request data validation successful', {
+        resourceType,
+        operationIdentifier,
+        validatedKeys: typeof validatedData === 'object' ? Object.keys(validatedData) : 'not-object'
+      });
+      return validatedData;
+    } catch (error) {
+      this.logDebug('Request data validation failed', {
+        resourceType,
+        operationIdentifier,
+        error: error instanceof Error ? error.message : 'Unknown validation error',
+        dataKeys: typeof data === 'object' ? Object.keys(data) : 'not-object',
+        data: data
+      });
+
+      if (error instanceof z.ZodError) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+          stack: error.stack,
+          context: {
+            resourceType,
+            operationIdentifier,
+            inputData: data,
+            zodIssues: error.issues,
+          }
+        });
+      }
+
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: {
+          resourceType,
+          operationIdentifier,
+          inputData: data,
+          error: error instanceof Error ? error.message : String(error),
+        }
+      });
+    }
+  }
+
+  /**
+   * Validate the payload slice that repositories actually persist.
+   *
+   * For bulk writes, the service/controller layer validates the full bulk
+   * envelope. Repositories only receive the per-row create item or the shared
+   * update patch, so repository validation must intentionally target that write
+   * slice rather than the bulk transport wrapper.
+   */
+  public validateRepositoryWriteData(
+    data: any,
+    resourceType: ResourceType,
+    operationIdentifier: string,
+    isBulkOperation: boolean = false
+  ): any {
+    if (!data || typeof data !== 'object') {
+      return data;
+    }
+
+    const resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
+    if (!resourceConfiguration.operations) {
+      return data;
+    }
+
+    const operation = resourceConfiguration.operations.find((candidate) => {
+      const candidateIsBulkOperation = 'isBulkOperation' in candidate && candidate.isBulkOperation === true;
+
+      return candidate.operationIdentifier === operationIdentifier
+        && candidateIsBulkOperation === isBulkOperation;
+    });
+
+    if (!operation) {
+      return data;
+    }
+
+    const validationOperation =
+      isBulkOperation && (
+        operationIdentifier === CoreResourceOperation.CREATE
+        || operationIdentifier === CoreResourceOperation.UPDATE
+      )
+        ? resourceConfiguration.operations.find((candidate) => {
+            const candidateIsBulkOperation = 'isBulkOperation' in candidate && candidate.isBulkOperation === true;
+
+            return candidate.operationIdentifier === operationIdentifier
+              && candidateIsBulkOperation === false;
+          }) ?? operation
+        : operation;
+
+    if (!validationOperation.requestDto) {
+      return data;
+    }
+
+    try {
+      const validatedData = validationOperation.requestDto.parse(data);
+      this.logDebug('Repository write payload validation successful', {
+        resourceType,
+        operationIdentifier,
+        isBulkOperation,
+        validatedKeys: typeof validatedData === 'object' ? Object.keys(validatedData) : 'not-object'
+      });
+      return validatedData;
+    } catch (error) {
+      this.logDebug('Repository write payload validation failed', {
+        resourceType,
+        operationIdentifier,
+        isBulkOperation,
+        error: error instanceof Error ? error.message : 'Unknown validation error',
+        dataKeys: typeof data === 'object' ? Object.keys(data) : 'not-object',
+        data,
+      });
+
+      if (error instanceof z.ZodError) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+          stack: error.stack,
+          context: {
+            resourceType,
+            operationIdentifier,
+            isBulkOperation,
+            inputData: data,
+            zodIssues: error.issues,
+          }
+        });
+      }
+
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+        context: {
+          resourceType,
+          operationIdentifier,
+          isBulkOperation,
+          inputData: data,
+          error: error instanceof Error ? error.message : String(error),
+        }
+      });
+    }
+  }
+}