@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/base-classes/services/controllers/controller-resource.backend.service.js

@@ -0,0 +1,1320 @@
+import 'reflect-metadata';
+import { Router } from 'express';
+import { z } from 'zod';
+import { HttpMethod, DataMode, OPERATION_VARIANT_KEY, ResourcesConfigOperationsDtosBuilderUtils, ResourceOperationsUtils, ResourcesConfigOperationsUrlsBuilderUtils, extractCrdtFieldNames } from '@wildo-ai/saas-models';
+import { isBackendOnlyField, getBackendOnlyParams, isAuditAccessField, getZodObjectShape, isZodObject } from '@wildo-ai/zod-decorators';
+import { CoreResourceOperation, ALL_COLLECTION_OPERATIONS, OPERATIONS_WITHOUT_REQUEST_BODY, ARRAY_RESPONSE_OPERATIONS } from '@wildo-ai/saas-models';
+import { ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, ErrorType, ErrorCustomMessageReference, WildoHeaderKeys, isWildoBackendError } from '@wildo-ai/saas-models';
+import { createMulterUploadConfig } from '../../../files/utils/file-upload.utils.js';
+import { resolveConfiguredMaxFileSize } from '../../../files/utils/file-validation.utils.js';
+import { initializeValidateFieldRoutes } from './validate-field-handler.backend.service.js';
+/**
+ * HTTP Method mapping for operations
+ */
+const HTTP_METHOD_MAP = {
+    [CoreResourceOperation.CREATE]: HttpMethod.POST,
+    [CoreResourceOperation.READ]: HttpMethod.GET,
+    [CoreResourceOperation.UPDATE]: HttpMethod.PUT,
+    [CoreResourceOperation.DELETE]: HttpMethod.DELETE,
+    [CoreResourceOperation.LIST]: HttpMethod.GET,
+    [CoreResourceOperation.SEARCH]: HttpMethod.GET,
+    [CoreResourceOperation.COUNT]: HttpMethod.GET,
+    [CoreResourceOperation.UPDATE_MANY]: HttpMethod.PUT,
+    [CoreResourceOperation.DELETE_MANY]: HttpMethod.DELETE,
+    [CoreResourceOperation.CREATE_MANY]: HttpMethod.POST,
+};
+export function shouldSkipImplicitRequestValidation(effectiveOperation, hasExplicitRequestDto) {
+    return !hasExplicitRequestDto && OPERATIONS_WITHOUT_REQUEST_BODY.includes(effectiveOperation);
+}
+function hasMeaningfulExplicitRequestDto(requestDto) {
+    if (!requestDto) {
+        return false;
+    }
+    if (requestDto instanceof z.ZodObject) {
+        return Object.keys(requestDto.shape).length > 0;
+    }
+    return true;
+}
+function parseOptionalPositiveInt(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return Math.trunc(value);
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+function parseCollectionQuerySort(value) {
+    if (!value || typeof value !== 'string') {
+        return undefined;
+    }
+    const sortEntries = value
+        .split(',')
+        .map((segment) => segment.trim())
+        .filter(Boolean)
+        .map((segment) => {
+        const [field, rawDirection] = segment.split(':');
+        if (!field) {
+            return null;
+        }
+        const normalizedDirection = rawDirection?.toLowerCase();
+        const direction = normalizedDirection === 'desc' ? -1 : 1;
+        return [field, direction];
+    })
+        .filter((entry) => entry !== null);
+    return sortEntries.length > 0 ? Object.fromEntries(sortEntries) : undefined;
+}
+function normalizeCollectionSorting(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const normalizedEntries = [];
+    for (const [field, rawValue] of Object.entries(value)) {
+        if (rawValue === 1 || rawValue === -1) {
+            normalizedEntries.push([field, rawValue]);
+            continue;
+        }
+        if (rawValue
+            && typeof rawValue === 'object'
+            && !Array.isArray(rawValue)
+            && typeof rawValue.field === 'string') {
+            const sortField = rawValue.field;
+            const rawOrder = String(rawValue.order ?? 'asc').toLowerCase();
+            normalizedEntries.push([sortField, rawOrder === 'desc' ? -1 : 1]);
+        }
+    }
+    return normalizedEntries.length > 0 ? Object.fromEntries(normalizedEntries) : undefined;
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseIfMatchVersionHeader(rawHeader) {
+    const rawValues = Array.isArray(rawHeader) ? rawHeader : [rawHeader];
+    for (const rawValue of rawValues) {
+        if (typeof rawValue !== 'string' || rawValue.trim() === '') {
+            continue;
+        }
+        const candidates = rawValue
+            .split(',')
+            .map((candidate) => candidate.trim())
+            .filter((candidate) => candidate !== '');
+        for (const candidate of candidates) {
+            const normalizedCandidate = candidate
+                .replace(/^W\//, '')
+                .replace(/^"|"$/g, '');
+            if (!normalizedCandidate) {
+                continue;
+            }
+            const parsedVersion = Number(normalizedCandidate);
+            if (Number.isInteger(parsedVersion) && parsedVersion >= 0) {
+                return parsedVersion;
+            }
+        }
+    }
+    return undefined;
+}
+function hasNonEmptyIfMatchHeader(rawHeader) {
+    const rawValues = Array.isArray(rawHeader) ? rawHeader : [rawHeader];
+    return rawValues.some((rawValue) => typeof rawValue === 'string' && rawValue.trim() !== '');
+}
+function supportsIfMatchOptimisticLocking(params) {
+    // The framework only treats If-Match as authoritative optimistic locking for
+    // the single-resource UPDATE-like lane. Broader mutation families may still
+    // be update-like semantically, but they do not have the same per-resource
+    // compare-and-swap contract and must fail closed when the header is present.
+    const effectiveOperation = params.resourceOperationLike || params.operationIdentifier;
+    return effectiveOperation === CoreResourceOperation.UPDATE && params.isBulkOperation !== true;
+}
+function collectSubmittedFieldPaths(value, prefix = '') {
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return prefix ? [prefix] : [];
+        }
+        return value.flatMap((childValue, index) => (collectSubmittedFieldPaths(childValue, `${prefix}[${index}]`)));
+    }
+    if (!isPlainRecord(value)) {
+        return prefix ? [prefix] : [];
+    }
+    const entries = Object.entries(value).filter(([key]) => !key.startsWith('_'));
+    if (entries.length === 0) {
+        return prefix ? [prefix] : [];
+    }
+    return entries.flatMap(([key, childValue]) => {
+        const nextPath = prefix ? `${prefix}.${key}` : key;
+        return collectSubmittedFieldPaths(childValue, nextPath);
+    });
+}
+function getValueAtPath(record, path) {
+    const normalizedPath = path.replace(/\[(\d+)\]/g, '.$1');
+    return normalizedPath.split('.').filter(Boolean).reduce((current, segment) => {
+        if (current == null || typeof current !== 'object') {
+            return undefined;
+        }
+        return current[segment];
+    }, record);
+}
+function areConflictValuesEqual(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (left === null || left === undefined || right === null || right === undefined) {
+        return left === right;
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) {
+            return false;
+        }
+        return left.every((value, index) => areConflictValuesEqual(value, right[index]));
+    }
+    if (isPlainRecord(left) || isPlainRecord(right)) {
+        if (!isPlainRecord(left) || !isPlainRecord(right)) {
+            return false;
+        }
+        const keys = [...new Set([...Object.keys(left), ...Object.keys(right)])]
+            .filter((key) => !key.startsWith('_'));
+        return keys.every((key) => areConflictValuesEqual(left[key], right[key]));
+    }
+    return false;
+}
+function buildSortingSchemaInput(sort) {
+    if (!sort) {
+        return undefined;
+    }
+    const entries = Object.entries(sort);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(entries.map(([field, direction], index) => [
+        field,
+        {
+            field,
+            order: direction === -1 ? 'desc' : 'asc',
+            priority: index,
+        },
+    ]));
+}
+function extractCollectionFilters(rawData, allowedFilterFields) {
+    const allowedKeys = new Set([
+        ...(allowedFilterFields ?? []),
+        'createdAt',
+        'updatedAt',
+    ]);
+    const filters = {};
+    for (const key of allowedKeys) {
+        const value = rawData[key];
+        if (value !== undefined) {
+            filters[key] = value;
+        }
+    }
+    return filters;
+}
+export function shouldAuthorizeCollectionOperation(effectiveOperation) {
+    return ALL_COLLECTION_OPERATIONS.includes(effectiveOperation);
+}
+export function isContextAddressedReadOperation(effectiveOperation, resourceFieldIdentifier, initiatorInfo, matchedParameterFieldIdentifiers) {
+    if (effectiveOperation !== CoreResourceOperation.READ) {
+        return false;
+    }
+    const parameters = initiatorInfo.parameters ?? [];
+    if ((matchedParameterFieldIdentifiers?.length ?? 0) > 0) {
+        const declaredParameterFieldIdentifiers = new Set(parameters.map((parameter) => parameter.fieldIdentifier));
+        const allMatchedParametersAreDeclared = matchedParameterFieldIdentifiers.every((fieldIdentifier) => declaredParameterFieldIdentifiers.has(fieldIdentifier));
+        if (allMatchedParametersAreDeclared) {
+            return !matchedParameterFieldIdentifiers?.includes(resourceFieldIdentifier);
+        }
+    }
+    if (parameters.length === 0) {
+        return false;
+    }
+    return !parameters.some((parameter) => parameter.fieldIdentifier === resourceFieldIdentifier);
+}
+export class ControllerResourceBackendService {
+    logger;
+    errorBuilder;
+    errorHandler;
+    jwtService;
+    authorizationsService;
+    resourcesRegistry;
+    executionContextCreator;
+    executionContextHandler;
+    repositoriesRegistry;
+    resourceOperationHelper;
+    servicesRegistry;
+    fileFieldDetection;
+    fileUploadHandler;
+    auditLogsService;
+    anonymousSessionService;
+    appConfigService;
+    resourceConfiguration;
+    operationsMap;
+    router;
+    logDebug;
+    constructor(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.errorHandler = errorHandler;
+        this.jwtService = jwtService;
+        this.authorizationsService = authorizationsService;
+        this.resourcesRegistry = resourcesRegistry;
+        this.executionContextCreator = executionContextCreator;
+        this.executionContextHandler = executionContextHandler;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.resourceOperationHelper = resourceOperationHelper;
+        this.servicesRegistry = servicesRegistry;
+        this.fileFieldDetection = fileFieldDetection;
+        this.fileUploadHandler = fileUploadHandler;
+        this.auditLogsService = auditLogsService;
+        this.anonymousSessionService = anonymousSessionService;
+        this.appConfigService = appConfigService;
+        this.resourceConfiguration = this.resourcesRegistry.getResourceConfiguration(resourceType);
+        this.router = Router();
+        this.operationsMap = new Map();
+        this.logDebug = this.logger.debugByType(`ControllerResource_${resourceType}`);
+        this.logger.setDebugTypeLogging(`ControllerResource_${resourceType}`, false);
+        this.initializeOperationsMap();
+        this.initializeRoutes();
+        this.logDebug('Controller resource service created', { resourceType: this.resourceConfiguration.resourceIdentifier, operationsCount: this.operationsMap.size
+        });
+    }
+    getRouter() { return this.router; }
+    // ================================
+    // Initialization
+    // ================================
+    static createInstance(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService) {
+        return new ControllerResourceBackendService(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService);
+    }
+    initializeOperationsMap() {
+        if (!this.resourceConfiguration.operations) {
+            return;
+        }
+        // Only include API_CALL operations
+        const apiCallOperations = this.resourceConfiguration.operations.filter((op) => [ResourceOperationVariantType.API_CALL, ResourceOperationVariantType.API_CALL_WITH_CALLBACK].includes(op.variantType));
+        apiCallOperations.forEach(operation => {
+            const operationKey = ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation);
+            this.operationsMap.set(operationKey, operation);
+        });
+        this.logDebug('Operations map initialized', { totalOperations: this.resourceConfiguration.operations.length, apiCallOperations: apiCallOperations.length });
+    }
+    initializeRoutes() {
+        this.logDebug('Initializing Express routes');
+        this.operationsMap.forEach((operation, operationKey) => {
+            this.createRouteForOperation(operation);
+        });
+        // Initialize file upload routes for resources with file fields
+        this.initializeFileUploadRoutes();
+        // Initialize validate-field routes for resources with unique fields
+        this.initializeValidateFieldRoutes();
+        this.router.use(this.errorHandler.expressErrorHandler());
+        this.logDebug('Express routes initialized with unified error handler', {
+            routeCount: this.operationsMap.size
+        });
+    }
+    /**
+     * Initialize file upload routes for resources with file fields.
+     * Creates routes:
+     * - POST /api/v1/.../resourceType/files/:fieldName (CREATE)
+     * - POST /api/v1/.../resourceType/:resourceId/files/:fieldName (UPDATE)
+     */
+    /**
+     * L12 Audit (Phase I):
+     * - Authorization: registered upload routes now build the execution context and
+     *   perform `authorizeInController()` before Multer and before the async upload
+     *   handler runs, so unauthorized requests are rejected before temp-disk writes,
+     *   storage upload, or DB write.
+     * - Parent resource params: `initiatorInfo.parameters` is correctly passed to the execution context
+     *   creator, ensuring parent resource FK authorization matches non-file routes.
+     * - Multer errors: Request-body parsing failures still flow through the unified
+     *   error handler, and request-size violations are classified as validation
+     *   errors rather than generic internal failures.
+     * - Route order: the controller-specific authorization middleware runs before
+     *   Multer for registered upload routes, so unauthenticated callers are
+     *   rejected before temp-disk parsing starts. Multer still runs before the
+     *   async upload handler itself, which is why file-type/size failures surface
+     *   as middleware-layer errors rather than handler exceptions.
+     */
+    initializeFileUploadRoutes() {
+        const resourceType = this.resourceConfiguration.resourceIdentifier;
+        // Check if resource has file fields
+        if (!this.fileFieldDetection.hasFileFields(resourceType)) {
+            this.logDebug('No file fields detected, skipping file upload routes', { resourceType });
+            return;
+        }
+        const fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+        // Get CREATE and UPDATE operations from resource configuration
+        // Operations already have initiatorInfos populated (via ResourcesConfigOperationsUrlsBuilderUtils.updateOperationUrls)
+        // This includes all parent combinations (REQUIRES_CONTEXT, OPTIONAL_CONTEXT, STANDALONE)
+        const createOperation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.CREATE &&
+            [ResourceOperationVariantType.API_CALL, ResourceOperationVariantType.API_CALL_WITH_CALLBACK].includes(op.variantType));
+        const updateOperation = this.resourceConfiguration.operations.find(op => op.operationIdentifier === CoreResourceOperation.UPDATE &&
+            [ResourceOperationVariantType.API_CALL, ResourceOperationVariantType.API_CALL_WITH_CALLBACK].includes(op.variantType));
+        if (!createOperation || !updateOperation) {
+            this.logDebug('CREATE or UPDATE operation not found or not API_CALL type, skipping file upload routes', { resourceType });
+            return;
+        }
+        // Get initiatorInfos (already populated with all parent combinations)
+        // Each initiatorInfo contains:
+        // - url: URL pattern with parent paths (e.g., /api/v1/parents/{parentId}/children)
+        // - parameters: Parent resource parameters to extract (e.g., [{ fieldIdentifier: 'parentId', resourceType: 'PARENTS' }])
+        const createInitiatorInfos = createOperation.initiatorInfos || [];
+        const updateInitiatorInfos = updateOperation.initiatorInfos || [];
+        if (createInitiatorInfos.length === 0 || updateInitiatorInfos.length === 0) {
+            this.logDebug('CREATE or UPDATE operation has no initiatorInfos, skipping file upload routes', { resourceType });
+            return;
+        }
+        // Configure Multer middleware with disk storage for true streaming (no memory buffering)
+        // Files are written to temp directory, then streamed to storage
+        // This enables true streaming for large files without OOM risk
+        // NOTE: In k8s, ensure pod has volume mount with read-write access to temp directory
+        // NOTE: Consider temp file cleanup job for orphaned files (if process crashes)
+        const upload = createMulterUploadConfig({
+            logger: this.logger,
+            maxFileSize: resolveConfiguredMaxFileSize(this.appConfigService.config.storage?.maxFileSize),
+        });
+        // Register routes for each file field and each parent combination
+        // CRITICAL SECURITY FIX: Use initiatorInfos to include parent resource context in routes
+        // This ensures parent resource authorization is properly validated
+        for (const fileField of fileFields) {
+            const { fieldName } = fileField;
+            // CREATE routes (one per parent combination)
+            // Register more specific routes first (with parent paths) for correct Express matching
+            // Sort by parameter count (more parameters = more specific route)
+            const sortedCreateInfos = [...createInitiatorInfos].sort((a, b) => {
+                const aParams = a.parameters?.length || 0;
+                const bParams = b.parameters?.length || 0;
+                return bParams - aParams; // Descending order (more specific first)
+            });
+            for (const initiatorInfo of sortedCreateInfos) {
+                const fileUploadInitiatorInfo = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+                    operationRouteUrl: initiatorInfo.url,
+                    operationParameters: initiatorInfo.parameters || [],
+                    targetResourceType: resourceType,
+                    targetResourceFieldIdentifier: this.resourceConfiguration.resourceFieldIdentifier,
+                    fieldName,
+                    requiresTargetResourceId: false,
+                    isFrontend: false,
+                });
+                const createPath = this.convertUrlPatternToExpressPath(fileUploadInitiatorInfo.url);
+                const authorizeCreateUpload = this.createFileUploadAuthorizationMiddleware(createOperation, fileUploadInitiatorInfo, {
+                    requiresTargetResourceId: false,
+                    resourceType,
+                    fieldName,
+                });
+                this.router.post(createPath, authorizeCreateUpload, upload.single('file'), // Multer middleware - expects 'file' field name
+                this.asyncHandler(async (req, res, next) => {
+                    try {
+                        const executionContext = res.locals.fileUploadExecutionContext
+                            ?? await this.executionContextCreator.createExecutionContextFromRequest(req, createOperation, {
+                                url: fileUploadInitiatorInfo.url,
+                                parameters: fileUploadInitiatorInfo.parameters,
+                            });
+                        await this.fileUploadHandler.handleFileUpload(req, res, resourceType, fieldName, undefined, // No resourceId for CREATE
+                        CoreResourceOperation.CREATE, executionContext);
+                    }
+                    catch (error) {
+                        next(error);
+                    }
+                }));
+                this.logDebug('File upload CREATE route registered', {
+                    resourceType,
+                    fieldName,
+                    path: createPath,
+                    parentParams: fileUploadInitiatorInfo.parameters.map(p => `${p.fieldIdentifier}:${p.resourceType}`).join(', ') || 'none',
+                });
+            }
+            // UPDATE routes (one per parent combination)
+            // Register more specific routes first (with parent paths) for correct Express matching
+            const sortedUpdateInfos = [...updateInitiatorInfos].sort((a, b) => {
+                const aParams = a.parameters?.length || 0;
+                const bParams = b.parameters?.length || 0;
+                return bParams - aParams; // Descending order (more specific first)
+            });
+            for (const initiatorInfo of sortedUpdateInfos) {
+                const fileUploadInitiatorInfo = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+                    operationRouteUrl: initiatorInfo.url,
+                    operationParameters: initiatorInfo.parameters || [],
+                    targetResourceType: resourceType,
+                    targetResourceFieldIdentifier: this.resourceConfiguration.resourceFieldIdentifier,
+                    fieldName,
+                    requiresTargetResourceId: true,
+                    isFrontend: false,
+                });
+                const updatePath = this.convertUrlPatternToExpressPath(fileUploadInitiatorInfo.url);
+                const authorizeUpdateUpload = this.createFileUploadAuthorizationMiddleware(updateOperation, fileUploadInitiatorInfo, {
+                    requiresTargetResourceId: true,
+                    resourceType,
+                    fieldName,
+                });
+                this.router.post(updatePath, authorizeUpdateUpload, upload.single('file'), // Multer middleware
+                this.asyncHandler(async (req, res, next) => {
+                    try {
+                        // Extract resourceId from URL params
+                        const resourceId = req.params[this.resourceConfiguration.resourceFieldIdentifier];
+                        if (!resourceId) {
+                            throw this.errorBuilder.buildError(ErrorType.VALIDATION, {}, {
+                                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                                context: {
+                                    message: `Resource ID is required for UPDATE file upload`,
+                                    resourceType,
+                                    fieldName,
+                                },
+                            });
+                        }
+                        const executionContext = res.locals.fileUploadExecutionContext
+                            ?? await this.executionContextCreator.createExecutionContextFromRequest(req, updateOperation, {
+                                url: fileUploadInitiatorInfo.url,
+                                parameters: fileUploadInitiatorInfo.parameters,
+                            });
+                        await this.fileUploadHandler.handleFileUpload(req, res, resourceType, fieldName, resourceId, CoreResourceOperation.UPDATE, executionContext);
+                    }
+                    catch (error) {
+                        next(error);
+                    }
+                }));
+                this.logDebug('File upload UPDATE route registered', {
+                    resourceType,
+                    fieldName,
+                    path: updatePath,
+                    parentParams: fileUploadInitiatorInfo.parameters.map(p => `${p.fieldIdentifier}:${p.resourceType}`).join(', ') || 'none',
+                });
+            }
+        }
+        this.logDebug('File upload routes initialized', {
+            resourceType,
+            fileFieldCount: fileFields.length,
+            createRoutes: createInitiatorInfos.length * fileFields.length,
+            updateRoutes: updateInitiatorInfos.length * fileFields.length,
+        });
+    }
+    /**
+     * Authorize file uploads before Multer touches request bodies.
+     *
+     * Resource upload routes are intentionally protected at the same semantic
+     * execution-context layer as the actual upload handler. Running that auth step
+     * first avoids unauthenticated callers forcing temp-disk writes through Multer
+     * while still reusing the exact same execution context for the later upload.
+     */
+    createFileUploadAuthorizationMiddleware(operation, fileUploadInitiatorInfo, options) {
+        return this.asyncHandler(async (req, res, next) => {
+            try {
+                let executionContext = await this.executionContextCreator.createExecutionContextFromRequest(req, operation, {
+                    url: fileUploadInitiatorInfo.url,
+                    parameters: fileUploadInitiatorInfo.parameters,
+                });
+                executionContext = this.resolveExecutionContextForAuthorization(executionContext, req).executionContext;
+                req.executionContext = executionContext;
+                const locals = (res.locals ??= {});
+                locals.fileUploadExecutionContext = executionContext;
+                const resourceId = options.requiresTargetResourceId
+                    ? req.params[this.resourceConfiguration.resourceFieldIdentifier]
+                    : undefined;
+                if (options.requiresTargetResourceId && !resourceId) {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                        context: {
+                            message: 'Resource ID is required for UPDATE file upload',
+                            resourceType: options.resourceType,
+                            fieldName: options.fieldName,
+                        },
+                    });
+                }
+                await this.authorizationsService.authorizeInController(resourceId, executionContext);
+                next();
+            }
+            catch (error) {
+                next(error);
+            }
+        });
+    }
+    /**
+     * Initialize validate-field routes for resources with unique fields.
+     * Delegates to the validate-field handler module.
+     *
+     * Creates route: POST /api/v1/.../:resourceType/validate-field
+     * Authorization uses CREATE operation rights (collection-level).
+     */
+    initializeValidateFieldRoutes() {
+        initializeValidateFieldRoutes(this.router, this.resourceConfiguration, this.logger, this.errorBuilder, this.authorizationsService, this.executionContextCreator, this.resourcesRegistry, this.repositoriesRegistry, this.convertUrlPatternToExpressPath.bind(this), this.asyncHandler.bind(this));
+    }
+    /**
+     * Async handler wrapper for Express route handlers.
+     * Ensures errors are properly passed to Express error handler.
+     */
+    asyncHandler(fn) {
+        return (req, res, next) => {
+            Promise.resolve(fn(req, res, next)).catch(next);
+        };
+    }
+    createRouteForOperation(operation) {
+        if (![ResourceOperationVariantType.API_CALL, ResourceOperationVariantType.API_CALL_WITH_CALLBACK].includes(operation.variantType)) {
+            this.logDebug('Operation is not API_CALL or API_CALL_WITH_CALLBACK type, skipping route creation', { operation: operation.operationIdentifier, variantType: operation.variantType });
+            return;
+        }
+        const apiCallOperation = operation;
+        const operationInitiatorInfos = apiCallOperation.initiatorInfos;
+        if (!operationInitiatorInfos || operationInitiatorInfos.length === 0) {
+            this.logDebug('No URLs found for operation, skipping route creation', { operation: operation.operationIdentifier });
+            return;
+        }
+        const httpMethod = this.getHttpMethodForOperation(operation);
+        // Create routes for all URL patterns
+        operationInitiatorInfos.forEach((initiatorInfo) => {
+            const expressPath = this.convertUrlPatternToExpressPath(initiatorInfo.url);
+            this.logDebug('Creating route', {
+                method: httpMethod,
+                path: expressPath,
+                operation: operation.operationIdentifier,
+                parameters: initiatorInfo.parameters?.map((p) => `${p.fieldIdentifier}:${p.resourceType}`).join(', ') || 'none',
+                callbackUrl: initiatorInfo['urlCallback'] ?? 'none'
+            });
+            const handler = async (req, res, next) => {
+                try {
+                    await this.doOperation(operation, initiatorInfo, httpMethod, req, res, next);
+                }
+                catch (error) {
+                    next(error);
+                }
+            };
+            switch (httpMethod) {
+                case HttpMethod.GET:
+                    this.router.get(expressPath, handler);
+                    break;
+                case HttpMethod.POST:
+                    this.router.post(expressPath, handler);
+                    break;
+                case HttpMethod.PUT:
+                    this.router.put(expressPath, handler);
+                    break;
+                case HttpMethod.DELETE:
+                    this.router.delete(expressPath, handler);
+                    break;
+                case HttpMethod.PATCH:
+                    this.router.patch(expressPath, handler);
+                    break;
+                default:
+                    this.logDebug('Unsupported HTTP method', { method: httpMethod });
+            }
+        });
+    }
+    convertUrlPatternToExpressPath(urlPattern) {
+        // Remove /api/v1 prefix to avoid double mounting (HTTP server already mounts master router at /api/v1)
+        let path = urlPattern.replace(/^\/api\/v1/, '');
+        // Ensure path starts with / if it's not empty
+        if (path && !path.startsWith('/')) {
+            path = '/' + path;
+        }
+        // Convert {param} to :param for Express
+        return path.replace(/\{([^}]+)\}/g, ':$1');
+    }
+    // ================================
+    // Execution
+    // ================================
+    async doOperation(operation, initiatorInfo, httpMethod, req, res, next) {
+        let executionContext;
+        let validatedData;
+        let dataMode;
+        let optionsWithVersion;
+        try {
+            this.logDebug('Executing operation', { operation: operation.operationIdentifier, method: req.method, path: req.path });
+            executionContext = await this.executionContextCreator.createExecutionContextFromRequest(req, operation, initiatorInfo);
+            const resolvedContext = this.resolveExecutionContextForAuthorization(executionContext, req);
+            executionContext = resolvedContext.executionContext;
+            dataMode = resolvedContext.dataMode;
+            // Attach executionContext to request for error handler access
+            req.executionContext = executionContext;
+            validatedData = this.validateRequestData(req, executionContext.operation, executionContext);
+            // Collection operations (LIST, CREATE, SEARCH) don't have a target resource ID
+            // They operate on collections and authorization is based on roles + parent scope
+            const operationId = executionContext.operation.operationIdentifier;
+            const operationLike = executionContext.operation.resourceOperationLike;
+            const effectiveOperation = operationLike || operationId;
+            const isCollectionOperation = shouldAuthorizeCollectionOperation(String(effectiveOperation));
+            if (isCollectionOperation) {
+                // For collection operations: authorize without specific resource ID
+                // Authorization relies on roles and parent scope validation (via initiatorIds)
+                this.logDebug('Collection operation - authorizing without resource ID', {
+                    operation: operationId,
+                    effectiveOperation,
+                    initiatorIds: executionContext.initiatorIds
+                });
+                await this.authorizationsService.authorizeInController(undefined, executionContext);
+            }
+            else {
+                const resourceId = this.resourceOperationHelper.extractIdsFromExecutionContext(executionContext, executionContext.operation.resourceFieldIdentifier);
+                const allowContextOnlyRead = (resourceId === undefined
+                    && isContextAddressedReadOperation(String(effectiveOperation), executionContext.operation.resourceFieldIdentifier, initiatorInfo, Object.keys(req.params ?? {})));
+                if (allowContextOnlyRead) {
+                    this.logDebug('Context-addressed read - authorizing without explicit resource ID', {
+                        operation: operationId,
+                        effectiveOperation,
+                        initiatorParameters: initiatorInfo.parameters?.map((parameter) => parameter.fieldIdentifier) ?? [],
+                    });
+                    await this.authorizationsService.authorizeInController(undefined, executionContext);
+                }
+                else {
+                    // Validate resourceId format (MongoDB ObjectId or UUID)
+                    // After validation, we know resourceId is a valid string
+                    this.resourceOperationHelper.validateResourceId(resourceId, executionContext, executionContext.operation.resourceFieldIdentifier);
+                    // Type assertion is safe here because validateResourceId ensures it's a string
+                    await this.authorizationsService.authorizeInController(resourceId, executionContext);
+                }
+            }
+            // For API calls, request pagination wrapper for list operations
+            // Extract dataMode from query to pass to service layer for variant resolution
+            const needsPagination = effectiveOperation === CoreResourceOperation.LIST || effectiveOperation === CoreResourceOperation.SEARCH;
+            const options = needsPagination ? { paginated: true, dataMode } : dataMode ? { dataMode } : undefined;
+            // Parse If-Match header for optimistic locking on the supported single-resource
+            // update-like lane only. Other mutation families must fail closed instead of
+            // silently accepting a header they do not actually enforce downstream.
+            const ifMatchRaw = req.headers[WildoHeaderKeys.IF_MATCH];
+            optionsWithVersion = options;
+            const hasIfMatchHeader = hasNonEmptyIfMatchHeader(ifMatchRaw);
+            const supportsIfMatch = supportsIfMatchOptimisticLocking({
+                operationIdentifier: operationId,
+                resourceOperationLike: operationLike,
+                isBulkOperation: executionContext.operation.isBulkOperation,
+            });
+            if (hasIfMatchHeader && !supportsIfMatch) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                    context: {
+                        field: WildoHeaderKeys.IF_MATCH,
+                        message: 'If-Match is only supported for single-resource update-like operations',
+                        operationIdentifier: executionContext.operation.operationIdentifier,
+                        resourceOperationLike: executionContext.operation.resourceOperationLike,
+                        isBulkOperation: executionContext.operation.isBulkOperation ?? false,
+                    },
+                });
+            }
+            const parsedVersion = supportsIfMatch ? parseIfMatchVersionHeader(ifMatchRaw) : undefined;
+            if (hasIfMatchHeader && supportsIfMatch && parsedVersion == null) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                    context: {
+                        field: WildoHeaderKeys.IF_MATCH,
+                        message: 'If-Match must contain a non-negative integer version',
+                        operationIdentifier: executionContext.operation.operationIdentifier,
+                        resourceOperationLike: executionContext.operation.resourceOperationLike,
+                        isBulkOperation: executionContext.operation.isBulkOperation ?? false,
+                    },
+                });
+            }
+            if (parsedVersion != null) {
+                optionsWithVersion = { ...options, ifMatchVersion: parsedVersion };
+            }
+            // CRDT: extract and validate field timestamps from request body (not from validated DTO —
+            // _field_timestamps is engine infrastructure, not part of the resource schema).
+            // S2: semantic validation — only accept keys that are actually marked isCRDT() on the schema.
+            const rawFieldTimestamps = req.body?._field_timestamps;
+            if (rawFieldTimestamps && typeof rawFieldTimestamps === 'object' && !Array.isArray(rawFieldTimestamps)) {
+                const crdtFields = extractCrdtFieldNames(operation.mainSchema, false);
+                const validated = {};
+                const entries = Object.entries(rawFieldTimestamps);
+                if (entries.length <= 100) {
+                    for (const [key, value] of entries) {
+                        if (typeof key === 'string' && key.length <= 200
+                            && typeof value === 'number' && Number.isFinite(value) && value > 0
+                            && crdtFields.has(key)) {
+                            validated[key] = value;
+                        }
+                    }
+                    if (Object.keys(validated).length > 0) {
+                        optionsWithVersion = { ...optionsWithVersion, fieldTimestamps: validated };
+                    }
+                }
+            }
+            this.logDebug('Calling service with operation', {
+                operationIdentifier: executionContext.operation.operationIdentifier,
+                variantKey: executionContext.operation.variantKey,
+                dataMode,
+                hasOptions: !!optionsWithVersion
+            });
+            // W7.3a: Create AnonymousUser BEFORE the main operation to avoid FK orphans.
+            // The main operation may create a resource with anonymousUserId FK — the
+            // AnonymousUser record must exist first for FK integrity.
+            if (executionContext.anonymousUserCreated) {
+                await this.anonymousSessionService.createAnonymousUser(executionContext.anonymousUserId, req);
+                const token = this.anonymousSessionService.signSessionToken(executionContext.anonymousUserId);
+                executionContext.setAnonymousSessionToken(token);
+            }
+            const result = await this.servicesRegistry.doByExecutionContext(executionContext, validatedData, optionsWithVersion);
+            // W7.3a: Set the token as response header AFTER the main operation succeeds.
+            if (executionContext.anonymousSessionToken) {
+                res.setHeader(WildoHeaderKeys.ANONYMOUS_SESSION_TOKEN, executionContext.anonymousSessionToken);
+            }
+            await this.sendResponse(res, req, executionContext, result);
+        }
+        catch (error) {
+            if (!executionContext) {
+                next(error);
+                return;
+            }
+            const enrichedError = await this.enrichVersionConflictError(error, executionContext, validatedData, optionsWithVersion);
+            next(enrichedError);
+        }
+    }
+    async enrichVersionConflictError(error, executionContext, validatedData, options) {
+        if (!isWildoBackendError(error)) {
+            return error;
+        }
+        if (error.type !== ErrorType.CONFLICT || error.customMessageReference !== ErrorCustomMessageReference.VERSION_CONFLICT) {
+            return error;
+        }
+        if (options?.ifMatchVersion == null) {
+            return error;
+        }
+        // Only optimistic-lock conflicts carry the richer versionConflict payload.
+        // A generic CONFLICT without an If-Match fence does not guarantee that the
+        // controller can explain "expected vs current" truth field-by-field.
+        const versionConflict = await this.buildVersionConflictDetails(executionContext, validatedData, options.ifMatchVersion);
+        if (!versionConflict) {
+            return error;
+        }
+        error.context = {
+            ...(error.context ?? {}),
+            versionConflict,
+        };
+        return error;
+    }
+    async buildVersionConflictDetails(executionContext, validatedData, expectedVersion) {
+        const resourceId = this.resourceOperationHelper.extractIdsFromExecutionContext(executionContext, executionContext.operation.resourceFieldIdentifier);
+        if (typeof resourceId !== 'string' || resourceId.length === 0) {
+            return undefined;
+        }
+        const submittedValues = isPlainRecord(validatedData) ? { ...validatedData } : {};
+        try {
+            const currentResource = await this.servicesRegistry.read(executionContext.operation.resourceIdentifier, executionContext, resourceId);
+            if (!isPlainRecord(currentResource)) {
+                return undefined;
+            }
+            const currentValues = this.shapeCanonicalConflictCurrentValues(currentResource);
+            if (!currentValues) {
+                return undefined;
+            }
+            // Compare the client-submitted shape against canonical READ-shaped server
+            // truth so conflict consumers see the same surface the frontend normally
+            // reads, while still preserving authoritative engine metadata below.
+            const conflictingFields = collectSubmittedFieldPaths(submittedValues).filter((fieldPath) => (!areConflictValuesEqual(getValueAtPath(currentValues, fieldPath), getValueAtPath(submittedValues, fieldPath))));
+            if (typeof currentValues._version !== 'number') {
+                this.logger.warn('Skipped version conflict enrichment because canonical current values omitted authoritative version', {
+                    resourceType: executionContext.operation.resourceIdentifier,
+                    resourceId,
+                    expectedVersion,
+                });
+                return undefined;
+            }
+            return {
+                currentVersion: currentValues._version,
+                expectedVersion,
+                conflictingFields,
+                currentValues,
+                submittedValues,
+            };
+        }
+        catch (readError) {
+            this.logger.warn('Failed to enrich version conflict with authoritative current values', {
+                resourceType: executionContext.operation.resourceIdentifier,
+                resourceId,
+                error: readError instanceof Error ? readError.message : String(readError),
+            });
+            return undefined;
+        }
+    }
+    shapeCanonicalConflictCurrentValues(currentResource) {
+        const readOperation = this.resolveCanonicalConflictReadOperation();
+        if (!readOperation) {
+            return currentResource;
+        }
+        const selectedDto = this.selectResponseDto(readOperation, undefined);
+        if (!selectedDto) {
+            return currentResource;
+        }
+        const transformedCurrentResource = ResourcesConfigOperationsDtosBuilderUtils.transformResponseDates(currentResource, selectedDto);
+        const parsedCurrentResource = selectedDto.parse(transformedCurrentResource);
+        if (!isPlainRecord(parsedCurrentResource)) {
+            return undefined;
+        }
+        // Preserve engine-owned identity/version metadata even when the canonical
+        // READ DTO strips them. Conflict consumers still need the authoritative
+        // resource id/version tuple from storage truth, not only the public DTO body.
+        if (parsedCurrentResource._id === undefined && currentResource._id !== undefined) {
+            parsedCurrentResource._id = currentResource._id;
+        }
+        if (parsedCurrentResource._version === undefined && currentResource._version !== undefined) {
+            parsedCurrentResource._version = currentResource._version;
+        }
+        if (currentResource._field_meta && typeof currentResource._field_meta === 'object' && !Array.isArray(currentResource._field_meta)) {
+            parsedCurrentResource._field_meta = currentResource._field_meta;
+        }
+        return parsedCurrentResource;
+    }
+    resolveCanonicalConflictReadOperation() {
+        return this.resourceConfiguration.operations?.find((operation) => (operation.operationIdentifier === CoreResourceOperation.READ && operation.isOperationDefault === true)) ?? this.resourceConfiguration.operations?.find((operation) => (operation.operationIdentifier === CoreResourceOperation.READ));
+    }
+    normalizeCollectionQueryRequestData(rawRequestData, operation, effectiveOperation) {
+        const { filterFields } = operation;
+        const nestedFilters = rawRequestData.filters && typeof rawRequestData.filters === 'object' && !Array.isArray(rawRequestData.filters)
+            ? rawRequestData.filters
+            : {};
+        const filter = {
+            ...extractCollectionFilters(rawRequestData, filterFields),
+            ...extractCollectionFilters(nestedFilters, filterFields),
+        };
+        const page = parseOptionalPositiveInt(rawRequestData.page)
+            ?? parseOptionalPositiveInt(rawRequestData.pagination?.page);
+        const limit = parseOptionalPositiveInt(rawRequestData.limit)
+            ?? parseOptionalPositiveInt(rawRequestData.pagination?.limit);
+        if (effectiveOperation === CoreResourceOperation.SEARCH) {
+            const searchQuery = (typeof rawRequestData.q === 'string' && rawRequestData.q.trim() !== ''
+                ? rawRequestData.q
+                : typeof rawRequestData.searchQuery === 'string' && rawRequestData.searchQuery.trim() !== ''
+                    ? rawRequestData.searchQuery
+                    : typeof nestedFilters.searchRequest === 'string' && nestedFilters.searchRequest.trim() !== ''
+                        ? nestedFilters.searchRequest
+                        : undefined);
+            const sort = parseCollectionQuerySort(rawRequestData.sort)
+                ?? normalizeCollectionSorting(rawRequestData.sorting);
+            return { filter, page, limit, searchQuery, sort };
+        }
+        if (effectiveOperation === CoreResourceOperation.LIST) {
+            return { filter, page, limit };
+        }
+        return { filter };
+    }
+    buildCollectionQueryRequestDtoInput(req, operation, effectiveOperation) {
+        const requestData = { ...req.params, ...req.query, ...req.body };
+        const normalizedRequest = this.normalizeCollectionQueryRequestData(requestData, operation, effectiveOperation);
+        const filters = { ...normalizedRequest.filter };
+        if (effectiveOperation === CoreResourceOperation.SEARCH && normalizedRequest.searchQuery) {
+            filters.searchRequest = normalizedRequest.searchQuery;
+        }
+        return {
+            ...requestData,
+            ...(Object.keys(filters).length > 0 ? { filters } : {}),
+            ...(normalizedRequest.page !== undefined || normalizedRequest.limit !== undefined
+                ? {
+                    pagination: {
+                        ...(normalizedRequest.page !== undefined ? { page: normalizedRequest.page } : {}),
+                        ...(normalizedRequest.limit !== undefined ? { limit: normalizedRequest.limit } : {}),
+                    },
+                }
+                : {}),
+            ...(normalizedRequest.sort ? { sorting: buildSortingSchemaInput(normalizedRequest.sort) } : {}),
+        };
+    }
+    validateRequestData(req, operation, executionContext) {
+        const _extractedRequestData = (req) => ({ ...req.params, ...req.query, ...req.body });
+        // Use effectiveOperation to account for resourceOperationLike
+        const effectiveOperation = operation.resourceOperationLike || operation.operationIdentifier;
+        const hasExplicitRequestDto = hasMeaningfulExplicitRequestDto(operation.requestDto);
+        if (effectiveOperation === CoreResourceOperation.LIST
+            || effectiveOperation === CoreResourceOperation.COUNT
+            || effectiveOperation === CoreResourceOperation.SEARCH) {
+            const dtoInput = this.buildCollectionQueryRequestDtoInput(req, operation, String(effectiveOperation));
+            if (shouldSkipImplicitRequestValidation(String(effectiveOperation), hasExplicitRequestDto)) {
+                return this.normalizeCollectionQueryRequestData(dtoInput, operation, String(effectiveOperation));
+            }
+            if (!operation.requestDto) {
+                return this.normalizeCollectionQueryRequestData(dtoInput, operation, String(effectiveOperation));
+            }
+            try {
+                const transformedRequestData = ResourcesConfigOperationsDtosBuilderUtils.transformRequestDates(dtoInput, operation.requestDto);
+                const parsedRequestData = operation.requestDto.parse(transformedRequestData);
+                return this.normalizeCollectionQueryRequestData(parsedRequestData, operation, String(effectiveOperation));
+            }
+            catch (error) {
+                if (error instanceof z.ZodError) {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, { customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                        stack: error.stack,
+                        context: { requestData: dtoInput, error: error.message, zodIssues: error.issues }
+                    });
+                }
+                throw error;
+            }
+        }
+        // For pure core READ/LIST/DELETE/COUNT/SEARCH semantics without an explicit
+        // request DTO, no request body validation is needed. Custom operations that
+        // reuse READ-like semantics may still declare requestDto and must keep it.
+        if (shouldSkipImplicitRequestValidation(String(effectiveOperation), hasExplicitRequestDto)) {
+            // For other operations (READ, DELETE, COUNT): return empty or minimal data
+            // The actual IDs will be extracted from execution context
+            return req.body || {};
+        }
+        if (!operation.requestDto) {
+            return _extractedRequestData(req);
+        }
+        try {
+            const requestData = _extractedRequestData(req);
+            // Phase 3.8: Transform dates from strings to Date objects before validation
+            let transformedRequestData = requestData;
+            if (operation.requestDto) {
+                transformedRequestData = ResourcesConfigOperationsDtosBuilderUtils.transformRequestDates(requestData, operation.requestDto);
+            }
+            // Phase 3.9: Validate against requestDto (field stripping already applied at factory time)
+            return operation.requestDto.parse(transformedRequestData);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, { customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                    stack: error.stack,
+                    context: { requestData: _extractedRequestData(req), error: error.message, zodIssues: error.issues }
+                });
+            }
+            throw this.errorBuilder.buildFromStandardError(error, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                context: { requestData: _extractedRequestData(req), error: error.message }
+            });
+        }
+    }
+    /**
+     * Phase 3.7: Extract DataMode from execution context or query parameters.
+     * DataMode determines which DTO variant to use (SUMMARY, CONTEXT, or RAW).
+     *
+     * Priority:
+     * 1. Query parameter `dataMode` (if provided)
+     * 2. Operation variantKey (set at factory time)
+     * 3. Default to RAW (responseDto)
+     */
+    extractDataMode(executionContext, req) {
+        // Check query parameter first (allows runtime override)
+        const queryDataMode = req?.query?.dataMode;
+        const extractedFromQuery = ResourceOperationsUtils.normalizeDataModeString(queryDataMode);
+        // If query param provided a valid value, use it
+        if (queryDataMode && extractedFromQuery) {
+            return extractedFromQuery;
+        }
+        // Fall back to operation variantKey (set at factory time)
+        const operation = executionContext.operation;
+        if (operation.variantKey === OPERATION_VARIANT_KEY.SUMMARY) {
+            return DataMode.SUMMARY;
+        }
+        if (operation.variantKey === OPERATION_VARIANT_KEY.CONTEXT) {
+            return DataMode.CONTEXT;
+        }
+        // Default to RAW
+        return DataMode.RAW;
+    }
+    resolveExecutionContextForAuthorization(executionContext, req) {
+        const dataMode = this.extractDataMode(executionContext, req);
+        const resolvedOperation = this.resolveOperationForAuthorizationDataMode(executionContext.operation, dataMode);
+        if (executionContext.operation === resolvedOperation) {
+            return { executionContext, dataMode };
+        }
+        this.logDebug('Resolved controller authorization operation variant before role checks', {
+            originalVariantKey: executionContext.operation.variantKey,
+            resolvedVariantKey: resolvedOperation.variantKey,
+            dataMode,
+            operationIdentifier: executionContext.operation.operationIdentifier,
+        });
+        return {
+            executionContext: executionContext.withOperation(resolvedOperation),
+            dataMode,
+        };
+    }
+    resolveOperationForAuthorizationDataMode(operation, dataMode) {
+        if (!dataMode || dataMode === DataMode.RAW) {
+            return operation;
+        }
+        const operationPath = {
+            resourceIdentifier: operation.resourceIdentifier,
+            operationIdentifier: operation.operationIdentifier,
+            variantType: operation.variantType,
+            isOperationDefault: false,
+            variantKey: dataMode === DataMode.SUMMARY
+                ? OPERATION_VARIANT_KEY.SUMMARY
+                : OPERATION_VARIANT_KEY.CONTEXT,
+            isBulkOperation: false,
+        };
+        return this.resourcesRegistry.getOperationFromPath(operationPath);
+    }
+    /**
+     * Phase 3.7: Select the appropriate response DTO based on DataMode.
+     * Uses structure-aware utility method that handles LIST/SEARCH pagination wrappers.
+     *
+     * - Variant operations: Uses `responseDto` (already variant-specific)
+     * - SUMMARY mode: Uses `summaryDto` (wrapped in pagination for LIST/SEARCH)
+     * - CONTEXT mode: Uses `contextDto` (wrapped in pagination for LIST/SEARCH)
+     * - RAW mode: Uses `responseDto` (default)
+     */
+    selectResponseDto(operation, dataMode) {
+        return ResourcesConfigOperationsDtosBuilderUtils.selectResponseDto(operation, dataMode) || undefined;
+    }
+    async sendResponse(res, req, executionContext, result) {
+        const operation = executionContext.operation;
+        // Phase 3.7: Select response DTO based on operation variant
+        // selectResponseDto() is now structure-aware and handles variant operations correctly
+        const dataMode = this.extractDataMode(executionContext, req);
+        const selectedDto = this.selectResponseDto(operation, dataMode);
+        // Analyze the DTOs to understand structure
+        const analyzeDtoStructure = (dto) => {
+            if (!dto || typeof dto !== 'object' || !('shape' in dto))
+                return 'Not a Zod object';
+            try {
+                const shape = dto.shape;
+                return Object.keys(shape).join(', ');
+            }
+            catch {
+                return 'Cannot analyze';
+            }
+        };
+        this.logDebug('Controller - sendResponse DTO selection', {
+            operationIdentifier: operation.operationIdentifier,
+            variantKey: operation.variantKey,
+            dataMode,
+            hasSelectedDto: !!selectedDto,
+            hasResponseDto: !!operation.responseDto,
+            hasSummaryDto: !!operation.summaryDto,
+            hasContextDto: !!operation.contextDto,
+            hasInternalDto: !!operation.internalDto,
+            responseDtoFields: analyzeDtoStructure(operation.responseDto),
+            selectedDtoFields: analyzeDtoStructure(selectedDto),
+            resultStructure: result && typeof result === 'object' ? Object.keys(result) : typeof result
+        });
+        // Phase 3.8: Transform dates from Date objects to ISO strings before validation
+        let transformedResult = result;
+        if (selectedDto) {
+            transformedResult = ResourcesConfigOperationsDtosBuilderUtils.transformResponseDates(result, selectedDto);
+        }
+        // CRDT: preserve _field_meta before DTO parse. Zod's .parse() silently strips
+        // engine fields not in the resource schema. We save per-item _field_meta for both
+        // single-item responses and collection responses (flat arrays + paginated wrappers).
+        const savedFieldMetaMap = new Map();
+        const savedSingleFieldMeta = transformedResult?._field_meta;
+        if (Array.isArray(transformedResult)) {
+            for (let i = 0; i < transformedResult.length; i++) {
+                if (transformedResult[i]?._field_meta)
+                    savedFieldMetaMap.set(i, transformedResult[i]._field_meta);
+            }
+        }
+        else if (transformedResult?.data && Array.isArray(transformedResult.data)) {
+            for (let i = 0; i < transformedResult.data.length; i++) {
+                if (transformedResult.data[i]?._field_meta)
+                    savedFieldMetaMap.set(i, transformedResult.data[i]._field_meta);
+            }
+        }
+        // Phase 3.9: Validate response against selected DTO (runtime safety net)
+        // Field stripping happens at two levels:
+        // 1. Schema-level (factory time): stripBackendOnlyFields() removes backend-only fields from the schema using .omit()
+        //    - Backend-only fields are stripped except isReturnedAtCreation for CREATE operations
+        // 2. Data-level (runtime): Zod's .parse() automatically strips any fields not in the schema (default behavior)
+        //    - This provides an additional safety layer in case any backend-only fields leak through
+        let responseData = transformedResult;
+        if (selectedDto) {
+            try {
+                // For operations that return arrays (LIST, LIST_MANY, etc.),
+                // validate each item against the selected DTO
+                const operationId = operation.operationIdentifier;
+                const operationLike = operation.resourceOperationLike;
+                const effectiveOperation = operationLike || operationId;
+                const isArrayOperation = ARRAY_RESPONSE_OPERATIONS.includes(effectiveOperation);
+                if (isArrayOperation && Array.isArray(transformedResult)) {
+                    // For array operations, validate each item individually
+                    // Note: Zod's .parse() automatically strips fields not in the schema (default behavior)
+                    responseData = transformedResult.map(item => selectedDto.parse(item));
+                }
+                else {
+                    // For single-item operations, validate directly
+                    // Note: Zod's .parse() automatically strips fields not in the schema (default behavior)
+                    responseData = selectedDto.parse(transformedResult);
+                }
+            }
+            catch (error) {
+                // Phase 3.9: Log warning if validation fails (safety net - this shouldn't happen if factory-time field stripping is correct)
+                this.logger.warn('Response DTO validation failed', {
+                    operation: operation.operationIdentifier,
+                    resourceIdentifier: operation.resourceIdentifier,
+                    dataMode,
+                    error: error instanceof Error ? error.message : 'Unknown',
+                    resultKeys: typeof result === 'object' ? Object.keys(result) : 'not-object'
+                });
+                // Build error and send JSON response directly (don't throw to avoid HTML error page)
+                const wildoError = error instanceof z.ZodError
+                    ? this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                        stack: error.stack,
+                        context: { responseData: result, error: error.message, zodIssues: error.issues }
+                    })
+                    : this.errorBuilder.buildFromStandardError(error, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+                        context: { responseData: result, error: error.message }
+                    });
+                // Extract validationErrors from zodIssues for frontend consumption
+                let validationErrors;
+                if (error instanceof z.ZodError) {
+                    validationErrors = {};
+                    for (const issue of error.issues) {
+                        const fieldPath = issue.path.join('.');
+                        if (fieldPath)
+                            validationErrors[fieldPath] = issue.message;
+                    }
+                }
+                return res.status(wildoError.statusCode).json({
+                    error: {
+                        type: wildoError.type,
+                        severity: wildoError.severity,
+                        message: wildoError.customMessageReference,
+                        timestamp: wildoError.timestamp?.toISOString() || new Date().toISOString(),
+                        ...(wildoError.context && { details: wildoError.context }),
+                        ...(validationErrors && { validationErrors }),
+                    }
+                });
+            }
+        }
+        // CRDT: reattach _field_meta after DTO parse (stripped by Zod since it's not in any resource schema)
+        if (Array.isArray(responseData) && savedFieldMetaMap.size > 0) {
+            for (const [i, meta] of savedFieldMetaMap) {
+                if (responseData[i] && typeof responseData[i] === 'object') {
+                    responseData[i]._field_meta = meta;
+                }
+            }
+        }
+        else if (responseData?.data && Array.isArray(responseData.data) && savedFieldMetaMap.size > 0) {
+            for (const [i, meta] of savedFieldMetaMap) {
+                if (responseData.data[i] && typeof responseData.data[i] === 'object') {
+                    responseData.data[i]._field_meta = meta;
+                }
+            }
+        }
+        else if (savedSingleFieldMeta && responseData && typeof responseData === 'object' && !Array.isArray(responseData)) {
+            responseData._field_meta = savedSingleFieldMeta;
+        }
+        // Phase 3.10 + Q4: Audit logging for isReturnedAtCreation (CREATE) and auditAccess (any operation) fields
+        await this.logAuditAccessForFields(operation, executionContext, responseData, result, selectedDto);
+        if (executionContext.consumableTokenConsumed) {
+            res.setHeader(WildoHeaderKeys.CONSUMABLE_TOKEN_CONSUMED, 'true');
+        }
+        res.setHeader(WildoHeaderKeys.X_SERVER_TIME, String(Date.now()));
+        const statusCode = this.getStatusCodeForOperation(operation, result);
+        res.status(statusCode).json(responseData);
+    }
+    /**
+     * Phase 3.10 + Q4: Log audit access for sensitive backend-only fields.
+     * Two independent triggers:
+     * - CREATE operations: fields with `isReturnedAtCreation: true` (Phase 3.10)
+     * - Any operation: fields with `auditAccess: true` (Q4)
+     *
+     * @param operation - The operation being executed
+     * @param executionContext - Execution context with initiator information
+     * @param responseData - The validated response data (may be array or single object)
+     * @param originalResult - The original result before validation (to get _id for CREATE operations)
+     * @param selectedDto - The selected response DTO schema that was used for validation
+     */
+    async logAuditAccessForFields(operation, executionContext, responseData, originalResult, selectedDto) {
+        try {
+            if (!selectedDto || !isZodObject(selectedDto)) {
+                return;
+            }
+            const operationId = operation.operationIdentifier;
+            const operationLike = operation.resourceOperationLike;
+            const effectiveOperation = operationLike || operationId;
+            const isCreateOperation = effectiveOperation === CoreResourceOperation.CREATE ||
+                effectiveOperation === CoreResourceOperation.CREATE_MANY;
+            const operationIdentifierStr = String(effectiveOperation);
+            const shape = getZodObjectShape(selectedDto);
+            const fieldsToAudit = [];
+            for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+                if (!isBackendOnlyField(fieldSchema))
+                    continue;
+                const backendOnlyParams = getBackendOnlyParams(fieldSchema);
+                // CREATE path: audit fields with isReturnedAtCreation (existing behavior)
+                if (isCreateOperation && backendOnlyParams?.isReturnedAtCreation) {
+                    fieldsToAudit.push(fieldName);
+                    continue;
+                }
+                // Any operation: audit fields with auditAccess: true (Q4)
+                if (isAuditAccessField(fieldSchema)) {
+                    fieldsToAudit.push(fieldName);
+                }
+            }
+            // If no fields to audit, return early
+            if (fieldsToAudit.length === 0) {
+                return;
+            }
+            // Check if any of these fields are present in the response data
+            const checkFieldsInData = (data) => {
+                if (!data || typeof data !== 'object') {
+                    return [];
+                }
+                return fieldsToAudit.filter(fieldName => fieldName in data && data[fieldName] !== undefined);
+            };
+            // Handle array responses (LIST, CREATE_MANY, etc.)
+            if (Array.isArray(responseData)) {
+                for (const item of responseData) {
+                    const fieldsPresent = checkFieldsInData(item);
+                    if (fieldsPresent.length > 0) {
+                        // Get resource ID from item or original result
+                        const resourceId = item?._id || (Array.isArray(originalResult) ? originalResult.find(r => r?._id)?._id : originalResult?._id);
+                        for (const fieldName of fieldsPresent) {
+                            await this.auditLogsService.logFieldAccess({
+                                fieldName,
+                                resourceType: operation.resourceIdentifier,
+                                resourceId: resourceId,
+                                userId: executionContext.initiatorIds?.userId,
+                                organizationId: executionContext.initiatorIds?.organizationId,
+                                applicationId: executionContext.initiatorIds?.applicationId,
+                                operationIdentifier: operationIdentifierStr,
+                                isCreateOperation,
+                            });
+                        }
+                    }
+                }
+            }
+            else {
+                // Single object response
+                const fieldsPresent = checkFieldsInData(responseData);
+                if (fieldsPresent.length > 0) {
+                    // Get resource ID from response data or original result
+                    const resourceId = responseData?._id || originalResult?._id;
+                    for (const fieldName of fieldsPresent) {
+                        await this.auditLogsService.logFieldAccess({
+                            fieldName,
+                            resourceType: operation.resourceIdentifier,
+                            resourceId: resourceId,
+                            userId: executionContext.initiatorIds?.userId,
+                            organizationId: executionContext.initiatorIds?.organizationId,
+                            applicationId: executionContext.initiatorIds?.applicationId,
+                            operationIdentifier: operationIdentifierStr,
+                            isCreateOperation,
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Don't let audit logging break the main flow
+            this.logger.warn('Failed to log audit access for fields', {
+                operation: operation.operationIdentifier,
+                resourceIdentifier: operation.resourceIdentifier,
+                error: error instanceof Error ? error.message : 'Unknown',
+            });
+        }
+    }
+    getHttpMethodForOperation(operation) {
+        const operationToCheck = ResourceOperationsUtils.getCoreResourceOperationFromOperation(operation);
+        if (!operationToCheck) {
+            this.logDebug('No HTTP method found for operation, defaulting to POST', { operation: operation.operationIdentifier });
+            return HttpMethod.POST;
+        }
+        return HTTP_METHOD_MAP[operationToCheck] || HttpMethod.POST;
+    }
+    getStatusCodeForOperation(operation, result) {
+        const notFoundableOperations = [
+            CoreResourceOperation.DELETE,
+            CoreResourceOperation.UPDATE_MANY,
+            CoreResourceOperation.DELETE_MANY,
+            CoreResourceOperation.READ,
+            CoreResourceOperation.UPDATE
+        ];
+        const operationToCheck = ResourceOperationsUtils.getCoreResourceOperationFromOperation(operation);
+        if (!operationToCheck) {
+            this.logDebug('No HTTP method found for operation, defaulting to 200', { operation: operation.operationIdentifier });
+            return 200;
+        }
+        return (operationToCheck === CoreResourceOperation.CREATE || operationToCheck === CoreResourceOperation.CREATE_MANY)
+            ? 201
+            : (notFoundableOperations.includes(operationToCheck)
+                ? result ? 200 : 404
+                : 200);
+    }
+}
+//# sourceMappingURL=controller-resource.backend.service.js.map