@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/base-classes/services/repositories/repository-resource.backend.service.js

@@ -0,0 +1,1509 @@
+import 'reflect-metadata';
+import { CoreResourceOperation, ErrorCustomMessageReference, ErrorType, ResourceOperationsUtils, ResourcesConfig_OperationPathUtils } from '@wildo-ai/saas-models';
+import { lwwFieldWinner, CrdtResolutionWinner, nextMonotonicTimestamp, isCrdtOnlyUpdate, sanitizeFieldMeta, extractCrdtFieldNames, } from '@wildo-ai/saas-models';
+import { Types } from 'mongoose';
+const DEBUG_ACTIVATED = false;
+/**
+ * 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 {
+    zodToMongooseConverter;
+    logger;
+    errorBuilder;
+    resourceRegistry;
+    resourceOperationHelper;
+    repositoriesRegistry;
+    connection;
+    resourceIdService;
+    resourceConfiguration;
+    mongooseModel;
+    inheritanceModels;
+    operationsMap;
+    logDebug;
+    constructor(resourceType, zodToMongooseConverter, logger, errorBuilder, resourceRegistry, resourceOperationHelper, repositoriesRegistry, connection = undefined, resourceIdService) {
+        this.zodToMongooseConverter = zodToMongooseConverter;
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.resourceRegistry = resourceRegistry;
+        this.resourceOperationHelper = resourceOperationHelper;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.connection = connection;
+        this.resourceIdService = resourceIdService;
+        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
+     */
+    getNativeSession(options) {
+        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;
+    }
+    // ================================
+    // Initialization
+    // ================================
+    static createInstance(resourceType, zodToMongooseConverter, logger, errorBuilder, resourceRegistry, resourceOperationHelper, repositoriesRegistry, connection = undefined, resourceIdService) {
+        return new RepositoryResourceBackendService(resourceType, zodToMongooseConverter, logger, errorBuilder, resourceRegistry, resourceOperationHelper, repositoriesRegistry, connection, resourceIdService);
+    }
+    initializeOperationsMap() {
+        if (!this.resourceConfiguration.operations) {
+            return;
+        }
+        this.resourceConfiguration.operations.forEach(operation => {
+            const operationKey = ResourcesConfig_OperationPathUtils.createOperationRepositoryPathKeyFromOperation(operation);
+            this.operationsMap.set(operationKey, operation);
+        });
+        this.logDebug('Operations map initialized', {
+            operationsCount: this.operationsMap.size,
+            operationKeys: Array.from(this.operationsMap.keys())
+        });
+    }
+    initializeMongooseModel() {
+        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();
+            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.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) {
+                    // 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.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
+    // ================================
+    getInheritanceModel(discriminatorValue) {
+        return this.inheritanceModels.get(discriminatorValue);
+    }
+    // ================================
+    // Execution
+    // ================================
+    async doByPath(operationRepositoryPath, executionContext, id_or_ids_or_filter, data, options) {
+        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)
+     */
+    async doByKey(operationRepositoryPathKey, executionContext, id_or_ids_or_filter, data, options) {
+        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);
+    }
+    async doByExecutionContext(executionContext, data, options) {
+        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);
+    }
+    async _prefixOperation(operation, executionContext, id_or_ids_or_filter, data, options) {
+        // 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.
+    }
+    async _postfixOperation(operation, executionContext, id_or_ids_or_filter, data, options) {
+        // 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
+    */
+    async doOperation(operation, executionContext, id_or_ids_or_filter, data, options) {
+        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;
+        // 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, 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, data, options);
+                break;
+            case CoreResourceOperation.UPDATE_MANY:
+                operationResult = await this._doUpdateMany(operation, executionContext, id_or_ids_or_filter, 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, 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, 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, options);
+                operationResult = listResult;
+                break;
+            case CoreResourceOperation.COUNT:
+                operationResult = await this._doCount(operation, executionContext, data?.filter ?? {}, options);
+                break;
+            case CoreResourceOperation.SEARCH:
+                operationResult = await this._doSearch(operation, executionContext, data?.query || '', data?.filter ?? {}, {
+                    ...options,
+                    searchOptions: options?.searchOptions ?? {},
+                });
+                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
+    // ================================
+    async create(executionContext, data, options) {
+        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;
+    }
+    async createMany(executionContext, data, options) {
+        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;
+    }
+    async read(executionContext, id_or_filter, options) {
+        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;
+    }
+    async update(executionContext, id_or_filter, data, options) {
+        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;
+    }
+    async updateMany(executionContext, data, options) {
+        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;
+    }
+    async delete(executionContext, id_or_ids_or_filter, options) {
+        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;
+    }
+    async deleteMany(executionContext, ids_or_filter, options) {
+        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;
+    }
+    async list(executionContext, ids_or_filter, options) {
+        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;
+    }
+    async search(executionContext, searchQuery, filter = {}, searchOptions = {}, options) {
+        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;
+    }
+    supportsOperation(operationIdentifier) {
+        return this.resourceConfiguration.operations.some(op => op.operationIdentifier === operationIdentifier && op.isDefault);
+    }
+    async count(executionContext, filter = {}, options) {
+        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)
+     */
+    async aggregateField(executionContext, filter, field, operation) {
+        const contextualFilter = this.buildContextualFilter(executionContext, filter);
+        // Map operation string to MongoDB aggregation operator
+        let mongoOp;
+        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
+    // ================================
+    async _doCreate(operation, executionContext, data, options) {
+        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, 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 = 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?.name });
+            this.logDebug('hasSlug:', { hasSlug: !!dataWithUserTracking?.slug });
+            this.logDebug('nameValue:', dataWithUserTracking?.name);
+            this.logDebug('slugValue:', { slugValue: dataWithUserTracking?.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);
+        }
+    }
+    async _doCreateMany(operation, executionContext, dataArray, options) {
+        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, 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 = 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);
+        return documents.map(doc => this.transformDocumentToResponse(doc, CoreResourceOperation.CREATE_MANY));
+    }
+    async _doRead(operation, executionContext, id_or_filter, options) {
+        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 = 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(document, CoreResourceOperation.READ);
+    }
+    async _doUpdate(operation, executionContext, id_or_filter, data, options) {
+        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, 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 = { 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 = sanitizeFieldMeta(currentDoc?._field_meta);
+            const mergedFieldMeta = { ...currentFieldMeta };
+            const fieldsToRemoveFromUpdate = [];
+            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 = [];
+                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 = sanitizeFieldMeta(freshDoc._field_meta);
+                        const freshMerged = { ...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(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(document, CoreResourceOperation.UPDATE);
+    }
+    async _doUpdateMany(operation, executionContext, ids_or_filter, data, options) {
+        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, 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 = { runValidators: true };
+        if (session) {
+            mongooseOpts.session = session;
+        }
+        const findOpts = session ? { session } : {};
+        const matchedDocuments = await this.mongooseModel.find(contextualFilter, { _id: 1 }, findOpts);
+        const matchedIds = matchedDocuments
+            .map((doc) => doc?._id?.toString?.() ?? doc?._id)
+            .filter((id) => typeof id === 'string' && id.length > 0);
+        if (matchedIds.length === 0) {
+            return [];
+        }
+        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 [];
+        }
+        // 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 } }, null, findOpts);
+        const updatedDocumentsById = new Map(updatedDocuments.map((doc) => [
+            doc?._id?.toString?.() ?? doc?._id,
+            doc,
+        ]));
+        const orderedUpdatedDocuments = matchedIds
+            .map((id) => updatedDocumentsById.get(id))
+            .filter((doc) => !!doc);
+        return orderedUpdatedDocuments.map(doc => this.transformDocumentToResponse(doc, CoreResourceOperation.UPDATE_MANY));
+    }
+    async _doDelete(operation, executionContext, id_or_filter, options) {
+        // Prepare mongoose options with transaction session if provided
+        const session = this.getNativeSession(options);
+        const mongooseOpts = 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._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;
+    }
+    async _doDeleteMany(operation, executionContext, ids_or_filter, options) {
+        // Prepare mongoose options with transaction session if provided
+        const session = this.getNativeSession(options);
+        const mongooseOpts = 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._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;
+    }
+    async _doList(operation, executionContext, ids_or_filter, options) {
+        // 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(doc, CoreResourceOperation.LIST));
+        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;
+    }
+    async _doSearch(operation, executionContext, searchQuery, filter = {}, options) {
+        // 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;
+        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) }
+        };
+    }
+    async _doCount(operation, executionContext, filter = {}, options) {
+        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)
+     */
+    formatIdForQuery(id) {
+        if (this.resourceIdService) {
+            return this.resourceIdService.formatForQuery(id);
+        }
+        // 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
+     */
+    buildBaseFilterFromIdOrIdsOrFilter(id_or_ids_or_filter, executionContext) {
+        let baseFilter = {};
+        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) };
+            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 } };
+            }
+            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) };
+                    isMultiple = false;
+                }
+                else if (Array.isArray(ids) && ids.length > 0) {
+                    const objectIds = ids.map(singleId => this.formatIdForQuery(singleId));
+                    baseFilter = { _id: { $in: objectIds } };
+                    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;
+                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 };
+    }
+    canReadViaContextWithoutExplicitId(operation, executionContext) {
+        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
+     */
+    validateIdOrIdsOrFilterRequired(id_or_ids_or_filter, executionContext, operationName, allowContextOnlyRead = false) {
+        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
+     */
+    escapeRegex(text) {
+        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
+     */
+    buildMongoProjectionFromResponseDto(operation) {
+        // 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.shape;
+                const projection = {};
+                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
+     */
+    buildContextualFilter(executionContext, baseFilter, options) {
+        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();
+        // 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' }
+     */
+    applyFKRelationshipFilters(executionContext, filter, blacklistedFields) {
+        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
+     */
+    hasSchemaField(fieldName) {
+        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
+     */
+    handleMongoDBError(error, executionContext) {
+        // Check for MongoDB duplicate key error (E11000)
+        const isMongoError = error && typeof error === 'object' && 'code' in error;
+        if (isMongoError && error.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.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
+     */
+    addUserTracking(enrichedData, executionContext, operation) {
+        // 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
+     */
+    transformDocumentToResponse(document, operationIdentifier) {
+        if (!document) {
+            return null;
+        }
+        // Convert mongoose document to plain object with error handling
+        let plainObject;
+        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;
+    }
+    previewDocument(document) {
+        if (!document)
+            return null;
+        const obj = document.toObject ? document.toObject() : document;
+        // Limit preview size and hide potentially large fields
+        const clone = { ...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.
+     */
+    findSearchOperationConfiguration() {
+        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
+     */
+    constructSearchQuery(searchQuery, searchConfig) {
+        if (!searchQuery?.trim()) {
+            return {};
+        }
+        const op = searchConfig;
+        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
+     */
+    buildFieldSearchConditions(searchQuery, searchableFields, searchableOptions) {
+        const caseSensitive = searchableOptions?.caseSensitive || false;
+        const fullMatchOnly = searchableOptions?.fullMatchOnly || false;
+        return searchableFields.map((field) => {
+            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
+     */
+    sanitizeRequestFilter(requestedFilter, searchConfig) {
+        if (!requestedFilter || Object.keys(requestedFilter).length === 0) {
+            return {};
+        }
+        const { filterFields } = searchConfig;
+        // 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 = {};
+        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
+     */
+    constructValidatedSortOptions(requestedSort, searchConfig) {
+        const { sortFields } = searchConfig;
+        const defaultSort = { 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 = {};
+        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;
+    }
+}
+//# sourceMappingURL=repository-resource.backend.service.js.map