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

part of '../../persistence_contract.dart';

/// Guard result for bounded document payload checks.
class PersistenceGuardResult {
  /// Creates a `PersistenceGuardResult._` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  const PersistenceGuardResult._({
    required this.isValid,
    this.fieldName,
    this.limit,
    this.actual,
  });

  /// Creates a `PersistenceGuardResult.valid` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  factory PersistenceGuardResult.valid() {
    return const PersistenceGuardResult._(isValid: true);
  }

  /// Creates a `PersistenceGuardResult.tooLarge` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  factory PersistenceGuardResult.tooLarge({
    required String fieldName,
    required int limit,
    required int actual,
  }) {
    return PersistenceGuardResult._(
      isValid: false,
      fieldName: fieldName,
      limit: limit,
      actual: actual,
    );
  }

  /// Stores the `isValid` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final bool isValid;

  /// Stores the `fieldName` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final String? fieldName;

  /// Stores the `limit` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final int? limit;

  /// Stores the `actual` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final int? actual;
}
