// SPDX-FileCopyrightText: 2026 FocusFlow contributors
// SPDX-License-Identifier: AGPL-3.0-only

/// Implements Document Mapping behavior for the Scheduler Core package.
library;

// Adapter-neutral V1 document mapping helpers.
//
// These helpers use plain Dart map shapes only. They do not import database
// APIs, create clients, or perform database I/O.

import '../application/application_layer.dart';
import '../scheduling/backlog.dart';
import '../domain/locked_time.dart';
import '../domain/models.dart';
import 'persistence_contract.dart';
import '../domain/project_statistics.dart';
import 'repositories.dart';
import '../scheduling/scheduling_engine.dart';
import '../scheduling/task_lifecycle.dart';
import '../domain/task_statistics.dart';
import '../domain/time_contracts.dart';
part 'document_mapping/failures/document_mapping_failure_code.dart';
part 'document_mapping/failures/document_mapping_exception.dart';
part 'document_mapping/metadata/document_metadata.dart';
part 'document_mapping/enums/persistence_enum_mapping.dart';
part 'document_mapping/tasks/task_document_mapping.dart';
part 'document_mapping/tasks/task_statistics_document_mapping.dart';
part 'document_mapping/projects/project_document_mapping.dart';
part 'document_mapping/projects/project_statistics_document_mapping.dart';
part 'document_mapping/locked_time/locked_block_recurrence_document_mapping.dart';
part 'document_mapping/locked_time/locked_block_document_mapping.dart';
part 'document_mapping/locked_time/locked_block_override_document_mapping.dart';
part 'document_mapping/tasks/task_activity_document_mapping.dart';
part 'document_mapping/application/owner_settings_document_mapping.dart';
part 'document_mapping/application/backlog_staleness_document_mapping.dart';
part 'document_mapping/application/notice_acknowledgement_document_mapping.dart';
part 'document_mapping/application/application_operation_document_mapping.dart';
part 'document_mapping/scheduling/scheduling_snapshot_document_mapping.dart';
part 'document_mapping/scheduling/scheduling_window_document_mapping.dart';
part 'document_mapping/time/time_interval_document_mapping.dart';
part 'document_mapping/scheduling/scheduling_notice_document_mapping.dart';
part 'document_mapping/scheduling/scheduling_change_document_mapping.dart';
part 'document_mapping/scheduling/scheduling_overlap_document_mapping.dart';
part 'document_mapping/tasks/task_document_extension.dart';
part 'document_mapping/tasks/task_statistics_document_extension.dart';
part 'document_mapping/projects/project_statistics_document_extension.dart';

/// Adds focused helper behavior through `on`.
/// The extension keeps conversion or convenience logic near the type it supports while avoiding changes to the original model surface.
extension on Task {
  /// Converts scheduler data for `_validateTaskDocumentMetadata` without changing the source object.
  /// Conversion helpers keep persistence and export shapes explicit so domain models do not depend on storage-specific details.
  void _validateTaskDocumentMetadata(Map<String, Object?> document) {
    _requiredNullableDateTime(document, TaskDocumentFields.backlogEnteredAt);
    _requiredNullableString(
      document,
      TaskDocumentFields.backlogEnteredAtProvenance,
    );
  }
}

/// Adds focused helper behavior through `on`.
/// The extension keeps conversion or convenience logic near the type it supports while avoiding changes to the original model surface.
extension on ProjectStatistics {
  /// Converts scheduler data for `_validateProjectStatisticsDocumentMetadata` without changing the source object.
  /// Conversion helpers keep persistence and export shapes explicit so domain models do not depend on storage-specific details.
  void _validateProjectStatisticsDocumentMetadata(
    Map<String, Object?> document,
  ) {
    for (final value in _requiredList(
      document,
      ProjectStatisticsDocumentFields.appliedActivityIds,
    )) {
      if (value is! String) {
        throw const DocumentMappingException(
          code: DocumentMappingFailureCode.wrongType,
          fieldName: ProjectStatisticsDocumentFields.appliedActivityIds,
        );
      }
    }
  }
}

/// Adds focused helper behavior through `on`.
/// The extension keeps conversion or convenience logic near the type it supports while avoiding changes to the original model surface.
extension on SchedulingStateSnapshot {
  /// Converts scheduler data for `_validateSchedulingSnapshotDocumentMetadata` without changing the source object.
  /// Conversion helpers keep persistence and export shapes explicit so domain models do not depend on storage-specific details.
  void _validateSchedulingSnapshotDocumentMetadata(
    Map<String, Object?> document,
  ) {
    _requiredNullableCivilDate(
      document,
      SchedulingSnapshotDocumentFields.sourceDate,
    );
    _requiredNullableCivilDate(
      document,
      SchedulingSnapshotDocumentFields.targetDate,
    );
    _requiredNullableDateTime(
      document,
      SchedulingSnapshotDocumentFields.retentionExpiresAt,
    );
    _requiredBool(document, SchedulingSnapshotDocumentFields.truncated);
  }
}
