@wildo-ai/saas-backend-lib 1.0.1

package/src/resources/services/resource-context.backend.service.ts

@@ -0,0 +1,1107 @@
+/**
+ * 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
+ */
+
+import { injectable, inject } from 'inversify';
+import { z } from 'zod';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import {
+  ResourceType,
+  ResourceRelationship,
+  ResourceRelationshipCardinality,
+  isOneToOneCardinality,
+  CoreResourceOperation,
+  RelationshipContextPolicy,
+  ContextPolicy_ObjectMode,
+  ContextPolicy_AccessRightsMode,
+  DEFAULT_RELATIONSHIP_CONTEXT_POLICY,
+  ExecutionContext_RelationshipContext,
+  ErrorType,
+  ErrorCustomMessageReference,
+  getChildDirectionRelationships,
+  getParentDirectionRelationships,
+  Resources_SharedUtils,
+} from '@wildo-ai/saas-models';
+import { isSummaryField, getZodObjectShape } from '@wildo-ai/zod-decorators';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ResourcesRegistryBackendService } from './resources-registry.backend.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import type { VirtualFieldsBackendService } from './virtual-fields.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import type { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+
+// =============================================================================
+// EFFECTIVE CONTEXT POLICY TYPE
+// =============================================================================
+
+/**
+ * Resolved effective context policy after merging defaults, base policy, and operation overrides.
+ * All fields are required (filled from defaults if not specified).
+ */
+export type EffectiveContextPolicy = Required<Omit<RelationshipContextPolicy, 'operationOverrides'>>;
+
+// =============================================================================
+// TYPE DEFINITIONS
+// =============================================================================
+
+/**
+ * Override configuration for a specific relationship
+ */
+export interface ResourceContextRelationshipOverride {
+  /** The relationship resource type to override */
+  resourceType: ResourceType;
+  /** Set to true to disable fetching this relationship */
+  disabled?: boolean;
+  /** Override depth for this relationship */
+  depth?: number;
+  /** Override object mode for this relationship */
+  objectMode?: ContextPolicy_ObjectMode;
+}
+
+/**
+ * Configuration for building a resource context
+ */
+export interface ResourceContextConfiguration {
+  /** Whether context building is enabled */
+  enabled?: boolean;
+  /** Maximum depth for parent relationships (0 = no parents) */
+  parentDepth?: number;
+  /** Maximum depth for child relationships (0 = no children) */
+  childDepth?: number;
+  /** Access rights mode for filtering relationships */
+  accessRightsMode?: ContextPolicy_AccessRightsMode;
+  /** Default object mode for relationships */
+  objectMode?: ContextPolicy_ObjectMode;
+  /** Per-relationship overrides for parent relationships */
+  parentOverrides?: ResourceContextRelationshipOverride[];
+  /** Per-relationship overrides for child relationships */
+  childOverrides?: ResourceContextRelationshipOverride[];
+}
+
+/**
+ * A single related resource item
+ */
+export interface ResourceContextItem<T = any> {
+  resourceType: ResourceType;
+  resourceId: string;
+  data: T;
+  objectMode: ContextPolicy_ObjectMode;
+  /**
+   * The relationship field this item came from (for disambiguation when multiple FKs to same type)
+   * @example 'assignedToUserId' or 'createdByUserId' for TODOS → USERS relationships
+   */
+  relationshipField?: string;
+  /**
+   * Cardinality of the relationship (ONE/ZERO_OR_ONE for 1:1, MANY/ONE_OR_MANY for 1:many)
+   * Used to determine if result should be a single object or array
+   */
+  cardinality?: ResourceRelationshipCardinality;
+  /**
+   * Nested parent context when depth > 1.
+   * Only populated when the relationship contextPolicy specifies depth > 1.
+   */
+  nestedParents?: Record<ResourceType, ResourceContextItem[]>;
+  /**
+   * Nested child context when child depth > 1.
+   * Only populated when fetching children with depth > 1.
+   */
+  nestedChildren?: Record<ResourceType, ResourceContextItem[]>;
+}
+
+/**
+ * The complete resource context
+ */
+export interface ResourceContext<T = any> {
+  /** The primary resource data */
+  resource: T;
+  /** Metadata about the resource */
+  metadata: {
+    resourceType: ResourceType;
+    resourceId: string;
+    fetchedAt: Date;
+  };
+  /** Parent resources keyed by resource type */
+  parents: Record<ResourceType, ResourceContextItem[]>;
+  /** Child resources keyed by resource type */
+  children: Record<ResourceType, ResourceContextItem[]>;
+  /** Configuration used to build this context */
+  configuration: ResourceContextConfiguration;
+}
+
+/**
+ * Options for building a resource context
+ */
+export interface BuildContextOptions extends Partial<ResourceContextConfiguration> {
+  /** Execution context for access rights checking */
+  executionContext?: ExecutionContext<any>;
+  /**
+   * The operation being performed - used to resolve operation-specific context policy overrides.
+   * @example CoreResourceOperation.READ, CoreResourceOperation.LIST, CoreResourceOperation.SEARCH
+   */
+  operation?: CoreResourceOperation;
+}
+
+/**
+ * Default context configuration
+ */
+export const DEFAULT_CONTEXT_CONFIGURATION: ResourceContextConfiguration = {
+  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
+ */
+@injectable()
+export class ResourceContextBackendService {
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService)
+    private readonly resourcesRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.Logger)
+    private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)
+    private readonly errorBuilder: ErrorBuilderBackendService,
+    // Lazy injection to avoid circular dependency - these are resolved at runtime
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)
+    private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.VirtualFieldsService)
+    private readonly virtualFieldsService: VirtualFieldsBackendService,
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)
+    private readonly executionContextCreator: ExecutionContextCreatorBackendService,
+  ) {
+    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
+   */
+  private stripBackendOnlyFieldsFromData<T extends Record<string, any>>(
+    resourceType: ResourceType,
+    data: T,
+    operation: CoreResourceOperation
+  ): Partial<T> {
+    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 as Partial<T>;
+    } 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
+   */
+  private async getOrCreateExecutionContext(
+    resourceType: ResourceType,
+    operationIdentifier: CoreResourceOperation,
+    providedContext?: ExecutionContext<any>,
+    resourceId?: string,
+    relationshipContext?: ExecutionContext_RelationshipContext
+  ): Promise<ExecutionContext<any>> {
+    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
+   */
+  public resolveEffectiveContextPolicy(
+    relationship: ResourceRelationship,
+    operation?: CoreResourceOperation
+  ): EffectiveContextPolicy {
+    const basePolicy = relationship.contextPolicy ?? {};
+
+    // Start with defaults
+    const effective: EffectiveContextPolicy = { ...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<T extends Record<string, any>>(
+    resourceType: ResourceType,
+    resourceId: string,
+    resource: T,
+    options?: BuildContextOptions
+  ): Promise<ResourceContext<T>> {
+    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 as any[]).length}`),
+      childKeys: Object.keys(children),
+      childCounts: Object.entries(children).map(([k, v]) => `${k}:${(v as any[]).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)
+   */
+  private createEmptyContext<T>(
+    resourceType: ResourceType,
+    resourceId: string,
+    resource: T,
+    config?: Partial<ResourceContextConfiguration>
+  ): ResourceContext<T> {
+    return {
+      resource,
+      metadata: {
+        resourceType,
+        resourceId,
+        fetchedAt: new Date(),
+      },
+      parents: {},
+      children: {},
+      configuration: { ...DEFAULT_CONTEXT_CONFIGURATION, ...config },
+    };
+  }
+
+  /**
+   * Merge multiple configuration objects (later objects override earlier ones)
+   */
+  private mergeConfiguration(
+    ...configs: Partial<ResourceContextConfiguration>[]
+  ): ResourceContextConfiguration {
+    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)
+   */
+  private async fetchParentResourcesWithPolicy(
+    resourceType: ResourceType,
+    resource: Record<string, any>,
+    parentRelationships: ResourceRelationship[],
+    config: ResourceContextConfiguration,
+    operation?: CoreResourceOperation,
+    executionContext?: ExecutionContext<any>,
+    visited: Set<string> = new Set()
+  ): Promise<Record<ResourceType, ResourceContextItem[]>> {
+    const result: Record<ResourceType, ResourceContextItem[]> = {};
+
+    // 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: ExecutionContext_RelationshipContext = {
+          resourceType: resourceType as string, // 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: ResourceContextItem = {
+            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
+   */
+  private async fetchChildResourcesWithPolicy(
+    resourceType: ResourceType,
+    resourceId: string,
+    parentResource: Record<string, any>,
+    childRelationships: ResourceRelationship[],
+    config: ResourceContextConfiguration,
+    operation?: CoreResourceOperation,
+    executionContext?: ExecutionContext<any>,
+    visited: Set<string> = new Set()
+  ): Promise<Record<ResourceType, ResourceContextItem[]>> {
+    const result: Record<ResourceType, ResourceContextItem[]> = {};
+
+    // 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: ExecutionContext_RelationshipContext = {
+          resourceType: resourceType as string,
+          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: any[] = [];
+
+        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: any;
+
+          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: ResourceContextItem = {
+            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
+   */
+  private async fetchResourceByMode(
+    resourceType: ResourceType,
+    resourceId: string,
+    objectMode: ContextPolicy_ObjectMode,
+    executionContext?: ExecutionContext<any>,
+    relationshipContext?: ExecutionContext_RelationshipContext
+  ): Promise<Record<string, any> | null> {
+    // 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)
+   */
+  private extractSummaryFields<T extends Record<string, any>>(
+    data: T,
+    resourceType: ResourceType
+  ): Partial<T> {
+    if (!data) {
+      return data;
+    }
+
+    const config = this.resourcesRegistry.tryGetResourceConfiguration(resourceType);
+    if (!config) {
+      return { _id: data._id } as unknown as Partial<T>;
+    }
+
+    const schema = config.mainSchema;
+
+    try {
+      const shape = getZodObjectShape(schema);
+      const result: Record<string, any> = { _id: data._id }; // Always include ID
+
+      for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+        if (isSummaryField(fieldSchema as z.ZodTypeAny)) {
+          if (fieldName in data) {
+            result[fieldName] = data[fieldName];
+          }
+        }
+      }
+
+      return result as Partial<T>;
+    } catch (error) {
+      this.logger.warn(
+        `[ResourceContext] Failed to extract summary fields for ${resourceType}`,
+        error
+      );
+      return { _id: data._id } as unknown as Partial<T>;
+    }
+  }
+
+  /**
+   * 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)
+   */
+  private async fetchRecursiveParentContext(
+    resourceType: ResourceType,
+    resourceData: Record<string, any>,
+    remainingDepth: number,
+    operation?: CoreResourceOperation,
+    executionContext?: ExecutionContext<any>,
+    visited: Set<string> = new Set()
+  ): Promise<Record<ResourceType, ResourceContextItem[]>> {
+    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: ResourceContextConfiguration = {
+      ...DEFAULT_CONTEXT_CONFIGURATION,
+      parentDepth: remainingDepth,
+    };
+
+    return this.fetchParentResourcesWithPolicy(
+      resourceType,
+      resourceData,
+      parentDirRels,
+      recursiveConfig,
+      operation,
+      executionContext,
+      visited
+    );
+  }
+}