@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/resources/services/resource-context.backend.service.js

@@ -0,0 +1,723 @@
+/**
+ * Resource Context Backend Service
+ *
+ * Responsible for building the ResourceContext object that contains
+ * the primary resource and related parent/child resources.
+ * Supports configurable depth, per-relationship overrides, and access rights checking.
+ *
+ * ## Conditional Relationship Handling (discriminator + condition)
+ *
+ * This service evaluates conditional relationships differently depending on direction:
+ *
+ * ### Fetching CHILDREN (fetchChildResourcesWithPolicy)
+ * Discriminator and condition are checked BEFORE querying child resources.
+ * The check is performed against the `parentResource` parameter — the resource
+ * we're looking DOWN from. If the discriminator doesn't match or the condition
+ * returns false, the entire child relationship is skipped (no DB query is issued).
+ *
+ * For recursive child traversal (depth > 1), the `rawChild` becomes the
+ * `parentResource` in the recursive call, so grandchild relationships are
+ * correctly evaluated against their immediate parent.
+ *
+ * ### Fetching PARENTS (fetchParentResourcesWithPolicy)
+ * Discriminator/condition checks are intentionally NOT performed.
+ * Rationale: the discriminator describes a condition on the PARENT resource,
+ * but when looking UP from a child, we don't have the parent data yet.
+ * The old behavior (checking the child resource) was incorrect — the child
+ * doesn't carry the discriminator field. Parents are always fetchable for
+ * navigation purposes.
+ *
+ * ### Shared activation semantics
+ * Runtime activation is now resolved through
+ * `Resources_SharedUtils.isRelationshipActiveForParent()`. That shared helper
+ * preserves the same discriminator `String()` coercion semantics used across
+ * backend and frontend while letting each caller choose its condition
+ * error-handling mode.
+ *
+ * @see ResourceRelationship — for discriminator/condition type definitions
+ */
+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 { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { isOneToOneCardinality, CoreResourceOperation, ContextPolicy_ObjectMode, ContextPolicy_AccessRightsMode, DEFAULT_RELATIONSHIP_CONTEXT_POLICY, ErrorType, ErrorCustomMessageReference, getChildDirectionRelationships, getParentDirectionRelationships, Resources_SharedUtils, } from '@wildo-ai/saas-models';
+import { isSummaryField, getZodObjectShape } from '@wildo-ai/zod-decorators';
+import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
+import { ResourcesRegistryBackendService } from './resources-registry.backend.service.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+/**
+ * Default context configuration
+ */
+export const DEFAULT_CONTEXT_CONFIGURATION = {
+    enabled: true,
+    parentDepth: 1,
+    childDepth: 1, // Changed from 0 to 1 to allow child fetching based on relationship contextPolicy
+    accessRightsMode: ContextPolicy_AccessRightsMode.USER_FILTERED,
+    objectMode: ContextPolicy_ObjectMode.SUMMARY,
+    parentOverrides: [],
+    childOverrides: [],
+};
+// =============================================================================
+// SERVICE IMPLEMENTATION
+// =============================================================================
+/**
+ * Service for building resource context objects.
+ *
+ * The context includes the primary resource and related parent/child resources
+ * based on the resource's relationship configuration.
+ *
+ * Architecture (see CONTEXT_FETCH_DTO_ARCHITECTURE_ANALYSIS.md):
+ * - Fetches via RepositoriesRegistry (raw data)
+ * - Computes virtual fields via VirtualFieldsService
+ * - Strips backend-only fields via operation's responseDto (from DTO builder)
+ * - Extracts summary fields based on isSummaryField() decorator
+ */
+let ResourceContextBackendService = class ResourceContextBackendService {
+    resourcesRegistry;
+    logger;
+    errorBuilder;
+    repositoriesRegistry;
+    virtualFieldsService;
+    executionContextCreator;
+    logDebug;
+    constructor(resourcesRegistry, logger, errorBuilder, repositoriesRegistry, virtualFieldsService, executionContextCreator) {
+        this.resourcesRegistry = resourcesRegistry;
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.virtualFieldsService = virtualFieldsService;
+        this.executionContextCreator = executionContextCreator;
+        this.logDebug = this.logger.debugByType('ResourceContextBackendService');
+        this.logger.setDebugTypeLogging('ResourceContextBackendService', false);
+        this.logDebug('Resource context service created');
+    }
+    // =============================================================================
+    // BACKEND-ONLY FIELD STRIPPING
+    // =============================================================================
+    /**
+     * Strip backend-only fields from data using operation's responseDto.
+     * The responseDto already has backend-only fields stripped by the DTO builder.
+     *
+     * @param resourceType - The resource type
+     * @param data - The data object to strip fields from
+     * @param operation - The operation type (READ, LIST, etc.)
+     * @returns Data with backend-only fields removed
+     */
+    stripBackendOnlyFieldsFromData(resourceType, data, operation) {
+        if (!data || typeof data !== 'object') {
+            return data;
+        }
+        // Get the operation's responseDto (already has backend-only fields stripped)
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, operation);
+        const operationConfig = this.resourcesRegistry.getOperationFromPath(operationPath);
+        if (!operationConfig?.responseDto) {
+            // No responseDto available - this is a configuration error
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND,
+                context: { resourceType, operationIdentifier: operation, reason: 'No responseDto found' }
+            });
+        }
+        // Parse data through responseDto schema to strip backend-only fields
+        // Using safeParse to handle cases where data might have extra fields
+        const result = operationConfig.responseDto.safeParse(data);
+        if (result.success) {
+            return result.data;
+        }
+        else {
+            // If parsing fails, return original data
+            // This handles cases where data has fields not in the schema
+            this.logDebug(`[ResourceContext] Failed to parse data through responseDto for ${resourceType}, falling back to original data`, {
+                errors: result.error.issues
+            });
+            return data;
+        }
+    }
+    // =============================================================================
+    // EXECUTION CONTEXT HELPERS
+    // =============================================================================
+    /**
+     * Get or create an execution context for internal operations.
+     *
+     * If an execution context is provided, it is returned as-is.
+     * Otherwise, creates a new execution context for internal operations using the
+     * READ operation of the specified resource type.
+     *
+     * @param resourceType - The resource type to get the operation for
+     * @param providedContext - Optional existing execution context
+     * @returns A valid execution context for repository operations
+     */
+    async getOrCreateExecutionContext(resourceType, operationIdentifier, providedContext, resourceId, relationshipContext) {
+        if (providedContext) {
+            // Create a proper sub-call context with the correct operation for this resource
+            return this.executionContextCreator.createForSubCall(providedContext, resourceType, operationIdentifier, undefined, // ServiceOptions
+            resourceId, relationshipContext);
+        }
+        // No parent context - create an internal operation context
+        const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, operationIdentifier);
+        return this.executionContextCreator.createForInternalOperation({
+            operation: operationPath,
+            contextResourcesFieldIdentifier: new Map(),
+            initiatorIds: null,
+            initiatorRoles: [],
+        });
+    }
+    // =============================================================================
+    // RELATIONSHIP-LEVEL CONTEXT POLICY RESOLUTION
+    // =============================================================================
+    /**
+     * Resolve effective context policy for a relationship and operation.
+     *
+     * Priority order:
+     * 1. relationship.contextPolicy.operationOverrides[operation] (if operation provided)
+     * 2. relationship.contextPolicy (base policy)
+     * 3. DEFAULT_RELATIONSHIP_CONTEXT_POLICY
+     *
+     * Special handling:
+     * - Self-referencing relationships are capped at depth: 1 (Edge Case #3)
+     *
+     * @param relationship - The relationship to resolve policy for
+     * @param operation - Optional operation for operation-specific overrides
+     * @returns The fully resolved effective policy with all fields required
+     */
+    resolveEffectiveContextPolicy(relationship, operation) {
+        const basePolicy = relationship.contextPolicy ?? {};
+        // Start with defaults
+        const effective = { ...DEFAULT_RELATIONSHIP_CONTEXT_POLICY };
+        // Apply base policy
+        if (basePolicy.enabled !== undefined)
+            effective.enabled = basePolicy.enabled;
+        if (basePolicy.depth !== undefined)
+            effective.depth = basePolicy.depth;
+        if (basePolicy.objectMode !== undefined)
+            effective.objectMode = basePolicy.objectMode;
+        if (basePolicy.accessRightsMode !== undefined)
+            effective.accessRightsMode = basePolicy.accessRightsMode;
+        // Apply operation override if present
+        if (operation && basePolicy.operationOverrides?.[operation]) {
+            const override = basePolicy.operationOverrides[operation];
+            if (override.enabled !== undefined)
+                effective.enabled = override.enabled;
+            if (override.depth !== undefined)
+                effective.depth = override.depth;
+            if (override.objectMode !== undefined)
+                effective.objectMode = override.objectMode;
+            if (override.accessRightsMode !== undefined)
+                effective.accessRightsMode = override.accessRightsMode;
+        }
+        // Edge Case #3: Cap depth for self-referencing relationships
+        if (relationship.resourceType1 === relationship.resourceType2) {
+            const originalDepth = effective.depth;
+            effective.depth = Math.min(effective.depth, 1);
+            if (originalDepth > 1) {
+                this.logDebug(`[ResourceContext] Self-reference depth capped from ${originalDepth} to 1 for ${relationship.resourceType1}`);
+            }
+        }
+        return effective;
+    }
+    /**
+     * Build a resource context for a given resource.
+     *
+     * @param resourceType - The resource type identifier
+     * @param resourceId - The ID of the resource
+     * @param resource - The resource data (already fetched)
+     * @param options - Optional configuration overrides
+     * @returns The complete ResourceContext
+     */
+    async buildContext(resourceType, resourceId, resource, options) {
+        const config = this.resourcesRegistry.tryGetResourceConfiguration(resourceType);
+        if (!config) {
+            this.logger.warn(`[ResourceContext] No configuration found for resource type: ${resourceType}`);
+            return this.createEmptyContext(resourceType, resourceId, resource, options);
+        }
+        // Merge default configuration with options overrides
+        // Note: contextConfiguration is not yet implemented on ResourceConfiguration
+        const effectiveConfig = this.mergeConfiguration(DEFAULT_CONTEXT_CONFIGURATION, {}, // contextConfiguration - not yet implemented
+        options || {});
+        if (!effectiveConfig.enabled) {
+            return this.createEmptyContext(resourceType, resourceId, resource, effectiveConfig);
+        }
+        const finalConfig = effectiveConfig;
+        // Extract operation for relationship-level policy resolution
+        const operation = options?.operation;
+        const parentDirRelationships = config.resourceRelationships
+            ? getParentDirectionRelationships(config.resourceRelationships)
+            : [];
+        const childDirRelationships = config.resourceRelationships
+            ? getChildDirectionRelationships(config.resourceRelationships)
+            : [];
+        this.logDebug(`[buildContext] Building context for ${resourceType}:${resourceId}`, {
+            operation,
+            parentRelationshipsCount: parentDirRelationships.length,
+            childRelationshipsCount: childDirRelationships.length,
+            selfRelationshipsCount: (config.resourceRelationships?.selfRelationships || []).length,
+            parentRelationshipTypes: parentDirRelationships.map(r => r.resourceType1),
+            childRelationshipTypes: childDirRelationships.map(r => r.resourceType2),
+        });
+        // Fetch parent resources using relationship-level context policy
+        const parents = await this.fetchParentResourcesWithPolicy(resourceType, resource, parentDirRelationships, finalConfig, operation, options?.executionContext);
+        // Fetch child resources using relationship-level context policy
+        const children = await this.fetchChildResourcesWithPolicy(resourceType, resourceId, resource, childDirRelationships, finalConfig, operation, options?.executionContext);
+        this.logDebug(`[buildContext] Fetch completed for ${resourceType}:${resourceId}`, {
+            parentKeys: Object.keys(parents),
+            parentCounts: Object.entries(parents).map(([k, v]) => `${k}:${v.length}`),
+            childKeys: Object.keys(children),
+            childCounts: Object.entries(children).map(([k, v]) => `${k}:${v.length}`),
+        });
+        return {
+            resource,
+            metadata: {
+                resourceType,
+                resourceId,
+                fetchedAt: new Date(),
+            },
+            parents,
+            children,
+            configuration: finalConfig,
+        };
+    }
+    /**
+     * Create an empty context (used when context building is disabled or fails)
+     */
+    createEmptyContext(resourceType, resourceId, resource, config) {
+        return {
+            resource,
+            metadata: {
+                resourceType,
+                resourceId,
+                fetchedAt: new Date(),
+            },
+            parents: {},
+            children: {},
+            configuration: { ...DEFAULT_CONTEXT_CONFIGURATION, ...config },
+        };
+    }
+    /**
+     * Merge multiple configuration objects (later objects override earlier ones)
+     */
+    mergeConfiguration(...configs) {
+        const result = { ...DEFAULT_CONTEXT_CONFIGURATION };
+        for (const config of configs) {
+            if (config.enabled !== undefined)
+                result.enabled = config.enabled;
+            if (config.parentDepth !== undefined)
+                result.parentDepth = config.parentDepth;
+            if (config.childDepth !== undefined)
+                result.childDepth = config.childDepth;
+            if (config.accessRightsMode !== undefined)
+                result.accessRightsMode = config.accessRightsMode;
+            if (config.objectMode !== undefined)
+                result.objectMode = config.objectMode;
+            if (config.parentOverrides) {
+                result.parentOverrides = [...(result.parentOverrides || []), ...config.parentOverrides];
+            }
+            if (config.childOverrides) {
+                result.childOverrides = [...(result.childOverrides || []), ...config.childOverrides];
+            }
+        }
+        return result;
+    }
+    // applyInheritanceConfiguration was removed — it was dead code (always called with
+    // undefined inheritanceContextConfigs). Context configuration overrides for discriminated
+    // union variants are handled by the discriminator/condition checks on each relationship.
+    // matchesInheritancePath was removed — dead code.
+    /**
+     * Fetch parent resources using relationship-level context policy.
+     *
+     * Iterates parent relationships (where current resource is the child) and fetches
+     * each parent resource via its FK field.
+     *
+     * **Discriminator/condition checks are intentionally NOT performed here.**
+     * The discriminator describes a condition on the PARENT resource, but at this
+     * point we're looking UP from the child and don't have the parent data yet.
+     * Checking the child resource (old behavior) was incorrect — the child doesn't
+     * carry the discriminator field. The parent is always fetchable for navigation
+     * purposes; it's the child→parent direction that is unconditional.
+     *
+     * Implements:
+     * - Edge Case #1: Multiple FKs to same type (uses relationshipField for disambiguation)
+     * - Edge Case #3: Circular reference protection via visited set
+     * - Recursive depth traversal (depth > 1 fetches grandparents)
+     */
+    async fetchParentResourcesWithPolicy(resourceType, resource, parentRelationships, config, operation, executionContext, visited = new Set()) {
+        const result = {};
+        // Fallback to legacy behavior if parentDepth is 0
+        if (!config.parentDepth || config.parentDepth <= 0) {
+            return result;
+        }
+        for (const relationship of parentRelationships) {
+            // Note: discriminator/condition checks are intentionally NOT performed here.
+            // The discriminator describes a condition on the PARENT resource, but at this point
+            // we're looking UP from the child and don't have the parent data yet.
+            // Checking the child resource (old behavior) was wrong — the child doesn't carry the
+            // discriminator field. The parent is always fetchable for navigation purposes.
+            // Resolve effective policy for this relationship and operation
+            const policy = this.resolveEffectiveContextPolicy(relationship, operation);
+            // Skip if disabled or depth is 0
+            if (!policy.enabled || policy.depth <= 0) {
+                this.logDebug(`[ResourceContext] Skipping parent ${relationship.resourceType1} - ` +
+                    `enabled: ${policy.enabled}, depth: ${policy.depth}`);
+                continue;
+            }
+            // Get FK field using centralized resolution (explicit foreignKeyField or from allResourceFieldIdentifiers)
+            const fkField = this.resourcesRegistry.resolveForeignKeyField({
+                resourceType1: relationship.resourceType1,
+                foreignKeyField: relationship.foreignKeyField,
+            });
+            const parentId = resource[fkField];
+            if (!parentId) {
+                continue;
+            }
+            // Edge Case #3: Circular reference protection
+            const circularKey = `${relationship.resourceType1}:${parentId}`;
+            if (visited.has(circularKey)) {
+                this.logDebug(`[ResourceContext] Skipping circular reference: ${circularKey}`);
+                continue;
+            }
+            visited.add(circularKey);
+            try {
+                const effectiveObjectMode = policy.objectMode;
+                // Build relationship context to track how we're accessing the parent
+                const relationshipContext = {
+                    resourceType: resourceType, // Current resource type
+                    relationshipField: fkField, // FK field on current resource pointing to parent
+                    resourceId: resource._id?.toString() || resource.id, // Current resource ID
+                };
+                // Fetch resource with appropriate mode transformation
+                const data = await this.fetchResourceByMode(relationship.resourceType1, parentId, policy.objectMode, executionContext, relationshipContext);
+                if (data) {
+                    const contextItem = {
+                        resourceType: relationship.resourceType1,
+                        resourceId: parentId,
+                        data,
+                        objectMode: effectiveObjectMode,
+                        relationshipField: fkField, // Edge Case #1: Include for disambiguation
+                    };
+                    result[relationship.resourceType1] = result[relationship.resourceType1] || [];
+                    result[relationship.resourceType1].push(contextItem);
+                    // Handle recursive depth > 1 (with visited set for circular protection)
+                    // Note: Self-references are already capped to depth 1 in resolveEffectiveContextPolicy
+                    if (policy.depth > 1 && policy.objectMode !== ContextPolicy_ObjectMode.ID_ONLY) {
+                        this.logDebug(`[ResourceContext] Recursively fetching context for ${relationship.resourceType1}:${parentId} with depth ${policy.depth - 1}`);
+                        // Fetch nested parent context
+                        const nestedParents = await this.fetchRecursiveParentContext(relationship.resourceType1, data, policy.depth - 1, operation, executionContext, visited);
+                        // Attach nested context to the item
+                        if (Object.keys(nestedParents).length > 0) {
+                            contextItem.nestedParents = nestedParents;
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.warn(`[ResourceContext] Failed to fetch parent ${relationship.resourceType1}:`, error);
+            }
+        }
+        return result;
+    }
+    /**
+     * Fetch child resources using relationship-level context policy.
+     *
+     * Iterates child relationships (where current resource is the parent) and queries
+     * children by FK. Before issuing any DB query, evaluates conditional filters:
+     *
+     * 1. **Static discriminator**: If the relationship has a `discriminator`, checks
+     *    `String(parentResource[discriminatorField])` against `values`. If no match,
+     *    the entire child type is skipped (no query issued).
+     *
+     * 2. **Function-based condition**: If the relationship has a `condition` function,
+     *    calls `condition(parentResource)`. If it returns false, the child type is skipped.
+     *
+     * Both checks use AND semantics — if both are present, both must pass.
+     * The checks are performed against the `parentResource` parameter, which is the
+     * actual data of the parent we are looking DOWN from.
+     *
+     * **Recursive traversal**: When `depth > 1`, each fetched child becomes the
+     * `parentResource` in a recursive call. This means grandchild relationships
+     * are correctly evaluated against their immediate parent (the child), not
+     * against the original top-level parent.
+     *
+     * Implements:
+     * - Discriminator/condition check on PARENT resource BEFORE fetching children
+     * - Edge Case #3: Circular reference protection via visited set
+     * - 1:1 vs 1:N cardinality-aware fetching (READ vs LIST operations)
+     *
+     * @param resourceType - The parent resource type
+     * @param resourceId - The parent resource's ID
+     * @param parentResource - The parent resource's actual data (used for discriminator/condition evaluation)
+     * @param childRelationships - The child relationships to traverse
+     * @param config - Context configuration (controls depth, object mode, etc.)
+     * @param operation - The current operation (READ, LIST, etc.)
+     * @param executionContext - The current execution context
+     * @param visited - Circular reference protection set
+     */
+    async fetchChildResourcesWithPolicy(resourceType, resourceId, parentResource, childRelationships, config, operation, executionContext, visited = new Set()) {
+        const result = {};
+        // Fallback to legacy behavior if childDepth is 0
+        if (!config.childDepth || config.childDepth <= 0) {
+            return result;
+        }
+        for (const relationship of childRelationships) {
+            const isRelationshipActive = Resources_SharedUtils.isRelationshipActiveForParent(relationship, parentResource, {
+                onConditionError: 'throw',
+            });
+            if (!isRelationshipActive) {
+                if (relationship.discriminator || relationship.condition) {
+                    this.logDebug(`[ResourceContext] Skipping children ${relationship.resourceType2} - parent activation check failed`);
+                }
+                continue;
+            }
+            // Resolve effective policy for this relationship and operation
+            const policy = this.resolveEffectiveContextPolicy(relationship, operation);
+            // Skip if disabled or depth is 0
+            if (!policy.enabled || policy.depth <= 0) {
+                this.logDebug(`[ResourceContext] Skipping children ${relationship.resourceType2} - ` +
+                    `enabled: ${policy.enabled}, depth: ${policy.depth}`);
+                continue;
+            }
+            const effectiveObjectMode = policy.objectMode;
+            try {
+                // Get repository for child resource type
+                const childRepository = this.repositoriesRegistry.getRepository(relationship.resourceType2);
+                if (!childRepository) {
+                    this.logger.warn(`[ResourceContext] No repository found for ${relationship.resourceType2}`);
+                    continue;
+                }
+                // Determine the FK field on the child that references the parent
+                // For relationship Parent → Child, the child has a field like parentId
+                // We resolve using the parent resource type (resourceType1)
+                const parentFkField = this.resourcesRegistry.resolveForeignKeyField({
+                    resourceType1: resourceType, // Parent type for FK naming
+                    foreignKeyField: relationship.foreignKeyField, // Explicit override if specified
+                });
+                // Include relationship context to track how we got here
+                const relationshipContext = {
+                    resourceType: resourceType,
+                    relationshipField: parentFkField,
+                    resourceId: resourceId
+                };
+                // Determine if this is a 1:1 or 1:many relationship based on cardinality2
+                // 1:1 relationships (ONE, ZERO_OR_ONE) don't have LIST operations - use READ with filter
+                // 1:many relationships (MANY, ONE_OR_MANY) use LIST
+                const isOneToOne = isOneToOneCardinality(relationship.cardinality2);
+                // Query children by parent FK
+                const filter = { [parentFkField]: resourceId };
+                this.logDebug(`[ResourceContext] Fetching children of type ${relationship.resourceType2} ` +
+                    `for ${resourceType}:${resourceId} with filter ${JSON.stringify(filter)} ` +
+                    `(1:1=${isOneToOne}, cardinality2=${relationship.cardinality2})`);
+                // Determine the operation to use based on relationship cardinality
+                const childOperation = isOneToOne ? CoreResourceOperation.READ : CoreResourceOperation.LIST;
+                // Create execution context for the child fetch
+                const ctx = await this.getOrCreateExecutionContext(relationship.resourceType2, childOperation, executionContext, undefined, // ID will be determined by filter (or none for LIST)
+                relationshipContext);
+                let childItems = [];
+                if (isOneToOne) {
+                    // For 1:1 relationships, use READ operation with filter (no LIST available)
+                    // Use repository's read() method which accepts filter
+                    const singleResult = await childRepository.read(ctx, filter);
+                    if (singleResult) {
+                        childItems = [singleResult];
+                    }
+                }
+                else {
+                    // For 1:many relationships, use LIST operation
+                    // Use doByPath with LIST operation and filter
+                    const listResult = await childRepository.doByPath({ resourceIdentifier: relationship.resourceType2, operationIdentifier: CoreResourceOperation.LIST }, ctx, filter);
+                    // Extract items from paginated result
+                    childItems = Array.isArray(listResult)
+                        ? listResult
+                        : (listResult?.items || listResult?.data || []);
+                }
+                result[relationship.resourceType2] = result[relationship.resourceType2] || [];
+                for (const rawChild of childItems) {
+                    const childId = rawChild._id?.toString() || rawChild.id;
+                    // Edge Case #3: Circular reference protection
+                    const circularKey = `${relationship.resourceType2}:${childId}`;
+                    if (visited.has(circularKey)) {
+                        this.logDebug(`[ResourceContext] Skipping circular child reference: ${circularKey}`);
+                        continue;
+                    }
+                    visited.add(circularKey);
+                    // Transform based on object mode
+                    let transformedData;
+                    if (policy.objectMode === ContextPolicy_ObjectMode.ID_ONLY) {
+                        transformedData = { _id: childId };
+                    }
+                    else {
+                        // Compute virtual fields
+                        const forSummary = policy.objectMode === ContextPolicy_ObjectMode.SUMMARY;
+                        const withVirtuals = await this.virtualFieldsService.computeVirtualFields(relationship.resourceType2, rawChild, ctx, { forSummary });
+                        // Strip backend-only fields using operation's responseDto (already has backend-only fields stripped)
+                        // Use childOperation (READ for 1:1, LIST for 1:many) to find the correct responseDto
+                        const stripped = this.stripBackendOnlyFieldsFromData(relationship.resourceType2, withVirtuals, childOperation);
+                        // Extract summary if needed
+                        transformedData = forSummary
+                            ? this.extractSummaryFields(stripped, relationship.resourceType2)
+                            : stripped;
+                    }
+                    const contextItem = {
+                        resourceType: relationship.resourceType2,
+                        resourceId: childId,
+                        data: transformedData,
+                        objectMode: effectiveObjectMode,
+                        cardinality: relationship.cardinality2,
+                    };
+                    result[relationship.resourceType2].push(contextItem);
+                    // Handle recursive depth > 1 for children
+                    if (policy.depth > 1 && policy.objectMode !== ContextPolicy_ObjectMode.ID_ONLY) {
+                        const childConfig = this.resourcesRegistry.tryGetResourceConfiguration(relationship.resourceType2);
+                        if (childConfig?.resourceRelationships) {
+                            const nestedChildRels = getChildDirectionRelationships(childConfig.resourceRelationships);
+                            const nestedChildren = await this.fetchChildResourcesWithPolicy(relationship.resourceType2, childId, rawChild, nestedChildRels, { ...config, childDepth: policy.depth - 1 }, operation, executionContext, visited);
+                            if (Object.keys(nestedChildren).length > 0) {
+                                contextItem.nestedChildren = nestedChildren;
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.warn(`[ResourceContext] Failed to fetch children ${relationship.resourceType2}:`, error);
+            }
+        }
+        return result;
+    }
+    // =============================================================================
+    // CORE FETCH & TRANSFORMATION METHODS
+    // =============================================================================
+    /**
+     * Fetch a single resource by ID with the specified object mode transformation.
+     *
+     * Processing flow:
+     * 1. ID_ONLY: Return { _id: id } without DB call
+     * 2. SUMMARY/FULL:
+     *    a. Fetch from repository
+     *    b. Compute virtual fields (forSummary if SUMMARY mode)
+     *    c. Strip backend-only fields
+     *    d. Extract summary fields if SUMMARY mode
+     *
+     * @param resourceType - The resource type to fetch
+     * @param resourceId - The ID of the resource
+     * @param objectMode - What level of detail to include
+     * @param executionContext - Execution context for authorization
+     * @returns The fetched and transformed resource data
+     */
+    async fetchResourceByMode(resourceType, resourceId, objectMode, executionContext, relationshipContext) {
+        // ID_ONLY: No database fetch needed
+        if (objectMode === ContextPolicy_ObjectMode.ID_ONLY) {
+            return { _id: resourceId };
+        }
+        try {
+            // Get repository for this resource type
+            const repository = this.repositoriesRegistry.getRepository(resourceType);
+            if (!repository) {
+                this.logger.warn(`[ResourceContext] No repository found for ${resourceType}`);
+                return { _id: resourceId }; // Fallback to ID only
+            }
+            // Create sub-call context with correct operation for READ
+            const ctx = await this.getOrCreateExecutionContext(resourceType, CoreResourceOperation.READ, executionContext, resourceId, relationshipContext);
+            // Fetch raw data via repository READ operation
+            const rawData = await repository.doByPath({ resourceIdentifier: resourceType, operationIdentifier: CoreResourceOperation.READ }, ctx, resourceId);
+            if (!rawData) {
+                return null;
+            }
+            // Compute virtual fields
+            const forSummary = objectMode === ContextPolicy_ObjectMode.SUMMARY;
+            const withVirtuals = await this.virtualFieldsService.computeVirtualFields(resourceType, rawData, ctx, { forSummary });
+            // Strip backend-only fields using operation's responseDto (already has backend-only fields stripped)
+            const stripped = this.stripBackendOnlyFieldsFromData(resourceType, withVirtuals, CoreResourceOperation.READ);
+            // Extract summary fields if SUMMARY mode
+            if (objectMode === ContextPolicy_ObjectMode.SUMMARY) {
+                return this.extractSummaryFields(stripped, resourceType);
+            }
+            return stripped;
+        }
+        catch (error) {
+            this.logger.warn(`[ResourceContext] Failed to fetch ${resourceType}:${resourceId}`, error);
+            return { _id: resourceId }; // Fallback to ID only on error
+        }
+    }
+    /**
+     * Extract only fields marked with isSummaryField() decorator.
+     * Uses schema metadata from the resource registry.
+     *
+     * @param data - The full resource data
+     * @param resourceType - The resource type for schema lookup
+     * @returns Object with only summary fields (always includes _id)
+     */
+    extractSummaryFields(data, resourceType) {
+        if (!data) {
+            return data;
+        }
+        const config = this.resourcesRegistry.tryGetResourceConfiguration(resourceType);
+        if (!config) {
+            return { _id: data._id };
+        }
+        const schema = config.mainSchema;
+        try {
+            const shape = getZodObjectShape(schema);
+            const result = { _id: data._id }; // Always include ID
+            for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+                if (isSummaryField(fieldSchema)) {
+                    if (fieldName in data) {
+                        result[fieldName] = data[fieldName];
+                    }
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            this.logger.warn(`[ResourceContext] Failed to extract summary fields for ${resourceType}`, error);
+            return { _id: data._id };
+        }
+    }
+    /**
+     * Recursively fetch parent context for a resource.
+     * Used when depth > 1 to build nested context.
+     *
+     * @param resourceType - The parent resource type
+     * @param resourceData - The parent resource data (already fetched)
+     * @param remainingDepth - How many more levels to fetch
+     * @param operation - The current operation for policy resolution
+     * @param executionContext - Execution context
+     * @param visited - Set of already-visited resources (for circular protection)
+     */
+    async fetchRecursiveParentContext(resourceType, resourceData, remainingDepth, operation, executionContext, visited = new Set()) {
+        if (remainingDepth <= 0) {
+            return {};
+        }
+        const config = this.resourcesRegistry.getResourceConfiguration(resourceType);
+        if (!config?.resourceRelationships) {
+            return {};
+        }
+        const parentDirRels = getParentDirectionRelationships(config.resourceRelationships);
+        // Build config with reduced depth
+        const recursiveConfig = {
+            ...DEFAULT_CONTEXT_CONFIGURATION,
+            parentDepth: remainingDepth,
+        };
+        return this.fetchParentResourcesWithPolicy(resourceType, resourceData, parentDirRels, recursiveConfig, operation, executionContext, visited);
+    }
+};
+ResourceContextBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(1, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.VirtualFieldsService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __metadata("design:paramtypes", [ResourcesRegistryBackendService,
+        LoggerService,
+        ErrorBuilderBackendService, Function, Function, Function])
+], ResourceContextBackendService);
+export { ResourceContextBackendService };
+//# sourceMappingURL=resource-context.backend.service.js.map