@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/base-classes/services/services/services-registry-handler.backend.service.js

@@ -0,0 +1,4015 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { injectable, inject, optional } from 'inversify';
+import { CoreResourceOperation, CoreResourceType, DEFAULT_PERSISTENCE_ADAPTER, ResourcesConfig_OperationPathUtils, ErrorType, ErrorCustomMessageReference, ResourceOperationVariantType, ResourceOperationsUtils, DataMode, OPERATION_VARIANT_KEY, ChildLifecycleMode, ResourceOperation_ServiceRuntimeMode, ExecutionContext_ExecutionType, CoreConsumableTokenTypes, isWildoBackendError, Resources_SharedUtils, ResourceRelationshipBulkAction, ResourceRelationshipBulkActionRequestSchema, ResourceRelationshipBulkClearOperationRequestSchema, ResourceRelationshipBulkCreateOperationRequestSchema, ResourceRelationshipBulkLinkOperationRequestSchema, ResourceRelationshipBulkReplaceOperationRequestSchema, ResourceRelationshipBulkSetOperationRequestSchema, ResourceRelationshipBulkUnlinkOperationRequestSchema, } from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { ResourceOperationHelperBackendService } from '../../../base-classes/services/resource-operations-helper.backend.service.js';
+import { extractFunctionContextNeeds, dataModeToVariantKey, } from '@wildo-ai/saas-models';
+import { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import { z } from 'zod';
+import { PlatformMutualizedHandlerBackendService } from '../../../requests/service/platform-mutualized-handler.backend.service.js';
+import { ResourcesRegistryBackendService } from '../../../resources/services/resources-registry.backend.service.js';
+import { ExternalApiHandlerBackendService } from '../../../external-providers/services/external-api-handler.backend.service.js';
+import { ResourceOperationCustomImplementationRegistryBackendService } from './resource-operation-custom-implementation-registry.backend.service.js';
+import { ServerlessServicesHandlerBackendService } from '../../../requests/service/serverless-services-handler.backend.service.js';
+import { ResourceOperation_CustomServiceImplementationMode } from '@wildo-ai/saas-models';
+import { NotificationDispatcherService } from '../../../notifications/services/notifications-dispatcher.backend.service.js';
+import { ResourcePopulationBackendService } from '../../../resources/services/resource-population.backend.service.js';
+import { VirtualFieldsBackendService } from '../../../resources/services/virtual-fields.backend.service.js';
+import { MongoDBService } from '../../../databases/services/mongodb.service.js';
+import { PostgreSQLDatabaseBackendService } from '../../../databases/services/postgresql-database.backend.service.js';
+import { ResourceParentResourceRequirement, isOneToOneCardinality, getChildDirectionRelationships } from '@wildo-ai/saas-models';
+import { FileOperationHandlerBackendService } from '../../../files/services/file-operation-handler.backend.service.js';
+import { FileFieldDetectionBackendService } from '../../../files/services/file-field-detection.backend.service.js';
+import { hasExplicitCanonicalFieldMutation } from '../../../files/utils/file-field-schema-path.backend.utils.js';
+import { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service.js';
+import { QueueBackendService } from '../../../queue/queue.backend.service.js';
+import { FeatureGateBackendService } from '../../../features/services/feature-gate.backend.service.js';
+import { ConsumableTokenBackendService } from '../../../security/consumable-tokens/services/consumable-token.backend.service.js';
+import { AppConfigurationService } from '../../../config/services/app-configuration.backend.service.js';
+import { GuidanceTriggerEvaluatorBackendService } from '../../../guidance/services/guidance-trigger-evaluator.backend.service.js';
+import { MilestoneEvaluatorBackendService } from '../../../guidance/services/milestone-evaluator.backend.service.js';
+import { LifecycleEvaluatorBackendService } from '../../../guidance/services/lifecycle-evaluator.backend.service.js';
+export async function dispatchPostOperationNotificationsBestEffort(deps, executionContext, inputData, currentResult, tokenGenerationResult) {
+    const resourceRoomParameters = {
+        inputDto: inputData,
+        currentObject: currentResult,
+        initiatorIds: executionContext.initiatorIds,
+    };
+    try {
+        // Resource-room notifications run first and on thinner inputs on purpose:
+        // websocket coherence only needs authoritative object truth + initiator ids,
+        // not the richer population/user context required by authored notifications.
+        await deps.notificationDispatcher.dispatchResourceRoomNotifications(executionContext, resourceRoomParameters);
+    }
+    catch (error) {
+        deps.logger.error('Failed to dispatch resource-room notifications', {
+            error: error instanceof Error ? error.message : 'Unknown error',
+            operationIdentifier: executionContext.operation.operationIdentifier,
+            resourceIdentifier: executionContext.operation.resourceIdentifier,
+        });
+    }
+    try {
+        // Configured notifications are the richer second phase. They may depend on
+        // populated object context, user context, and additional authored delivery
+        // channels, so they intentionally run after the lightweight websocket pass.
+        const resourceType = executionContext.operation.resourceIdentifier;
+        const needs = deps.populationService.analyzeContextNeeds(resourceType);
+        const computationContext = await deps.populationService.fetchComputationContext(resourceType, currentResult, needs, executionContext);
+        const functionParameters = {
+            inputDto: inputData,
+            currentObject: currentResult,
+            objectContext: computationContext.objectContext,
+            initiatorUserContext: computationContext.userContext,
+            initiatorIds: executionContext.initiatorIds,
+        };
+        if (tokenGenerationResult) {
+            functionParameters.additionalContext = {
+                ...(functionParameters.additionalContext || {}),
+                tokenValue: tokenGenerationResult.tokenValue,
+            };
+        }
+        await deps.notificationDispatcher.dispatchConfiguredNotifications(executionContext, functionParameters);
+        deps.logDebug('Configured notifications dispatched successfully');
+    }
+    catch (error) {
+        deps.logger.error('Failed to dispatch configured notifications', {
+            error: error instanceof Error ? error.message : 'Unknown error',
+            operationIdentifier: executionContext.operation.operationIdentifier,
+            resourceIdentifier: executionContext.operation.resourceIdentifier,
+        });
+    }
+}
+let ServicesRegistryHandlerBackendService = class ServicesRegistryHandlerBackendService {
+    repositoriesRegistry;
+    logger;
+    errorBuilder;
+    resourcesRegistry;
+    repositoryHelper;
+    customImplRegistry;
+    externalApiHandler;
+    platformMutualizedHandler;
+    serverlessServicesHandler;
+    notificationDispatcher;
+    populationService;
+    virtualFieldsService;
+    mongoDBService;
+    fileOperationHandler;
+    fileFieldDetection;
+    executionContextCreator;
+    queueService;
+    featureGate;
+    consumableTokenService;
+    appConfigService;
+    guidanceTriggerEvaluator;
+    milestoneEvaluator;
+    lifecycleEvaluator;
+    postgreSQLDatabaseService;
+    samlMetadataService;
+    services;
+    serviceOperationsMap;
+    isInitialized = false;
+    logDebug;
+    /**
+     * Post-operation hooks: fire after a successful mutation on a resource type.
+     * Key = resource type identifier, Value = array of hook callbacks.
+     */
+    postOperationHooks = new Map();
+    constructor(repositoriesRegistry, logger, errorBuilder, resourcesRegistry, repositoryHelper, customImplRegistry, externalApiHandler, platformMutualizedHandler, serverlessServicesHandler, notificationDispatcher, populationService, virtualFieldsService, mongoDBService, fileOperationHandler, fileFieldDetection, executionContextCreator, queueService, featureGate, consumableTokenService, appConfigService, guidanceTriggerEvaluator, milestoneEvaluator, lifecycleEvaluator, postgreSQLDatabaseService, samlMetadataService) {
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.resourcesRegistry = resourcesRegistry;
+        this.repositoryHelper = repositoryHelper;
+        this.customImplRegistry = customImplRegistry;
+        this.externalApiHandler = externalApiHandler;
+        this.platformMutualizedHandler = platformMutualizedHandler;
+        this.serverlessServicesHandler = serverlessServicesHandler;
+        this.notificationDispatcher = notificationDispatcher;
+        this.populationService = populationService;
+        this.virtualFieldsService = virtualFieldsService;
+        this.mongoDBService = mongoDBService;
+        this.fileOperationHandler = fileOperationHandler;
+        this.fileFieldDetection = fileFieldDetection;
+        this.executionContextCreator = executionContextCreator;
+        this.queueService = queueService;
+        this.featureGate = featureGate;
+        this.consumableTokenService = consumableTokenService;
+        this.appConfigService = appConfigService;
+        this.guidanceTriggerEvaluator = guidanceTriggerEvaluator;
+        this.milestoneEvaluator = milestoneEvaluator;
+        this.lifecycleEvaluator = lifecycleEvaluator;
+        this.postgreSQLDatabaseService = postgreSQLDatabaseService;
+        this.samlMetadataService = samlMetadataService;
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.services = new Map();
+        this.serviceOperationsMap = new Map();
+        this.logDebug = this.logger.debugByType('ServicesRegistryHandler');
+        this.logger.setDebugTypeLogging('ServicesRegistryHandler', false);
+        this.logDebug('Services registry service created');
+    }
+    /** Exposes SAML metadata service for custom impl utils (DISCOVER_ENDPOINTS). */
+    getSamlMetadataService() {
+        return this.samlMetadataService;
+    }
+    // ================================
+    // Initialization Methods
+    // ================================
+    async initializeServices() {
+        if (this.isInitialized) {
+            this.logDebug('Registry already initialized, skipping...');
+            return;
+        }
+        const resourceTypes = this.resourcesRegistry.getResourceTypes();
+        this.logDebug('Initializing services', { resourceCount: resourceTypes.length, resourceTypes: resourceTypes });
+        // First pass: Create all services
+        for (const resourceType of resourceTypes) {
+            try {
+                await this.createService(resourceType);
+            }
+            catch (error) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, { customMessageReference: ErrorCustomMessageReference.SERVICE_CREATION_FAILED, context: { resourceType, error: error instanceof Error ? error.message : 'Unknown error' } });
+            }
+        }
+        this.buildOperationPathsMap();
+        this.isInitialized = true;
+        this.logDebug('Services registry initialization completed', {
+            serviceCount: this.services.size,
+            operationPathsCount: this.serviceOperationsMap.size
+        });
+    }
+    async createService(resourceType) {
+        this.logDebug('Creating service', { resourceType });
+        const service = ServiceResourceBackendService.createInstance(resourceType, this.logger, this.errorBuilder, this.repositoriesRegistry, this, this.resourcesRegistry, this.repositoryHelper, this.customImplRegistry, this.externalApiHandler, this.platformMutualizedHandler, this.serverlessServicesHandler, this.notificationDispatcher, this.populationService, this.virtualFieldsService, this.mongoDBService, this.fileOperationHandler, this.fileFieldDetection, this.executionContextCreator, this.queueService, this.featureGate, this.consumableTokenService, this.appConfigService, this.guidanceTriggerEvaluator, this.milestoneEvaluator, this.lifecycleEvaluator, this.postgreSQLDatabaseService);
+        this.services.set(resourceType, service);
+        this.logDebug('Service created successfully', { resourceType });
+    }
+    buildOperationPathsMap() {
+        this.logDebug('Building operation paths map');
+        let totalOperationPaths = 0;
+        this.services.forEach((service, resourceType) => {
+            const resourceConfiguration = this.resourcesRegistry.getResourceConfiguration(resourceType);
+            if (!resourceConfiguration.operations) {
+                return;
+            }
+            resourceConfiguration.operations.forEach(operation => {
+                const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(operation);
+                const operationKey = ResourcesConfig_OperationPathUtils.createOperationPathKey(operationPath);
+                this.serviceOperationsMap.set(operationKey, { service, operationPath });
+                totalOperationPaths++;
+            });
+        });
+        this.logDebug('Operation paths map built', { totalOperationPaths, operationKeys: Array.from(this.serviceOperationsMap.keys()).slice(0, 5) });
+    }
+    // ================================
+    // Service Access Methods
+    // ================================
+    getService(resourceType) {
+        const service = this.services.get(resourceType);
+        if (!service) {
+            this.logDebug('Service not found', { resourceType });
+            return undefined;
+        }
+        return service;
+    }
+    getServiceOrThrow(resourceType) {
+        const service = this.getService(resourceType);
+        if (!service) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, { customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND, context: { resourceType } });
+        }
+        return service;
+    }
+    // ================================
+    // Execution Methods
+    // ================================
+    async doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, data, options) {
+        const operationKey = ResourcesConfig_OperationPathUtils.createOperationPathKey(operationPath);
+        const operationInfo = this.serviceOperationsMap.get(operationKey);
+        if (!operationInfo) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, { customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND, context: { operationKey, operationPath } });
+        }
+        this.logDebug('Executing operation by path', { operationPath, operationKey, id_or_ids_or_filter });
+        return operationInfo.service.doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, data, options);
+    }
+    async doByExecutionContext(executionContext, data, options) {
+        const operation = executionContext.operation;
+        const resourceType = operation.resourceIdentifier;
+        const service = this.getServiceOrThrow(resourceType);
+        this.logDebug('Executing operation by execution context', { resourceType, operationIdentifier: operation.operationIdentifier });
+        return service.doByExecutionContext(executionContext, data, options);
+    }
+    // ════════════════════════════════════════════════════════════════════
+    // Convenience methods for programmatic resource operations.
+    //
+    // These pass the caller's executionContext through to doByOperationPath,
+    // which resolves the target operation from the registry. If the caller's
+    // executionContext.operation differs from the target operation (e.g., a
+    // webhook handler calling create(SUBSCRIPTION, webhookCtx)), doOperation's
+    // Correction Point 1 corrects the context before any pipeline logic runs.
+    //
+    // For proper sub-call depth tracking and cycle detection, callers should
+    // use executionContextCreator.createForSubCall() before calling these
+    // methods. Without it, operations are functionally correct but skip
+    // depth/cycle safety checks.
+    // ════════════════════════════════════════════════════════════════════
+    async create(resourceType, executionContext, data, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.CREATE);
+        return service.doByOperationPath(operationPath, executionContext, undefined, data, options);
+    }
+    async createMany(resourceType, executionContext, data, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.CREATE_MANY);
+        return service.doByOperationPath(operationPath, executionContext, undefined, data, options);
+    }
+    async read(resourceType, executionContext, id_or_ids_or_filter, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        // If variantKey is specified, get that variant's operationPath
+        const operationPath = options?.variantKey
+            ? this.resourcesRegistry.getOperationPath(resourceType, CoreResourceOperation.READ, options.variantKey)
+            : this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.READ);
+        return service.doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, undefined, options);
+    }
+    async update(resourceType, executionContext, id_or_ids_or_filter, data, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.UPDATE);
+        return service.doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, data, options);
+    }
+    async updateMany(resourceType, executionContext, id_or_ids_or_filter, data, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.UPDATE_MANY);
+        return service.doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, data, options);
+    }
+    async delete(resourceType, executionContext, resourceId, options) {
+        if (typeof resourceId !== 'string' || resourceId.length === 0) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    operation: CoreResourceOperation.DELETE,
+                    reason: 'ServicesRegistryHandlerBackendService.delete() only accepts a single resource id. Use deleteMany() for ids or filters.',
+                    resourceType,
+                },
+            });
+        }
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.DELETE);
+        return service.doByOperationPath(operationPath, executionContext, resourceId, undefined, options);
+    }
+    async deleteMany(resourceType, executionContext, id_or_ids_or_filter, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.DELETE_MANY);
+        return service.doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, undefined, options);
+    }
+    // ════════════════════════════════════════════════════════════════════
+    // Custom operations
+    // ════════════════════════════════════════════════════════════════════
+    /**
+     * Execute a custom operation on a resource through the full pipeline.
+     * Routes through the same operation pipeline as HTTP-triggered custom operations
+     * (Zod validation, RBAC, custom impl dispatch, post-operation hooks).
+     *
+     * @param resourceType - The resource type to execute the operation on
+     * @param customOperationIdentifier - The custom operation name (e.g., 'top_up', 'consume')
+     * @param executionContext - The execution context for RBAC and scoping
+     * @param id_or_ids_or_filter - The resource ID to target (most custom ops require this)
+     * @param data - The request payload for the custom operation
+     * @param options - Optional service options
+     */
+    async executeCustomOperation(resourceType, customOperationIdentifier, executionContext, id_or_ids_or_filter, data, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, customOperationIdentifier);
+        return service.doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, data, options);
+    }
+    /**
+     * Execute an explicit multi-target relationship action.
+     *
+     * This is the service-level implementation seam behind the planned operation
+     * split:
+     * - `UPDATE_MANY` stays a bulk patch of the main resource
+     * - explicit relationship actions (`set`, `clear`, `create`, `link`,
+     *   `unlink`) are applied to a named relationship from the current resource's
+     *   perspective
+     */
+    async applyRelationshipActionMany(resourceType, executionContext, id_or_ids_or_filter, request, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const parsedRequest = ResourceRelationshipBulkActionRequestSchema.parse(request);
+        return service.applyRelationshipActionMany(executionContext, id_or_ids_or_filter, parsedRequest, options);
+    }
+    // ════════════════════════════════════════════════════════════════════
+    // Post-operation hooks
+    // ════════════════════════════════════════════════════════════════════
+    /**
+     * Register a callback that fires after any successful mutation on a resource type.
+     * Hooks are fire-and-forget — errors are logged but do not fail the operation.
+     *
+     * @param resourceType - The resource type to observe
+     * @param callback - Invoked after CREATE, UPDATE, DELETE, or custom mutation succeeds
+     */
+    registerPostOperationHook(resourceType, callback) {
+        const hooks = this.postOperationHooks.get(resourceType) ?? [];
+        hooks.push(callback);
+        this.postOperationHooks.set(resourceType, hooks);
+        this.logDebug('Post-operation hook registered', { resourceType });
+    }
+    /**
+     * Dispatch post-operation hooks for a resource type.
+     * Called by ServiceResourceBackendService after successful operations.
+     * @internal
+     */
+    async dispatchPostOperationHooks(resourceType, operationIdentifier, result, executionContext) {
+        const hooks = this.postOperationHooks.get(resourceType);
+        if (!hooks || hooks.length === 0)
+            return;
+        for (const hook of hooks) {
+            try {
+                await hook(resourceType, operationIdentifier, result, executionContext);
+            }
+            catch (error) {
+                this.logger.warn('Post-operation hook failed', {
+                    resourceType,
+                    operationIdentifier,
+                    error: error.message,
+                });
+            }
+        }
+    }
+    // ════════════════════════════════════════════════════════════════════
+    // Read / List / Search / Count
+    // ════════════════════════════════════════════════════════════════════
+    /**
+     * List resources with optional pagination.
+     * @param options.paginated - When true, returns { data: T[], pagination: {...} }. Default: false (returns T[])
+     * @param options.variantKey - Optional variant key (e.g., 'summary', 'context')
+     * @param options.dataMode - Optional data mode for population behavior
+     */
+    async list(resourceType, executionContext, filter, pagination, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        // If variantKey is specified, get that variant's operationPath
+        const operationPath = options?.variantKey
+            ? this.resourcesRegistry.getOperationPath(resourceType, CoreResourceOperation.LIST, options.variantKey)
+            : this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.LIST);
+        const listData = { filter, page: pagination?.page, limit: pagination?.limit };
+        return service.doByOperationPath(operationPath, executionContext, undefined, listData, options);
+    }
+    async search(resourceType, executionContext, searchQuery, filter, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.SEARCH);
+        return service.doByOperationPath(operationPath, executionContext, undefined, { searchQuery, filter }, options);
+    }
+    async count(resourceType, executionContext, filter, options) {
+        const service = this.getServiceOrThrow(resourceType);
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.COUNT);
+        const countData = filter ? { filter } : undefined;
+        return service.doByOperationPath(operationPath, executionContext, undefined, countData, options);
+    }
+    // ================================
+    // Utility Methods
+    // ================================
+    getAvailableOperationPaths() {
+        return Array.from(this.serviceOperationsMap.values()).map(info => info.operationPath);
+    }
+    hasService(resourceType) {
+        return this.services.has(resourceType);
+    }
+    getRegisteredResourceTypes() {
+        return Array.from(this.services.keys());
+    }
+    getServiceCount() {
+        return this.services.size;
+    }
+    getDebugInfo() {
+        return {
+            serviceCount: this.services.size,
+            operationPathsCount: this.serviceOperationsMap.size,
+            resourceTypes: Array.from(this.services.keys()),
+            isInitialized: this.isInitialized
+        };
+    }
+};
+ServicesRegistryHandlerBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(1, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ResourceOperationHelperService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ResourceOperationCustomImplementationRegistryService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.ExternalApiHandlerService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.PlatformMutualizedHandlerService)),
+    __param(8, inject(SAAS_SERVICE_TYPES.ServerlessServicesHandlerService)),
+    __param(9, inject(SAAS_SERVICE_TYPES.NotificationDispatcherService)),
+    __param(10, inject(SAAS_SERVICE_TYPES.ResourcePopulationService)),
+    __param(11, inject(SAAS_SERVICE_TYPES.VirtualFieldsService)),
+    __param(12, inject(SAAS_SERVICE_TYPES.MongoDBService)),
+    __param(13, inject(SAAS_SERVICE_TYPES.FileOperationHandlerService)),
+    __param(14, inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)),
+    __param(15, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(16, inject(SAAS_SERVICE_TYPES.QueueBackendService)),
+    __param(17, inject(SAAS_SERVICE_TYPES.FeatureGateService)),
+    __param(18, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(19, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(20, inject(SAAS_SERVICE_TYPES.GuidanceTriggerEvaluator)),
+    __param(20, optional()),
+    __param(21, inject(SAAS_SERVICE_TYPES.MilestoneEvaluator)),
+    __param(21, optional()),
+    __param(22, inject(SAAS_SERVICE_TYPES.LifecycleEvaluator)),
+    __param(22, optional()),
+    __param(23, inject(SAAS_SERVICE_TYPES.PostgreSQLDatabaseService)),
+    __param(23, optional()),
+    __param(24, inject(SAAS_SERVICE_TYPES.SAMLMetadataService)),
+    __param(24, optional()),
+    __metadata("design:paramtypes", [RepositoriesRegistryHandlerBackendService,
+        LoggerService,
+        ErrorBuilderBackendService,
+        ResourcesRegistryBackendService,
+        ResourceOperationHelperBackendService,
+        ResourceOperationCustomImplementationRegistryBackendService,
+        ExternalApiHandlerBackendService,
+        PlatformMutualizedHandlerBackendService,
+        ServerlessServicesHandlerBackendService,
+        NotificationDispatcherService,
+        ResourcePopulationBackendService,
+        VirtualFieldsBackendService,
+        MongoDBService,
+        FileOperationHandlerBackendService,
+        FileFieldDetectionBackendService,
+        ExecutionContextCreatorBackendService,
+        QueueBackendService,
+        FeatureGateBackendService,
+        ConsumableTokenBackendService,
+        AppConfigurationService,
+        GuidanceTriggerEvaluatorBackendService,
+        MilestoneEvaluatorBackendService,
+        LifecycleEvaluatorBackendService,
+        PostgreSQLDatabaseBackendService, Function])
+], ServicesRegistryHandlerBackendService);
+export { ServicesRegistryHandlerBackendService };
+//============================================================================================================================
+//
+// Service Resource Backend Service
+//
+//============================================================================================================================
+export class ServiceResourceBackendService {
+    resourcesRegistry;
+    logger;
+    errorBuilder;
+    repositoryHelper;
+    customImplRegistry;
+    repositoriesRegistry;
+    servicesRegistry;
+    externalApiHandler;
+    platformMutualizedHandler;
+    serverlessServicesHandler;
+    notificationDispatcher;
+    populationService;
+    virtualFieldsService;
+    mongoDBService;
+    fileOperationHandler;
+    fileFieldDetection;
+    executionContextCreator;
+    queueService;
+    featureGate;
+    consumableTokenService;
+    appConfigService;
+    guidanceTriggerEvaluator;
+    milestoneEvaluator;
+    lifecycleEvaluator;
+    postgreSQLDatabaseService;
+    resourceConfiguration;
+    operationsMap;
+    logDebug;
+    constructor(resourceType, resourcesRegistry, logger, errorBuilder, repositoryHelper, customImplRegistry, repositoriesRegistry, servicesRegistry, externalApiHandler, platformMutualizedHandler, serverlessServicesHandler, notificationDispatcher, populationService, virtualFieldsService, mongoDBService, fileOperationHandler, fileFieldDetection, executionContextCreator, queueService, featureGate, consumableTokenService, appConfigService, guidanceTriggerEvaluator, milestoneEvaluator, lifecycleEvaluator, postgreSQLDatabaseService) {
+        this.resourcesRegistry = resourcesRegistry;
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.repositoryHelper = repositoryHelper;
+        this.customImplRegistry = customImplRegistry;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.servicesRegistry = servicesRegistry;
+        this.externalApiHandler = externalApiHandler;
+        this.platformMutualizedHandler = platformMutualizedHandler;
+        this.serverlessServicesHandler = serverlessServicesHandler;
+        this.notificationDispatcher = notificationDispatcher;
+        this.populationService = populationService;
+        this.virtualFieldsService = virtualFieldsService;
+        this.mongoDBService = mongoDBService;
+        this.fileOperationHandler = fileOperationHandler;
+        this.fileFieldDetection = fileFieldDetection;
+        this.executionContextCreator = executionContextCreator;
+        this.queueService = queueService;
+        this.featureGate = featureGate;
+        this.consumableTokenService = consumableTokenService;
+        this.appConfigService = appConfigService;
+        this.guidanceTriggerEvaluator = guidanceTriggerEvaluator;
+        this.milestoneEvaluator = milestoneEvaluator;
+        this.lifecycleEvaluator = lifecycleEvaluator;
+        this.postgreSQLDatabaseService = postgreSQLDatabaseService;
+        this.operationsMap = new Map();
+        this.resourceConfiguration = this.resourcesRegistry.getResourceConfiguration(resourceType);
+        this.logDebug = this.logger.debugByType(`ServiceResource_${resourceType}`);
+        this.logger.setDebugTypeLogging(`ServiceResource_${resourceType}`, false);
+        this.initializeOperationsMap();
+        this.logDebug('Service resource created', {
+            resourceType: this.resourceConfiguration.resourceIdentifier,
+            operationsCount: this.operationsMap.size
+        });
+    }
+    static createInstance(resourceType, logger, errorBuilder, repositoriesRegistry, servicesRegistry, resourcesRegistry, repositoryHelper, customImplRegistry, externalApiHandler, platformMutualizedHandler, serverlessServicesHandler, notificationDispatcher, populationService, virtualFieldsService, mongoDBService, fileOperationHandler, fileFieldDetection, executionContextCreator, queueService, featureGate, consumableTokenService, appConfigService, guidanceTriggerEvaluator, milestoneEvaluator, lifecycleEvaluator, postgreSQLDatabaseService) {
+        return new ServiceResourceBackendService(resourceType, resourcesRegistry, logger, errorBuilder, repositoryHelper, customImplRegistry, repositoriesRegistry, servicesRegistry, externalApiHandler, platformMutualizedHandler, serverlessServicesHandler, notificationDispatcher, populationService, virtualFieldsService, mongoDBService, fileOperationHandler, fileFieldDetection, executionContextCreator, queueService, featureGate, consumableTokenService, appConfigService, guidanceTriggerEvaluator, milestoneEvaluator, lifecycleEvaluator, postgreSQLDatabaseService);
+    }
+    async applyRelationshipActionMany(executionContext, id_or_ids_or_filter, request, options) {
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const parsedRequest = ResourceRelationshipBulkActionRequestSchema.parse(request);
+        let relationship;
+        try {
+            relationship = this.getRelationshipForBulkAction(parsedRequest.relationshipField);
+        }
+        catch (error) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    relationshipField: parsedRequest.relationshipField,
+                    resourceType,
+                    reason: error instanceof Error ? error.message : 'Invalid relationship field for bulk action',
+                },
+            });
+        }
+        const allowedActions = Resources_SharedUtils.resolveAllowedBulkRelationshipActionsForResource(relationship, resourceType);
+        if (!allowedActions.includes(parsedRequest.action)) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    relationshipField: parsedRequest.relationshipField,
+                    action: parsedRequest.action,
+                    resourceType,
+                    allowedActions,
+                    reason: 'Requested bulk relationship action is not allowed for this relationship from the current resource perspective',
+                },
+            });
+        }
+        switch (parsedRequest.action) {
+            case ResourceRelationshipBulkAction.SET:
+                return this.applyReferenceSetActionMany(executionContext, id_or_ids_or_filter, relationship, parsedRequest.relationshipField, parsedRequest.targetId, options);
+            case ResourceRelationshipBulkAction.CLEAR:
+                return this.applyReferenceClearActionMany(executionContext, id_or_ids_or_filter, relationship, parsedRequest.relationshipField, options);
+            case ResourceRelationshipBulkAction.CREATE:
+                return this.applyCompositionCreateActionMany(executionContext, id_or_ids_or_filter, relationship, parsedRequest.relationshipField, parsedRequest.data, options);
+            case ResourceRelationshipBulkAction.LINK:
+                return this.applyAssociationLinkActionMany(executionContext, id_or_ids_or_filter, relationship, parsedRequest.relationshipField, parsedRequest.peerIds, options);
+            case ResourceRelationshipBulkAction.UNLINK:
+                return this.applyAssociationUnlinkActionMany(executionContext, id_or_ids_or_filter, relationship, parsedRequest.relationshipField, parsedRequest.peerIds, options);
+            case ResourceRelationshipBulkAction.REPLACE:
+                return this.applyAssociationReplaceActionMany(executionContext, id_or_ids_or_filter, relationship, parsedRequest.relationshipField, parsedRequest.peerIds, options);
+        }
+    }
+    async executeGeneratedRelationshipBulkOperation(resolvedOperation, operation, executionContext, data, options) {
+        switch (operation.action) {
+            case ResourceRelationshipBulkAction.SET: {
+                const request = this.parseGeneratedRelationshipBulkOperationRequest(ResourceRelationshipBulkSetOperationRequestSchema, operation, data, executionContext);
+                await this.assertGeneratedRelationshipBulkOperationEnabled(resolvedOperation, request, executionContext);
+                return this.applyRelationshipActionMany(executionContext, this.resolveGeneratedRelationshipBulkSelector(request), {
+                    relationshipField: operation.relationshipField,
+                    action: ResourceRelationshipBulkAction.SET,
+                    targetId: request.targetId,
+                }, options);
+            }
+            case ResourceRelationshipBulkAction.CLEAR: {
+                const request = this.parseGeneratedRelationshipBulkOperationRequest(ResourceRelationshipBulkClearOperationRequestSchema, operation, data, executionContext);
+                await this.assertGeneratedRelationshipBulkOperationEnabled(resolvedOperation, request, executionContext);
+                return this.applyRelationshipActionMany(executionContext, this.resolveGeneratedRelationshipBulkSelector(request), {
+                    relationshipField: operation.relationshipField,
+                    action: ResourceRelationshipBulkAction.CLEAR,
+                }, options);
+            }
+            case ResourceRelationshipBulkAction.CREATE: {
+                const request = this.parseGeneratedRelationshipBulkOperationRequest(ResourceRelationshipBulkCreateOperationRequestSchema, operation, data, executionContext);
+                await this.assertGeneratedRelationshipBulkOperationEnabled(resolvedOperation, request, executionContext);
+                return this.applyRelationshipActionMany(executionContext, this.resolveGeneratedRelationshipBulkSelector(request), {
+                    relationshipField: operation.relationshipField,
+                    action: ResourceRelationshipBulkAction.CREATE,
+                    data: request.data,
+                }, options);
+            }
+            case ResourceRelationshipBulkAction.LINK: {
+                const request = this.parseGeneratedRelationshipBulkOperationRequest(ResourceRelationshipBulkLinkOperationRequestSchema, operation, data, executionContext);
+                await this.assertGeneratedRelationshipBulkOperationEnabled(resolvedOperation, request, executionContext);
+                return this.applyRelationshipActionMany(executionContext, this.resolveGeneratedRelationshipBulkSelector(request), {
+                    relationshipField: operation.relationshipField,
+                    action: ResourceRelationshipBulkAction.LINK,
+                    peerIds: request.peerIds,
+                }, options);
+            }
+            case ResourceRelationshipBulkAction.UNLINK: {
+                const request = this.parseGeneratedRelationshipBulkOperationRequest(ResourceRelationshipBulkUnlinkOperationRequestSchema, operation, data, executionContext);
+                await this.assertGeneratedRelationshipBulkOperationEnabled(resolvedOperation, request, executionContext);
+                return this.applyRelationshipActionMany(executionContext, this.resolveGeneratedRelationshipBulkSelector(request), {
+                    relationshipField: operation.relationshipField,
+                    action: ResourceRelationshipBulkAction.UNLINK,
+                    peerIds: request.peerIds,
+                }, options);
+            }
+            case ResourceRelationshipBulkAction.REPLACE: {
+                const request = this.parseGeneratedRelationshipBulkOperationRequest(ResourceRelationshipBulkReplaceOperationRequestSchema, operation, data, executionContext);
+                await this.assertGeneratedRelationshipBulkOperationEnabled(resolvedOperation, request, executionContext);
+                return this.applyRelationshipActionMany(executionContext, this.resolveGeneratedRelationshipBulkSelector(request), {
+                    relationshipField: operation.relationshipField,
+                    action: ResourceRelationshipBulkAction.REPLACE,
+                    peerIds: request.peerIds,
+                }, options);
+            }
+        }
+    }
+    parseGeneratedRelationshipBulkOperationRequest(schema, operation, data, executionContext) {
+        try {
+            return schema.parse(data);
+        }
+        catch (error) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    action: operation.action,
+                    relationshipField: operation.relationshipField,
+                    reason: error instanceof Error ? error.message : 'Invalid bulk relationship operation payload',
+                },
+            });
+        }
+    }
+    resolveGeneratedRelationshipBulkSelector(request) {
+        if ('_ids' in request && Array.isArray(request._ids)) {
+            return request._ids.length === 1 ? request._ids[0] : request._ids;
+        }
+        if ('filter' in request && request.filter) {
+            return request.filter;
+        }
+        throw new Error('Bulk relationship operation selector must provide either _ids or filter');
+    }
+    async assertGeneratedRelationshipBulkOperationEnabled(operation, request, executionContext) {
+        if (!('enabledCondition' in operation) || !operation.enabledCondition) {
+            return;
+        }
+        const selector = this.resolveGeneratedRelationshipBulkSelector(request);
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const singleSelectedId = Array.isArray(request._ids) && request._ids.length === 1
+            ? request._ids[0]
+            : undefined;
+        const needs = extractFunctionContextNeeds(operation.enabledCondition);
+        if (!singleSelectedId && needs.needsObjectContext) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED,
+                context: {
+                    reason: 'Generated bulk relationship operations with multi-target selectors cannot satisfy enabledCondition object-context requirements',
+                    operationIdentifier: String(operation.operationIdentifier),
+                },
+            });
+        }
+        const currentObject = singleSelectedId
+            ? await this.fetchCurrentObjectForOperation(CoreResourceOperation.UPDATE_MANY, resourceType, singleSelectedId, executionContext)
+            : undefined;
+        if (singleSelectedId && needs.needsObjectContext && !currentObject) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED,
+                context: {
+                    reason: 'Generated bulk relationship operations requiring object context cannot run when the selected current object cannot be loaded',
+                    operationIdentifier: String(operation.operationIdentifier),
+                },
+            });
+        }
+        const { objectContext, initiatorUserContext } = await this.fetchContextsForOperationFunction(operation.enabledCondition, resourceType, currentObject, executionContext);
+        // Generated bulk operations only have a persisted current object when the
+        // selector is exactly one `_id`. Multi-target selectors deliberately fail
+        // closed before this point if `needsObjectContext` is declared.
+        const isEnabled = operation.enabledCondition({
+            inputDto: request,
+            currentObject: currentObject,
+            objectContext,
+            initiatorUserContext,
+            initiatorIds: executionContext.initiatorIds,
+        });
+        if (!isEnabled) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, { customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED });
+        }
+    }
+    resolveSingleSelectedId(id_or_ids_or_filter) {
+        if (typeof id_or_ids_or_filter === 'string') {
+            return id_or_ids_or_filter;
+        }
+        if (Array.isArray(id_or_ids_or_filter)
+            && id_or_ids_or_filter.length === 1
+            && typeof id_or_ids_or_filter[0] === 'string') {
+            return id_or_ids_or_filter[0];
+        }
+        if (id_or_ids_or_filter
+            && typeof id_or_ids_or_filter === 'object'
+            && !Array.isArray(id_or_ids_or_filter)) {
+            if ('id_or_ids' in id_or_ids_or_filter
+                && Array.isArray(id_or_ids_or_filter.id_or_ids)
+                && id_or_ids_or_filter.id_or_ids.length === 1
+                && typeof id_or_ids_or_filter.id_or_ids[0] === 'string') {
+                return id_or_ids_or_filter.id_or_ids[0];
+            }
+            if ('ids' in id_or_ids_or_filter
+                && Array.isArray(id_or_ids_or_filter.ids)
+                && id_or_ids_or_filter.ids.length === 1
+                && typeof id_or_ids_or_filter.ids[0] === 'string') {
+                return id_or_ids_or_filter.ids[0];
+            }
+        }
+        return undefined;
+    }
+    resolveHookCurrentObject(coreOperation, currentObject, data) {
+        return coreOperation === CoreResourceOperation.CREATE
+            || coreOperation === CoreResourceOperation.CREATE_MANY
+            ? data
+            : currentObject;
+    }
+    assertBulkHookObjectContextAvailability(coreOperation, isBulkOperation, fn, currentObject, executionContext, operationIdentifier, hookName) {
+        const isBulkUpdateOperation = coreOperation === CoreResourceOperation.UPDATE_MANY
+            || (coreOperation === CoreResourceOperation.UPDATE && isBulkOperation === true);
+        if (!isBulkUpdateOperation) {
+            return;
+        }
+        const needs = extractFunctionContextNeeds(fn);
+        if (!needs.needsObjectContext || currentObject) {
+            return;
+        }
+        throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED,
+            context: {
+                reason: `${hookName} requires object context, but this bulk update cannot provide a single persisted current object`,
+                operationIdentifier,
+            },
+        });
+    }
+    initializeOperationsMap() {
+        if (!this.resourceConfiguration.operations) {
+            return;
+        }
+        // Include operations that should be handled by services
+        const serviceOperations = this.resourceConfiguration.operations.filter((op) => op.variantType === ResourceOperationVariantType.INTERNAL_CALL ||
+            op.variantType === ResourceOperationVariantType.API_CALL ||
+            op.variantType === ResourceOperationVariantType.CRON_JOB ||
+            op.variantType === ResourceOperationVariantType.BATCH_JOB);
+        serviceOperations.forEach(operation => {
+            const operationKey = ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation);
+            this.operationsMap.set(operationKey, operation);
+        });
+        this.logDebug('Service operations map initialized', {
+            totalOperations: this.resourceConfiguration.operations.length,
+            serviceOperations: serviceOperations.length
+        });
+    }
+    /**
+     * Entry point from registry convenience methods (`create`, `update`, `delete`, etc.)
+     * and controller-level `doByOperationPath`.
+     *
+     * Resolves `operation` from this handler's `operationsMap`. The caller's
+     * `executionContext.operation` may point to a DIFFERENT operation (e.g., a parent's
+     * operation or a generic webhook operation). `doOperation()` corrects this mismatch
+     * via Correction Point 1 before any pipeline logic executes.
+     */
+    async doByOperationPath(operationPath, executionContext, id_or_ids_or_filter, data, options) {
+        const operationKey = ResourcesConfig_OperationPathUtils.createOperationPathKey(operationPath);
+        const operation = this.operationsMap.get(operationKey);
+        if (!operation) {
+            const error = this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, { customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED });
+            throw error;
+        }
+        this.logDebug('Executing operation by path', {
+            operationPath,
+            operationKey,
+            resourceType: this.resourceConfiguration.resourceIdentifier,
+            id_or_ids_or_filter
+        });
+        return this.doOperation(operation, executionContext, id_or_ids_or_filter, data, options);
+    }
+    /**
+     * Entry point from controller-level `doByExecutionContext`.
+     *
+     * Reads `operation` directly from `executionContext.operation` — guaranteed to match
+     * (same object reference). `doOperation()` correction points are no-ops in this path.
+     */
+    async doByExecutionContext(executionContext, data, options) {
+        const operation = executionContext.operation;
+        // Extract IDs based on resourceFieldIdentifier from execution context
+        const id_or_ids_or_filter = this.repositoryHelper.extractIdsFromExecutionContext(executionContext, this.resourceConfiguration.resourceFieldIdentifier);
+        this.logDebug('Executing operation by execution context', {
+            resourceType: this.resourceConfiguration.resourceIdentifier,
+            operationIdentifier: operation.operationIdentifier,
+            extractedIds: id_or_ids_or_filter,
+            resourceFieldIdentifier: this.resourceConfiguration.resourceFieldIdentifier
+        });
+        return this.doOperation(operation, executionContext, id_or_ids_or_filter, data, options);
+    }
+    resolveOperationForDataMode(operation, dataMode) {
+        if (!dataMode || dataMode === DataMode.RAW) {
+            return operation;
+        }
+        return this.resolveOperationVariant(operation, dataMode);
+    }
+    /**
+     * Helper method to fetch contexts for operation functions (enabledCondition, basicPrefixOperation).
+     * Fetches objectContext and userContext only when needed based on function flags.
+     *
+     * @param fn - Function with optional context needs flags
+     * @param resourceType - Resource type for context fetching
+     * @param currentObject - Current object (fetched if needed for UPDATE/DELETE)
+     * @param executionContext - Execution context
+     * @returns Object with objectContext, userContext, and resolved currentObject
+     */
+    async fetchContextsForOperationFunction(fn, resourceType, currentObject, executionContext) {
+        const needs = extractFunctionContextNeeds(fn);
+        let objectContext = undefined;
+        let initiatorUserContext = undefined;
+        if (needs.needsObjectContext) {
+            const resourceNeeds = this.populationService.analyzeContextNeeds(resourceType);
+            const computationContext = await this.populationService.fetchComputationContext(resourceType, currentObject || {}, resourceNeeds, executionContext);
+            objectContext = computationContext.objectContext;
+        }
+        if (needs.needsUserContext) {
+            initiatorUserContext = executionContext.user; // Initiator user context from execution context
+        }
+        return { objectContext, initiatorUserContext, currentObject };
+    }
+    /**
+     * Fetch current object for UPDATE/DELETE operations.
+     * For CREATE operations, returns undefined (object doesn't exist yet).
+     *
+     * @param coreOperation - The core operation type
+     * @param resourceType - Resource type
+     * @param id_or_ids_or_filter - ID or filter
+     * @param executionContext - Execution context
+     * @returns Current object or undefined for CREATE
+     */
+    async fetchCurrentObjectForOperation(coreOperation, resourceType, id_or_ids_or_filter, executionContext) {
+        const isCreateOperation = coreOperation === CoreResourceOperation.CREATE ||
+            coreOperation === CoreResourceOperation.CREATE_MANY;
+        // For CREATE operations, currentObject is undefined (object doesn't exist yet)
+        if (isCreateOperation) {
+            return undefined;
+        }
+        const singleSelectedId = this.resolveSingleSelectedId(id_or_ids_or_filter);
+        // For UPDATE/DELETE/READ operations, fetch current object if we have exactly one ID
+        if (singleSelectedId) {
+            try {
+                const repo = this.repositoriesRegistry.getRepository(resourceType);
+                if (repo && 'read' in repo) {
+                    const readResult = await repo.read(executionContext, singleSelectedId);
+                    return Array.isArray(readResult) ? readResult[0] : readResult;
+                }
+            }
+            catch (error) {
+                // If object doesn't exist, return undefined (enabledCondition will handle it)
+                this.logDebug('Failed to fetch current object for enabledCondition', {
+                    resourceType,
+                    id: singleSelectedId,
+                    error: error instanceof Error ? error.message : 'Unknown'
+                });
+                return undefined;
+            }
+        }
+        // Fallback: return undefined if we can't determine the object
+        return undefined;
+    }
+    static STEP_UP_EXEMPT_OPERATIONS = new Set([
+        CoreResourceOperation.READ,
+        CoreResourceOperation.LIST,
+        CoreResourceOperation.SEARCH,
+        CoreResourceOperation.COUNT,
+    ]);
+    /**
+     * W7.1: Enforces step-up re-authentication for sensitive (mutating) operations.
+     *
+     * Skip conditions (all must be false for enforcement to apply):
+     * 1. Non-user requests (INTERNAL_CALL, API_KEY, etc.) — exempt
+     * 2. Worker executions — already authorized at queue time
+     * 3. Sub-calls (subCallDepth > 0) — parent already passed step-up
+     * 4. Read-only operations (READ, LIST, SEARCH, COUNT) — exempt
+     * 5. stepUpAuth not enabled for this user type — no-op
+     *
+     * When enforced and auth is stale (beyond maxAgeSeconds), accepts either:
+     * - A valid REAUTH consumable token via X-Reauth-Token header
+     * - Otherwise throws STEP_UP_REQUIRED (HTTP 403)
+     */
+    async enforceStepUpAuth(coreOperation, executionContext, options) {
+        if (executionContext.executionType !== ExecutionContext_ExecutionType.USER_REQUEST)
+            return;
+        if (options?.isWorkerExecution)
+            return;
+        if (executionContext.subCallDepth > 0)
+            return;
+        if (coreOperation && ServiceResourceBackendService.STEP_UP_EXEMPT_OPERATIONS.has(coreOperation))
+            return;
+        const activeUserType = executionContext.activeUserType;
+        if (!activeUserType)
+            return;
+        const authPolicy = this.appConfigService.getUserTypeAuthPolicy(activeUserType);
+        const stepUpConfig = authPolicy?.stepUpAuth;
+        if (!stepUpConfig?.enabled)
+            return;
+        const lastAuthAt = executionContext.lastAuthenticatedAt ?? 0;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (nowSeconds - lastAuthAt <= stepUpConfig.maxAgeSeconds)
+            return;
+        const reAuthTokenValue = executionContext.reAuthTokenValue;
+        if (reAuthTokenValue) {
+            try {
+                const consumed = await this.consumableTokenService.consumeToken(reAuthTokenValue);
+                if (consumed.tokenType === CoreConsumableTokenTypes.REAUTH
+                    && consumed.userId === executionContext.initiatorIds.userId) {
+                    return;
+                }
+            }
+            catch (err) {
+                if (isWildoBackendError(err)) {
+                    this.logDebug('Re-auth token consumption failed', { error: err.customMessageReference });
+                }
+            }
+        }
+        throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.STEP_UP_REQUIRED,
+            context: { maxAgeSeconds: stepUpConfig.maxAgeSeconds },
+        });
+    }
+    /**
+     * Central orchestration method — ALL resource operations flow through here.
+     *
+     * Two entry points:
+     * - `doByOperationPath()` — resolves `operation` from the operations map. The caller's
+     *   `executionContext.operation` may differ (e.g., webhook context with a generic operation).
+     * - `doByExecutionContext()` — reads `operation` from `executionContext.operation`.
+     *   Guaranteed to match (same reference).
+     *
+     * Two correction points enforce the invariant that `executionContext.operation` always
+     * matches the operation being executed:
+     * - Correction Point 1 (pre-queue): corrects to the base `operation` parameter.
+     * - Correction Point 2 (post-variant): refines to `resolvedOperation` when `dataMode !== RAW`.
+     *
+     * After correction, ALL downstream reads of `executionContext.operation` — notifications,
+     * guidance, milestones, queue serialization, repositories — use the correct operation.
+     */
+    async doOperation(operation, executionContext, id_or_ids_or_filter, data, options) {
+        let currentState;
+        if (operation.variantType === ResourceOperationVariantType.REPOSITORY_ONLY) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, { customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED });
+        }
+        // ── INVARIANT: executionContext.operation must match the operation being executed ──
+        // Correction Point 1 (pre-queue): ensures queue serialization and all non-INLINE
+        // dispatch paths use the correct operation. Without this, QueueBackendService.buildJobPayload
+        // would serialize the caller's stale operation path.
+        if (executionContext.operation !== operation) {
+            this.logDebug('Correcting executionContext.operation mismatch', {
+                contextOp: `${executionContext.operation.resourceIdentifier}.${executionContext.operation.operationIdentifier}`,
+                actualOp: `${operation.resourceIdentifier}.${operation.operationIdentifier}`,
+            });
+            executionContext = executionContext.withOperation(operation);
+        }
+        // ============================================
+        // STEP 1: Check serviceRuntimeMode FIRST
+        // Skip this check if executing from worker (prevents infinite loop)
+        // ============================================
+        const runtimeMode = operation.serviceRuntimeMode ?? ResourceOperation_ServiceRuntimeMode.INLINE;
+        if (!options?.isWorkerExecution && runtimeMode !== ResourceOperation_ServiceRuntimeMode.INLINE) {
+            switch (runtimeMode) {
+                case ResourceOperation_ServiceRuntimeMode.NONE:
+                    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                        context: { message: 'Operation has serviceRuntimeMode: NONE (disabled)' },
+                    });
+                case ResourceOperation_ServiceRuntimeMode.QUEUED:
+                    // Queue and wait for result via RPC pattern
+                    return this.executeQueued(executionContext, id_or_ids_or_filter, data, true);
+                case ResourceOperation_ServiceRuntimeMode.QUEUED_NOT_AWAITABLE:
+                    // Queue and return immediately
+                    return this.executeQueued(executionContext, id_or_ids_or_filter, data, false);
+                case ResourceOperation_ServiceRuntimeMode.BACKGROUND_JOB:
+                    // Queue with callback pattern (async notification)
+                    return this.executeBackgroundJob(executionContext, id_or_ids_or_filter, data);
+                case ResourceOperation_ServiceRuntimeMode.INLINE_NOT_AWAITABLE:
+                    // Fire and forget - execute async but don't wait
+                    this.executeInlineAsync(operation, executionContext, id_or_ids_or_filter, data, options);
+                    return { acknowledged: true };
+            }
+        }
+        // ============================================
+        // STEP 2: Continue with inline execution (existing logic)
+        // ============================================
+        const operationIdentifier = String(operation.operationIdentifier);
+        // CRITICAL FIX: Resolve operation variant BEFORE custom impl lookup
+        // If dataMode is specified in options, resolve the variant first so custom impl
+        // lookup can match the correct variant operation (e.g., 'context' variant)
+        const dataMode = options?.dataMode ?? DataMode.RAW;
+        const resolvedOperation = dataMode !== DataMode.RAW
+            ? this.resolveOperationVariant(operation, dataMode)
+            : operation;
+        // Correction Point 2 (post-variant): when dataMode !== RAW, the resolvedOperation
+        // may differ from the base operation. Update the context to the variant so all
+        // downstream reads (notifications, guidance, milestones, repos) use variant configs.
+        if (executionContext.operation !== resolvedOperation) {
+            executionContext = executionContext.withOperation(resolvedOperation);
+        }
+        this.logDebug('Operation variant resolution for doOperation', {
+            operationIdentifier,
+            originalVariantKey: operation.variantKey,
+            dataMode,
+            resolvedVariantKey: resolvedOperation.variantKey,
+            variantResolved: resolvedOperation !== operation
+        });
+        const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(resolvedOperation);
+        const coreOperation = ResourceOperationsUtils.getCoreResourceOperationFromOperation(resolvedOperation);
+        const generatedBulkRelationshipOperation = Resources_SharedUtils.parseRelationshipBulkOperationIdentifier(operationIdentifier);
+        if (generatedBulkRelationshipOperation) {
+            await this.featureGate.checkOperationFeatures(resolvedOperation, executionContext, data);
+            await this.enforceStepUpAuth(coreOperation, executionContext, options);
+            return this.executeGeneratedRelationshipBulkOperation(resolvedOperation, generatedBulkRelationshipOperation, executionContext, data, options);
+        }
+        // Lookup custom impl registrations with RESOLVED operation (includes variantKey if dataMode specified)
+        const customImplRegistrations = this.customImplRegistry.getRegistrationsForOperation(resolvedOperation);
+        const customImplPlaceholders = new Set(customImplRegistrations.flatMap(r => r.implementation.getPlaceholders()));
+        this.logDebug('Custom implementation check', {
+            operationIdentifier,
+            resourceIdentifier: this.resourceConfiguration.resourceIdentifier,
+            registrationCount: customImplRegistrations.length,
+            placeholders: [...customImplPlaceholders],
+            registrations: customImplRegistrations.map(r => r.debugLabel),
+            operationPathKey: ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(resolvedOperation),
+            usedResolvedOperation: resolvedOperation !== operation
+        });
+        // Fetch current object for UPDATE/DELETE operations (needed for enabledCondition and basicPrefixOperation)
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const currentObject = await this.fetchCurrentObjectForOperation(coreOperation, resourceType, id_or_ids_or_filter, executionContext);
+        const hookCurrentObject = this.resolveHookCurrentObject(coreOperation, currentObject, data);
+        // Fetch computation context for custom implementations
+        const needs = this.populationService.analyzeContextNeeds(resourceType);
+        const computationContext = await this.populationService.fetchComputationContext(resourceType, hookCurrentObject || {}, needs, executionContext);
+        const customImplUtils = {
+            logger: this.logger,
+            errorBuilder: this.errorBuilder,
+            resourcesRegistry: this.resourcesRegistry,
+            servicesRegistry: this.servicesRegistry,
+            repositoriesRegistry: this.repositoriesRegistry,
+            externalApiHandler: this.externalApiHandler,
+            platformMutualizedHandler: this.platformMutualizedHandler,
+            serverlessServicesHandler: this.serverlessServicesHandler,
+            executionContextCreator: this.executionContextCreator,
+            samlMetadataService: this.servicesRegistry.getSamlMetadataService?.(),
+            objectContext: {
+                parents: computationContext.objectContext?.parents || {},
+                children: computationContext.objectContext?.children || {}
+            },
+            initiatorUserContext: computationContext.userContext,
+            currentObject: hookCurrentObject
+        };
+        // Check feature gate — is this capability available for this scope?
+        // Runs before enabledCondition because feature availability is independent of RBAC/object state.
+        // The gate handles its own bypass logic (INTERNAL_CALL, REPOSITORY_ONLY, system resources).
+        await this.featureGate.checkOperationFeatures(resolvedOperation, executionContext, data);
+        // W7.1: Step-up authentication enforcement
+        await this.enforceStepUpAuth(coreOperation, executionContext, options);
+        // Check enabledCondition if it exists (available in both frontend and backend)
+        // Only API_CALL and API_CALL_WITH_CALLBACK variants have enabledCondition
+        if ('enabledCondition' in operation && operation.enabledCondition) {
+            this.assertBulkHookObjectContextAvailability(coreOperation, operation.isBulkOperation, operation.enabledCondition, currentObject, executionContext, operationIdentifier, 'enabledCondition');
+            // Fetch contexts only if needed
+            const { objectContext, initiatorUserContext } = await this.fetchContextsForOperationFunction(operation.enabledCondition, resourceType, currentObject, executionContext);
+            // Check if operation is enabled
+            const isEnabled = operation.enabledCondition({
+                inputDto: data,
+                currentObject: hookCurrentObject,
+                objectContext,
+                initiatorUserContext,
+                initiatorIds: executionContext.initiatorIds,
+            });
+            if (!isEnabled) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, { customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED });
+            }
+        }
+        if (customImplPlaceholders.has(ResourceOperation_CustomServiceImplementationMode.OVERRIDE_ALL)) {
+            const winner = this.customImplRegistry.resolveSingleOwner(customImplRegistrations, ResourceOperation_CustomServiceImplementationMode.OVERRIDE_ALL, this.logger);
+            if (winner) {
+                return winner.implementation.overrideAll(id_or_ids_or_filter, data, executionContext, customImplUtils);
+            }
+        }
+        // Check for custom implementation - basicPrefixOperation
+        // Use resolvedOperation to get correct variant-specific configuration
+        if ('basicPrefixOperation' in resolvedOperation && resolvedOperation.basicPrefixOperation) {
+            this.assertBulkHookObjectContextAvailability(coreOperation, 'isBulkOperation' in resolvedOperation ? resolvedOperation.isBulkOperation : false, resolvedOperation.basicPrefixOperation, currentObject, executionContext, operationIdentifier, 'basicPrefixOperation');
+            // Fetch contexts only if needed
+            const { objectContext, initiatorUserContext } = await this.fetchContextsForOperationFunction(resolvedOperation.basicPrefixOperation, resourceType, currentObject, executionContext);
+            const inputAdding = resolvedOperation.basicPrefixOperation({
+                inputDto: data,
+                currentObject: hookCurrentObject,
+                objectContext,
+                initiatorUserContext,
+                initiatorIds: executionContext.initiatorIds,
+            });
+            // Ensure inputAdding is an object before spreading
+            if (inputAdding && typeof inputAdding === 'object' && !Array.isArray(inputAdding)) {
+                data = { ...data, ...inputAdding };
+            }
+        }
+        if (customImplPlaceholders.has(ResourceOperation_CustomServiceImplementationMode.PREFIX_CORE_OPERARTIONS)) {
+            const prefixRegs = this.customImplRegistry.resolveRegistrationsForMode(customImplRegistrations, ResourceOperation_CustomServiceImplementationMode.PREFIX_CORE_OPERARTIONS, this.logger);
+            for (const reg of prefixRegs) {
+                const prefixResult = await reg.implementation.prefixCoreOperations(id_or_ids_or_filter, data, executionContext, customImplUtils);
+                if (Array.isArray(data)) {
+                    // Array inputs (CREATE_MANY): handler must return the full transformed array
+                    if (Array.isArray(prefixResult)) {
+                        data = prefixResult;
+                    }
+                    else {
+                        this.logDebug(`[CustomImpl] PREFIX handler [${reg.debugLabel}] returned non-array for array input, result ignored`);
+                    }
+                }
+                else if (prefixResult && typeof prefixResult === 'object' && !Array.isArray(prefixResult)) {
+                    data = { ...data, ...prefixResult };
+                }
+                else if (prefixResult !== undefined && prefixResult !== null) {
+                    this.logDebug(`[CustomImpl] PREFIX handler [${reg.debugLabel}] returned non-object (${typeof prefixResult}), result ignored`);
+                }
+            }
+            // PREFIX augments `data` for the core write — do NOT set `currentState`.
+            // Leaving it undefined ensures revocationTarget falls back to `currentObject`
+            // (the pre-fetched DB record), which has the identity fields needed for revocation.
+        }
+        // ── TOKEN REVOCATION (pre-operation) ────────────────────────────────
+        // Revoke existing tokens BEFORE the core operation (e.g., on DELETE).
+        // Uses currentObject (the pre-existing DB record fetched at line ~781) to resolve the relatedId.
+        // Use 'in' narrowing because ResourceConfiguration_Operation is a union — CronJob variant lacks tokenRevocation.
+        const revocationTarget = currentObject;
+        if ('tokenRevocation' in resolvedOperation && resolvedOperation.tokenRevocation && revocationTarget) {
+            await this.consumableTokenService.processTokenRevocation(resolvedOperation.tokenRevocation, revocationTarget, { organizationId: executionContext.initiatorIds?.organizationId });
+        }
+        // Handle core operations - use resolvedOperation for variant-aware execution
+        switch (coreOperation) {
+            case CoreResourceOperation.CREATE:
+                currentState = await this.create(resolvedOperation, executionContext, data, options);
+                break;
+            case CoreResourceOperation.CREATE_MANY:
+                currentState = await this.createMany(resolvedOperation, executionContext, data, options);
+                break;
+            case CoreResourceOperation.READ:
+                currentState = await this.read(resolvedOperation, executionContext, id_or_ids_or_filter, options);
+                break;
+            case CoreResourceOperation.UPDATE:
+                currentState = await this.update(resolvedOperation, executionContext, id_or_ids_or_filter, data, options);
+                break;
+            case CoreResourceOperation.UPDATE_MANY:
+                currentState = await this.updateMany(resolvedOperation, executionContext, id_or_ids_or_filter, data, options);
+                break;
+            case CoreResourceOperation.DELETE:
+                currentState = await this.delete(resolvedOperation, executionContext, id_or_ids_or_filter, options);
+                break;
+            case CoreResourceOperation.DELETE_MANY:
+                currentState = await this.deleteMany(resolvedOperation, executionContext, id_or_ids_or_filter, options);
+                break;
+            case CoreResourceOperation.LIST:
+                currentState = await this.list(resolvedOperation, executionContext, data?.filter, { page: data?.page, limit: data?.limit }, options);
+                break;
+            case CoreResourceOperation.COUNT:
+                currentState = await this.count(resolvedOperation, executionContext, data?.filter, options);
+                break;
+            case CoreResourceOperation.SEARCH:
+                currentState = await this.search(resolvedOperation, executionContext, data?.searchQuery ?? '', data?.filter, {
+                    ...(options ?? {}),
+                    searchOptions: {
+                        page: data?.page,
+                        limit: data?.limit,
+                        sort: data?.sort,
+                    },
+                });
+                break;
+            default:
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, { customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED, context: { operationIdentifier, operationPath } });
+        }
+        if (customImplPlaceholders.has(ResourceOperation_CustomServiceImplementationMode.REPLACE_CORE_OPERARTIONS)) {
+            const replaceWinner = this.customImplRegistry.resolveSingleOwner(customImplRegistrations, ResourceOperation_CustomServiceImplementationMode.REPLACE_CORE_OPERARTIONS, this.logger);
+            if (replaceWinner) {
+                currentState = await replaceWinner.implementation.replaceCoreOperations(id_or_ids_or_filter, data, executionContext, customImplUtils);
+            }
+        }
+        if (customImplPlaceholders.has(ResourceOperation_CustomServiceImplementationMode.POSTFIX_CORE_OPERARTIONS)) {
+            const postfixRegs = this.customImplRegistry.resolveRegistrationsForMode(customImplRegistrations, ResourceOperation_CustomServiceImplementationMode.POSTFIX_CORE_OPERARTIONS, this.logger);
+            for (const reg of postfixRegs) {
+                this.logDebug(`Executing postfixCoreOperations [${reg.debugLabel}]`, {
+                    operationIdentifier,
+                    currentStateKeys: currentState && typeof currentState === 'object' ? Object.keys(currentState) : typeof currentState,
+                });
+                currentState = await reg.implementation.postfixCoreOperations(id_or_ids_or_filter, currentState, executionContext, customImplUtils);
+            }
+        }
+        // ── TOKEN GENERATION (post-operation) ─────────────────────────────
+        // Generate a new token as a side-effect of a successful operation.
+        // The tokenValue is injected into notification additionalContext for email templates.
+        let tokenGenerationResult = null;
+        // Use 'in' narrowing because ResourceConfiguration_Operation is a union — CronJob variant lacks tokenGeneration.
+        if ('tokenGeneration' in resolvedOperation && resolvedOperation.tokenGeneration && currentState) {
+            tokenGenerationResult = await this.consumableTokenService.processTokenGeneration(resolvedOperation.tokenGeneration, currentState, {
+                organizationId: executionContext.initiatorIds?.organizationId,
+                userId: executionContext.initiatorIds?.userId,
+                resourceType: operation.resourceIdentifier,
+            });
+        }
+        // ── TOKEN CONSUMPTION (post-operation, MF2) ─────────────────────
+        // Consume the token ONLY after the core operation succeeded (Trap 4).
+        // Checks consumableTokenValue presence (not executionType) so it works for BOTH:
+        //   - ALTERNATIVE tokens (executionType = CONSUMABLE_TOKEN)
+        //   - ADDITIVE tokens (executionType = USER_REQUEST, token validated alongside JWT)
+        // consumptionMode logic (SINGLE_USE vs BOUNDED_REUSE) lives inside consumeToken().
+        if (executionContext.consumableTokenValue) {
+            await this.consumableTokenService.consumeToken(executionContext.consumableTokenValue);
+            executionContext.markConsumableTokenConsumed();
+        }
+        // Dispatch notifications after the main operation/postfix work and token
+        // consumption. This path is intentionally unconditional: resource-room
+        // coherence is part of the standard post-write contract even when authored
+        // notification arrays are empty, and NotificationDispatcherService already
+        // no-ops internally for empty/non-write lanes.
+        await this.dispatchNotifications(executionContext, data, currentState, tokenGenerationResult);
+        // GUIDANCE / MILESTONE / LIFECYCLE EVALUATIONS (fire-and-forget)
+        // NOTE: In-flight evaluations are lost on server restart.
+        // Self-healing: next user operation re-triggers evaluation.
+        // Acceptable trade-off for v1 — eliminates request latency impact.
+        // GUIDANCE TRIGGER EVALUATION: Fire-and-forget evaluation of guidance flows
+        // triggered by EVENT-type triggers matching this resource operation.
+        // Wrapped in setImmediate to avoid occupying the current event loop tick.
+        if (this.guidanceTriggerEvaluator) {
+            setImmediate(() => {
+                this.guidanceTriggerEvaluator.evaluateForOperation({
+                    resourceType: executionContext.operation.resourceIdentifier,
+                    operationIdentifier: executionContext.operation.operationIdentifier,
+                    userId: executionContext.initiatorIds?.userId ?? '',
+                    organizationId: executionContext.initiatorIds?.organizationId,
+                }).catch((err) => {
+                    this.logDebug('Guidance trigger evaluation failed (non-blocking)', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            });
+        }
+        // MILESTONE EVALUATION: Fire-and-forget evaluation of milestone conditions
+        // triggered by the current resource operation. Runs after guidance evaluation.
+        if (this.milestoneEvaluator) {
+            setImmediate(() => {
+                this.milestoneEvaluator.evaluateForOperation({
+                    resourceType: executionContext.operation.resourceIdentifier,
+                    operationIdentifier: executionContext.operation.operationIdentifier,
+                    userId: executionContext.initiatorIds?.userId ?? '',
+                    organizationId: executionContext.initiatorIds?.organizationId,
+                }).catch((err) => {
+                    this.logDebug('Milestone evaluation failed (non-blocking)', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            });
+        }
+        // LIFECYCLE ACTIVITY CHECK: Fire-and-forget tri-scope activity tracking + reactivation
+        if (this.lifecycleEvaluator) {
+            setImmediate(() => {
+                this.lifecycleEvaluator.onOperation({
+                    userId: executionContext.initiatorIds?.userId ?? '',
+                    organizationId: executionContext.initiatorIds?.organizationId,
+                    operationIdentifier: String(operationPath.operationIdentifier),
+                    resourceIdentifier: operationPath.resourceIdentifier,
+                    executionContext,
+                }).catch((err) => {
+                    this.logDebug('Lifecycle activity check failed (non-blocking)', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            });
+        }
+        if (customImplPlaceholders.has(ResourceOperation_CustomServiceImplementationMode.AFTER_USER_NOTIFICATIONS)) {
+            const afterNotifRegs = this.customImplRegistry.resolveRegistrationsForMode(customImplRegistrations, ResourceOperation_CustomServiceImplementationMode.AFTER_USER_NOTIFICATIONS, this.logger);
+            for (const reg of afterNotifRegs) {
+                currentState = await reg.implementation.afterUserNotifications(id_or_ids_or_filter, currentState, executionContext, customImplUtils);
+            }
+        }
+        if (customImplPlaceholders.has(ResourceOperation_CustomServiceImplementationMode.AT_THE_END)) {
+            const atEndRegs = this.customImplRegistry.resolveRegistrationsForMode(customImplRegistrations, ResourceOperation_CustomServiceImplementationMode.AT_THE_END, this.logger);
+            for (const reg of atEndRegs) {
+                currentState = await reg.implementation.atTheEnd(id_or_ids_or_filter, currentState, executionContext, customImplUtils);
+            }
+        }
+        // READ/UPDATE/DELETE can legitimately return null (document not found).
+        // Skip Zod output validation for null — callers already handle it.
+        if (currentState == null) {
+            return null;
+        }
+        // Transform output using resolved operation's internalDto
+        // Use the already-resolved operation to avoid double resolution
+        const finalResult = await this.transformOutput(executionContext, currentState, dataMode, resolvedOperation);
+        return finalResult;
+    }
+    // ================================
+    // Queue Runtime Mode Methods
+    // ================================
+    /**
+     * Execute operation via queue with RPC pattern (QUEUED / QUEUED_NOT_AWAITABLE).
+     *
+     * @param executionContext - The execution context with operation
+     * @param id_or_ids_or_filter - Resource ID(s) or filter for the operation
+     * @param data - Input data for the operation
+     * @param awaitable - If true, wait for result (QUEUED); if false, return immediately (QUEUED_NOT_AWAITABLE)
+     * @returns For awaitable: the operation result; otherwise: { jobId, status: 'queued' }
+     */
+    async executeQueued(executionContext, id_or_ids_or_filter, data, awaitable) {
+        // Extract inputId for READ/UPDATE/DELETE operations
+        const inputId = typeof id_or_ids_or_filter === 'string' ? id_or_ids_or_filter : undefined;
+        if (awaitable) {
+            // QUEUED: Wait for result via RPC
+            return this.queueService.enqueueAndWait(executionContext, data, inputId);
+        }
+        else {
+            // QUEUED_NOT_AWAITABLE: Fire and forget to queue
+            const result = await this.queueService.enqueueOperation(executionContext, data, inputId);
+            return { jobId: result.jobId, status: 'queued' };
+        }
+    }
+    /**
+     * Execute operation via queue with callback pattern (BACKGROUND_JOB).
+     * Returns immediately with job tracking info.
+     *
+     * @param executionContext - The execution context with operation
+     * @param id_or_ids_or_filter - Resource ID(s) or filter for the operation
+     * @param data - Input data for the operation
+     * @returns Job tracking info: { jobId, status: 'processing', message }
+     */
+    async executeBackgroundJob(executionContext, id_or_ids_or_filter, data) {
+        const inputId = typeof id_or_ids_or_filter === 'string' ? id_or_ids_or_filter : undefined;
+        // Enqueue with callback (async result notification)
+        const result = await this.queueService.enqueueWithCallback(executionContext, data, inputId);
+        // Return immediately with job tracking info
+        return {
+            jobId: result.jobId,
+            status: 'processing',
+            message: 'Job has been queued for background processing',
+        };
+    }
+    /**
+     * Execute operation inline but don't wait for result (INLINE_NOT_AWAITABLE).
+     * Fire and forget pattern - executes in the next tick.
+     *
+     * @param operation - The operation to execute
+     * @param executionContext - The execution context
+     * @param id_or_ids_or_filter - Resource ID(s) or filter
+     * @param data - Input data
+     * @param options - Repository options
+     */
+    executeInlineAsync(operation, executionContext, id_or_ids_or_filter, data, options) {
+        // Execute in next tick, don't await - use setImmediate for true async
+        setImmediate(async () => {
+            try {
+                // Call doOperation with isWorkerExecution to prevent infinite loop
+                await this.doOperation(operation, executionContext, id_or_ids_or_filter, data, {
+                    ...options,
+                    isWorkerExecution: true, // Prevents runtime mode check
+                });
+            }
+            catch (error) {
+                this.logger.error('Inline async operation failed', {
+                    operationPathKey: ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation),
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+            }
+        });
+    }
+    async callRepository(operation, executionContext, id_or_ids_or_filter, data, options) {
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const repository = this.repositoriesRegistry.getRepositoryOrThrow(resourceType);
+        const operationRepositoryPath = ResourcesConfig_OperationPathUtils.extractOperationRepositoryPath(operation);
+        return repository.doByPath(operationRepositoryPath, executionContext, id_or_ids_or_filter, data, options);
+    }
+    // ================================
+    // Business Logic Methods
+    // ================================
+    async create(operation, executionContext, data, options) {
+        this.logDebug('Executing create business operation');
+        // 0. Clean input data (remove mandatory discard fields)
+        const cleanedData = this.repositoryHelper.cleanInputData(data, CoreResourceOperation.CREATE);
+        this.logDebug('Data cleaned for create operation', {
+            originalKeys: typeof data === 'object' ? Object.keys(data) : 'not-object',
+            cleanedKeys: typeof cleanedData === 'object' ? Object.keys(cleanedData) : 'not-object'
+        });
+        // 1. Validate input against operation's requestDto
+        const validatedData = await this.validateAndTransformInput(executionContext, cleanedData);
+        // 2. Extract nested data if nested operations are configured
+        const resourceRelationships = this.resourceConfiguration.resourceRelationships;
+        const childRelationships = getChildDirectionRelationships(resourceRelationships);
+        const relationshipsWithNested = childRelationships.filter(rel => this.getResolvedNestedMutationConfig(rel, CoreResourceOperation.CREATE));
+        const { parentData, nestedData } = relationshipsWithNested.length > 0
+            ? this.extractNestedData(validatedData, relationshipsWithNested, CoreResourceOperation.CREATE)
+            : { parentData: validatedData, nestedData: {} };
+        // 3. Apply business validation
+        const businessValidatedData = await this.applyBusinessValidation(CoreResourceOperation.CREATE, parentData, executionContext);
+        // 3.5. Validate file fields (fail fast before resource creation)
+        // ============================================================================
+        // FILE FIELD VALIDATION (Pre-CREATE)
+        // ============================================================================
+        // This validation runs BEFORE resource creation to fail fast if file references
+        // are invalid. However, note the following limitations:
+        //
+        // 1. Files are validated by fileId lookup but scope validation (ensuring the file
+        //    belongs to the same organization/user scope) relies on organizationId in
+        //    ExecutionContext. Scope-based file segregation is not fully implemented.
+        //
+        // 2. The validation doesn't check if the user has permission to link the specific
+        //    file - only that the file exists and is in UPLOADED status.
+        //
+        // 3. For PostgreSQL resources, file metadata lookup still uses MongoDB,
+        //    which could have latency implications.
+        //
+        // See: .cursor/plans for file/storage context
+        // ============================================================================
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        if (this.fileFieldDetection.hasFileFields(resourceType)) {
+            try {
+                await this.fileOperationHandler.validateFileFieldsForCreate(businessValidatedData, resourceType, executionContext, this.buildFileRepositoryOptions(options));
+            }
+            catch (error) {
+                // File validation errors should fail the operation
+                throw error;
+            }
+        }
+        // 4. Execute pre-creation business logic
+        const enrichedData = await this.executePreOperationLogic(CoreResourceOperation.CREATE, businessValidatedData, executionContext);
+        // 5. Execute repository operation (create parent) and process nested operations
+        // ALWAYS use transaction for file operations, even without nested operations
+        // Extract organizationId early (needed for file operations and transactions)
+        const hasFileFields = this.fileFieldDetection.hasFileFields(resourceType);
+        const hasNestedOperations = relationshipsWithNested.length > 0 && Object.keys(nestedData).length > 0;
+        const persistenceAdapter = this.getResolvedPersistenceAdapter();
+        let result;
+        if (hasNestedOperations || hasFileFields) {
+            result = await this.executeResourceTransaction(executionContext, async (optionsWithTransaction) => {
+                // 1. Create resource within transaction
+                const parentResult = await this.callRepository(operation, executionContext, undefined, enrichedData, optionsWithTransaction);
+                const activeRelationships = hasNestedOperations
+                    ? this.filterRelationshipsByParent(relationshipsWithNested, parentResult)
+                    : [];
+                if (activeRelationships.length > 0) {
+                    this.assertNestedMutationAdaptersMatchCurrentResource(activeRelationships, executionContext);
+                }
+                if (persistenceAdapter === 'postgresql') {
+                    if (activeRelationships.length > 0) {
+                        await this.processNestedOperations(CoreResourceOperation.CREATE, parentResult, nestedData, {}, activeRelationships, executionContext, optionsWithTransaction);
+                    }
+                    if (hasFileFields) {
+                        const resourceId = parentResult?._id?.toString() || parentResult?.id;
+                        if (resourceId) {
+                            await this.executeFileMetadataWork(executionContext, options, async (fileOptions) => this.fileOperationHandler.processFileFieldsForCreate(enrichedData, resourceType, resourceId, executionContext, fileOptions));
+                        }
+                    }
+                }
+                else {
+                    // Mongo-backed resources still keep parent + file metadata mutations in
+                    // the same transaction context.
+                    if (hasFileFields) {
+                        const resourceId = parentResult?._id?.toString() || parentResult?.id;
+                        if (resourceId) {
+                            await this.fileOperationHandler.processFileFieldsForCreate(enrichedData, resourceType, resourceId, executionContext, optionsWithTransaction);
+                        }
+                    }
+                    if (activeRelationships.length > 0) {
+                        await this.processNestedOperations(CoreResourceOperation.CREATE, parentResult, nestedData, {}, activeRelationships, executionContext, optionsWithTransaction);
+                    }
+                }
+                return parentResult;
+            }, options);
+        }
+        else {
+            // No file fields, no nested operations - no transaction needed
+            result = await this.callRepository(operation, executionContext, undefined, enrichedData, options);
+        }
+        // 8. Execute post-creation business logic (including engine cascading)
+        const processedResult = await this.executePostOperationLogic(CoreResourceOperation.CREATE, result, executionContext);
+        this.logDebug('Create business operation completed');
+        return processedResult;
+    }
+    async createMany(operation, executionContext, data, options) {
+        this.logDebug('Executing createMany business operation');
+        const normalizedCreateManyPayload = this.normalizeCreateManyRequestPayload(data, executionContext);
+        // 0. Clean input data array (remove mandatory discard fields)
+        const cleanedDataArray = this.repositoryHelper.cleanInputDataArray(normalizedCreateManyPayload.data, CoreResourceOperation.CREATE_MANY);
+        const cleanedRequestPayload = {
+            ...normalizedCreateManyPayload,
+            data: cleanedDataArray,
+        };
+        this.logDebug('Data array cleaned for createMany operation', {
+            originalCount: normalizedCreateManyPayload.data.length,
+            cleanedCount: cleanedDataArray?.length
+        });
+        // 1. Validate input against operation's requestDto
+        const validatedData = await this.validateAndTransformInput(executionContext, cleanedRequestPayload);
+        // 2. Extract nested data per item if nested operations are configured
+        const resourceRelationships = this.resourceConfiguration.resourceRelationships;
+        const childRelationships = getChildDirectionRelationships(resourceRelationships);
+        const relationshipsWithNested = childRelationships.filter(rel => this.getResolvedNestedMutationConfig(rel, CoreResourceOperation.CREATE_MANY));
+        const validatedDataArray = this.normalizeCreateManyInput(validatedData, executionContext);
+        const { parentDataArray, nestedDataArray } = relationshipsWithNested.length > 0
+            ? this.extractNestedDataArray(validatedDataArray, relationshipsWithNested, CoreResourceOperation.CREATE_MANY, executionContext)
+            : { parentDataArray: validatedDataArray, nestedDataArray: [] };
+        // 3. Apply business validation
+        const businessValidatedData = await this.applyBusinessValidation(CoreResourceOperation.CREATE_MANY, parentDataArray, executionContext);
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const hasFileFields = this.fileFieldDetection.hasFileFields(resourceType);
+        if (hasFileFields) {
+            for (const item of businessValidatedData) {
+                await this.fileOperationHandler.validateFileFieldsForCreate(item, resourceType, executionContext, options);
+            }
+        }
+        // 4. Execute pre-creation business logic
+        const enrichedData = await this.executePreOperationLogic(CoreResourceOperation.CREATE_MANY, businessValidatedData, executionContext);
+        const hasNestedOperations = relationshipsWithNested.length > 0 &&
+            nestedDataArray.some(item => Object.keys(item).length > 0);
+        const requiresTransactionalBulkCreate = hasNestedOperations || hasFileFields;
+        let result;
+        if (requiresTransactionalBulkCreate) {
+            // Bulk create currently needs a Mongo-compatible transaction whenever it must
+            // coordinate parent writes with nested child replay or file-link side effects.
+            this.assertMongoBulkTransactionSupport(executionContext, hasNestedOperations
+                ? 'Bulk nested create transactions currently require MongoDB-backed resources'
+                : 'Bulk create file-field transactions currently require MongoDB-backed resources');
+            result = await this.mongoDBService.executeTransaction(async (ctx) => {
+                const optionsWithTransaction = { ...options, transaction: ctx };
+                const parentResults = await this.callRepository(operation, executionContext, undefined, enrichedData, optionsWithTransaction);
+                if (hasFileFields) {
+                    await this.processBulkCreateFileFields(parentResults, enrichedData, resourceType, executionContext, optionsWithTransaction);
+                }
+                await this.processBulkNestedOperations(CoreResourceOperation.CREATE_MANY, parentResults, nestedDataArray, [], relationshipsWithNested, executionContext, optionsWithTransaction);
+                return parentResults;
+            });
+        }
+        else {
+            // 5. Execute repository operation
+            result = await this.callRepository(operation, executionContext, undefined, enrichedData, options);
+        }
+        // 6. Execute post-creation business logic (including engine cascading)
+        const processedResult = await this.executePostOperationLogic(CoreResourceOperation.CREATE_MANY, result, executionContext);
+        this.logDebug('CreateMany business operation completed', { resultCount: processedResult?.length });
+        return processedResult;
+    }
+    /**
+     * Resolve operation variant based on dataMode.
+     * Maps dataMode to appropriate variantKey:
+     * - RAW -> default variant (no variantKey)
+     * - SUMMARY -> 'summary' variant (throws if not found)
+     * - CONTEXT -> 'context' variant (throws if not found)
+     *
+     * Throws error if requested variant doesn't exist (fail-fast).
+     */
+    resolveOperationVariant(operation, dataMode) {
+        // RAW mode uses default variant (provided operation)
+        if (dataMode === DataMode.RAW) {
+            return operation;
+        }
+        // Determine variantKey based on dataMode using enum-based helper
+        const variantKey = dataModeToVariantKey(dataMode);
+        // If no variant key (RAW mode), return the provided operation
+        if (!variantKey) {
+            return operation;
+        }
+        // Find variant with matching variantKey (throws if not found)
+        const resourceType = operation.resourceIdentifier;
+        const operationIdentifier = operation.operationIdentifier;
+        // Create operation path object directly
+        const variantPath = {
+            resourceIdentifier: resourceType,
+            operationIdentifier,
+            variantType: operation.variantType,
+            isOperationDefault: false,
+            variantKey,
+            isBulkOperation: false,
+        };
+        // This will throw ErrorCustomMessageReference.RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND if variant doesn't exist
+        const variantOperation = this.resourcesRegistry.getOperationFromPath(variantPath);
+        this.logDebug(`Resolved variant for ${operationIdentifier}`, { dataMode, variantKey, found: true });
+        return variantOperation;
+    }
+    async read(operation, executionContext, id_or_ids_or_filter, options) {
+        // Extract dataMode from ServiceOptions, or infer from operation's variantKey
+        // This allows direct URL calls to /resource/{id}/context to use CONTEXT mode
+        let dataMode = options?.dataMode ?? DataMode.RAW;
+        // If operation already has a variantKey (direct URL call), infer dataMode from it
+        if (operation.variantKey === OPERATION_VARIANT_KEY.CONTEXT) {
+            dataMode = DataMode.CONTEXT;
+        }
+        else if (operation.variantKey === OPERATION_VARIANT_KEY.SUMMARY) {
+            dataMode = DataMode.SUMMARY;
+        }
+        // Resolve operation variant based on dataMode
+        const resolvedOperation = this.resolveOperationVariant(operation, dataMode);
+        this.logDebug('Executing read business operation', { id_or_ids_or_filter, dataMode, variantKey: resolvedOperation.variantKey });
+        // 1. Execute repository operation with resolved variant (uses correct repositoryDto)
+        const result = await this.callRepository(resolvedOperation, executionContext, id_or_ids_or_filter, undefined, options);
+        if (!result) {
+            return null;
+        }
+        // 2. Process nested read operations if configured
+        const resourceRelationships = this.resourceConfiguration.resourceRelationships;
+        const childRelationships = getChildDirectionRelationships(resourceRelationships);
+        const relationshipsWithNestedRead = childRelationships.filter(rel => this.getResolvedNestedReadConfig(rel));
+        // Application point #2: Nested READ — filter by discriminator/condition using
+        // the read result (parent data) so we only fetch nested children for relationships
+        // that are active for this particular parent resource variant.
+        if (relationshipsWithNestedRead.length > 0) {
+            const activeReadRelationships = this.filterRelationshipsByParent(relationshipsWithNestedRead, result);
+            if (activeReadRelationships.length > 0) {
+                await this.processNestedRead(result, activeReadRelationships, executionContext, options);
+            }
+        }
+        // 3. Process based on DataMode
+        let processedResult = result;
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        if (dataMode !== DataMode.RAW) {
+            // Analyze context needs for virtual fields
+            const needs = this.populationService.analyzeContextNeeds(resourceType);
+            // Fetch computation context if needed (for virtual field computation only)
+            let computationContext = {};
+            if (needs.needsObjectContext || needs.needsUserContext) {
+                computationContext = await this.populationService.fetchComputationContext(resourceType, result, needs, executionContext);
+            }
+            // Compute virtual fields with fault tolerance
+            processedResult = await this.virtualFieldsService.computeVirtualFields(resourceType, processedResult, executionContext, {
+                faultTolerant: true,
+                includeContextDependent: needs.needsObjectContext || needs.needsUserContext,
+                objectContext: computationContext.objectContext,
+                userContext: computationContext.userContext,
+                forSummary: dataMode === DataMode.SUMMARY,
+            });
+            // Apply population based on DataMode
+            // Extract populateFiles option from ServiceOptions (default: true)
+            const populateFiles = options?.populateFiles !== false;
+            const populationOptions = { populateFiles };
+            if (dataMode === DataMode.SUMMARY) {
+                processedResult = await this.populationService.populateForSummary(resourceType, processedResult, executionContext, populationOptions, options);
+            }
+            else if (dataMode === DataMode.CONTEXT) {
+                processedResult = await this.populationService.populateForContext(resourceType, processedResult, executionContext, populationOptions, options);
+            }
+        }
+        // 3. Apply business context enrichment
+        const enrichedResult = await this.enrichBusinessContext(CoreResourceOperation.READ, processedResult, executionContext);
+        this.logDebug('Read business operation completed', { dataMode });
+        return enrichedResult;
+    }
+    async update(operation, executionContext, id_or_ids_or_filter, data, options) {
+        this.logDebug('Executing update business operation', { id_or_ids_or_filter });
+        if (!id_or_ids_or_filter) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: { operation: 'UPDATE', missingParameter: 'id_or_ids_or_filter' },
+            });
+        }
+        if (!data) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: { operation: 'UPDATE', missingParameter: 'data' },
+            });
+        }
+        // 0. Clean input data (remove mandatory discard fields)
+        const cleanedData = this.repositoryHelper.cleanInputData(data, CoreResourceOperation.UPDATE);
+        this.logDebug('Data cleaned for update operation', {
+            originalKeys: typeof data === 'object' ? Object.keys(data) : 'not-object',
+            cleanedKeys: typeof cleanedData === 'object' ? Object.keys(cleanedData) : 'not-object'
+        });
+        // 1. Validate input against operation's requestDto
+        const validatedData = await this.validateAndTransformInput(executionContext, cleanedData);
+        // 1.5. Extract nested data if nested operations are configured
+        const resourceRelationships = this.resourceConfiguration.resourceRelationships;
+        const childRelationships = getChildDirectionRelationships(resourceRelationships);
+        const relationshipsWithNested = childRelationships.filter(rel => this.getResolvedNestedMutationConfig(rel, CoreResourceOperation.UPDATE));
+        const { parentData, nestedData, deleteData } = relationshipsWithNested.length > 0
+            ? this.extractNestedDataForUpdate(validatedData, relationshipsWithNested)
+            : { parentData: validatedData, nestedData: {}, deleteData: {} };
+        // 2. Get current state - for single updates only (bulk update skips current state fetching)
+        let currentState = null;
+        if (typeof id_or_ids_or_filter === 'string') {
+            currentState = await this.fetchCurrentObjectForOperation(CoreResourceOperation.UPDATE, this.resourceConfiguration.resourceIdentifier, id_or_ids_or_filter, executionContext);
+            if (!currentState) {
+                throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_NOT_FOUND,
+                    context: { operation: 'UPDATE', id_or_ids_or_filter },
+                });
+            }
+        }
+        // 3. Apply business validation for changes
+        const businessValidatedData = await this.applyBusinessValidation(CoreResourceOperation.UPDATE, parentData, executionContext, currentState);
+        // 3.5. Validate file fields (fail fast before resource update)
+        // Note: we only reuse validateFileFieldsForCreate() when this UPDATE path does
+        // not have a persisted current state to diff against. When currentState exists,
+        // processFileFieldsForUpdate() owns validation of newly introduced file ids
+        // inside the same transaction as the parent update.
+        // ============================================================================
+        // FILE FIELD VALIDATION (Pre-UPDATE)
+        // ============================================================================
+        // Same limitations as CREATE validation apply here. Additionally:
+        //
+        // 1. Only NEW file references are validated. The old-to-new file transition
+        //    (unlinking old files, linking new ones) happens in processFileFieldsForUpdate
+        //    which runs AFTER the resource update, not during validation.
+        //
+        // 2. If a file being replaced is still referenced by other resources, this
+        //    validation doesn't check for that. File reference counting is not implemented.
+        //
+        // 3. Bulk UPDATE_MANY now has its own dedicated path: it validates explicit
+        //    file-field mutations and reloads per-parent snapshots before processing
+        //    file diffs inside the transactional bulk branch.
+        //
+        // See: .cursor/plans for file/storage context
+        // ============================================================================
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        if (this.fileFieldDetection.hasFileFields(resourceType) && !currentState) {
+            try {
+                await this.fileOperationHandler.validateFileFieldsForCreate(businessValidatedData, resourceType, executionContext, this.buildFileRepositoryOptions(options));
+            }
+            catch (error) {
+                // File validation errors should fail the operation
+                throw error;
+            }
+        }
+        // 4. Execute pre-update business logic
+        const enrichedData = await this.executePreOperationLogic(CoreResourceOperation.UPDATE, businessValidatedData, executionContext, currentState);
+        // 5. Execute repository operation (update parent) and process nested operations
+        // ALWAYS use transaction for file operations, even without nested operations
+        // Extract organizationId early (needed for file operations and transactions)
+        const hasFileFields = this.fileFieldDetection.hasFileFields(resourceType);
+        const hasNestedOperations = relationshipsWithNested.length > 0 && (Object.keys(nestedData).length > 0 || Object.keys(deleteData).length > 0);
+        // Note: File operations only for single updates (currentState is only fetched for single updates)
+        const canProcessFileFields = hasFileFields && currentState && typeof id_or_ids_or_filter === 'string';
+        const persistenceAdapter = this.getResolvedPersistenceAdapter();
+        let result;
+        if (hasNestedOperations || canProcessFileFields) {
+            result = await this.executeResourceTransaction(executionContext, async (optionsWithTransaction) => {
+                // 1. Update resource within transaction
+                const parentResult = await this.callRepository(operation, executionContext, id_or_ids_or_filter, enrichedData, optionsWithTransaction);
+                const activeRelationships = hasNestedOperations
+                    ? this.filterRelationshipsByParent(relationshipsWithNested, parentResult)
+                    : [];
+                if (activeRelationships.length > 0) {
+                    this.assertNestedMutationAdaptersMatchCurrentResource(activeRelationships, executionContext);
+                }
+                if (persistenceAdapter === 'postgresql') {
+                    if (activeRelationships.length > 0) {
+                        await this.processNestedOperations(CoreResourceOperation.UPDATE, parentResult, nestedData, deleteData, activeRelationships, executionContext, optionsWithTransaction);
+                    }
+                    if (canProcessFileFields) {
+                        const resourceId = typeof id_or_ids_or_filter === 'string'
+                            ? id_or_ids_or_filter
+                            : parentResult?._id?.toString() || parentResult?.id;
+                        if (resourceId) {
+                            await this.executeFileMetadataWork(executionContext, options, async (fileOptions) => this.fileOperationHandler.processFileFieldsForUpdate(enrichedData, currentState, resourceType, resourceId, executionContext, fileOptions));
+                        }
+                    }
+                }
+                else {
+                    // Mongo-backed resources still keep parent + file metadata mutations in
+                    // the same transaction context.
+                    if (canProcessFileFields) {
+                        const resourceId = typeof id_or_ids_or_filter === 'string'
+                            ? id_or_ids_or_filter
+                            : parentResult?._id?.toString() || parentResult?.id;
+                        if (resourceId) {
+                            await this.fileOperationHandler.processFileFieldsForUpdate(enrichedData, currentState, resourceType, resourceId, executionContext, optionsWithTransaction);
+                        }
+                    }
+                    if (activeRelationships.length > 0) {
+                        await this.processNestedOperations(CoreResourceOperation.UPDATE, parentResult, nestedData, deleteData, activeRelationships, executionContext, optionsWithTransaction);
+                    }
+                }
+                return parentResult;
+            }, options);
+        }
+        else {
+            // No file fields, no nested operations - no transaction needed
+            result = await this.callRepository(operation, executionContext, id_or_ids_or_filter, enrichedData, options);
+        }
+        // 7. Execute post-update business logic (including engine cascading)
+        const processedResult = await this.executePostOperationLogic(CoreResourceOperation.UPDATE, result, executionContext, currentState);
+        this.logDebug('Update business operation completed');
+        return processedResult;
+    }
+    async updateMany(operation, executionContext, id_or_ids_or_filter, data, options) {
+        this.logDebug('Executing updateMany business operation', { id_or_ids_or_filter });
+        if (!id_or_ids_or_filter) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: { operation: 'UPDATE_MANY', missingParameter: 'id_or_ids_or_filter' },
+            });
+        }
+        if (!data) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: { operation: 'UPDATE_MANY', missingParameter: 'data' },
+            });
+        }
+        // 0. Clean input data (remove mandatory discard fields - preserve _id for updateMany)
+        const cleanedData = this.repositoryHelper.cleanInputData(data, CoreResourceOperation.UPDATE_MANY);
+        this.logDebug('Data cleaned for updateMany operation', {
+            originalKeys: typeof data === 'object' ? Object.keys(data) : 'not-object',
+            cleanedKeys: typeof cleanedData === 'object' ? Object.keys(cleanedData) : 'not-object'
+        });
+        // 1. Validate input against operation's requestDto
+        const validatedData = await this.validateAndTransformInput(executionContext, cleanedData);
+        // 1.5. Extract nested data if nested operations are configured
+        const resourceRelationships = this.resourceConfiguration.resourceRelationships;
+        const childRelationships = getChildDirectionRelationships(resourceRelationships);
+        const relationshipsWithNested = childRelationships.filter(rel => this.getResolvedNestedMutationConfig(rel, CoreResourceOperation.UPDATE_MANY));
+        const { parentData, nestedData, deleteData } = relationshipsWithNested.length > 0
+            ? this.extractNestedDataForUpdate(validatedData, relationshipsWithNested)
+            : { parentData: validatedData, nestedData: {}, deleteData: {} };
+        // 2. Apply business validation for bulk changes (no current state fetching for bulk operations)
+        const businessValidatedData = await this.applyBusinessValidation(CoreResourceOperation.UPDATE_MANY, parentData, executionContext);
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const hasFileFields = this.fileFieldDetection.hasFileFields(resourceType);
+        const hasBulkFileMutations = hasFileFields && this.hasExplicitFileFieldMutations(resourceType, businessValidatedData);
+        if (hasBulkFileMutations) {
+            await this.fileOperationHandler.validateFileFieldsForCreate(businessValidatedData, resourceType, executionContext, options);
+        }
+        // 3. Execute pre-update business logic
+        const enrichedData = await this.executePreOperationLogic(CoreResourceOperation.UPDATE_MANY, businessValidatedData, executionContext);
+        const hasNestedOperations = relationshipsWithNested.length > 0 &&
+            (Object.keys(nestedData).length > 0 || Object.keys(deleteData).length > 0);
+        const requiresTransactionalBulkUpdate = hasNestedOperations || hasBulkFileMutations;
+        let result;
+        if (requiresTransactionalBulkUpdate) {
+            // UPDATE_MANY shares the same limitation as CREATE_MANY: once nested payloads
+            // or file-field mutations are present, the service currently relies on
+            // MongoDBService to own the outer transaction while parent updates and
+            // follow-up side effects are replayed.
+            this.assertMongoBulkTransactionSupport(executionContext, hasNestedOperations
+                ? 'Bulk nested update transactions currently require MongoDB-backed resources'
+                : 'Bulk update file-field transactions currently require MongoDB-backed resources');
+            result = await this.mongoDBService.executeTransaction(async (ctx) => {
+                const optionsWithTransaction = { ...options, transaction: ctx };
+                const currentStatesById = hasBulkFileMutations
+                    ? await this.loadBulkParentStateMap(executionContext, id_or_ids_or_filter, optionsWithTransaction)
+                    : new Map();
+                const parentResults = await this.callRepository(operation, executionContext, id_or_ids_or_filter, enrichedData, optionsWithTransaction);
+                if (Object.keys(deleteData).length > 0 && Array.isArray(parentResults) && parentResults.length > 1) {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                        context: {
+                            operation: CoreResourceOperation.UPDATE_MANY,
+                            parentResultsCount: parentResults.length,
+                            reason: 'nested delete payloads in UPDATE_MANY are only supported when the mutation targets exactly one parent resource',
+                        },
+                    });
+                }
+                if (hasBulkFileMutations) {
+                    await this.processBulkUpdateFileFields(parentResults, currentStatesById, enrichedData, resourceType, executionContext, optionsWithTransaction);
+                }
+                // Contract: UPDATE_MANY uses broadcast semantics for nested create/update payloads.
+                // The validated nestedData object is treated as one shared envelope and replayed
+                // once per matched parent result. This is intentional: bulk parent mutation +
+                // nested mutation means "apply this same nested update plan to every parent that
+                // matched the bulk selector". Nested deletes remain stricter because replaying the
+                // same child-id delete list across multiple parents is ambiguous and unsafe.
+                await this.processBulkNestedOperations(CoreResourceOperation.UPDATE_MANY, parentResults, Array.isArray(parentResults) ? parentResults.map(() => nestedData) : [], Array.isArray(parentResults) ? parentResults.map(() => deleteData) : [], relationshipsWithNested, executionContext, optionsWithTransaction);
+                return parentResults;
+            });
+        }
+        else {
+            // 4. Execute repository operation
+            result = await this.callRepository(operation, executionContext, id_or_ids_or_filter, enrichedData, options);
+        }
+        // 5. Execute post-update business logic (including engine cascading)
+        const processedResult = await this.executePostOperationLogic(CoreResourceOperation.UPDATE_MANY, result, executionContext);
+        this.logDebug('UpdateMany business operation completed', { resultCount: processedResult?.length });
+        return processedResult;
+    }
+    async delete(operation, executionContext, id_or_ids_or_filter, options) {
+        this.logDebug('Executing delete business operation', { id_or_ids_or_filter });
+        if (!id_or_ids_or_filter) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: { operation: 'DELETE', missingParameter: 'id_or_ids_or_filter' },
+            });
+        }
+        // 1. Get current state - for single deletes only (bulk delete skips current state fetching)
+        let currentState = null;
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const hasFileFields = this.fileFieldDetection.hasFileFields(resourceType);
+        // ============================================================================
+        // FILE MANAGEMENT DELETE NOTES
+        // ============================================================================
+        //
+        // Current contract:
+        // 1. Parent deletes fail closed if pre-delete file cleanup throws.
+        // 2. Mongo-backed parents still keep parent + file metadata work in one Mongo
+        //    transaction context.
+        // 3. PostgreSQL-backed parents use a best-effort split boundary: file metadata
+        //    cleanup runs through the Mongo-backed FILES seam first, then parent delete
+        //    runs inside the PostgreSQL transaction.
+        //
+        // Remaining limitations:
+        // 1. Cross-database delete is still best-effort, not one ACID transaction.
+        // 2. File storage cleanup stays outside the parent DB rollback boundary and is
+        //    intentionally owned later by the cleanup batch.
+        // 3. Lifecycle-delete coverage for child resources that own file fields is
+        //    still narrower than the direct parent delete path.
+        //
+        // NOTE: organizationId validation is intentionally NOT done here. Tenant isolation
+        // is enforced at the FilesBackendService level, not duplicated in the service handler.
+        // See: .cursor/plans for file/storage context
+        //
+        // ============================================================================
+        if (typeof id_or_ids_or_filter === 'string') {
+            currentState = await this.fetchCurrentObjectForOperation(CoreResourceOperation.DELETE, resourceType, id_or_ids_or_filter, executionContext);
+            if (!currentState) {
+                return '';
+            }
+            // 2. Check business constraints for deletion
+            await this.validateDeletionConstraints(currentState, executionContext);
+            // 3. Execute pre-deletion business logic
+            await this.executePreOperationLogic(CoreResourceOperation.DELETE, currentState, executionContext);
+            // 4. Execute repository operation plus lifecycle cascading inside the
+            // resource transaction so child-delete failures can still roll back the
+            // parent row on same-adapter paths.
+            const result = await this.executeResourceTransaction(executionContext, async (optionsWithTransaction) => {
+                if (hasFileFields) {
+                    const persistenceAdapter = this.getResolvedPersistenceAdapter();
+                    if (persistenceAdapter === 'postgresql') {
+                        await this.executeFileMetadataWork(executionContext, options, async (fileOptions) => this.fileOperationHandler.processFileFieldsForDelete(resourceType, id_or_ids_or_filter, executionContext, fileOptions));
+                    }
+                    else {
+                        await this.fileOperationHandler.processFileFieldsForDelete(resourceType, id_or_ids_or_filter, executionContext, optionsWithTransaction);
+                    }
+                }
+                const deleteResult = await this.callRepository(operation, executionContext, id_or_ids_or_filter, undefined, optionsWithTransaction);
+                await this.executeLifecycleOperations(CoreResourceOperation.DELETE, deleteResult, executionContext, currentState, optionsWithTransaction);
+                return deleteResult;
+            }, options);
+            // 5. Execute non-cascading post-deletion logic after the delete transaction commits.
+            await this.executeAdditionalPostOperationLogic(CoreResourceOperation.DELETE, result, executionContext, currentState);
+            this.logDebug('Delete business operation completed');
+            return result;
+        }
+        const deleteManyOperationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.DELETE_MANY);
+        const deleteManyOperation = this.resourcesRegistry.getOperationFromPath(deleteManyOperationPath);
+        return this.deleteMany(deleteManyOperation, executionContext, id_or_ids_or_filter, options);
+    }
+    async deleteMany(operation, executionContext, id_or_ids_or_filter, options) {
+        this.logDebug('Executing deleteMany business operation', { id_or_ids_or_filter });
+        if (!id_or_ids_or_filter) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: { operation: 'DELETE_MANY', missingParameter: 'id_or_ids_or_filter' },
+            });
+        }
+        // 1. Fetch resources BEFORE deletion so post-delete lifecycle logic can still
+        // evaluate relationship activation against real parent snapshots. The same
+        // snapshot set is also reused for pre-delete file handling.
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const hasFileFields = this.fileFieldDetection.hasFileFields(resourceType);
+        const childRelationships = getChildDirectionRelationships(this.resourceConfiguration.resourceRelationships);
+        const hasLifecycleDeleteRelationships = childRelationships
+            .some((relationship) => this.getResolvedLifecycleOnParentDelete(relationship)?.enabled === true);
+        const hasFileOwningChildRelationships = childRelationships
+            .some((relationship) => this.fileFieldDetection.hasFileFields(relationship.resourceType2));
+        const currentStates = await this.loadBulkTargetResources(executionContext, id_or_ids_or_filter, options);
+        // ============================================================================
+        // FILE MANAGEMENT DELETE_MANY NOTES
+        // ============================================================================
+        //
+        // Current contract:
+        // 1. Bulk deletes now keep lifecycle cascades inside the parent resource
+        //    transaction whenever a shared same-adapter transaction is available.
+        // 2. MongoDB-backed bulk deletes with file fields reuse that same
+        //    transaction for file metadata cleanup plus parent-row deletion.
+        // 3. Non-Mongo bulk deletes without lifecycle still fail closed before the
+        //    repository delete if any resource-level file cleanup throws.
+        // 4. File cleanup no longer inherits a foreign PostgreSQL transaction when the
+        //    parent bulk delete is called inside an outer SQL transaction.
+        //
+        // Remaining limitations:
+        // 1. PostgreSQL-backed bulk deletes still have no shared parent+file rollback
+        //    boundary because FILES remains Mongo-backed by design.
+        // 2. Fetching all resources before deletion can be expensive for large
+        //    datasets. Consider streaming/pagination for very large deletes.
+        // 3. Scope-based cleanup still relies on FilesBackendService boundaries rather
+        //    than service-layer duplication.
+        //
+        // NOTE: organizationId validation is intentionally NOT done here. Tenant isolation
+        // is enforced at the FilesBackendService level, not duplicated in the service handler.
+        //
+        // ============================================================================
+        if (this.getResolvedPersistenceAdapter() === 'postgresql'
+            && hasFileOwningChildRelationships
+            && !hasLifecycleDeleteRelationships) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'PostgreSQL bulk delete is not supported for resources with file-owning child relationships unless service-managed lifecycle delete is enabled',
+                    resourceType,
+                },
+            });
+        }
+        const processBulkDeleteFileCleanup = async (fileRepositoryOptions) => {
+            const batchSize = 100;
+            for (let i = 0; i < currentStates.length; i += batchSize) {
+                const batch = currentStates.slice(i, i + batchSize);
+                for (const resource of batch) {
+                    const resourceId = resource._id?.toString() || resource.id;
+                    if (!resourceId) {
+                        this.logger.warn('Resource missing ID in bulk delete, skipping file processing', {
+                            resource,
+                        });
+                        continue;
+                    }
+                    await this.fileOperationHandler.processFileFieldsForDelete(resourceType, resourceId, executionContext, fileRepositoryOptions);
+                }
+            }
+        };
+        const requiresTransactionalBulkDelete = hasLifecycleDeleteRelationships
+            || (hasFileFields && this.getResolvedPersistenceAdapter() === 'mongodb');
+        const processBulkDeleteWithinTransaction = async (optionsWithTransaction) => {
+            if (hasFileFields) {
+                if (optionsWithTransaction.transaction?.databaseType === 'postgresql') {
+                    await this.executeFileMetadataWork(executionContext, optionsWithTransaction, async (fileOptions) => processBulkDeleteFileCleanup(fileOptions));
+                }
+                else {
+                    await processBulkDeleteFileCleanup(optionsWithTransaction);
+                }
+            }
+            const deleteResult = await this.callRepository(operation, executionContext, id_or_ids_or_filter, undefined, optionsWithTransaction);
+            if (hasLifecycleDeleteRelationships) {
+                await this.executeLifecycleOperations(CoreResourceOperation.DELETE_MANY, deleteResult, executionContext, currentStates, optionsWithTransaction);
+            }
+            return deleteResult;
+        };
+        let result;
+        if (requiresTransactionalBulkDelete) {
+            if (hasFileFields && this.getResolvedPersistenceAdapter() === 'mongodb') {
+                this.assertMongoBulkTransactionSupport(executionContext, 'Bulk delete file-field transactions currently require MongoDB-backed resources');
+            }
+            result = await this.executeResourceTransaction(executionContext, async (optionsWithTransaction) => processBulkDeleteWithinTransaction(optionsWithTransaction), options);
+            await this.executeAdditionalPostOperationLogic(CoreResourceOperation.DELETE_MANY, result, executionContext, currentStates);
+        }
+        else {
+            if (hasFileFields) {
+                const fileRepositoryOptions = this.buildFileRepositoryOptions(options);
+                if (!this.mongoDBService) {
+                    this.logger.warn('Transaction support unavailable for file operations during DELETE_MANY, processing sequentially', {
+                        resourceType,
+                        reason: 'MongoDBService not available'
+                    });
+                }
+                // Process file fields for each resource BEFORE deletion so non-Mongo bulk
+                // paths still fail closed before the repository mutation lands.
+                await processBulkDeleteFileCleanup(fileRepositoryOptions);
+            }
+            // 2. Execute repository operation (delete resources)
+            result = await this.callRepository(operation, executionContext, id_or_ids_or_filter, undefined, options);
+            // 3. Execute post-deletion business logic (including engine cascading)
+            await this.executePostOperationLogic(CoreResourceOperation.DELETE_MANY, result, executionContext, currentStates);
+        }
+        this.logDebug('DeleteMany business operation completed', { deletedCount: result?.length });
+        return result;
+    }
+    async list(operation, executionContext, filter, pagination, options) {
+        const paginated = options?.paginated ?? false;
+        // Extract dataMode from ServiceOptions, or infer from operation's variantKey
+        // This allows direct URL calls to /resource/context to use CONTEXT mode
+        let dataMode = options?.dataMode ?? DataMode.RAW;
+        // If operation already has a variantKey (direct URL call), infer dataMode from it
+        if (operation.variantKey === OPERATION_VARIANT_KEY.CONTEXT) {
+            dataMode = DataMode.CONTEXT;
+        }
+        else if (operation.variantKey === OPERATION_VARIANT_KEY.SUMMARY) {
+            dataMode = DataMode.SUMMARY;
+        }
+        // Resolve operation variant based on dataMode
+        const resolvedOperation = this.resolveOperationVariant(operation, dataMode);
+        this.logDebug('Executing list business operation', { hasFilter: !!filter, pagination, paginated, dataMode, variantKey: resolvedOperation.variantKey, hasOptions: !!options });
+        // 1. Apply business filtering to the provided filter
+        const businessFilter = await this.applyBusinessFilter(filter || {}, executionContext);
+        // 2. Execute repository operation with resolved variant (uses correct repositoryDto) - pass filter and pagination
+        const listOptions = pagination ? { ...options, listOptions: pagination } : options;
+        const result = await this.callRepository(resolvedOperation, executionContext, businessFilter, undefined, listOptions);
+        // 3. Process based on DataMode
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const processItems = async (items) => {
+            if (dataMode === DataMode.RAW) {
+                // No population or virtual fields processing
+                return items;
+            }
+            // Analyze context needs for virtual fields
+            const needs = this.populationService.analyzeContextNeeds(resourceType);
+            const includeContextDependent = needs.needsObjectContext || needs.needsUserContext;
+            // Process each item with virtual fields
+            let processedItems = items;
+            if (includeContextDependent) {
+                // Process items with computation context (slower path)
+                processedItems = await Promise.all(items.map(async (item) => {
+                    const computationContext = await this.populationService.fetchComputationContext(resourceType, item, needs, executionContext);
+                    return this.virtualFieldsService.computeVirtualFields(resourceType, item, executionContext, {
+                        faultTolerant: true,
+                        includeContextDependent: true,
+                        objectContext: computationContext.objectContext,
+                        userContext: computationContext.userContext,
+                        forSummary: dataMode === DataMode.SUMMARY,
+                    });
+                }));
+            }
+            else {
+                // Process items without context fetching (fast path)
+                processedItems = await Promise.all(items.map((item) => this.virtualFieldsService.computeVirtualFields(resourceType, item, executionContext, {
+                    faultTolerant: true,
+                    forSummary: dataMode === DataMode.SUMMARY,
+                })));
+            }
+            // Apply population based on DataMode
+            // Extract populateFiles option from ServiceOptions (default: true)
+            const populateFiles = options?.populateFiles !== false;
+            const populationOptions = { populateFiles };
+            if (dataMode === DataMode.SUMMARY) {
+                return this.populationService.populateListForSummary(resourceType, processedItems, executionContext, populationOptions, options);
+            }
+            else if (dataMode === DataMode.CONTEXT) {
+                return this.populationService.populateListForContext(resourceType, processedItems, executionContext, populationOptions, options);
+            }
+            return processedItems;
+        };
+        // 4. Handle both raw array and paginated response from repository
+        if (paginated && result.data !== undefined) {
+            // Repository returned { data: [...], pagination: {...} }
+            const processedData = await processItems(result.data);
+            const enrichedData = await Promise.all(processedData.map((item) => this.enrichBusinessContext(CoreResourceOperation.LIST, item, executionContext)));
+            this.logDebug('List business operation completed (paginated)', { count: enrichedData.length, pagination: result.pagination, dataMode });
+            return { data: enrichedData, pagination: result.pagination };
+        }
+        else {
+            // Repository returned raw array
+            const items = Array.isArray(result) ? result : result.data || [];
+            const processedData = await processItems(items);
+            const enrichedData = await Promise.all(processedData.map((item) => this.enrichBusinessContext(CoreResourceOperation.LIST, item, executionContext)));
+            this.logDebug('List business operation completed (raw)', { count: enrichedData.length, dataMode });
+            return enrichedData;
+        }
+    }
+    async search(operation, executionContext, searchQuery, filter, options) {
+        // Extract dataMode from options (default: RAW)
+        const dataMode = options?.dataMode ?? DataMode.RAW;
+        // Resolve operation variant based on dataMode
+        const resolvedOperation = this.resolveOperationVariant(operation, dataMode);
+        this.logDebug('Executing search business operation', { searchQuery, hasFilter: !!filter, dataMode, variantKey: resolvedOperation.variantKey });
+        // 1. Apply business search logic
+        const businessFilter = await this.applyBusinessFilter(filter || {}, executionContext);
+        const enhancedSearchQuery = await this.enhanceSearchQuery(searchQuery, executionContext);
+        // 2. Execute repository operation with resolved variant - search doesn't use id_or_ids_or_filter, pass search data via data parameter
+        const searchData = { query: enhancedSearchQuery, filter: businessFilter };
+        const result = await this.callRepository(resolvedOperation, executionContext, undefined, searchData, options);
+        // 3. Enrich each item with business context
+        const enrichedData = result.data ?
+            await Promise.all(result.data.map(item => this.enrichBusinessContext(CoreResourceOperation.SEARCH, item, executionContext))) :
+            [];
+        // 4. Return result with enriched data (transformation happens in doOperation)
+        const processedResult = { ...result, data: enrichedData };
+        this.logDebug('Search business operation completed', { count: enrichedData.length });
+        return processedResult;
+    }
+    async count(operation, executionContext, filter, options) {
+        this.logDebug('Executing count business operation', { hasFilter: !!filter });
+        // 1. Apply business filtering
+        const businessFilter = await this.applyBusinessFilter(filter || {}, executionContext);
+        // 2. Execute repository operation - count doesn't use id_or_ids_or_filter, pass filter via data parameter
+        const countData = Object.keys(businessFilter).length > 0 ? { filter: businessFilter } : undefined;
+        const result = await this.callRepository(operation, executionContext, undefined, countData, options);
+        this.logDebug('Count business operation completed', { count: result.count });
+        return result;
+    }
+    // ================================
+    // DTO Validation and Transformation Methods
+    // ================================
+    /**
+     * Validate and transform input data using operation's requestDto
+     */
+    async validateAndTransformInput(executionContext, data) {
+        const operation = executionContext.operation;
+        if (!operation.requestDto) {
+            this.logDebug('No requestDto defined for operation, skipping validation');
+            return data;
+        }
+        try {
+            // Validate and transform input — use loose parse to preserve PREFIX-augmented
+            // persistence fields that are not part of the API's requestDto schema.
+            // Field-level security is enforced at the controller boundary; Mongoose strict
+            // mode strips schema-unknown fields at the repository layer.
+            const validatedData = (operation.requestDto instanceof z.ZodObject)
+                ? z.looseObject(operation.requestDto.shape).parse(data)
+                : operation.requestDto.parse(data);
+            this.logDebug('Input validation successful');
+            return validatedData;
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                    stack: error.stack,
+                    context: {
+                        operationIdentifier: operation.operationIdentifier,
+                        inputData: data,
+                        zodIssues: error.issues,
+                    }
+                });
+            }
+            throw this.errorBuilder.buildFromStandardError(error instanceof Error ? error : new Error('Unknown validation error'), executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    operationIdentifier: operation.operationIdentifier,
+                    inputData: data,
+                }
+            });
+        }
+    }
+    async transformOutput(executionContext, data, dataMode = DataMode.RAW, alreadyResolvedOperation) {
+        const operation = executionContext.operation;
+        // Use already-resolved operation if provided (to avoid double resolution)
+        // Otherwise resolve based on dataMode
+        const resolvedOperation = alreadyResolvedOperation ?? this.resolveOperationVariant(operation, dataMode);
+        this.logDebug('Transform output - using resolved operation', {
+            operationIdentifier: operation.operationIdentifier,
+            dataMode,
+            resolvedVariantKey: resolvedOperation.variantKey,
+            wasAlreadyResolved: !!alreadyResolvedOperation
+        });
+        // Use internalDto for service-layer validation
+        // internalDto MUST exist - it's built by buildAllOperationDtos() for all operations
+        if (!resolvedOperation.internalDto) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_TRANSFORMATION_FAILED,
+                context: {
+                    reason: 'Missing internalDto - this indicates a configuration error in buildAllOperationDtos()',
+                    operationIdentifier: resolvedOperation.operationIdentifier,
+                    resourceIdentifier: resolvedOperation.resourceIdentifier,
+                    variantKey: resolvedOperation.variantKey,
+                    dataMode
+                }
+            });
+        }
+        this.logDebug('Service transformOutput - resolved operation', {
+            operationIdentifier: operation.operationIdentifier,
+            dataMode,
+            resolvedVariantKey: resolvedOperation.variantKey,
+            hasInternalDto: !!resolvedOperation.internalDto
+        });
+        this.logDebug('transformOutput - before validation', {
+            dataKeys: data && typeof data === 'object' && !Array.isArray(data) ? Object.keys(data) : 'not plain object',
+            hasUserSelfProfile: data && typeof data === 'object' ? 'userSelfProfile' in data : false,
+            hasUserSelfPreference: data && typeof data === 'object' ? 'userSelfPreference' in data : false,
+            hasOrgMembers: data && typeof data === 'object' ? 'organizationMembers' in data : false
+        });
+        try {
+            // Transform and validate output using resolved operation's internalDto
+            const effectiveOperation = resolvedOperation.resourceOperationLike || resolvedOperation.operationIdentifier;
+            const isBulkArrayOperation = (effectiveOperation === CoreResourceOperation.CREATE_MANY
+                || effectiveOperation === CoreResourceOperation.UPDATE_MANY);
+            const isCollectionOperation = (effectiveOperation === CoreResourceOperation.LIST
+                || effectiveOperation === CoreResourceOperation.SEARCH);
+            const collectionItemDto = (Array.isArray(data) && isCollectionOperation)
+                ? this.extractCollectionItemDto(resolvedOperation.internalDto) ?? resolvedOperation.repositoryDto
+                : null;
+            const transformedData = (Array.isArray(data) && (isBulkArrayOperation || !!collectionItemDto))
+                ? data.map((item) => (collectionItemDto ?? resolvedOperation.internalDto).parse(item))
+                : resolvedOperation.internalDto.parse(data);
+            this.logDebug('transformOutput - after validation', {
+                dataKeys: transformedData && typeof transformedData === 'object' && !Array.isArray(transformedData) ? Object.keys(transformedData) : 'not plain object',
+                hasUserSelfProfile: transformedData && typeof transformedData === 'object' ? 'userSelfProfile' in transformedData : false,
+                hasUserSelfPreference: transformedData && typeof transformedData === 'object' ? 'userSelfPreference' in transformedData : false,
+                hasOrgMembers: transformedData && typeof transformedData === 'object' ? 'organizationMembers' in transformedData : false
+            });
+            this.logDebug('Output transformation successful');
+            return transformedData;
+        }
+        catch (error) {
+            // Output transformation failures are programming/configuration errors.
+            // The DTO doesn't match the actual output structure.
+            const transformationError = this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_TRANSFORMATION_FAILED,
+                context: {
+                    operationIdentifier: operation.operationIdentifier,
+                    resourceIdentifier: operation.resourceIdentifier,
+                    outputDataType: Array.isArray(data) ? 'array' : typeof data,
+                    outputDataLength: Array.isArray(data) ? data.length : undefined,
+                    outputDataKeys: data && typeof data === 'object' && !Array.isArray(data) ? Object.keys(data) : undefined
+                },
+                stack: error instanceof Error ? error.stack : undefined
+            });
+            throw transformationError;
+        }
+    }
+    extractCollectionItemDto(dto) {
+        if (!(dto instanceof z.ZodObject)) {
+            return null;
+        }
+        const dataField = dto.shape?.data;
+        const paginationField = dto.shape?.pagination;
+        if (!(dataField instanceof z.ZodArray) || !paginationField) {
+            return null;
+        }
+        return dataField.element;
+    }
+    /**
+     * Apply business validation
+     */
+    async applyBusinessValidation(operation, data, executionContext, currentState) {
+        // Implement business validation logic here
+        // This could include:
+        // - Business rule validation
+        // - Permission checks
+        // - Data consistency validation
+        // - Cross-resource validation
+        return data; // Default: pass through
+    }
+    /**
+     * Execute pre-operation business logic
+     */
+    async executePreOperationLogic(operation, data, executionContext, currentState) {
+        // Implement pre-operation logic here
+        // This could include:
+        // - Data enrichment
+        // - Related resource updates
+        // - Event preparation
+        // - Cache invalidation preparation
+        return data; // Default: pass through
+    }
+    /**
+     * Execute post-operation business logic using engine lifecycle operations
+     */
+    async executePostOperationLogic(operation, result, executionContext, currentState) {
+        // Get the current operation configuration
+        const operationConfig = executionContext.operation;
+        const resourceType = operationConfig.resourceIdentifier;
+        // Execute lifecycle operations for DELETE (child deletion based on childOperations config)
+        if (operation === CoreResourceOperation.DELETE || operation === CoreResourceOperation.DELETE_MANY) {
+            await this.executeLifecycleOperations(operation, result, executionContext, currentState);
+        }
+        // Execute other post-operation logic (events, notifications, etc.)
+        await this.executeAdditionalPostOperationLogic(operation, result, executionContext, currentState);
+        return result;
+    }
+    // =============================================================================
+    // NESTED OPERATIONS PROCESSING
+    // =============================================================================
+    getRelationshipFieldNameForCurrentResource(rel) {
+        return Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(rel, this.resourceConfiguration.resourceIdentifier, this.getAllResourceFieldIdentifiers()).objectFieldName;
+    }
+    getRelationshipForBulkAction(relationshipField) {
+        const currentResourceType = this.resourceConfiguration.resourceIdentifier;
+        const candidateRelationships = this.resourcesRegistry
+            .getResourcesRegistry()
+            .resourceRelationships
+            .filter((rel) => rel.isDisabled !== true
+            && (rel.resourceType1 === currentResourceType || rel.resourceType2 === currentResourceType));
+        const matches = candidateRelationships.filter((rel) => this.getRelationshipFieldNameForCurrentResource(rel) === relationshipField);
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        if (matches.length > 1) {
+            throw new Error(`Bulk relationship field "${relationshipField}" is ambiguous for resource "${this.resourceConfiguration.resourceIdentifier}".`);
+        }
+        throw new Error(`Bulk relationship field "${relationshipField}" does not map to a relationship on resource "${this.resourceConfiguration.resourceIdentifier}".`);
+    }
+    async applyReferenceSetActionMany(executionContext, id_or_ids_or_filter, relationship, relationshipField, targetId, options) {
+        const relatedReadContext = await this.executionContextCreator.createForSubCall(executionContext, relationship.resourceType1, CoreResourceOperation.READ);
+        const relatedTarget = await this.servicesRegistry.read(relationship.resourceType1, relatedReadContext, targetId, options);
+        if (!relatedTarget) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                context: {
+                    relationshipField,
+                    action: ResourceRelationshipBulkAction.SET,
+                    targetId,
+                    relatedResourceType: relationship.resourceType1,
+                },
+            });
+        }
+        if (!Resources_SharedUtils.isRelationshipActiveForParent(relationship, relatedTarget, {
+            onMissingParentResource: 'exclude',
+            onConditionError: 'throw',
+        })) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    relationshipField,
+                    action: ResourceRelationshipBulkAction.SET,
+                    targetId,
+                    reason: 'Reference relationship is inactive for the selected related resource',
+                },
+            });
+        }
+        const updateManyContext = await this.executionContextCreator.createForSubCall(executionContext, this.resourceConfiguration.resourceIdentifier, CoreResourceOperation.UPDATE_MANY);
+        const fkField = this.getFKFieldForRelationship(relationship);
+        const updatedTargets = await this.servicesRegistry.updateMany(this.resourceConfiguration.resourceIdentifier, updateManyContext, id_or_ids_or_filter, { [fkField]: targetId }, options);
+        return {
+            relationshipField,
+            action: ResourceRelationshipBulkAction.SET,
+            matchedTargetIds: this.extractResourceIds(updatedTargets),
+            affectedCount: Array.isArray(updatedTargets) ? updatedTargets.length : 0,
+            results: Array.isArray(updatedTargets) ? updatedTargets : [],
+        };
+    }
+    async applyReferenceClearActionMany(executionContext, id_or_ids_or_filter, relationship, relationshipField, options) {
+        if (relationship.parentResourceRequirement === ResourceParentResourceRequirement.MANDATORY) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    relationshipField,
+                    action: ResourceRelationshipBulkAction.CLEAR,
+                    reason: 'Cannot clear a mandatory parent relationship through bulk reference mutation',
+                },
+            });
+        }
+        const updateManyContext = await this.executionContextCreator.createForSubCall(executionContext, this.resourceConfiguration.resourceIdentifier, CoreResourceOperation.UPDATE_MANY);
+        const fkField = this.getFKFieldForRelationship(relationship);
+        const updatedTargets = await this.servicesRegistry.updateMany(this.resourceConfiguration.resourceIdentifier, updateManyContext, id_or_ids_or_filter, { [fkField]: null }, options);
+        return {
+            relationshipField,
+            action: ResourceRelationshipBulkAction.CLEAR,
+            matchedTargetIds: this.extractResourceIds(updatedTargets),
+            affectedCount: Array.isArray(updatedTargets) ? updatedTargets.length : 0,
+            results: Array.isArray(updatedTargets) ? updatedTargets : [],
+        };
+    }
+    async applyCompositionCreateActionMany(executionContext, id_or_ids_or_filter, relationship, relationshipField, data, options) {
+        const fkField = this.getFKFieldForRelationship(relationship);
+        if (fkField in data) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    relationshipField,
+                    action: ResourceRelationshipBulkAction.CREATE,
+                    fkField,
+                    reason: 'Bulk composition create payload must not provide the relationship foreign key explicitly',
+                },
+            });
+        }
+        const targetResources = await this.loadBulkTargetResources(executionContext, id_or_ids_or_filter, options);
+        const createdChildren = [];
+        const matchedTargetIds = [];
+        for (const targetResource of targetResources) {
+            if (!Resources_SharedUtils.isRelationshipActiveForParent(relationship, targetResource, {
+                onMissingParentResource: 'exclude',
+                onConditionError: 'throw',
+            })) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action: ResourceRelationshipBulkAction.CREATE,
+                        reason: 'Composition relationship is inactive for one of the matched target resources',
+                        targetResourceId: this.getResourceIdValue(targetResource),
+                    },
+                });
+            }
+            const targetResourceId = this.getResourceIdValue(targetResource);
+            if (!targetResourceId) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action: ResourceRelationshipBulkAction.CREATE,
+                        reason: 'Bulk composition create requires every matched target resource to expose an id',
+                    },
+                });
+            }
+            const createContext = await this.executionContextCreator.createForSubCall(executionContext, relationship.resourceType2, CoreResourceOperation.CREATE);
+            const createdChild = await this.servicesRegistry.create(relationship.resourceType2, createContext, {
+                ...data,
+                [fkField]: targetResourceId,
+            }, options);
+            matchedTargetIds.push(targetResourceId);
+            createdChildren.push(createdChild);
+        }
+        return {
+            relationshipField,
+            action: ResourceRelationshipBulkAction.CREATE,
+            matchedTargetIds,
+            affectedCount: createdChildren.length,
+            results: createdChildren,
+        };
+    }
+    async applyAssociationLinkActionMany(executionContext, id_or_ids_or_filter, relationship, relationshipField, peerIds, options) {
+        const { jointResourceType, peerResourceType, currentForeignKeyField, peerForeignKeyField, } = this.resolveAssociationBulkIdentity(relationship);
+        const uniquePeerIds = [...new Set(peerIds)];
+        await this.assertAssociationPeerResourcesExist(executionContext, relationshipField, peerResourceType, uniquePeerIds, ResourceRelationshipBulkAction.LINK, options);
+        const targetResources = await this.loadBulkTargetResources(executionContext, id_or_ids_or_filter, options);
+        const matchedTargetIds = [];
+        for (const targetResource of targetResources) {
+            if (!Resources_SharedUtils.isRelationshipActiveForParent(relationship, targetResource, {
+                onMissingParentResource: 'exclude',
+                onConditionError: 'throw',
+            })) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action: ResourceRelationshipBulkAction.LINK,
+                        reason: 'Association relationship is inactive for one of the matched target resources',
+                        targetResourceId: this.getResourceIdValue(targetResource),
+                    },
+                });
+            }
+            const targetResourceId = this.getResourceIdValue(targetResource);
+            if (!targetResourceId) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action: ResourceRelationshipBulkAction.LINK,
+                        reason: 'Bulk association link requires every matched target resource to expose an id',
+                    },
+                });
+            }
+            matchedTargetIds.push(targetResourceId);
+        }
+        const existingRows = matchedTargetIds.length > 0
+            ? await this.listAssociationRowsByCurrentAndPeerIds(executionContext, jointResourceType, currentForeignKeyField, matchedTargetIds, peerForeignKeyField, uniquePeerIds, options)
+            : [];
+        const existingKeys = new Set(existingRows
+            .map((row) => {
+            const currentId = row?.[currentForeignKeyField];
+            const peerId = row?.[peerForeignKeyField];
+            return typeof currentId === 'string' && typeof peerId === 'string'
+                ? `${currentId}::${peerId}`
+                : undefined;
+        })
+            .filter((key) => Boolean(key)));
+        const createdRows = [];
+        for (const targetResourceId of matchedTargetIds) {
+            for (const peerId of uniquePeerIds) {
+                const key = `${targetResourceId}::${peerId}`;
+                if (existingKeys.has(key)) {
+                    continue;
+                }
+                const createContext = await this.executionContextCreator.createForSubCall(executionContext, jointResourceType, CoreResourceOperation.CREATE);
+                const createdRow = await this.servicesRegistry.create(jointResourceType, createContext, {
+                    [currentForeignKeyField]: targetResourceId,
+                    [peerForeignKeyField]: peerId,
+                }, options);
+                createdRows.push(createdRow);
+            }
+        }
+        return {
+            relationshipField,
+            action: ResourceRelationshipBulkAction.LINK,
+            matchedTargetIds,
+            affectedCount: createdRows.length,
+            results: createdRows,
+        };
+    }
+    async applyAssociationUnlinkActionMany(executionContext, id_or_ids_or_filter, relationship, relationshipField, peerIds, options) {
+        const { jointResourceType, currentForeignKeyField, peerForeignKeyField, } = this.resolveAssociationBulkIdentity(relationship);
+        const uniquePeerIds = [...new Set(peerIds)];
+        const targetResources = await this.loadBulkTargetResources(executionContext, id_or_ids_or_filter, options);
+        const matchedTargetIds = [];
+        for (const targetResource of targetResources) {
+            if (!Resources_SharedUtils.isRelationshipActiveForParent(relationship, targetResource, {
+                onMissingParentResource: 'exclude',
+                onConditionError: 'throw',
+            })) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action: ResourceRelationshipBulkAction.UNLINK,
+                        reason: 'Association relationship is inactive for one of the matched target resources',
+                        targetResourceId: this.getResourceIdValue(targetResource),
+                    },
+                });
+            }
+            const targetResourceId = this.getResourceIdValue(targetResource);
+            if (!targetResourceId) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action: ResourceRelationshipBulkAction.UNLINK,
+                        reason: 'Bulk association unlink requires every matched target resource to expose an id',
+                    },
+                });
+            }
+            matchedTargetIds.push(targetResourceId);
+        }
+        if (matchedTargetIds.length === 0 || uniquePeerIds.length === 0) {
+            return {
+                relationshipField,
+                action: ResourceRelationshipBulkAction.UNLINK,
+                matchedTargetIds,
+                affectedCount: 0,
+                results: [],
+            };
+        }
+        const existingRows = await this.listAssociationRowsByCurrentAndPeerIds(executionContext, jointResourceType, currentForeignKeyField, matchedTargetIds, peerForeignKeyField, uniquePeerIds, options);
+        const existingRowIds = existingRows
+            .map((row) => this.getResourceIdValue(row))
+            .filter((rowId) => Boolean(rowId));
+        if (existingRowIds.length !== existingRows.length) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                context: {
+                    relationshipField,
+                    action: ResourceRelationshipBulkAction.UNLINK,
+                    reason: 'Bulk association unlink requires every junction row to expose an id',
+                },
+            });
+        }
+        if (existingRowIds.length === 0) {
+            return {
+                relationshipField,
+                action: ResourceRelationshipBulkAction.UNLINK,
+                matchedTargetIds,
+                affectedCount: 0,
+                results: [],
+            };
+        }
+        const deleteManyContext = await this.executionContextCreator.createForSubCall(executionContext, jointResourceType, CoreResourceOperation.DELETE_MANY);
+        const deletedRowIds = await this.servicesRegistry.deleteMany(jointResourceType, deleteManyContext, existingRowIds, options);
+        return {
+            relationshipField,
+            action: ResourceRelationshipBulkAction.UNLINK,
+            matchedTargetIds,
+            affectedCount: Array.isArray(deletedRowIds) ? deletedRowIds.length : 0,
+            results: Array.isArray(deletedRowIds) ? deletedRowIds : [],
+        };
+    }
+    async applyAssociationReplaceActionMany(executionContext, id_or_ids_or_filter, relationship, relationshipField, peerIds, options) {
+        const { jointResourceType, peerResourceType, currentForeignKeyField, peerForeignKeyField, } = this.resolveAssociationBulkIdentity(relationship);
+        const uniquePeerIds = [...new Set(peerIds)];
+        await this.assertAssociationPeerResourcesExist(executionContext, relationshipField, peerResourceType, uniquePeerIds, ResourceRelationshipBulkAction.REPLACE, options);
+        const matchedTargetIds = await this.resolveActiveAssociationBulkTargetIds(executionContext, id_or_ids_or_filter, relationship, relationshipField, ResourceRelationshipBulkAction.REPLACE, options);
+        if (matchedTargetIds.length === 0) {
+            return {
+                relationshipField,
+                action: ResourceRelationshipBulkAction.REPLACE,
+                matchedTargetIds,
+                affectedCount: 0,
+                results: [],
+            };
+        }
+        const existingRows = await this.listAssociationRowsByCurrentIds(executionContext, jointResourceType, currentForeignKeyField, matchedTargetIds, options);
+        const desiredKeys = new Set();
+        for (const targetResourceId of matchedTargetIds) {
+            for (const peerId of uniquePeerIds) {
+                desiredKeys.add(`${targetResourceId}::${peerId}`);
+            }
+        }
+        const rowsToDelete = existingRows.filter((row) => {
+            const currentId = row?.[currentForeignKeyField];
+            const peerId = row?.[peerForeignKeyField];
+            if (typeof currentId !== 'string' || typeof peerId !== 'string') {
+                return false;
+            }
+            return !desiredKeys.has(`${currentId}::${peerId}`);
+        });
+        const deleteRowIds = rowsToDelete
+            .map((row) => this.getResourceIdValue(row))
+            .filter((rowId) => Boolean(rowId));
+        if (deleteRowIds.length !== rowsToDelete.length) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                context: {
+                    relationshipField,
+                    action: ResourceRelationshipBulkAction.REPLACE,
+                    reason: 'Bulk association replace requires every junction row to expose an id',
+                },
+            });
+        }
+        const existingKeys = new Set(existingRows
+            .map((row) => {
+            const currentId = row?.[currentForeignKeyField];
+            const peerId = row?.[peerForeignKeyField];
+            return typeof currentId === 'string' && typeof peerId === 'string'
+                ? `${currentId}::${peerId}`
+                : undefined;
+        })
+            .filter((key) => Boolean(key)));
+        const createdRows = [];
+        for (const targetResourceId of matchedTargetIds) {
+            for (const peerId of uniquePeerIds) {
+                const key = `${targetResourceId}::${peerId}`;
+                if (existingKeys.has(key)) {
+                    continue;
+                }
+                const createContext = await this.executionContextCreator.createForSubCall(executionContext, jointResourceType, CoreResourceOperation.CREATE);
+                const createdRow = await this.servicesRegistry.create(jointResourceType, createContext, {
+                    [currentForeignKeyField]: targetResourceId,
+                    [peerForeignKeyField]: peerId,
+                }, options);
+                createdRows.push(createdRow);
+            }
+        }
+        if (deleteRowIds.length > 0) {
+            const deleteManyContext = await this.executionContextCreator.createForSubCall(executionContext, jointResourceType, CoreResourceOperation.DELETE_MANY);
+            await this.servicesRegistry.deleteMany(jointResourceType, deleteManyContext, deleteRowIds, options);
+        }
+        return {
+            relationshipField,
+            action: ResourceRelationshipBulkAction.REPLACE,
+            matchedTargetIds,
+            affectedCount: createdRows.length + deleteRowIds.length,
+            results: [
+                ...createdRows,
+                ...deleteRowIds,
+            ],
+        };
+    }
+    /**
+     * Extract nested field name from relationship using the shared
+     * relationship-object identity rule.
+     */
+    getNestedFieldName(rel) {
+        return Resources_SharedUtils.resolveRelationshipObjectIdentity(rel, rel.resourceType2, rel.cardinality2, this.getAllResourceFieldIdentifiers()).objectFieldName;
+    }
+    getAllResourceFieldIdentifiers() {
+        const registry = this.resourcesRegistry.getResourcesRegistry();
+        const allResourceFieldIdentifiers = {};
+        for (const resourceType of Object.keys(registry.resourceConfigurations)) {
+            const fieldIdentifier = registry.resourceConfigurations[resourceType]?.resourceFieldIdentifier;
+            if (typeof fieldIdentifier === 'string' && fieldIdentifier.length > 0) {
+                allResourceFieldIdentifiers[resourceType] = fieldIdentifier;
+            }
+        }
+        return allResourceFieldIdentifiers;
+    }
+    extractResourceIds(resources) {
+        if (!Array.isArray(resources)) {
+            return [];
+        }
+        return resources
+            .map((resource) => this.getResourceIdValue(resource))
+            .filter((resourceId) => Boolean(resourceId));
+    }
+    /**
+     * Get FK field name for a relationship.
+     * Delegates to the registry so backend services do not improvise their own
+     * FK fallback semantics.
+     */
+    getFKFieldForRelationship(rel) {
+        return this.resourcesRegistry.resolveForeignKeyField({
+            resourceType1: rel.resourceType1,
+            foreignKeyField: rel.foreignKeyField,
+        });
+    }
+    async resolveActiveAssociationBulkTargetIds(executionContext, id_or_ids_or_filter, relationship, relationshipField, action, options) {
+        const targetResources = await this.loadBulkTargetResources(executionContext, id_or_ids_or_filter, options);
+        const matchedTargetIds = [];
+        for (const targetResource of targetResources) {
+            if (!Resources_SharedUtils.isRelationshipActiveForParent(relationship, targetResource, {
+                onMissingParentResource: 'exclude',
+                onConditionError: 'throw',
+            })) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action,
+                        reason: 'Association relationship is inactive for one of the matched target resources',
+                        targetResourceId: this.getResourceIdValue(targetResource),
+                    },
+                });
+            }
+            const targetResourceId = this.getResourceIdValue(targetResource);
+            if (!targetResourceId) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action,
+                        reason: 'Bulk association mutation requires every matched target resource to expose an id',
+                    },
+                });
+            }
+            matchedTargetIds.push(targetResourceId);
+        }
+        return matchedTargetIds;
+    }
+    resolveAssociationBulkIdentity(relationship) {
+        const currentResourceType = this.resourceConfiguration.resourceIdentifier;
+        const perspective = Resources_SharedUtils.getRelationshipPerspectiveForResource(relationship, currentResourceType);
+        if (!perspective || !relationship.jointResourceType) {
+            throw new Error('Association bulk actions require a non-self association relationship with jointResourceType');
+        }
+        const currentForeignKeyField = this.resourcesRegistry.resolveForeignKeyField({
+            resourceType1: currentResourceType,
+            foreignKeyField: perspective === 'resourceType1' ? relationship.foreignKeyField : undefined,
+        });
+        const peerResourceType = perspective === 'resourceType1'
+            ? relationship.resourceType2
+            : relationship.resourceType1;
+        const peerForeignKeyField = this.resourcesRegistry.resolveForeignKeyField({
+            resourceType1: peerResourceType,
+            foreignKeyField: perspective === 'resourceType2' ? relationship.foreignKeyField : undefined,
+        });
+        return {
+            jointResourceType: relationship.jointResourceType,
+            peerResourceType,
+            currentForeignKeyField,
+            peerForeignKeyField,
+        };
+    }
+    async assertAssociationPeerResourcesExist(executionContext, relationshipField, peerResourceType, peerIds, action = ResourceRelationshipBulkAction.LINK, options) {
+        for (const peerId of peerIds) {
+            const readContext = await this.executionContextCreator.createForSubCall(executionContext, peerResourceType, CoreResourceOperation.READ);
+            const peerResource = await this.servicesRegistry.read(peerResourceType, readContext, peerId, options);
+            if (!peerResource) {
+                throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        relationshipField,
+                        action,
+                        peerId,
+                        peerResourceType,
+                    },
+                });
+            }
+        }
+    }
+    async listAssociationRowsByCurrentAndPeerIds(executionContext, jointResourceType, currentForeignKeyField, currentIds, peerForeignKeyField, peerIds, options) {
+        const existingRows = [];
+        const seenRowIds = new Set();
+        for (const currentId of currentIds) {
+            for (const peerId of peerIds) {
+                const listContext = await this.executionContextCreator.createForSubCall(executionContext, jointResourceType, CoreResourceOperation.LIST);
+                const result = await this.servicesRegistry.list(jointResourceType, listContext, {
+                    [currentForeignKeyField]: currentId,
+                    [peerForeignKeyField]: peerId,
+                }, undefined, options);
+                const rows = Array.isArray(result) ? result : result.data;
+                for (const row of rows) {
+                    const rowId = this.getResourceIdValue(row);
+                    if (rowId) {
+                        if (seenRowIds.has(rowId)) {
+                            continue;
+                        }
+                        seenRowIds.add(rowId);
+                    }
+                    existingRows.push(row);
+                }
+            }
+        }
+        return existingRows;
+    }
+    async listAssociationRowsByCurrentIds(executionContext, jointResourceType, currentForeignKeyField, currentIds, options) {
+        const existingRows = [];
+        const seenRowIds = new Set();
+        for (const currentId of currentIds) {
+            const listContext = await this.executionContextCreator.createForSubCall(executionContext, jointResourceType, CoreResourceOperation.LIST);
+            const result = await this.servicesRegistry.list(jointResourceType, listContext, {
+                [currentForeignKeyField]: currentId,
+            }, undefined, options);
+            const rows = Array.isArray(result) ? result : result.data;
+            for (const row of rows) {
+                const rowId = this.getResourceIdValue(row);
+                if (rowId) {
+                    if (seenRowIds.has(rowId)) {
+                        continue;
+                    }
+                    seenRowIds.add(rowId);
+                }
+                existingRows.push(row);
+            }
+        }
+        return existingRows;
+    }
+    getResolvedNestedMutationConfig(rel, operation) {
+        return Resources_SharedUtils.resolveRelationshipNestedMutationConfig(rel, operation);
+    }
+    getResolvedNestedReadConfig(rel) {
+        return Resources_SharedUtils.resolveRelationshipNestedReadConfig(rel);
+    }
+    getResolvedLifecycleOnParentDelete(rel) {
+        return Resources_SharedUtils.resolveRelationshipLifecycleOnParentDeleteConfig(rel);
+    }
+    /**
+     * Extract nested data from request, separating parent data from nested child data.
+     * Returns { parentData, nestedData } where nestedData is keyed by field name.
+     */
+    extractNestedData(data, relationships, operation) {
+        const parentData = { ...data };
+        const nestedData = {};
+        for (const rel of relationships) {
+            const nestedConfig = this.getResolvedNestedMutationConfig(rel, operation);
+            if (!nestedConfig)
+                continue;
+            const fieldName = this.getNestedFieldName(rel);
+            if (fieldName in parentData) {
+                nestedData[fieldName] = parentData[fieldName];
+                delete parentData[fieldName];
+            }
+        }
+        return { parentData, nestedData };
+    }
+    /**
+     * Bulk variant of extractNestedData().
+     * Applies the same nested field split to each item independently.
+     */
+    extractNestedDataArray(dataArray, relationships, operation, executionContext) {
+        if (!Array.isArray(dataArray)) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                context: {
+                    operation,
+                    reason: 'Bulk create expects an array of parent payloads after validation',
+                    receivedType: typeof dataArray,
+                }
+            });
+        }
+        const parentDataArray = [];
+        const nestedDataArray = [];
+        for (const item of dataArray) {
+            const { parentData, nestedData } = this.extractNestedData(item, relationships, operation);
+            parentDataArray.push(parentData);
+            nestedDataArray.push(nestedData);
+        }
+        return { parentDataArray, nestedDataArray };
+    }
+    /**
+     * Normalize bulk create payloads to the array shape expected by the service layer.
+     * Some callers may already pass the raw array, while others may use a `{ data: [] }`
+     * envelope before controller-level extraction.
+     */
+    normalizeCreateManyInput(validatedData, executionContext) {
+        if (Array.isArray(validatedData)) {
+            return validatedData;
+        }
+        if (validatedData && typeof validatedData === 'object' && Array.isArray(validatedData.data)) {
+            return validatedData.data;
+        }
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+            context: {
+                operation: CoreResourceOperation.CREATE_MANY,
+                reason: 'Bulk create expects either an array payload or an object with a data array',
+            }
+        });
+    }
+    /**
+     * Normalize the CREATE_MANY request shape so service callers may pass either
+     * a raw array or the controller-facing `{ data: [...] }` envelope.
+     */
+    normalizeCreateManyRequestPayload(data, executionContext) {
+        if (Array.isArray(data)) {
+            return { data };
+        }
+        if (data && typeof data === 'object' && Array.isArray(data.data)) {
+            return { ...data, data: data.data };
+        }
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+            context: {
+                operation: CoreResourceOperation.CREATE_MANY,
+                reason: 'Bulk create expects either an array payload or an object with a data array',
+            }
+        });
+    }
+    getResolvedPersistenceAdapter() {
+        return this.resourceConfiguration.persistenceAdapter
+            ?? this.appConfigService.config.database.defaultAdapter
+            ?? DEFAULT_PERSISTENCE_ADAPTER;
+    }
+    getResolvedPersistenceAdapterForResource(resourceType) {
+        const resourceConfiguration = this.resourcesRegistry.getResourceConfiguration(resourceType);
+        return resourceConfiguration.persistenceAdapter
+            ?? this.appConfigService.config.database.defaultAdapter
+            ?? DEFAULT_PERSISTENCE_ADAPTER;
+    }
+    /**
+     * The FILES resource is currently the Mongo-backed coordination seam for file
+     * metadata. PostgreSQL-backed resources can coordinate with it, but they cannot
+     * silently inherit the parent SQL transaction.
+     */
+    assertMongoBackedFilesResource(executionContext, message) {
+        const filesPersistenceAdapter = this.getResolvedPersistenceAdapterForResource(CoreResourceType.FILES);
+        if (filesPersistenceAdapter !== 'mongodb') {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message,
+                    resourceType: this.resourceConfiguration.resourceIdentifier,
+                    filesPersistenceAdapter,
+                },
+            });
+        }
+        if (!this.mongoDBService) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: `${message} (MongoDBService is not available)`,
+                    resourceType: this.resourceConfiguration.resourceIdentifier,
+                    filesPersistenceAdapter,
+                },
+            });
+        }
+    }
+    getResourceDatabaseService(executionContext) {
+        const persistenceAdapter = this.getResolvedPersistenceAdapter();
+        if (persistenceAdapter === 'postgresql') {
+            if (!this.postgreSQLDatabaseService) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        message: 'PostgreSQLDatabaseService is required for PostgreSQL-backed resource transactions',
+                        resourceType: this.resourceConfiguration.resourceIdentifier,
+                        persistenceAdapter,
+                    },
+                });
+            }
+            return this.postgreSQLDatabaseService;
+        }
+        if (!this.mongoDBService) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'MongoDBService is required for MongoDB-backed resource transactions',
+                    resourceType: this.resourceConfiguration.resourceIdentifier,
+                    persistenceAdapter,
+                },
+            });
+        }
+        return this.mongoDBService;
+    }
+    buildFileRepositoryOptions(options) {
+        if (!options?.transaction || options.transaction.databaseType === 'mongodb') {
+            return options;
+        }
+        const { transaction: _ignoredTransaction, ...fileOptions } = options;
+        return fileOptions;
+    }
+    buildRepositoryOptionsForResource(resourceType, executionContext, options) {
+        if (!options?.transaction) {
+            return options;
+        }
+        const expectedDatabaseType = this.getResolvedPersistenceAdapterForResource(resourceType);
+        if (options.transaction.databaseType === expectedDatabaseType) {
+            return options;
+        }
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+                message: 'Lifecycle deletes across mixed persistence adapters are not supported within a shared resource transaction',
+                parentResourceType: this.resourceConfiguration.resourceIdentifier,
+                childResourceType: resourceType,
+                parentPersistenceAdapter: options.transaction.databaseType,
+                childPersistenceAdapter: expectedDatabaseType,
+            },
+        });
+    }
+    async executeResourceTransaction(executionContext, callback, options) {
+        const databaseService = this.getResourceDatabaseService(executionContext);
+        return databaseService.executeTransaction(async (transactionContext) => callback({
+            ...options,
+            transaction: transactionContext,
+        }), {
+            nestedBehavior: 'reuse',
+        });
+    }
+    /**
+     * Route file metadata work through the FILES resource adapter instead of
+     * leaking the current resource transaction into a different repository backend.
+     */
+    async executeFileMetadataWork(executionContext, options, callback) {
+        this.assertMongoBackedFilesResource(executionContext, 'File metadata operations currently require MongoDB-backed FILES resources');
+        const fileOptions = this.buildFileRepositoryOptions(options);
+        if (fileOptions?.transaction?.databaseType === 'mongodb') {
+            return callback(fileOptions);
+        }
+        return this.mongoDBService.executeTransaction(async (transactionContext) => callback({
+            ...fileOptions,
+            transaction: transactionContext,
+        }), {
+            nestedBehavior: 'reuse',
+        });
+    }
+    assertNestedMutationAdaptersMatchCurrentResource(relationships, executionContext) {
+        const currentPersistenceAdapter = this.getResolvedPersistenceAdapter();
+        const incompatibleNestedResourceTypes = relationships
+            .map((relationship) => relationship.resourceType2)
+            .filter((childResourceType) => {
+            return this.getResolvedPersistenceAdapterForResource(childResourceType) !== currentPersistenceAdapter;
+        });
+        if (incompatibleNestedResourceTypes.length === 0) {
+            return;
+        }
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+                message: 'Nested mutations across mixed persistence adapters are not supported within a shared resource transaction',
+                resourceType: this.resourceConfiguration.resourceIdentifier,
+                persistenceAdapter: currentPersistenceAdapter,
+                incompatibleNestedResourceTypes,
+            },
+        });
+    }
+    assertMongoBulkTransactionSupport(executionContext, message) {
+        const persistenceAdapter = this.getResolvedPersistenceAdapter();
+        if (persistenceAdapter !== 'mongodb') {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message,
+                    resourceType: this.resourceConfiguration.resourceIdentifier,
+                    persistenceAdapter,
+                },
+            });
+        }
+        if (!this.mongoDBService) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: `${message} (MongoDBService is not available)`,
+                    resourceType: this.resourceConfiguration.resourceIdentifier,
+                    persistenceAdapter,
+                },
+            });
+        }
+    }
+    getResourceIdValue(resource) {
+        if (!resource)
+            return null;
+        const rawId = resource._id ?? resource.id;
+        if (typeof rawId === 'string' && rawId.length > 0) {
+            return rawId;
+        }
+        if (rawId && typeof rawId.toString === 'function') {
+            const stringified = rawId.toString();
+            return stringified.length > 0 ? stringified : null;
+        }
+        return null;
+    }
+    hasExplicitFileFieldMutations(resourceType, data) {
+        const fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+        return fileFields.some(({ fieldName }) => hasExplicitCanonicalFieldMutation(data, fieldName));
+    }
+    async processBulkCreateFileFields(parentResults, parentDataArray, resourceType, executionContext, options) {
+        if (!Array.isArray(parentResults) || parentResults.length !== parentDataArray.length) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                context: {
+                    operation: CoreResourceOperation.CREATE_MANY,
+                    reason: 'Bulk create file processing requires one parent result per input payload',
+                    parentResultsCount: Array.isArray(parentResults) ? parentResults.length : 'not-array',
+                    payloadCount: parentDataArray.length,
+                },
+            });
+        }
+        for (let index = 0; index < parentResults.length; index += 1) {
+            const parentResult = parentResults[index];
+            const resourceId = this.getResourceIdValue(parentResult);
+            if (!resourceId) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        operation: CoreResourceOperation.CREATE_MANY,
+                        reason: 'Bulk create file processing requires each created parent to expose an id',
+                        index,
+                    },
+                });
+            }
+            await this.fileOperationHandler.processFileFieldsForCreate(parentDataArray[index], resourceType, resourceId, executionContext, options);
+        }
+    }
+    async loadBulkParentStateMap(executionContext, id_or_ids_or_filter, options) {
+        const currentStates = await this.loadBulkTargetResources(executionContext, id_or_ids_or_filter, options);
+        return new Map((Array.isArray(currentStates) ? currentStates : [])
+            .map((item) => [this.getResourceIdValue(item), item])
+            .filter((entry) => !!entry[0]));
+    }
+    async loadBulkTargetResources(executionContext, id_or_ids_or_filter, options) {
+        if (!id_or_ids_or_filter) {
+            return [];
+        }
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        const repository = this.repositoriesRegistry.getRepositoryOrThrow(resourceType);
+        if (typeof id_or_ids_or_filter === 'string') {
+            const currentState = await repository.read(executionContext, id_or_ids_or_filter, options);
+            return currentState ? [currentState] : [];
+        }
+        const snapshotCandidates = await repository.list(executionContext, id_or_ids_or_filter, options);
+        const snapshotIds = (Array.isArray(snapshotCandidates) ? snapshotCandidates : [])
+            .map((item) => this.getResourceIdValue(item))
+            .filter((id) => !!id);
+        const currentStates = await Promise.all(snapshotIds.map((id) => repository.read(executionContext, id, options)));
+        return (Array.isArray(currentStates) ? currentStates : []).filter(Boolean);
+    }
+    async processBulkUpdateFileFields(parentResults, currentStatesById, parentPatch, resourceType, executionContext, options) {
+        if (!Array.isArray(parentResults)) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                context: {
+                    operation: CoreResourceOperation.UPDATE_MANY,
+                    reason: 'Bulk update file processing requires an array of parent results',
+                },
+            });
+        }
+        for (const parentResult of parentResults) {
+            const resourceId = this.getResourceIdValue(parentResult);
+            if (!resourceId) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        operation: CoreResourceOperation.UPDATE_MANY,
+                        reason: 'Bulk update file processing requires each updated parent to expose an id',
+                    },
+                });
+            }
+            const currentState = currentStatesById.get(resourceId);
+            if (!currentState) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                    context: {
+                        operation: CoreResourceOperation.UPDATE_MANY,
+                        reason: 'Bulk update file processing requires a pre-update snapshot for every updated parent',
+                        resourceId,
+                    },
+                });
+            }
+            await this.fileOperationHandler.processFileFieldsForUpdate(parentPatch, currentState, resourceType, resourceId, executionContext, options);
+        }
+    }
+    /**
+     * Extract nested data for UPDATE operations, including delete arrays.
+     * Returns { parentData, nestedData, deleteData }.
+     */
+    extractNestedDataForUpdate(data, relationships) {
+        const parentData = { ...data };
+        const nestedData = {};
+        const deleteData = {};
+        for (const rel of relationships) {
+            const nestedConfig = this.getResolvedNestedMutationConfig(rel, CoreResourceOperation.UPDATE);
+            if (!nestedConfig)
+                continue;
+            const fieldName = this.getNestedFieldName(rel);
+            const deleteFieldName = `_${fieldName}ToDelete`;
+            if (fieldName in parentData) {
+                nestedData[fieldName] = parentData[fieldName];
+                delete parentData[fieldName];
+            }
+            if (nestedConfig.allowDelete && deleteFieldName in parentData) {
+                deleteData[fieldName] = parentData[deleteFieldName] || [];
+                delete parentData[deleteFieldName];
+            }
+        }
+        return { parentData, nestedData, deleteData };
+    }
+    /**
+     * Filter child relationships by evaluating discriminator/condition against the parent resource.
+     *
+     * This is the central runtime gate for conditional relationships in the services layer.
+     * It ensures that nested CRUD operations and lifecycle cascades only apply to child
+     * relationships whose conditions match the current parent resource's data.
+     *
+     * ## Evaluation Logic
+     *
+     * For each relationship:
+     * 1. If `discriminator` is present: check `String(parentResource[discriminatorField])`
+     *    against `values`. If no match → exclude.
+     * 2. If `condition` is present: call `condition(parentResource)`.
+     *    If it returns false → exclude.
+     * 3. Relationships without discriminator or condition always pass through.
+     *
+     * When both discriminator and condition are present, AND semantics apply —
+     * discriminator is checked first, then condition.
+     *
+     * ## Application Points
+     *
+     * This method is called at 4 critical points in the CRUD lifecycle:
+     *
+     * 1. **Nested CREATE** (inside transaction): After creating the parent, filters
+     *    child relationships using `parentResult` before processing nested creates.
+     *    This prevents creating children for relationships that don't apply to this parent.
+     *
+     * 2. **Nested READ**: After reading the parent, filters child relationships using
+     *    the read `result` before fetching nested children for the response.
+     *
+     * 3. **Nested UPDATE** (inside transaction): After updating the parent, filters
+     *    child relationships using `parentResult` before processing nested updates.
+     *
+     * 4. **Lifecycle DELETE**: Filters lifecycle relationships using pre-delete parent
+     *    snapshots to determine which children should cascade-delete.
+     *    - `DELETE`: uses the single `currentState`
+     *    - `DELETE_MANY`: uses the pre-delete snapshot set loaded for the matched parents,
+     *      so discriminator/condition gating still fails closed per deleted parent
+     *
+     * ## String Coercion
+     *
+     * Uses the shared relationship-activation utility in `saas-models`, preserving
+     * the same `String()` coercion semantics used across backend and frontend
+     * runtime evaluation.
+     *
+     * @param relationships - Child relationships to filter
+     * @param parentResource - The parent resource's data to evaluate conditions against
+     * @returns Relationships whose discriminator/condition match the parent (or have no conditions)
+     */
+    filterRelationshipsByParent(relationships, parentResource) {
+        return Resources_SharedUtils.filterRelationshipsActiveForParent(relationships, parentResource, {
+            onConditionError: 'throw',
+        });
+    }
+    /**
+     * Process nested operations for CREATE/UPDATE.
+     * Handles creating/updating/deleting children and attaching them to parent result.
+     */
+    async processNestedOperations(operation, parentResult, nestedData, deleteData, relationships, executionContext, options) {
+        const parentId = parentResult._id || parentResult.id;
+        if (!parentId) {
+            this.logDebug('No parent ID found, skipping nested operations');
+            return;
+        }
+        const relationshipsByFieldName = new Map(relationships.map(rel => [this.getNestedFieldName(rel), rel]));
+        // Process deletions first (for UPDATE only)
+        if (operation === CoreResourceOperation.UPDATE || operation === CoreResourceOperation.UPDATE_MANY) {
+            for (const [fieldName, idsToDelete] of Object.entries(deleteData)) {
+                if (!idsToDelete || idsToDelete.length === 0)
+                    continue;
+                const rel = relationshipsByFieldName.get(fieldName);
+                if (!rel) {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                        context: {
+                            parentResourceType: this.resourceConfiguration.resourceIdentifier,
+                            fieldName,
+                            operation,
+                            reason: 'nested delete field is not active for the current parent state or does not map to an allowed relationship',
+                        },
+                    });
+                }
+                const nestedConfig = this.getResolvedNestedMutationConfig(rel, CoreResourceOperation.UPDATE);
+                if (!nestedConfig?.allowDelete) {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                        context: {
+                            parentResourceType: this.resourceConfiguration.resourceIdentifier,
+                            childResourceType: rel.resourceType2,
+                            fieldName,
+                            operation,
+                            reason: 'nested deletes are not enabled for this relationship',
+                        },
+                    });
+                }
+                this.logDebug('Deleting nested children', { fieldName, count: idsToDelete.length });
+                for (const childId of idsToDelete) {
+                    // Build relationship context for child DELETE
+                    const relationshipContext = {
+                        resourceType: this.resourceConfiguration.resourceIdentifier,
+                        relationshipField: this.getFKFieldForRelationship(rel),
+                        resourceId: parentId
+                    };
+                    // Create sub-call context with correct operation
+                    const subContext = await this.executionContextCreator.createForSubCall(executionContext, rel.resourceType2, CoreResourceOperation.DELETE, undefined, childId, relationshipContext);
+                    // Authorization: DELETE operation on child resource is checked via enabledCondition
+                    // in doByExecutionContext when servicesRegistry.delete is called
+                    await this.servicesRegistry.delete(rel.resourceType2, subContext, childId, options);
+                }
+            }
+        }
+        // Process creates and updates
+        for (const [fieldName, items] of Object.entries(nestedData)) {
+            if (!items)
+                continue;
+            const rel = relationshipsByFieldName.get(fieldName);
+            if (!rel) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        parentResourceType: this.resourceConfiguration.resourceIdentifier,
+                        fieldName,
+                        operation,
+                        reason: 'nested field is not active for the current parent state or does not map to an allowed relationship',
+                    },
+                });
+            }
+            const nestedConfig = this.getResolvedNestedMutationConfig(rel, operation);
+            if (!nestedConfig) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        parentResourceType: this.resourceConfiguration.resourceIdentifier,
+                        childResourceType: rel.resourceType2,
+                        fieldName,
+                        operation,
+                        reason: 'nested operations are not enabled for this relationship',
+                    },
+                });
+            }
+            const fkField = this.getFKFieldForRelationship(rel);
+            const processedChildren = [];
+            const itemsArray = Array.isArray(items) ? items : [items];
+            const isCreateOperation = operation === CoreResourceOperation.CREATE || operation === CoreResourceOperation.CREATE_MANY;
+            const isUpdateOperation = operation === CoreResourceOperation.UPDATE || operation === CoreResourceOperation.UPDATE_MANY;
+            for (const item of itemsArray) {
+                const hasId = !!(item._id || item.id);
+                if (hasId && nestedConfig.allowUpdate && isUpdateOperation) {
+                    // Update existing child
+                    const childId = item._id || item.id;
+                    const childData = { ...item, [fkField]: parentId };
+                    delete childData._id; // Remove _id from update data
+                    // Build relationship context for child UPDATE
+                    const relationshipContext = {
+                        resourceType: this.resourceConfiguration.resourceIdentifier,
+                        relationshipField: fkField,
+                        resourceId: parentId
+                    };
+                    // Create sub-call context with correct operation
+                    const subContext = await this.executionContextCreator.createForSubCall(executionContext, rel.resourceType2, CoreResourceOperation.UPDATE, undefined, childId, relationshipContext);
+                    // Authorization: UPDATE operation on child resource is checked via enabledCondition
+                    // in doByExecutionContext when servicesRegistry.update is called
+                    const updatedChild = await this.servicesRegistry.update(rel.resourceType2, subContext, childId, childData, options);
+                    if (updatedChild) {
+                        processedChildren.push(updatedChild);
+                    }
+                }
+                else if (!hasId && nestedConfig.allowCreate) {
+                    // Create new child
+                    const childData = { ...item, [fkField]: parentId };
+                    // Build relationship context for child CREATE
+                    const relationshipContext = {
+                        resourceType: this.resourceConfiguration.resourceIdentifier,
+                        relationshipField: fkField,
+                        resourceId: parentId
+                    };
+                    // Create sub-call context with correct operation (no resourceId for CREATE)
+                    const subContext = await this.executionContextCreator.createForSubCall(executionContext, rel.resourceType2, CoreResourceOperation.CREATE, undefined, undefined, // No resourceId for CREATE - it doesn't exist yet
+                    relationshipContext);
+                    // Authorization: CREATE operation on child resource is checked via enabledCondition
+                    // in doByExecutionContext when servicesRegistry.create is called
+                    const createdChild = await this.servicesRegistry.create(rel.resourceType2, subContext, childData, options);
+                    if (createdChild) {
+                        processedChildren.push(createdChild);
+                    }
+                }
+                else {
+                    const action = hasId ? 'update_existing' : 'create_new';
+                    const reason = hasId
+                        ? (isCreateOperation
+                            ? 'nested create payloads cannot reference existing child ids'
+                            : 'nested updates are not enabled for this relationship')
+                        : 'nested creates are not enabled for this relationship';
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                        context: {
+                            parentResourceType: this.resourceConfiguration.resourceIdentifier,
+                            childResourceType: rel.resourceType2,
+                            fieldName,
+                            action,
+                            reason,
+                            operation,
+                        },
+                    });
+                }
+            }
+            // Attach children to parent result — 1:1 gets single/null, 1:N gets array
+            if (isOneToOneCardinality(rel.cardinality2)) {
+                parentResult[fieldName] = processedChildren[0] || null;
+            }
+            else {
+                parentResult[fieldName] = processedChildren;
+            }
+        }
+    }
+    /**
+     * Bulk variant of processNestedOperations().
+     * Reuses the single-parent orchestration path for each returned parent result,
+     * preserving sub-call execution contexts and relationship activation checks.
+     *
+     * Contract:
+     * - CREATE_MANY expects per-row nested payloads and receives one nested envelope
+     *   per created parent result.
+     * - UPDATE_MANY currently uses broadcast semantics for nested create/update payloads:
+     *   the same validated nested envelope is replayed for every matched parent result.
+     * - UPDATE_MANY nested deletes are intentionally more restrictive and are rejected
+     *   earlier when a shared delete payload would target multiple parents ambiguously.
+     */
+    async processBulkNestedOperations(operation, parentResults, nestedDataArray, deleteDataArray, relationships, executionContext, options) {
+        if (!Array.isArray(parentResults) || parentResults.length === 0) {
+            return;
+        }
+        if (parentResults.length !== nestedDataArray.length) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+                context: {
+                    operation,
+                    parentResultsCount: parentResults.length,
+                    nestedPayloadCount: nestedDataArray.length,
+                    reason: 'bulk nested orchestration requires one nested payload envelope per parent result',
+                },
+            });
+        }
+        for (let index = 0; index < parentResults.length; index += 1) {
+            const parentResult = parentResults[index];
+            const nestedData = nestedDataArray[index] ?? {};
+            const deleteData = deleteDataArray[index] ?? {};
+            if (!parentResult || (!Object.keys(nestedData).length && !Object.keys(deleteData).length)) {
+                continue;
+            }
+            const activeRelationships = this.filterRelationshipsByParent(relationships, parentResult);
+            if (activeRelationships.length === 0) {
+                continue;
+            }
+            await this.processNestedOperations(operation, parentResult, nestedData, deleteData, activeRelationships, executionContext, options);
+        }
+    }
+    /**
+     * Process nested read operations - include children in READ response.
+     */
+    async processNestedRead(parentResult, relationships, executionContext, options) {
+        if (!parentResult)
+            return;
+        const parentId = parentResult._id || parentResult.id;
+        if (!parentId)
+            return;
+        for (const rel of relationships) {
+            const readConfig = this.getResolvedNestedReadConfig(rel);
+            if (!readConfig)
+                continue;
+            const fieldName = this.getNestedFieldName(rel);
+            const fkField = this.getFKFieldForRelationship(rel);
+            // Build filter to find children
+            const filter = { [fkField]: parentId };
+            // Apply maxItems limit if specified
+            const limit = readConfig.maxItems;
+            // Build relationship context for child nested fetch
+            const relationshipContext = {
+                resourceType: this.resourceConfiguration.resourceIdentifier,
+                relationshipField: fkField,
+                resourceId: parentId
+            };
+            const childrenOptions = { ...options };
+            childrenOptions.dataMode = readConfig.dataMode;
+            // Attach to parent result — 1:1 gets single/null, 1:N gets array
+            if (isOneToOneCardinality(rel.cardinality2)) {
+                const subContext = await this.executionContextCreator.createForSubCall(executionContext, rel.resourceType2, CoreResourceOperation.READ, { dataMode: readConfig.dataMode }, undefined, relationshipContext);
+                const child = await this.servicesRegistry.read(rel.resourceType2, subContext, filter, childrenOptions);
+                parentResult[fieldName] = child ?? null;
+            }
+            else {
+                const subContext = await this.executionContextCreator.createForSubCall(executionContext, rel.resourceType2, CoreResourceOperation.LIST, { dataMode: readConfig.dataMode }, undefined, relationshipContext);
+                const children = await this.servicesRegistry.list(rel.resourceType2, subContext, filter, limit ? { limit } : undefined, childrenOptions);
+                parentResult[fieldName] = Array.isArray(children) ? children : [];
+            }
+        }
+    }
+    /**
+     * Execute lifecycle operations for child resources based on relationship configuration.
+     * Handles onParentDelete cascade for all child relationships with lifecycle.onParentDelete.enabled = true.
+     */
+    async executeLifecycleOperations(operation, result, executionContext, currentState, options) {
+        // Only handle DELETE operations for lifecycle
+        if (operation !== CoreResourceOperation.DELETE && operation !== CoreResourceOperation.DELETE_MANY) {
+            return;
+        }
+        const resourceRelationships = this.resourceConfiguration.resourceRelationships;
+        const childRelationships = getChildDirectionRelationships(resourceRelationships);
+        // Find relationships with lifecycle.onParentDelete.enabled = true
+        let lifecycleRelationships = childRelationships.filter(rel => this.getResolvedLifecycleOnParentDelete(rel)?.enabled === true);
+        if (lifecycleRelationships.length === 0) {
+            return;
+        }
+        // Application point #4: Lifecycle DELETE — filter lifecycle relationships using
+        // the available pre-delete parent snapshots so cascades only apply where the
+        // relationship is active for the concrete parent variant being deleted.
+        if (operation === CoreResourceOperation.DELETE && currentState) {
+            lifecycleRelationships = this.filterRelationshipsByParent(lifecycleRelationships, currentState);
+            if (lifecycleRelationships.length === 0) {
+                return;
+            }
+        }
+        this.logDebug('Executing lifecycle operations for delete', {
+            operation,
+            relationshipsCount: lifecycleRelationships.length,
+            resourceType: this.resourceConfiguration.resourceIdentifier
+        });
+        // Get parent ID(s) from result
+        const parentIds = operation === CoreResourceOperation.DELETE_MANY
+            ? (Array.isArray(result)
+                ? result.map((item) => (typeof item === 'string' ? item : this.getResourceIdValue(item))).filter(Boolean)
+                : result?.deletedIds || [])
+            : (() => {
+                if (typeof result === 'string') {
+                    return [result];
+                }
+                const resultId = result?._id ?? result?.id;
+                if (resultId) {
+                    return [String(resultId)];
+                }
+                const currentStateId = currentState ? this.getResourceIdValue(currentState) : undefined;
+                return currentStateId ? [currentStateId] : [];
+            })();
+        if (parentIds.length === 0) {
+            this.logDebug('No parent IDs found in result, skipping lifecycle operations');
+            return;
+        }
+        // Process each child relationship with lifecycle config
+        for (const relationship of lifecycleRelationships) {
+            const lifecycleConfig = this.getResolvedLifecycleOnParentDelete(relationship);
+            const mode = lifecycleConfig.mode || ChildLifecycleMode.IMMEDIATE;
+            const maxDepth = lifecycleConfig.maxDepth || 1;
+            let relationshipParentIds = parentIds;
+            if (operation === CoreResourceOperation.DELETE_MANY && Array.isArray(currentState)) {
+                const currentStatesById = new Map(currentState
+                    .map((item) => [this.getResourceIdValue(item), item])
+                    .filter((entry) => !!entry[0]));
+                relationshipParentIds = parentIds.filter((parentId) => {
+                    const parentSnapshot = currentStatesById.get(parentId);
+                    if (!parentSnapshot) {
+                        return false;
+                    }
+                    return this.filterRelationshipsByParent([relationship], parentSnapshot).length > 0;
+                });
+            }
+            if (relationshipParentIds.length === 0) {
+                continue;
+            }
+            if (mode === ChildLifecycleMode.IMMEDIATE) {
+                await this.deleteChildrenImmediate(relationship, relationshipParentIds, executionContext, 0, // currentDepth
+                maxDepth, new Set(), // visitedResourceIds for circular reference detection
+                options);
+            }
+            else if (mode === ChildLifecycleMode.LAZY) {
+                await this.queueChildDeletion(relationship, relationshipParentIds, executionContext);
+            }
+        }
+    }
+    /**
+     * Delete child resources immediately (synchronous, within same transaction).
+     *
+     * Includes depth tracking and circular reference detection to prevent infinite loops.
+     *
+     * @param relationship - The relationship configuration
+     * @param parentIds - IDs of parent resources being deleted
+     * @param executionContext - Execution context for the operation
+     * @param currentDepth - Current recursion depth (starts at 0)
+     * @param maxDepth - Maximum allowed depth (from lifecycle config, default 1)
+     * @param visitedResourceIds - Set of visited resource IDs to prevent circular references
+     */
+    async deleteChildrenImmediate(relationship, parentIds, executionContext, currentDepth = 0, maxDepth = 1, visitedResourceIds = new Set(), options) {
+        // Guard 1: Depth limit check
+        if (currentDepth >= maxDepth) {
+            this.logDebug('Max depth reached, stopping lifecycle delete', {
+                currentDepth,
+                maxDepth,
+                childResourceType: relationship.resourceType2
+            });
+            return;
+        }
+        const childResourceType = relationship.resourceType2;
+        const fkField = this.getFKFieldForRelationship(relationship);
+        this.logDebug('Deleting children immediately', {
+            childResourceType,
+            fkField,
+            parentIdsCount: parentIds.length,
+            currentDepth,
+            maxDepth
+        });
+        try {
+            // Get child service from registry
+            const childService = this.servicesRegistry.getService(childResourceType);
+            if (!childService) {
+                this.logDebug('Child service not found, skipping lifecycle delete', { childResourceType });
+                return;
+            }
+            // Build filter to find children with parent FK in parentIds.
+            // Child discovery must stay adapter-neutral: use repository operations
+            // rather than reaching into Mongo-specific model internals.
+            const filter = { [fkField]: { $in: parentIds } };
+            const childRepositoryOptions = this.buildRepositoryOptionsForResource(childResourceType, executionContext, options);
+            // Find children first (we need their IDs for recursive lifecycle)
+            const childRepository = this.repositoriesRegistry.getRepository(childResourceType);
+            let children = [];
+            if (isOneToOneCardinality(relationship.cardinality2)) {
+                if (!childRepository.supportsOperation(CoreResourceOperation.READ)) {
+                    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                        context: {
+                            message: `Lifecycle delete requires READ support on child resource "${childResourceType}" ` +
+                                `to discover 1:1 dependents before deletion.`,
+                            childResourceType,
+                            fkField,
+                            relationshipField: this.getNestedFieldName(relationship),
+                        },
+                    });
+                }
+                const child = await childRepository.read(executionContext, filter, childRepositoryOptions);
+                children = child ? [child] : [];
+            }
+            else {
+                if (!childRepository.supportsOperation(CoreResourceOperation.LIST)) {
+                    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                        context: {
+                            message: `Lifecycle delete requires LIST support on child resource "${childResourceType}" ` +
+                                `to discover dependent children before deletion.`,
+                            childResourceType,
+                            fkField,
+                            relationshipField: this.getNestedFieldName(relationship),
+                        },
+                    });
+                }
+                const listedChildren = await childRepository.list(executionContext, filter, childRepositoryOptions);
+                children = Array.isArray(listedChildren) ? listedChildren : [];
+            }
+            if (!children || children.length === 0) {
+                this.logDebug('No children found to delete', { childResourceType, fkField });
+                return;
+            }
+            const childIds = children.map((c) => c._id?.toString() || c.id);
+            const childSnapshotsById = new Map();
+            for (const child of children) {
+                const childId = child?._id?.toString() || child?.id;
+                if (childId) {
+                    childSnapshotsById.set(childId, child);
+                }
+            }
+            // Guard 2: Circular reference detection
+            // Check if any child ID was already visited in this deletion chain.
+            // This prevents infinite loops when deleting resources that reference each other.
+            // Note: This detects same-chain circular refs (A→B→A). Cross-branch circular refs
+            // (A→B→C→A where C is deleted via different parent) are rare and would require
+            // more complex graph traversal to detect fully.
+            const newChildIds = [];
+            for (const childId of childIds) {
+                const resourceKey = `${childResourceType}:${childId}`;
+                if (visitedResourceIds.has(resourceKey)) {
+                    this.logDebug('Circular reference detected, skipping child', {
+                        childResourceType,
+                        childId,
+                        resourceKey,
+                        note: 'This resource was already processed in this deletion chain, preventing infinite loop'
+                    });
+                    continue;
+                }
+                visitedResourceIds.add(resourceKey);
+                newChildIds.push(childId);
+            }
+            if (newChildIds.length === 0) {
+                this.logDebug('All children skipped due to circular references', { childResourceType });
+                return;
+            }
+            this.logDebug('Found children to delete', {
+                childResourceType,
+                count: newChildIds.length,
+                skipped: childIds.length - newChildIds.length
+            });
+            const supportsDeleteMany = childRepository.supportsOperation(CoreResourceOperation.DELETE_MANY);
+            const supportsDelete = childRepository.supportsOperation(CoreResourceOperation.DELETE);
+            if (!supportsDeleteMany && !supportsDelete) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        message: `Lifecycle delete requires DELETE_MANY or DELETE support on child resource "${childResourceType}".`,
+                        childResourceType,
+                        relationshipField: this.getNestedFieldName(relationship),
+                    },
+                });
+            }
+            // Recursively delete grandchildren before mutating the current child level.
+            // This keeps deeper failures from leaving the current child rows already
+            // deleted while descendants remain behind.
+            // Activation must still be evaluated against each deleted child snapshot before we recurse;
+            // otherwise discriminator/condition-gated lifecycle relationships would over-delete deeper
+            // descendants just because the FK chain exists.
+            if (currentDepth + 1 < maxDepth) {
+                const childConfig = this.resourcesRegistry.tryGetResourceConfiguration(childResourceType);
+                if (childConfig?.resourceRelationships) {
+                    const grandchildRelationships = getChildDirectionRelationships(childConfig.resourceRelationships).filter((rel) => this.getResolvedLifecycleOnParentDelete(rel)?.enabled === true);
+                    for (const grandchildRel of grandchildRelationships) {
+                        const grandchildLifecycleConfig = this.getResolvedLifecycleOnParentDelete(grandchildRel);
+                        const grandchildMaxDepth = grandchildLifecycleConfig.maxDepth || 1;
+                        const activeGrandchildParentIds = newChildIds.filter(childId => {
+                            const childSnapshot = childSnapshotsById.get(childId);
+                            if (!childSnapshot) {
+                                return false;
+                            }
+                            return this.filterRelationshipsByParent([grandchildRel], childSnapshot).length > 0;
+                        });
+                        if (activeGrandchildParentIds.length === 0) {
+                            continue;
+                        }
+                        // Recursively delete grandchildren
+                        await this.deleteChildrenImmediate(grandchildRel, activeGrandchildParentIds, executionContext, currentDepth + 1, Math.min(maxDepth, grandchildMaxDepth + currentDepth + 1), // Respect both limits
+                        visitedResourceIds, // Share visited set to prevent cross-branch circular refs
+                        options);
+                    }
+                }
+            }
+            // Keep lifecycle depth ownership in this method, but do not bypass the
+            // file cleanup contract. Child resources with file fields must run through
+            // the same file-delete orchestration before their repository delete lands.
+            if (this.fileFieldDetection.hasFileFields(childResourceType)) {
+                for (const childId of newChildIds) {
+                    if (childRepositoryOptions?.transaction?.databaseType === 'postgresql') {
+                        await this.executeFileMetadataWork(executionContext, childRepositoryOptions, async (fileOptions) => this.fileOperationHandler.processFileFieldsForDelete(childResourceType, childId, executionContext, fileOptions));
+                    }
+                    else {
+                        await this.fileOperationHandler.processFileFieldsForDelete(childResourceType, childId, executionContext, childRepositoryOptions);
+                    }
+                }
+            }
+            // The repository call must still stay adapter-agnostic: pass the generic
+            // ids array contract instead of a Mongo-specific `{ _id: { $in: ... } }`
+            // filter shape.
+            if (supportsDeleteMany) {
+                await childRepository.deleteMany(executionContext, newChildIds, childRepositoryOptions);
+            }
+            else if (supportsDelete) {
+                for (const childId of newChildIds) {
+                    await childRepository.delete(executionContext, childId, childRepositoryOptions);
+                }
+            }
+            this.logDebug('Children deleted successfully', {
+                childResourceType,
+                deletedCount: newChildIds.length
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to delete children in lifecycle operation', {
+                childResourceType,
+                fkField,
+                currentDepth,
+                error: error instanceof Error ? error.message : 'Unknown error'
+            });
+            // Re-throw to ensure parent delete fails if child delete fails
+            throw error;
+        }
+    }
+    /**
+     * Queue child resources for async deletion (eventual consistency).
+     *
+     * LAZY mode provides eventual consistency by queuing deletion operations
+     * for asynchronous processing. This improves performance for bulk deletions
+     * but requires a queue system to be implemented.
+     *
+     * Current implementation: Placeholder that throws NOT_IMPLEMENTED error.
+     *
+     * Future implementation (Phase 6.1-6.2):
+     * When the queue system is implemented, this method should:
+     * 1. Get the DELETE operation for the child resource type
+     * 2. Use `operation.internalDto` for serializing queue payloads
+     *    - `internalDto` includes `isBackendOnly` fields needed for backend-to-backend communication
+     *    - Date coercion is already applied in `internalDto`
+     * 3. Serialize resource data using `operation.internalDto.parse()` for validation
+     * 4. Enqueue job with validated payload
+     *
+     * Example (when queue system is ready):
+     * ```typescript
+     * const childResourceConfig = this.resourcesRegistry.resourceConfigurations[relationship.resourceType2];
+     * const deleteOperation = childResourceConfig.operations.find(
+     *   op => op.operationIdentifier === CoreResourceOperation.DELETE
+     * );
+     * if (!deleteOperation?.internalDto) {
+     *   throw new Error('DELETE operation or internalDto not found');
+     * }
+     *
+     * // Validate and serialize using internalDto
+     * const queuePayload = {
+     *   resourceType: relationship.resourceType2,
+     *   operationIdentifier: CoreResourceOperation.DELETE,
+     *   data: deleteOperation.internalDto.parse({ _id: childId, ...otherFields }),
+     *   executionContext: { ... },
+     * };
+     *
+     * await this.queueService.enqueueResourceOperation(deleteOperation, queuePayload.data, executionContext);
+     * ```
+     *
+     * @see Phase 6.1 - Use internalDto for Queue Payloads
+     * @see Phase 6.2 - Validate Queue Payloads Against internalDto
+     */
+    async queueChildDeletion(relationship, parentIds, executionContext) {
+        throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_FAILED,
+            context: {
+                message: 'LAZY cascade mode requires queue system integration. Queue system implementation pending. See Phase 6.1-6.2 for implementation details.',
+                relationship: relationship.resourceType2,
+                parentIds,
+            },
+        });
+    }
+    /**
+     * Execute additional post-operation logic (non-cascading)
+     */
+    async executeAdditionalPostOperationLogic(operation, result, executionContext, currentState) {
+        this.logDebug('Executing additional post-operation logic', { operation });
+        // Dispatch post-operation hooks registered on this resource type
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        await this.servicesRegistry.dispatchPostOperationHooks(resourceType, operation, result, executionContext);
+    }
+    /**
+     * Enrich business context
+     */
+    async enrichBusinessContext(operation, data, executionContext) {
+        // Implement business context enrichment here
+        // This could include:
+        // - Adding computed fields
+        // - Loading related resources
+        // - Adding user-specific data
+        // - Permission-based filtering
+        return data; // Default: pass through
+    }
+    /**
+     * Apply business filter
+     */
+    async applyBusinessFilter(filter, executionContext) {
+        // Implement business filtering logic here
+        // This could include:
+        // - User permission-based filtering
+        // - Organization scope filtering
+        // - Security filtering
+        return filter; // Default: pass through
+    }
+    /**
+     * Enhance search query with business logic
+     */
+    async enhanceSearchQuery(searchQuery, executionContext) {
+        // Implement search enhancement logic here
+        // This could include:
+        // - Query expansion
+        // - Synonym handling
+        // - Permission-based query modification
+        return searchQuery; // Default: pass through
+    }
+    /**
+     * Validate deletion constraints
+     */
+    async validateDeletionConstraints(data, executionContext) {
+        // Implement deletion constraint validation here
+        // This could include:
+        // - Dependency checking
+        // - Business rule validation
+        // - Permission validation
+        // Default: allow deletion
+    }
+    // ================================
+    // Notification Methods
+    // ================================
+    /**
+     * Dispatch notifications (email, badge, WebSocket, M2M) based on operation configuration.
+     *
+     * Reads ALL notification config from `executionContext.operation` — which is guaranteed
+     * to be the correct (possibly variant-resolved) operation thanks to Correction Points
+     * 1 and 2 in `doOperation()`. The NotificationDispatcherService also reads
+     * `executionContext.operation` extensively (15+ reads across its sub-methods).
+     */
+    async dispatchNotifications(executionContext, inputData, currentResult, tokenGenerationResult) {
+        await dispatchPostOperationNotificationsBestEffort({
+            notificationDispatcher: this.notificationDispatcher,
+            populationService: this.populationService,
+            logger: this.logger,
+            logDebug: this.logDebug,
+        }, executionContext, inputData, currentResult, tokenGenerationResult);
+    }
+}
+//# sourceMappingURL=services-registry-handler.backend.service.js.map