@wildo-ai/saas-backend-lib 1.0.1

package/src/files/services/file-operation-handler.backend.service.ts

@@ -0,0 +1,861 @@
+/**
+ * File Operation Handler Backend Service
+ *
+ * Handles file field operations during resource CRUD operations.
+ * Validates and processes file fields when resources are created, updated, or deleted.
+ *
+ * Features:
+ * - File validation before resource creation/update
+ * - File linking/unlinking during resource operations
+ * - Cascade behavior on resource deletion
+ * - Idempotent operations (safe to retry)
+ */
+
+import { injectable, inject } from 'inversify';
+import { ResourceType, ErrorType, ErrorCustomMessageReference, FileStatus } from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { FileFieldDetectionBackendService, FileFieldMetadata } from './file-field-detection.backend.service';
+import { FilesBackendService } from './files.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { RepositoryOptions } from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';
+import { File } from '@wildo-ai/saas-models';
+import { validateFileId, validateResourceType, validateResourceId, validateFieldName } from '~wildo-backend-lib/files/utils/file-validation.utils';
+import {
+  enumerateFileFieldValueOccurrences,
+  mergeEffectiveResourceState,
+  type FileFieldValueOccurrence,
+} from '~wildo-backend-lib/files/utils/file-field-schema-path.backend.utils';
+
+@injectable()
+export class FileOperationHandlerBackendService {
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger)
+    private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)
+    private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)
+    private readonly fileFieldDetection: FileFieldDetectionBackendService,
+    @inject(SAAS_SERVICE_TYPES.FilesBackendService)
+    private readonly filesService: FilesBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('FileOperationHandlerBackendService');
+    this.logger.setDebugTypeLogging('FileOperationHandlerBackendService', false);
+  }
+
+  /**
+   * Validate file fields before resource creation.
+   * Ensures files exist, are in UPLOADED status, and are ready to be linked.
+   *
+   * @param data - Resource data being created
+   * @param resourceType - Resource type
+   * @param executionContext - Execution context
+   * @param options - Repository options (for transaction support)
+   * @throws Error if validation fails (fail fast before resource creation)
+   */
+  async validateFileFieldsForCreate(
+    data: Record<string, any>,
+    resourceType: ResourceType,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Validate inputs (CRITICAL: Prevents invalid data propagation)
+    validateResourceType(resourceType, this.errorBuilder, executionContext, 'resourceType');
+
+    // Check if resource has file fields
+    if (!this.fileFieldDetection.hasFileFields(resourceType)) {
+      return;
+    }
+
+    const fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+
+    this.logDebug('Validating file fields for CREATE', {
+      resourceType,
+      fileFieldsCount: fileFields.length,
+    });
+
+    // Collect all fileIds to validate
+    const fileIdsToValidate: string[] = [];
+
+    for (const fileField of fileFields) {
+      const occurrences = enumerateFileFieldValueOccurrences(data, fileField.fieldName);
+
+      for (const occurrence of occurrences) {
+        const fieldFileIds = this.extractFileIds(occurrence.value, executionContext, true);
+
+        // F4-01: Enforce maxFiles constraint per concrete occurrence
+        const { maxFiles, multiple } = fileField.fileMetadata;
+        if (multiple && maxFiles !== undefined && fieldFileIds.length > maxFiles) {
+          throw this.errorBuilder.buildError(
+            ErrorType.BUSINESS_RULE,
+            executionContext,
+            {
+              customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+              context: {
+                message: `Too many files for field "${fileField.fieldName}". Maximum: ${maxFiles}, received: ${fieldFileIds.length}`,
+                fieldName: fileField.fieldName,
+                runtimeFieldPath: occurrence.runtimeFieldPath,
+                resourceType,
+                maxFiles,
+                receivedCount: fieldFileIds.length,
+              },
+            }
+          );
+        }
+
+        fileIdsToValidate.push(...fieldFileIds);
+      }
+    }
+
+    // Validate each file
+    for (const fileId of fileIdsToValidate) {
+      // Validate fileId format (CRITICAL: Prevents query injection and database errors)
+      validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+      const file = await this.filesService.getFile(fileId, executionContext, options);
+
+      if (!file) {
+        throw this.errorBuilder.buildError(
+          ErrorType.NOT_FOUND,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+            context: {
+              message: 'File not found for resource creation',
+              fileId,
+              resourceType,
+            },
+          }
+        );
+      }
+
+      // Verify file is in UPLOADED status (ready to be linked)
+      if (file.status !== FileStatus.UPLOADED) {
+        throw this.errorBuilder.buildError(
+          ErrorType.BUSINESS_RULE,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+            context: {
+              message: 'File must be in UPLOADED status before linking to resource',
+              fileId,
+              fileStatus: file.status,
+              resourceType,
+              expectedStatus: FileStatus.UPLOADED,
+            },
+          }
+        );
+      }
+
+      // Note: uploadContext validation can be added in Phase 2 if needed
+      // For now, we only validate that file is UPLOADED
+    }
+
+    this.logDebug('File fields validation for CREATE completed', {
+      resourceType,
+      validatedFilesCount: fileIdsToValidate.length,
+    });
+  }
+
+  /**
+   * Process file fields after resource creation.
+   * Links files to the newly created resource.
+   *
+   * @param data - Resource data that was created
+   * @param resourceType - Resource type
+   * @param resourceId - ID of the created resource
+   * @param executionContext - Execution context
+   */
+  async processFileFieldsForCreate(
+    data: Record<string, any>,
+    resourceType: ResourceType,
+    resourceId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Validate inputs (CRITICAL: Prevents invalid data propagation)
+    validateResourceType(resourceType, this.errorBuilder, executionContext, 'resourceType');
+    validateResourceId(resourceId, this.errorBuilder, executionContext, 'resourceId');
+
+    // Check if resource has file fields
+    if (!this.fileFieldDetection.hasFileFields(resourceType)) {
+      return;
+    }
+
+    const fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+
+    this.logDebug('Processing file fields for CREATE', {
+      resourceType,
+      resourceId,
+      fileFieldsCount: fileFields.length,
+    });
+
+    // Process each file field
+    for (const fileField of fileFields) {
+      const occurrences = enumerateFileFieldValueOccurrences(data, fileField.fieldName);
+
+      for (const occurrence of occurrences) {
+        const fieldFileIds = this.extractFileIds(occurrence.value, executionContext, true);
+        for (const fileId of fieldFileIds) {
+          await this.linkFileToResource(
+            fileId,
+            resourceType,
+            resourceId,
+            fileField.fieldName,
+            executionContext,
+            options
+          );
+        }
+      }
+    }
+
+    this.logDebug('File fields processing for CREATE completed', {
+      resourceType,
+      resourceId,
+    });
+  }
+
+  /**
+   * Process file fields after resource update.
+   * Unlinks old files and links new files.
+   * Validates new files BEFORE unlinking old ones (fail fast).
+   *
+   * Note: This method handles partial updates correctly. If a file field is not present
+   * in `data`, it is treated as unchanged (not removed). Only explicit changes to file
+   * field values trigger unlinking/linking operations.
+   *
+   * @param data - Updated resource data (may be partial update - only changed fields)
+   * @param existingResource - Existing resource before update (complete state)
+   * @param resourceType - Resource type
+   * @param resourceId - Resource ID
+   * @param executionContext - Execution context
+   */
+  async processFileFieldsForUpdate(
+    data: Record<string, any>,
+    existingResource: Record<string, any>,
+    resourceType: ResourceType,
+    resourceId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Validate inputs (CRITICAL: Prevents invalid data propagation)
+    validateResourceType(resourceType, this.errorBuilder, executionContext, 'resourceType');
+    validateResourceId(resourceId, this.errorBuilder, executionContext, 'resourceId');
+
+    // Check if resource has file fields
+    if (!this.fileFieldDetection.hasFileFields(resourceType)) {
+      return;
+    }
+
+    const fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+    const effectiveNewResource = mergeEffectiveResourceState(existingResource, data) as Record<string, any>;
+
+    this.logDebug('Processing file fields for UPDATE', {
+      resourceType,
+      resourceId,
+      fileFieldsCount: fileFields.length,
+    });
+
+    // Process each file field
+    for (const fileField of fileFields) {
+      const oldOccurrences = this.prepareOccurrences(
+        enumerateFileFieldValueOccurrences(existingResource, fileField.fieldName),
+        executionContext,
+        false,
+      );
+      const newOccurrences = this.prepareOccurrences(
+        enumerateFileFieldValueOccurrences(effectiveNewResource, fileField.fieldName),
+        executionContext,
+        true,
+      );
+
+      const occurrencePairs = this.matchOccurrences(oldOccurrences, newOccurrences);
+      if (occurrencePairs.requiresAmbiguousFallback && fileField.fileMetadata.overridable === false) {
+        throw this.errorBuilder.buildError(
+          ErrorType.BUSINESS_RULE,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+            context: {
+              message: `Nested file field "${fileField.fieldName}" cannot be updated safely because multiple identity-less array items changed at once.`,
+              fieldName: fileField.fieldName,
+              resourceType,
+              resourceId,
+            },
+          }
+        );
+      }
+
+      for (const pair of occurrencePairs.pairs) {
+        const oldFileIds = pair.oldOccurrence?.fileIds ?? [];
+        const newFileIds = pair.newOccurrence?.fileIds ?? [];
+        const oldSet = new Set(oldFileIds);
+        const newSet = new Set(newFileIds);
+        const hasChanged =
+          oldSet.size !== newSet.size ||
+          !oldFileIds.every(id => newSet.has(id)) ||
+          !newFileIds.every(id => oldSet.has(id));
+
+        if (!hasChanged) {
+          continue;
+        }
+
+        const runtimeFieldPath = pair.newOccurrence?.occurrence.runtimeFieldPath
+          ?? pair.oldOccurrence?.occurrence.runtimeFieldPath;
+
+        // F4-02: Enforce overridable constraint
+        const { overridable, multiple, maxFiles } = fileField.fileMetadata;
+        if (overridable === false) {
+          const removedFileIds = oldFileIds.filter(id => !newSet.has(id));
+
+          if (!multiple) {
+            if (removedFileIds.length > 0) {
+              throw this.errorBuilder.buildError(
+                ErrorType.BUSINESS_RULE,
+                executionContext,
+                {
+                  customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+                  context: {
+                    message: `File field "${fileField.fieldName}" is not overridable. Cannot replace or remove the existing file.`,
+                    fieldName: fileField.fieldName,
+                    runtimeFieldPath,
+                    resourceType,
+                    resourceId,
+                  },
+                }
+              );
+            }
+          } else if (removedFileIds.length > 0) {
+            throw this.errorBuilder.buildError(
+              ErrorType.BUSINESS_RULE,
+              executionContext,
+              {
+                customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+                context: {
+                  message: `File field "${fileField.fieldName}" is not overridable. Cannot remove existing files, only add new ones.`,
+                  fieldName: fileField.fieldName,
+                  runtimeFieldPath,
+                  resourceType,
+                  resourceId,
+                  removedFileIds,
+                },
+              }
+            );
+          }
+        }
+
+        if (multiple && maxFiles !== undefined && newFileIds.length > maxFiles) {
+          throw this.errorBuilder.buildError(
+            ErrorType.BUSINESS_RULE,
+            executionContext,
+            {
+              customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+              context: {
+                message: `Too many files for field "${fileField.fieldName}". Maximum: ${maxFiles}, new total: ${newFileIds.length}`,
+                fieldName: fileField.fieldName,
+                runtimeFieldPath,
+                resourceType,
+                resourceId,
+                maxFiles,
+                newTotal: newFileIds.length,
+              },
+            }
+          );
+        }
+
+        for (const fileId of newFileIds) {
+          if (!oldSet.has(fileId)) {
+          // New file - validate fileId format (CRITICAL: Prevents query injection and database errors)
+            validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+            const file = await this.filesService.getFile(fileId, executionContext, options);
+
+            if (!file) {
+              throw this.errorBuilder.buildError(
+                ErrorType.NOT_FOUND,
+                executionContext,
+                {
+                  customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+                  context: {
+                    message: 'File not found for resource update',
+                    fileId,
+                    resourceType,
+                    resourceId,
+                    runtimeFieldPath,
+                  },
+                }
+              );
+            }
+
+            if (file.status !== FileStatus.UPLOADED) {
+              throw this.errorBuilder.buildError(
+                ErrorType.BUSINESS_RULE,
+                executionContext,
+                {
+                  customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+                  context: {
+                    message: 'File must be in UPLOADED status before linking to resource',
+                    fileId,
+                    fileStatus: file.status,
+                    runtimeFieldPath,
+                    resourceType,
+                    resourceId,
+                    expectedStatus: FileStatus.UPLOADED,
+                  },
+                }
+              );
+            }
+          }
+        }
+
+        for (const oldFileId of oldFileIds) {
+          if (!newSet.has(oldFileId)) {
+          // File removed - unlink it
+            await this.unlinkFileFromResource(
+              oldFileId,
+              fileField.fieldName,
+              executionContext,
+              options
+            );
+          }
+        }
+
+        for (const newFileId of newFileIds) {
+          if (!oldSet.has(newFileId)) {
+          // New file - link it
+            await this.linkFileToResource(
+              newFileId,
+              resourceType,
+              resourceId,
+              fileField.fieldName,
+              executionContext,
+              options
+            );
+          }
+        }
+      }
+    }
+
+    this.logDebug('File fields processing for UPDATE completed', {
+      resourceType,
+      resourceId,
+    });
+  }
+
+  /**
+   * Process file fields before resource deletion.
+   * Applies onParentDelete behavior to all linked files.
+   *
+   * @param resourceType - Resource type being deleted
+   * @param resourceId - Resource ID being deleted
+   * @param executionContext - Execution context
+   */
+  async processFileFieldsForDelete(
+    resourceType: ResourceType,
+    resourceId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Check if resource has file fields
+    if (!this.fileFieldDetection.hasFileFields(resourceType)) {
+      return;
+    }
+
+    const fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+
+    this.logDebug('Processing file fields for DELETE', {
+      resourceType,
+      resourceId,
+      fileFieldsCount: fileFields.length,
+    });
+
+    // Get all files linked to this resource
+    const linkedFiles = await this.filesService.listFilesForResource(
+      resourceType,
+      resourceId,
+      undefined, // fieldName - undefined means all fields
+      executionContext,
+      options
+    );
+
+    // Process each file based on onParentDelete behavior from field metadata
+    for (const file of linkedFiles) {
+      if (!file.linkedFieldName) {
+        this.logger.warn('Linked file missing linkedFieldName during parent delete; defaulting to cascade cleanup', {
+          fileId: file.fileId,
+          resourceType,
+          resourceId,
+        });
+        await this.applyOnParentDeleteBehavior(
+          file.fileId,
+          'cascade',
+          executionContext,
+          options
+        );
+        continue;
+      }
+
+      const fileField = this.fileFieldDetection.getFileFieldMetadata(
+        resourceType,
+        file.linkedFieldName
+      );
+
+      if (!fileField) {
+        // Field not found - use default cascade behavior
+        await this.applyOnParentDeleteBehavior(
+          file.fileId,
+          'cascade',
+          executionContext,
+          options
+        );
+        continue;
+      }
+
+      const onParentDelete = fileField.fileMetadata.onParentDelete || 'cascade';
+
+      await this.applyOnParentDeleteBehavior(
+        file.fileId,
+        onParentDelete,
+        executionContext,
+        options
+      );
+    }
+
+    this.logDebug('File fields processing for DELETE completed', {
+      resourceType,
+      resourceId,
+      processedFilesCount: linkedFiles.length,
+    });
+  }
+
+  /**
+   * Extract file IDs from field value (handles single file or array).
+   *
+   * @param fieldValue - The raw field value from the resource object
+   * @param executionContext - Current execution context
+   * @param strict - When true (user input / new values), throws on invalid fileIds.
+   *                 When false (existing DB data), silently filters and logs warnings.
+   */
+  private extractFileIds(fieldValue: any, executionContext?: ExecutionContext<any>, strict: boolean = false): string[] {
+    if (fieldValue === null || fieldValue === undefined) {
+      return [];
+    }
+
+    if (typeof fieldValue === 'object' && !Array.isArray(fieldValue)) {
+      if ('fileId' in fieldValue) {
+        return this.extractFileIds((fieldValue as { fileId?: unknown }).fileId, executionContext, strict);
+      }
+
+      if ('fileIds' in fieldValue) {
+        return this.extractFileIds((fieldValue as { fileIds?: unknown }).fileIds, executionContext, strict);
+      }
+    }
+
+    if (Array.isArray(fieldValue)) {
+      const validFileIds: string[] = [];
+      for (const fileId of fieldValue) {
+        if (typeof fileId !== 'string' || fileId.trim() === '') {
+          if (strict) {
+            throw this.errorBuilder.buildError(
+              ErrorType.VALIDATION,
+              executionContext,
+              {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                  message: `Invalid fileId value: expected a non-empty string, received ${typeof fileId}`,
+                  fileId,
+                },
+              }
+            );
+          }
+          continue;
+        }
+        try {
+          validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+          validFileIds.push(fileId);
+        } catch (error) {
+          if (strict) {
+            throw error; // Re-throw in strict mode — user provided invalid input
+          }
+          // Tolerant mode: filter out and warn (handles corrupt DB data gracefully)
+          this.logger.warn('Invalid fileId filtered out during extraction', {
+            fileId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+      return validFileIds;
+    }
+
+    if (typeof fieldValue === 'string' && fieldValue.trim() !== '') {
+      try {
+        validateFileId(fieldValue, this.errorBuilder, executionContext, 'fileId');
+        return [fieldValue];
+      } catch (error) {
+        if (strict) {
+          throw error;
+        }
+        this.logger.warn('Invalid fileId filtered out during extraction', {
+          fileId: fieldValue,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+      }
+    }
+
+    if (strict && fieldValue !== null && fieldValue !== undefined) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            message: `Invalid file field value: expected string, array, null, or undefined, received ${typeof fieldValue}`,
+          },
+        }
+      );
+    }
+
+    return [];
+  }
+
+  /**
+   * Link a file to a resource.
+   * Handles race conditions (idempotent - safe to call multiple times).
+   */
+  private async linkFileToResource(
+    fileId: string,
+    resourceType: ResourceType,
+    resourceId: string,
+    fieldName: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Validate inputs (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+    validateResourceType(resourceType, this.errorBuilder, executionContext, 'resourceType');
+    validateResourceId(resourceId, this.errorBuilder, executionContext, 'resourceId');
+    validateFieldName(fieldName, this.errorBuilder, executionContext, 'fieldName');
+
+    // Check if file is already linked to the same resource (idempotent check - before calling service)
+    // This prevents unnecessary service calls and handles idempotent cases early
+    const file = await this.filesService.getFile(fileId, executionContext, options);
+    if (file &&
+        file.status === FileStatus.LINKED &&
+        file.linkedResourceType === resourceType &&
+        file.linkedResourceId === resourceId &&
+        file.linkedFieldName === fieldName) {
+      // Already linked to same resource - skip (idempotent)
+      this.logDebug('File already linked to same resource, skipping', {
+        fileId,
+        resourceType,
+        resourceId,
+        fieldName,
+      });
+      return;
+    }
+
+    // Link file - errors propagate to fail the transaction (Decision 2.2: Option A)
+    // FilesBackendService.linkFileToResource() handles idempotent cases internally (returns existing file)
+    // All other errors (NOT_FOUND, BUSINESS_RULE, INTERNAL) should fail the operation
+    await this.filesService.linkFileToResource(
+      fileId,
+      resourceType,
+      resourceId,
+      fieldName,
+      executionContext,
+      options
+    );
+  }
+
+  /**
+   * Unlink a file from a resource.
+   * Applies onParentDelete behavior.
+   */
+  private async unlinkFileFromResource(
+    fileId: string,
+    fieldName: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    // Validate fileId format (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+    const file = await this.filesService.getFile(fileId, executionContext, options);
+    if (!file || file.status !== FileStatus.LINKED) {
+      // Already unlinked or doesn't exist - skip (idempotent)
+      return;
+    }
+
+    // Unlink file (sets status to ORPHANED)
+    await this.filesService.unlinkFileFromResource(fileId, executionContext, options);
+  }
+
+  /**
+   * Apply onParentDelete behavior to a file.
+   *
+   * @param fileId - File ID
+   * @param behavior - Behavior: 'cascade', 'soft-delete', or 'orphan'
+   * @param executionContext - Execution context
+   */
+  private async applyOnParentDeleteBehavior(
+    fileId: string,
+    behavior: 'cascade' | 'soft-delete' | 'orphan',
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<void> {
+    this.logDebug('Applying onParentDelete behavior', {
+      fileId,
+      behavior,
+    });
+
+    switch (behavior) {
+      case 'cascade':
+        // Cascade now marks the file as DELETED only. Physical storage cleanup is
+        // intentionally deferred to the cleanup batch so resource deletes never
+        // mix Mongo rollback with non-transactional storage side effects.
+        await this.filesService.deleteFile(fileId, executionContext, options);
+        break;
+
+      case 'soft-delete':
+        // Soft delete: update status to DELETED
+        await this.filesService.deleteFile(fileId, executionContext, options);
+        break;
+
+      case 'orphan':
+        // Unlink: clear parent fields, set status to ORPHANED
+        await this.filesService.unlinkFileFromResource(fileId, executionContext, options);
+        break;
+
+      default:
+        // Default to cascade
+        await this.filesService.deleteFile(fileId, executionContext, options);
+    }
+  }
+
+  private prepareOccurrences(
+    occurrences: FileFieldValueOccurrence[],
+    executionContext: ExecutionContext<any>,
+    strict: boolean,
+  ): Array<{
+    occurrence: FileFieldValueOccurrence;
+    fileIds: string[];
+    signature: string;
+  }> {
+    return occurrences.map((occurrence) => {
+      const fileIds = this.extractFileIds(occurrence.value, executionContext, strict);
+      return {
+        occurrence,
+        fileIds,
+        signature: JSON.stringify([...fileIds].sort()),
+      };
+    });
+  }
+
+  private matchOccurrences(
+    oldOccurrences: Array<{
+      occurrence: FileFieldValueOccurrence;
+      fileIds: string[];
+      signature: string;
+    }>,
+    newOccurrences: Array<{
+      occurrence: FileFieldValueOccurrence;
+      fileIds: string[];
+      signature: string;
+    }>,
+  ): {
+    pairs: Array<{
+      oldOccurrence?: {
+        occurrence: FileFieldValueOccurrence;
+        fileIds: string[];
+        signature: string;
+      };
+      newOccurrence?: {
+        occurrence: FileFieldValueOccurrence;
+        fileIds: string[];
+        signature: string;
+      };
+    }>;
+    requiresAmbiguousFallback: boolean;
+  } {
+    const pairs: Array<{
+      oldOccurrence?: {
+        occurrence: FileFieldValueOccurrence;
+        fileIds: string[];
+        signature: string;
+      };
+      newOccurrence?: {
+        occurrence: FileFieldValueOccurrence;
+        fileIds: string[];
+        signature: string;
+      };
+    }> = [];
+
+    const remainingOld = [...oldOccurrences];
+    const remainingNew = [...newOccurrences];
+
+    const stableIds = new Set(
+      [...remainingOld, ...remainingNew]
+        .map((entry) => entry.occurrence.ownerStableId)
+        .filter((value): value is string => typeof value === 'string' && value.trim() !== ''),
+    );
+
+    for (const stableId of stableIds) {
+      const oldMatches = remainingOld.filter((entry) => entry.occurrence.ownerStableId === stableId);
+      const newMatches = remainingNew.filter((entry) => entry.occurrence.ownerStableId === stableId);
+
+      while (oldMatches.length > 0 && newMatches.length > 0) {
+        const oldEntry = oldMatches.shift()!;
+        const newEntry = newMatches.shift()!;
+        remainingOld.splice(remainingOld.indexOf(oldEntry), 1);
+        remainingNew.splice(remainingNew.indexOf(newEntry), 1);
+        pairs.push({ oldOccurrence: oldEntry, newOccurrence: newEntry });
+      }
+    }
+
+    const oldSignatureBuckets = new Map<string, typeof remainingOld>();
+    for (const entry of remainingOld) {
+      if (entry.occurrence.ownerStableId) {
+        continue;
+      }
+      const bucket = oldSignatureBuckets.get(entry.signature) ?? [];
+      bucket.push(entry);
+      oldSignatureBuckets.set(entry.signature, bucket);
+    }
+
+    for (const newEntry of [...remainingNew]) {
+      if (newEntry.occurrence.ownerStableId) {
+        continue;
+      }
+
+      const bucket = oldSignatureBuckets.get(newEntry.signature);
+      const oldEntry = bucket?.shift();
+      if (!oldEntry) {
+        continue;
+      }
+
+      remainingOld.splice(remainingOld.indexOf(oldEntry), 1);
+      remainingNew.splice(remainingNew.indexOf(newEntry), 1);
+      pairs.push({ oldOccurrence: oldEntry, newOccurrence: newEntry });
+    }
+
+    const requiresAmbiguousFallback =
+      remainingOld.some((entry) => !entry.occurrence.ownerStableId) &&
+      remainingNew.some((entry) => !entry.occurrence.ownerStableId);
+
+    while (remainingOld.length > 0 || remainingNew.length > 0) {
+      pairs.push({
+        oldOccurrence: remainingOld.shift(),
+        newOccurrence: remainingNew.shift(),
+      });
+    }
+
+    return {
+      pairs,
+      requiresAmbiguousFallback,
+    };
+  }
+}