@wildo-ai/saas-backend-lib 1.0.1

package/src/base-classes/services/repositories/repository-resource.backend.service.ts

@@ -0,0 +1,2186 @@
+import 'reflect-metadata';
+
+import type {
+  ResourceConfiguration,
+  ResourceConfiguration_Operation,
+  ResourceConfiguration_OperationRepositoryPath,
+  CollectionView_SearchOptions,
+  Resources_PaginationRequest
+} from '@wildo-ai/saas-models';
+import {
+  CoreResourceOperation,
+  ErrorCustomMessageReference,
+  ErrorType,
+  ResourceOperationsUtils,
+  Resources_PaginatedResult,
+  ResourcesConfig_OperationPathUtils,
+  ResourceType,
+  WildoError_Backend
+} from '@wildo-ai/saas-models';
+import { EnumLikeType } from '@wildo-ai/zod-decorators';
+import type { FieldMetaEntry } from '@wildo-ai/saas-models';
+import {
+  lwwFieldWinner,
+  CrdtResolutionWinner,
+  nextMonotonicTimestamp,
+  isCrdtOnlyUpdate,
+  sanitizeFieldMeta,
+  extractCrdtFieldNames,
+} from '@wildo-ai/saas-models';
+import { Connection, Document, FilterQuery, Model, Types } from 'mongoose';
+
+import { z } from 'zod';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { ZodToMongooseSchemaConvertorBackendService } from '~wildo-backend-lib/databases/services/zod-to-mongoose-schema-convertor.backend.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { ResourceIdBackendService } from '~wildo-backend-lib/resources/services/resource-id.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { IdOrFilterType, IdOrIdsOrFilterType, IdsOrFilterType, RepositoryOptions } from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';
+import { ResourceOperationHelperBackendService } from '~wildo-backend-lib/base-classes/services/resource-operations-helper.backend.service';
+import {
+  MainSchemaType,
+  PartialMainSchemaType,
+  MainSchemaArrayType,
+  ConditionalReturnType,
+  ConditionalArrayReturnType,
+  ConditionalNullableReturnType
+} from '~wildo-backend-lib/base-classes/utils/backend-type-utils';
+
+
+const DEBUG_ACTIVATED = false;
+
+// Forward declaration to avoid circular dependency
+type RepositoriesRegistryHandlerBackendService = any;
+
+/**
+ * Factory interface for creating repository resource instances
+ *
+ * NOTE: TDatabaseSchema has been removed. Backend-only fields are now marked with
+ * the `isBackendOnly` decorator on mainSchema and handled at the service layer.
+ */
+export interface RepositoryResourceFactory {
+  create<
+    TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+    TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+    TMainSchema extends z.ZodTypeAny = z.ZodTypeAny
+  >(
+    resourceConfiguration: ResourceConfiguration<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): RepositoryResourceBackendService<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+}
+
+/**
+ * MongoDB Repository Implementation
+ *
+ * This class provides the MongoDB/Mongoose implementation of the resource repository.
+ * It conforms to the `BackendResourceRepository` interface contract through TypeScript's
+ * structural typing.
+ *
+ * ## Transaction Support
+ *
+ * Uses the `getNativeSession()` helper to extract the Mongoose ClientSession from
+ * the database-agnostic `options.transaction.nativeSession` (TransactionContext).
+ *
+ * @see BackendResourceRepository in repositories-registry-handler.backend.service.ts
+ * @see PostgreSQLResourceRepositoryBackendService for PostgreSQL implementation
+ */
+export class RepositoryResourceBackendService<
+  TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+  TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+  TMainSchema extends z.ZodTypeAny = z.ZodTypeAny
+> {
+
+  private readonly resourceConfiguration: ResourceConfiguration<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+  private readonly mongooseModel: Model<any & Document>;
+  private readonly inheritanceModels: Map<string, Model<any & Document>>;
+  private readonly operationsMap: Map<string, ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>>;
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    resourceType: ResourceType,
+    private readonly zodToMongooseConverter: ZodToMongooseSchemaConvertorBackendService,
+    private readonly logger: LoggerService,
+    private readonly errorBuilder: ErrorBuilderBackendService,
+    private readonly resourceRegistry: ResourcesRegistryBackendService,
+    private readonly resourceOperationHelper: ResourceOperationHelperBackendService,
+    private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    private readonly connection: Connection | undefined = undefined,
+    private readonly resourceIdService?: ResourceIdBackendService,
+  ) {
+    this.resourceConfiguration = this.resourceRegistry.getResourceConfiguration(resourceType);
+    this.zodToMongooseConverter = zodToMongooseConverter;
+
+    this.inheritanceModels = new Map();
+    this.operationsMap = new Map();
+
+    this.logDebug = this.logger.debugByType(`RepositoryResource_${resourceType}`);
+    this.logger.setDebugTypeLogging(`RepositoryResource_${resourceType}`, DEBUG_ACTIVATED);
+
+    // Initialize mongoose model and operations
+    this.mongooseModel = this.initializeMongooseModel();
+    this.initializeOperationsMap();
+
+    this.logDebug('Repository resource service created', { resourceType: this.resourceConfiguration.resourceIdentifier, operationsCount: this.operationsMap.size, hasInheritance: this.inheritanceModels.size > 0 });
+  }
+
+  // ================================
+  // Transaction Session Helper
+  // ================================
+
+  /**
+   * Get the native Mongoose session from repository options.
+   *
+   * Extracts the Mongoose ClientSession from the database-agnostic TransactionContext.
+   * Includes runtime safety check to ensure MongoDB repository doesn't receive
+   * a PostgreSQL transaction context.
+   *
+   * @param options - Repository options that may contain transaction
+   * @returns The Mongoose ClientSession or undefined
+   * @throws Error if a non-MongoDB transaction is provided
+   */
+  protected getNativeSession(options?: RepositoryOptions): import('mongoose').ClientSession | undefined {
+    if (!options?.transaction) {
+      return undefined;
+    }
+
+    // Runtime safety check: ensure this is a MongoDB transaction
+    if (options.transaction.databaseType !== 'mongodb') {
+      throw new Error(
+        `MongoDB repository received non-MongoDB transaction. ` +
+        `Expected databaseType='mongodb', got '${options.transaction.databaseType}'. ` +
+        `This indicates a configuration error where a resource is using the wrong persistence adapter.`
+      );
+    }
+    return options.transaction.nativeSession as import('mongoose').ClientSession | undefined;
+  }
+
+  // ================================
+  // Initialization
+  // ================================
+
+  static createInstance<
+    TCustomOperationEnum extends EnumLikeType | undefined = undefined,
+    TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined,
+    TMainSchema extends z.ZodTypeAny = z.ZodTypeAny
+    >(
+      resourceType: ResourceType,
+      zodToMongooseConverter: ZodToMongooseSchemaConvertorBackendService,
+      logger: LoggerService,
+      errorBuilder: ErrorBuilderBackendService,
+      resourceRegistry: ResourcesRegistryBackendService,
+      resourceOperationHelper: ResourceOperationHelperBackendService,
+      repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+      connection: Connection | undefined = undefined,
+      resourceIdService?: ResourceIdBackendService,
+  ): RepositoryResourceBackendService<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> {
+    return new RepositoryResourceBackendService(
+      resourceType,
+      zodToMongooseConverter,
+      logger,
+      errorBuilder,
+      resourceRegistry,
+      resourceOperationHelper,
+      repositoriesRegistry,
+      connection,
+      resourceIdService,
+    );
+  }
+
+  private initializeOperationsMap(): void {
+    if (!this.resourceConfiguration.operations) {
+      return;
+    }
+
+    this.resourceConfiguration.operations.forEach(operation => {
+      const operationKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKeyFromOperation(operation as any);
+      this.operationsMap.set(operationKey, operation);
+    });
+
+    this.logDebug('Operations map initialized', {
+      operationsCount: this.operationsMap.size,
+      operationKeys: Array.from(this.operationsMap.keys())
+    });
+  }
+
+  private initializeMongooseModel(): Model<any & Document> {
+    try {
+      const modelResult = this.zodToMongooseConverter.convertResourceConfigurationToModel(
+        this.resourceConfiguration,
+        {
+          includeIndexes: true,
+          applyDefaults: true,
+          connection: this.connection
+        }
+      );
+
+      // Store inheritance models if any
+      // Use a Set to track created discriminator values to avoid duplicates
+      const createdDiscriminatorValues = new Set<string>();
+      modelResult.inheritanceSchemas.forEach(inheritance => {
+        // Skip if discriminator with this value already exists
+        if (createdDiscriminatorValues.has(inheritance.discriminatorValue)) {
+          this.logDebug(`Skipping duplicate discriminator value: ${inheritance.discriminatorValue}`, {
+            discriminatorKey: inheritance.discriminatorKey,
+            discriminatorValue: inheritance.discriminatorValue
+          });
+          return;
+        }
+
+        try {
+          // Check if discriminator already exists on the model
+          const existingDiscriminator = (modelResult.mainModel as any).discriminators?.[inheritance.discriminatorValue];
+          if (existingDiscriminator) {
+            this.logDebug(`Discriminator already exists, reusing: ${inheritance.discriminatorValue}`, {
+              discriminatorKey: inheritance.discriminatorKey,
+              discriminatorValue: inheritance.discriminatorValue
+            });
+            this.inheritanceModels.set(inheritance.discriminatorValue, existingDiscriminator);
+            createdDiscriminatorValues.add(inheritance.discriminatorValue);
+            return;
+          }
+
+          // Create inheritance model from schema
+          const inheritanceModel = modelResult.mainModel.discriminator(
+            inheritance.discriminatorValue,
+            inheritance.schema
+          );
+          this.inheritanceModels.set(inheritance.discriminatorValue, inheritanceModel);
+          createdDiscriminatorValues.add(inheritance.discriminatorValue);
+        } catch (error: any) {
+          // If discriminator already exists, try to get it
+          if (error?.message?.includes('already exists')) {
+            this.logDebug(`Discriminator already exists, attempting to retrieve: ${inheritance.discriminatorValue}`, {
+              discriminatorKey: inheritance.discriminatorKey,
+              discriminatorValue: inheritance.discriminatorValue
+            });
+            const existingDiscriminator = (modelResult.mainModel as any).discriminators?.[inheritance.discriminatorValue];
+            if (existingDiscriminator) {
+              this.inheritanceModels.set(inheritance.discriminatorValue, existingDiscriminator);
+              createdDiscriminatorValues.add(inheritance.discriminatorValue);
+            } else {
+              this.logger.warn(`Failed to create or retrieve discriminator: ${inheritance.discriminatorValue}`, {
+                error: error.message,
+                discriminatorKey: inheritance.discriminatorKey
+              });
+            }
+          } else {
+            throw error;
+          }
+        }
+      });
+
+      this.logDebug('Mongoose model initialized', {
+        modelName: modelResult.mainModel.modelName,
+        inheritanceCount: this.inheritanceModels.size
+      });
+
+      return modelResult.mainModel;
+    } catch (error) {
+      this.logger.error('Failed to initialize mongoose model', {
+        resourceType: this.resourceConfiguration.resourceIdentifier,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+      throw error;
+    }
+  }
+
+
+  // ================================
+  // Getters
+  // ================================
+
+  public getInheritanceModel(discriminatorValue: string): Model<any & Document> | undefined {
+    return this.inheritanceModels.get(discriminatorValue);
+  }
+
+  // ================================
+  // Execution
+  // ================================
+
+  public async doByPath<T = any, U = any>(
+    operationRepositoryPath: ResourceConfiguration_OperationRepositoryPath,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: U,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    const operationRepositoryPathKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKey(operationRepositoryPath);
+
+    this.logDebug('Executing operation by repository path', { operationRepositoryPath, operationRepositoryPathKey, hasData: !!data, id_or_ids_or_filter });
+
+    return this.doByKey( operationRepositoryPathKey, executionContext, id_or_ids_or_filter, data, options );
+  }
+
+  /**
+   * Execute operation by operation repository path key (string)
+   */
+  public async doByKey<T = any, U = any>(
+    operationRepositoryPathKey: string,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: U,
+    options?: RepositoryOptions
+  ): Promise<T> {
+
+    ResourcesConfig_OperationPathUtils.validateOperationRepositoryPathKey(operationRepositoryPathKey);
+
+    const operation = this.operationsMap.get(operationRepositoryPathKey);
+
+    if (!operation) {
+      throw this.errorBuilder.buildError( ErrorType.NOT_FOUND, executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationRepositoryPathKey } } );
+    }
+
+    this.logDebug('Executing operation by repository path key', { operationRepositoryPathKey, hasData: !!data, id_or_ids_or_filter });
+
+    return this.doOperation(operation, executionContext, id_or_ids_or_filter, data, options);
+  }
+
+  public async doByExecutionContext<T = any>(
+    executionContext: ExecutionContext<ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>>,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<T> {
+    const operation = executionContext.operation;
+
+    // Extract IDs based on resourceFieldIdentifier from execution context
+    const id_or_ids_or_filter = this.resourceOperationHelper.extractIdsFromExecutionContext(executionContext, this.resourceConfiguration.resourceFieldIdentifier);
+
+    this.logDebug('Executing operation by execution context', {
+      operationIdentifier: operation.operationIdentifier,
+      resourceIdentifier: operation.resourceIdentifier,
+      hasData: !!data,
+      extractedIds: id_or_ids_or_filter,
+      resourceFieldIdentifier: this.resourceConfiguration.resourceFieldIdentifier
+    });
+
+    return this.doOperation(operation, executionContext, id_or_ids_or_filter, data, options);
+  }
+
+  private async _prefixOperation(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Authorization is handled at the controller/middleware layer before reaching the repository.
+    // Repository-level prefix operations are reserved for data-level pre-processing (e.g., input normalization).
+    // Operation-level authorization is enforced by the ResourceOperationService via role + variant checks.
+  }
+
+  private async _postfixOperation(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Post-operation hook reserved for data-level post-processing (e.g., cache invalidation).
+    // Currently no-op by design — business logic runs at the service layer.
+  }
+
+   /**
+   * Execute a specific operation
+   */
+   private async doOperation(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_ids_or_filter?: IdOrIdsOrFilterType,
+    data?: any,
+    options?: RepositoryOptions
+  ): Promise<any> {
+    const operationRepositoryPathKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKeyFromOperation(operation);
+
+    if(operation.resourceIdentifier !== this.resourceConfiguration.resourceIdentifier) {
+      throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationRepositoryPathKey, resourceIdentifier: this.resourceConfiguration.resourceIdentifier } } );
+    }
+    const operationIdentifier = ResourceOperationsUtils.getCoreResourceOperationFromOperation(operation);
+
+    if (!operationIdentifier) {
+
+      throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationRepositoryPathKey } } );
+    }
+
+    await this._prefixOperation(operation, executionContext, id_or_ids_or_filter, data, options);
+
+    let operationResult: any;
+    // Handle core operations
+    switch (operationIdentifier) {
+      case CoreResourceOperation.CREATE:
+        operationResult = await this._doCreate(operation, executionContext, data, options);
+        break;
+
+      case CoreResourceOperation.CREATE_MANY:
+        operationResult = await this._doCreateMany(operation, executionContext, data, options);
+        break;
+
+      case CoreResourceOperation.READ:
+        if(Array.isArray(id_or_ids_or_filter)) {
+          throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+            { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+              context: { operationRepositoryPathKey, resourceIdentifier: this.resourceConfiguration.resourceIdentifier, id_or_ids_or_filter } } );
+        }
+        operationResult = await this._doRead(operation, executionContext, id_or_ids_or_filter as IdOrFilterType, options);
+        break;
+
+      case CoreResourceOperation.UPDATE:
+        if(Array.isArray(id_or_ids_or_filter)) {
+          throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+            { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+              context: { operationRepositoryPathKey, resourceIdentifier: this.resourceConfiguration.resourceIdentifier, id_or_ids_or_filter } } );
+        }
+        operationResult = await this._doUpdate(operation, executionContext, id_or_ids_or_filter as IdOrFilterType, data, options);
+        break;
+
+      case CoreResourceOperation.UPDATE_MANY:
+        operationResult = await this._doUpdateMany(operation, executionContext, id_or_ids_or_filter as IdsOrFilterType, data, options);
+        break;
+
+      case CoreResourceOperation.DELETE:
+        if(Array.isArray(id_or_ids_or_filter)) {
+          throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+            { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED,
+              context: { operationRepositoryPathKey, resourceIdentifier: this.resourceConfiguration.resourceIdentifier, id_or_ids_or_filter } } );
+        }
+        operationResult = await this._doDelete(operation, executionContext, id_or_ids_or_filter as IdOrIdsOrFilterType, options);
+        break;
+
+      case CoreResourceOperation.DELETE_MANY:
+        const idToDelete = typeof id_or_ids_or_filter === 'string' ? [id_or_ids_or_filter] : id_or_ids_or_filter;
+        operationResult = await this._doDeleteMany(operation, executionContext, idToDelete as IdsOrFilterType, options);
+        break;
+
+      case CoreResourceOperation.LIST:
+        // For LIST operation, return paginated format
+        const idsToList = typeof id_or_ids_or_filter === 'string' ? [id_or_ids_or_filter] : id_or_ids_or_filter;
+        const listResult = await this._doList(operation, executionContext, idsToList as IdsOrFilterType, options);
+        operationResult = listResult;
+        break;
+
+      case CoreResourceOperation.COUNT:
+        operationResult = await this._doCount(
+          operation,
+          executionContext,
+          (data?.filter as FilterQuery<any>) ?? {},
+          options,
+        );
+        break;
+
+      case CoreResourceOperation.SEARCH:
+        operationResult = await this._doSearch(
+          operation,
+          executionContext,
+          data?.query || '',
+          (data?.filter as FilterQuery<any>) ?? {},
+          {
+            ...options,
+            searchOptions: (options as { searchOptions?: { fieldsToSearch?: string[]; page?: number; limit?: number; sort?: any; } } | undefined)?.searchOptions ?? {},
+          } as RepositoryOptions & { searchOptions: { fieldsToSearch?: string[]; page?: number; limit?: number; sort?: any; } },
+        );
+        break;
+
+      default:
+        // Handle custom operations
+        throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+          { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { resourceIdentifier: this.resourceConfiguration.resourceIdentifier, operationIdentifier } });
+    }
+
+    await this._postfixOperation(operation, executionContext, id_or_ids_or_filter, data, options);
+
+    return operationResult;
+  }
+
+
+
+  // ================================
+  // Core Public Operations
+  // ================================
+
+    public async create<T = undefined>(
+    executionContext: ExecutionContext<any>,
+    data: MainSchemaType<TMainSchema>,
+    options?: RepositoryOptions
+  ): Promise<ConditionalReturnType<T, TMainSchema>> {
+    const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.CREATE && op.isDefault);
+    if (!operation) {
+      throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.CREATE } } );
+    }
+    await this._prefixOperation(operation, executionContext, undefined, data, options);
+    const result = await this._doCreate(operation, executionContext, data, options);
+    await this._postfixOperation(operation, executionContext, undefined, data, options);
+    return result as ConditionalReturnType<T, TMainSchema>;
+  }
+
+  public async createMany<T = undefined>(
+     executionContext: ExecutionContext<any>,
+     data: MainSchemaArrayType<TMainSchema>,
+     options?: RepositoryOptions
+   ): Promise<ConditionalArrayReturnType<T, TMainSchema>> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.CREATE_MANY && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.CREATE_MANY } } );
+     }
+         await this._prefixOperation(operation, executionContext, undefined, data, options);
+    const result = await this._doCreateMany(operation, executionContext, data, options);
+    await this._postfixOperation(operation, executionContext, undefined, data, options);
+    return result as ConditionalArrayReturnType<T, TMainSchema>;
+   }
+
+   public async read<T = undefined>(
+     executionContext: ExecutionContext<any>,
+     id_or_filter: IdOrFilterType,
+     options?: RepositoryOptions
+   ): Promise<ConditionalNullableReturnType<T, TMainSchema>> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.READ && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.READ } } );
+     }
+     await this._prefixOperation(operation, executionContext, id_or_filter, undefined, options);
+     const result = await this._doRead(operation, executionContext, id_or_filter, options);
+     await this._postfixOperation(operation, executionContext, id_or_filter, undefined, options);
+     return result as ConditionalNullableReturnType<T, TMainSchema>;
+   }
+
+   public async update<T = undefined>(
+     executionContext: ExecutionContext<any>,
+     id_or_filter: IdOrFilterType,
+     data: PartialMainSchemaType<TMainSchema>,
+     options?: RepositoryOptions
+   ): Promise<ConditionalNullableReturnType<T, TMainSchema>> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.UPDATE && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.UPDATE } } );
+     }
+     await this._prefixOperation(operation, executionContext, id_or_filter, data, options);
+     const result = await this._doUpdate(operation, executionContext, id_or_filter, data, options);
+     await this._postfixOperation(operation, executionContext, id_or_filter, data, options);
+     return result as ConditionalNullableReturnType<T, TMainSchema>;
+   }
+
+   public async updateMany<T = undefined>(
+     executionContext: ExecutionContext<any>,
+     data: PartialMainSchemaType<TMainSchema>,
+     options?: RepositoryOptions
+   ): Promise<ConditionalArrayReturnType<T, TMainSchema>> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.UPDATE_MANY && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.UPDATE_MANY } } );
+     }
+        await this._prefixOperation(operation, executionContext, undefined, data, options);
+   const result = await this._doUpdateMany(operation, executionContext, undefined, data, options);
+   await this._postfixOperation(operation, executionContext, undefined, data, options);
+    return result as ConditionalArrayReturnType<T, TMainSchema>;
+   }
+
+   public async delete(
+     executionContext: ExecutionContext<any>,
+     id_or_ids_or_filter: IdOrIdsOrFilterType,
+     options?: RepositoryOptions
+   ): Promise<string> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.DELETE && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.DELETE } } );
+     }
+     await this._prefixOperation(operation, executionContext, id_or_ids_or_filter, undefined, options);
+     const result = await this._doDelete(operation, executionContext, id_or_ids_or_filter, options);
+     await this._postfixOperation(operation, executionContext, id_or_ids_or_filter, undefined, options);
+     return result;
+   }
+
+   public async deleteMany(
+     executionContext: ExecutionContext<any>,
+     ids_or_filter: IdsOrFilterType,
+     options?: RepositoryOptions
+   ): Promise<string[]> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.DELETE_MANY && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.DELETE_MANY } } );
+     }
+     await this._prefixOperation(operation, executionContext, ids_or_filter, undefined, options);
+     const result = await this._doDeleteMany(operation, executionContext, ids_or_filter, options);
+     await this._postfixOperation(operation, executionContext, ids_or_filter, undefined, options);
+     return result;
+   }
+
+   public async list<T = undefined>(
+     executionContext: ExecutionContext<any>,
+     ids_or_filter: IdsOrFilterType,
+     options?: RepositoryOptions
+   ): Promise<ConditionalArrayReturnType<T, TMainSchema>> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.LIST && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.LIST } } );
+     }
+         await this._prefixOperation(operation, executionContext, ids_or_filter, undefined, options);
+    const result = await this._doList(operation, executionContext, ids_or_filter, options);
+    await this._postfixOperation(operation, executionContext, ids_or_filter, undefined, options);
+    return result as ConditionalArrayReturnType<T, TMainSchema>;
+   }
+
+   public async search<T = any>(
+     executionContext: ExecutionContext<any>,
+     searchQuery: string,
+     filter: FilterQuery<any> = {},
+     searchOptions: { fieldsToSearch?: string[]; page?: number; limit?: number; sort?: any} = {},
+     options?: RepositoryOptions
+   ): Promise<Resources_PaginatedResult<T>> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.SEARCH && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.SEARCH } } );
+     }
+     const searchOptionsWithDefaults = { searchOptions, ...options };
+     await this._prefixOperation(operation, executionContext, undefined, { query: searchQuery }, searchOptionsWithDefaults);
+     const result = await this._doSearch(operation, executionContext, searchQuery, filter, searchOptionsWithDefaults);
+     await this._postfixOperation(operation, executionContext, undefined, { query: searchQuery }, searchOptionsWithDefaults);
+     return result;
+   }
+
+   public supportsOperation(operationIdentifier: string): boolean {
+     return this.resourceConfiguration.operations.some(
+       op => op.operationIdentifier === operationIdentifier && op.isDefault
+     );
+   }
+
+   public async count(
+     executionContext: ExecutionContext<any>,
+     filter: FilterQuery<any> = {},
+     options?: RepositoryOptions
+   ): Promise<{ count: number }> {
+     const operation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.COUNT && op.isDefault);
+     if (!operation) {
+       throw this.errorBuilder.buildError( ErrorType.INTERNAL, executionContext,
+         { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { operationIdentifier: CoreResourceOperation.COUNT } } );
+     }
+     await this._prefixOperation(operation, executionContext, undefined, filter, options);
+     const result = await this._doCount(operation, executionContext, filter, options);
+     await this._postfixOperation(operation, executionContext, undefined, filter, options);
+     return result;
+   }
+
+  /**
+   * Aggregate a numeric field across documents matching the filter.
+   * Framework infrastructure method for feature limit enforcement.
+   *
+   * Uses MongoDB aggregation pipeline: $match (with buildContextualFilter) + $group.
+   * Handles null/undefined field values via $ifNull.
+   * Does NOT require a COUNT operation to be configured (not API-facing).
+   *
+   * @param executionContext - Current execution context (used for scope filtering)
+   * @param filter - Additional filter criteria (scope is added automatically by buildContextualFilter)
+   * @param field - The document field to aggregate
+   * @param operation - The aggregation operation (SUM, AVG, MAX)
+   * @returns The aggregated numeric result (0 if no matching documents)
+   */
+  public async aggregateField(
+    executionContext: ExecutionContext<any>,
+    filter: FilterQuery<any>,
+    field: string,
+    operation: string,
+  ): Promise<number> {
+    const contextualFilter = this.buildContextualFilter(executionContext, filter);
+
+    // Map operation string to MongoDB aggregation operator
+    let mongoOp: string;
+    switch (operation) {
+      case 'SUM':
+        mongoOp = '$sum';
+        break;
+      case 'AVG':
+        mongoOp = '$avg';
+        break;
+      case 'MAX':
+        mongoOp = '$max';
+        break;
+      default:
+        mongoOp = '$sum';
+    }
+
+    const pipeline = [
+      { $match: contextualFilter },
+      {
+        $group: {
+          _id: null,
+          result: { [mongoOp]: { $ifNull: [`$${field}`, 0] } },
+        },
+      },
+    ];
+
+    this.logDebug('Aggregating field', { field, operation, filter: contextualFilter });
+
+    const results = await this.mongooseModel.aggregate(pipeline).exec();
+    const value = results.length > 0 ? (results[0].result ?? 0) : 0;
+
+    this.logDebug('Aggregation result', { field, operation, value });
+    return value;
+  }
+
+  // ================================
+  // Core Private Operations
+  // ================================
+
+  private async _doCreate<T = undefined>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    data: MainSchemaType<TMainSchema>,
+    options?: RepositoryOptions
+  ): Promise<ConditionalReturnType<T, TMainSchema>> {
+    this.logDebug('Creating resource', { hasData: !!data, dataKeys: typeof data === 'object' ? Object.keys(data) : 'not-object' });
+
+    // Clean input data FIRST (remove mandatory discard fields)
+    const cleanedData = this.resourceOperationHelper.cleanInputData(data, CoreResourceOperation.CREATE);
+    this.logDebug('Data cleaned', { cleanedKeys: typeof cleanedData === 'object' ? Object.keys(cleanedData) : 'not-object' });
+
+    // Validate against request DTO (after cleaning)
+    const validatedData = this.repositoriesRegistry.validateRequestData(cleanedData, this.resourceConfiguration.resourceIdentifier as ResourceType, CoreResourceOperation.CREATE);
+    this.logDebug('Data validated against requestDto', { validatedKeys: typeof validatedData === 'object' ? Object.keys(validatedData) : 'not-object' });
+
+    // THEN apply execution context data enrichment to the validated data
+    const enrichedData = this.resourceOperationHelper.enrichDataWithContext(validatedData, executionContext, this.resourceConfiguration.mainSchema, this.resourceConfiguration.resourceFieldIdentifier, CoreResourceOperation.CREATE, options);
+    this.logDebug('Data enriched with context', { enrichedKeys: typeof enrichedData === 'object' ? Object.keys(enrichedData) : 'not-object' });
+
+    // Defense-in-depth: anonymous creation on isAnonymizable resources must have userId = null
+    if (executionContext.isAnonymousExecution() && this.resourceConfiguration.isAnonymizable) {
+      enrichedData.userId = null;
+    }
+
+    // Inject non-discriminator literal values from schema (e.g., scope: 'ORGANIZATION')
+    // These are fixed values excluded from CREATE DTOs but must be persisted
+    const dataWithLiterals = this.resourceOperationHelper.injectNonDiscriminatorLiteralValues(enrichedData, this.resourceConfiguration.mainSchema);
+    this.logDebug('Non-discriminator literals injected', { dataWithLiteralsKeys: typeof dataWithLiterals === 'object' ? Object.keys(dataWithLiterals) : 'not-object' });
+
+    // Add user tracking to enriched data
+    const dataWithUserTracking = this.addUserTracking(dataWithLiterals, executionContext, CoreResourceOperation.CREATE);
+    this.logDebug('User tracking added', { finalKeys: typeof dataWithUserTracking === 'object' ? Object.keys(dataWithUserTracking) : 'not-object' });
+
+    try {
+      const nativeSession = this.getNativeSession(options);
+      this.logDebug('Creating document with Model.create()...', {
+        hasTransaction: !!nativeSession
+      });
+
+      // Use transaction session if provided
+      const createOptions: any = nativeSession ? { session: nativeSession } : {};
+
+      // DEBUG: Log the exact data being passed to mongoose
+      this.logDebug('\n=== DEBUG: About to call mongoose create ===');
+      this.logDebug('dataWithUserTracking:', { dataWithUserTracking: JSON.stringify(dataWithUserTracking, null, 2) });
+      this.logDebug('keys:', { keys: Object.keys(dataWithUserTracking || {}) });
+      this.logDebug('dataType:', { dataType: typeof dataWithUserTracking });
+      this.logDebug('hasName:', { hasName: !!(dataWithUserTracking as any)?.name });
+      this.logDebug('hasSlug:', { hasSlug: !!(dataWithUserTracking as any)?.slug });
+      this.logDebug('nameValue:', (dataWithUserTracking as any)?.name);
+      this.logDebug('slugValue:', { slugValue: (dataWithUserTracking as any)?.slug });
+
+      // DEBUG: Log mongoose schema info
+      this.logDebug('Mongoose model name:', { mongooseModelName: this.mongooseModel.modelName });
+      this.logDebug('Mongoose schema paths:', { mongooseSchemaPaths: Object.keys(this.mongooseModel.schema.paths) });
+      this.logDebug('Required paths:', { requiredPaths: Object.keys(this.mongooseModel.schema.paths).filter(path => {
+        const schemaType = this.mongooseModel.schema.paths[path];
+        return schemaType.isRequired;
+      }) });
+
+      this.logDebug('Name field config:', { nameFieldConfig: this.mongooseModel.schema.paths['name']?.isRequired, nameFieldInstance: this.mongooseModel.schema.paths['name']?.instance });
+      this.logDebug('Slug field config:', { slugFieldConfig: this.mongooseModel.schema.paths['slug']?.isRequired, slugFieldInstance: this.mongooseModel.schema.paths['slug']?.instance });
+      this.logDebug('Status field config:', { statusFieldConfig: this.mongooseModel.schema.paths['status']?.isRequired, statusFieldInstance: this.mongooseModel.schema.paths['status']?.instance });
+      this.logDebug('=======================================\n');
+
+      // Use Model.create() instead of new Model().save() to allow MongoDB to auto-generate _id
+      const savedDocument = await this.mongooseModel.create(dataWithUserTracking);
+      this.logDebug('Document created successfully');
+
+      return this.transformDocumentToResponse(savedDocument, CoreResourceOperation.CREATE);
+    } catch (error) {
+      this.logDebug('Mongoose create failed', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        enrichedData: enrichedData,
+        hasTransaction: !!this.getNativeSession(options)
+      });
+
+      // Handle MongoDB unique constraint violations (E11000 duplicate key error)
+      throw this.handleMongoDBError(error, executionContext);
+    }
+  }
+
+
+  private async _doCreateMany<T = undefined>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    dataArray: MainSchemaArrayType<TMainSchema>,
+    options?: RepositoryOptions
+  ): Promise<ConditionalArrayReturnType<T, TMainSchema>> {
+    this.logDebug('Creating multiple resources', { count: dataArray.length });
+
+    // Clean input data FIRST (remove mandatory discard fields)
+    const cleanedDataArray = this.resourceOperationHelper.cleanInputDataArray(dataArray, CoreResourceOperation.CREATE_MANY);
+    this.logDebug('Data array cleaned', { count: cleanedDataArray.length });
+
+    // CreateMany always processes multiple items
+
+    // Validate and enrich each item
+    const isAnonymousCreate = executionContext.isAnonymousExecution() && this.resourceConfiguration.isAnonymizable;
+    const isBulkOperation = 'isBulkOperation' in operation && operation.isBulkOperation === true;
+    const processedDataArray = cleanedDataArray.map(data => {
+      const validatedData = this.repositoriesRegistry.validateRepositoryWriteData(
+        data,
+        this.resourceConfiguration.resourceIdentifier as ResourceType,
+        String(operation.operationIdentifier),
+        isBulkOperation
+      );
+      const enrichedData = this.resourceOperationHelper.enrichDataWithContext(validatedData, executionContext, this.resourceConfiguration.mainSchema, this.resourceConfiguration.resourceFieldIdentifier, CoreResourceOperation.CREATE_MANY, options);
+      if (isAnonymousCreate) { enrichedData.userId = null; }
+      // Inject non-discriminator literal values from schema
+      const dataWithLiterals = this.resourceOperationHelper.injectNonDiscriminatorLiteralValues(enrichedData, this.resourceConfiguration.mainSchema);
+      return this.addUserTracking(dataWithLiterals, executionContext, CoreResourceOperation.CREATE_MANY);
+    });
+
+    // Prepare mongoose options with transaction session if provided
+    const session = this.getNativeSession(options);
+    const mongooseOpts: any = session ? { session } : {};
+
+    this.logDebug('Creating multiple documents', {
+      count: processedDataArray.length,
+      hasTransaction: !!session
+    });
+
+    // insertMany returns an array of documents by default (not InsertManyResult unless rawResult: true)
+    // TypeScript infers the wrong type, so we cast through unknown
+    const documents = await this.mongooseModel.insertMany(processedDataArray, mongooseOpts) as unknown as any[];
+
+    return documents.map(doc => this.transformDocumentToResponse(doc, CoreResourceOperation.CREATE_MANY)) as ConditionalArrayReturnType<T, TMainSchema>;
+  }
+
+
+  private async _doRead<T = undefined>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_filter?: IdOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<ConditionalNullableReturnType<T, TMainSchema>> {
+    const session = this.getNativeSession(options);
+    this.logDebug('Reading resource', { id_or_filter, hasOptions: !!options, hasTransaction: !!session });
+
+    // Validate required parameter
+    this.validateIdOrIdsOrFilterRequired(
+      id_or_filter,
+      executionContext,
+      CoreResourceOperation.READ,
+      this.canReadViaContextWithoutExplicitId(operation, executionContext),
+    );
+
+    // Build base filter - read operation is always unitary (single entity)
+    const { baseFilter } = this.buildBaseFilterFromIdOrIdsOrFilter(id_or_filter, executionContext);
+
+    const filter = this.buildContextualFilter(executionContext, baseFilter, options);
+
+    // Prepare mongoose options with transaction session if provided
+    const mongooseOpts: any = session ? { session } : {};
+
+    // Read operation always returns single entity or null
+      const document = await this.mongooseModel.findOne(filter, null, mongooseOpts);
+      this.logDebug('Read single result', {
+        filter,
+        found: !!document,
+        preview: this.previewDocument(document),
+        hasTransaction: !!session
+      });
+
+      if (!document) {
+        return null;
+      }
+
+      return this.transformDocumentToResponse<T>(document, CoreResourceOperation.READ);
+  }
+
+
+  private async _doUpdate<T = undefined>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_filter?: IdOrFilterType,
+    data?: PartialMainSchemaType<TMainSchema>,
+    options?: RepositoryOptions
+  ): Promise<ConditionalNullableReturnType<T, TMainSchema>> {
+    this.logDebug('Updating resource', { id_or_filter, hasData: !!data, hasOptions: !!options });
+
+    // Validate required parameter
+    this.validateIdOrIdsOrFilterRequired(id_or_filter, executionContext, CoreResourceOperation.UPDATE);
+
+    if (!data) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { message: 'UPDATE requires data' } }
+      );
+    }
+
+    // Clean input data FIRST (remove mandatory discard fields)
+    const cleanedData = this.resourceOperationHelper.cleanInputData(data, CoreResourceOperation.UPDATE);
+    this.logDebug('Data cleaned for update', { cleanedKeys: typeof cleanedData === 'object' ? Object.keys(cleanedData) : 'not-object' });
+
+    // Validate against request DTO (after cleaning)
+    const validatedData = this.repositoriesRegistry.validateRequestData(cleanedData, this.resourceConfiguration.resourceIdentifier as ResourceType, CoreResourceOperation.UPDATE);
+    this.logDebug('Data validated against requestDto', { validatedKeys: typeof validatedData === 'object' ? Object.keys(validatedData) : 'not-object' });
+
+    // THEN apply execution context data enrichment to the validated data
+    const enrichedData = this.resourceOperationHelper.enrichDataWithContext(validatedData, executionContext, this.resourceConfiguration.mainSchema, this.resourceConfiguration.resourceFieldIdentifier, CoreResourceOperation.UPDATE, options);
+    this.logDebug('Data enriched with context', { enrichedKeys: typeof enrichedData === 'object' ? Object.keys(enrichedData) : 'not-object' });
+
+    // Add user tracking to enriched data
+    const dataWithUserTracking = this.addUserTracking(enrichedData, executionContext, CoreResourceOperation.UPDATE);
+    this.logDebug('User tracking added', { finalKeys: typeof dataWithUserTracking === 'object' ? Object.keys(dataWithUserTracking) : 'not-object' });
+
+    // Build base filter - update operation is always unitary (single entity)
+    const { baseFilter } = this.buildBaseFilterFromIdOrIdsOrFilter(id_or_filter, executionContext);
+
+    // Ensure we have some filter criteria
+    if (Object.keys(baseFilter).length === 0) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { message: 'UPDATE requires valid id_or_ids_or_filter parameter' } }
+      );
+    }
+
+    // Apply contextual filtering
+    const filter = this.buildContextualFilter(executionContext, baseFilter, options);
+
+    if (options?.ifMatchVersion !== undefined) {
+      filter._version_db_doc = options.ifMatchVersion;
+      this.logDebug('Optimistic locking: added version filter', { ifMatchVersion: options.ifMatchVersion });
+    }
+
+    // Prepare mongoose options with transaction session if provided
+    const session = this.getNativeSession(options);
+    const mongooseOpts: any = { runValidators: true, new: true };
+    if (session) {
+      mongooseOpts.session = session;
+    }
+
+    // Defense-in-depth: strip version fields from update data to prevent
+    // $set/$inc conflict on _version_db_doc
+    delete dataWithUserTracking._version_db_doc;
+    delete dataWithUserTracking._version;
+
+    // CRDT: userId needed by both the LWW merge and the version-conflict retry
+    const userId = options?.fieldTimestamps ? (executionContext.initiatorIds?.userId ?? 'unknown') : undefined;
+    const FIELD_META_CAP = 200;
+
+    // CRDT field-level LWW merge
+    // P1: The extra findOne (projection: _field_meta only) is an intentional round-trip —
+    // LWW needs the latest per-field server timestamps before findOneAndUpdate; a blind
+    // CAS without pre-read cannot compare client vs server field clocks.
+    if (options?.fieldTimestamps && Object.keys(options.fieldTimestamps).length > 0) {
+      const currentDoc = await this.mongooseModel.findOne(
+        { _id: baseFilter._id },
+        { _field_meta: 1 },
+        session ? { session } : undefined,
+      );
+
+      const currentFieldMeta: Record<string, FieldMetaEntry> = sanitizeFieldMeta(currentDoc?._field_meta);
+      const mergedFieldMeta: Record<string, FieldMetaEntry> = { ...currentFieldMeta };
+      const fieldsToRemoveFromUpdate: string[] = [];
+
+      for (const [field, clientTs] of Object.entries(options.fieldTimestamps)) {
+        const serverTs = currentFieldMeta[field]?.ts ?? 0;
+
+        if (lwwFieldWinner(clientTs, serverTs) === CrdtResolutionWinner.INCOMING) {
+          mergedFieldMeta[field] = { ts: nextMonotonicTimestamp(Date.now(), serverTs), by: userId! };
+        } else {
+          fieldsToRemoveFromUpdate.push(field);
+        }
+      }
+
+      for (const field of fieldsToRemoveFromUpdate) {
+        delete dataWithUserTracking[field];
+        this.logDebug('CRDT LWW: server wins for field', { field });
+      }
+
+      // D1: Schema-aware prune — remove _field_meta keys for fields no longer in the schema.
+      // Prevents unbounded growth after schema renames.
+      const validCrdtKeys = extractCrdtFieldNames(this.resourceConfiguration.mainSchema, false);
+      if (validCrdtKeys.size > 0) {
+        const staleKeys: string[] = [];
+        for (const key of Object.keys(mergedFieldMeta)) {
+          if (!validCrdtKeys.has(key)) staleKeys.push(key);
+        }
+        for (const key of staleKeys) {
+          delete mergedFieldMeta[key];
+        }
+        if (staleKeys.length > 0) {
+          this.logDebug('CRDT D1: pruned stale _field_meta keys', { staleKeys });
+        }
+      }
+
+      // S3: Cap _field_meta size — evict oldest entries beyond the cap.
+      // Runs after D1 semantic prune as a second line of defense.
+      const metaKeys = Object.keys(mergedFieldMeta);
+      if (metaKeys.length > FIELD_META_CAP) {
+        const sorted = metaKeys.sort((a, b) => (mergedFieldMeta[a].ts ?? 0) - (mergedFieldMeta[b].ts ?? 0));
+        const toEvict = sorted.slice(0, metaKeys.length - FIELD_META_CAP);
+        for (const key of toEvict) {
+          delete mergedFieldMeta[key];
+        }
+        this.logDebug('CRDT S3: capped _field_meta', { evicted: toEvict.length, remaining: FIELD_META_CAP });
+      }
+
+      dataWithUserTracking._field_meta = mergedFieldMeta;
+
+      this.logDebug('CRDT LWW merge', {
+        clientFields: Object.keys(options.fieldTimestamps),
+        removedFields: fieldsToRemoveFromUpdate,
+        survivingFields: Object.keys(options.fieldTimestamps).filter(f => !fieldsToRemoveFromUpdate.includes(f)),
+      });
+    }
+
+    // Update operation always updates single entity
+    let document;
+    try {
+      document = await this.mongooseModel.findOneAndUpdate(
+        filter,
+        { $set: dataWithUserTracking, $inc: { _version_db_doc: 1 } },
+        mongooseOpts
+      );
+    } catch (error) {
+      this.logDebug('Mongoose update failed', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        filter,
+        hasTransaction: !!session
+      });
+      throw this.handleMongoDBError(error, executionContext);
+    }
+
+    this.logDebug('Single update completed', {
+      filter,
+      found: !!document,
+      hasTransaction: !!session
+    });
+
+    if (!document) {
+      if (options?.ifMatchVersion !== undefined) {
+        // Disambiguate: version conflict vs resource deleted.
+        // Query by _id only (no version filter, no contextual filter) to check existence.
+        const existsDoc = await this.mongooseModel.findOne(
+          baseFilter,
+          { _id: 1 },
+          session ? { session } : undefined
+        );
+
+        // CRDT-only update retry: when two clients save different CRDT fields simultaneously,
+        // the second client's findOneAndUpdate fails because the first already incremented
+        // the version. Retry with the current version instead of returning 409.
+        const crdtFieldSet = options?.fieldTimestamps ? new Set(Object.keys(options.fieldTimestamps)) : null;
+        const userDataKeys = Object.keys(dataWithUserTracking).filter(
+          k => !k.startsWith('_')
+        );
+        const isCrdtOnly = crdtFieldSet !== null && isCrdtOnlyUpdate(userDataKeys, crdtFieldSet);
+
+        if (existsDoc && options?.fieldTimestamps && isCrdtOnly) {
+          const freshDoc = await this.mongooseModel.findOne(
+            baseFilter,
+            { _field_meta: 1, _version_db_doc: 1 },
+            session ? { session } : undefined,
+          );
+          if (freshDoc) {
+            filter._version_db_doc = freshDoc._version_db_doc;
+
+            const freshFieldMeta: Record<string, FieldMetaEntry> = sanitizeFieldMeta(freshDoc._field_meta);
+            const freshMerged: Record<string, FieldMetaEntry> = { ...freshFieldMeta };
+            for (const [field, clientTs] of Object.entries(options.fieldTimestamps)) {
+              const serverTs = freshFieldMeta[field]?.ts ?? 0;
+              if (lwwFieldWinner(clientTs, serverTs) === CrdtResolutionWinner.INCOMING) {
+                freshMerged[field] = { ts: nextMonotonicTimestamp(Date.now(), serverTs), by: userId! };
+              } else {
+                delete dataWithUserTracking[field];
+              }
+            }
+            // D1: Schema-aware prune on retry path
+            const validCrdtKeysRetry = extractCrdtFieldNames(this.resourceConfiguration.mainSchema, false);
+            if (validCrdtKeysRetry.size > 0) {
+              for (const key of Object.keys(freshMerged)) {
+                if (!validCrdtKeysRetry.has(key)) delete freshMerged[key];
+              }
+            }
+
+            // S3: Cap _field_meta size on retry path
+            const retryMetaKeys = Object.keys(freshMerged);
+            if (retryMetaKeys.length > FIELD_META_CAP) {
+              const sorted = retryMetaKeys.sort((a, b) => (freshMerged[a].ts ?? 0) - (freshMerged[b].ts ?? 0));
+              const toEvict = sorted.slice(0, retryMetaKeys.length - FIELD_META_CAP);
+              for (const key of toEvict) delete freshMerged[key];
+            }
+
+            dataWithUserTracking._field_meta = freshMerged;
+
+            document = await this.mongooseModel.findOneAndUpdate(
+              filter,
+              { $set: dataWithUserTracking, $inc: { _version_db_doc: 1 } },
+              mongooseOpts,
+            );
+            if (document) {
+              this.logDebug('CRDT LWW: retry succeeded after version conflict');
+              return this.transformDocumentToResponse<T>(document, CoreResourceOperation.UPDATE);
+            }
+            // O1: retry was attempted (freshDoc found) but second findOneAndUpdate still lost the race
+            this.logger.warn('CRDT LWW retry exhausted — falling through to VERSION_CONFLICT', {
+              resourceId: String(baseFilter._id),
+              clientFields: options?.fieldTimestamps ? Object.keys(options.fieldTimestamps) : [],
+            });
+          }
+          // If freshDoc was null, fall through to 409 without O1 (could not refresh version / meta)
+        }
+
+        if (existsDoc) {
+          this.logDebug('Version conflict detected', {
+            ifMatchVersion: options.ifMatchVersion,
+            resourceId: baseFilter._id
+          });
+          throw this.errorBuilder.buildError(
+            ErrorType.CONFLICT,
+            executionContext,
+            {
+              customMessageReference: ErrorCustomMessageReference.VERSION_CONFLICT,
+              context: {
+                resourceType: this.resourceConfiguration.resourceIdentifier,
+                ifMatchVersion: options.ifMatchVersion,
+              }
+            }
+          );
+        }
+        // Document truly doesn't exist — fall through to return null
+        // (service layer will throw NOT_FOUND)
+      }
+      return null;
+    }
+
+    return this.transformDocumentToResponse<T>(document, CoreResourceOperation.UPDATE);
+  }
+
+  private async _doUpdateMany<T = undefined>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    ids_or_filter: IdsOrFilterType | undefined,
+    data: PartialMainSchemaType<TMainSchema>,
+    options?: RepositoryOptions
+  ): Promise<ConditionalArrayReturnType<T, TMainSchema>> {
+    const { baseFilter } = this.buildBaseFilterFromIdOrIdsOrFilter(ids_or_filter, executionContext);
+    const session = this.getNativeSession(options);
+    this.logDebug('Updating multiple resources', { ids_or_filter, hasData: !!data, hasTransaction: !!session });
+
+    // Clean input data FIRST (remove mandatory discard fields)
+    const cleanedData = this.resourceOperationHelper.cleanInputData(data, CoreResourceOperation.UPDATE_MANY);
+    this.logDebug('Data cleaned for updateMany', { cleanedKeys: typeof cleanedData === 'object' ? Object.keys(cleanedData) : 'not-object' });
+
+    // Validate against request DTO (after cleaning)
+    const isBulkOperation = 'isBulkOperation' in operation && operation.isBulkOperation === true;
+    const validatedData = this.repositoriesRegistry.validateRepositoryWriteData(
+      cleanedData,
+      this.resourceConfiguration.resourceIdentifier as ResourceType,
+      String(operation.operationIdentifier),
+      isBulkOperation
+    );
+    this.logDebug('Data validated against requestDto', { validatedKeys: typeof validatedData === 'object' ? Object.keys(validatedData) : 'not-object' });
+
+    // THEN apply execution context data enrichment to the validated data
+    const enrichedData = this.resourceOperationHelper.enrichDataWithContext(validatedData, executionContext, this.resourceConfiguration.mainSchema, this.resourceConfiguration.resourceFieldIdentifier, CoreResourceOperation.UPDATE_MANY, options);
+    this.logDebug('Data enriched with context', { enrichedKeys: typeof enrichedData === 'object' ? Object.keys(enrichedData) : 'not-object' });
+
+    // Add user tracking to enriched data
+    const dataWithUserTracking = this.addUserTracking(enrichedData, executionContext, CoreResourceOperation.UPDATE_MANY);
+    this.logDebug('User tracking added', { finalKeys: typeof dataWithUserTracking === 'object' ? Object.keys(dataWithUserTracking) : 'not-object' });
+
+    // Defense-in-depth: strip version fields from update data to prevent
+    // $set/$inc conflict on _version_db_doc in bulk updates too.
+    delete dataWithUserTracking._version_db_doc;
+    delete dataWithUserTracking._version;
+
+    const contextualFilter = this.buildContextualFilter(executionContext, baseFilter, options);
+
+    // Prepare mongoose options with transaction session if provided
+    const mongooseOpts: any = { runValidators: true };
+    if (session) {
+      mongooseOpts.session = session;
+    }
+
+    const findOpts: any = session ? { session } : {};
+    const matchedDocuments = await this.mongooseModel.find(contextualFilter, { _id: 1 }, findOpts);
+    const matchedIds = matchedDocuments
+      .map((doc: any) => doc?._id?.toString?.() ?? doc?._id)
+      .filter((id: unknown): id is string => typeof id === 'string' && id.length > 0);
+
+    if (matchedIds.length === 0) {
+      return [] as ConditionalArrayReturnType<T, TMainSchema>;
+    }
+
+    const updateResult = await this.mongooseModel.updateMany(
+      contextualFilter,
+      { $set: dataWithUserTracking, $inc: { _version_db_doc: 1 } },
+      mongooseOpts
+    );
+
+    this.logDebug('UpdateMany completed', {
+      filter: contextualFilter,
+      matchedCount: updateResult.matchedCount,
+      modifiedCount: updateResult.modifiedCount,
+      hasTransaction: !!session
+    });
+
+    if (updateResult.matchedCount === 0) {
+      return [] as ConditionalArrayReturnType<T, TMainSchema>;
+    }
+
+    // Re-read by stable ids rather than the original filter.
+    // Otherwise a patch that changes a matched filter field can make the follow-up
+    // find() return an empty set even though Mongo actually updated documents.
+    const updatedDocuments = await this.mongooseModel.find(
+      { _id: { $in: matchedIds } } as FilterQuery<any>,
+      null,
+      findOpts
+    );
+    const updatedDocumentsById = new Map(
+      updatedDocuments.map((doc: any) => [
+        doc?._id?.toString?.() ?? doc?._id,
+        doc,
+      ] as const)
+    );
+    const orderedUpdatedDocuments = matchedIds
+      .map((id) => updatedDocumentsById.get(id))
+      .filter((doc): doc is any => !!doc);
+
+    return orderedUpdatedDocuments.map(doc => this.transformDocumentToResponse<T>(doc, CoreResourceOperation.UPDATE_MANY)) as ConditionalArrayReturnType<T, TMainSchema>;
+  }
+
+
+  private async _doDelete(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    id_or_filter?: IdOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<string> {
+    // Prepare mongoose options with transaction session if provided
+    const session = this.getNativeSession(options);
+    const mongooseOpts: any = session ? { session } : {};
+
+    this.logDebug('Deleting resource', { id_or_filter, hasTransaction: !!session });
+
+    // Validate required parameter
+    this.validateIdOrIdsOrFilterRequired(id_or_filter, executionContext, CoreResourceOperation.DELETE);
+
+    // Build base filter - delete operation is always unitary (single entity)
+    const { baseFilter: deleteFilter } = this.buildBaseFilterFromIdOrIdsOrFilter(id_or_filter, executionContext);
+
+    const filter = this.buildContextualFilter(executionContext, deleteFilter, options);
+
+    // First, fetch the document to get its ID before deletion
+    const documentToDelete = await this.mongooseModel.findOne(filter, { _id: 1 }, mongooseOpts);
+
+    if (!documentToDelete) {
+      this.logDebug('No document found to delete', { filter });
+      return '';
+    }
+
+    const deletedId = (documentToDelete as any)._id.toString();
+
+    // Delete operation always deletes single entity
+    const result = await this.mongooseModel.deleteOne(filter, mongooseOpts);
+
+    this.logDebug('Single delete completed', {
+      filter,
+      deletedCount: result.deletedCount,
+      deletedId: deletedId,
+      hasTransaction: !!session
+    });
+
+    return deletedId;
+  }
+
+
+  private async _doDeleteMany(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    ids_or_filter?: IdsOrFilterType,
+    options?: RepositoryOptions
+  ): Promise<string[]> {
+    // Prepare mongoose options with transaction session if provided
+    const session = this.getNativeSession(options);
+    const mongooseOpts: any = session ? { session } : {};
+
+    this.logDebug('Deleting multiple resources', { ids_or_filter, hasTransaction: !!session });
+
+    // Validate required parameter for deleteMany operation
+    this.validateIdOrIdsOrFilterRequired(ids_or_filter, executionContext, CoreResourceOperation.DELETE_MANY);
+
+    // Build base filter for multiple deletions - this handles IdsOrFilterType
+    const { baseFilter } = this.buildBaseFilterFromIdOrIdsOrFilter(ids_or_filter, executionContext);
+
+    // Apply contextual filtering
+    const contextualFilter = this.buildContextualFilter(executionContext, baseFilter, options);
+
+    // First, fetch all documents that match the filter to get their IDs before deletion
+    const documentsToDelete = await this.mongooseModel.find(contextualFilter, { _id: 1 }, mongooseOpts);
+
+    if (!documentsToDelete || documentsToDelete.length === 0) {
+      this.logDebug('No documents found to delete', { contextualFilter });
+      return [];
+    }
+
+    const deletedIds = documentsToDelete.map(doc => (doc as any)._id.toString());
+
+    // Perform multiple deletions using deleteMany
+    const result = await this.mongooseModel.deleteMany(contextualFilter, mongooseOpts);
+
+    this.logDebug('Multiple delete completed', {
+      contextualFilter,
+      deletedCount: result.deletedCount,
+      deletedIds: deletedIds,
+      hasTransaction: !!session
+    });
+
+    return deletedIds;
+  }
+
+  private async _doList<T = undefined>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    ids_or_filter?: IdsOrFilterType,
+    options?: RepositoryOptions & { listOptions?: Partial<Resources_PaginationRequest> }
+  ): Promise<(T extends undefined ? any : T)[] | Resources_PaginatedResult<T extends undefined ? any : T>> {
+
+    // Validate required parameter
+    this.validateIdOrIdsOrFilterRequired(ids_or_filter, executionContext, CoreResourceOperation.LIST);
+
+    // Build base filter
+    const { baseFilter } = this.buildBaseFilterFromIdOrIdsOrFilter(ids_or_filter, executionContext);
+
+    const contextualFilter = this.buildContextualFilter(executionContext, baseFilter, options);
+
+    // Build projection from operation's responseDto
+    const projection = this.buildMongoProjectionFromResponseDto(operation);
+
+    // Check if pagination wrapper is requested
+    const paginated = options?.paginated ?? false;
+    const listOptions = options?.listOptions;
+    const hasPagination = listOptions?.page !== undefined || listOptions?.limit !== undefined;
+
+    // Only count documents if we need pagination metadata
+    let total = 0;
+    let page = 1;
+    let limit = 0;
+    let skip = 0;
+    let totalPages = 1;
+
+    if (paginated || hasPagination) {
+      total = await this.mongooseModel.countDocuments(contextualFilter).exec();
+      page = hasPagination ? Math.max(1, listOptions?.page || 1) : 1;
+      limit = hasPagination ? Math.min(100, Math.max(1, listOptions?.limit || 20)) : total || 1;
+      skip = (page - 1) * limit;
+      totalPages = limit > 0 ? Math.ceil(total / limit) : 1;
+    }
+
+    // Get session for transaction support
+    const session = this.getNativeSession(options);
+
+    this.logDebug('Listing resources', {
+      ids_or_filter,
+      paginated,
+      hasPagination,
+      page,
+      limit,
+      skip,
+      total,
+      hasTransaction: !!session
+    });
+
+    // Prepare query with projection and transaction session
+    let query = this.mongooseModel
+      .find(contextualFilter, projection)
+      .sort({ createdAt: -1 });
+
+    // Apply pagination only if requested
+    if (hasPagination) {
+      query = query.skip(skip).limit(limit);
+    }
+
+    if (session) {
+      query = query.session(session);
+    }
+
+    const documents = await query.exec();
+
+    const data = documents.map(doc => this.transformDocumentToResponse<T>(doc, CoreResourceOperation.LIST)) as (T extends undefined ? any : T)[];
+
+    this.logDebug('List result', {
+      filter: contextualFilter,
+      count: data.length,
+      paginated,
+      pagination: paginated ? { page, limit, total, totalPages } : undefined,
+      sample: this.previewDocument(documents[0]),
+      hasTransaction: !!session
+    });
+
+    // Return raw array by default, or with pagination wrapper if requested
+    if (paginated) {
+      return {
+        data,
+        pagination: { page, limit: limit || data.length, total: total || data.length, totalPages }
+      };
+    }
+
+    return data;
+  }
+
+  private async _doSearch<T = any>(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    searchQuery: string,
+    filter: FilterQuery<any> = {},
+    options: RepositoryOptions & { searchOptions: { fieldsToSearch?: string[]; page?: number; limit?: number; sort?: any} }
+  ): Promise<Resources_PaginatedResult<T>> {
+    // Get session for transaction support
+    const session = this.getNativeSession(options);
+
+    // Find the search operation configuration
+    const searchConfig = this.findSearchOperationConfiguration();
+
+    if (!searchConfig) {
+      const error = this.errorBuilder.buildError(
+        ErrorType.NOT_FOUND,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_SEARCH_NOT_CONFIGURED,
+        }
+      );
+      throw error;
+    }
+
+    const op = searchConfig as unknown as {
+      isSearchable?: boolean;
+      searchableFields?: string[];
+      maxPaginatedResultPerPageLimit?: number;
+    };
+
+    if (!op.isSearchable) {
+      const error = this.errorBuilder.buildError( ErrorType.BUSINESS_RULE, executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_SEARCH_NOT_ENABLED }
+      );
+      throw error;
+    }
+
+    const page = Math.max(1, options.searchOptions.page || 1);
+    const maxLimit = op.maxPaginatedResultPerPageLimit || 50;
+    const limit = Math.min(maxLimit, Math.max(1, options.searchOptions.limit || 20));
+    const skip = (page - 1) * limit;
+
+    this.logDebug('Searching resources with configuration', {
+      searchQuery, filter, page, limit, maxLimit,
+      searchableFields: op.searchableFields,
+      isSearchable: op.isSearchable,
+      hasTransaction: !!session
+    });
+
+    // Build advanced search filter using configuration
+    const searchFilter = this.constructSearchQuery(searchQuery, searchConfig);
+    const validatedFilter = this.sanitizeRequestFilter(filter, searchConfig);
+    const combinedFilter = { ...validatedFilter, ...searchFilter };
+    const contextualFilter = this.buildContextualFilter(executionContext, combinedFilter, options);
+
+    // Build sort options using configuration
+    const sortOptions = this.constructValidatedSortOptions(options.searchOptions.sort, searchConfig);
+
+    // Build projection from operation's responseDto
+    const projection = this.buildMongoProjectionFromResponseDto(operation);
+
+    // Prepare mongoose queries with projection and transaction session if provided
+    let findQuery = this.mongooseModel
+      .find(contextualFilter, projection)
+      .sort(sortOptions)
+      .skip(skip)
+      .limit(limit);
+
+    let countQuery = this.mongooseModel.countDocuments(contextualFilter);
+
+    if (session) {
+      findQuery = findQuery.session(session);
+      countQuery = countQuery.session(session);
+    }
+
+    const [documents, total] = await Promise.all([
+      findQuery.exec(),
+      countQuery.exec()
+    ]);
+
+    const data = documents.map(doc => this.transformDocumentToResponse(doc, CoreResourceOperation.SEARCH));
+
+    return {
+      data,
+      pagination: { page, limit, total, totalPages: Math.ceil(total / limit) }
+    };
+  }
+
+  private async _doCount(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+    filter: FilterQuery<any> = {},
+    options?: RepositoryOptions
+  ): Promise<{ count: number }> {
+    const session = this.getNativeSession(options);
+    this.logDebug('Counting resources', { filter, hasTransaction: !!session });
+
+    const contextualFilter = this.buildContextualFilter(executionContext, filter, options);
+
+    // Prepare count query with transaction session if provided
+    let countQuery = this.mongooseModel.countDocuments(contextualFilter);
+
+    if (session) {
+      countQuery = countQuery.session(session);
+    }
+
+    const count = await countQuery.exec();
+
+    this.logDebug('Count result', {
+      filter: contextualFilter,
+      count,
+      hasTransaction: !!session
+    });
+
+    return { count };
+  }
+
+  // ================================
+  // Helper Methods
+  // ================================
+
+  /**
+   * Format a string ID for MongoDB queries.
+   * Uses ResourceIdBackendService if available, falls back to direct ObjectId creation.
+   *
+   * @param id - The string ID to format
+   * @returns The formatted ID (Types.ObjectId for MongoDB)
+   */
+  private formatIdForQuery(id: string): Types.ObjectId {
+    if (this.resourceIdService) {
+      return this.resourceIdService.formatForQuery(id) as Types.ObjectId;
+    }
+    // Fallback for backward compatibility when service not available
+    return new Types.ObjectId(id);
+  }
+
+  /**
+   * Utility function to build a base filter from IdOrIdsOrFilterType
+   * @param id_or_ids_or_filter - The input parameter to process
+   * @param executionContext - Execution context for error handling
+   * @returns Object containing the base filter and whether it represents multiple items
+   */
+  private buildBaseFilterFromIdOrIdsOrFilter(
+    id_or_ids_or_filter: IdOrIdsOrFilterType,
+    executionContext: ExecutionContext<any>
+  ): { baseFilter: FilterQuery<any>; isMultiple: boolean } {
+    let baseFilter: FilterQuery<any> = {};
+    let isMultiple = false;
+
+    if (!id_or_ids_or_filter) {
+      return { baseFilter, isMultiple };
+    }
+
+    if (typeof id_or_ids_or_filter === 'string') {
+      // Single ID
+      baseFilter = { _id: this.formatIdForQuery(id_or_ids_or_filter) } as FilterQuery<any>;
+      isMultiple = false;
+    } else if (Array.isArray(id_or_ids_or_filter)) {
+      // Multiple IDs
+      if (id_or_ids_or_filter.length > 0) {
+        const objectIds = id_or_ids_or_filter.map(singleId => this.formatIdForQuery(singleId));
+        baseFilter = { _id: { $in: objectIds } } as FilterQuery<any>;
+      }
+      isMultiple = true;
+    } else if (typeof id_or_ids_or_filter === 'object' && !Array.isArray(id_or_ids_or_filter)) {
+      // Handle different object types
+      if ('id_or_ids' in id_or_ids_or_filter) {
+        // Combined object with id_or_ids and optional filter
+        const { id_or_ids: ids, filter } = id_or_ids_or_filter;
+        if (typeof ids === 'string') {
+          baseFilter = { _id: this.formatIdForQuery(ids) } as FilterQuery<any>;
+          isMultiple = false;
+        } else if (Array.isArray(ids) && ids.length > 0) {
+          const objectIds = ids.map(singleId => this.formatIdForQuery(singleId));
+          baseFilter = { _id: { $in: objectIds } } as FilterQuery<any>;
+          isMultiple = true;
+        }
+        // Merge additional filter if present
+        if (filter && Object.keys(filter).length > 0) {
+          baseFilter = { ...baseFilter, ...filter };
+          isMultiple = true; // Combined filters usually imply multiple results
+        }
+      } else {
+        // Direct FilterQuery object
+        baseFilter = id_or_ids_or_filter as FilterQuery<any>;
+        isMultiple = true; // Filter queries usually imply multiple results
+      }
+    } else {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { message: 'Invalid id_or_ids_or_filter format' } }
+      );
+    }
+
+    return { baseFilter, isMultiple };
+  }
+
+  private canReadViaContextWithoutExplicitId(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>,
+    executionContext: ExecutionContext<any>,
+  ): boolean {
+    const contextResourceIds = executionContext.getContextResourceIds();
+    if (contextResourceIds.size === 0) {
+      return false;
+    }
+
+    const initiatorInfos = 'initiatorInfos' in operation ? operation.initiatorInfos : undefined;
+    if (!initiatorInfos || initiatorInfos.length === 0) {
+      return false;
+    }
+
+    return initiatorInfos.some((initiatorInfo) => {
+      const parameters = initiatorInfo.parameters ?? [];
+      return (
+        parameters.length > 0
+        && !parameters.some((parameter) => parameter.fieldIdentifier === operation.resourceFieldIdentifier)
+        && parameters.every((parameter) => contextResourceIds.has(parameter.fieldIdentifier))
+      );
+    });
+  }
+
+  /**
+   * Utility function to validate that id_or_ids_or_filter parameter is provided
+   * @param id_or_ids_or_filter - The parameter to validate
+   * @param executionContext - Execution context for error handling
+   * @param operationName - Name of the operation for error messages
+   */
+  private validateIdOrIdsOrFilterRequired(
+    id_or_ids_or_filter: IdOrIdsOrFilterType,
+    executionContext: ExecutionContext<any>,
+    operationName: string,
+    allowContextOnlyRead: boolean = false,
+  ): void {
+    if (!id_or_ids_or_filter) {
+      if (operationName === CoreResourceOperation.READ && allowContextOnlyRead) {
+        return;
+      }
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        { customMessageReference: ErrorCustomMessageReference.REPOSITORY_RESOURCE_OPERATION_FAILED, context: { message: `${operationName} requires id_or_ids_or_filter parameter` } }
+      );
+    }
+  }
+
+
+
+  /**
+   * Escapes special regex characters in search query to prevent regex injection
+   * @param text - The text to escape
+   * @returns Escaped text safe for regex
+   */
+  private escapeRegex(text: string): string {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+
+
+  /**
+   * Extract projection fields from operation's responseDto for MongoDB field selection
+   * @param operation - The operation to extract responseDto fields from
+   * @returns MongoDB projection object or null if no responseDto is defined
+   */
+  private buildMongoProjectionFromResponseDto(
+    operation: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): Record<string, 1> | null {
+    // Prefer repositoryDto over responseDto
+    // repositoryDto excludes virtual fields and populated placeholders,
+    // but includes virtual field dependencies
+    const dtoToUse = operation.repositoryDto ?? operation.responseDto;
+
+    if (!dtoToUse) {
+      this.logDebug('No responseDto/repositoryDto found in operation, using full document projection');
+      return null;
+    }
+
+    try {
+      // Parse the DTO to extract field names
+      const responseSchema = dtoToUse;
+
+      // For Zod schemas, we can use the shape property to get field names
+      if (responseSchema && typeof responseSchema === 'object' && 'shape' in responseSchema) {
+        const shape = (responseSchema as any).shape;
+        const projection: Record<string, 1> = {};
+
+        Object.keys(shape).forEach(fieldName => {
+          projection[fieldName] = 1;
+        });
+
+        this.logDebug('Built projection from responseDto', {
+          operationIdentifier: operation.operationIdentifier,
+          projectionFields: Object.keys(projection)
+        });
+
+        return projection;
+      }
+
+      // If we can't extract fields from the schema, fall back to full document
+      this.logDebug('Unable to extract fields from responseDto, using full document projection', {
+        operationIdentifier: operation.operationIdentifier,
+        responseDtoType: typeof responseSchema
+      });
+
+      return null;
+    } catch (error) {
+      this.logDebug('Error extracting projection from responseDto, using full document', {
+        operationIdentifier: operation.operationIdentifier,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+
+      return null;
+    }
+  }
+
+  /**
+   * Build contextual filter based on execution context with schema validation and blacklist support
+   * @param executionContext - The execution context containing resource IDs
+   * @param baseFilter - The base filter to enhance with context
+   * @param options - Repository options containing exclusion rules
+   * @returns Enhanced filter with context information
+   */
+  private buildContextualFilter(executionContext: ExecutionContext<any>, baseFilter: FilterQuery<any>, options?: RepositoryOptions): FilterQuery<any> {
+    const contextualFilter = { ...baseFilter };
+
+    // Check if contextual filtering should be excluded
+    if (options?.excludeContextualFilter === true) {
+      // Skip all contextual filtering if explicitly disabled
+      this.logDebug('Contextual filtering disabled, returning base filter only');
+      return contextualFilter;
+    }
+
+    // Determine blacklisted fields
+    const blacklistedFields = new Set<string>();
+
+    // Always exclude the resource's own resourceFieldIdentifier to avoid self-reference in filtering
+    blacklistedFields.add(this.resourceConfiguration.resourceFieldIdentifier);
+
+    // Add custom blacklisted fields if provided
+    if (Array.isArray(options?.excludeContextualFilter)) {
+      options.excludeContextualFilter.forEach(field => blacklistedFields.add(field));
+    }
+
+    // Add context resource filters (with nested path support, schema validation and blacklist filtering)
+    const contextResourceIds = executionContext.getContextResourceIds();
+    contextResourceIds.forEach((resourceId, fieldIdentifier) => {
+      // Skip if field is blacklisted
+      if (blacklistedFields.has(fieldIdentifier)) {
+        this.logDebug('Skipping blacklisted field in contextual filter', { fieldIdentifier });
+        return;
+      }
+
+      // Find all schema paths that end with this field identifier (including nested paths)
+      const matchingPaths = this.resourceOperationHelper.findRequiredNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema,
+        fieldIdentifier,
+        executionContext,
+        {
+          reason: 'context_filter',
+          resourceIdentifier: this.resourceConfiguration.resourceIdentifier,
+          message: `Execution context field '${fieldIdentifier}' is missing from schema for resource '${this.resourceConfiguration.resourceIdentifier}' during contextual filtering`,
+        }
+      );
+
+      // Process each matching path
+      matchingPaths.forEach(fullPath => {
+        // Only add if not already present in filter (check nested path)
+        if (!this.resourceOperationHelper.hasNestedPath(contextualFilter, fullPath)) {
+          this.resourceOperationHelper.setNestedValue(contextualFilter, fullPath, resourceId);
+          this.logDebug('Added contextual filter to nested path', { fieldIdentifier, fullPath, resourceId });
+        } else {
+          this.logDebug('Skipping contextual filter - already present in filter', { fieldIdentifier, fullPath });
+        }
+      });
+    });
+
+    // Defense-in-depth: enforce userId = null for ANONYMOUS scope on isAnonymizable resources.
+    // Prevents any anonymous query from seeing authenticated users' data even if scoping is bypassed.
+    if (executionContext.isAnonymousExecution() && this.resourceConfiguration.isAnonymizable) {
+      const userPaths = this.resourceOperationHelper.findNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema, 'userId'
+      );
+      userPaths.forEach(fullPath => {
+        this.resourceOperationHelper.setNestedValue(contextualFilter, fullPath, null);
+      });
+    }
+
+    // Apply FK relationship filters from relationship contexts
+    // This handles cases like /assigned-to-users/{userId}/todos where we need to filter by assignedToUserId
+    this.applyFKRelationshipFilters(executionContext, contextualFilter, blacklistedFields);
+
+    return contextualFilter;
+  }
+
+  /**
+   * Apply FK relationship filters from ExecutionContext.relationshipContexts
+   *
+   * When a resource is accessed via a FK relationship path (e.g., /assigned-to-users/{userId}/todos),
+   * this method adds the appropriate filter to ensure only resources matching the FK field are returned.
+   *
+   * For example:
+   * - URL: /assigned-to-users/{userId}/todos
+   * - relationshipContext: { resourceType: 'USERS', relationshipField: 'assignedToUserId', resourceId: '123' }
+   * - Filter added: { assignedToUserId: '123' }
+   */
+  private applyFKRelationshipFilters(
+    executionContext: ExecutionContext<any>,
+    filter: FilterQuery<any>,
+    blacklistedFields: Set<string>
+  ): void {
+    const relationshipContexts = executionContext.relationshipContexts;
+
+    if (!relationshipContexts || relationshipContexts.length === 0) {
+      return;
+    }
+
+    for (const relationshipContext of relationshipContexts) {
+      const { relationshipField, resourceId } = relationshipContext;
+
+      // Only apply for FK relationships (those with a relationshipField defined)
+      // Standard parent relationships are handled by the contextResourceIds loop above
+      if (!relationshipField) {
+        continue;
+      }
+
+      // Skip if field is blacklisted
+      if (blacklistedFields.has(relationshipField)) {
+        this.logDebug('Skipping blacklisted FK relationship field in filter', { relationshipField });
+        continue;
+      }
+
+      // Find all schema paths that match this FK field
+      const matchingPaths = this.resourceOperationHelper.findRequiredNestedFieldPathsFromZodSchema(
+        this.resourceConfiguration.mainSchema,
+        relationshipField,
+        executionContext,
+        {
+          reason: 'fk_filter',
+          resourceIdentifier: this.resourceConfiguration.resourceIdentifier,
+          message: `Relationship field '${relationshipField}' is missing from schema for resource '${this.resourceConfiguration.resourceIdentifier}' during FK-path filtering`,
+        }
+      );
+
+      // Apply filter for each matching path
+      matchingPaths.forEach(fullPath => {
+        if (!this.resourceOperationHelper.hasNestedPath(filter, fullPath)) {
+          this.resourceOperationHelper.setNestedValue(filter, fullPath, resourceId);
+          this.logDebug('Added FK relationship filter', { relationshipField, fullPath, resourceId });
+        } else {
+          this.logDebug('Skipping FK relationship filter - already present', { relationshipField, fullPath });
+        }
+      });
+    }
+  }
+
+
+
+  /**
+   * Check if a field exists in the mongoose model schema
+   */
+  private hasSchemaField(fieldName: string): boolean {
+    if (!this.mongooseModel?.schema?.paths) {
+      return false;
+    }
+
+    return this.mongooseModel.schema.paths[fieldName] !== undefined;
+  }
+
+  /**
+   * Handle MongoDB errors and convert them to application-specific errors.
+   * Specifically handles unique constraint violations (E11000 duplicate key error).
+   *
+   * @param error - The error caught from MongoDB operation
+   * @param executionContext - The execution context for error building
+   * @returns The original error or a transformed application error
+   */
+  private handleMongoDBError(error: unknown, executionContext?: ExecutionContext<any>): Error | WildoError_Backend {
+    // Check for MongoDB duplicate key error (E11000)
+    const isMongoError = error && typeof error === 'object' && 'code' in error;
+
+    if (isMongoError && (error as any).code === 11000) {
+      // Extract field name from the error message
+      // MongoDB error message format: "E11000 duplicate key error collection: db.collection index: fieldName_1 dup key: { fieldName: "value" }"
+      const errorMessage = (error as any).message || '';
+      const keyValueMatch = errorMessage.match(/dup key: \{ ([^:]+):/);
+      const fieldName = keyValueMatch ? keyValueMatch[1].trim() : 'unknown';
+
+      // Extract the duplicate value if present
+      const valueMatch = errorMessage.match(/dup key: \{ [^:]+: "([^"]+)" \}/);
+      const duplicateValue = valueMatch ? valueMatch[1] : undefined;
+
+      return this.errorBuilder.buildError(
+        ErrorType.CONFLICT,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.UNIQUE_CONSTRAINT_VIOLATION,
+          context: {
+            resourceType: this.resourceConfiguration.resourceIdentifier,
+            fieldName,
+            duplicateValue,
+            originalError: errorMessage
+          }
+        }
+      );
+    }
+
+    // Return the original error if not a unique constraint violation
+    return error instanceof Error ? error : new Error(String(error));
+  }
+
+
+  /**
+   * Add user tracking to enriched data (timestamps are handled automatically by MongoDB)
+   * @param enrichedData - The data to add user tracking to
+   * @param executionContext - The execution context containing user info
+   * @param operation - The operation being performed
+   * @returns Data with user tracking added
+   */
+  private addUserTracking(enrichedData: any, executionContext: ExecutionContext<any>, operation?: CoreResourceOperation): any {
+    // Note: createdAt and updatedAt timestamps are handled automatically by MongoDB, so we don't add them here
+
+    // Add operation-specific user tracking if userId is available in execution context
+    const userId = executionContext.initiatorIds?.userId;
+    if (userId) {
+
+      // For CREATE operations: populate createdByUserId if field exists in database schema
+      if (operation === CoreResourceOperation.CREATE || operation === CoreResourceOperation.CREATE_MANY) {
+        if (this.hasSchemaField('createdByUserId') && !enrichedData.createdByUserId) {
+          enrichedData.createdByUserId = userId;
+        }
+      }
+
+      // For UPDATE operations: populate updatedByUserId or lastUpdatedByUserId if field exists in database schema
+      if (operation === CoreResourceOperation.UPDATE || operation === CoreResourceOperation.UPDATE_MANY) {
+        // Try updatedByUserId first, then lastUpdatedByUserId as fallback
+        if (this.hasSchemaField('updatedByUserId') && !enrichedData.updatedByUserId) {
+          enrichedData.updatedByUserId = userId;
+        } else if (this.hasSchemaField('lastUpdatedByUserId') && !enrichedData.lastUpdatedByUserId) {
+          enrichedData.lastUpdatedByUserId = userId;
+        }
+      }
+    }
+
+    return enrichedData;
+  }
+
+  /**
+   * Transform mongoose document to response format using operation DTO
+   */
+  private transformDocumentToResponse<T = undefined>(document: any, operationIdentifier: string): T extends undefined ? any : T {
+    if (!document) {
+      return null;
+    }
+
+    // Convert mongoose document to plain object with error handling
+    let plainObject: any;
+    try {
+      plainObject = document.toObject ? document.toObject() : document;
+    } catch (error) {
+      this.logDebug('Document toObject() failed, using document as-is', {
+        operationIdentifier,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+      plainObject = document;
+    }
+
+    // Map _version_db_doc to _version for API responses, then remove internal field name
+    if (plainObject && typeof plainObject === 'object') {
+      if (plainObject._version_db_doc !== undefined) {
+        plainObject._version = plainObject._version_db_doc;
+      }
+      delete plainObject._version_db_doc;
+    }
+
+    // Transforming to response DTO is the role of  the service layer
+      return plainObject;
+
+  }
+
+  private previewDocument(document: any): any {
+    if (!document) return null;
+    const obj = document.toObject ? document.toObject() : document;
+    // Limit preview size and hide potentially large fields
+    const clone: any = { ...obj };
+    Object.keys(clone).forEach((k) => {
+      const v = clone[k];
+      if (v && typeof v === 'object') {
+        if (Array.isArray(v)) {
+          clone[k] = `[Array(${v.length})]`;
+        } else {
+          clone[k] = '[Object]';
+        }
+      }
+    });
+    return clone;
+  }
+  // ================================
+  // Search Configuration Methods
+  // ================================
+
+  /**
+   * Retrieves the search operation configuration for this resource.
+   * Uses structural narrowing — SEARCH operations are API_CALL operations
+   * with collection-view fields (filterFields, sortFields, etc.) flattened by the factory.
+   */
+  private findSearchOperationConfiguration(): ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | null {
+    return Array.from(this.operationsMap.values()).find(
+      operation => operation.operationIdentifier === CoreResourceOperation.SEARCH
+    ) ?? null;
+  }
+
+  /**
+   * Constructs MongoDB search filter based on query string and searchable field configuration
+   * @param searchQuery - The search query string
+   * @param searchConfig - The search operation configuration
+   * @returns MongoDB filter query for search
+   */
+  private constructSearchQuery(
+    searchQuery: string,
+    searchConfig: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): FilterQuery<any> {
+    if (!searchQuery?.trim()) {
+      return {};
+    }
+
+    const op = searchConfig as unknown as { searchableFields?: string[]; searchableOptions?: CollectionView_SearchOptions };
+    const searchableFields = op.searchableFields;
+    const searchableOptions = op.searchableOptions;
+
+    if (!searchableFields?.length) {
+      return { $text: { $search: searchQuery } };
+    }
+
+    const searchConditions = this.buildFieldSearchConditions(
+      searchQuery,
+      searchableFields,
+      searchableOptions
+    );
+
+    return searchConditions.length > 1
+      ? { $or: searchConditions }
+      : searchConditions[0] || {};
+  }
+
+  /**
+   * Builds individual field search conditions based on searchable options
+   * @param searchQuery - The search query string
+   * @param searchableFields - Array of fields that can be searched
+   * @param searchableOptions - Search behavior options
+   * @returns Array of MongoDB field conditions
+   */
+  private buildFieldSearchConditions(
+    searchQuery: string,
+    searchableFields: string[],
+    searchableOptions?: CollectionView_SearchOptions
+  ): FilterQuery<any>[] {
+    const caseSensitive = searchableOptions?.caseSensitive || false;
+    const fullMatchOnly = searchableOptions?.fullMatchOnly || false;
+
+    return searchableFields.map((field: string) => {
+      if (fullMatchOnly) {
+        return caseSensitive
+          ? { [field]: searchQuery }
+          : { [field]: { $regex: `^${this.escapeRegex(searchQuery)}$`, $options: 'i' } };
+      } else {
+        return caseSensitive
+          ? { [field]: { $regex: this.escapeRegex(searchQuery) } }
+          : { [field]: { $regex: this.escapeRegex(searchQuery), $options: 'i' } };
+      }
+    });
+  }
+
+  /**
+   * Validates and filters the provided filter object against allowed filter fields configuration
+   * @param requestedFilter - The filter object from the request
+   * @param searchConfig - The search operation configuration
+   * @returns Validated and sanitized filter object
+   */
+  private sanitizeRequestFilter(
+    requestedFilter: FilterQuery<any>,
+    searchConfig: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): FilterQuery<any> {
+    if (!requestedFilter || Object.keys(requestedFilter).length === 0) {
+      return {};
+    }
+
+    const { filterFields } = searchConfig as unknown as { filterFields?: Record<string, unknown> };
+
+    // If no filter fields configured, return filter as-is (fallback behavior)
+    if (!filterFields || Object.keys(filterFields).length === 0) {
+      return requestedFilter;
+    }
+
+    // Only include fields that are explicitly allowed in the configuration
+    const sanitizedFilter: FilterQuery<any> = {};
+
+    Object.entries(requestedFilter).forEach(([fieldName, fieldValue]) => {
+      if (filterFields[fieldName]) {
+        sanitizedFilter[fieldName] = fieldValue;
+      }
+      // Note: Invalid fields are silently ignored for security
+    });
+
+    return sanitizedFilter;
+  }
+
+  /**
+   * Constructs validated sort options based on allowed sort fields configuration
+   * @param requestedSort - The sort object from the request
+   * @param searchConfig - The search operation configuration
+   * @returns Validated MongoDB sort object
+   */
+  private constructValidatedSortOptions(
+    requestedSort: Record<string, 1 | -1> | undefined,
+    searchConfig: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>
+  ): Record<string, 1 | -1> {
+    const { sortFields } = searchConfig as unknown as { sortFields?: readonly string[] };
+    const defaultSort: Record<string, 1 | -1> = { createdAt: -1 };
+
+    // If no sort fields configured, use requested sort or default
+    if (!sortFields?.length) {
+      return requestedSort || defaultSort;
+    }
+
+    // If no sort requested, use first configured sort field
+    if (!requestedSort) {
+      const firstSortField = sortFields[0];
+      return { [firstSortField]: -1 };
+    }
+
+    // Validate requested sort fields against configuration
+    const validatedSort: Record<string, 1 | -1> = {};
+
+    Object.entries(requestedSort).forEach(([fieldName, sortDirection]) => {
+      if (sortFields.includes(fieldName) && (sortDirection === 1 || sortDirection === -1)) {
+        validatedSort[fieldName] = sortDirection;
+      }
+    });
+
+    // Return validated sort or fallback to default
+    return Object.keys(validatedSort).length > 0 ? validatedSort : defaultSort;
+  }
+
+
+
+}