@wildo-ai/saas-backend-lib 1.0.1

package/src/__tests__/integration/relationship-service-semantics.integration.test.ts

@@ -0,0 +1,2086 @@
+import 'reflect-metadata';
+import { describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { MockPayloadAssigningErrorBuilderService } from '~wildo-backend-lib/errors/services/__tests__/mock-error-builder.service';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+import { ServiceResourceBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import {
+  ChildLifecycleMode,
+  CoreResourceOperation,
+  createResourcesRelationship,
+  DataMode,
+  RelationshipNature,
+  ResourceRelationshipCardinality,
+  Resources_SharedUtils,
+  type ResourceType,
+} from '@wildo-ai/saas-models';
+import {
+  createTestOperation,
+  createTestResourceConfig,
+  processResourceRelationships,
+} from '@wildo-ai/saas-models/testing';
+
+type FakeResourceConfig = ReturnType<typeof createTestResourceConfig>;
+
+function createFakeResourcesRegistry(resourceConfigurations: Record<ResourceType, FakeResourceConfig>) {
+  return {
+    getResourceConfiguration: vi.fn((resourceType: ResourceType) => {
+      const config = resourceConfigurations[resourceType];
+      if (!config) {
+        throw new Error(`Unknown resource configuration: ${resourceType}`);
+      }
+      return config;
+    }),
+    tryGetResourceConfiguration: vi.fn((resourceType: ResourceType) => resourceConfigurations[resourceType]),
+    getResourcesRegistry: vi.fn(() => ({
+      resourceConfigurations,
+    })),
+    getOperationPathDefault: vi.fn((resourceType: ResourceType, operationIdentifier: CoreResourceOperation) => ({
+      resourceIdentifier: resourceType,
+      operationIdentifier,
+    })),
+    getOperationFromPath: vi.fn((operationPath: { resourceIdentifier: ResourceType; operationIdentifier: CoreResourceOperation }) => {
+      const config = resourceConfigurations[operationPath.resourceIdentifier];
+      const operation = config?.operations.find(
+        (candidate) => candidate.operationIdentifier === operationPath.operationIdentifier
+      );
+      if (!operation) {
+        throw new Error(
+          `Unknown operation "${operationPath.operationIdentifier}" for ${operationPath.resourceIdentifier}`
+        );
+      }
+      return operation;
+    }),
+    resolveForeignKeyField: vi.fn(
+      ({ resourceType1, foreignKeyField }: { resourceType1: ResourceType; foreignKeyField?: string }) => {
+        if (foreignKeyField) {
+          return foreignKeyField;
+        }
+
+        const parentConfig = resourceConfigurations[resourceType1];
+        if (!parentConfig?.resourceFieldIdentifier) {
+          throw new Error(`Missing field identifier for ${resourceType1}`);
+        }
+
+        return parentConfig.resourceFieldIdentifier;
+      }
+    ),
+  } as any;
+}
+
+function createServiceHarness(
+  resourceType: ResourceType,
+  resourceConfigurations: Record<ResourceType, FakeResourceConfig>,
+  overrides?: {
+    repositoriesRegistry?: any;
+    servicesRegistry?: any;
+    executionContextCreator?: any;
+    fileOperationHandler?: any;
+    fileFieldDetection?: any;
+    mongoDBService?: any;
+    appConfigService?: any;
+  }
+) {
+  const resourcesRegistry = createFakeResourcesRegistry(resourceConfigurations);
+  const repositoriesRegistry = {
+    getRepository: vi.fn(),
+    getRepositoryOrThrow: vi.fn(),
+    ...overrides?.repositoriesRegistry,
+  };
+  const servicesRegistry = {
+    dispatchPostOperationHooks: vi.fn().mockResolvedValue(undefined),
+    read: vi.fn(),
+    list: vi.fn(),
+    getService: vi.fn(),
+    ...overrides?.servicesRegistry,
+  };
+  const executionContextCreator = {
+    createForSubCall: vi.fn().mockResolvedValue({}),
+    ...overrides?.executionContextCreator,
+  };
+  const fileOperationHandler = {
+    processFileFieldsForDelete: vi.fn().mockResolvedValue(undefined),
+    ...overrides?.fileOperationHandler,
+  };
+  const fileFieldDetection = {
+    hasFileFields: vi.fn().mockReturnValue(false),
+    ...overrides?.fileFieldDetection,
+  };
+  const mongoDBService = {
+    executeTransaction: vi.fn(async (callback: (transactionContext: any) => Promise<unknown>) =>
+      callback({ databaseType: 'mongodb' })),
+    isInTransaction: vi.fn(() => false),
+    ...overrides?.mongoDBService,
+  };
+  const appConfigService = {
+    config: {
+      database: {
+        defaultAdapter: 'mongodb',
+      },
+    },
+    ...overrides?.appConfigService,
+  };
+
+  const service = new ServiceResourceBackendService(
+    resourceType,
+    resourcesRegistry,
+    new MockLoggerService(),
+    new MockPayloadAssigningErrorBuilderService({
+      preferPayloadContextMessage: false,
+    }),
+    {} as any,
+    {} as any,
+    repositoriesRegistry,
+    servicesRegistry,
+    {} as any,
+    {} as any,
+    {} as any,
+    {} as any,
+    {} as any,
+    {} as any,
+    mongoDBService as any,
+    fileOperationHandler,
+    fileFieldDetection,
+    executionContextCreator,
+    {} as any,
+    {} as any,
+    {} as any,
+    appConfigService as any,
+    undefined,
+    undefined,
+    undefined
+  );
+
+  return {
+    service,
+    resourcesRegistry,
+    repositoriesRegistry,
+    servicesRegistry,
+    executionContextCreator,
+    fileOperationHandler,
+    fileFieldDetection,
+    mongoDBService,
+  };
+}
+
+function buildTestResourceConfig(
+  resourceType: ResourceType,
+  resourceFieldIdentifier: string,
+  mainSchema: z.ZodTypeAny,
+  relationships: ReturnType<typeof processResourceRelationships>,
+  operations: CoreResourceOperation[]
+): FakeResourceConfig {
+  const builtOperations = operations.map((operationIdentifier) => ({
+    ...createTestOperation(mainSchema, operationIdentifier),
+    resourceIdentifier: resourceType,
+    resourceFieldIdentifier,
+    resourceRelationships: relationships,
+  }));
+
+  return {
+    ...createTestResourceConfig(mainSchema, builtOperations),
+    resourceIdentifier: resourceType,
+    resourceFieldIdentifier,
+    resourceRelationships: relationships,
+    operations: builtOperations,
+  };
+}
+
+describe('relationship service semantics', () => {
+  it('should fetch nested children for compiled composition read semantics', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const compositionRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          nested: {
+            onRead: {
+              dataMode: DataMode.SUMMARY,
+              maxItems: 25,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      role: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [compositionRelationship]),
+      [CoreResourceOperation.READ]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [compositionRelationship]),
+      [CoreResourceOperation.LIST, CoreResourceOperation.READ]
+    );
+
+    const listSpy = vi.fn().mockResolvedValue([]);
+    const createForSubCallSpy = vi.fn().mockResolvedValue({});
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        servicesRegistry: {
+          list: listSpy,
+          getService: vi.fn(),
+        },
+        executionContextCreator: {
+          createForSubCall: createForSubCallSpy,
+        },
+      }
+    );
+
+    const parentResult = { _id: 'project-1', name: 'Main project' };
+    const compositionField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      compositionRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [membershipsResourceType]: 'projectMembershipId',
+      }
+    ).objectFieldName;
+
+    await (service as any).processNestedRead(
+      parentResult,
+      [compositionRelationship],
+      {} as any,
+      undefined
+    );
+
+    expect(createForSubCallSpy).toHaveBeenCalledTimes(1);
+    expect(listSpy).toHaveBeenCalledTimes(1);
+    expect(listSpy).toHaveBeenCalledWith(
+      membershipsResourceType,
+      {},
+      { projectId: 'project-1' },
+      { limit: 25 },
+      expect.objectContaining({ dataMode: DataMode.SUMMARY })
+    );
+    expect(parentResult[compositionField]).toEqual([]);
+  });
+
+  it('should fetch one-to-one nested reads through child READ semantics instead of LIST', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const detailsResourceType = 'projectDetails' as ResourceType;
+
+    const oneToOneRelationship = createResourcesRelationship(
+      projectsResourceType,
+      detailsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.ONE,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          nested: {
+            onRead: {
+              dataMode: DataMode.SUMMARY,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const detailsSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+      description: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [oneToOneRelationship]),
+      [CoreResourceOperation.READ]
+    );
+
+    const detailsConfig = buildTestResourceConfig(
+      detailsResourceType,
+      'projectDetailsId',
+      detailsSchema,
+      processResourceRelationships(detailsResourceType, [oneToOneRelationship]),
+      [CoreResourceOperation.READ, CoreResourceOperation.LIST]
+    );
+
+    const readSpy = vi.fn().mockResolvedValue({
+      _id: 'details-1',
+      projectId: 'project-1',
+      description: 'Main project details',
+    });
+    const listSpy = vi.fn();
+    const createForSubCallSpy = vi.fn().mockResolvedValue({});
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [detailsResourceType]: detailsConfig,
+      },
+      {
+        servicesRegistry: {
+          read: readSpy,
+          list: listSpy,
+          getService: vi.fn(),
+        },
+        executionContextCreator: {
+          createForSubCall: createForSubCallSpy,
+        },
+      }
+    );
+
+    const parentResult = { _id: 'project-1', name: 'Main project' };
+    const relationshipField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      oneToOneRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [detailsResourceType]: 'projectDetailsId',
+      }
+    ).objectFieldName;
+
+    await (service as any).processNestedRead(
+      parentResult,
+      [oneToOneRelationship],
+      {} as any,
+      undefined
+    );
+
+    expect(createForSubCallSpy).toHaveBeenCalledTimes(1);
+    expect(readSpy).toHaveBeenCalledWith(
+      detailsResourceType,
+      {},
+      { projectId: 'project-1' },
+      expect.objectContaining({ dataMode: DataMode.SUMMARY })
+    );
+    expect(listSpy).not.toHaveBeenCalled();
+    expect(parentResult[relationshipField]).toEqual({
+      _id: 'details-1',
+      projectId: 'project-1',
+      description: 'Main project details',
+    });
+  });
+
+  it('should fail closed and skip peer nested reads for association semantics', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const usersResourceType = 'users' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const associationRelationship = createResourcesRelationship(
+      projectsResourceType,
+      usersResourceType,
+      ResourceRelationshipCardinality.MANY,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.ASSOCIATION,
+        jointResourceType: membershipsResourceType,
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const userSchema = z.object({
+      _id: z.string(),
+      email: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+      userId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [associationRelationship]),
+      [CoreResourceOperation.READ]
+    );
+
+    const userConfig = buildTestResourceConfig(
+      usersResourceType,
+      'userId',
+      userSchema,
+      processResourceRelationships(usersResourceType, [associationRelationship]),
+      [CoreResourceOperation.READ, CoreResourceOperation.LIST]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [associationRelationship]),
+      [CoreResourceOperation.READ]
+    );
+
+    const listSpy = vi.fn().mockResolvedValue([]);
+    const createForSubCallSpy = vi.fn().mockResolvedValue({});
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [usersResourceType]: userConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        servicesRegistry: {
+          list: listSpy,
+          getService: vi.fn(),
+        },
+        executionContextCreator: {
+          createForSubCall: createForSubCallSpy,
+        },
+      }
+    );
+
+    const parentResult = { _id: 'project-1', name: 'Main project' };
+    const associationField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      associationRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [usersResourceType]: 'userId',
+        [membershipsResourceType]: 'projectMembershipId',
+      }
+    ).objectFieldName;
+
+    await (service as any).processNestedRead(
+      parentResult,
+      [associationRelationship],
+      {} as any,
+      undefined
+    );
+
+    expect(createForSubCallSpy).not.toHaveBeenCalled();
+    expect(listSpy).not.toHaveBeenCalled();
+    expect(parentResult[associationField]).toBeUndefined();
+  });
+
+  it('should discover and delete lifecycle children through adapter-neutral repository operations', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const lifecycleRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const listSpy = vi.fn().mockResolvedValue([
+      { _id: 'membership-1' },
+      { _id: 'membership-2' },
+    ]);
+    const deleteManySpy = vi.fn().mockResolvedValue(['membership-1', 'membership-2']);
+    const processFileFieldsForDeleteSpy = vi.fn().mockResolvedValue(undefined);
+    const childRepository = {
+      supportsOperation: vi.fn((operationIdentifier: string) =>
+        operationIdentifier === CoreResourceOperation.LIST
+        || operationIdentifier === CoreResourceOperation.DELETE_MANY
+      ),
+      list: listSpy,
+      deleteMany: deleteManySpy,
+    };
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn().mockReturnValue(childRepository),
+        },
+        servicesRegistry: {
+          getService: vi.fn().mockReturnValue({}),
+        },
+        fileOperationHandler: {
+          processFileFieldsForDelete: processFileFieldsForDeleteSpy,
+        },
+        fileFieldDetection: {
+          hasFileFields: vi.fn((candidateResourceType: ResourceType) => candidateResourceType === membershipsResourceType),
+        },
+      }
+    );
+
+    const executionContext = {} as any;
+
+    await (service as any).deleteChildrenImmediate(
+      lifecycleRelationship,
+      ['project-1'],
+      executionContext,
+      0,
+      1,
+      new Set()
+    );
+
+    expect(childRepository.supportsOperation).toHaveBeenCalledWith(CoreResourceOperation.LIST);
+    expect(listSpy).toHaveBeenCalledWith(executionContext, { projectId: { $in: ['project-1'] } }, undefined);
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      1,
+      membershipsResourceType,
+      'membership-1',
+      executionContext,
+      undefined
+    );
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      2,
+      membershipsResourceType,
+      'membership-2',
+      executionContext,
+      undefined
+    );
+    expect(deleteManySpy).toHaveBeenCalledWith(executionContext, ['membership-1', 'membership-2'], undefined);
+    expect(deleteManySpy).not.toHaveBeenCalledWith(
+      executionContext,
+      expect.objectContaining({ _id: expect.anything() })
+    );
+  });
+
+  it('should execute lifecycle child deletion for single DELETE results returned as bare ids', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const lifecycleRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const parentReadSpy = vi.fn().mockResolvedValue({ _id: 'project-1', name: 'Main project' });
+    const parentDeleteSpy = vi.fn().mockResolvedValue('project-1');
+    const parentRepository = {
+      read: parentReadSpy,
+      doByPath: parentDeleteSpy,
+    };
+    const childListSpy = vi.fn().mockResolvedValue([
+      { _id: 'membership-1' },
+      { _id: 'membership-2' },
+    ]);
+    const childDeleteManySpy = vi.fn().mockResolvedValue(['membership-1', 'membership-2']);
+    const childRepository = {
+      supportsOperation: vi.fn((operationIdentifier: string) =>
+        operationIdentifier === CoreResourceOperation.LIST
+        || operationIdentifier === CoreResourceOperation.DELETE_MANY
+      ),
+      list: childListSpy,
+      deleteMany: childDeleteManySpy,
+    };
+    const processFileFieldsForDeleteSpy = vi.fn().mockResolvedValue(undefined);
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn((candidateResourceType: ResourceType) =>
+            candidateResourceType === projectsResourceType ? parentRepository : childRepository
+          ),
+          getRepositoryOrThrow: vi.fn((candidateResourceType: ResourceType) =>
+            candidateResourceType === projectsResourceType ? parentRepository : childRepository
+          ),
+        },
+        servicesRegistry: {
+          getService: vi.fn().mockReturnValue({}),
+        },
+        fileOperationHandler: {
+          processFileFieldsForDelete: processFileFieldsForDeleteSpy,
+        },
+        fileFieldDetection: {
+          hasFileFields: vi.fn((candidateResourceType: ResourceType) => candidateResourceType === membershipsResourceType),
+        },
+      }
+    );
+
+    const serviceAny = service as any;
+    serviceAny.validateDeletionConstraints = vi.fn().mockResolvedValue(undefined);
+    serviceAny.executePreOperationLogic = vi.fn().mockResolvedValue(undefined);
+
+    await serviceAny.delete(
+      projectConfig.operations[0],
+      { operation: projectConfig.operations[0] } as any,
+      'project-1',
+      undefined,
+    );
+
+    expect(parentReadSpy).toHaveBeenCalledWith(expect.any(Object), 'project-1');
+    expect(parentDeleteSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resourceIdentifier: projectsResourceType,
+        operationIdentifier: CoreResourceOperation.DELETE,
+      }),
+      expect.any(Object),
+      'project-1',
+      undefined,
+      expect.objectContaining({
+        transaction: expect.objectContaining({
+          databaseType: 'mongodb',
+        }),
+      })
+    );
+    expect(childListSpy).toHaveBeenCalledWith(expect.any(Object), { projectId: { $in: ['project-1'] } }, expect.any(Object));
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      1,
+      membershipsResourceType,
+      'membership-1',
+      expect.any(Object),
+      expect.any(Object)
+    );
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      2,
+      membershipsResourceType,
+      'membership-2',
+      expect.any(Object),
+      expect.any(Object)
+    );
+    expect(childDeleteManySpy).toHaveBeenCalledWith(expect.any(Object), ['membership-1', 'membership-2'], expect.any(Object));
+  });
+
+  it('should keep single-delete lifecycle child file cleanup inside the parent transaction boundary', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const lifecycleRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+      attachment: z.string().optional(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.LIST, CoreResourceOperation.DELETE_MANY]
+    );
+
+    const transactionContext = { databaseType: 'mongodb' };
+    const parentReadSpy = vi.fn().mockResolvedValue({ _id: 'project-1', name: 'Main project' });
+    const parentDeleteSpy = vi.fn().mockResolvedValue('project-1');
+    const childListSpy = vi.fn().mockResolvedValue([
+      { _id: 'membership-1', projectId: 'project-1' },
+      { _id: 'membership-2', projectId: 'project-1' },
+    ]);
+    const childDeleteManySpy = vi.fn();
+    const processFileFieldsForDeleteSpy = vi.fn()
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(new Error('child file cleanup failed'));
+    const mongoExecuteTransactionSpy = vi.fn(async (callback: (transactionContext: any) => Promise<unknown>) =>
+      callback(transactionContext));
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn((candidateResourceType: ResourceType) => (
+            candidateResourceType === projectsResourceType
+              ? {
+                read: parentReadSpy,
+                doByPath: parentDeleteSpy,
+                supportsOperation: vi.fn(),
+              }
+              : {
+                supportsOperation: vi.fn((operationIdentifier: string) =>
+                  operationIdentifier === CoreResourceOperation.LIST
+                  || operationIdentifier === CoreResourceOperation.DELETE_MANY
+                ),
+                list: childListSpy,
+                deleteMany: childDeleteManySpy,
+              }
+          )),
+          getRepositoryOrThrow: vi.fn((candidateResourceType: ResourceType) => (
+            candidateResourceType === projectsResourceType
+              ? {
+                read: parentReadSpy,
+                doByPath: parentDeleteSpy,
+                supportsOperation: vi.fn(),
+              }
+              : {
+                supportsOperation: vi.fn((operationIdentifier: string) =>
+                  operationIdentifier === CoreResourceOperation.LIST
+                  || operationIdentifier === CoreResourceOperation.DELETE_MANY
+                ),
+                list: childListSpy,
+                deleteMany: childDeleteManySpy,
+              }
+          )),
+        },
+        servicesRegistry: {
+          dispatchPostOperationHooks: vi.fn().mockResolvedValue(undefined),
+          getService: vi.fn().mockReturnValue({}),
+        },
+        fileOperationHandler: {
+          processFileFieldsForDelete: processFileFieldsForDeleteSpy,
+        },
+        fileFieldDetection: {
+          hasFileFields: vi.fn((candidateResourceType: ResourceType) => candidateResourceType === membershipsResourceType),
+        },
+        mongoDBService: {
+          executeTransaction: mongoExecuteTransactionSpy,
+          isInTransaction: vi.fn(() => false),
+        },
+      }
+    );
+
+    const serviceAny = service as any;
+    serviceAny.validateDeletionConstraints = vi.fn().mockResolvedValue(undefined);
+    serviceAny.executePreOperationLogic = vi.fn().mockResolvedValue(undefined);
+
+    await expect(
+      serviceAny.delete(
+        projectConfig.operations[0],
+        { operation: projectConfig.operations[0] } as any,
+        'project-1',
+        undefined,
+      )
+    ).rejects.toThrow('child file cleanup failed');
+
+    expect(mongoExecuteTransactionSpy).toHaveBeenCalledTimes(1);
+    expect(parentDeleteSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        resourceIdentifier: projectsResourceType,
+        operationIdentifier: CoreResourceOperation.DELETE,
+      }),
+      expect.any(Object),
+      'project-1',
+      undefined,
+      expect.objectContaining({
+        transaction: transactionContext,
+      })
+    );
+    expect(childListSpy).toHaveBeenCalledWith(
+      expect.any(Object),
+      { projectId: { $in: ['project-1'] } },
+      expect.objectContaining({
+        transaction: transactionContext,
+      })
+    );
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      1,
+      membershipsResourceType,
+      'membership-1',
+      expect.any(Object),
+      expect.objectContaining({
+        transaction: transactionContext,
+      })
+    );
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      2,
+      membershipsResourceType,
+      'membership-2',
+      expect.any(Object),
+      expect.objectContaining({
+        transaction: transactionContext,
+      })
+    );
+    expect(childDeleteManySpy).not.toHaveBeenCalled();
+  });
+
+  it('should fail closed when single-delete lifecycle children use a different persistence adapter', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const lifecycleRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = {
+      ...buildTestResourceConfig(
+        projectsResourceType,
+        'projectId',
+        projectSchema,
+        processResourceRelationships(projectsResourceType, [lifecycleRelationship]),
+        [CoreResourceOperation.DELETE]
+      ),
+      persistenceAdapter: 'mongodb',
+    };
+
+    const membershipConfig = {
+      ...buildTestResourceConfig(
+        membershipsResourceType,
+        'projectMembershipId',
+        membershipSchema,
+        processResourceRelationships(membershipsResourceType, [lifecycleRelationship]),
+        [CoreResourceOperation.LIST, CoreResourceOperation.DELETE_MANY]
+      ),
+      persistenceAdapter: 'postgresql',
+    };
+
+    const parentReadSpy = vi.fn().mockResolvedValue({ _id: 'project-1', name: 'Main project' });
+    const parentDeleteSpy = vi.fn().mockResolvedValue('project-1');
+    const childListSpy = vi.fn();
+    const childDeleteManySpy = vi.fn();
+    const processFileFieldsForDeleteSpy = vi.fn();
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn((candidateResourceType: ResourceType) => (
+            candidateResourceType === projectsResourceType
+              ? {
+                read: parentReadSpy,
+                doByPath: parentDeleteSpy,
+                supportsOperation: vi.fn(),
+              }
+              : {
+                supportsOperation: vi.fn((operationIdentifier: string) =>
+                  operationIdentifier === CoreResourceOperation.LIST
+                  || operationIdentifier === CoreResourceOperation.DELETE_MANY
+                ),
+                list: childListSpy,
+                deleteMany: childDeleteManySpy,
+              }
+          )),
+          getRepositoryOrThrow: vi.fn((candidateResourceType: ResourceType) => (
+            candidateResourceType === projectsResourceType
+              ? {
+                read: parentReadSpy,
+                doByPath: parentDeleteSpy,
+                supportsOperation: vi.fn(),
+              }
+              : {
+                supportsOperation: vi.fn((operationIdentifier: string) =>
+                  operationIdentifier === CoreResourceOperation.LIST
+                  || operationIdentifier === CoreResourceOperation.DELETE_MANY
+                ),
+                list: childListSpy,
+                deleteMany: childDeleteManySpy,
+              }
+          )),
+        },
+        servicesRegistry: {
+          dispatchPostOperationHooks: vi.fn().mockResolvedValue(undefined),
+          getService: vi.fn().mockReturnValue({}),
+        },
+        fileOperationHandler: {
+          processFileFieldsForDelete: processFileFieldsForDeleteSpy,
+        },
+      }
+    );
+
+    const serviceAny = service as any;
+    serviceAny.validateDeletionConstraints = vi.fn().mockResolvedValue(undefined);
+    serviceAny.executePreOperationLogic = vi.fn().mockResolvedValue(undefined);
+
+    await expect(
+      serviceAny.delete(
+        projectConfig.operations[0],
+        { operation: projectConfig.operations[0] } as any,
+        'project-1',
+        undefined,
+      )
+    ).rejects.toMatchObject({
+      context: expect.objectContaining({
+        childResourceType: membershipsResourceType,
+        childPersistenceAdapter: 'postgresql',
+        parentPersistenceAdapter: 'mongodb',
+      }),
+    });
+
+    expect(parentDeleteSpy).toHaveBeenCalledTimes(1);
+    expect(childListSpy).not.toHaveBeenCalled();
+    expect(childDeleteManySpy).not.toHaveBeenCalled();
+    expect(processFileFieldsForDeleteSpy).not.toHaveBeenCalled();
+  });
+
+  it('should fall back to per-child repository delete when lifecycle children do not support DELETE_MANY', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const lifecycleRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const listSpy = vi.fn().mockResolvedValue([
+      { _id: 'membership-1' },
+      { _id: 'membership-2' },
+    ]);
+    const deleteSpy = vi.fn()
+      .mockResolvedValueOnce('membership-1')
+      .mockResolvedValueOnce('membership-2');
+    const processFileFieldsForDeleteSpy = vi.fn().mockResolvedValue(undefined);
+    const childRepository = {
+      supportsOperation: vi.fn((operationIdentifier: string) =>
+        operationIdentifier === CoreResourceOperation.LIST
+        || operationIdentifier === CoreResourceOperation.DELETE
+      ),
+      list: listSpy,
+      delete: deleteSpy,
+    };
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn().mockReturnValue(childRepository),
+          getRepositoryOrThrow: vi.fn().mockReturnValue(childRepository),
+        },
+        servicesRegistry: {
+          getService: vi.fn().mockReturnValue({}),
+        },
+        fileOperationHandler: {
+          processFileFieldsForDelete: processFileFieldsForDeleteSpy,
+        },
+        fileFieldDetection: {
+          hasFileFields: vi.fn((candidateResourceType: ResourceType) => candidateResourceType === membershipsResourceType),
+        },
+      }
+    );
+
+    await (service as any).deleteChildrenImmediate(
+      lifecycleRelationship,
+      ['project-1'],
+      {} as any,
+      0,
+      1,
+      new Set()
+    );
+
+    expect(listSpy).toHaveBeenCalledWith({} as any, { projectId: { $in: ['project-1'] } }, undefined);
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      1,
+      membershipsResourceType,
+      'membership-1',
+      {} as any,
+      undefined
+    );
+    expect(processFileFieldsForDeleteSpy).toHaveBeenNthCalledWith(
+      2,
+      membershipsResourceType,
+      'membership-2',
+      {} as any,
+      undefined
+    );
+    expect(deleteSpy).toHaveBeenNthCalledWith(1, {} as any, 'membership-1', undefined);
+    expect(deleteSpy).toHaveBeenNthCalledWith(2, {} as any, 'membership-2', undefined);
+  });
+
+  it('should keep deep lifecycle recursion gated by each deleted child snapshot', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+    const auditEntriesResourceType = 'membershipAuditEntries' as ResourceType;
+
+    const projectToMembershipRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 2,
+            },
+          },
+        },
+      }
+    );
+
+    const membershipToAuditRelationship = createResourcesRelationship(
+      membershipsResourceType,
+      auditEntriesResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'membershipId',
+        discriminator: {
+          discriminatorField: 'role',
+          values: ['OWNER'],
+        },
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+      role: z.string(),
+    });
+    const auditEntrySchema = z.object({
+      _id: z.string(),
+      membershipId: z.string(),
+      action: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [projectToMembershipRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [
+        projectToMembershipRelationship,
+        membershipToAuditRelationship,
+      ]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const auditEntryConfig = buildTestResourceConfig(
+      auditEntriesResourceType,
+      'membershipAuditEntryId',
+      auditEntrySchema,
+      processResourceRelationships(auditEntriesResourceType, [membershipToAuditRelationship]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const membershipListSpy = vi.fn().mockResolvedValue([
+      { _id: 'membership-owner', projectId: 'project-1', role: 'OWNER' },
+      { _id: 'membership-viewer', projectId: 'project-1', role: 'VIEWER' },
+    ]);
+    const membershipDeleteManySpy = vi
+      .fn()
+      .mockResolvedValue(['membership-owner', 'membership-viewer']);
+    const auditEntryListSpy = vi.fn().mockResolvedValue([{ _id: 'audit-1' }]);
+    const auditEntryDeleteManySpy = vi.fn().mockResolvedValue(['audit-1']);
+
+    const membershipRepository = {
+      supportsOperation: vi.fn((operationIdentifier: string) =>
+        operationIdentifier === CoreResourceOperation.LIST
+        || operationIdentifier === CoreResourceOperation.DELETE_MANY
+      ),
+      list: membershipListSpy,
+      deleteMany: membershipDeleteManySpy,
+    };
+    const auditEntryRepository = {
+      supportsOperation: vi.fn((operationIdentifier: string) =>
+        operationIdentifier === CoreResourceOperation.LIST
+        || operationIdentifier === CoreResourceOperation.DELETE_MANY
+      ),
+      list: auditEntryListSpy,
+      deleteMany: auditEntryDeleteManySpy,
+    };
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+        [auditEntriesResourceType]: auditEntryConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn((resourceType: ResourceType) => {
+            if (resourceType === membershipsResourceType) {
+              return membershipRepository;
+            }
+            if (resourceType === auditEntriesResourceType) {
+              return auditEntryRepository;
+            }
+            throw new Error(`Unexpected repository request: ${resourceType}`);
+          }),
+        },
+        servicesRegistry: {
+          getService: vi.fn((resourceType: ResourceType) => {
+            if (
+              resourceType === membershipsResourceType ||
+              resourceType === auditEntriesResourceType
+            ) {
+              return {};
+            }
+            return undefined;
+          }),
+        },
+      }
+    );
+
+    await (service as any).deleteChildrenImmediate(
+      projectToMembershipRelationship,
+      ['project-1'],
+      {} as any,
+      0,
+      2,
+      new Set()
+    );
+
+    expect(membershipListSpy).toHaveBeenCalledWith(
+      {} as any,
+      { projectId: { $in: ['project-1'] } },
+      undefined
+    );
+    expect(membershipDeleteManySpy).toHaveBeenCalledWith(
+      {} as any,
+      ['membership-owner', 'membership-viewer'],
+      undefined
+    );
+    expect(auditEntryListSpy).toHaveBeenCalledWith(
+      {} as any,
+      { membershipId: { $in: ['membership-owner'] } },
+      undefined
+    );
+    expect(auditEntryDeleteManySpy).toHaveBeenCalledWith({} as any, ['audit-1'], undefined);
+    expect(auditEntryDeleteManySpy.mock.invocationCallOrder[0]).toBeLessThan(
+      membershipDeleteManySpy.mock.invocationCallOrder[0]
+    );
+    expect(auditEntryListSpy).not.toHaveBeenCalledWith(
+      {} as any,
+      { membershipId: { $in: ['membership-owner', 'membership-viewer'] } }
+    );
+  });
+
+  it('should keep top-level lifecycle cascade fail-closed for DELETE_MANY parent snapshots', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const lifecycleRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        discriminator: {
+          discriminatorField: 'projectType',
+          values: ['INTERNAL'],
+        },
+        childOperations: {
+          lifecycle: {
+            onParentDelete: {
+              enabled: true,
+              mode: ChildLifecycleMode.IMMEDIATE,
+              maxDepth: 1,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+      projectType: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [lifecycleRelationship]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const parentSnapshots = [
+      { _id: 'project-internal', name: 'Internal project', projectType: 'INTERNAL' },
+      { _id: 'project-external', name: 'External project', projectType: 'EXTERNAL' },
+    ];
+
+    const parentRepository = {
+      list: vi.fn().mockResolvedValue(parentSnapshots),
+      read: vi.fn((_: unknown, id: string) => Promise.resolve(
+        parentSnapshots.find((item) => item._id === id) ?? null
+      )),
+      doByPath: vi.fn().mockResolvedValue(['project-internal', 'project-external']),
+    };
+    const membershipListSpy = vi.fn().mockResolvedValue([]);
+    const membershipDeleteManySpy = vi.fn().mockResolvedValue([]);
+    const membershipRepository = {
+      supportsOperation: vi.fn((operationIdentifier: string) =>
+        operationIdentifier === CoreResourceOperation.LIST
+        || operationIdentifier === CoreResourceOperation.DELETE_MANY
+      ),
+      list: membershipListSpy,
+      deleteMany: membershipDeleteManySpy,
+    };
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        repositoriesRegistry: {
+          getRepository: vi.fn((resourceType: ResourceType) => {
+            if (resourceType === membershipsResourceType) {
+              return membershipRepository;
+            }
+            return parentRepository;
+          }),
+          getRepositoryOrThrow: vi.fn((resourceType: ResourceType) => {
+            if (resourceType === membershipsResourceType) {
+              return membershipRepository;
+            }
+            return parentRepository;
+          }),
+        },
+        servicesRegistry: {
+          getService: vi.fn().mockReturnValue({}),
+        },
+      }
+    );
+    (service as any).fileFieldDetection = { hasFileFields: vi.fn().mockReturnValue(false) };
+
+    const deleteManyOperation = projectConfig.operations.find(
+      (candidate) => candidate.operationIdentifier === CoreResourceOperation.DELETE_MANY
+    )!;
+
+    await (service as any).deleteMany(
+      deleteManyOperation,
+      { operation: { resourceIdentifier: projectsResourceType } } as any,
+      { archived: true },
+      undefined
+    );
+
+    expect(parentRepository.list).toHaveBeenCalled();
+    expect(parentRepository.doByPath).toHaveBeenCalled();
+    expect(membershipListSpy).toHaveBeenCalledWith(
+      expect.anything(),
+      { projectId: { $in: ['project-internal'] } },
+      expect.objectContaining({
+        transaction: expect.objectContaining({
+          databaseType: 'mongodb',
+        }),
+      })
+    );
+    expect(membershipListSpy).not.toHaveBeenCalledWith(
+      expect.anything(),
+      { projectId: { $in: ['project-internal', 'project-external'] } },
+      expect.objectContaining({
+        transaction: expect.objectContaining({
+          databaseType: 'mongodb',
+        }),
+      })
+    );
+  });
+
+  it('should execute nested composition create, update, and delete through child services', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const compositionRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          nested: {
+            onUpdate: {
+              allowCreate: true,
+              allowUpdate: true,
+              allowDelete: true,
+            },
+          },
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string().optional(),
+      role: z.string(),
+      projectId: z.string().optional(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [compositionRelationship]),
+      [CoreResourceOperation.UPDATE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [compositionRelationship]),
+      [CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE, CoreResourceOperation.DELETE]
+    );
+
+    const createSpy = vi.fn().mockImplementation(async (_resourceType, _ctx, data) => ({
+      _id: 'membership-created',
+      ...data,
+    }));
+    const updateSpy = vi.fn().mockImplementation(async (_resourceType, _ctx, childId, data) => ({
+      _id: childId,
+      ...data,
+    }));
+    const deleteSpy = vi.fn().mockResolvedValue('membership-to-delete');
+    const createForSubCallSpy = vi.fn().mockResolvedValue({});
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        servicesRegistry: {
+          create: createSpy,
+          update: updateSpy,
+          delete: deleteSpy,
+          list: vi.fn(),
+          getService: vi.fn(),
+        },
+        executionContextCreator: {
+          createForSubCall: createForSubCallSpy,
+        },
+      }
+    );
+
+    const parentResult = { _id: 'project-1', name: 'Main project' };
+    const relationshipField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      compositionRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [membershipsResourceType]: 'projectMembershipId',
+      }
+    ).objectFieldName;
+
+    await (service as any).processNestedOperations(
+      CoreResourceOperation.UPDATE,
+      parentResult,
+      {
+        [relationshipField]: [
+          { role: 'owner' },
+          { _id: 'membership-2', role: 'admin' },
+        ],
+      },
+      {
+        [relationshipField]: ['membership-to-delete'],
+      },
+      [compositionRelationship],
+      {} as any,
+      undefined
+    );
+
+    expect(deleteSpy).toHaveBeenCalledWith(
+      membershipsResourceType,
+      {},
+      'membership-to-delete',
+      undefined
+    );
+    expect(createSpy).toHaveBeenCalledWith(
+      membershipsResourceType,
+      {},
+      { role: 'owner', projectId: 'project-1' },
+      undefined
+    );
+    expect(updateSpy).toHaveBeenCalledWith(
+      membershipsResourceType,
+      {},
+      'membership-2',
+      { role: 'admin', projectId: 'project-1' },
+      undefined
+    );
+    expect(createForSubCallSpy).toHaveBeenCalledTimes(3);
+    expect(parentResult[relationshipField]).toEqual([
+      { _id: 'membership-created', role: 'owner', projectId: 'project-1' },
+      { _id: 'membership-2', role: 'admin', projectId: 'project-1' },
+    ]);
+  });
+
+  it('should fail closed for nested reference mutation payloads', async () => {
+    const usersResourceType = 'users' as ResourceType;
+    const tasksResourceType = 'tasks' as ResourceType;
+
+    const referenceRelationship = createResourcesRelationship(
+      usersResourceType,
+      tasksResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.REFERENCE,
+        foreignKeyField: 'assignedToUserId',
+      }
+    );
+
+    const taskSchema = z.object({
+      _id: z.string(),
+      title: z.string(),
+      assignedToUserId: z.string().optional(),
+    });
+    const userSchema = z.object({
+      _id: z.string(),
+      email: z.string(),
+    });
+
+    const userConfig = buildTestResourceConfig(
+      usersResourceType,
+      'userId',
+      userSchema,
+      processResourceRelationships(usersResourceType, [referenceRelationship]),
+      [CoreResourceOperation.UPDATE]
+    );
+
+    const taskConfig = buildTestResourceConfig(
+      tasksResourceType,
+      'taskId',
+      taskSchema,
+      processResourceRelationships(tasksResourceType, [referenceRelationship]),
+      [CoreResourceOperation.UPDATE]
+    );
+
+    const createSpy = vi.fn();
+    const updateSpy = vi.fn();
+    const deleteSpy = vi.fn();
+
+    const { service } = createServiceHarness(
+      usersResourceType,
+      {
+        [usersResourceType]: userConfig,
+        [tasksResourceType]: taskConfig,
+      },
+      {
+        servicesRegistry: {
+          create: createSpy,
+          update: updateSpy,
+          delete: deleteSpy,
+          list: vi.fn(),
+          getService: vi.fn(),
+        },
+      }
+    );
+
+    const relationshipField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      referenceRelationship,
+      usersResourceType,
+      {
+        [usersResourceType]: 'userId',
+        [tasksResourceType]: 'taskId',
+      }
+    ).objectFieldName;
+
+    await expect(
+      (service as any).processNestedOperations(
+        CoreResourceOperation.UPDATE,
+        { _id: 'user-1', email: 'user@example.com' },
+        {
+          [relationshipField]: [{ title: 'Do work' }],
+        },
+        {},
+        [referenceRelationship],
+        {} as any,
+        undefined
+      )
+    ).rejects.toMatchObject({
+      context: expect.objectContaining({
+        reason: 'nested operations are not enabled for this relationship',
+      }),
+    });
+
+    expect(createSpy).not.toHaveBeenCalled();
+    expect(updateSpy).not.toHaveBeenCalled();
+    expect(deleteSpy).not.toHaveBeenCalled();
+  });
+
+  it('should fail closed for association nested delete payloads', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const usersResourceType = 'users' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const associationRelationship = createResourcesRelationship(
+      projectsResourceType,
+      usersResourceType,
+      ResourceRelationshipCardinality.MANY,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.ASSOCIATION,
+        jointResourceType: membershipsResourceType,
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const userSchema = z.object({
+      _id: z.string(),
+      email: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      projectId: z.string(),
+      userId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [associationRelationship]),
+      [CoreResourceOperation.UPDATE]
+    );
+
+    const userConfig = buildTestResourceConfig(
+      usersResourceType,
+      'userId',
+      userSchema,
+      processResourceRelationships(usersResourceType, [associationRelationship]),
+      [CoreResourceOperation.READ]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [associationRelationship]),
+      [CoreResourceOperation.DELETE_MANY]
+    );
+
+    const deleteSpy = vi.fn();
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [usersResourceType]: userConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        servicesRegistry: {
+          create: vi.fn(),
+          update: vi.fn(),
+          delete: deleteSpy,
+          list: vi.fn(),
+          getService: vi.fn(),
+        },
+      }
+    );
+
+    const relationshipField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      associationRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [usersResourceType]: 'userId',
+        [membershipsResourceType]: 'projectMembershipId',
+      }
+    ).objectFieldName;
+
+    await expect(
+      (service as any).processNestedOperations(
+        CoreResourceOperation.UPDATE,
+        { _id: 'project-1', name: 'Main project' },
+        {},
+        {
+          [relationshipField]: ['membership-1'],
+        },
+        [associationRelationship],
+        {} as any,
+        undefined
+      )
+    ).rejects.toMatchObject({
+      context: expect.objectContaining({
+        reason: 'nested deletes are not enabled for this relationship',
+      }),
+    });
+
+    expect(deleteSpy).not.toHaveBeenCalled();
+  });
+
+  it('should skip nested reads when a condition-gated relationship is inactive for the parent', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const gatedRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          nested: {
+            onRead: {
+              dataMode: DataMode.SUMMARY,
+              maxItems: 25,
+            },
+          },
+        },
+        condition: (parent: Record<string, any>) => parent.lifecycleState === 'ACTIVE',
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+      lifecycleState: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      role: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [gatedRelationship]),
+      [CoreResourceOperation.READ]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [gatedRelationship]),
+      [CoreResourceOperation.LIST, CoreResourceOperation.READ]
+    );
+
+    const listSpy = vi.fn().mockResolvedValue([]);
+    const createForSubCallSpy = vi.fn().mockResolvedValue({});
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        servicesRegistry: {
+          list: listSpy,
+          getService: vi.fn(),
+        },
+        executionContextCreator: {
+          createForSubCall: createForSubCallSpy,
+        },
+      }
+    );
+
+    const parentResult = {
+      _id: 'project-1',
+      name: 'Archived project',
+      lifecycleState: 'ARCHIVED',
+    };
+    const relationshipField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      gatedRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [membershipsResourceType]: 'projectMembershipId',
+      }
+    ).objectFieldName;
+    const activeRelationships = (service as any).filterRelationshipsByParent(
+      [gatedRelationship],
+      parentResult
+    );
+
+    expect(activeRelationships).toEqual([]);
+
+    await (service as any).processNestedRead(parentResult, activeRelationships, {} as any, undefined);
+
+    expect(createForSubCallSpy).not.toHaveBeenCalled();
+    expect(listSpy).not.toHaveBeenCalled();
+    expect(parentResult[relationshipField]).toBeUndefined();
+  });
+
+  it('should reject nested delete payloads when a discriminator-gated relationship is inactive for the parent', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const membershipsResourceType = 'projectMemberships' as ResourceType;
+
+    const gatedRelationship = createResourcesRelationship(
+      projectsResourceType,
+      membershipsResourceType,
+      ResourceRelationshipCardinality.ONE,
+      ResourceRelationshipCardinality.MANY,
+      {
+        nature: RelationshipNature.COMPOSITION,
+        foreignKeyField: 'projectId',
+        childOperations: {
+          nested: {
+            onUpdate: {
+              allowDelete: true,
+            },
+          },
+        },
+        discriminator: {
+          discriminatorField: 'projectType',
+          values: ['INTERNAL'],
+        },
+      }
+    );
+
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+      projectType: z.string(),
+    });
+    const membershipSchema = z.object({
+      _id: z.string(),
+      role: z.string(),
+      projectId: z.string(),
+    });
+
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, [gatedRelationship]),
+      [CoreResourceOperation.UPDATE]
+    );
+
+    const membershipConfig = buildTestResourceConfig(
+      membershipsResourceType,
+      'projectMembershipId',
+      membershipSchema,
+      processResourceRelationships(membershipsResourceType, [gatedRelationship]),
+      [CoreResourceOperation.DELETE]
+    );
+
+    const deleteSpy = vi.fn();
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+        [membershipsResourceType]: membershipConfig,
+      },
+      {
+        servicesRegistry: {
+          create: vi.fn(),
+          update: vi.fn(),
+          delete: deleteSpy,
+          list: vi.fn(),
+          getService: vi.fn(),
+        },
+      }
+    );
+
+    const parentResult = {
+      _id: 'project-1',
+      name: 'Customer rollout',
+      projectType: 'EXTERNAL',
+    };
+    const relationshipField = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(
+      gatedRelationship,
+      projectsResourceType,
+      {
+        [projectsResourceType]: 'projectId',
+        [membershipsResourceType]: 'projectMembershipId',
+      }
+    ).objectFieldName;
+    const activeRelationships = (service as any).filterRelationshipsByParent(
+      [gatedRelationship],
+      parentResult
+    );
+
+    expect(activeRelationships).toEqual([]);
+
+    await expect(
+      (service as any).processNestedOperations(
+        CoreResourceOperation.UPDATE,
+        parentResult,
+        {},
+        {
+          [relationshipField]: ['membership-1'],
+        },
+        activeRelationships,
+        {} as any,
+        undefined
+      )
+    ).rejects.toMatchObject({
+      context: expect.objectContaining({
+        reason:
+          'nested delete field is not active for the current parent state or does not map to an allowed relationship',
+      }),
+    });
+
+    expect(deleteSpy).not.toHaveBeenCalled();
+  });
+
+  it('should route non-string delete selectors through DELETE_MANY semantics', async () => {
+    const projectsResourceType = 'projects' as ResourceType;
+    const projectSchema = z.object({
+      _id: z.string(),
+      name: z.string(),
+    });
+    const projectConfig = buildTestResourceConfig(
+      projectsResourceType,
+      'projectId',
+      projectSchema,
+      processResourceRelationships(projectsResourceType, []),
+      [CoreResourceOperation.DELETE, CoreResourceOperation.DELETE_MANY]
+    );
+
+    const { service } = createServiceHarness(
+      projectsResourceType,
+      {
+        [projectsResourceType]: projectConfig,
+      }
+    );
+    (service as any).fileFieldDetection = { hasFileFields: vi.fn().mockReturnValue(false) };
+
+    const deleteManySpy = vi
+      .spyOn(service as any, 'deleteMany')
+      .mockResolvedValue(['project-1']);
+
+    const deleteOperation = projectConfig.operations.find(
+      (candidate) => candidate.operationIdentifier === CoreResourceOperation.DELETE
+    )!;
+
+    const result = await (service as any).delete(
+      deleteOperation,
+      {} as any,
+      { archived: true },
+      undefined
+    );
+
+    expect(deleteManySpy).toHaveBeenCalledTimes(1);
+    expect(result).toEqual(['project-1']);
+  });
+});